From f7b990bd5c711a29c560cd567c91e50c5cb7f310 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 12 Jul 2026 22:09:53 +0800
Subject: [PATCH 01/74] docs(rfc): propose the scoped-layers store

---
 docs/rfc/INDEX.md                             |   1 +
 .../2026-07-12-scoped-layers-store.i18n.yaml  |   6 +
 .../2026-07-12-scoped-layers-store.md         | 139 ++++++++++++++++++
 .../2026-07-12-scoped-layers-store.zh.md      | 139 ++++++++++++++++++
 4 files changed, 285 insertions(+)
 create mode 100644 docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml
 create mode 100644 docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md
 create mode 100644 docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md

diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md
index 5e508344fa..9596aecd78 100644
--- a/docs/rfc/INDEX.md
+++ b/docs/rfc/INDEX.md
@@ -24,6 +24,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 |---|---|
 | [Runtime schemas for the event vocabulary (Zod vs the merge-extensible-map pattern)](proposed/architecture/2026-06-16-typed-event-schemas.md) | 2026-06-16 |
 | [Extract a generic long-running tool runtime](proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md) | 2026-06-20 |
+| [Scoped-layers store — one aggregate layer per scope behind a scheduling helper](proposed/architecture/2026-07-12-scoped-layers-store.md) | 2026-07-12 |
 
 ### Process
 
diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml
new file mode 100644
index 0000000000..f868cfc669
--- /dev/null
+++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-12-scoped-layers-store.md: 0673d6c63291a66c84e91f2eff8eca26798b931f
+2026-07-12-scoped-layers-store.zh.md: 6460802f3cf3163f6be2ad51f2f82319a04288bc
diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md
new file mode 100644
index 0000000000..0673d6c632
--- /dev/null
+++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md
@@ -0,0 +1,139 @@
+# RFC: Scoped-layers store — one aggregate layer per scope behind a scheduling helper
+
+Status: proposed
+
+English | [中文](2026-07-12-scoped-layers-store.zh.md)
+
+## Problem
+
+Agent scoping ([the agent-scope RFC](../../implemented/architecture/2026-07-08-agent-scope-contexts.md), [runtime design](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)) made "a registry with a global layer plus per-agent layers" a recurring shape, and every occurrence is hand-written. Seven registration sites exist today — `tools.register`/`tools.restrict`/`tools.guard` in `dsh-tools` and `section`/`tools`/`variable`/`protect` in `dsh-system-prompt` — each pairing a global container with its own `Map<ScopeKey, container>` and repeating the same 10-15-line effect choreography: read the calling context's tag, get-or-create the layer, validate, mutate, yield a rollback that deletes the entry, reclaims the emptied layer, and emits the change event, then emit and return the exact cordis effect disposer.
+
+Beyond the duplication, the risk concentrates in the choreography details:
+- The rollback must be collected before the change emit (so a throwing listener unwinds the insertion instead of leaking it)
+- The returned disposer must be cordis's own function (a wrapper silently breaks nested ordered teardown)
+- Emptied scoped layers must be reclaimed (a disposed agent must not leave residue keyed by its dead `ScopeKey`)
+
+Every new consumer has to rewrite all of that correctly, and the copies have already diverged stylistically — two private `layerFor` helpers in `dsh-tools`, four inline IIFEs in `dsh-system-prompt`.
+
+Finally, one agent's contribution to one service is scattered across several maps that know nothing of each other — there is no object that means "what this scope contributes here" — and the consumer count keeps growing: guards and prompt protections landed recently, and per-agent `fs/*` policy, `llm/*` overrides, and per-agent compaction policy are all queued on the same pattern.
+
+## Proposal
+
+`dsh-scope` gains a store module (a new `store.ts` under its `src/`, peer-dependent on cordis only, key-agnostic) built around one division of labor: **business logic lives in a layer class; the helper only schedules layers**. One helper instance per service; the value in its map is the aggregate of everything one scope contributes to that service.
+
+- **`ScopedLayers<L>`** — a concrete scheduler, never subclassed. It owns the global layer plus one `Map<ScopeKey, L>`, builds layers on demand as `new layerClass(scope, this)`, reclaims a layer when `isEmpty()`, and funnels every write through `effect(ctx, action, options?)`. The single `ctx` parameter decides both the visible layer (`scopeOf(ctx)`) and the owning fiber (`ctx.effect`), so "visible to X, disposed with Y" stays unrepresentable — the same shape argument the agent-scope RFC used against explicit scope parameters. Actions may produce one undo, an iterable of undos, a promise, or an async iterable — the four shapes of cordis `Effect` — and undos may be async. The helper seals collected undos (run in LIFO), empty-layer reclamation, and the change notification into one disposer, and hands cordis that disposer **before** the notification runs: a throwing change listener therefore makes cordis execute the already-collected rollback and rethrow, exactly like the hand-written yield-before-emit today. Reads are `global`/`peek` plus three selector primitives lifting the table views across the two layers — `merge` (named entries, scoped shadows global, global position preserved, optional admit predicate), `values` (concatenation including anonymous entries, deliberately no shadowing), `keys` (the pre-restriction name universe) — and array-returning `forEach`/`filter`/`map` over all layers.
+- **`createLayer({ name: table<V>(kind) })`** — a class factory in the `defineTool` DSL tradition. The generated base class builds every declared table in its constructor, threads the scope down, receives the sibling back-reference (`protected readonly layers: ScopedLayers<this>`, injected by the helper at construction; polymorphic `this` narrows it in subclasses), and aggregates `isEmpty()` over the declared tables. `layer.<table>` is a fully typed mapped property, so a misspelled table name is a compile error; the table names `scope`, `isEmpty`, and `layers` are reserved and throw. Business subclasses add domain methods in the class body — single-layer queries, registration validations, and cross-layer *reads* through `this.layers` (writes must still go through `effect`); a fully custom layer may instead implement the one-method `ScopeLayer` interface (`isEmpty()`).
+- **`Entries<V>`** — the canned table: named entries (`insert`, same-layer duplicates throw one standardized message pair pointing at `agent.ctx`) and anonymous entries (`append`, process-unique symbol keys, O(1) undo removal) share one insertion-ordered map; read views (`keys`/`entries`/`values`) return array snapshots.
+
+`dsh-tools` migrates its three tables into one `ToolLayer` (domain methods `addRestriction` — empty-filter/read-once/reserved-name/known-names validation with the reserved list passed in as data, since it reads service state — plus `admits` and `guardReason`), and `dsh-system-prompt` its four into one `PromptLayer` (`addProtection` with the global-conflict self-check via the back-reference, plus the `shadowedSections` predicate). Every facade becomes a single `effect` call carrying per-call `label`, `silent` (guards emit no change event), or `scopedOnly` (boolean, or a string carrying the domain error message) options. `assemble` stays in the facade for three hard reasons: it has no legal receiver (the subject scope's layer may not exist, and reads never create layers), shadowing forces merge-before-evaluate (per-layer rendering would evaluate shadowed providers, an observable change), and the assemble waterfall, `toolOrder`, and protection restore need service-level resources a layer must not hold.
+
+Migration is behavior-preserving with two declared exceptions: the three duplicate-name messages unify into one template (tests asserting the old wording update in the same change), and validations move relative to the effect boundary (restrict/protect checks move inside the action, the variable name regex moves to the facade), so the error *order* for multiply-invalid inputs can change while every single-fault path is unchanged. Two knowingly unobservable differences: an aggregate layer is reclaimed only when all its tables are empty, and read views are snapshots rather than live containers (visible only to a callback that registers during its own iteration).
+
+## API sketch
+
+```ts ignore-check
+interface ScopeLayer {
+  isEmpty(): boolean
+}
+
+type LayerClass<L extends ScopeLayer> = new (scope: ScopeKey | undefined, layers: ScopedLayers<L>) => L
+
+declare function table<V>(kind: string): TableSpec<V>
+declare function createLayer<S extends Record<string, TableSpec<unknown>>>(
+  spec: S,
+): LayerClass<ScopeLayer & { readonly [K in keyof S]: Entries<EntryTypeOf<S[K]>> }>
+
+type Undo = () => unknown
+type LayerAction<L> = (layer: L) =>
+  | Undo
+  | Iterable<Undo, void, void>
+  | Promise<Undo>
+  | AsyncIterable<Undo, void, void>
+
+class ScopedLayers<L extends ScopeLayer> {
+  constructor(layerClass: LayerClass<L>, options: { label: string; onChange?: () => void })
+  readonly global: L
+  peek(scope: ScopeKey | undefined): L | undefined
+  merge<T>(scope: ScopeKey | undefined, pick: (layer: L) => Entries<T>, admitGlobal?: (name: string) => boolean): Map<string, T>
+  values<T>(scope: ScopeKey | undefined, pick: (layer: L) => Entries<T>): T[]
+  keys<T>(scope: ScopeKey | undefined, pick: (layer: L) => Entries<T>): string[]
+  effect(ctx: Context, action: LayerAction<L>, options?: { label?: string; silent?: boolean; scopedOnly?: boolean | string }): () => Promise<void> | void
+  forEach(fn: (layer: L, scope: ScopeKey | undefined) => void): void
+  filter(fn: (layer: L, scope: ScopeKey | undefined) => boolean): L[]
+  map<T>(fn: (layer: L, scope: ScopeKey | undefined) => T): T[]
+}
+
+class Entries<V> {
+  constructor(kind: string, scope: ScopeKey | undefined)
+  insert(name: string, value: V): () => void
+  append(value: V): () => void
+  get(name: string): V | undefined
+  has(name: string): boolean
+  keys(): string[]
+  entries(): ReadonlyArray<readonly [string, V]>
+  values(): readonly V[]
+  isEmpty(): boolean
+}
+```
+
+What a migrated consumer looks like — the heaviest current site shrinks from 30+ lines of choreography to a declaration and one-line facades:
+
+```ts ignore-check
+class ToolLayer extends createLayer({
+  tools: table<ToolDefinition>('tool'),
+  restrictions: table<ToolRestriction>('tool restriction'),
+  guards: table<ToolGuardRegistration>('tool guard'),
+}) {
+  addRestriction(filter: ToolRestriction, reserved: readonly string[]): () => void { /* validate, snapshot, append */ }
+  admits(name: string): boolean { /* intersection over this.restrictions.values() */ }
+  guardReason(view: Readonly<ToolExecution>): string | undefined { /* first monotonic denial */ }
+}
+
+class ToolRegistry extends Service {
+  private readonly layers = new ScopedLayers(ToolLayer, {
+    label: 'tools',
+    onChange: () => this.ctx.emit('tools/change'),
+  })
+
+  register(definition: ToolDefinition): () => Promise<void> | void {
+    return this.layers.effect(this.ctx,
+      layer => layer.tools.insert(definition.name, definition),
+      { label: 'tools.register()' })
+  }
+
+  visible(scope?: ScopeKey): ToolDefinition[] {
+    return Array.from(this.layers.merge(scope, layer => layer.tools, name => this.admits(scope, name)).values())
+  }
+}
+```
+
+## Alternatives considered
+
+**Per-scope registry instances behind a parent/child delegation chain.** Instance explosion; the "deployment tools plus my tools" merged view needs a hand-built delegating registry per service; single-subscription observers (persistence, the ACP bridge) would have to discover and subscribe per instance; and a delegation chain cannot express subtraction (restrictions). A child registry would also have to reach back into a parent context, widening the exposure surface.
+
+**Explicit scope parameters on registration APIs.** Already rejected by the agent-scope RFC: omitting the parameter silently registers globally, and the shape can express visible-to-X-disposed-with-Y, which is almost always a bug.
+
+**Extracting only the data structure, leaving the choreography in services.** Removes the safe half of the duplication and keeps the dangerous half — the rollback-before-emit ordering, raw-disposer, and reclamation rules are exactly where the bugs live.
+
+**A fixed-container helper with built-in view semantics.** Pins container shapes and merge policy inside the helper; business gets no freedom, and every naming or single-value variation becomes a helper feature request.
+
+**One helper per table.** Reproduces today's scattered bookkeeping — that is the status quo being replaced, with N scope maps per service and no aggregate for an agent's contribution.
+
+**`helper.get(ctx).effect(...)` two-step registration.** Splits layer creation from lifecycle attachment; a throw between the steps strands an empty layer, and the returned handle is an extra allocation per call.
+
+**Layers holding a ctx and registering their own effects.** Turns data objects into lifecycle managers and reinstates the choreography once per business class.
+
+## Acceptance criteria
+
+- `store.ts` ships in `dsh-scope` (peer deps unchanged: cordis only; module-graph position unchanged) with per-file 100% coverage, including: layer bookkeeping and reclamation, all four action shapes, seal ordering, the throwing-change-listener rollback (the entry is rolled back and the duplicate check re-registers), failure reclamation of freshly created layers, `label`/`silent`/`scopedOnly` options, `createLayer` construction, reserved table names, back-reference typing, and `Entries` named/anonymous semantics.
+- `dsh-tools` and `dsh-system-prompt` each collapse to one `ScopedLayers`; all existing tests pass with only the declared duplicate-message assertion updates; every registration facade is a single `effect` call and keeps returning the exact cordis effect disposer.
+- Behavior matches the old baseline per the equivalence statement above: two declared exceptions (unified messages; error order for multiply-invalid inputs), two unobservable differences (aggregate reclamation timing; snapshot read views), nothing else.
+- Documentation lands in the same change: `dsh-scope`/`dsh-tools`/`dsh-system-prompt` READMEs; on implementation this RFC moves to `implemented/` and the [runtime-design RFC](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)'s registration section is updated in place.
+
+## Risks
+
+- The layer/facade boundary may not fit a future consumer's shape. Mitigation: the bare `ScopeLayer` interface remains the floor, and widening `LayerClass` to accept a factory (for layers with constructor dependencies) is a recorded non-breaking extension.
+- `createLayer`'s mapped-type factory is deliberate type gymnastics. Accepted: the `defineTool` schema DSL is the repo precedent, and the gymnastics stay inside `dsh-scope`.
+- The two equivalence exceptions can surprise tests that assert exact duplicate messages or multi-fault error order; they are declared here so review checks them rather than discovers them.
+- Snapshot read views hide entries registered by a callback during its own iteration — a pathological pattern, but a visible one; snapshots make it deterministic instead.
+- Two core registries migrate at once. Mitigated by the behavior comparison performed during design and by landing the store with equivalence-pinning tests before either migration commit.
diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md
new file mode 100644
index 0000000000..6460802f3c
--- /dev/null
+++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md
@@ -0,0 +1,139 @@
+# RFC: 作用域分层存储——每 scope 一个聚合层与统一调度 helper
+
+Status: proposed
+
+[English](2026-07-12-scoped-layers-store.md) | 中文
+
+## 问题
+
+agent 作用域落地之后（[agent-scope RFC](../../implemented/architecture/2026-07-08-agent-scope-contexts.md)、[运行时设计篇](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)），「一张全局层加若干 per-agent 层的注册表」成为反复出现的形态，而每一处都是手写的。今天已有七个登记口——`dsh-tools` 的 `tools.register`/`tools.restrict`/`tools.guard` 与 `dsh-system-prompt` 的 `section`/`tools`/`variable`/`protect`——每处都是一个全局容器配一张自己的 `Map<ScopeKey, 容器>`，并重复同一段 10-15 行的 effect 编排：读调用方上下文的标签、按需建层、校验、变更、yield 一个「删条目 → 回收空层 → 发 change 事件」的回滚，然后发事件并返回 cordis effect 的原始 disposer。
+
+除此之外：风险集中在编排细节上：
+- 回滚必须在 change 发出之前被收集（抛错的监听器才能回卷插入而不是泄漏）
+- 返回的 disposer 必须是 cordis 自己的那个函数（包装器会静默破坏嵌套的有序拆除）
+- 清空的专属层必须被回收（被 dispose 的 agent 不得留下以死 `ScopeKey` 为键的残余）
+
+每个新消费者都要把这一切重新写对一遍，而各副本的写法已经分叉——`dsh-tools` 里有两个私有 `layerFor`，`dsh-system-prompt` 里是四处内联 IIFE。
+
+最后，一个 agent 在一个服务里的贡献散落在几张互不相识的 Map 里——不存在一个「这个 scope 在这里贡献了什么」的对象——而消费者还在持续增多：guard 与提示词 protection 是最近落地的一批，per-agent 的 `fs/*` 策略、`llm/*` 覆盖、per-agent compaction 策略都排在同一个模式上。
+
+## 提案
+
+`dsh-scope` 新增 store 模块（其 `src/` 下新增 `store.ts`，peer 依赖仅 cordis，与键类型无关），核心是一条分工：**业务逻辑封在层类里，helper 只负责调度层**。一个服务一个 helper 实例；其 Map 的 value 就是「一个 scope 在该服务的全部贡献」这一聚合对象。
+
+- **`ScopedLayers<L>`**——具体的调度器，不作继承点。持有全局层与一张 `Map<ScopeKey, L>`，按需以 `new layerClass(scope, this)` 建层，层 `isEmpty()` 时回收，并把所有写入收拢到 `effect(ctx, action, options?)`。单一 `ctx` 参数同时决定可见层（`scopeOf(ctx)`）与属主 fiber（`ctx.effect`），「对 X 可见、随 Y 销毁」因此不可表达——与 agent-scope RFC 否决显式 scope 参数用的是同一个形状论证。action 可以产出单个撤销、撤销的可迭代、Promise 或异步可迭代——即 cordis `Effect` 的四种形态——且撤销允许异步。helper 把收集到的撤销（逆序执行）、空层回收与 change 通知合成**一个** disposer，并在通知运行**之前**先把它交给 cordis：因此 change 监听器抛错时，cordis 会执行已收集的回滚再重抛，与今天手写的「yield 在 emit 之前」逐字等价。读取件是 `global`/`peek`，外加把表视图提升到两层的三个 selector 原语——`merge`（命名条目，专属遮蔽全局、保留全局位置，可选放行谓词）、`values`（拼接、含匿名条目、刻意不做遮蔽）、`keys`（限制前名字全集）——以及跨全部层、返回数组的 `forEach`/`filter`/`map`。
+- **`createLayer({ 表名: table<V>(kind) })`**——`defineTool` DSL 传统的类工厂。生成的基类在构造器里建好每张声明的表、把 scope 传下去、接收同族回引（`protected readonly layers: ScopedLayers<this>`，由 helper 建层时注入；多态 `this` 型在子类中自动收窄），并对声明的表聚合 `isEmpty()`。`layer.<表名>` 是带完整类型的映射属性，写错表名是编译错误；表名 `scope`、`isEmpty`、`layers` 保留，冲突即抛。业务子类在类体里追加领域方法——单层查询、登记校验，以及经 `this.layers` 的跨层**只读**（写入仍必须走 `effect`）；完全自定义的层也可以只实现单方法接口 `ScopeLayer`（`isEmpty()`）。
+- **`Entries<V>`**——罐装条目表：命名条目（`insert`，同层重名抛一对指向 `agent.ctx` 的标准化文案）与匿名条目（`append`，进程内唯一 symbol 键、O(1) 撤销删除）共用一张保插入序的 Map；读视图（`keys`/`entries`/`values`）返回数组快照。
+
+`dsh-tools` 把三张表合并进一个 `ToolLayer`（领域方法 `addRestriction`——空过滤器/读取一次性/保留名/已知名校验，保留名单因读服务状态而以数据传入——加上 `admits` 与 `guardReason`），`dsh-system-prompt` 把四张表合并进一个 `PromptLayer`（`addProtection` 经同族回引做全局冲突自检，加上 `shadowedSections` 谓词）。每个门面都变成单次 `effect` 调用，携带 per-call 的 `label`、`silent`（guard 不发 change 事件）或 `scopedOnly`（布尔，或携带领域报错文案的字符串）选项。`assemble` 留在门面，三条硬理由：它没有合法接收者（主体 scope 的层可能不存在，而读路径绝不建层）、遮蔽语义强制先合并后求值（逐层渲染会求值被遮蔽的 provider，行为可观察地改变）、组装 waterfall、`toolOrder` 与 protection 恢复需要层不应持有的服务级资源。
+
+迁移保持行为等价，带两个声明的例外：三处重名文案统一为一个模板（断言旧文案的测试在同一变更中更新）；校验相对 effect 边界发生挪动（restrict/protect 的检查移入 action，variable 的名字正则移到门面），因此多重非法输入的报错**先后**可能改变，而所有单一错误路径不变。两个已知的不可观察差异：聚合层要等全部表清空才回收；读视图是快照而非活容器（仅对「在自己的遍历回调里再注册」可见）。
+
+## API 草图
+
+```ts ignore-check
+interface ScopeLayer {
+  isEmpty(): boolean
+}
+
+type LayerClass<L extends ScopeLayer> = new (scope: ScopeKey | undefined, layers: ScopedLayers<L>) => L
+
+declare function table<V>(kind: string): TableSpec<V>
+declare function createLayer<S extends Record<string, TableSpec<unknown>>>(
+  spec: S,
+): LayerClass<ScopeLayer & { readonly [K in keyof S]: Entries<EntryTypeOf<S[K]>> }>
+
+type Undo = () => unknown
+type LayerAction<L> = (layer: L) =>
+  | Undo
+  | Iterable<Undo, void, void>
+  | Promise<Undo>
+  | AsyncIterable<Undo, void, void>
+
+class ScopedLayers<L extends ScopeLayer> {
+  constructor(layerClass: LayerClass<L>, options: { label: string; onChange?: () => void })
+  readonly global: L
+  peek(scope: ScopeKey | undefined): L | undefined
+  merge<T>(scope: ScopeKey | undefined, pick: (layer: L) => Entries<T>, admitGlobal?: (name: string) => boolean): Map<string, T>
+  values<T>(scope: ScopeKey | undefined, pick: (layer: L) => Entries<T>): T[]
+  keys<T>(scope: ScopeKey | undefined, pick: (layer: L) => Entries<T>): string[]
+  effect(ctx: Context, action: LayerAction<L>, options?: { label?: string; silent?: boolean; scopedOnly?: boolean | string }): () => Promise<void> | void
+  forEach(fn: (layer: L, scope: ScopeKey | undefined) => void): void
+  filter(fn: (layer: L, scope: ScopeKey | undefined) => boolean): L[]
+  map<T>(fn: (layer: L, scope: ScopeKey | undefined) => T): T[]
+}
+
+class Entries<V> {
+  constructor(kind: string, scope: ScopeKey | undefined)
+  insert(name: string, value: V): () => void
+  append(value: V): () => void
+  get(name: string): V | undefined
+  has(name: string): boolean
+  keys(): string[]
+  entries(): ReadonlyArray<readonly [string, V]>
+  values(): readonly V[]
+  isEmpty(): boolean
+}
+```
+
+迁移后的消费者长什么样——现存最重的登记口从 30+ 行编排缩为一份声明加一行门面：
+
+```ts ignore-check
+class ToolLayer extends createLayer({
+  tools: table<ToolDefinition>('tool'),
+  restrictions: table<ToolRestriction>('tool restriction'),
+  guards: table<ToolGuardRegistration>('tool guard'),
+}) {
+  addRestriction(filter: ToolRestriction, reserved: readonly string[]): () => void { /* validate, snapshot, append */ }
+  admits(name: string): boolean { /* intersection over this.restrictions.values() */ }
+  guardReason(view: Readonly<ToolExecution>): string | undefined { /* first monotonic denial */ }
+}
+
+class ToolRegistry extends Service {
+  private readonly layers = new ScopedLayers(ToolLayer, {
+    label: 'tools',
+    onChange: () => this.ctx.emit('tools/change'),
+  })
+
+  register(definition: ToolDefinition): () => Promise<void> | void {
+    return this.layers.effect(this.ctx,
+      layer => layer.tools.insert(definition.name, definition),
+      { label: 'tools.register()' })
+  }
+
+  visible(scope?: ScopeKey): ToolDefinition[] {
+    return Array.from(this.layers.merge(scope, layer => layer.tools, name => this.admits(scope, name)).values())
+  }
+}
+```
+
+## 备选方案
+
+**每 scope 一个注册表实例，父子委托链。** 实例爆炸；「部署工具加我的工具」的合并视图要每个服务手写一个委托注册表；单订阅观察者（持久化、ACP bridge）必须逐实例发现并订阅；委托链表达不了减法（restriction）。子注册表还得反向触及父上下文，扩大暴露面。
+
+**注册 API 上的显式 scope 参数。** agent-scope RFC 已否决：漏传参数即静默注册为全局，且该形状能表达「对 X 可见、随 Y 销毁」——几乎必然是 bug。
+
+**只抽数据结构、编排留在服务。** 消掉的是重复里安全的那一半，留下的是危险的那一半——回滚先于 emit 的顺序、原始 disposer、回收规则，恰是 bug 所在。
+
+**内置视图语义的固定容器 helper。** 容器形态与合并策略被钉死在 helper 里；业务没有自由度，任何命名或单值变体都变成对 helper 的功能诉求。
+
+**每张表一个 helper。** 复刻今天的散装簿记——那正是被替换的现状：每服务 N 张 scope Map，agent 的贡献没有聚合。
+
+**`helper.get(ctx).effect(...)` 两步式登记。** 把建层与挂生命周期拆成两步；两步之间抛错会搁浅一个空层，返回的 handle 还是每次调用一笔额外分配。
+
+**层持有 ctx、自己注册 effect。** 把数据对象变成生命周期管理者，编排在每个业务类里重演一遍。
+
+## 验收标准
+
+- `store.ts` 落在 `dsh-scope`（peer 依赖不变：仅 cordis；模块图位置不变），逐文件 100% 覆盖，包括：层簿记与回收、四种 action 形态、合成顺序、change 监听器抛错回滚（条目被回卷、重名检查可再注册）、新建层的失败回收、`label`/`silent`/`scopedOnly` 选项、`createLayer` 构造、保留表名、同族回引类型、`Entries` 命名/匿名语义。
+- `dsh-tools` 与 `dsh-system-prompt` 各收敛为一个 `ScopedLayers`；所有既有测试通过，改动仅限已声明的重名文案断言更新；每个登记门面都是单次 `effect` 调用，并继续返回 cordis effect 的原始 disposer。
+- 行为按上文等价性声明与老基线一致：两个声明例外（统一文案；多重非法输入的报错先后）、两个不可观察差异（聚合回收时机；快照读视图），此外无他。
+- 文档随同一变更落地：`dsh-scope`/`dsh-tools`/`dsh-system-prompt` 的 README；实现后本 RFC 移入 `implemented/`，并就地更新[运行时设计 RFC](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md) 的注册章节。
+
+## 风险
+
+- 层/门面边界可能不适配某个未来消费者的形状。缓解：裸 `ScopeLayer` 接口始终是兜底；把 `LayerClass` 拓宽为可接受工厂（供有构造依赖的层）是已记录的非破坏扩展。
+- `createLayer` 的映射类型工厂是刻意的类型体操。接受：`defineTool` schema DSL 是仓库先例，体操圈在 `dsh-scope` 内部。
+- 两个等价性例外可能让断言精确重名文案或多重错误顺序的测试意外；在此声明，使评审是核对而非发现。
+- 快照读视图会隐藏「回调在自己的遍历中注册」的条目——病态但可见的模式；快照使其转为确定性行为。
+- 两个核心注册表同时迁移。缓解：设计期已完成逐行为对比，且 store 连同钉住等价性的测试先于任一迁移 commit 落地。

From 84d0932e5e7e117b753b34c123db9dbd1c102743 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 13 Jul 2026 00:06:04 +0800
Subject: [PATCH 02/74] docs(rfc): align scoped layers with final scope design

---
 .../2026-07-12-scoped-layers-store.i18n.yaml  |   4 +-
 .../2026-07-12-scoped-layers-store.md         | 125 +++++++++---------
 .../2026-07-12-scoped-layers-store.zh.md      | 125 +++++++++---------
 3 files changed, 134 insertions(+), 120 deletions(-)

diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml
index f868cfc669..be26cfa552 100644
--- a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml
+++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-12-scoped-layers-store.md: 0673d6c63291a66c84e91f2eff8eca26798b931f
-2026-07-12-scoped-layers-store.zh.md: 6460802f3cf3163f6be2ad51f2f82319a04288bc
+2026-07-12-scoped-layers-store.md: c3a9ab8724191b5b1bc87f02a90d6995c247d944
+2026-07-12-scoped-layers-store.zh.md: e2ec72145766a95ea1c330e3a658f7c86490e263
diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md
index 0673d6c632..c3a9ab8724 100644
--- a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md
+++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md
@@ -6,72 +6,70 @@ English | [中文](2026-07-12-scoped-layers-store.zh.md)
 
 ## Problem
 
-Agent scoping ([the agent-scope RFC](../../implemented/architecture/2026-07-08-agent-scope-contexts.md), [runtime design](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)) made "a registry with a global layer plus per-agent layers" a recurring shape, and every occurrence is hand-written. Seven registration sites exist today — `tools.register`/`tools.restrict`/`tools.guard` in `dsh-tools` and `section`/`tools`/`variable`/`protect` in `dsh-system-prompt` — each pairing a global container with its own `Map<ScopeKey, container>` and repeating the same 10-15-line effect choreography: read the calling context's tag, get-or-create the layer, validate, mutate, yield a rollback that deletes the entry, reclaims the emptied layer, and emits the change event, then emit and return the exact cordis effect disposer.
+Agent scoping ([the agent-scope RFC](../../implemented/architecture/2026-07-08-agent-scope-contexts.md), [runtime design](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)) made "a registry with a global layer plus per-agent layers" a recurring shape, and every occurrence is hand-written. Six registration sites exist today — `tools.register`/`tools.restrict`/`tools.guard` in `dsh-tools` and `section`/`tools`/`variable` in `dsh-system-prompt` — each repeating the same 10-15-line effect choreography around its applicable global or scoped containers: read the calling context's tag, get or create the layer, validate, mutate, yield a rollback that deletes the entry and reclaims an emptied scoped layer, emit the applicable change event, and return the exact Cordis effect disposer.
 
 Beyond the duplication, the risk concentrates in the choreography details:
 - The rollback must be collected before the change emit (so a throwing listener unwinds the insertion instead of leaking it)
-- The returned disposer must be cordis's own function (a wrapper silently breaks nested ordered teardown)
+- The returned disposer must be Cordis's own function (a wrapper silently breaks nested ordered teardown)
 - Emptied scoped layers must be reclaimed (a disposed agent must not leave residue keyed by its dead `ScopeKey`)
 
-Every new consumer has to rewrite all of that correctly, and the copies have already diverged stylistically — two private `layerFor` helpers in `dsh-tools`, four inline IIFEs in `dsh-system-prompt`.
+Every new consumer has to rewrite all of that correctly, and the copies have already diverged stylistically — two private layer helpers in `dsh-tools`, three inline IIFEs in `dsh-system-prompt`.
 
-Finally, one agent's contribution to one service is scattered across several maps that know nothing of each other — there is no object that means "what this scope contributes here" — and the consumer count keeps growing: guards and prompt protections landed recently, and per-agent `fs/*` policy, `llm/*` overrides, and per-agent compaction policy are all queued on the same pattern.
+Finally, one agent's contribution to one service is scattered across several maps that know nothing of each other — there is no object that means "what this scope contributes here" — and the consumer count keeps growing: scoped guards and per-agent prompt/tool composition landed recently, while per-agent `fs/*` policy, `llm/*` overrides, and compaction policy are plausible future users of the same pattern.
 
 ## Proposal
 
-`dsh-scope` gains a store module (a new `store.ts` under its `src/`, peer-dependent on cordis only, key-agnostic) built around one division of labor: **business logic lives in a layer class; the helper only schedules layers**. One helper instance per service; the value in its map is the aggregate of everything one scope contributes to that service.
+`dsh-scope` gains a key-agnostic `store.ts`, with Cordis as its only peer dependency. The module implements the smallest abstraction shared by the six current sites: **business state and validation stay in an explicit layer class; one helper owns layer selection, effect attachment, rollback, notification, and reclamation**. One helper instance belongs to one service, and one layer instance aggregates everything a scope contributes to that service.
 
-- **`ScopedLayers<L>`** — a concrete scheduler, never subclassed. It owns the global layer plus one `Map<ScopeKey, L>`, builds layers on demand as `new layerClass(scope, this)`, reclaims a layer when `isEmpty()`, and funnels every write through `effect(ctx, action, options?)`. The single `ctx` parameter decides both the visible layer (`scopeOf(ctx)`) and the owning fiber (`ctx.effect`), so "visible to X, disposed with Y" stays unrepresentable — the same shape argument the agent-scope RFC used against explicit scope parameters. Actions may produce one undo, an iterable of undos, a promise, or an async iterable — the four shapes of cordis `Effect` — and undos may be async. The helper seals collected undos (run in LIFO), empty-layer reclamation, and the change notification into one disposer, and hands cordis that disposer **before** the notification runs: a throwing change listener therefore makes cordis execute the already-collected rollback and rethrow, exactly like the hand-written yield-before-emit today. Reads are `global`/`peek` plus three selector primitives lifting the table views across the two layers — `merge` (named entries, scoped shadows global, global position preserved, optional admit predicate), `values` (concatenation including anonymous entries, deliberately no shadowing), `keys` (the pre-restriction name universe) — and array-returning `forEach`/`filter`/`map` over all layers.
-- **`createLayer({ name: table<V>(kind) })`** — a class factory in the `defineTool` DSL tradition. The generated base class builds every declared table in its constructor, threads the scope down, receives the sibling back-reference (`protected readonly layers: ScopedLayers<this>`, injected by the helper at construction; polymorphic `this` narrows it in subclasses), and aggregates `isEmpty()` over the declared tables. `layer.<table>` is a fully typed mapped property, so a misspelled table name is a compile error; the table names `scope`, `isEmpty`, and `layers` are reserved and throw. Business subclasses add domain methods in the class body — single-layer queries, registration validations, and cross-layer *reads* through `this.layers` (writes must still go through `effect`); a fully custom layer may instead implement the one-method `ScopeLayer` interface (`isEmpty()`).
-- **`Entries<V>`** — the canned table: named entries (`insert`, same-layer duplicates throw one standardized message pair pointing at `agent.ctx`) and anonymous entries (`append`, process-unique symbol keys, O(1) undo removal) share one insertion-ordered map; read views (`keys`/`entries`/`values`) return array snapshots.
+- **`ScopedLayers<L>`** is a concrete scheduler, not a base class. It owns the global layer plus one `Map<ScopeKey, L>`, constructs scoped layers on demand through an explicit factory, and reclaims a layer when `isEmpty()`. Its `effect(ctx, action, options?)` accepts one synchronous action that returns one synchronous undo because that is the complete shape of all six current sites. The single `ctx` decides both the visible layer (`scopeOf(ctx)`) and the owning Cordis fiber (`ctx.effect`), so "visible to X, disposed with Y" stays unrepresentable. The helper yields the undo before notifying listeners, returns Cordis's exact disposer, and reclaims a newly created empty layer if validation or mutation throws. Reads are `global`/`peek` plus `merge` (named entries with scoped shadowing and an optional global-admission predicate), `values` (global then scoped concatenation without shadowing), `keys` (the pre-restriction name universe), and `some` (cross-layer invariant checks).
+- **Explicit `ScopeLayer` classes** make each service's state visible to readers. `ToolLayer` and `PromptLayer` declare their three table properties and their `isEmpty()` aggregation directly; a small layer factory receives only the scope, while its closure may capture real constructor dependencies. Domain methods stay ordinary class methods. This costs a few repetitive declarations but avoids a mapped-type class factory, a scheduler/layer ownership cycle, reserved property names, and generated runtime structure.
+- **`NamedEntries<V>` and `AnonymousEntries<V>`** are the two shared insertion-ordered tables. Named entries expose `insert`/lookup and retain the current global/scoped duplicate wording through domain `kind` and per-agent-alternative labels; anonymous entries expose only `append`, using process-unique symbol keys for O(1) undo removal. Keeping the classes separate makes meaningless mixed named/anonymous operations unrepresentable and keeps key types sound. Their iterators borrow membership and typed contribution values; they do not clone or freeze values. `ScopedLayers` materializes only the merged arrays/maps already required by the service read paths.
 
-`dsh-tools` migrates its three tables into one `ToolLayer` (domain methods `addRestriction` — empty-filter/read-once/reserved-name/known-names validation with the reserved list passed in as data, since it reads service state — plus `admits` and `guardReason`), and `dsh-system-prompt` its four into one `PromptLayer` (`addProtection` with the global-conflict self-check via the back-reference, plus the `shadowedSections` predicate). Every facade becomes a single `effect` call carrying per-call `label`, `silent` (guards emit no change event), or `scopedOnly` (boolean, or a string carrying the domain error message) options. `assemble` stays in the facade for three hard reasons: it has no legal receiver (the subject scope's layer may not exist, and reads never create layers), shadowing forces merge-before-evaluate (per-layer rendering would evaluate shadowed providers, an observable change), and the assemble waterfall, `toolOrder`, and protection restore need service-level resources a layer must not hold.
+`dsh-tools` migrates its three tables into one `ToolLayer`: tools, compiled restrictions, and guards. The layer owns restriction admission and guard evaluation; the facade retains domain validation that needs service configuration, such as the reserved `run_code` name and the current known-global-name universe. Readonly allow/deny inputs are compiled once into internal sets. `dsh-system-prompt` likewise migrates sections, tool providers, and variables into one `PromptLayer`; its facade performs owner-final cross-layer checks through `layers.some`. Every registration facade performs its public argument validation and then makes one `effect` call with a label and, for guards, `silent: true`. A generic helper does not learn domain rules such as "restrictions require a scoped context."
 
-Migration is behavior-preserving with two declared exceptions: the three duplicate-name messages unify into one template (tests asserting the old wording update in the same change), and validations move relative to the effect boundary (restrict/protect checks move inside the action, the variable name regex moves to the facade), so the error *order* for multiply-invalid inputs can change while every single-fault path is unchanged. Two knowingly unobservable differences: an aggregate layer is reclaimed only when all its tables are empty, and read views are snapshots rather than live containers (visible only to a callback that registers during its own iteration).
+`assemble` stays in the `SystemPrompt` facade for three reasons: the subject scope's layer may not exist and reads must not create it; shadowing requires merge-before-evaluate so a hidden section provider is never called; and the assembly waterfall, `toolOrder`, and owner-final restoration use service-level resources. Sections and tool providers keep their current materialized derived views. Variable providers instead iterate the global and scoped `NamedEntries` directly, preserving today's live Map behavior when a provider registers another variable during assembly. Tool guards likewise iterate their `AnonymousEntries` directly. Owner-final remains metadata on section and tool contributions, not a second protection registry.
+
+Migration preserves public behavior and exact duplicate messages. The internal aggregate layer is reclaimed only after all three tables empty rather than when one table empties; no service API exposes layer identity. Direct live iteration retains current re-entrant variable-provider and guard behavior, while selector helpers continue to materialize the same section, tool-provider, and tool-resolution views their facades build today.
+
+`ScopeLayer`, `EntryValues`, `ScopedLayers`, `NamedEntries`, and `AnonymousEntries` are public `dsh-scope` root exports with export JSDoc. Consumers import them from `@deepseek-ai/dsh-scope`; `store.ts` is an implementation module, not a package subpath.
 
 ## API sketch
 
 ```ts ignore-check
-interface ScopeLayer {
+export interface ScopeLayer {
   isEmpty(): boolean
 }
 
-type LayerClass<L extends ScopeLayer> = new (scope: ScopeKey | undefined, layers: ScopedLayers<L>) => L
-
-declare function table<V>(kind: string): TableSpec<V>
-declare function createLayer<S extends Record<string, TableSpec<unknown>>>(
-  spec: S,
-): LayerClass<ScopeLayer & { readonly [K in keyof S]: Entries<EntryTypeOf<S[K]>> }>
-
-type Undo = () => unknown
-type LayerAction<L> = (layer: L) =>
-  | Undo
-  | Iterable<Undo, void, void>
-  | Promise<Undo>
-  | AsyncIterable<Undo, void, void>
-
-class ScopedLayers<L extends ScopeLayer> {
-  constructor(layerClass: LayerClass<L>, options: { label: string; onChange?: () => void })
+export class ScopedLayers<L extends ScopeLayer> {
+  constructor(createLayer: (scope: ScopeKey | undefined) => L, options: { onChange?: () => void })
   readonly global: L
   peek(scope: ScopeKey | undefined): L | undefined
-  merge<T>(scope: ScopeKey | undefined, pick: (layer: L) => Entries<T>, admitGlobal?: (name: string) => boolean): Map<string, T>
-  values<T>(scope: ScopeKey | undefined, pick: (layer: L) => Entries<T>): T[]
-  keys<T>(scope: ScopeKey | undefined, pick: (layer: L) => Entries<T>): string[]
-  effect(ctx: Context, action: LayerAction<L>, options?: { label?: string; silent?: boolean; scopedOnly?: boolean | string }): () => Promise<void> | void
-  forEach(fn: (layer: L, scope: ScopeKey | undefined) => void): void
-  filter(fn: (layer: L, scope: ScopeKey | undefined) => boolean): L[]
-  map<T>(fn: (layer: L, scope: ScopeKey | undefined) => T): T[]
+  merge<T>(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries<T>, admitGlobal?: (name: string) => boolean): Map<string, T>
+  values<T>(scope: ScopeKey | undefined, pick: (layer: L) => EntryValues<T>): T[]
+  keys<T>(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries<T>): string[]
+  some(fn: (layer: L, scope: ScopeKey | undefined) => boolean): boolean
+  effect(ctx: Context, action: (layer: L) => () => void, options: { label: string; silent?: boolean }): () => Promise<void> | void
 }
 
-class Entries<V> {
-  constructor(kind: string, scope: ScopeKey | undefined)
+export interface EntryValues<V> {
+  values(): IterableIterator<V>
+  isEmpty(): boolean
+}
+
+export class NamedEntries<V> implements EntryValues<V> {
+  constructor(kind: string, perAgentAlternative: string, scope: ScopeKey | undefined)
   insert(name: string, value: V): () => void
-  append(value: V): () => void
   get(name: string): V | undefined
   has(name: string): boolean
-  keys(): string[]
-  entries(): ReadonlyArray<readonly [string, V]>
-  values(): readonly V[]
+  keys(): IterableIterator<string>
+  entries(): IterableIterator<[string, V]>
+  values(): IterableIterator<V>
+  isEmpty(): boolean
+}
+
+export class AnonymousEntries<V> implements EntryValues<V> {
+  append(value: V): () => void
+  values(): IterableIterator<V>
   isEmpty(): boolean
 }
 ```
@@ -79,21 +77,26 @@ class Entries<V> {
 What a migrated consumer looks like — the heaviest current site shrinks from 30+ lines of choreography to a declaration and one-line facades:
 
 ```ts ignore-check
-class ToolLayer extends createLayer({
-  tools: table<ToolDefinition>('tool'),
-  restrictions: table<ToolRestriction>('tool restriction'),
-  guards: table<ToolGuardRegistration>('tool guard'),
-}) {
-  addRestriction(filter: ToolRestriction, reserved: readonly string[]): () => void { /* validate, snapshot, append */ }
+class ToolLayer implements ScopeLayer {
+  readonly tools = new NamedEntries<ToolDefinition>('tool', 'variant', this.scope)
+  readonly restrictions = new AnonymousEntries<CompiledToolRestriction>()
+  readonly guards = new AnonymousEntries<ToolGuardRegistration>()
+
+  constructor(
+    readonly scope: ScopeKey | undefined,
+  ) {}
+
+  isEmpty(): boolean { return this.tools.isEmpty() && this.restrictions.isEmpty() && this.guards.isEmpty() }
+  addRestriction(filter: ToolRestriction): () => void { /* compile to sets, append */ }
   admits(name: string): boolean { /* intersection over this.restrictions.values() */ }
   guardReason(view: Readonly<ToolExecution>): string | undefined { /* first monotonic denial */ }
 }
 
 class ToolRegistry extends Service {
-  private readonly layers = new ScopedLayers(ToolLayer, {
-    label: 'tools',
-    onChange: () => this.ctx.emit('tools/change'),
-  })
+  private readonly layers = new ScopedLayers(
+    scope => new ToolLayer(scope),
+    { onChange: () => this.ctx.emit('tools/change') },
+  )
 
   register(definition: ToolDefinition): () => Promise<void> | void {
     return this.layers.effect(this.ctx,
@@ -101,8 +104,9 @@ class ToolRegistry extends Service {
       { label: 'tools.register()' })
   }
 
-  visible(scope?: ScopeKey): ToolDefinition[] {
-    return Array.from(this.layers.merge(scope, layer => layer.tools, name => this.admits(scope, name)).values())
+  private resolveVisible(scope?: ScopeKey): ToolDefinition[] {
+    const scoped = this.layers.peek(scope)
+    return Array.from(this.layers.merge(scope, layer => layer.tools, name => scoped?.admits(name) ?? true).values())
   }
 }
 ```
@@ -115,6 +119,10 @@ class ToolRegistry extends Service {
 
 **Extracting only the data structure, leaving the choreography in services.** Removes the safe half of the duplication and keeps the dangerous half — the rollback-before-emit ordering, raw-disposer, and reclamation rules are exactly where the bugs live.
 
+**Accepting the full Cordis `Effect` union as a layer action.** None of the six sites has asynchronous setup, multiple undos, or an independent settlement boundary. Normalizing promises, iterables, async iterables, LIFO sealing, and partial failure would duplicate lifecycle machinery speculatively. The store accepts one synchronous action and one undo; a future real boundary can justify widening it.
+
+**Generating layer classes from a mapped-type table DSL.** The two consumers each declare three tables. A class factory would save a handful of lines while adding generated runtime shape, reserved names, polymorphic-`this` typing, and a second construction model. Explicit classes are easier to inspect and can still share the entry tables and `ScopedLayers`.
+
 **A fixed-container helper with built-in view semantics.** Pins container shapes and merge policy inside the helper; business gets no freedom, and every naming or single-value variation becomes a helper feature request.
 
 **One helper per table.** Reproduces today's scattered bookkeeping — that is the status quo being replaced, with N scope maps per service and no aggregate for an agent's contribution.
@@ -125,15 +133,14 @@ class ToolRegistry extends Service {
 
 ## Acceptance criteria
 
-- `store.ts` ships in `dsh-scope` (peer deps unchanged: cordis only; module-graph position unchanged) with per-file 100% coverage, including: layer bookkeeping and reclamation, all four action shapes, seal ordering, the throwing-change-listener rollback (the entry is rolled back and the duplicate check re-registers), failure reclamation of freshly created layers, `label`/`silent`/`scopedOnly` options, `createLayer` construction, reserved table names, back-reference typing, and `Entries` named/anonymous semantics.
-- `dsh-tools` and `dsh-system-prompt` each collapse to one `ScopedLayers`; all existing tests pass with only the declared duplicate-message assertion updates; every registration facade is a single `effect` call and keeps returning the exact cordis effect disposer.
-- Behavior matches the old baseline per the equivalence statement above: two declared exceptions (unified messages; error order for multiply-invalid inputs), two unobservable differences (aggregate reclamation timing; snapshot read views), nothing else.
+- `store.ts` ships in `dsh-scope` (peer dependencies unchanged: Cordis only; module-graph position unchanged) with per-file 100% coverage of layer selection and reclamation, synchronous action/undo ordering, throwing-action cleanup, throwing-change-listener rollback, exact disposer identity, `label`/`silent`, factory typing, cross-layer `some`, merge selectors, and separate named/anonymous entry semantics. Its five public symbols are re-exported from the package root and carry export JSDoc.
+- `dsh-tools` and `dsh-system-prompt` each collapse to one `ScopedLayers`; every registration facade validates its domain contract and then makes one `effect` call, and all keep returning the exact Cordis effect disposer.
+- Existing behavior, duplicate messages, validation order, live variable-provider re-entrancy, and live guard re-entrancy remain unchanged. Tests additionally pin aggregate reclamation timing and selector materialization.
 - Documentation lands in the same change: `dsh-scope`/`dsh-tools`/`dsh-system-prompt` READMEs; on implementation this RFC moves to `implemented/` and the [runtime-design RFC](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)'s registration section is updated in place.
 
 ## Risks
 
-- The layer/facade boundary may not fit a future consumer's shape. Mitigation: the bare `ScopeLayer` interface remains the floor, and widening `LayerClass` to accept a factory (for layers with constructor dependencies) is a recorded non-breaking extension.
-- `createLayer`'s mapped-type factory is deliberate type gymnastics. Accepted: the `defineTool` schema DSL is the repo precedent, and the gymnastics stay inside `dsh-scope`.
-- The two equivalence exceptions can surprise tests that assert exact duplicate messages or multi-fault error order; they are declared here so review checks them rather than discovers them.
-- Snapshot read views hide entries registered by a callback during its own iteration — a pathological pattern, but a visible one; snapshots make it deterministic instead.
+- The layer/facade boundary may not fit a future consumer's shape. Mitigation: `ScopeLayer` requires only `isEmpty()`, while the factory closure can capture constructor dependencies without giving a layer ownership of its scheduler.
+- A future registration may genuinely need asynchronous setup or several independently owned undos. The helper deliberately does not predict that lifecycle; such a consumer must first identify its owner and settlement boundary, then widen the contract with tests.
+- Explicit layer declarations repeat three property initializers and `isEmpty()` in each consumer. Accepted: the repetition keeps runtime state and types visible and avoids a second DSL for two classes.
 - Two core registries migrate at once. Mitigated by the behavior comparison performed during design and by landing the store with equivalence-pinning tests before either migration commit.
diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md
index 6460802f3c..e2ec721457 100644
--- a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md
+++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md
@@ -6,72 +6,70 @@ Status: proposed
 
 ## 问题
 
-agent 作用域落地之后（[agent-scope RFC](../../implemented/architecture/2026-07-08-agent-scope-contexts.md)、[运行时设计篇](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)），「一张全局层加若干 per-agent 层的注册表」成为反复出现的形态，而每一处都是手写的。今天已有七个登记口——`dsh-tools` 的 `tools.register`/`tools.restrict`/`tools.guard` 与 `dsh-system-prompt` 的 `section`/`tools`/`variable`/`protect`——每处都是一个全局容器配一张自己的 `Map<ScopeKey, 容器>`，并重复同一段 10-15 行的 effect 编排：读调用方上下文的标签、按需建层、校验、变更、yield 一个「删条目 → 回收空层 → 发 change 事件」的回滚，然后发事件并返回 cordis effect 的原始 disposer。
+agent 作用域落地之后（[agent-scope RFC](../../implemented/architecture/2026-07-08-agent-scope-contexts.md)、[运行时设计篇](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)），「一张全局层加若干 per-agent 层的注册表」成为反复出现的形态，而每一处都是手写的。今天已有六个登记口——`dsh-tools` 的 `tools.register`/`tools.restrict`/`tools.guard` 与 `dsh-system-prompt` 的 `section`/`tools`/`variable`——每处都围绕适用的全局或专属容器重复同一段 10-15 行的 effect 编排：读调用方上下文的标签、按需建层、校验、变更、yield 一个删除条目并回收空专属层的回滚、发适用的 change 事件，然后返回 Cordis effect 的原始 disposer。
 
 除此之外：风险集中在编排细节上：
 - 回滚必须在 change 发出之前被收集（抛错的监听器才能回卷插入而不是泄漏）
-- 返回的 disposer 必须是 cordis 自己的那个函数（包装器会静默破坏嵌套的有序拆除）
+- 返回的 disposer 必须是 Cordis 自己的那个函数（包装器会静默破坏嵌套的有序拆除）
 - 清空的专属层必须被回收（被 dispose 的 agent 不得留下以死 `ScopeKey` 为键的残余）
 
-每个新消费者都要把这一切重新写对一遍，而各副本的写法已经分叉——`dsh-tools` 里有两个私有 `layerFor`，`dsh-system-prompt` 里是四处内联 IIFE。
+每个新消费者都要把这一切重新写对一遍，而各副本的写法已经分叉——`dsh-tools` 里有两个私有建层 helper，`dsh-system-prompt` 里是三处内联 IIFE。
 
-最后，一个 agent 在一个服务里的贡献散落在几张互不相识的 Map 里——不存在一个「这个 scope 在这里贡献了什么」的对象——而消费者还在持续增多：guard 与提示词 protection 是最近落地的一批，per-agent 的 `fs/*` 策略、`llm/*` 覆盖、per-agent compaction 策略都排在同一个模式上。
+最后，一个 agent 在一个服务里的贡献散落在几张互不相识的 Map 里——不存在一个「这个 scope 在这里贡献了什么」的对象——而消费者还在持续增多：专属 guard 与 per-agent 提示词/工具组合是最近落地的一批，per-agent 的 `fs/*` 策略、`llm/*` 覆盖与 compaction 策略则是同一模式的潜在后续用户。
 
 ## 提案
 
-`dsh-scope` 新增 store 模块（其 `src/` 下新增 `store.ts`，peer 依赖仅 cordis，与键类型无关），核心是一条分工：**业务逻辑封在层类里，helper 只负责调度层**。一个服务一个 helper 实例；其 Map 的 value 就是「一个 scope 在该服务的全部贡献」这一聚合对象。
+`dsh-scope` 新增与键类型无关的 `store.ts`，peer 依赖仍只有 Cordis。模块只抽取六个现有登记口已经共同证明的最小形状：**业务状态与校验留在显式层类里；一个 helper 统一负责选层、挂 effect、回滚、通知与回收**。一个 helper 实例属于一个服务；一个层实例聚合某 scope 对该服务的全部贡献。
 
-- **`ScopedLayers<L>`**——具体的调度器，不作继承点。持有全局层与一张 `Map<ScopeKey, L>`，按需以 `new layerClass(scope, this)` 建层，层 `isEmpty()` 时回收，并把所有写入收拢到 `effect(ctx, action, options?)`。单一 `ctx` 参数同时决定可见层（`scopeOf(ctx)`）与属主 fiber（`ctx.effect`），「对 X 可见、随 Y 销毁」因此不可表达——与 agent-scope RFC 否决显式 scope 参数用的是同一个形状论证。action 可以产出单个撤销、撤销的可迭代、Promise 或异步可迭代——即 cordis `Effect` 的四种形态——且撤销允许异步。helper 把收集到的撤销（逆序执行）、空层回收与 change 通知合成**一个** disposer，并在通知运行**之前**先把它交给 cordis：因此 change 监听器抛错时，cordis 会执行已收集的回滚再重抛，与今天手写的「yield 在 emit 之前」逐字等价。读取件是 `global`/`peek`，外加把表视图提升到两层的三个 selector 原语——`merge`（命名条目，专属遮蔽全局、保留全局位置，可选放行谓词）、`values`（拼接、含匿名条目、刻意不做遮蔽）、`keys`（限制前名字全集）——以及跨全部层、返回数组的 `forEach`/`filter`/`map`。
-- **`createLayer({ 表名: table<V>(kind) })`**——`defineTool` DSL 传统的类工厂。生成的基类在构造器里建好每张声明的表、把 scope 传下去、接收同族回引（`protected readonly layers: ScopedLayers<this>`，由 helper 建层时注入；多态 `this` 型在子类中自动收窄），并对声明的表聚合 `isEmpty()`。`layer.<表名>` 是带完整类型的映射属性，写错表名是编译错误；表名 `scope`、`isEmpty`、`layers` 保留，冲突即抛。业务子类在类体里追加领域方法——单层查询、登记校验，以及经 `this.layers` 的跨层**只读**（写入仍必须走 `effect`）；完全自定义的层也可以只实现单方法接口 `ScopeLayer`（`isEmpty()`）。
-- **`Entries<V>`**——罐装条目表：命名条目（`insert`，同层重名抛一对指向 `agent.ctx` 的标准化文案）与匿名条目（`append`，进程内唯一 symbol 键、O(1) 撤销删除）共用一张保插入序的 Map；读视图（`keys`/`entries`/`values`）返回数组快照。
+- **`ScopedLayers<L>`** 是具体调度器，不作基类。它持有全局层与一张 `Map<ScopeKey, L>`，通过显式工厂按需构造专属层，并在层 `isEmpty()` 时回收。`effect(ctx, action, options?)` 只接受一个同步 action，action 只返回一个同步 undo，因为六个现有登记口的完整形状就是如此。单一 `ctx` 同时决定可见层（`scopeOf(ctx)`）与属主 Cordis fiber（`ctx.effect`），「对 X 可见、随 Y 销毁」因此不可表达。helper 在通知监听器前 yield undo，返回 Cordis 的原始 disposer，并在校验或变更抛错时回收刚建出的空层。读取接口是 `global`/`peek`，以及 `merge`（命名条目的专属遮蔽与可选全局放行谓词）、`values`（不遮蔽地依次拼接全局与专属条目）、`keys`（限制前名字全集）和 `some`（跨层不变量检查）。
+- **显式 `ScopeLayer` 类**让每个服务的状态一眼可见。`ToolLayer` 与 `PromptLayer` 直接声明各自三项表属性与 `isEmpty()` 聚合；一个小工厂只向构造器传入 scope，闭包仍可捕获真实构造依赖。领域方法仍是普通类方法。代价是几行重复声明，收益是不用引入 mapped-type 类工厂、scheduler/layer 属主环、保留属性名和生成式运行时结构。
+- **`NamedEntries<V>` 与 `AnonymousEntries<V>`** 是两种共用的保插入序条目表。命名表暴露 `insert`/查询，并通过领域 `kind` 与 per-agent alternative 标签保持现有全局/专属重名文案；匿名表只暴露 `append`，以进程内唯一 symbol 作键支持 O(1) 撤销删除。分成两类以后，无意义的命名/匿名混用不可表达，key 类型也保持健全。迭代器借用表成员与带类型的贡献值，不会 clone 或 freeze 值；`ScopedLayers` 只物化服务读路径本来就需要的合并数组或 Map。
 
-`dsh-tools` 把三张表合并进一个 `ToolLayer`（领域方法 `addRestriction`——空过滤器/读取一次性/保留名/已知名校验，保留名单因读服务状态而以数据传入——加上 `admits` 与 `guardReason`），`dsh-system-prompt` 把四张表合并进一个 `PromptLayer`（`addProtection` 经同族回引做全局冲突自检，加上 `shadowedSections` 谓词）。每个门面都变成单次 `effect` 调用，携带 per-call 的 `label`、`silent`（guard 不发 change 事件）或 `scopedOnly`（布尔，或携带领域报错文案的字符串）选项。`assemble` 留在门面，三条硬理由：它没有合法接收者（主体 scope 的层可能不存在，而读路径绝不建层）、遮蔽语义强制先合并后求值（逐层渲染会求值被遮蔽的 provider，行为可观察地改变）、组装 waterfall、`toolOrder` 与 protection 恢复需要层不应持有的服务级资源。
+`dsh-tools` 把工具、已编译 restriction 与 guard 三张表合并进一个 `ToolLayer`。restriction 放行判断与 guard 求值归层所有；`run_code` 保留名、当前已知全局名集合等依赖服务配置的领域校验仍留在门面。只读 allow/deny 输入只编译一次，成为内部 Set。`dsh-system-prompt` 同样把 section、tool provider 与 variable 合并进一个 `PromptLayer`；门面通过 `layers.some` 完成 owner-final 跨层冲突检查。每个登记门面先完成公开参数校验，再以 label 做一次 `effect` 调用；guard 额外传 `silent: true`。通用 helper 不理解「restriction 必须由 scoped context 调用」之类领域规则。
 
-迁移保持行为等价，带两个声明的例外：三处重名文案统一为一个模板（断言旧文案的测试在同一变更中更新）；校验相对 effect 边界发生挪动（restrict/protect 的检查移入 action，variable 的名字正则移到门面），因此多重非法输入的报错**先后**可能改变，而所有单一错误路径不变。两个已知的不可观察差异：聚合层要等全部表清空才回收；读视图是快照而非活容器（仅对「在自己的遍历回调里再注册」可见）。
+`assemble` 留在 `SystemPrompt` 门面，三条理由：主体 scope 的层可能不存在，读路径不得创建它；遮蔽语义要求先合并再求值，被遮蔽的 section provider 绝不能被调用；组装 waterfall、`toolOrder` 与 owner-final 恢复使用服务级资源。section 与 tool provider 保持既有的派生视图物化；variable provider 则直接遍历全局与专属 `NamedEntries`，保留 provider 在组装期间登记另一 variable 时的现有活 Map 行为。tool guard 同样直接遍历其 `AnonymousEntries`。owner-final 仍是 section 与 tool 贡献上的元数据，不是第二张 protection 注册表。
+
+迁移保持公开行为与精确重名文案不变。内部聚合层会在三张表全部清空后才回收，而不是某一张表清空时回收；服务 API 不暴露层身份。直接活遍历保留现有 variable-provider 与 guard 重入行为，selector helper 则继续物化门面今天已经在构造的 section、tool-provider 与工具解析视图。
+
+`ScopeLayer`、`EntryValues`、`ScopedLayers`、`NamedEntries` 与 `AnonymousEntries` 都是带 export JSDoc 的 `dsh-scope` 根导出。消费者从 `@deepseek-ai/dsh-scope` 导入；`store.ts` 是实现模块，不是 package subpath。
 
 ## API 草图
 
 ```ts ignore-check
-interface ScopeLayer {
+export interface ScopeLayer {
   isEmpty(): boolean
 }
 
-type LayerClass<L extends ScopeLayer> = new (scope: ScopeKey | undefined, layers: ScopedLayers<L>) => L
-
-declare function table<V>(kind: string): TableSpec<V>
-declare function createLayer<S extends Record<string, TableSpec<unknown>>>(
-  spec: S,
-): LayerClass<ScopeLayer & { readonly [K in keyof S]: Entries<EntryTypeOf<S[K]>> }>
-
-type Undo = () => unknown
-type LayerAction<L> = (layer: L) =>
-  | Undo
-  | Iterable<Undo, void, void>
-  | Promise<Undo>
-  | AsyncIterable<Undo, void, void>
-
-class ScopedLayers<L extends ScopeLayer> {
-  constructor(layerClass: LayerClass<L>, options: { label: string; onChange?: () => void })
+export class ScopedLayers<L extends ScopeLayer> {
+  constructor(createLayer: (scope: ScopeKey | undefined) => L, options: { onChange?: () => void })
   readonly global: L
   peek(scope: ScopeKey | undefined): L | undefined
-  merge<T>(scope: ScopeKey | undefined, pick: (layer: L) => Entries<T>, admitGlobal?: (name: string) => boolean): Map<string, T>
-  values<T>(scope: ScopeKey | undefined, pick: (layer: L) => Entries<T>): T[]
-  keys<T>(scope: ScopeKey | undefined, pick: (layer: L) => Entries<T>): string[]
-  effect(ctx: Context, action: LayerAction<L>, options?: { label?: string; silent?: boolean; scopedOnly?: boolean | string }): () => Promise<void> | void
-  forEach(fn: (layer: L, scope: ScopeKey | undefined) => void): void
-  filter(fn: (layer: L, scope: ScopeKey | undefined) => boolean): L[]
-  map<T>(fn: (layer: L, scope: ScopeKey | undefined) => T): T[]
+  merge<T>(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries<T>, admitGlobal?: (name: string) => boolean): Map<string, T>
+  values<T>(scope: ScopeKey | undefined, pick: (layer: L) => EntryValues<T>): T[]
+  keys<T>(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries<T>): string[]
+  some(fn: (layer: L, scope: ScopeKey | undefined) => boolean): boolean
+  effect(ctx: Context, action: (layer: L) => () => void, options: { label: string; silent?: boolean }): () => Promise<void> | void
 }
 
-class Entries<V> {
-  constructor(kind: string, scope: ScopeKey | undefined)
+export interface EntryValues<V> {
+  values(): IterableIterator<V>
+  isEmpty(): boolean
+}
+
+export class NamedEntries<V> implements EntryValues<V> {
+  constructor(kind: string, perAgentAlternative: string, scope: ScopeKey | undefined)
   insert(name: string, value: V): () => void
-  append(value: V): () => void
   get(name: string): V | undefined
   has(name: string): boolean
-  keys(): string[]
-  entries(): ReadonlyArray<readonly [string, V]>
-  values(): readonly V[]
+  keys(): IterableIterator<string>
+  entries(): IterableIterator<[string, V]>
+  values(): IterableIterator<V>
+  isEmpty(): boolean
+}
+
+export class AnonymousEntries<V> implements EntryValues<V> {
+  append(value: V): () => void
+  values(): IterableIterator<V>
   isEmpty(): boolean
 }
 ```
@@ -79,21 +77,26 @@ class Entries<V> {
 迁移后的消费者长什么样——现存最重的登记口从 30+ 行编排缩为一份声明加一行门面：
 
 ```ts ignore-check
-class ToolLayer extends createLayer({
-  tools: table<ToolDefinition>('tool'),
-  restrictions: table<ToolRestriction>('tool restriction'),
-  guards: table<ToolGuardRegistration>('tool guard'),
-}) {
-  addRestriction(filter: ToolRestriction, reserved: readonly string[]): () => void { /* validate, snapshot, append */ }
+class ToolLayer implements ScopeLayer {
+  readonly tools = new NamedEntries<ToolDefinition>('tool', 'variant', this.scope)
+  readonly restrictions = new AnonymousEntries<CompiledToolRestriction>()
+  readonly guards = new AnonymousEntries<ToolGuardRegistration>()
+
+  constructor(
+    readonly scope: ScopeKey | undefined,
+  ) {}
+
+  isEmpty(): boolean { return this.tools.isEmpty() && this.restrictions.isEmpty() && this.guards.isEmpty() }
+  addRestriction(filter: ToolRestriction): () => void { /* compile to sets, append */ }
   admits(name: string): boolean { /* intersection over this.restrictions.values() */ }
   guardReason(view: Readonly<ToolExecution>): string | undefined { /* first monotonic denial */ }
 }
 
 class ToolRegistry extends Service {
-  private readonly layers = new ScopedLayers(ToolLayer, {
-    label: 'tools',
-    onChange: () => this.ctx.emit('tools/change'),
-  })
+  private readonly layers = new ScopedLayers(
+    scope => new ToolLayer(scope),
+    { onChange: () => this.ctx.emit('tools/change') },
+  )
 
   register(definition: ToolDefinition): () => Promise<void> | void {
     return this.layers.effect(this.ctx,
@@ -101,8 +104,9 @@ class ToolRegistry extends Service {
       { label: 'tools.register()' })
   }
 
-  visible(scope?: ScopeKey): ToolDefinition[] {
-    return Array.from(this.layers.merge(scope, layer => layer.tools, name => this.admits(scope, name)).values())
+  private resolveVisible(scope?: ScopeKey): ToolDefinition[] {
+    const scoped = this.layers.peek(scope)
+    return Array.from(this.layers.merge(scope, layer => layer.tools, name => scoped?.admits(name) ?? true).values())
   }
 }
 ```
@@ -115,6 +119,10 @@ class ToolRegistry extends Service {
 
 **只抽数据结构、编排留在服务。** 消掉的是重复里安全的那一半，留下的是危险的那一半——回滚先于 emit 的顺序、原始 disposer、回收规则，恰是 bug 所在。
 
+**让 layer action 接受完整 Cordis `Effect` union。** 六个现有登记口都没有异步 setup、多份 undo 或独立 settlement 边界。现在就规范化 Promise、iterable、async iterable、LIFO 合成与部分失败，会重复一套纯属推测的生命周期 machinery。store 只接受一个同步 action 与一个 undo；未来出现真实边界时再凭证据拓宽。
+
+**由 mapped-type 表 DSL 生成层类。** 两个消费者各自只有三张表。类工厂省下几行代码，却引入生成式运行时形状、保留名、多态 `this` 类型和第二种构造模型。显式类更易检查，同时仍可复用两种条目表与 `ScopedLayers`。
+
 **内置视图语义的固定容器 helper。** 容器形态与合并策略被钉死在 helper 里；业务没有自由度，任何命名或单值变体都变成对 helper 的功能诉求。
 
 **每张表一个 helper。** 复刻今天的散装簿记——那正是被替换的现状：每服务 N 张 scope Map，agent 的贡献没有聚合。
@@ -125,15 +133,14 @@ class ToolRegistry extends Service {
 
 ## 验收标准
 
-- `store.ts` 落在 `dsh-scope`（peer 依赖不变：仅 cordis；模块图位置不变），逐文件 100% 覆盖，包括：层簿记与回收、四种 action 形态、合成顺序、change 监听器抛错回滚（条目被回卷、重名检查可再注册）、新建层的失败回收、`label`/`silent`/`scopedOnly` 选项、`createLayer` 构造、保留表名、同族回引类型、`Entries` 命名/匿名语义。
-- `dsh-tools` 与 `dsh-system-prompt` 各收敛为一个 `ScopedLayers`；所有既有测试通过，改动仅限已声明的重名文案断言更新；每个登记门面都是单次 `effect` 调用，并继续返回 cordis effect 的原始 disposer。
-- 行为按上文等价性声明与老基线一致：两个声明例外（统一文案；多重非法输入的报错先后）、两个不可观察差异（聚合回收时机；快照读视图），此外无他。
+- `store.ts` 落在 `dsh-scope`（peer 依赖不变：仅 Cordis；模块图位置不变），逐文件 100% 覆盖选层与回收、同步 action/undo 顺序、action 抛错清理、change 监听器抛错回滚、原始 disposer 身份、`label`/`silent`、工厂类型、跨层 `some`、合并 selector，以及分开的命名/匿名条目语义。五个公开符号从 package 根重导出并带 export JSDoc。
+- `dsh-tools` 与 `dsh-system-prompt` 各收敛为一个 `ScopedLayers`；每个登记门面先校验领域契约再做一次 `effect` 调用，并继续返回 Cordis effect 的原始 disposer。
+- 既有行为、重名文案、校验顺序、variable-provider 活重入与 guard 活重入不变。测试另行钉住聚合回收时机与 selector 物化。
 - 文档随同一变更落地：`dsh-scope`/`dsh-tools`/`dsh-system-prompt` 的 README；实现后本 RFC 移入 `implemented/`，并就地更新[运行时设计 RFC](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md) 的注册章节。
 
 ## 风险
 
-- 层/门面边界可能不适配某个未来消费者的形状。缓解：裸 `ScopeLayer` 接口始终是兜底；把 `LayerClass` 拓宽为可接受工厂（供有构造依赖的层）是已记录的非破坏扩展。
-- `createLayer` 的映射类型工厂是刻意的类型体操。接受：`defineTool` schema DSL 是仓库先例，体操圈在 `dsh-scope` 内部。
-- 两个等价性例外可能让断言精确重名文案或多重错误顺序的测试意外；在此声明，使评审是核对而非发现。
-- 快照读视图会隐藏「回调在自己的遍历中注册」的条目——病态但可见的模式；快照使其转为确定性行为。
+- 层/门面边界可能不适配某个未来消费者的形状。缓解：`ScopeLayer` 只要求 `isEmpty()`；工厂闭包可捕获构造依赖，无需让层反向持有 scheduler。
+- 未来登记口可能真的需要异步 setup 或多份独立属主的 undo。helper 刻意不预测这种生命周期；该消费者必须先说明 owner 与 settlement 边界，再连同测试拓宽契约。
+- 显式层声明会在两个消费者中各重复三行属性初始化与一段 `isEmpty()`。接受：这点重复让运行时状态和类型保持可见，避免为两个类引入第二套 DSL。
 - 两个核心注册表同时迁移。缓解：设计期已完成逐行为对比，且 store 连同钉住等价性的测试先于任一迁移 commit 落地。

From 0289e69ee99f63cbb2149137c78d08fbd314e0fb Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 13 Jul 2026 12:08:41 +0800
Subject: [PATCH 03/74] docs(rfc): narrow scoped-layer disposers

---
 .../architecture/2026-07-12-scoped-layers-store.i18n.yaml     | 4 ++--
 .../proposed/architecture/2026-07-12-scoped-layers-store.md   | 4 ++--
 .../architecture/2026-07-12-scoped-layers-store.zh.md         | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml
index be26cfa552..bf5027e5ec 100644
--- a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml
+++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-12-scoped-layers-store.md: c3a9ab8724191b5b1bc87f02a90d6995c247d944
-2026-07-12-scoped-layers-store.zh.md: e2ec72145766a95ea1c330e3a658f7c86490e263
+2026-07-12-scoped-layers-store.md: 510f462344b25b72bb8604d88f125cc92c6510b1
+2026-07-12-scoped-layers-store.zh.md: abc2aad140cc10325392ed8800e33e38684511a8
diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md
index c3a9ab8724..510f462344 100644
--- a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md
+++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md
@@ -48,7 +48,7 @@ export class ScopedLayers<L extends ScopeLayer> {
   values<T>(scope: ScopeKey | undefined, pick: (layer: L) => EntryValues<T>): T[]
   keys<T>(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries<T>): string[]
   some(fn: (layer: L, scope: ScopeKey | undefined) => boolean): boolean
-  effect(ctx: Context, action: (layer: L) => () => void, options: { label: string; silent?: boolean }): () => Promise<void> | void
+  effect(ctx: Context, action: (layer: L) => () => void, options: { label: string; silent?: boolean }): () => void
 }
 
 export interface EntryValues<V> {
@@ -98,7 +98,7 @@ class ToolRegistry extends Service {
     { onChange: () => this.ctx.emit('tools/change') },
   )
 
-  register(definition: ToolDefinition): () => Promise<void> | void {
+  register(definition: ToolDefinition): () => void {
     return this.layers.effect(this.ctx,
       layer => layer.tools.insert(definition.name, definition),
       { label: 'tools.register()' })
diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md
index e2ec721457..abc2aad140 100644
--- a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md
+++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md
@@ -48,7 +48,7 @@ export class ScopedLayers<L extends ScopeLayer> {
   values<T>(scope: ScopeKey | undefined, pick: (layer: L) => EntryValues<T>): T[]
   keys<T>(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries<T>): string[]
   some(fn: (layer: L, scope: ScopeKey | undefined) => boolean): boolean
-  effect(ctx: Context, action: (layer: L) => () => void, options: { label: string; silent?: boolean }): () => Promise<void> | void
+  effect(ctx: Context, action: (layer: L) => () => void, options: { label: string; silent?: boolean }): () => void
 }
 
 export interface EntryValues<V> {
@@ -98,7 +98,7 @@ class ToolRegistry extends Service {
     { onChange: () => this.ctx.emit('tools/change') },
   )
 
-  register(definition: ToolDefinition): () => Promise<void> | void {
+  register(definition: ToolDefinition): () => void {
     return this.layers.effect(this.ctx,
       layer => layer.tools.insert(definition.name, definition),
       { label: 'tools.register()' })

From 0646bae562ffb3c9f50152703e74bcc051c90cb4 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 13 Jul 2026 13:49:25 +0800
Subject: [PATCH 04/74] docs(rfc): narrow scoped-layer abstraction

---
 .../2026-07-12-scoped-layers-store.i18n.yaml             | 4 ++--
 .../architecture/2026-07-12-scoped-layers-store.md       | 9 ++++-----
 .../architecture/2026-07-12-scoped-layers-store.zh.md    | 9 ++++-----
 3 files changed, 10 insertions(+), 12 deletions(-)

diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml
index bf5027e5ec..c12497f016 100644
--- a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml
+++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-12-scoped-layers-store.md: 510f462344b25b72bb8604d88f125cc92c6510b1
-2026-07-12-scoped-layers-store.zh.md: abc2aad140cc10325392ed8800e33e38684511a8
+2026-07-12-scoped-layers-store.md: f2056446abb3b8d0793b6ef7898c01001ccf0460
+2026-07-12-scoped-layers-store.zh.md: 9726eb3de953af1086d8bcdd779fc02b3c324596
diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md
index 510f462344..f2056446ab 100644
--- a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md
+++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md
@@ -21,13 +21,13 @@ Finally, one agent's contribution to one service is scattered across several map
 
 `dsh-scope` gains a key-agnostic `store.ts`, with Cordis as its only peer dependency. The module implements the smallest abstraction shared by the six current sites: **business state and validation stay in an explicit layer class; one helper owns layer selection, effect attachment, rollback, notification, and reclamation**. One helper instance belongs to one service, and one layer instance aggregates everything a scope contributes to that service.
 
-- **`ScopedLayers<L>`** is a concrete scheduler, not a base class. It owns the global layer plus one `Map<ScopeKey, L>`, constructs scoped layers on demand through an explicit factory, and reclaims a layer when `isEmpty()`. Its `effect(ctx, action, options?)` accepts one synchronous action that returns one synchronous undo because that is the complete shape of all six current sites. The single `ctx` decides both the visible layer (`scopeOf(ctx)`) and the owning Cordis fiber (`ctx.effect`), so "visible to X, disposed with Y" stays unrepresentable. The helper yields the undo before notifying listeners, returns Cordis's exact disposer, and reclaims a newly created empty layer if validation or mutation throws. Reads are `global`/`peek` plus `merge` (named entries with scoped shadowing and an optional global-admission predicate), `values` (global then scoped concatenation without shadowing), `keys` (the pre-restriction name universe), and `some` (cross-layer invariant checks).
+- **`ScopedLayers<L>`** is a concrete scheduler, not a base class. It owns the global layer plus one `Map<ScopeKey, L>`, constructs scoped layers on demand through an explicit factory, and reclaims a layer when `isEmpty()`. Its `effect(ctx, action, options?)` accepts one synchronous action that returns one synchronous undo because that is the complete shape of all six current sites. The single `ctx` decides both the visible layer (`scopeOf(ctx)`) and the owning Cordis fiber (`ctx.effect`), so "visible to X, disposed with Y" stays unrepresentable. The helper yields the undo before notifying listeners, returns Cordis's exact disposer, and reclaims a newly created empty layer if validation or mutation throws. Reads are `global`/`peek` plus `merge` (named entries with scoped shadowing and an optional global-admission predicate), `values` (global then scoped concatenation without shadowing), and `keys` (the pre-restriction name universe).
 - **Explicit `ScopeLayer` classes** make each service's state visible to readers. `ToolLayer` and `PromptLayer` declare their three table properties and their `isEmpty()` aggregation directly; a small layer factory receives only the scope, while its closure may capture real constructor dependencies. Domain methods stay ordinary class methods. This costs a few repetitive declarations but avoids a mapped-type class factory, a scheduler/layer ownership cycle, reserved property names, and generated runtime structure.
 - **`NamedEntries<V>` and `AnonymousEntries<V>`** are the two shared insertion-ordered tables. Named entries expose `insert`/lookup and retain the current global/scoped duplicate wording through domain `kind` and per-agent-alternative labels; anonymous entries expose only `append`, using process-unique symbol keys for O(1) undo removal. Keeping the classes separate makes meaningless mixed named/anonymous operations unrepresentable and keeps key types sound. Their iterators borrow membership and typed contribution values; they do not clone or freeze values. `ScopedLayers` materializes only the merged arrays/maps already required by the service read paths.
 
-`dsh-tools` migrates its three tables into one `ToolLayer`: tools, compiled restrictions, and guards. The layer owns restriction admission and guard evaluation; the facade retains domain validation that needs service configuration, such as the reserved `run_code` name and the current known-global-name universe. Readonly allow/deny inputs are compiled once into internal sets. `dsh-system-prompt` likewise migrates sections, tool providers, and variables into one `PromptLayer`; its facade performs owner-final cross-layer checks through `layers.some`. Every registration facade performs its public argument validation and then makes one `effect` call with a label and, for guards, `silent: true`. A generic helper does not learn domain rules such as "restrictions require a scoped context."
+`dsh-tools` migrates its three tables into one `ToolLayer`: tools, compiled restrictions, and guards. The layer owns restriction admission and guard evaluation; the facade retains domain validation that needs service configuration, such as the reserved `run_code` name and the current known-global-name universe. Readonly allow/deny inputs are compiled once into internal sets. `dsh-system-prompt` likewise migrates sections, tool providers, and variables into one `PromptLayer`. Every registration facade performs its public argument validation and then makes one `effect` call with a label and, for guards, `silent: true`. A generic helper does not learn domain rules such as "restrictions require a scoped context."
 
-`assemble` stays in the `SystemPrompt` facade for three reasons: the subject scope's layer may not exist and reads must not create it; shadowing requires merge-before-evaluate so a hidden section provider is never called; and the assembly waterfall, `toolOrder`, and owner-final restoration use service-level resources. Sections and tool providers keep their current materialized derived views. Variable providers instead iterate the global and scoped `NamedEntries` directly, preserving today's live Map behavior when a provider registers another variable during assembly. Tool guards likewise iterate their `AnonymousEntries` directly. Owner-final remains metadata on section and tool contributions, not a second protection registry.
+`assemble` stays in the `SystemPrompt` facade for three reasons: the subject scope's layer may not exist and reads must not create it; shadowing requires merge-before-evaluate so a hidden section provider is never called; and the assembly waterfall and `toolOrder` use service-level resources. Sections and tool providers keep their current materialized derived views. Variable providers instead iterate the global and scoped `NamedEntries` directly, preserving today's live Map behavior when a provider registers another variable during assembly. Tool guards likewise iterate their `AnonymousEntries` directly.
 
 Migration preserves public behavior and exact duplicate messages. The internal aggregate layer is reclaimed only after all three tables empty rather than when one table empties; no service API exposes layer identity. Direct live iteration retains current re-entrant variable-provider and guard behavior, while selector helpers continue to materialize the same section, tool-provider, and tool-resolution views their facades build today.
 
@@ -47,7 +47,6 @@ export class ScopedLayers<L extends ScopeLayer> {
   merge<T>(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries<T>, admitGlobal?: (name: string) => boolean): Map<string, T>
   values<T>(scope: ScopeKey | undefined, pick: (layer: L) => EntryValues<T>): T[]
   keys<T>(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries<T>): string[]
-  some(fn: (layer: L, scope: ScopeKey | undefined) => boolean): boolean
   effect(ctx: Context, action: (layer: L) => () => void, options: { label: string; silent?: boolean }): () => void
 }
 
@@ -133,7 +132,7 @@ class ToolRegistry extends Service {
 
 ## Acceptance criteria
 
-- `store.ts` ships in `dsh-scope` (peer dependencies unchanged: Cordis only; module-graph position unchanged) with per-file 100% coverage of layer selection and reclamation, synchronous action/undo ordering, throwing-action cleanup, throwing-change-listener rollback, exact disposer identity, `label`/`silent`, factory typing, cross-layer `some`, merge selectors, and separate named/anonymous entry semantics. Its five public symbols are re-exported from the package root and carry export JSDoc.
+- `store.ts` ships in `dsh-scope` (peer dependencies unchanged: Cordis only; module-graph position unchanged) with per-file 100% coverage of layer selection and reclamation, synchronous action/undo ordering, throwing-action cleanup, throwing-change-listener rollback, exact disposer identity, `label`/`silent`, factory typing, merge selectors, and separate named/anonymous entry semantics. Its five public symbols are re-exported from the package root and carry export JSDoc.
 - `dsh-tools` and `dsh-system-prompt` each collapse to one `ScopedLayers`; every registration facade validates its domain contract and then makes one `effect` call, and all keep returning the exact Cordis effect disposer.
 - Existing behavior, duplicate messages, validation order, live variable-provider re-entrancy, and live guard re-entrancy remain unchanged. Tests additionally pin aggregate reclamation timing and selector materialization.
 - Documentation lands in the same change: `dsh-scope`/`dsh-tools`/`dsh-system-prompt` READMEs; on implementation this RFC moves to `implemented/` and the [runtime-design RFC](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)'s registration section is updated in place.
diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md
index abc2aad140..9726eb3de9 100644
--- a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md
+++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md
@@ -21,13 +21,13 @@ agent 作用域落地之后（[agent-scope RFC](../../implemented/architecture/2
 
 `dsh-scope` 新增与键类型无关的 `store.ts`，peer 依赖仍只有 Cordis。模块只抽取六个现有登记口已经共同证明的最小形状：**业务状态与校验留在显式层类里；一个 helper 统一负责选层、挂 effect、回滚、通知与回收**。一个 helper 实例属于一个服务；一个层实例聚合某 scope 对该服务的全部贡献。
 
-- **`ScopedLayers<L>`** 是具体调度器，不作基类。它持有全局层与一张 `Map<ScopeKey, L>`，通过显式工厂按需构造专属层，并在层 `isEmpty()` 时回收。`effect(ctx, action, options?)` 只接受一个同步 action，action 只返回一个同步 undo，因为六个现有登记口的完整形状就是如此。单一 `ctx` 同时决定可见层（`scopeOf(ctx)`）与属主 Cordis fiber（`ctx.effect`），「对 X 可见、随 Y 销毁」因此不可表达。helper 在通知监听器前 yield undo，返回 Cordis 的原始 disposer，并在校验或变更抛错时回收刚建出的空层。读取接口是 `global`/`peek`，以及 `merge`（命名条目的专属遮蔽与可选全局放行谓词）、`values`（不遮蔽地依次拼接全局与专属条目）、`keys`（限制前名字全集）和 `some`（跨层不变量检查）。
+- **`ScopedLayers<L>`** 是具体调度器，不作基类。它持有全局层与一张 `Map<ScopeKey, L>`，通过显式工厂按需构造专属层，并在层 `isEmpty()` 时回收。`effect(ctx, action, options?)` 只接受一个同步 action，action 只返回一个同步 undo，因为六个现有登记口的完整形状就是如此。单一 `ctx` 同时决定可见层（`scopeOf(ctx)`）与属主 Cordis fiber（`ctx.effect`），「对 X 可见、随 Y 销毁」因此不可表达。helper 在通知监听器前 yield undo，返回 Cordis 的原始 disposer，并在校验或变更抛错时回收刚建出的空层。读取接口是 `global`/`peek`，以及 `merge`（命名条目的专属遮蔽与可选全局放行谓词）、`values`（不遮蔽地依次拼接全局与专属条目）和 `keys`（限制前名字全集）。
 - **显式 `ScopeLayer` 类**让每个服务的状态一眼可见。`ToolLayer` 与 `PromptLayer` 直接声明各自三项表属性与 `isEmpty()` 聚合；一个小工厂只向构造器传入 scope，闭包仍可捕获真实构造依赖。领域方法仍是普通类方法。代价是几行重复声明，收益是不用引入 mapped-type 类工厂、scheduler/layer 属主环、保留属性名和生成式运行时结构。
 - **`NamedEntries<V>` 与 `AnonymousEntries<V>`** 是两种共用的保插入序条目表。命名表暴露 `insert`/查询，并通过领域 `kind` 与 per-agent alternative 标签保持现有全局/专属重名文案；匿名表只暴露 `append`，以进程内唯一 symbol 作键支持 O(1) 撤销删除。分成两类以后，无意义的命名/匿名混用不可表达，key 类型也保持健全。迭代器借用表成员与带类型的贡献值，不会 clone 或 freeze 值；`ScopedLayers` 只物化服务读路径本来就需要的合并数组或 Map。
 
-`dsh-tools` 把工具、已编译 restriction 与 guard 三张表合并进一个 `ToolLayer`。restriction 放行判断与 guard 求值归层所有；`run_code` 保留名、当前已知全局名集合等依赖服务配置的领域校验仍留在门面。只读 allow/deny 输入只编译一次，成为内部 Set。`dsh-system-prompt` 同样把 section、tool provider 与 variable 合并进一个 `PromptLayer`；门面通过 `layers.some` 完成 owner-final 跨层冲突检查。每个登记门面先完成公开参数校验，再以 label 做一次 `effect` 调用；guard 额外传 `silent: true`。通用 helper 不理解「restriction 必须由 scoped context 调用」之类领域规则。
+`dsh-tools` 把工具、已编译 restriction 与 guard 三张表合并进一个 `ToolLayer`。restriction 放行判断与 guard 求值归层所有；`run_code` 保留名、当前已知全局名集合等依赖服务配置的领域校验仍留在门面。只读 allow/deny 输入只编译一次，成为内部 Set。`dsh-system-prompt` 同样把 section、tool provider 与 variable 合并进一个 `PromptLayer`。每个登记门面先完成公开参数校验，再以 label 做一次 `effect` 调用；guard 额外传 `silent: true`。通用 helper 不理解「restriction 必须由 scoped context 调用」之类领域规则。
 
-`assemble` 留在 `SystemPrompt` 门面，三条理由：主体 scope 的层可能不存在，读路径不得创建它；遮蔽语义要求先合并再求值，被遮蔽的 section provider 绝不能被调用；组装 waterfall、`toolOrder` 与 owner-final 恢复使用服务级资源。section 与 tool provider 保持既有的派生视图物化；variable provider 则直接遍历全局与专属 `NamedEntries`，保留 provider 在组装期间登记另一 variable 时的现有活 Map 行为。tool guard 同样直接遍历其 `AnonymousEntries`。owner-final 仍是 section 与 tool 贡献上的元数据，不是第二张 protection 注册表。
+`assemble` 留在 `SystemPrompt` 门面，三条理由：主体 scope 的层可能不存在，读路径不得创建它；遮蔽语义要求先合并再求值，被遮蔽的 section provider 绝不能被调用；组装 waterfall 与 `toolOrder` 使用服务级资源。section 与 tool provider 保持既有的派生视图物化；variable provider 则直接遍历全局与专属 `NamedEntries`，保留 provider 在组装期间登记另一 variable 时的现有活 Map 行为。tool guard 同样直接遍历其 `AnonymousEntries`。
 
 迁移保持公开行为与精确重名文案不变。内部聚合层会在三张表全部清空后才回收，而不是某一张表清空时回收；服务 API 不暴露层身份。直接活遍历保留现有 variable-provider 与 guard 重入行为，selector helper 则继续物化门面今天已经在构造的 section、tool-provider 与工具解析视图。
 
@@ -47,7 +47,6 @@ export class ScopedLayers<L extends ScopeLayer> {
   merge<T>(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries<T>, admitGlobal?: (name: string) => boolean): Map<string, T>
   values<T>(scope: ScopeKey | undefined, pick: (layer: L) => EntryValues<T>): T[]
   keys<T>(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries<T>): string[]
-  some(fn: (layer: L, scope: ScopeKey | undefined) => boolean): boolean
   effect(ctx: Context, action: (layer: L) => () => void, options: { label: string; silent?: boolean }): () => void
 }
 
@@ -133,7 +132,7 @@ class ToolRegistry extends Service {
 
 ## 验收标准
 
-- `store.ts` 落在 `dsh-scope`（peer 依赖不变：仅 Cordis；模块图位置不变），逐文件 100% 覆盖选层与回收、同步 action/undo 顺序、action 抛错清理、change 监听器抛错回滚、原始 disposer 身份、`label`/`silent`、工厂类型、跨层 `some`、合并 selector，以及分开的命名/匿名条目语义。五个公开符号从 package 根重导出并带 export JSDoc。
+- `store.ts` 落在 `dsh-scope`（peer 依赖不变：仅 Cordis；模块图位置不变），逐文件 100% 覆盖选层与回收、同步 action/undo 顺序、action 抛错清理、change 监听器抛错回滚、原始 disposer 身份、`label`/`silent`、工厂类型、合并 selector，以及分开的命名/匿名条目语义。五个公开符号从 package 根重导出并带 export JSDoc。
 - `dsh-tools` 与 `dsh-system-prompt` 各收敛为一个 `ScopedLayers`；每个登记门面先校验领域契约再做一次 `effect` 调用，并继续返回 Cordis effect 的原始 disposer。
 - 既有行为、重名文案、校验顺序、variable-provider 活重入与 guard 活重入不变。测试另行钉住聚合回收时机与 selector 物化。
 - 文档随同一变更落地：`dsh-scope`/`dsh-tools`/`dsh-system-prompt` 的 README；实现后本 RFC 移入 `implemented/`，并就地更新[运行时设计 RFC](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md) 的注册章节。

From e15a6168d2c8d69ae004feff822c89b2adc78c36 Mon Sep 17 00:00:00 2001
From: Huanqi Cao <caohuanqi@deepseek.com>
Date: Sun, 5 Jul 2026 04:31:22 +0800
Subject: [PATCH 05/74] Support durable JSONL persistence on Windows

---
 docs/rfc/INDEX.md                             |   1 +
 ...026-07-05-windows-jsonl-durable-publish.md |  33 ++++
 .../session-persistence-jsonl/README.md       |   4 +-
 .../session-persistence-jsonl/package.json    |   1 +
 .../session-persistence-jsonl/src/index.ts    | 128 +++++++++----
 .../session-persistence-jsonl/src/win32.ts    | 150 ++++++++++++++++
 .../tests/jsonl.spec.ts                       |  39 ++++
 .../tests/win32.spec.ts                       | 168 ++++++++++++++++++
 pnpm-lock.yaml                                | 144 +++++++++++++++
 pnpm-workspace.yaml                           |   2 +
 10 files changed, 636 insertions(+), 34 deletions(-)
 create mode 100644 docs/rfc/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md
 create mode 100644 packages/session-persistence/session-persistence-jsonl/src/win32.ts
 create mode 100644 packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts

diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md
index ab39d4f314..32f11b744a 100644
--- a/docs/rfc/INDEX.md
+++ b/docs/rfc/INDEX.md
@@ -150,6 +150,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [Prompt variables and tool-guidance ownership](implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md) | 2026-07-05 |
 | [Every LLM request is reconstructable from the session log](implemented/architecture/2026-07-05-reconstructable-requests.md) | 2026-07-05 |
 | [Subagent provider-lifecycle events — `subagent/provider-added` / `subagent/provider-removed`](implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.md) | 2026-07-05 |
+| [Windows-native durable JSONL publication](implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md) | 2026-07-05 |
 | [A shared timeout/deadline primitive, with hard-kill left to each capability](implemented/architecture/2026-07-06-timeout-deadline-library.md) | 2026-07-06 |
 | [Tool result retention library](implemented/architecture/2026-07-06-tool-result-retention-library.md) | 2026-07-06 |
 | [Tool-call timeout policy as a plugin](implemented/architecture/2026-07-07-tool-call-timeout-policy.md) | 2026-07-07 |
diff --git a/docs/rfc/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md b/docs/rfc/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md
new file mode 100644
index 0000000000..909f75132f
--- /dev/null
+++ b/docs/rfc/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md
@@ -0,0 +1,33 @@
+# RFC: Windows-native durable JSONL publication
+
+Status: implemented
+
+## Problem
+
+`dsh-session-persistence-jsonl` publishes a session log lazily on the first append. The POSIX protocol writes a temp file, fsyncs it, links it to the final name, fsyncs the parent directory, and then removes the temp link. The parent-directory fsync is part of the durability contract: a crash after the namespace change must not lose the committed final name while leaving callers believing the session log materialized.
+
+Windows has atomic namespace operations, but Node does not expose a POSIX-equivalent parent-directory fsync contract there. Treating Windows directory sync failures as success would silently weaken a durable backend. The Windows path therefore needs a different publication primitive rather than a conditional inside the POSIX `syncDir` helper.
+
+## Decision
+
+The JSONL backend forks inside `materialize()` before any namespace mutation. Shared code computes the session directory, final log path, and initial JSONL bytes; POSIX and Windows then run separate publication protocols.
+
+POSIX keeps the existing protocol: create the root and cwd bucket with parent directory fsyncs, write and fsync a temp file, publish with `link()` so an existing final log is never overwritten, fsync the bucket directory, then remove the redundant temp hard link.
+
+Windows creates missing directories through a durable staging publish: create a random sibling directory, then publish it to the final directory name with `MoveFileExW(..., MOVEFILE_WRITE_THROUGH)` without `MOVEFILE_REPLACE_EXISTING` or `MOVEFILE_COPY_ALLOWED`. File materialization writes and fsyncs the temp log, then publishes that temp file to the final path with the same write-through `MoveFileExW` call and no replacement. `koffi` is the minimal Win32 bridge for this API surface; its install script is allowed in `pnpm-workspace.yaml` because the package ships the native loader and prebuilt platform modules.
+
+## Alternatives considered
+
+**Ignore Windows directory-sync failures.** Rejected because it reports a first append as durable without forcing the published namespace entry to stable storage.
+
+**Use `CreateHardLinkW`.** Rejected because hard links are filesystem-dependent, do not publish directories, and expose no write-through option.
+
+**Use replacement or transactional APIs.** `ReplaceFileW` has replacement semantics that conflict with same-id collision rejection, and Transactional NTFS is not recommended for new application designs.
+
+## Consequences
+
+The backend keeps one external contract across platforms: first append either publishes a complete log at the final name or fails without overwriting an existing log. The platform split is an implementation detail; `SessionPersistence` APIs and on-disk JSONL format do not change.
+
+Windows tests exercise the real Win32 publish path on native Windows. Power-loss behavior remains an API-contract property rather than something unit tests can prove; the testable invariants are that directory fsync is not called on Windows materialization, final-path collisions fail, temp logs are fsync'd before publication, and the resulting log loads normally.
+
+Append and repair still use ordinary file-handle fsyncs on both platforms. A failed append closes its append-only handle, reopens the log read/write, truncates it to the pre-append size, and fsyncs the rollback because Windows rejects `ftruncate` on append-only handles.
diff --git a/packages/session-persistence/session-persistence-jsonl/README.md b/packages/session-persistence/session-persistence-jsonl/README.md
index 43f4443107..097ad04b67 100644
--- a/packages/session-persistence/session-persistence-jsonl/README.md
+++ b/packages/session-persistence/session-persistence-jsonl/README.md
@@ -23,7 +23,7 @@ The JSONL durable session-persistence backend — a concrete `SessionPersistence
 
 ## Durability and crash semantics
 
-- **Lazy materialization.** `create(meta)` writes nothing; on the first `append`, the backend writes and `fsync`s a temporary file, publishes it without overwrite via a hard link, then `fsync`s the directory. A created-but-never-appended session leaves nothing on disk and is absent from `list`.
+- **Lazy materialization.** `create(meta)` writes nothing; the `.jsonl` (header + first batch) is written atomically on the first `append`: POSIX uses temp-write + file `fsync` + `link` + parent-directory `fsync`; Windows uses temp-write + file `fsync` + `MoveFileExW(..., MOVEFILE_WRITE_THROUGH)` and creates missing directories through the same write-through publish pattern. A created-but-never-appended session leaves nothing on disk and is absent from `list`.
 - **Append-only.** Committed events (at or below a flushed `turn/end`) are never rewritten. Subsequent appends are line appends at EOF + `fsync`.
 - **Crash recovery — preserve valid tail work.** `load` keeps the contiguous valid prefix of an interrupted final turn. It truncates from the first unparsable or sequence-gapped uncommitted record, then appends the synthetic tool, step, and turn closers required by the shared [persistence contract](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md); the same defect at or before the last committed `turn/end` rejects.
 - **Contiguous-seq.** `append` rejects a batch whose first `seq` does not continue the stored log, and rejects non-JSON-serializable `event.data` naming the offending event type.
@@ -45,4 +45,4 @@ The plugin buffers frozen session events and drains them on flush or disposal. A
 - **Only the current `SESSION_FORMAT_VERSION` (v0) loads** — the on-disk format is pre-release/unstable: a breaking format change is absorbed at v0 and non-current logs are rejected; there is no migration.
 - **Nothing deletes session files** — logs accumulate under `root` until removed externally (the seam has no deletion surface).
 - **Single-process assumption** — per-session serialization and the write cursor live in this process; two processes appending to the same `root` are not coordinated.
-- **Initial materialization requires hard-link support** — first append uses `link()` so same-id races fail instead of overwriting a committed log; a filesystem that cannot create hard links cannot host this backend.
+- **POSIX materialization requires hard-link support** — its first append uses `link()` so same-id races fail instead of overwriting a committed log; Windows uses write-through rename without replacement.
diff --git a/packages/session-persistence/session-persistence-jsonl/package.json b/packages/session-persistence/session-persistence-jsonl/package.json
index ddb9f2af4d..2644e14efc 100644
--- a/packages/session-persistence/session-persistence-jsonl/package.json
+++ b/packages/session-persistence/session-persistence-jsonl/package.json
@@ -27,6 +27,7 @@
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
+    "koffi": "^3.1.0",
     "schemastery": "^3.18.0"
   },
   "devDependencies": {
diff --git a/packages/session-persistence/session-persistence-jsonl/src/index.ts b/packages/session-persistence/session-persistence-jsonl/src/index.ts
index 0c8a2ee3ef..ac1c07860e 100644
--- a/packages/session-persistence/session-persistence-jsonl/src/index.ts
+++ b/packages/session-persistence/session-persistence-jsonl/src/index.ts
@@ -19,6 +19,7 @@ import type { SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-se
 import {
   encodeSegment, eventLine, logPath, parseHeaderMeta, scanLog, sessionDir, toHeaderLine,
 } from './format.ts'
+import { ensureDurableDirectoryWin32, publishNewFileWin32 } from './win32.ts'
 
 /** Plugin config: where the JSONL backend keeps its session logs (`root` is required — no default). */
 export interface Config {
@@ -160,33 +161,35 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
 
   // --- materialization / append / repair (file mechanics) ---
 
-  /** Atomically write the header line + first batch (temp-write, fsync, collision-safe hard-link publish). */
+  /** Atomically write the header line + first batch (temp-write, fsync, publish). */
   private async materialize(meta: SessionHeader, events: readonly SessionEvent[]): Promise<void> {
     const dir = sessionDir(this.root, meta.cwd)
-    await mkdir(this.root, { recursive: true, mode: 0o700 })
-    await this.syncDir(dirname(this.root))
-    await mkdir(dir, { recursive: true, mode: 0o700 })
-    await this.syncDir(this.root)
     const finalPath = logPath(this.root, meta.cwd, meta.id)
-    // Materialization is the first write; an existing log is an id collision.
-    /* v8 ignore next 3 -- createCore guards collisions before materialize; this is a TOCTOU backstop */
-    if (await this.exists(finalPath)) {
-      throw new Error(`refusing to materialize "${meta.id}": a log already exists on disk (load/resume it instead)`)
+    const content = this.initialLogContent(meta, events)
+    /* v8 ignore next -- native Windows coverage exercises this platform dispatch; Linux covers the POSIX peer */
+    if (process.platform === 'win32') {
+      await this.materializeWin32(dir, finalPath, meta.id, content)
+    } else {
+      await this.materializePosix(dir, finalPath, meta.id, content)
     }
+  }
+
+  private initialLogContent(meta: SessionHeader, events: readonly SessionEvent[]): string {
     const header = JSON.stringify(toHeaderLine(meta))
     const body = events.map(eventLine).join('\n')
-    const content = header + '\n' + body + '\n'
+    return header + '\n' + body + '\n'
+  }
 
-    const tmp = `${finalPath}.${randomBytes(6).toString('hex')}.tmp`
-    const handle = await open(tmp, 'wx', 0o600)
-    try {
-      await handle.writeFile(content)
-      await handle.sync()
-    } finally {
-      await handle.close()
-    }
-    // Publish with link()+unlink(): unlike rename(), link fails if another
-    // process materialized the same id first.
+  private async materializePosix(dir: string, finalPath: string, id: SessionId, content: string): Promise<void> {
+    await mkdir(this.root, { recursive: true, mode: 0o700 })
+    await this.syncDirPosix(dirname(this.root))
+    await mkdir(dir, { recursive: true, mode: 0o700 })
+    await this.syncDirPosix(this.root)
+    await this.rejectExistingLog(finalPath, id)
+    const tmp = await this.writeSyncedTempFile(finalPath, content)
+    // Publish via link()+unlink(), NOT rename(): link fails with EEXIST if the
+    // final path already exists, so two processes materializing the same id
+    // concurrently cannot clobber each other. rename() would silently overwrite.
     let linked = false
     try {
       await link(tmp, finalPath)
@@ -197,10 +200,13 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
       /* v8 ignore next -- link failure is the TOCTOU/IO race guarded above; not reachable in test */
       if (!linked) await rm(tmp, { force: true })
     }
-    // The published link becomes crash-durable only after its directory fsync.
-    await this.syncDir(dir)
-    // Best-effort temp cleanup: the log is already published and durable, so a failure to
-    // remove the (now-redundant) temp hard link must not reject the append.
+    // link() succeeded — the log is published. fsync the directory so the new
+    // entry survives a power loss: the new link is not crash-durable until the
+    // parent directory's metadata is synced.
+    await this.syncDirPosix(dir)
+    // Best-effort temp cleanup: the log is already published and durable, so a
+    // failure to remove the (now-redundant) temp hard link must NOT reject the
+    // append. Swallow only the rm failure; nothing else of consequence runs here.
     try {
       await rm(tmp, { force: true })
     } catch {
@@ -208,8 +214,47 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
     }
   }
 
-  /** fsync a directory so a just-created or published entry inside it is crash-durable. */
-  private async syncDir(dir: string): Promise<void> {
+  /* v8 ignore start -- native Windows coverage exercises this integration path */
+  private async materializeWin32(dir: string, finalPath: string, id: SessionId, content: string): Promise<void> {
+    await ensureDurableDirectoryWin32(this.root)
+    await ensureDurableDirectoryWin32(dir)
+    await this.rejectExistingLog(finalPath, id)
+    const tmp = await this.writeSyncedTempFile(finalPath, content)
+    try {
+      await publishNewFileWin32(tmp, finalPath)
+    } catch (error) {
+      await rm(tmp, { force: true })
+      throw error
+    }
+  }
+  /* v8 ignore stop */
+
+  private async rejectExistingLog(finalPath: string, id: SessionId): Promise<void> {
+    // Never publish over an existing committed log: materialize is the FIRST
+    // write of a session the backend believes is new. A file here means a
+    // different session shares this id on disk — reject loudly. (createCore
+    // already guards the create path, so this is unreachable-in-practice TOCTOU
+    // defense.)
+    /* v8 ignore next 3 -- createCore guards collisions before materialize; this is a TOCTOU backstop */
+    if (await this.exists(finalPath)) {
+      throw new Error(`refusing to materialize "${id}": a log already exists on disk (load/resume it instead)`)
+    }
+  }
+
+  private async writeSyncedTempFile(finalPath: string, content: string): Promise<string> {
+    const tmp = `${finalPath}.${randomBytes(6).toString('hex')}.tmp`
+    const handle = await open(tmp, 'wx', 0o600)
+    try {
+      await handle.writeFile(content)
+      await handle.sync()
+    } finally {
+      await handle.close()
+    }
+    return tmp
+  }
+
+  /** fsync a POSIX directory so a just-created/renamed entry is crash-durable. */
+  private async syncDirPosix(dir: string): Promise<void> {
     const handle = await open(dir, 'r')
     try {
       await handle.sync()
@@ -226,17 +271,37 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
   private async appendLines(meta: SessionHeader, events: readonly SessionEvent[]): Promise<void> {
     const path = logPath(this.root, meta.cwd, meta.id)
     const handle = await open(path, 'a')
+    let closed = false
+    const closeAppendHandle = async (): Promise<void> => {
+      if (closed) return
+      closed = true
+      await handle.close()
+    }
+
     try {
       const { size: before } = await handle.stat()
       try {
         await handle.writeFile(events.map(eventLine).join('\n') + '\n')
         await handle.sync()
       } catch (error) {
-        // Roll back whatever bytes landed so a retry starts from a clean EOF.
-        await handle.truncate(before)
-        await handle.sync()
+        try {
+          await closeAppendHandle()
+          await this.rollbackAppend(path, before)
+        } catch (rollbackError) {
+          throw new AggregateError([error, rollbackError], `failed to roll back append to "${path}"`)
+        }
         throw error
       }
+    } finally {
+      await closeAppendHandle()
+    }
+  }
+
+  private async rollbackAppend(path: string, size: number): Promise<void> {
+    const handle = await open(path, 'r+')
+    try {
+      await handle.truncate(size)
+      await handle.sync()
     } finally {
       await handle.close()
     }
@@ -322,9 +387,8 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
       await handle.close()
       return true
     } catch (error) {
-      // Only ENOENT means absent. A permission/I/O error must surface, not be
-      // collapsed to `false` — otherwise load() reports "not found" and collision
-      // checks proceed under a false absence assumption.
+      // Only ENOENT means absent. A permission/I/O error must surface rather
+      // than letting load or collision checks proceed under false absence.
       if (isENOENT(error)) return false
       throw error
     }
diff --git a/packages/session-persistence/session-persistence-jsonl/src/win32.ts b/packages/session-persistence/session-persistence-jsonl/src/win32.ts
new file mode 100644
index 0000000000..143f230ea3
--- /dev/null
+++ b/packages/session-persistence/session-persistence-jsonl/src/win32.ts
@@ -0,0 +1,150 @@
+/**
+ * Windows durable namespace helpers for the JSONL backend.
+ *
+ * POSIX publishes a newly-created log by creating a directory entry and then
+ * fsyncing the parent directory. Windows does not expose that parent-directory
+ * fsync contract through Node, so the Windows path uses the native durable
+ * namespace primitive instead: create a staging object in the target directory
+ * and publish it with `MoveFileExW(..., MOVEFILE_WRITE_THROUGH)` without
+ * replacement or cross-volume copy fallback.
+ *
+ * @module dsh-session-persistence-jsonl/win32
+ */
+
+import { mkdtemp, rm, stat } from 'node:fs/promises'
+import { basename, join, parse, resolve, toNamespacedPath } from 'node:path'
+
+type MoveFileExW = (existing: string, replacement: string, flags: number) => boolean
+type GetLastError = () => number
+
+interface Win32Bindings {
+  moveFileExW: MoveFileExW
+  getLastError: GetLastError
+}
+
+interface Win32ErrnoException extends NodeJS.ErrnoException {
+  win32Code: number
+  dest: string
+}
+
+const MOVEFILE_WRITE_THROUGH = 0x00000008
+const ERROR_FILE_NOT_FOUND = 2
+const ERROR_PATH_NOT_FOUND = 3
+const ERROR_ACCESS_DENIED = 5
+const ERROR_NOT_SAME_DEVICE = 17
+const ERROR_FILE_EXISTS = 80
+const ERROR_INVALID_NAME = 123
+const ERROR_ALREADY_EXISTS = 183
+
+let bindings: Win32Bindings | undefined
+
+/** Load the small Win32 surface lazily so non-Windows processes never load Koffi. */
+async function win32(): Promise<Win32Bindings> {
+  if (bindings !== undefined) return bindings
+  const koffi = (await import('koffi')).default
+  const kernel32 = koffi.load('kernel32.dll')
+  bindings = {
+    moveFileExW: kernel32.func('__stdcall', 'MoveFileExW', 'bool', ['str16', 'str16', 'uint']) as MoveFileExW,
+    getLastError: kernel32.func('__stdcall', 'GetLastError', 'uint', []) as GetLastError,
+  }
+  return bindings
+}
+
+function errnoCode(win32Code: number): string {
+  switch (win32Code) {
+    case ERROR_FILE_NOT_FOUND:
+    case ERROR_PATH_NOT_FOUND:
+      return 'ENOENT'
+    case ERROR_ACCESS_DENIED:
+      return 'EACCES'
+    case ERROR_NOT_SAME_DEVICE:
+      return 'EXDEV'
+    case ERROR_FILE_EXISTS:
+    case ERROR_ALREADY_EXISTS:
+      return 'EEXIST'
+    case ERROR_INVALID_NAME:
+      return 'EINVAL'
+    default:
+      return 'EIO'
+  }
+}
+
+function win32Error(syscall: string, win32Code: number, path: string, dest: string): Win32ErrnoException {
+  const code = errnoCode(win32Code)
+  const error = new Error(`${syscall} ${code} (Win32 ${win32Code}): ${path} -> ${dest}`) as Win32ErrnoException
+  error.code = code
+  error.errno = win32Code
+  error.syscall = syscall
+  error.path = path
+  error.dest = dest
+  error.win32Code = win32Code
+  return error
+}
+
+function isENOENT(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException | null)?.code === 'ENOENT'
+}
+
+function isEEXIST(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException | null)?.code === 'EEXIST'
+}
+
+async function assertDirectory(path: string): Promise<boolean> {
+  try {
+    const info = await stat(path)
+    if (info.isDirectory()) return true
+    const error = new Error(`path exists but is not a directory: ${path}`) as NodeJS.ErrnoException
+    error.code = 'ENOTDIR'
+    error.path = path
+    throw error
+  } catch (error) {
+    if (isENOENT(error)) return false
+    throw error
+  }
+}
+
+/**
+ * Publish `existing` at `replacement` with Windows write-through rename
+ * semantics. The destination must not already exist; the move must stay within
+ * the volume (no copy fallback flag is set).
+ * @param existing - the synced staging path to move.
+ * @param replacement - the final path, which must not already exist.
+ */
+export async function publishNewFileWin32(existing: string, replacement: string): Promise<void> {
+  const api = await win32()
+  const ok = api.moveFileExW(toNamespacedPath(existing), toNamespacedPath(replacement), MOVEFILE_WRITE_THROUGH)
+  if (!ok) throw win32Error('MoveFileExW', api.getLastError(), existing, replacement)
+}
+
+/**
+ * Create `target` and its missing ancestors with durable Windows namespace
+ * publication. Each missing directory is first created as a random staging
+ * sibling, then moved to its final name with `MOVEFILE_WRITE_THROUGH`; races
+ * with another creator are accepted only after verifying the winner is a
+ * directory.
+ * @param target - the absolute directory path to create durably when absent.
+ */
+export async function ensureDurableDirectoryWin32(target: string): Promise<void> {
+  const absolute = resolve(target)
+  const root = parse(absolute).root
+  await assertDirectory(root)
+
+  const segments = absolute.slice(root.length).split(/[\\/]+/).filter(part => part.length > 0)
+  let current = root
+  for (const segment of segments) {
+    const next = join(current, segment)
+    if (!await assertDirectory(next)) await createLeafDirectoryWin32(current, next)
+    current = next
+  }
+}
+
+async function createLeafDirectoryWin32(parent: string, target: string): Promise<void> {
+  const staging = await mkdtemp(join(parent, `.dsh-mkdir-${basename(target)}-`))
+  try {
+    await publishNewFileWin32(staging, target)
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true })
+    if (isEEXIST(error) && await assertDirectory(target)) return
+    throw error
+  }
+}
diff --git a/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts
index 4b279e3c6e..e7a65d3c8f 100644
--- a/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts
+++ b/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts
@@ -336,6 +336,45 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => {
     expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
   })
 
+  it('reports both the append failure and a failed rollback', async () => {
+    const m = meta('rollback-failure')
+    await ctx.sessionPersistence.create(m)
+    await ctx.sessionPersistence.append(m.id, oneTurnLog())
+
+    const path = logPath(root, undefined, m.id)
+    const handle = await (await import('node:fs/promises')).open(path, 'r')
+    const proto = Object.getPrototypeOf(handle) as { sync: () => Promise<void> }
+    await handle.close()
+    const realSync = proto.sync
+    let failed = false
+    const syncSpy = vi.spyOn(proto, 'sync').mockImplementation(async function (this: unknown) {
+      if (!failed) { failed = true; throw new Error('simulated append fsync failure') }
+      return realSync.call(this)
+    })
+    const backend = ctx.sessionPersistence as unknown as {
+      rollbackAppend: (path: string, size: number) => Promise<void>
+    }
+    const realRollback = backend.rollbackAppend.bind(backend)
+    backend.rollbackAppend = () => Promise.reject(new Error('simulated rollback failure'))
+
+    try {
+      await ctx.sessionPersistence.append(m.id, [
+        { type: 'turn/start', seq: 6, time: 9, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } },
+      ] as SessionEvent[])
+      throw new Error('expected append to reject')
+    } catch (error) {
+      expect(error).toBeInstanceOf(AggregateError)
+      const aggregate = error as AggregateError
+      expect(aggregate.message).toContain(`failed to roll back append to "${path}"`)
+      expect(aggregate.errors).toHaveLength(2)
+      expect(aggregate.errors[0]).toMatchObject({ message: 'simulated append fsync failure' })
+      expect(aggregate.errors[1]).toMatchObject({ message: 'simulated rollback failure' })
+    } finally {
+      backend.rollbackAppend = realRollback
+      syncSpy.mockRestore()
+    }
+  })
+
   it('load returns a meta copy: mutating it does not corrupt backend pathing', async () => {
     const m = meta('meta-copy', '/proj')
     await ctx.sessionPersistence.create(m)
diff --git a/packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts b/packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts
new file mode 100644
index 0000000000..760eb3d455
--- /dev/null
+++ b/packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts
@@ -0,0 +1,168 @@
+/**
+ * Unit tests for the Windows durable namespace helper with a mocked kernel32
+ * binding. The real JSONL suite exercises the helper on native Windows; these
+ * tests keep the Win32 error mapping and race handling covered on every host.
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+const MOVEFILE_WRITE_THROUGH = 0x00000008
+const ERROR_FILE_NOT_FOUND = 2
+const ERROR_PATH_NOT_FOUND = 3
+const ERROR_ACCESS_DENIED = 5
+const ERROR_NOT_SAME_DEVICE = 17
+const ERROR_FILE_EXISTS = 80
+const ERROR_INVALID_NAME = 123
+const ERROR_ALREADY_EXISTS = 183
+
+type MoveFileExW = (existing: string, replacement: string, flags: number, setLastError: (code: number) => void) => boolean
+
+const roots: string[] = []
+
+function stripNamespace(path: string): string {
+  if (path.startsWith('\\\\?\\UNC\\')) return `\\\\${path.slice('\\\\?\\UNC\\'.length)}`
+  if (path.startsWith('\\\\?\\')) return path.slice('\\\\?\\'.length)
+  return path
+}
+
+async function tempRoot(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'dsh-jsonl-win32-'))
+  roots.push(dir)
+  return dir
+}
+
+async function importWithMove(moveFileExW: MoveFileExW): Promise<typeof import('../src/win32.ts')> {
+  vi.resetModules()
+  vi.doMock('koffi', () => {
+    let lastError = 0
+    const setLastError = (code: number): void => { lastError = code }
+    const move: MoveFileExW = (existing, replacement, flags, setError) => {
+      const ok = moveFileExW(existing, replacement, flags, setError)
+      lastError = ok ? 0 : lastError
+      return ok
+    }
+    return {
+      default: {
+        load: () => ({
+          func: (_convention: string, name: string) => {
+            if (name === 'MoveFileExW') return (existing: string, replacement: string, flags: number) => {
+              const ok = move(existing, replacement, flags, setLastError)
+              return ok
+            }
+            return () => lastError
+          },
+        }),
+      },
+    }
+  })
+  return import('../src/win32.ts')
+}
+
+async function importWithError(code: number): Promise<typeof import('../src/win32.ts')> {
+  vi.resetModules()
+  vi.doMock('koffi', () => ({
+    default: {
+      load: () => ({
+        func: (_convention: string, name: string) => {
+          if (name === 'MoveFileExW') return () => false
+          return () => code
+        },
+      }),
+    },
+  }))
+  return import('../src/win32.ts')
+}
+
+async function importWithFilesystemMove(): Promise<typeof import('../src/win32.ts')> {
+  return importWithMove((existing, replacement, flags, setLastError) => {
+    expect(flags).toBe(MOVEFILE_WRITE_THROUGH)
+    const from = stripNamespace(existing)
+    const to = stripNamespace(replacement)
+    if (!existsSync(from)) { setLastError(ERROR_FILE_NOT_FOUND); return false }
+    if (existsSync(to)) { setLastError(ERROR_ALREADY_EXISTS); return false }
+    renameSync(from, to)
+    return true
+  })
+}
+
+afterEach(async () => {
+  vi.doUnmock('koffi')
+  vi.resetModules()
+  for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true })
+})
+
+describe('Windows durable namespace helpers', () => {
+  it('publishes a new file with write-through MoveFileExW semantics', async () => {
+    const { publishNewFileWin32 } = await importWithFilesystemMove()
+    const root = await tempRoot()
+    const tmp = join(root, 'log.tmp')
+    const final = join(root, 'log.jsonl')
+    await writeFile(tmp, 'content')
+
+    await publishNewFileWin32(tmp, final)
+    expect(existsSync(tmp)).toBe(false)
+    expect(readFileSync(final, 'utf8')).toBe('content')
+  })
+
+  it('maps Win32 publish failures to Node-style errno codes', async () => {
+    const cases = [
+      [ERROR_FILE_NOT_FOUND, 'ENOENT'],
+      [ERROR_PATH_NOT_FOUND, 'ENOENT'],
+      [ERROR_ACCESS_DENIED, 'EACCES'],
+      [ERROR_NOT_SAME_DEVICE, 'EXDEV'],
+      [ERROR_FILE_EXISTS, 'EEXIST'],
+      [ERROR_ALREADY_EXISTS, 'EEXIST'],
+      [ERROR_INVALID_NAME, 'EINVAL'],
+      [9999, 'EIO'],
+    ] as const
+    for (const [win32Code, code] of cases) {
+      const { publishNewFileWin32 } = await importWithError(win32Code)
+      await expect(publishNewFileWin32('from', 'to')).rejects.toMatchObject({ code, win32Code, path: 'from', dest: 'to' })
+    }
+  })
+
+  it('creates missing directories through staging siblings and tolerates an already-created race', async () => {
+    const root = await tempRoot()
+    const raced = join(root, 'raced')
+    const { ensureDurableDirectoryWin32 } = await importWithMove((existing, replacement, flags, setLastError) => {
+      expect(flags).toBe(MOVEFILE_WRITE_THROUGH)
+      const from = stripNamespace(existing)
+      const to = stripNamespace(replacement)
+      if (to === raced) {
+        mkdirSync(to)
+        setLastError(ERROR_ALREADY_EXISTS)
+        return false
+      }
+      if (!existsSync(from)) { setLastError(ERROR_FILE_NOT_FOUND); return false }
+      if (existsSync(to)) { setLastError(ERROR_ALREADY_EXISTS); return false }
+      renameSync(from, to)
+      return true
+    })
+
+    await ensureDurableDirectoryWin32(join(root, 'a', 'b'))
+    expect(existsSync(join(root, 'a', 'b'))).toBe(true)
+    await ensureDurableDirectoryWin32(join(root, 'a', 'b'))
+    await ensureDurableDirectoryWin32(raced)
+    expect(existsSync(raced)).toBe(true)
+  })
+
+  it('surfaces directory publication failures other than an existing-target race', async () => {
+    const { ensureDurableDirectoryWin32 } = await importWithError(ERROR_ACCESS_DENIED)
+    const root = await tempRoot()
+
+    await expect(ensureDurableDirectoryWin32(join(root, 'denied'))).rejects.toMatchObject({ code: 'EACCES' })
+  })
+
+  it('rejects a non-directory component instead of treating it as missing', async () => {
+    const { ensureDurableDirectoryWin32 } = await importWithFilesystemMove()
+    const root = await tempRoot()
+    const blocked = join(root, 'blocked')
+    writeFileSync(blocked, 'x')
+
+    await expect(ensureDurableDirectoryWin32(join(blocked, 'child'))).rejects.toMatchObject({ code: 'ENOTDIR' })
+  })
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 9810a9a61e..9e6532f466 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1259,6 +1259,9 @@ importers:
 
   packages/session-persistence/session-persistence-jsonl:
     dependencies:
+      koffi:
+        specifier: ^3.1.0
+        version: 3.1.1
       schemastery:
         specifier: ^3.18.0
         version: 3.18.0
@@ -3453,6 +3456,81 @@ packages:
   '@jridgewell/trace-mapping@0.3.31':
     resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
 
+  '@koromix/koffi-darwin-arm64@3.1.1':
+    resolution: {integrity: sha512-+Dl0zQDh1Wb55AWOn9hp7K30qgkODvrvN+ZNkFOh81Q0oFX/rpJQtocgjAuYk2zFAcajSeVDumkcHMPwnKSXzA==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@koromix/koffi-darwin-x64@3.1.1':
+    resolution: {integrity: sha512-cDFAKn1qdZBFLrp7dAc9QUDw3l4xAhTJbOdPWWb0LxssVicUdHcRCLZGrDsmPW2tpH6LGNNeLgqRpAoD2Mo8iA==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@koromix/koffi-freebsd-arm64@3.1.1':
+    resolution: {integrity: sha512-zaP7FJISI/scQW9Wa5QicY3a09WmtKBWSbmC+5nfCqPzwWe7Hx2so74Er7mPsDfCiMMR0Ya+evKbJQDkfyXicg==}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@koromix/koffi-freebsd-ia32@3.1.1':
+    resolution: {integrity: sha512-7GejVb688TLM8rbjfc0oezJrATxZc0dn801xWEDJekN2DgmRXu7HquGqWQ6z3NeSq7ZxEggz4T3xtlbCysQapA==}
+    cpu: [ia32]
+    os: [freebsd]
+
+  '@koromix/koffi-freebsd-x64@3.1.1':
+    resolution: {integrity: sha512-XLiCFP9OFCyOoGTjAimtDKLhzhfo34WcP1ShVWxRzNCWDGjfz8BYjwd69cp/cDSUXZbxamqs4+/6vmkePq9wxA==}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@koromix/koffi-linux-arm64@3.1.1':
+    resolution: {integrity: sha512-HA9xINK7G4dRAkpfnBWD9VfuyIBgW1SuK+KPHjksUwRMOnhgqP8J/JqgrAzdzcDiefGBkqEacIP776OUwz7knQ==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@koromix/koffi-linux-ia32@3.1.1':
+    resolution: {integrity: sha512-jG7IFytmP8K5Qtbx0ro0ZeuX3JjSsLxmYhq+nmXDdrtOAlxIsWGynuiDLS6Jk3vOchVii2m6Y2f/L3GLG2fG5A==}
+    cpu: [ia32]
+    os: [linux]
+
+  '@koromix/koffi-linux-loong64@3.1.1':
+    resolution: {integrity: sha512-CIsT1cNnih8FuU52Me/IVlJBpH28SQfoDeYPctJswgJzaARktusF7m4MUbtR1PBDjuquCVM4/vFyNdOzfPonvA==}
+    cpu: [loong64]
+    os: [linux]
+
+  '@koromix/koffi-linux-riscv64@3.1.1':
+    resolution: {integrity: sha512-9D6RmqeKsSvs3U6jILJU9PcAjMwKKyn7yLxNBb5k6z9PCoUoGJ3/BrhXAX0qjrLLwEiIpP/hS/40RuXvH8Lc3Q==}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@koromix/koffi-linux-x64@3.1.1':
+    resolution: {integrity: sha512-pyTcX5fePeYbt7TZAwRby69wdlRx3PT+g15ra5IYdat/Pgh3qAKEYeZ+uu7WpPGOy43p/oSRqqZoa2kORzozlA==}
+    cpu: [x64]
+    os: [linux]
+
+  '@koromix/koffi-openbsd-ia32@3.1.1':
+    resolution: {integrity: sha512-iPnPzvG2HOfdzaiG1drdkt86sAqmTPDv9mAf+5gL7mRzkeeQC88EVGboRy7eXwdXn7R+v0ntA3iQxdHrBn6yXw==}
+    cpu: [ia32]
+    os: [openbsd]
+
+  '@koromix/koffi-openbsd-x64@3.1.1':
+    resolution: {integrity: sha512-/Xqc3R0SVoMCYjMPZnJ9bULtRo364+dKmnQhfDrI83tSpxUHRw7HRNf12vBeL+hPgKxSBjtMpWfQ/ZIyVyLFag==}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@koromix/koffi-win32-arm64@3.1.1':
+    resolution: {integrity: sha512-JhqHauEwQvdcWUERxrV5HH/DT9W7hY1A1eU6/o8tB+yck+D3kt5elpRDBt9KjpW6h+vHPy3V0sjDvO0CXyabTA==}
+    cpu: [arm64]
+    os: [win32]
+
+  '@koromix/koffi-win32-ia32@3.1.1':
+    resolution: {integrity: sha512-ZRuyYmlGS/rCc966qqs0qREXDW4FRdul7rDF1VgSWHbVmdc196PUgUT+blq/GjZgTwqzeEXtMRgM+cU8krHjvA==}
+    cpu: [ia32]
+    os: [win32]
+
+  '@koromix/koffi-win32-x64@3.1.1':
+    resolution: {integrity: sha512-KqHPmvj6QILhNyI/To8QSihHsijeVGIYYPBOUnXEpcnH2LuLbargY4Hd6dDeTN3Z90uUUxN+1FWz1UnhVzFOiA==}
+    cpu: [x64]
+    os: [win32]
+
   '@mermaid-js/parser@1.2.0':
     resolution: {integrity: sha512-oYPyv8A4As1yH5Bx+04iQEQxXuIQDe0GKCNSRgao6z8AM9jixXIfP0vsppRLvGf+nKIOb9/LdpWA4YuJiVvESA==}
 
@@ -5662,6 +5740,9 @@ packages:
     engines: {node: ^20.19.0 || >=22.12.0}
     hasBin: true
 
+  koffi@3.1.1:
+    resolution: {integrity: sha512-mRX6AMeeKCxSOeOopqAcLAl5jcNvge7NAG8l7rF/8gGJATI0tdHFYjteIdE0mGOtWdsrJOij+PjnP8Q9c1gwgA==}
+
   layout-base@1.0.2:
     resolution: {integrity: sha512-8h2oVEZNktL4BH2JCOI90iD1yXwL6iNW7KcCKT2QZgQJR2vbqDsldCTPRU9NifTCqHZci57XvQQ15YTu+sTYPg==}
 
@@ -7842,6 +7923,51 @@ snapshots:
       '@jridgewell/resolve-uri': 3.1.2
       '@jridgewell/sourcemap-codec': 1.5.5
 
+  '@koromix/koffi-darwin-arm64@3.1.1':
+    optional: true
+
+  '@koromix/koffi-darwin-x64@3.1.1':
+    optional: true
+
+  '@koromix/koffi-freebsd-arm64@3.1.1':
+    optional: true
+
+  '@koromix/koffi-freebsd-ia32@3.1.1':
+    optional: true
+
+  '@koromix/koffi-freebsd-x64@3.1.1':
+    optional: true
+
+  '@koromix/koffi-linux-arm64@3.1.1':
+    optional: true
+
+  '@koromix/koffi-linux-ia32@3.1.1':
+    optional: true
+
+  '@koromix/koffi-linux-loong64@3.1.1':
+    optional: true
+
+  '@koromix/koffi-linux-riscv64@3.1.1':
+    optional: true
+
+  '@koromix/koffi-linux-x64@3.1.1':
+    optional: true
+
+  '@koromix/koffi-openbsd-ia32@3.1.1':
+    optional: true
+
+  '@koromix/koffi-openbsd-x64@3.1.1':
+    optional: true
+
+  '@koromix/koffi-win32-arm64@3.1.1':
+    optional: true
+
+  '@koromix/koffi-win32-ia32@3.1.1':
+    optional: true
+
+  '@koromix/koffi-win32-x64@3.1.1':
+    optional: true
+
   '@mermaid-js/parser@1.2.0':
     dependencies:
       '@chevrotain/types': 11.1.2
@@ -10072,6 +10198,24 @@ snapshots:
       yaml: 2.9.0
       zod: 4.4.3
 
+  koffi@3.1.1:
+    optionalDependencies:
+      '@koromix/koffi-darwin-arm64': 3.1.1
+      '@koromix/koffi-darwin-x64': 3.1.1
+      '@koromix/koffi-freebsd-arm64': 3.1.1
+      '@koromix/koffi-freebsd-ia32': 3.1.1
+      '@koromix/koffi-freebsd-x64': 3.1.1
+      '@koromix/koffi-linux-arm64': 3.1.1
+      '@koromix/koffi-linux-ia32': 3.1.1
+      '@koromix/koffi-linux-loong64': 3.1.1
+      '@koromix/koffi-linux-riscv64': 3.1.1
+      '@koromix/koffi-linux-x64': 3.1.1
+      '@koromix/koffi-openbsd-ia32': 3.1.1
+      '@koromix/koffi-openbsd-x64': 3.1.1
+      '@koromix/koffi-win32-arm64': 3.1.1
+      '@koromix/koffi-win32-ia32': 3.1.1
+      '@koromix/koffi-win32-x64': 3.1.1
+
   layout-base@1.0.2: {}
 
   layout-base@2.0.1: {}
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 8f93814899..2de5578f5d 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -31,6 +31,8 @@ allowBuilds:
   '@google/genai': false
   protobufjs: false
   node-addon-require-builtin: false
+  # JSONL durability calls MoveFileExW with write-through publication on Windows.
+  koffi: true
 
 # The Landlock launcher family is our own sibling-repo release, consumed
 # fresh (hours old at each coordinated bump) — the release-age quarantine

From 5ed34b66ce0d688a2440b42a25db99a7c71330de Mon Sep 17 00:00:00 2001
From: Huanqi Cao <caohuanqi@deepseek.com>
Date: Wed, 8 Jul 2026 12:45:31 +0800
Subject: [PATCH 06/74] fix(acp-snapshot): make path-separator tests
 platform-neutral

Three tests in the shared acp-snapshot package hardcoded POSIX path
separators in their assertions, so they failed on Windows where
node:path.join produces backslash paths:

- childFixturePaths (suite.spec.ts): expected literal '/snap/s/session.1.jsonl'
  but join returns '\snap\s\...' on Windows; use join() for the expected value.
- harness.spec.ts (env-forwarding test): substring-matched a JSON-encoded
  path against raw stdout text, where backslash escaping makes the compare
  byte-fragile; parse the env-probe chunk and compare the structured value.
- harness.spec.ts (harvested-cwd test): substring-matched the raw cwd
  against JSONL text where the cwd is JSON-escaped; parse the session line
  and compare the cwd field.

These were master's latent bugs (the package's tests never ran on Windows
until the Windows CI lane observed them). Verified green on Windows via
scripts/caohuanqi-private/run-ci.py --windows.
---
 .../support/acp-snapshot/tests/harness.spec.ts | 18 ++++++++++++++++--
 .../support/acp-snapshot/tests/suite.spec.ts   |  2 +-
 2 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/packages/support/acp-snapshot/tests/harness.spec.ts b/packages/support/acp-snapshot/tests/harness.spec.ts
index 1d953f5e95..d141fb1f09 100644
--- a/packages/support/acp-snapshot/tests/harness.spec.ts
+++ b/packages/support/acp-snapshot/tests/harness.spec.ts
@@ -72,7 +72,11 @@ describe('runScenario', () => {
     expect(result.sessionLogs[0]?.createdAt).toBe(42)
     expect(result.sessionLogs[0]?.content).toContain('turn/start')
     // The harvested log embeds the run's REAL temp cwd (template-substituted).
-    expect(result.sessionLogs[0]?.content).toContain(result.cwd)
+    // The cwd is JSON-encoded in the log line, so compare the parsed field
+    // rather than substring-matching a raw path (which breaks when the path
+    // separator is escaped inside JSON text on Windows).
+    const sessionLine = result.sessionLogs[0]?.content.split('\n').find(l => l.includes('"type":"session"')) ?? '{}'
+    expect((JSON.parse(sessionLine) as { cwd?: string }).cwd).toBe(result.cwd)
   })
 
   it('forwards override/child fixture paths into the child env and captures stderr', { timeout: 20_000 }, async () => {
@@ -93,7 +97,17 @@ describe('runScenario', () => {
     expect(result.stderr).toContain('fake bin booted')
     expect(result.rawStdout).toContain('replay.override.json')
     // Child paths ride one env var, joined with the platform delimiter.
-    expect(result.rawStdout).toContain(JSON.stringify(childFiles.join(delimiter)).slice(1, -1))
+    // Parse the fake bin's env-probe chunk rather than substring-matching a
+    // JSON-encoded path (the escaping breaks raw-substring compares on Windows).
+    const envChunk = result.rawStdout.split('\n')
+      .map(l => l.trim())
+      .filter(l => l.length > 0)
+      .map(l => JSON.parse(l) as { params?: { update?: { content?: { text?: string } } } })
+      .find(f => f.params?.update?.content?.text?.startsWith('env:'))
+    const env = JSON.parse((envChunk?.params?.update?.content?.text ?? 'env:{}').slice('env:'.length)) as {
+      childFiles: string | null
+    }
+    expect(env.childFiles).toBe(childFiles.join(delimiter))
   })
 
   it('seeds the workspace dir into the temp cwd before the run', { timeout: 20_000 }, async () => {
diff --git a/packages/support/acp-snapshot/tests/suite.spec.ts b/packages/support/acp-snapshot/tests/suite.spec.ts
index 4cedc1cdfb..c2007321de 100644
--- a/packages/support/acp-snapshot/tests/suite.spec.ts
+++ b/packages/support/acp-snapshot/tests/suite.spec.ts
@@ -181,7 +181,7 @@ describe('defineAcpSnapshotSuite: registration contract', () => {
 
 describe('childFixturePaths', () => {
   it('yields one sibling path per child, 1-based', () => {
-    expect(childFixturePaths('/snap/s', 2)).toEqual(['/snap/s/session.1.jsonl', '/snap/s/session.2.jsonl'])
+    expect(childFixturePaths('/snap/s', 2)).toEqual([join('/snap/s', 'session.1.jsonl'), join('/snap/s', 'session.2.jsonl')])
   })
 
   it('yields nothing for a single-session scenario', () => {

From 1a4af034c0edd60e4bd54de1f2a1371afbdef056 Mon Sep 17 00:00:00 2001
From: Huanqi Cao <caohuanqi@deepseek.com>
Date: Sun, 5 Jul 2026 04:45:41 +0800
Subject: [PATCH 07/74] Accept native ACP path separators in tests

---
 packages/ui/acp/README.md                   |  4 +-
 packages/ui/acp/tests/stream-update.spec.ts | 53 ++++++++++++++-------
 2 files changed, 37 insertions(+), 20 deletions(-)

diff --git a/packages/ui/acp/README.md b/packages/ui/acp/README.md
index 300cd69023..4f810ba0b4 100644
--- a/packages/ui/acp/README.md
+++ b/packages/ui/acp/README.md
@@ -53,11 +53,11 @@ The shared [`ctx.tasks` runtime](../../tasks/tasks/) fences access to predictabl
 
 ## Tool-call presentation
 
-Tools return provider-neutral `generic`, `terminal`, or `diff` render intents from `presentCall()` and `presentResult()`. The bridge maps the discriminator to ACP without special-casing tool names and falls back to a generic card. Per-session call-id state supplies result events with their omitted name and arguments during live streaming and replay. See [`dsh-tools`](../../core/tools/README.md#tool-owned-ui-presentation).
+Tools return provider-neutral `generic`, `terminal`, or `diff` render intents from `presentCall()` and `presentResult()`. The bridge maps the discriminator to ACP without special-casing tool names and falls back to a generic card. Per-session call-id state supplies result events with their omitted name and arguments during live streaming and replay. File-card titles are relative to the session cwd and use the host separator, while location and diff paths remain raw so the editor opens the real file. See [`dsh-tools`](../../core/tools/README.md#tool-owned-ui-presentation).
 
 ## Terminal card (capability-gated)
 
-When the client advertises `_meta.terminal_output`, terminal intents map to Zed's terminal info, output, and exit metadata. The bridge resolves relative cwd against the session, places the description before the terminal block, and omits result content because ACP updates replace call content. Other clients receive a generic card and bridge-derived fenced console fallback. Session creation snapshots the capability so call and result agree. The command still executes through the harness, not ACP terminal creation. See the [terminal-rendering RFC](../../../docs/rfc/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md) and [render-intent RFC](../../../docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md).
+When the client advertises `_meta.terminal_output`, terminal intents map to Zed's terminal info, output, and exit metadata. The bridge resolves relative cwd against the session and preserves the host filesystem separator, places the description before the terminal block, and omits result content because ACP updates replace call content. Other clients receive a generic card and bridge-derived fenced console fallback. Session creation snapshots the capability so call and result agree. The command still executes through the harness, not ACP terminal creation. See the [terminal-rendering RFC](../../../docs/rfc/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md) and [render-intent RFC](../../../docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md).
 
 ## Settle-exactly-once
 
diff --git a/packages/ui/acp/tests/stream-update.spec.ts b/packages/ui/acp/tests/stream-update.spec.ts
index 415e9afb33..15a6d3c3fc 100644
--- a/packages/ui/acp/tests/stream-update.spec.ts
+++ b/packages/ui/acp/tests/stream-update.spec.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest'
+import { join as pathJoin, resolve as pathResolve } from 'node:path'
 import { Context } from 'cordis'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
@@ -49,6 +50,16 @@ function evt<T extends SessionEvent['type']>(type: T, data: Extract<SessionEvent
   return { type, seq: 0, time: 0, data } as SessionEvent
 }
 
+/** ACP path fields are filesystem paths; expectations use the host separator. */
+function nativePath(...segments: string[]): string {
+  return pathJoin(...segments)
+}
+
+/** Resolve root-relative fixtures the same way the bridge does on this host. */
+function nativeAbsolute(...segments: string[]): string {
+  return pathResolve(...segments)
+}
+
 describe('streamSessionEventUpdate', () => {
   it('maps assistant/chunk text-delta to agent_message_chunk', () => {
     expect(updatesFor(evt('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'hi' } })))
@@ -480,10 +491,10 @@ describe('terminal-card mapping (capability-gated)', () => {
   it('capability ON: an ABSOLUTE tool cwd wins; a RELATIVE one resolves against the session cwd', () => {
     const [absCall] = termUpdates(termTool({ card: 'terminal', cwd: '/explicit/abs' }, { output: 'x' }), true, '/work/proj', callEvent)
     expect((absCall as unknown as { _meta: { terminal_info: { cwd: string } } })._meta.terminal_info.cwd).toBe('/explicit/abs')
-    const [relCall] = termUpdates(termTool({ card: 'terminal', cwd: 'sub/dir' }, { output: 'x' }), true, '/work/proj', callEvent)
+    const [relCall] = termUpdates(termTool({ card: 'terminal', cwd: nativePath('sub', 'dir') }, { output: 'x' }), true, nativeAbsolute('/work/proj'), callEvent)
     // Relative workdir resolved against the session cwd — the card header matches
     // where execution actually ran (tool-bash resolves the same way).
-    expect((relCall as unknown as { _meta: { terminal_info: { cwd: string } } })._meta.terminal_info.cwd).toBe('/work/proj/sub/dir')
+    expect((relCall as unknown as { _meta: { terminal_info: { cwd: string } } })._meta.terminal_info.cwd).toBe(nativeAbsolute('/work/proj', 'sub', 'dir'))
     // No session cwd to resolve against → the relative tool cwd is passed through as-is.
     const [noSessionCwd] = termUpdates(termTool({ card: 'terminal', cwd: 'rel/only' }, { output: 'x' }), true, undefined, callEvent)
     expect((noSessionCwd as unknown as { _meta: { terminal_info: { cwd: string } } })._meta.terminal_info.cwd).toBe('rel/only')
@@ -675,10 +686,12 @@ describe('result-time diff card (REAL fs edit tool → tool_call_update diff blo
     // paths remain absolute so the editor can open the real file.
     const ctx = await fsCtx()
     const presenter = new ToolPresenter(ctx.tools)
-    const args = JSON.stringify({ file_path: '/work/proj/src/b.ts', old_string: 'OLD', new_string: 'NEW' })
-    const meta = { diffs: [{ path: '/work/proj/src/b.ts', oldText: 'a\nOLD\nb', newText: 'a\nNEW\nb' }] }
+    const workspace = nativeAbsolute('/work/proj')
+    const file = nativeAbsolute('/work/proj', 'src', 'b.ts')
+    const args = JSON.stringify({ file_path: file, old_string: 'OLD', new_string: 'NEW' })
+    const meta = { diffs: [{ path: file, oldText: 'a\nOLD\nb', newText: 'a\nNEW\nb' }] }
     const out: SessionNotification['update'][] = []
-    const rendering = { enabled: false, cwd: '/work/proj' }
+    const rendering = { enabled: false, cwd: workspace }
     for (const event of [
       evt('tool/call', { turn: 1, step: 1, callId: CallId('e1'), name: 'edit', arguments: args }),
       evt('tool/result', { turn: 1, step: 1, callId: CallId('e1'), content: [{ type: 'text', text: 'ok' }], isError: false, meta }),
@@ -687,8 +700,8 @@ describe('result-time diff card (REAL fs edit tool → tool_call_update diff blo
       sessionUpdate: 'tool_call_update',
       toolCallId: 'e1',
       status: 'completed',
-      title: 'Edit src/b.ts',
-      content: [{ type: 'diff', path: '/work/proj/src/b.ts', oldText: 'a\nOLD\nb', newText: 'a\nNEW\nb' }],
+      title: `Edit ${nativePath('src', 'b.ts')}`,
+      content: [{ type: 'diff', path: file, oldText: 'a\nOLD\nb', newText: 'a\nNEW\nb' }],
     })
     await ctx.fiber.dispose()
   })
@@ -739,21 +752,25 @@ describe('relative-path display titles (bridge relativizes the title against the
 
   it('read: an absolute path inside the workspace relativizes the TITLE; the location path stays absolute', async () => {
     const ctx = await fsCtx()
-    const update = callUpdate(ctx, '/work/proj', 'read', { file_path: '/work/proj/src/a.ts', offset: 5 })
+    const workspace = nativeAbsolute('/work/proj')
+    const file = nativeAbsolute('/work/proj', 'src', 'a.ts')
+    const update = callUpdate(ctx, workspace, 'read', { file_path: file, offset: 5 })
     expect(update).toMatchObject({
-      title: 'Read src/a.ts (from line 5)',
-      locations: [{ path: '/work/proj/src/a.ts', line: 5 }],
+      title: `Read ${nativePath('src', 'a.ts')} (from line 5)`,
+      locations: [{ path: file, line: 5 }],
     })
     await ctx.fiber.dispose()
   })
 
   it('edit: the diff TITLE relativizes; the diff/location paths stay absolute (the editor opens the real path)', async () => {
     const ctx = await fsCtx()
-    const update = callUpdate(ctx, '/work/proj', 'edit', { file_path: '/work/proj/src/b.ts', old_string: 'x', new_string: 'y' })
+    const workspace = nativeAbsolute('/work/proj')
+    const file = nativeAbsolute('/work/proj', 'src', 'b.ts')
+    const update = callUpdate(ctx, workspace, 'edit', { file_path: file, old_string: 'x', new_string: 'y' })
     expect(update).toMatchObject({
-      title: 'Edit src/b.ts',
-      locations: [{ path: '/work/proj/src/b.ts' }],
-      content: [{ type: 'diff', path: '/work/proj/src/b.ts', oldText: 'x', newText: 'y' }],
+      title: `Edit ${nativePath('src', 'b.ts')}`,
+      locations: [{ path: file }],
+      content: [{ type: 'diff', path: file, oldText: 'x', newText: 'y' }],
     })
     await ctx.fiber.dispose()
   })
@@ -770,8 +787,8 @@ describe('relative-path display titles (bridge relativizes the title against the
     // with the chars `..` but is not a parent segment. Segment-aware guarding must relativize it,
     // matching targets under `cwd + sep` in the reference adapter.
     const ctx = await fsCtx()
-    const update = callUpdate(ctx, '/work/proj', 'read', { file_path: '/work/proj/..cache/x.ts' })
-    expect((update as { title: string }).title).toBe('Read ..cache/x.ts')
+    const update = callUpdate(ctx, nativeAbsolute('/work/proj'), 'read', { file_path: nativeAbsolute('/work/proj', '..cache', 'x.ts') })
+    expect((update as { title: string }).title).toBe(`Read ${nativePath('..cache', 'x.ts')}`)
     await ctx.fiber.dispose()
   })
 
@@ -784,8 +801,8 @@ describe('relative-path display titles (bridge relativizes the title against the
 
   it('a relative path is passed through unchanged (already display-friendly)', async () => {
     const ctx = await fsCtx()
-    const update = callUpdate(ctx, '/work/proj', 'read', { file_path: 'src/a.ts' })
-    expect((update as { title: string }).title).toBe('Read src/a.ts')
+    const update = callUpdate(ctx, nativeAbsolute('/work/proj'), 'read', { file_path: nativePath('src', 'a.ts') })
+    expect((update as { title: string }).title).toBe(`Read ${nativePath('src', 'a.ts')}`)
     await ctx.fiber.dispose()
   })
 })

From 130944caeb8118033f5de86f4a1df1c85e962595 Mon Sep 17 00:00:00 2001
From: Huanqi Cao <caohuanqi@deepseek.com>
Date: Sun, 5 Jul 2026 17:47:24 +0800
Subject: [PATCH 08/74] Close SQLite probe handle after journalMode assertion

---
 .../session-persistence-sqlite/tests/sqlite.spec.ts           | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts b/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts
index a728cc0b71..cebfae09a4 100644
--- a/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts
+++ b/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts
@@ -423,7 +423,9 @@ describe('SessionPersistenceSqlite: edge cases', () => {
     const walPath = await freshDbPath()
     const bWal = await backend(walPath)
     await bWal.ctx.sessionPersistence.create(meta('jm-wal'))
-    expect((openDatabase(walPath, 'wal').prepare('PRAGMA journal_mode').get() as { journal_mode: string }).journal_mode).toBe('wal')
+    const probe = openDatabase(walPath, 'wal')
+    expect((probe.prepare('PRAGMA journal_mode').get() as { journal_mode: string }).journal_mode).toBe('wal')
+    probe.close()
     await bWal.dispose()
 
     const deletePath = await freshDbPath()

From 715aa7372a0ab51c5780a4d014009138da5f1444 Mon Sep 17 00:00:00 2001
From: Huanqi Cao <caohuanqi@deepseek.com>
Date: Sun, 5 Jul 2026 18:57:23 +0800
Subject: [PATCH 09/74] Restore ENOTDIR semantic distinction in
 resolveLocalTarget on Windows

---
 packages/fs/fs-local/src/fsio.ts | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts
index 360145e8c8..e0745f1735 100644
--- a/packages/fs/fs-local/src/fsio.ts
+++ b/packages/fs/fs-local/src/fsio.ts
@@ -145,8 +145,22 @@ export async function resolveLocalTarget(cwd: string, path: string): Promise<Loc
   while (true) {
     try {
       const realAncestor = await realpath(ancestor)
+      // On Windows, realpath of a regular file succeeds where POSIX returns
+      // ENOTDIR (the OS reports ENOENT for `regular-file/child`, not ENOTDIR).
+      // Stat the ancestor to restore the semantic distinction: a non-directory
+      // ancestor means the target passes through a file and can never be created.
+      /* v8 ignore start -- native Windows coverage exercises this repair; POSIX reports ENOTDIR before this point. */
+      if (process.platform === 'win32') {
+        const parentInfo = await stat(realAncestor)
+        if (!parentInfo.isDirectory()) {
+          throw new FsError(`cannot resolve "${displayPath}": a parent path segment is not a directory`, 'FS_NOT_FOUND')
+        }
+      }
+      /* v8 ignore stop */
       return { displayPath, targetKey: FsTargetKey(join(realAncestor, ...missing)) }
     } catch (error: unknown) {
+      /* v8 ignore next -- native Windows coverage exercises the FsError raised by the repair above. */
+      if (error instanceof FsError) throw error
       /* v8 ignore next -- a non-ENOENT realpath failure needs a permission/IO fault. */
       if (!isENOENT(error)) throw error
       const parent = dirname(ancestor)

From e47ae0643c3797f8c759b06396783c8053b7dc5b Mon Sep 17 00:00:00 2001
From: Huanqi Cao <caohuanqi@deepseek.com>
Date: Sun, 5 Jul 2026 21:15:46 +0800
Subject: [PATCH 10/74] fs-local: POSIX-only mode-bit assertions, document
 Windows DACL-inheritance semantics

Windows drives only the read-only attribute through chmod and reports
synthetic stat mode bits, so writeFileAtomic's mode arguments are inert
there; write-in-progress privacy comes from the staging dir (created in
the target's parent) inheriting the destination directory's DACL.
Production is deliberately unchanged -- the chmod calls are benign
no-ops and platform-guarding them out buys nothing. Tests guard the
mode-bit expects to POSIX; there is no Windows ACL assertion because an
ACL check would pin OS inheritance plus the machine's %TEMP% ACL, not
this package. Decision and rejected alternatives (explicit DACLs,
Get-Acl/icacls test verification) recorded in the new RFC.
---
 docs/rfc/INDEX.md                             |  1 +
 .../2026-07-05-windows-fs-permissions.md      | 29 +++++++++++++++++++
 packages/fs/fs-local/README.md                |  2 +-
 packages/fs/fs-local/src/fsio.ts              |  4 ++-
 packages/fs/fs-local/tests/fsio.spec.ts       | 19 +++++++++---
 5 files changed, 49 insertions(+), 6 deletions(-)
 create mode 100644 docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md

diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md
index 32f11b744a..5ebf52f07a 100644
--- a/docs/rfc/INDEX.md
+++ b/docs/rfc/INDEX.md
@@ -150,6 +150,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [Prompt variables and tool-guidance ownership](implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md) | 2026-07-05 |
 | [Every LLM request is reconstructable from the session log](implemented/architecture/2026-07-05-reconstructable-requests.md) | 2026-07-05 |
 | [Subagent provider-lifecycle events — `subagent/provider-added` / `subagent/provider-removed`](implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.md) | 2026-07-05 |
+| [Windows write-permission semantics — inherited DACLs, not mode bits](implemented/architecture/2026-07-05-windows-fs-permissions.md) | 2026-07-05 |
 | [Windows-native durable JSONL publication](implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md) | 2026-07-05 |
 | [A shared timeout/deadline primitive, with hard-kill left to each capability](implemented/architecture/2026-07-06-timeout-deadline-library.md) | 2026-07-06 |
 | [Tool result retention library](implemented/architecture/2026-07-06-tool-result-retention-library.md) | 2026-07-06 |
diff --git a/docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md b/docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md
new file mode 100644
index 0000000000..0001e8223c
--- /dev/null
+++ b/docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md
@@ -0,0 +1,29 @@
+# RFC: Windows write-permission semantics — inherited DACLs, not mode bits
+
+Status: implemented
+
+## Problem
+
+`writeFileAtomic` in `@deepseek-ai/dsh-fs-local` protects write-in-progress content with POSIX mode bits: the staging directory is created `0o700`, the temp file is opened `0o600`, and new files default to `0o600`. On POSIX this keeps temporary content owner-only regardless of the parent directory's permissions.
+
+Windows has no working equivalent behind the same API. Node's `chmod` there drives only the read-only attribute (every mode this package passes carries owner-write, so the calls are benign no-ops), and `stat().mode` reports synthetic `0o666`/`0o444` bits. The real security state is the file's DACL, which this code never sets; a newly created file or directory inherits its DACL from its parent directory.
+
+## Decision
+
+Production code is unchanged: no platform fork, no DACL management. The Windows privacy invariant is structural rather than mode-driven — the staging directory is created inside the target's parent directory (`dirname(absolutePath)`), so it and the temp file inherit exactly the destination directory's DACL, and write-in-progress content is never exposed more widely than the destination itself. In the typical deployment (a coding agent writing the user's own project tree under `C:\Users\<user>\`) the inherited DACL is owner + SYSTEM + Administrators, matching the POSIX intent.
+
+Tests assert mode bits on POSIX only. There is no Windows-side ACL assertion because there is no Windows-side code behavior to pin: an ACL check on a `mkdtemp(tmpdir())` fixture would verify Windows DACL inheritance plus the machine's `%TEMP%` ACL — the operating system, not this package — and no change to this package could turn it red.
+
+## Alternatives considered
+
+**Explicit protected DACLs.** Granting owner-only access would require per-write FFI or a subprocess, break inheritance, and surprise users whose project directories are deliberately shared. This becomes appropriate only if the threat model includes hostile local readers of broadly accessible target directories.
+
+**Test-side ACL verification.** A `Get-Acl` SID allowlist or `icacls` would verify Windows inheritance and the machine's `%TEMP%` ACL rather than package behavior; `icacls` also localizes well-known account names, making parsing locale-fragile.
+
+**Skip `chmod` on Windows.** Platform-guarding benign no-op calls adds branches without changing behavior.
+
+## Consequences
+
+POSIX keeps the stronger guarantee: owner-only temp content regardless of the parent directory. Windows guarantees only "no wider than the destination": a target inside a broadly accessible directory (a share, a permissive `D:\` root) gets equally accessible write-in-progress content. The gap is deliberate and documented, not an oversight.
+
+Mode preservation across a replace degenerates to a no-op on Windows: a writable file probes as `0o666`, and replaying that through `chmod` leaves the read-only attribute clear. A read-only target cannot be replaced at all there — `rename` over it fails before the preserved mode would matter.
diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md
index 65ed76efce..7c3899e5cb 100644
--- a/packages/fs/fs-local/README.md
+++ b/packages/fs/fs-local/README.md
@@ -16,7 +16,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **`stat` / `lstat`** — return target metadata or `undefined` when absent. `stat` reports `FsInfo` for an already resolved target (`version` = an opaque token derived from bigint `dev:ino:size:mtimeNs:ctimeNs`, `type` of `file`/`directory`/`other`, byte `size`); path-shaped `lstat` reports `FsPathInfo` without following the final symlink and can therefore return `symlink`. Both check cancellation before and after their asynchronous metadata probe, so an abort that lands in flight reports `FS_ABORTED` rather than stale absence.
 - **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` streams it in chunks (cross-chunk decoding) so a huge file never has to be held whole in memory. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) decides which to call by size and owns the line windowing.
 - **`listDir`** — lists one directory level in stable `name.localeCompare()` order. Each entry carries the child basename, type, resolved child target (`displayPath` under the listed directory, `targetKey` as the realpath identity), and cheap stat metadata (`version`, plus `size` for regular files). It never opens or decodes file contents. Missing targets report `FS_NOT_FOUND`, file/special-file targets report `FS_NOT_DIRECTORY`, aborted calls report `FS_ABORTED`, permission failures report `FS_PERMISSION_DENIED`, and other listing or child metadata I/O failures report `FS_IO_ERROR`. Broken/disappeared children are returned as `other` without metadata, but permission/IO failures while resolving a child fail the whole listing with a structured `FsError`.
-- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`. The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
+- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`; on Windows the mode bits drive only the read-only attribute, and write-in-progress privacy comes instead from the staging dir inheriting the destination directory's DACL ([Windows write-permission RFC](../../../docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
 - **`editText`** — atomic literal read-modify-write over the same primitive, serialized per target by a mutation lock. The `expected` guard is OPTIONAL: when supplied it verifies the version BEFORE literal matching (a stale edit reports `FS_STALE_VERSION`, never `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` against newer content); omitting it edits the current content unconditionally. A missing target reports `FS_STALE_VERSION` either way. LF-normalizes for matching, restores the file's dominant CRLF/LF style, and rejects empty `oldString` / zero matches (`FS_EDIT_NOT_FOUND`) or ambiguous multi-matches without `replace_all` (`FS_AMBIGUOUS_EDIT`).
 
 The package-root SDK surface is the default/named `LocalFileSystem` class plus `Config`. Raw I/O lives in `src/fsio.ts` (Cordis-free, independently unit-tested); `src/index.ts` is the thin service wiring.
diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts
index e0745f1735..4603611ce4 100644
--- a/packages/fs/fs-local/src/fsio.ts
+++ b/packages/fs/fs-local/src/fsio.ts
@@ -408,9 +408,11 @@ async function removeStagingDirOrThrow(stagingDir: string, originalError: unknow
 
 /**
  * Atomically replace a file through a private, synced staging file in the same directory.
+ * POSIX protects the staging directory and file with `0o700` and `0o600`; Windows
+ * inherits the destination directory's DACL because Node mode bits are synthetic there.
  * @param absolutePath - destination; missing parent directories are created.
  * @param content - the full UTF-8 text to write.
- * @param mode - final mode, or `0o600` when omitted.
+ * @param mode - final POSIX mode, or `0o600` when omitted; inert on Windows.
  * @param signal - cancellation checked before the final rename.
  * @param internals - test seam for pinning temp names and observing the staged file.
  */
diff --git a/packages/fs/fs-local/tests/fsio.spec.ts b/packages/fs/fs-local/tests/fsio.spec.ts
index 199c01f411..559ef86563 100644
--- a/packages/fs/fs-local/tests/fsio.spec.ts
+++ b/packages/fs/fs-local/tests/fsio.spec.ts
@@ -367,6 +367,12 @@ describe('streamWholeText', () => {
   })
 })
 
+// Windows drives only the read-only attribute through `chmod` and reports
+// synthetic `stat` mode bits, so mode assertions are POSIX-only; on Windows
+// write-in-progress privacy comes from the destination directory's inherited
+// DACL (docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md).
+const posixModes = process.platform !== 'win32'
+
 describe('writeFileAtomic — temp-file safety', () => {
   it('writes through a private staging dir and owner-only temp file', async () => {
     const file = join(dir, 'a.txt')
@@ -374,17 +380,22 @@ describe('writeFileAtomic — temp-file safety', () => {
     await writeFileAtomic(file, 'hello', 0o640, undefined, {
       inspectTemp: async ({ stagingDir, tempPath }) => {
         inspected = true
-        expect((await stat(stagingDir)).mode & 0o777).toBe(0o700)
-        expect((await stat(tempPath)).mode & 0o777).toBe(0o600)
+        const [staging, temp] = await Promise.all([stat(stagingDir), stat(tempPath)])
+        expect(staging.isDirectory()).toBe(true)
+        expect(temp.isFile()).toBe(true)
+        if (posixModes) {
+          expect(staging.mode & 0o777).toBe(0o700)
+          expect(temp.mode & 0o777).toBe(0o600)
+        }
       },
     })
     expect(inspected).toBe(true)
     expect(await readFile(file, 'utf8')).toBe('hello')
-    expect((await stat(file)).mode & 0o777).toBe(0o640)
+    if (posixModes) expect((await stat(file)).mode & 0o777).toBe(0o640)
     expect((await readdir(dir)).filter(n => n.includes('.tmp'))).toEqual([])
   })
 
-  it('creates new files owner-only by default', async () => {
+  it.skipIf(!posixModes)('creates new files owner-only by default', async () => {
     const file = join(dir, 'a.txt')
     await writeFileAtomic(file, 'hello', undefined, undefined)
     expect((await stat(file)).mode & 0o777).toBe(0o600)

From 5a2ca3ff3aaa6b3410572c9a443ca98625b557ad Mon Sep 17 00:00:00 2001
From: Huanqi Cao <caohuanqi@deepseek.com>
Date: Fri, 17 Jul 2026 15:43:44 +0800
Subject: [PATCH 11/74] Restore JSONL ENOTDIR distinction on Windows

---
 .../session-persistence-jsonl/src/index.ts    | 24 +++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/packages/session-persistence/session-persistence-jsonl/src/index.ts b/packages/session-persistence/session-persistence-jsonl/src/index.ts
index ac1c07860e..2f33664139 100644
--- a/packages/session-persistence/session-persistence-jsonl/src/index.ts
+++ b/packages/session-persistence/session-persistence-jsonl/src/index.ts
@@ -8,7 +8,7 @@
 
 import { Context } from 'cordis'
 import z from 'schemastery'
-import { open, mkdir, readFile, readdir, link, rm, truncate } from 'node:fs/promises'
+import { open, mkdir, readFile, readdir, link, rm, stat as fsStat, truncate } from 'node:fs/promises'
 import { dirname, resolve } from 'node:path'
 import { randomBytes } from 'node:crypto'
 import {
@@ -389,7 +389,27 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
     } catch (error) {
       // Only ENOENT means absent. A permission/I/O error must surface rather
       // than letting load or collision checks proceed under false absence.
-      if (isENOENT(error)) return false
+      // Windows reports ENOENT, not ENOTDIR, for `regular-file/child`; verify
+      // the immediate parent so a blocked cwd bucket remains a storage fault.
+      if (isENOENT(error)) {
+        await this.assertLogParentAllowsAbsence(path)
+        return false
+      }
+      throw error
+    }
+  }
+
+  private async assertLogParentAllowsAbsence(path: string): Promise<void> {
+    try {
+      const parent = dirname(path)
+      const info = await fsStat(parent)
+      if (info.isDirectory()) return
+      const error = new Error(`ENOTDIR: parent path exists but is not a directory: ${parent}`) as NodeJS.ErrnoException
+      error.code = 'ENOTDIR'
+      error.path = parent
+      throw error
+    } catch (error) {
+      if (isENOENT(error)) return
       throw error
     }
   }

From 86c09f6ca9d4bcec8226bd7a62febb1580bb96f4 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 17 Jul 2026 15:50:37 +0800
Subject: [PATCH 12/74] test(jsonl): mark native Windows ENOTDIR coverage

---
 docs/config-catalog.md                                          | 2 +-
 .../session-persistence/session-persistence-jsonl/src/index.ts  | 2 ++
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 3e3d8141fa..ba273888d1 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -634,7 +634,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/session-persistence/session-persistence-jsonl/src/index.ts:24`](../packages/session-persistence/session-persistence-jsonl/src/index.ts)
+Source: [`packages/session-persistence/session-persistence-jsonl/src/index.ts:25`](../packages/session-persistence/session-persistence-jsonl/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-persistence-sqlite`
 
diff --git a/packages/session-persistence/session-persistence-jsonl/src/index.ts b/packages/session-persistence/session-persistence-jsonl/src/index.ts
index 2f33664139..39aa493a0b 100644
--- a/packages/session-persistence/session-persistence-jsonl/src/index.ts
+++ b/packages/session-persistence/session-persistence-jsonl/src/index.ts
@@ -399,6 +399,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
     }
   }
 
+  /* v8 ignore start -- native Windows coverage exercises this repair; POSIX open reports ENOTDIR before this point. */
   private async assertLogParentAllowsAbsence(path: string): Promise<void> {
     try {
       const parent = dirname(path)
@@ -413,6 +414,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
       throw error
     }
   }
+  /* v8 ignore stop */
 }
 
 export default SessionPersistenceJsonl

From beb13c3808c643a93e3a4b0d6fc698d050638321 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 17 Jul 2026 13:53:13 +0800
Subject: [PATCH 13/74] test(acp): pin Windows-native snapshot paths

---
 examples/acp-agent/tests/acp.snapshot.ts      |  10 +-
 .../stdout.golden.windows.jsonl               | 132 ++++++++++++++++++
 packages/support/acp-snapshot/README.md       |  10 +-
 packages/support/acp-snapshot/src/harness.ts  |  11 +-
 packages/support/acp-snapshot/src/index.ts    |   2 +
 .../support/acp-snapshot/src/normalize.ts     |  66 +++++++--
 packages/support/acp-snapshot/src/suite.ts    |  49 ++++++-
 .../acp-snapshot/tests/harness.spec.ts        |   7 +-
 .../acp-snapshot/tests/normalize.spec.ts      |  77 ++++++++++
 .../support/acp-snapshot/tests/suite.spec.ts  |  26 ++++
 10 files changed, 367 insertions(+), 23 deletions(-)
 create mode 100644 examples/acp-agent/tests/snapshots/workspace-edit/stdout.golden.windows.jsonl

diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts
index 23eca9dbc0..e68724cbfe 100644
--- a/examples/acp-agent/tests/acp.snapshot.ts
+++ b/examples/acp-agent/tests/acp.snapshot.ts
@@ -57,7 +57,15 @@ const SCENARIOS: Scenario[] = [
   { name: 'fs-terminal-card', hasModelTurn: true, recorded: true },
   { name: 'todo-plan', hasModelTurn: true, recorded: true },
   { name: 'skill-load', hasModelTurn: true, recorded: false, pinsHeader: true, headerClass: 'skill' },
-  { name: 'workspace-edit', hasModelTurn: true, recorded: true, pinsHeader: true, headerClass: 'fs', configPath: FS_CONFIG },
+  {
+    name: 'workspace-edit',
+    hasModelTurn: true,
+    recorded: true,
+    pinsHeader: true,
+    pinsNativeWindowsStdout: true,
+    headerClass: 'fs',
+    configPath: FS_CONFIG,
+  },
   { name: 'fs-read', hasModelTurn: true, recorded: true, headerClass: 'fs', configPath: FS_CONFIG },
   { name: 'fs-write', hasModelTurn: true, recorded: true, headerClass: 'fs', configPath: FS_CONFIG },
   { name: 'fs-edit', hasModelTurn: true, recorded: true, headerClass: 'fs', configPath: FS_CONFIG },
diff --git a/examples/acp-agent/tests/snapshots/workspace-edit/stdout.golden.windows.jsonl b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.golden.windows.jsonl
new file mode 100644
index 0000000000..5f8762adcd
--- /dev/null
+++ b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.golden.windows.jsonl
@@ -0,0 +1,132 @@
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
+{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"Sets this session's sandbox and approval behavior.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"1"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Read"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" file"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" greeting"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".txt"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"2"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Append"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" word"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" WORLD"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" as"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" second"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" line"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"3"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Read"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" file"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" back"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" cat"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" confirm"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"4"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Reply"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" D"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Let"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" start"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" by"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reading"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" file"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" see"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" its"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" contents"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_OjRFB4zvxu6UALDjytZD0978","title":"Read greeting.txt","kind":"read","status":"in_progress","locations":[{"path":"greeting.txt","line":1}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_OjRFB4zvxu6UALDjytZD0978","status":"completed","content":[{"type":"content","content":{"type":"text","text":"<path>{{cwd}}\\greeting.txt</path>\n<type>file</type>\n<content>\n1: hello\n\n(End of file - total 1 lines)\n</content>"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" file"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" contains"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"hello"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" on"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" one"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" line"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Now"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" I"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" need"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" append"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" second"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" line"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WOR"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"LD"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" it"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Then"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" cat"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" it"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" confirm"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_IUUvbNiPcnwhVL8ErEFS4806","title":"printf '\\nWORLD' >> greeting.txt","kind":"execute","status":"in_progress","rawInput":"printf '\\nWORLD' >> greeting.txt","content":[{"type":"content","content":{"type":"text","text":"Append newline and WORLD to greeting.txt"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_IUUvbNiPcnwhVL8ErEFS4806","status":"completed","content":[{"type":"content","content":{"type":"text","text":"```console\n(no output)\n```"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Good"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":","}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" now"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" let"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" read"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" file"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" back"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" cat"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_Wo4H7tFNheZJWKVDrAHK5851","title":"cat greeting.txt","kind":"execute","status":"in_progress","rawInput":"cat greeting.txt","content":[{"type":"content","content":{"type":"text","text":"Read greeting.txt to confirm"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_Wo4H7tFNheZJWKVDrAHK5851","status":"completed","content":[{"type":"content","content":{"type":"text","text":"```console\nhello\n\nWORLD\n```"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" file"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" now"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" has"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" two"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" lines"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"1"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" hello"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"2"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" WORLD"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n\n"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"I"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" can"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" D"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"D"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"ONE"}}}}
+{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}}
diff --git a/packages/support/acp-snapshot/README.md b/packages/support/acp-snapshot/README.md
index 222d572043..9969eadb46 100644
--- a/packages/support/acp-snapshot/README.md
+++ b/packages/support/acp-snapshot/README.md
@@ -4,9 +4,9 @@ The ACP snapshot suite kit: the shared machinery behind the keyless snapshot tie
 
 Three layers, importable separately:
 
-- **`runScenario` (harness)** — boots the real agent bin as a subprocess via tsx (unbuilt, Loader path), drives it over ACP JSON-RPC stdio from a deterministic `input.json` script, tees raw stdout for the golden + purity check, and harvests every persisted session JSONL (parent + subagent children, primary-first) after a graceful stdin-EOF shutdown. Parameterized by `AgentUnderTest` (`binScript`, `configPath`, `tsconfigPath` — absolute paths; the subprocess cwd is a temp dir outside the repo). Startup failures preserve captured agent stderr in the rejected diagnostic.
-- **Normalizers** — pure functions turning the two captured surfaces into stable text: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs/cwd → tokens; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept), `scrubSystemPrompts` (prompt text → `{{system}}`), `scrubToolSchemas` (schema bulk → `{{tools}}`), and `scrubRequestHeaders` (all header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}` outside each pin, structure kept — [pinned-header RFC](../../../docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
-- **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario golden + re-persisted-log compares, record/refresh fixture write-back, rejection of structured `UNKNOWN_TOOL` results, the per-header-class pin (`system-prompt.golden.md` plus `tool-schemas.golden.json`) with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin per class, every JSONL prompt/schema-scrubbed, non-pinning fixtures fully header-scrubbed). Must be called at vitest collection time.
+- **`runScenario` (harness)** — boots the real agent bin in the selected example mode: source under tsx or built `lib` under plain Node. It drives ACP JSON-RPC stdio from a deterministic `input.json` script, tees raw stdout for the golden and purity check, and harvests every persisted session JSONL (parent and subagent children, primary-first) after graceful stdin EOF. `AgentUnderTest` supplies absolute `binScript`, `configPath`, and `tsconfigPath` paths because the subprocess cwd is a temp directory outside the repo. Startup failures preserve captured agent stderr in the rejected diagnostic.
+- **Normalizers** — pure functions turning the two captured surfaces into stable text: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs/cwd → tokens; cwd-rooted separators → `/` for shared goldens; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept, the same cwd-path policy), `scrubSystemPrompts` (prompt text → `{{system}}`), `scrubToolSchemas` (schema bulk → `{{tools}}`), and `scrubRequestHeaders` (all header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}` outside each pin, structure kept — [pinned-header RFC](../../../docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
+- **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario shared golden + re-persisted-log compares, optional Windows-native stdout sidecars, record/refresh fixture write-back, rejection of structured `UNKNOWN_TOOL` results, the per-header-class pin (`system-prompt.golden.md` plus `tool-schemas.golden.json`) with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin per class, every JSONL prompt/schema-scrubbed, non-pinning fixtures fully header-scrubbed). Must be called at vitest collection time.
 
 A consuming `*.snapshot.ts` is the scenario table plus one factory call:
 
@@ -37,6 +37,8 @@ defineAcpSnapshotSuite({
 
 A scenario booting a differently-composed tree sets its own `configPath` (an overlay whose basename still ends in `cordis.yml`, so the bin's replay swap finds the sibling `*cordis.snapshot.yml`) and, when that composition changes the request header, its own `headerClass` with its own pinning scenario — the acp-agent example's Code Mode and filesystem scenarios are templates. Each pinning directory stores the normalized full prompt sequence in generated `system-prompt.golden.md` and the corresponding full tool-schema sequence in generated `tool-schemas.golden.json`; `session.jsonl` stores `"system":"{{system}}","tools":"{{tools}}"` while retaining config, reason, and any model-visible prefix. A pin with legitimate mid-run header changes declares `expectedHeaderChanges`, which fixes the length of both sidecar sequences.
 
+Every scenario compares `stdout.golden.jsonl` with cwd-rooted separators canonicalized to `/`. A scenario may set `pinsNativeWindowsStdout` to add a Windows-only comparison against the complete `stdout.golden.windows.jsonl`; the shared golden still runs first on Windows, and the fixture guard requires the sidecar exactly when declared.
+
 Examples use a `cordis.snapshot.yml` overlay with [`dsh-llm-replay`](../llm-replay/README.md). Recording calls the live model and updates model fixtures; keyless refresh replays those fixtures and updates derived stdout, session-log, prompt, and tool-schema snapshots. See the [snapshot RFC](../../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md).
 
 `suite.ts` imports Vitest, so use this package only inside a Vitest run. The ACP-specific script queues permission answers by stable option kind and maps them to current option ids; a missing answer cancels, while an unavailable kind fails the scenario after cancelling the agent request. It can also set session config options or assert that unknown ids and values are rejected in the transcript.
@@ -48,4 +50,4 @@ None, as this test-only harness records, normalizes, and compares ACP transcript
 ## Known Limitations and Deferred Work
 
 - **Session harvest is JSONL-only** — `runScenario` collects persisted `.jsonl` logs, so an example composed over the SQLite persistence backend has no snapshot path.
-- **The subprocess boots the unbuilt tsx/Loader path only** — the built-bin artifact is guarded by the separate `built-bin` e2e smokes, never by this tier.
+- **Built mode requires current artifacts** — run `pnpm run build` before selecting `DSH_EXAMPLE_MODE=lib`; source mode remains the zero-build path.
diff --git a/packages/support/acp-snapshot/src/harness.ts b/packages/support/acp-snapshot/src/harness.ts
index e2072b6b17..cf8d7afc27 100644
--- a/packages/support/acp-snapshot/src/harness.ts
+++ b/packages/support/acp-snapshot/src/harness.ts
@@ -150,6 +150,15 @@ export interface RunOptions {
   configPath?: string
 }
 
+/**
+ * Return a fixed-length spill root across POSIX and Windows after Windows adds its drive prefix.
+ * @param platform - the host platform, injectable for unit coverage.
+ * @returns the root-relative snapshot spill directory.
+ */
+export function snapshotSpillRoot(platform: NodeJS.Platform = process.platform): string {
+  return platform === 'win32' ? '/t/dsh-acp-snapshot-spill' : '/tmp/dsh-acp-snapshot-spill'
+}
+
 /**
  * Run a scenario end-to-end against a freshly-spawned subprocess. Owns the
  * child and its temp dirs; always tears them down. Returns the captured stdout
@@ -164,7 +173,7 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise
   const sessionsRoot = await mkdtemp(join(tmpdir(), 'acp-snap-sessions-'))
   // Fixed path length: spill-policy budgets the preview against the REAL path
   // before stdout normalization, so tmpdir() length differences churn goldens.
-  const spillRoot = '/tmp/dsh-acp-snapshot-spill'
+  const spillRoot = snapshotSpillRoot()
   // Everything past the temp-dir creation runs under a try/finally that always
   // removes both dirs — so a failure in workspace seeding, spawn, or any step
   // never leaks them (the "e2e tests own their resources" rule).
diff --git a/packages/support/acp-snapshot/src/index.ts b/packages/support/acp-snapshot/src/index.ts
index bdf8cccaf7..46eac5568b 100644
--- a/packages/support/acp-snapshot/src/index.ts
+++ b/packages/support/acp-snapshot/src/index.ts
@@ -21,7 +21,9 @@ export {
   scrubRequestHeaders,
   scrubSystemPrompts,
   scrubToolSchemas,
+  type CwdPathMode,
   type NormalizeContext,
+  type NormalizeOptions,
 } from './normalize.ts'
 export {
   defineAcpSnapshotSuite,
diff --git a/packages/support/acp-snapshot/src/normalize.ts b/packages/support/acp-snapshot/src/normalize.ts
index 48761864f0..76bd40d610 100644
--- a/packages/support/acp-snapshot/src/normalize.ts
+++ b/packages/support/acp-snapshot/src/normalize.ts
@@ -12,19 +12,33 @@ const SYSTEM = '{{system}}'
 const TOOLS = '{{tools}}'
 const MESSAGE_PREFIX = '{{messagePrefix}}'
 
+/** A cwd-rooted path after volatile cwd replacement, through its last separator-delimited segment. */
+const CWD_ROOTED_PATH_RE = /\{\{cwd\}\}(?:[\\/][^\s<>"'`]+)+/g
+const PATH_TAG_RE = /(<path>)([^<]*)(<\/path>)/g
+const ADDITIONAL_INSTRUCTIONS_PATH_RE = /(Additional instructions from: )([^\r\n]+)/g
+
 /** A UUID v4 string, the shape `randomUUID()` produces for session ids. */
 const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi
 const LOCAL_SPILL_PATH_RE = new RegExp(
-  String.raw`\{\{cwd\}\}/\.spill/session-[0-9a-f]{12}/[0-9a-f]{12}-([A-Za-z0-9._~-]+?)`
+  String.raw`\{\{cwd\}\}[\\/]\.spill[\\/]session-[0-9a-f]{12}[\\/][0-9a-f]{12}-([A-Za-z0-9._~-]+?)`
   + String.raw`(?=\. Use read with offset/limit|[\s)]|$)`,
   'g',
 )
 const SNAPSHOT_SPILL_PATH_RE = new RegExp(
-  String.raw`/tmp/dsh-acp-snapshot-spill/session-[0-9a-f]{12}/[0-9a-f]{12}-([A-Za-z0-9._~-]+?)`
+  String.raw`(?:[A-Za-z]:)?[\\/](?:tmp|t)[\\/]dsh-acp-snapshot-spill[\\/]session-[0-9a-f]{12}[\\/][0-9a-f]{12}-([A-Za-z0-9._~-]+?)`
   + String.raw`(?=\. Use read with offset/limit|[\s)]|$)`,
   'g',
 )
 
+/** Convert separators only inside generated path-bearing text markers. */
+function canonicalizeEmbeddedPaths(value: string): string {
+  return value
+    .replace(PATH_TAG_RE, (_match, open: string, path: string, close: string) =>
+      `${open}${path.replaceAll('\\', '/')}${close}`)
+    .replace(ADDITIONAL_INSTRUCTIONS_PATH_RE, (_match, prefix: string, path: string) =>
+      `${prefix}${path.replaceAll('\\', '/')}`)
+}
+
 /** Inputs the normalizers need to recognize a run's volatile values. */
 export interface NormalizeContext {
   /** The session id(s) the run issued — replaced with `{{sessionId}}`. */
@@ -33,13 +47,28 @@ export interface NormalizeContext {
   cwd: string
 }
 
+/** How cwd-rooted path separators are represented after the cwd is tokenized. */
+export type CwdPathMode = 'canonical' | 'native'
+
+/** Optional controls shared by stdout and session-log normalization. */
+export interface NormalizeOptions {
+  /** Use `/` for shared goldens, or preserve captured separators for a platform-specific golden. */
+  cwdPathMode?: CwdPathMode
+}
+
 /** Replace cwd, session ids, and any stray UUID with stable tokens in a string. */
-function scrubString(value: string, ctx: NormalizeContext): string {
+function scrubString(value: string, ctx: NormalizeContext, cwdPathMode: CwdPathMode): string {
   let out = value
   // cwd first (longest, most specific), then explicit session ids, then any
   // residual UUID (covers ids that appear in places we didn't enumerate).
   out = out.split(ctx.cwd).join(CWD)
   out = out.split(`/private${CWD}`).join(CWD)
+  if (cwdPathMode === 'canonical') {
+    // Restrict separator conversion to paths rooted at the cwd token. A global
+    // backslash rewrite would corrupt regexes, commands, and model-authored text.
+    out = out.replace(CWD_ROOTED_PATH_RE, path => path.replaceAll('\\', '/'))
+    out = canonicalizeEmbeddedPaths(out)
+  }
   out = out.replace(LOCAL_SPILL_PATH_RE, (_match, name: string) => `{{spillLocator:${name}}}`)
   out = out.replace(SNAPSHOT_SPILL_PATH_RE, (_match, name: string) => `{{spillLocator:${name}}}`)
   for (const id of ctx.sessionIds) out = out.split(id).join(SESSION_ID)
@@ -48,12 +77,15 @@ function scrubString(value: string, ctx: NormalizeContext): string {
 }
 
 /** Recursively scrub a parsed JSON value (strings replaced; structure kept). */
-function scrubValue(value: unknown, ctx: NormalizeContext): unknown {
-  if (typeof value === 'string') return scrubString(value, ctx)
-  if (Array.isArray(value)) return value.map(v => scrubValue(v, ctx))
+function scrubValue(value: unknown, ctx: NormalizeContext, cwdPathMode: CwdPathMode, key?: string): unknown {
+  if (typeof value === 'string') {
+    const scrubbed = scrubString(value, ctx, cwdPathMode)
+    return cwdPathMode === 'canonical' && key === 'path' ? scrubbed.replaceAll('\\', '/') : scrubbed
+  }
+  if (Array.isArray(value)) return value.map(v => scrubValue(v, ctx, cwdPathMode))
   if (value !== null && typeof value === 'object') {
     const out: Record<string, unknown> = {}
-    for (const [k, v] of Object.entries(value)) out[k] = scrubValue(v, ctx)
+    for (const [k, v] of Object.entries(value)) out[k] = scrubValue(v, ctx, cwdPathMode, k)
     return out
   }
   return value
@@ -67,9 +99,15 @@ function scrubValue(value: unknown, ctx: NormalizeContext): unknown {
  *
  * @param rawStdout The captured stdout bytes, decoded utf8.
  * @param ctx The run's volatile values to scrub.
+ * @param options Separator output controls; shared canonical paths are the default.
  * @returns The normalized NDJSON transcript, one frame per line.
  */
-export function normalizeStdout(rawStdout: string, ctx: NormalizeContext): string {
+export function normalizeStdout(
+  rawStdout: string,
+  ctx: NormalizeContext,
+  options: NormalizeOptions = {},
+): string {
+  const cwdPathMode = options.cwdPathMode ?? 'canonical'
   const lines = rawStdout.split('\n').filter(line => line.trim().length > 0)
   // Map each distinct JSON-RPC id (request/response correlate by id) to a stable
   // sequence number, in first-seen order, so id churn doesn't perturb the golden.
@@ -85,7 +123,7 @@ export function normalizeStdout(rawStdout: string, ctx: NormalizeContext): strin
     if ('id' in frame && frame.id !== undefined && frame.id !== null) {
       frame.id = stableId(frame.id)
     }
-    return scrubValue(frame, ctx) as Record<string, unknown>
+    return scrubValue(frame, ctx, cwdPathMode) as Record<string, unknown>
   })
   return frames.map(f => JSON.stringify(f)).join('\n') + '\n'
 }
@@ -99,9 +137,15 @@ export function normalizeStdout(rawStdout: string, ctx: NormalizeContext): strin
  *
  * @param rawLog The raw session `.jsonl` content.
  * @param ctx The run's volatile values to scrub.
+ * @param options Separator output controls; shared canonical paths are the default.
  * @returns The normalized JSONL log, one record per line.
  */
-export function normalizeSessionLog(rawLog: string, ctx: NormalizeContext): string {
+export function normalizeSessionLog(
+  rawLog: string,
+  ctx: NormalizeContext,
+  options: NormalizeOptions = {},
+): string {
+  const cwdPathMode = options.cwdPathMode ?? 'canonical'
   const lines = rawLog.split('\n').filter(line => line.trim().length > 0)
   const records = lines.map((line) => {
     const record = JSON.parse(line) as Record<string, unknown>
@@ -119,7 +163,7 @@ export function normalizeSessionLog(rawLog: string, ctx: NormalizeContext): stri
         if ('durationMs' in data) data.durationMs = 0
       }
     }
-    return scrubValue(record, ctx) as Record<string, unknown>
+    return scrubValue(record, ctx, cwdPathMode) as Record<string, unknown>
   })
   return records.map(r => JSON.stringify(r)).join('\n') + '\n'
 }
diff --git a/packages/support/acp-snapshot/src/suite.ts b/packages/support/acp-snapshot/src/suite.ts
index 322439bb01..7fdc70dc67 100644
--- a/packages/support/acp-snapshot/src/suite.ts
+++ b/packages/support/acp-snapshot/src/suite.ts
@@ -21,6 +21,7 @@ import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import { type AgentUnderTest, type HarvestedLog, type InputScript, runScenario } from './harness.ts'
 import {
+  type CwdPathMode,
   type NormalizeContext,
   normalizeSessionLog,
   normalizeStdout,
@@ -35,6 +36,9 @@ const SYSTEM_PROMPT_SNAPSHOT = 'system-prompt.golden.md'
 /** The structured tool-schema snapshot beside each header-pinning fixture. */
 const TOOL_SCHEMAS_SNAPSHOT = 'tool-schemas.golden.json'
 
+/** The optional full Windows-native stdout transcript. */
+const WINDOWS_STDOUT_SNAPSHOT = 'stdout.golden.windows.jsonl'
+
 /** Stable session-log token standing in for the sidecar's initial schemas. */
 const TOOLS_TOKEN = '{{tools}}'
 
@@ -108,6 +112,35 @@ export interface Scenario {
    * {@link headerClass}.
    */
   configPath?: string
+  /**
+   * Whether Windows additionally compares stdout with native separators against
+   * `stdout.golden.windows.jsonl`. The shared canonical stdout golden is still
+   * compared on every platform, and the fixture guard requires this sidecar
+   * exactly when the option is set.
+   */
+  pinsNativeWindowsStdout?: boolean
+}
+
+/** One stdout golden selected for a platform run. */
+interface StdoutGoldenVariant {
+  file: string
+  cwdPathMode: CwdPathMode
+}
+
+/**
+ * Select the shared stdout golden plus any platform-native assertion declared by a scenario.
+ *
+ * @param scenario The scenario whose stdout contract is being selected.
+ * @param platform The running Node platform, injectable for unit coverage.
+ * @returns The ordered golden variants: shared canonical first, then optional Windows native.
+ */
+export function stdoutGoldenVariants(
+  scenario: Scenario,
+  platform: NodeJS.Platform = process.platform,
+): StdoutGoldenVariant[] {
+  const canonical: StdoutGoldenVariant = { file: 'stdout.golden.jsonl', cwdPathMode: 'canonical' }
+  if (platform !== 'win32' || scenario.pinsNativeWindowsStdout !== true) return [canonical]
+  return [canonical, { file: WINDOWS_STDOUT_SNAPSHOT, cwdPathMode: 'native' }]
 }
 
 /** One suite's inputs: the agent to boot, where its fixtures live, and its scenario table. */
@@ -530,11 +563,13 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
           }
         }
 
-        const stdout = normalizeStdout(result.rawStdout, ctx)
-        if (REFRESHING) {
-          await writeFile(join(dir, 'stdout.golden.jsonl'), stdout)
+        for (const golden of stdoutGoldenVariants(scenario)) {
+          const stdout = normalizeStdout(result.rawStdout, ctx, { cwdPathMode: golden.cwdPathMode })
+          if (REFRESHING) {
+            await writeFile(join(dir, golden.file), stdout)
+          }
+          await expect(stdout, `${golden.file} mismatch`).toMatchFileSnapshot(join(dir, golden.file))
         }
-        await expect(stdout).toMatchFileSnapshot(join(dir, 'stdout.golden.jsonl'))
 
         // A model turn always produces a log worth comparing; a hook scenario can
         // produce one without a model turn (a `rejected` turn carrying `hook/*`).
@@ -621,10 +656,14 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
 
     it('every registered scenario has its required fixture files', () => {
       // Every scenario has an input script and an stdout golden.
-      for (const { name, overridden, childSessions, pinsHeader } of scenarios) {
+      for (const { name, overridden, childSessions, pinsHeader, pinsNativeWindowsStdout } of scenarios) {
         const dir = join(snapshotsDir, name)
         expect(existsSync(join(dir, 'input.json')), `${name}/input.json`).toBe(true)
         expect(existsSync(join(dir, 'stdout.golden.jsonl')), `${name}/stdout.golden.jsonl`).toBe(true)
+        expect(
+          existsSync(join(dir, WINDOWS_STDOUT_SNAPSHOT)),
+          `${name}/${WINDOWS_STDOUT_SNAPSHOT} presence must match \`pinsNativeWindowsStdout\``,
+        ).toBe(pinsNativeWindowsStdout === true)
         expect(existsSync(join(dir, 'session.jsonl')), `${name}/session.jsonl`).toBe(true)
         expect(existsSync(join(dir, 'replay.override.json')), `${name}/replay.override.json presence must match \`overridden\``)
           .toBe(overridden === true)
diff --git a/packages/support/acp-snapshot/tests/harness.spec.ts b/packages/support/acp-snapshot/tests/harness.spec.ts
index d141fb1f09..35fcb21d09 100644
--- a/packages/support/acp-snapshot/tests/harness.spec.ts
+++ b/packages/support/acp-snapshot/tests/harness.spec.ts
@@ -3,7 +3,7 @@ import { tmpdir } from 'node:os'
 import { delimiter, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { afterAll, describe, expect, it } from 'vitest'
-import { runScenario, type AgentUnderTest, type InputStep } from '../src/harness.ts'
+import { runScenario, snapshotSpillRoot, type AgentUnderTest, type InputStep } from '../src/harness.ts'
 
 /**
  * Unit tests for the subprocess harness, driven through the REAL spawn path
@@ -39,6 +39,11 @@ async function scenario(behavior: object): Promise<{ dir: string; fixtureFile: s
 
 const boot: InputStep[] = [{ op: 'initialize' }, { op: 'newSession' }]
 
+it('keeps the resolved snapshot spill root length stable across platforms', () => {
+  expect(snapshotSpillRoot('linux')).toBe('/tmp/dsh-acp-snapshot-spill')
+  expect(snapshotSpillRoot('win32')).toBe('/t/dsh-acp-snapshot-spill')
+})
+
 describe('runScenario', () => {
   it('includes agent stderr when the ACP connection closes during startup', { timeout: 20_000 }, async () => {
     const { fixtureFile } = await scenario({ failOnBoot: true, stderrNote: 'fake agent requested startup failure' })
diff --git a/packages/support/acp-snapshot/tests/normalize.spec.ts b/packages/support/acp-snapshot/tests/normalize.spec.ts
index 2beaba5114..fed086fec7 100644
--- a/packages/support/acp-snapshot/tests/normalize.spec.ts
+++ b/packages/support/acp-snapshot/tests/normalize.spec.ts
@@ -44,6 +44,56 @@ describe('normalizeStdout', () => {
     expect(out).not.toContain(ctx.sessionIds[0] as string)
   })
 
+  it('canonicalizes only cwd-rooted path separators', () => {
+    const windowsCtx: NormalizeContext = {
+      sessionIds: [],
+      cwd: String.raw`C:\Users\runner\AppData\Local\Temp\acp-snapshot`,
+    }
+    const raw = JSON.stringify({
+      jsonrpc: '2.0',
+      method: 'session/update',
+      params: {
+        path: `${windowsCtx.cwd}\\nested\\proof.txt`,
+        regex: String.raw`\d+\w+`,
+        command: String.raw`printf "\\n"`,
+      },
+    })
+    const frame = JSON.parse(normalizeStdout(raw, windowsCtx)) as {
+      params: { path: string; regex: string; command: string }
+    }
+    expect(frame.params).toEqual({
+      path: '{{cwd}}/nested/proof.txt',
+      regex: String.raw`\d+\w+`,
+      command: String.raw`printf "\\n"`,
+    })
+  })
+
+  it('canonicalizes generated relative path fields and text markers without rewriting other text', () => {
+    const raw = JSON.stringify({
+      path: String.raw`nested\AGENTS.md`,
+      content: String.raw`<path>.\nested\task.txt</path>
+Additional instructions from: nested\AGENTS.md`,
+      regex: String.raw`\d+\w+`,
+    })
+    const frame = JSON.parse(normalizeStdout(raw, { sessionIds: [], cwd: '/unused' })) as {
+      path: string
+      content: string
+      regex: string
+    }
+    expect(frame).toEqual({
+      path: 'nested/AGENTS.md',
+      content: '<path>./nested/task.txt</path>\nAdditional instructions from: nested/AGENTS.md',
+      regex: String.raw`\d+\w+`,
+    })
+  })
+
+  it('can preserve native cwd-rooted separators for a platform golden', () => {
+    const windowsCtx: NormalizeContext = { sessionIds: [], cwd: String.raw`C:\work\snapshot` }
+    const raw = JSON.stringify({ path: `${windowsCtx.cwd}\\nested\\proof.txt` })
+    const frame = JSON.parse(normalizeStdout(raw, windowsCtx, { cwdPathMode: 'native' })) as { path: string }
+    expect(frame.path).toBe(String.raw`{{cwd}}\nested\proof.txt`)
+  })
+
   it('scrubs a stray UUID not in the known list', () => {
     const raw = JSON.stringify({ jsonrpc: '2.0', method: 'x', params: { id: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' } })
     expect(normalizeStdout(raw, ctx)).toContain('{{sessionId}}')
@@ -139,6 +189,33 @@ describe('normalizeSessionLog', () => {
     expect(out).not.toContain('/tmp/dsh-acp-snapshot-spill')
   })
 
+  it('scrubs fixed snapshot spill paths with Windows drive and separators', () => {
+    const ev = JSON.stringify({
+      type: 'tool/result', seq: 2, time: 5,
+      data: {
+        content: [{
+          type: 'text',
+          text: String.raw`Full formatted result stored at: C:\t\dsh-acp-snapshot-spill\session-c22bc3f1d2af\8a7b6c5d4e3f-bash.txt. Use read with offset/limit, or grep this path to search within it.`,
+        }],
+      },
+    })
+    const out = normalizeSessionLog(`${header({ cwd: ctx.cwd })}\n${ev}\n`, ctx)
+    expect(out).toContain('{{spillLocator:bash.txt}}')
+    expect(out).not.toContain('C:\\t\\dsh-acp-snapshot-spill')
+  })
+
+  it('shares cwd-rooted path handling with stdout normalization', () => {
+    const windowsCtx: NormalizeContext = { sessionIds: [], cwd: String.raw`C:\work\snapshot` }
+    const ev = JSON.stringify({
+      type: 'tool/result', seq: 2, time: 5,
+      data: { path: `${windowsCtx.cwd}\\nested\\proof.txt` },
+    })
+    expect(normalizeSessionLog(`${header({ cwd: windowsCtx.cwd })}\n${ev}\n`, windowsCtx))
+      .toContain('{{cwd}}/nested/proof.txt')
+    expect(normalizeSessionLog(`${header({ cwd: windowsCtx.cwd })}\n${ev}\n`, windowsCtx, { cwdPathMode: 'native' }))
+      .toContain(String.raw`{{cwd}}\\nested\\proof.txt`)
+  })
+
   it('scrubs the session id in the header', () => {
     const out = normalizeSessionLog(`${header({ id: ctx.sessionIds[0] })}\n`, ctx)
     expect(out).toContain('{{sessionId}}')
diff --git a/packages/support/acp-snapshot/tests/suite.spec.ts b/packages/support/acp-snapshot/tests/suite.spec.ts
index c2007321de..24812029dc 100644
--- a/packages/support/acp-snapshot/tests/suite.spec.ts
+++ b/packages/support/acp-snapshot/tests/suite.spec.ts
@@ -18,6 +18,7 @@ import {
   refreshFixtureReplacements,
   restorePinnedToolSchemas,
   stabilizeRefreshLog,
+  stdoutGoldenVariants,
   unknownToolCallIds,
 } from '../src/suite.ts'
 
@@ -189,6 +190,31 @@ describe('childFixturePaths', () => {
   })
 })
 
+describe('stdoutGoldenVariants', () => {
+  const scenario: Scenario = {
+    name: 'windows-native',
+    hasModelTurn: true,
+    recorded: true,
+    pinsNativeWindowsStdout: true,
+  }
+
+  it('adds the native sidecar after the shared golden on Windows', () => {
+    expect(stdoutGoldenVariants(scenario, 'win32')).toEqual([
+      { file: 'stdout.golden.jsonl', cwdPathMode: 'canonical' },
+      { file: 'stdout.golden.windows.jsonl', cwdPathMode: 'native' },
+    ])
+  })
+
+  it('keeps only the shared golden on other platforms or without the declaration', () => {
+    expect(stdoutGoldenVariants(scenario, 'linux')).toEqual([
+      { file: 'stdout.golden.jsonl', cwdPathMode: 'canonical' },
+    ])
+    expect(stdoutGoldenVariants({ ...scenario, pinsNativeWindowsStdout: false }, 'win32')).toEqual([
+      { file: 'stdout.golden.jsonl', cwdPathMode: 'canonical' },
+    ])
+  })
+})
+
 describe('fixtureContext', () => {
   it('reads the fixture header id and cwd', () => {
     const ctx = fixtureContext('{"type":"session","id":"abc","cwd":"/rec"}\n{"type":"turn/start"}\n')

From b5fa2cb2b8c3a320f773e21695daa7a8b222cc87 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 17 Jul 2026 12:30:16 +0800
Subject: [PATCH 14/74] test(windows): skip unsupported SDK test surfaces

---
 .../sdk/create-sdk/tests/create.snapshot.ts    |  2 +-
 vitest.config.ts                               | 18 +++++++++++++++++-
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/packages/sdk/create-sdk/tests/create.snapshot.ts b/packages/sdk/create-sdk/tests/create.snapshot.ts
index a5ea46db53..4733653a0d 100644
--- a/packages/sdk/create-sdk/tests/create.snapshot.ts
+++ b/packages/sdk/create-sdk/tests/create.snapshot.ts
@@ -71,7 +71,7 @@ class RecordingPort implements PromptPort {
   }
 }
 
-describe('create-sdk terminal contract', () => {
+describe.skipIf(process.platform === 'win32')('create-sdk terminal contract', () => {
   it('renders package-manager-specific setup commands', () => {
     const model = packageManagerTemplateModel(createPackageManager('yarn', '4.0.0'))
     expect(CREATE_TEMPLATES.installQuestion.render(model)).toBe('Run yarn install and then build the project?\n')
diff --git a/vitest.config.ts b/vitest.config.ts
index c0946e2e10..1001b7daa3 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -1,6 +1,16 @@
 import tsconfigPaths from 'vite-tsconfig-paths'
 import { defineConfig } from 'vitest/config'
 
+const windowsUnsupportedPackages = process.platform === 'win32'
+  ? [
+      'packages/bash/*',
+      'packages/hooks/*',
+      'packages/sandbox/sandbox-local',
+      'packages/sdk/create-sdk',
+      'packages/sdk/helper',
+    ]
+  : []
+
 export default defineConfig({
   // Native path resolution reads each package's nearest tsconfig, but only the root defines
   // workspace paths. Keep this plugin pinned to the root map so unbuilt bare package imports resolve
@@ -8,6 +18,7 @@ export default defineConfig({
   plugins: [tsconfigPaths({ projects: ['./tsconfig.json'] })],
   test: {
     include: ['packages/*/*/tests/**/*.spec.ts', 'examples/*/tests/**/*.spec.ts', 'scripts/**/*.spec.ts'],
+    exclude: windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`),
     coverage: {
       provider: 'v8',
       // Coverage measures OUR runtime source. Types-only files carry no
@@ -16,7 +27,12 @@ export default defineConfig({
       include: ['packages/*/*/src/**/*.ts'],
       // Types-only files have no runtime coverage. Importing self-executing bins/workers would boot
       // them inside the unit process, so real subprocess/Worker tests cover their thin entry glue.
-      exclude: ['packages/*/*/src/types.ts', 'packages/*/*/src/bin.ts', 'packages/*/*/src/worker.ts'],
+      exclude: [
+        'packages/*/*/src/types.ts',
+        'packages/*/*/src/bin.ts',
+        'packages/*/*/src/worker.ts',
+        ...windowsUnsupportedPackages.map(path => `${path}/src/**/*.ts`),
+      ],
       // 100% or it doesn't merge (docs/testing.md: excessive tests are welcome).
       // Per-file so a well-covered big file can't subsidize a bare one.
       // Every v8 ignore comment must carry a reason — see the quality-gates RFC

From 228f6e3867ce4cdbbd2d4edb85ef132c91e5634c Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 17 Jul 2026 15:44:19 +0800
Subject: [PATCH 15/74] test(windows): skip POSIX-only assertions

---
 .../workspace-context/tests/workspace-context.spec.ts        | 2 +-
 packages/spill/spill-local/tests/spill-local.spec.ts         | 2 +-
 packages/subagent/subagent-acp/tests/subagent-acp.spec.ts    | 2 +-
 .../subagent-subprocess/tests/subagent-subprocess.spec.ts    | 5 +++--
 4 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts
index b3a9947221..5f04b3a485 100644
--- a/packages/context/workspace-context/tests/workspace-context.spec.ts
+++ b/packages/context/workspace-context/tests/workspace-context.spec.ts
@@ -2403,7 +2403,7 @@ describe('dynamic nested workspace context injection', () => {
     }
   })
 
-  it('skips unreadable nested instruction files without attaching empty context', async () => {
+  it.skipIf(process.platform === 'win32')('skips unreadable nested instruction files without attaching empty context', async () => {
     const root = await tempRepo()
     const home = await tempRepo()
     try {
diff --git a/packages/spill/spill-local/tests/spill-local.spec.ts b/packages/spill/spill-local/tests/spill-local.spec.ts
index d73fca9fe3..b4abc6e3d6 100644
--- a/packages/spill/spill-local/tests/spill-local.spec.ts
+++ b/packages/spill/spill-local/tests/spill-local.spec.ts
@@ -84,7 +84,7 @@ describe('saveTextFile', () => {
     expect(saved.path.includes('/..')).toBe(false)
   })
 
-  it('creates the session dir with owner-only permissions', async () => {
+  it.skipIf(process.platform === 'win32')('creates the session dir with owner-only permissions', async () => {
     const saved = await saveTextFile({ root, sessionId: 'sess-1', suggestedName: 'r.txt', content: 'x' })
     // 0o700 dir, 0o600 file (masked by umask, but the owner bits must hold).
     expect(statSync(dirname(saved.path)).mode & 0o700).toBe(0o700)
diff --git a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts
index bfc8476bae..e3fd3eda48 100644
--- a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts
+++ b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts
@@ -263,7 +263,7 @@ describe('dsh-subagent-acp', () => {
     }
   })
 
-  it('escalates to SIGTERM for a child that ignores EOF but is not SIGTERM-trapping', async () => {
+  it.skipIf(process.platform === 'win32')('escalates to SIGTERM for a child that ignores EOF but is not SIGTERM-trapping', async () => {
     // A child that keeps its loop alive past stdin EOF (so the graceful window
     // times out) but exits cooperatively on SIGTERM must die on the SIGTERM tier
     // — dispose returns there, never reaching the SIGKILL tier. The child touches
diff --git a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts
index bdc0260c73..8ed3891578 100644
--- a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts
+++ b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts
@@ -258,8 +258,9 @@ describe('createIsolatedConfigDir', () => {
       expect(dir.path.startsWith(join(tmpdir(), 'dsh-subagent-subprocess-test-'))).toBe(true)
       const st = await stat(dir.path)
       expect(st.isDirectory()).toBe(true)
-      // Private (0700) per the defensive-patterns temp-dir rule.
-      expect(st.mode & 0o777).toBe(0o700)
+      // Windows reports synthetic POSIX mode bits; privacy comes from the
+      // inherited directory ACL rather than chmod-compatible mode bits.
+      if (process.platform !== 'win32') expect(st.mode & 0o777).toBe(0o700)
     } finally {
       await dir.remove()
     }

From 7e620db8ba470cc48b44c8a1887208b03206bd3a Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 17 Jul 2026 21:08:59 +0800
Subject: [PATCH 16/74] test(windows): use host path semantics

---
 .../tests/workspace-context.spec.ts           | 46 +++++++++----------
 .../fs/tool-fs-search/tests/tools.spec.ts     |  7 +--
 .../spill-local/tests/spill-local.spec.ts     |  7 +--
 packages/util/paths/tests/paths.spec.ts       |  4 +-
 4 files changed, 33 insertions(+), 31 deletions(-)

diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts
index 5f04b3a485..9de003ae8d 100644
--- a/packages/context/workspace-context/tests/workspace-context.spec.ts
+++ b/packages/context/workspace-context/tests/workspace-context.spec.ts
@@ -1,5 +1,5 @@
 import { chmod, mkdtemp, mkdir, rm, stat, symlink, utimes, writeFile } from 'node:fs/promises'
-import { dirname, join } from 'node:path'
+import { dirname, join, resolve } from 'node:path'
 import { tmpdir } from 'node:os'
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
@@ -61,7 +61,7 @@ class RecordingFileSystem extends FileSystem {
   override async resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget> {
     if (opts?.signal !== undefined) this.signals.push(opts.signal)
     opts?.signal?.throwIfAborted()
-    const absolute = join(opts?.cwd ?? '/', path)
+    const absolute = resolve(opts?.cwd ?? '/', path)
     return { targetKey: FsTargetKey(absolute), displayPath: absolute }
   }
 
@@ -277,8 +277,8 @@ describe('workspace context instruction discovery', () => {
       expect(files.map(file => file.displayPath)).toEqual([
         '$DSH_HOME/AGENTS.md',
         'AGENTS.md',
-        'packages/CLAUDE.md',
-        'packages/app/AGENTS.md',
+        join('packages', 'CLAUDE.md'),
+        join('packages', 'app', 'AGENTS.md'),
       ])
       expect(files.map(file => file.absolutePath)).not.toContain(join(root, 'CLAUDE.md'))
     } finally {
@@ -336,7 +336,7 @@ describe('workspace context instruction discovery', () => {
     }
   })
 
-  it('skips a file that becomes unreadable after discovery without failing the request', async () => {
+  it.skipIf(process.platform === 'win32')('skips a file that becomes unreadable after discovery without failing the request', async () => {
     const root = await tempRepo()
     const home = await tempRepo()
     try {
@@ -932,7 +932,7 @@ describe('workspace context request injection', () => {
       await composeBaselinePrefix(ctx, agent)
 
       expect(derivedText(agent)).toContain('omitted AGENTS.md')
-      expect(derivedText(agent)).toContain('Instructions from: pkg/AGENTS.md\n\npackage rule')
+      expect(derivedText(agent)).toContain(`Instructions from: ${join('pkg', 'AGENTS.md')}\n\npackage rule`)
     } finally {
       await rm(root, { recursive: true, force: true })
       await rm(home, { recursive: true, force: true })
@@ -1398,7 +1398,7 @@ describe('workspace context request injection', () => {
       await composeBaselinePrefix(ctx, agent)
 
       expect(derivedText(agent)).toContain('Instructions from: AGENTS.md\n\nroot schema default rule')
-      expect(derivedText(agent)).toContain('Instructions from: child/AGENTS.md\n\nchild schema default rule')
+      expect(derivedText(agent)).toContain(`Instructions from: ${join('child', 'AGENTS.md')}\n\nchild schema default rule`)
       await ctx.fiber.dispose()
     } finally {
       await rm(root, { recursive: true, force: true })
@@ -1700,7 +1700,7 @@ describe('dynamic nested workspace context injection', () => {
         changes: [{
           action: 'set',
           scope: 'pkg',
-          path: 'pkg/AGENTS.md',
+          path: join('pkg', 'AGENTS.md'),
         }],
       })
       const meta = workspaceContextOf(result)?.meta
@@ -1714,7 +1714,7 @@ describe('dynamic nested workspace context injection', () => {
       const text = blocksText(workspaceContextOf(result)?.content)
       expect(text).toBe([
         '<system-reminder>',
-        'Additional instructions from: pkg/AGENTS.md',
+        `Additional instructions from: ${join('pkg', 'AGENTS.md')}`,
         '',
         'These instructions apply to work under `pkg`. Use them as guidance when relevant; more specific instructions take precedence. They do not override system, developer, or direct user instructions.',
         '',
@@ -1752,7 +1752,7 @@ describe('dynamic nested workspace context injection', () => {
       })
 
       const text = blocksText(workspaceContextOf(result)?.content)
-      expect(text).toContain('Additional instructions from: pkg/CLAUDE.local.md')
+      expect(text).toContain(`Additional instructions from: ${join('pkg', 'CLAUDE.local.md')}`)
       expect(text).toContain('local package rule')
       expect(text).not.toContain('native package rule')
     } finally {
@@ -1922,11 +1922,11 @@ describe('dynamic nested workspace context injection', () => {
 
       expect(workspaceContextOf(changed)?.meta).toMatchObject({
         kind: 'workspace-instructions',
-        changes: [{ action: 'replace', scope: 'pkg', path: 'pkg/AGENTS.md' }],
+        changes: [{ action: 'replace', scope: 'pkg', path: join('pkg', 'AGENTS.md') }],
       })
       expect(blocksText(workspaceContextOf(changed)?.content)).toBe([
         '<system-reminder>',
-        'Updated instructions from: pkg/AGENTS.md',
+        `Updated instructions from: ${join('pkg', 'AGENTS.md')}`,
         '',
         'This file changed after it was loaded. Use the following content instead of the previously loaded instructions from this file.',
         '',
@@ -1966,11 +1966,11 @@ describe('dynamic nested workspace context injection', () => {
 
       expect(workspaceContextOf(changed)?.meta).toMatchObject({
         changes: [{
-          action: 'replace', scope: 'pkg', path: 'pkg/CLAUDE.md', previousPath: 'pkg/AGENTS.md',
+          action: 'replace', scope: 'pkg', path: join('pkg', 'CLAUDE.md'), previousPath: join('pkg', 'AGENTS.md'),
         }],
       })
-      expect(blocksText(workspaceContextOf(changed)?.content)).toContain('Updated instructions from: pkg/CLAUDE.md')
-      expect(blocksText(workspaceContextOf(changed)?.content)).toContain('The instructions previously loaded from `pkg/AGENTS.md` no longer apply. Use the following content for `pkg` instead.')
+      expect(blocksText(workspaceContextOf(changed)?.content)).toContain(`Updated instructions from: ${join('pkg', 'CLAUDE.md')}`)
+      expect(blocksText(workspaceContextOf(changed)?.content)).toContain(`The instructions previously loaded from \`${join('pkg', 'AGENTS.md')}\` no longer apply. Use the following content for \`pkg\` instead.`)
       expect(blocksText(workspaceContextOf(changed)?.content)).toContain('fallback package rule')
       expect(unchanged.additionalContexts).toBeUndefined()
     } finally {
@@ -2002,11 +2002,11 @@ describe('dynamic nested workspace context injection', () => {
       expect(workspaceContextOf(removed)?.meta).toEqual({
         kind: 'workspace-instructions',
         version: 1,
-        changes: [{ action: 'remove', scope: 'pkg', path: 'pkg/AGENTS.md' }],
+        changes: [{ action: 'remove', scope: 'pkg', path: join('pkg', 'AGENTS.md') }],
       })
       expect(blocksText(workspaceContextOf(removed)?.content)).toBe([
         '<system-reminder>',
-        'Instructions removed: pkg/AGENTS.md',
+        `Instructions removed: ${join('pkg', 'AGENTS.md')}`,
         '',
         'The previously loaded instructions from this file no longer apply.',
         '</system-reminder>',
@@ -2044,9 +2044,9 @@ describe('dynamic nested workspace context injection', () => {
       })
 
       expect(workspaceContextOf(restored)?.meta).toMatchObject({
-        changes: [{ action: 'set', scope: 'pkg', path: 'pkg/AGENTS.md' }],
+        changes: [{ action: 'set', scope: 'pkg', path: join('pkg', 'AGENTS.md') }],
       })
-      expect(blocksText(workspaceContextOf(restored)?.content)).toContain('Additional instructions from: pkg/AGENTS.md')
+      expect(blocksText(workspaceContextOf(restored)?.content)).toContain(`Additional instructions from: ${join('pkg', 'AGENTS.md')}`)
       expect(blocksText(workspaceContextOf(restored)?.content)).toContain('restored package rule')
     } finally {
       await rm(root, { recursive: true, force: true })
@@ -2146,7 +2146,7 @@ describe('dynamic nested workspace context injection', () => {
 
       const update = resumed.session.events.findLast(event => event.type === 'context/message')
       expect(update?.type === 'context/message' && update.data.meta).toMatchObject({
-        changes: [{ action: 'replace', scope: 'pkg', path: 'pkg/AGENTS.md' }],
+        changes: [{ action: 'replace', scope: 'pkg', path: join('pkg', 'AGENTS.md') }],
       })
       expect(update?.type === 'context/message' && blocksText(update.data.content)).toContain('new nested rule after resume')
     } finally {
@@ -2267,8 +2267,8 @@ describe('dynamic nested workspace context injection', () => {
       })
 
       const firstText = blocksText(workspaceContextOf(first)?.content)
-      expect(firstText).toContain('omitted pkg/AGENTS.md')
-      expect(firstText).not.toContain('## pkg/AGENTS.md')
+      expect(firstText).toContain(`omitted ${join('pkg', 'AGENTS.md')}`)
+      expect(firstText).not.toContain(`## ${join('pkg', 'AGENTS.md')}`)
       expect(firstText).toContain('subtree rule')
       expect(blocksText(workspaceContextOf(second)?.content)).toContain('parent rule')
     } finally {
@@ -2462,7 +2462,7 @@ describe('dynamic nested workspace context injection', () => {
       expect(workspaceContextOf(result)?.envelope).toBe('raw')
       expect(workspaceContextOf(result)?.meta).toMatchObject({
         kind: 'workspace-instructions',
-        changes: [{ action: 'set', scope: 'pkg', path: 'pkg/AGENTS.md' }],
+        changes: [{ action: 'set', scope: 'pkg', path: join('pkg', 'AGENTS.md') }],
       })
       expect(blocksText(workspaceContextOf(result)?.content)).toContain('nested package rule')
       expect(blocksText(workspaceContextOf(result)?.content)).not.toContain('downstream context')
diff --git a/packages/fs/tool-fs-search/tests/tools.spec.ts b/packages/fs/tool-fs-search/tests/tools.spec.ts
index 5363344f07..add5b932f9 100644
--- a/packages/fs/tool-fs-search/tests/tools.spec.ts
+++ b/packages/fs/tool-fs-search/tests/tools.spec.ts
@@ -12,6 +12,7 @@
 
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
+import { join } from 'node:path'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
@@ -416,7 +417,7 @@ describe('glob results', () => {
     const { ctx, bash } = await setup()
     bash.handler = () => runResult('/sessions/s1/src/a.ts\n/elsewhere/b.ts\nrel/c.ts\n')
     const result = await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/sessions/s1') })
-    expect(text(result)).toBe('src/a.ts\n/elsewhere/b.ts\nrel/c.ts')
+    expect(text(result)).toBe(`${join('src', 'a.ts')}\n/elsewhere/b.ts\nrel/c.ts`)
   })
 
   it('validates arguments (blank pattern, blank path)', async () => {
@@ -498,7 +499,7 @@ describe('grep results', () => {
     const { ctx, bash } = await setup()
     bash.handler = () => runResult(`${matchLine('/sessions/s1/deep/a.ts', 2, 'hit')}\n`)
     const result = await call(ctx, 'grep', { pattern: 'hit', path: '/sessions/s1' }, { agent: agent('/sessions/s1') })
-    expect(text(result)).toContain('deep/a.ts\nLine 2: hit')
+    expect(text(result)).toContain(`${join('deep', 'a.ts')}\nLine 2: hit`)
   })
 
   it('previews a long matched line at grepMaxLineBytes preserving UTF-8', async () => {
@@ -608,7 +609,7 @@ describe('presentation', () => {
 
 describe('helpers', () => {
   it('toWorkdirRelative maps inside-workdir absolutes and passes everything else through', () => {
-    expect(toWorkdirRelative('/w/a/b.ts', '/w')).toBe('a/b.ts')
+    expect(toWorkdirRelative('/w/a/b.ts', '/w')).toBe(join('a', 'b.ts'))
     expect(toWorkdirRelative('/w', '/w')).toBe('.')
     expect(toWorkdirRelative('/other/b.ts', '/w')).toBe('/other/b.ts')
     expect(toWorkdirRelative('/w-sibling/b.ts', '/w')).toBe('/w-sibling/b.ts')
diff --git a/packages/spill/spill-local/tests/spill-local.spec.ts b/packages/spill/spill-local/tests/spill-local.spec.ts
index b4abc6e3d6..46fa0b66b2 100644
--- a/packages/spill/spill-local/tests/spill-local.spec.ts
+++ b/packages/spill/spill-local/tests/spill-local.spec.ts
@@ -10,7 +10,7 @@ import { describe, expect, it, beforeEach, afterEach } from 'vitest'
 import { Context } from 'cordis'
 import { mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { dirname, isAbsolute, join } from 'node:path'
+import { basename, dirname, isAbsolute, join, normalize } from 'node:path'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import type { SaveTextSpill } from '@deepseek-ai/dsh-spill'
@@ -63,7 +63,8 @@ describe('sessionDir', () => {
   it('is a stable per-session hash under the root', () => {
     const dir = sessionDir('/spill', 'sess-1')
     expect(dir).toBe(sessionDir('/spill', 'sess-1'))
-    expect(dir).toMatch(/\/spill\/session-[0-9a-f]{12}$/)
+    expect(dirname(dir)).toBe(normalize('/spill'))
+    expect(basename(dir)).toMatch(/^session-[0-9a-f]{12}$/)
     expect(sessionDir('/spill', 'sess-2')).not.toBe(dir)
   })
 })
@@ -74,7 +75,7 @@ describe('saveTextFile', () => {
     expect(readFileSync(saved.path, 'utf8')).toBe('héllo')
     expect(saved.bytes).toBe(Buffer.byteLength('héllo', 'utf8'))
     expect(dirname(saved.path)).toBe(sessionDir(root, 'sess-1'))
-    expect(saved.path).toMatch(/\/[0-9a-f]{12}-r\.txt$/)
+    expect(basename(saved.path)).toMatch(/^[0-9a-f]{12}-r\.txt$/)
   })
 
   it('sanitizes a traversal-shaped suggested name into one segment', async () => {
diff --git a/packages/util/paths/tests/paths.spec.ts b/packages/util/paths/tests/paths.spec.ts
index 97e91a556e..4ba4fab155 100644
--- a/packages/util/paths/tests/paths.spec.ts
+++ b/packages/util/paths/tests/paths.spec.ts
@@ -1,5 +1,5 @@
 import { homedir } from 'node:os'
-import { join } from 'node:path'
+import { join, resolve } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import {
   DEFAULT_DSH_HOME_DISPLAY,
@@ -28,7 +28,7 @@ describe('dsh path helpers', () => {
     const envHome = join(homedir(), 'env-dsh')
 
     expect(resolveDshHome(undefined, { DSH_HOME: '~/env-dsh' })).toBe(envHome)
-    expect(resolveDshHome('/tmp/explicit-dsh', { DSH_HOME: '~/env-dsh' })).toBe('/tmp/explicit-dsh')
+    expect(resolveDshHome('/tmp/explicit-dsh', { DSH_HOME: '~/env-dsh' })).toBe(resolve('/tmp/explicit-dsh'))
     expect(resolveDshHome(undefined, {})).toBe(defaultDshHome())
   })
 })

From 3a82b3edd7d52107578c1add212ade384bebfe55 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 15 Jul 2026 20:28:46 +0800
Subject: [PATCH 17/74] ci(windows): observe runtime coverage and snapshots

docs: record cross-platform gate boundaries
---
 .github/AGENTS.md        |  3 +++
 .github/workflows/ci.yml | 24 +++++++++++++++++++-----
 scripts/AGENTS.md        |  3 +++
 3 files changed, 25 insertions(+), 5 deletions(-)
 create mode 100644 .github/AGENTS.md
 create mode 100644 scripts/AGENTS.md

diff --git a/.github/AGENTS.md b/.github/AGENTS.md
new file mode 100644
index 0000000000..00e3ed8f87
--- /dev/null
+++ b/.github/AGENTS.md
@@ -0,0 +1,3 @@
+# AGENTS.md — CI gates
+
+Run Windows gates from native `pwsh`, invoke pnpm shell-free, and normalize repo-relative glob paths to `/` at ingestion. Keep platform fixes at each gate boundary; do not add a shared platform layer.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index bac25b07cb..de9a03288b 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -182,11 +182,9 @@ jobs:
       - name: Build (tsc -b + tsdown)
         run: pnpm run build
 
-  # Observational, non-blocking Windows static, lint, and artifact lanes. Coverage
-  # and snapshot stay Linux-only until their platform-specific runtime failures
-  # have dedicated support. Run the gates from native PowerShell: an MSYS parent
-  # would change the environment being measured. This job intentionally stays
-  # out of all-checks-passed.needs.
+  # Observational, non-blocking Windows mirror of the Linux gate lanes. Run the
+  # gates from native PowerShell: an MSYS parent would change the environment
+  # being measured. This job intentionally stays out of all-checks-passed.needs.
   windows-gates:
     continue-on-error: true
     runs-on: windows-2025
@@ -194,6 +192,7 @@ jobs:
     env:
       DSH_GATE_CONCURRENCY: ${{ matrix.gate_concurrency }}
       DSH_PUBLINT_CONCURRENCY: ${{ matrix.publint_concurrency }}
+      DSH_COVERAGE_MAX_WORKERS: ${{ matrix.coverage_max_workers }}
       DSH_ESLINT_CACHE: ${{ matrix.eslint_cache }}
     strategy:
       fail-fast: false
@@ -203,16 +202,31 @@ jobs:
             command: pnpm run check:ci:static
             gate_concurrency: '4'
             publint_concurrency: '8'
+            coverage_max_workers: ''
             eslint_cache: ''
           - lane: lint
             command: pnpm run check:ci:lint
             gate_concurrency: '1'
             publint_concurrency: '8'
+            coverage_max_workers: ''
             eslint_cache: '1'
+          - lane: coverage
+            command: pnpm run check:ci:coverage
+            gate_concurrency: '1'
+            publint_concurrency: '8'
+            coverage_max_workers: '4'
+            eslint_cache: ''
+          - lane: snapshot
+            command: pnpm run check:ci:snapshot
+            gate_concurrency: '1'
+            publint_concurrency: '8'
+            coverage_max_workers: ''
+            eslint_cache: ''
           - lane: artifacts
             command: pnpm run check:ci:artifacts
             gate_concurrency: '3'
             publint_concurrency: '8'
+            coverage_max_workers: ''
             eslint_cache: ''
     steps:
       - uses: actions/checkout@v6
diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md
new file mode 100644
index 0000000000..2d1ebafc27
--- /dev/null
+++ b/scripts/AGENTS.md
@@ -0,0 +1,3 @@
+# AGENTS.md — Repository scripts
+
+Gate-related scripts follow the [CI gate rules](../.github/AGENTS.md).

From 1d6acc331538aa7d5144257fcfd6690acd69eb1f Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 18 Jul 2026 03:23:52 +0800
Subject: [PATCH 18/74] test(loader-smoke): use native home paths

---
 packages/support/loader-smoke/tests/loader-smoke.spec.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/support/loader-smoke/tests/loader-smoke.spec.ts b/packages/support/loader-smoke/tests/loader-smoke.spec.ts
index b99d810188..755197b134 100644
--- a/packages/support/loader-smoke/tests/loader-smoke.spec.ts
+++ b/packages/support/loader-smoke/tests/loader-smoke.spec.ts
@@ -1,4 +1,5 @@
 import { existsSync } from 'node:fs'
+import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
@@ -33,8 +34,8 @@ describe('runLoaderSmoke', () => {
       marker: 'present',
       input: 'one\ntwo\n',
     })
-    expect(canonicalTempPath(output.dshHome)).toBe(`${canonicalTempPath(output.cwd)}/.dsh`)
-    expect(canonicalTempPath(output.agentsHome)).toBe(`${canonicalTempPath(output.cwd)}/.agents`)
+    expect(canonicalTempPath(output.dshHome)).toBe(canonicalTempPath(join(output.cwd, '.dsh')))
+    expect(canonicalTempPath(output.agentsHome)).toBe(canonicalTempPath(join(output.cwd, '.agents')))
     expect(result.stderr).toContain('fixture stderr')
     expect(existsSync(output.cwd)).toBe(false)
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)

From 588f4d948d8ac1c023366dbdc337546cb3ca65d3 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 18 Jul 2026 12:10:18 +0800
Subject: [PATCH 19/74] test(windows): mark platform-only coverage branches

---
 packages/context/workspace-context/src/files.ts              | 1 +
 packages/context/workspace-context/src/state.ts              | 1 +
 packages/fs/fs-local/src/fsio.ts                             | 1 +
 packages/sandbox/sandbox/src/index.ts                        | 1 +
 .../session-persistence-jsonl/src/index.ts                   | 5 +++++
 packages/skill/skill-local/src/index.ts                      | 1 +
 6 files changed, 10 insertions(+)

diff --git a/packages/context/workspace-context/src/files.ts b/packages/context/workspace-context/src/files.ts
index feb6304b4c..770024c569 100644
--- a/packages/context/workspace-context/src/files.ts
+++ b/packages/context/workspace-context/src/files.ts
@@ -459,6 +459,7 @@ export async function readScopeInstruction(
   signal?: AbortSignal,
 ): Promise<LoadedInstructionFile | undefined> {
   const content = await readBounded(file, maxSourceBytes, fileSystem, signal)
+  /* v8 ignore next -- Windows cannot reproduce a post-probe unreadable file with POSIX mode bits. */
   if (content === undefined) return undefined
   return {
     absolutePath: file.absolutePath,
diff --git a/packages/context/workspace-context/src/state.ts b/packages/context/workspace-context/src/state.ts
index 98b8fcc066..ab18f442f4 100644
--- a/packages/context/workspace-context/src/state.ts
+++ b/packages/context/workspace-context/src/state.ts
@@ -437,6 +437,7 @@ export async function reconcileInstructionContext(
     ) continue
 
     const file = await readScopeInstruction(probedFile, resolved.maxSourceBytes, fileSystem, options.signal)
+    /* v8 ignore next -- Windows cannot make the probed file unreadable through POSIX mode bits. */
     if (file === undefined) continue
     const currentDigest = instructionContentSha1(file.content)
     const nextVersion: InstructionVersionState = {
diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts
index 4603611ce4..9592ba0349 100644
--- a/packages/fs/fs-local/src/fsio.ts
+++ b/packages/fs/fs-local/src/fsio.ts
@@ -175,6 +175,7 @@ export async function resolveLocalTarget(cwd: string, path: string): Promise<Loc
 function pathType(info: Stats | BigIntStats): PathInfo['type'] {
   if (info.isFile()) return 'file'
   if (info.isDirectory()) return 'directory'
+  /* v8 ignore next -- Windows does not expose Unix-domain socket paths as special filesystem entries. */
   return 'other'
 }
 
diff --git a/packages/sandbox/sandbox/src/index.ts b/packages/sandbox/sandbox/src/index.ts
index 75cea5ecfe..56f40471e2 100644
--- a/packages/sandbox/sandbox/src/index.ts
+++ b/packages/sandbox/sandbox/src/index.ts
@@ -110,6 +110,7 @@ declare module 'cordis' {
  */
 export abstract class SandboxProvider extends Service {
   constructor(ctx: Context) {
+    /* v8 ignore next -- Windows has no sandbox backend to instantiate this service. */
     super(ctx, 'sandbox')
   }
 
diff --git a/packages/session-persistence/session-persistence-jsonl/src/index.ts b/packages/session-persistence/session-persistence-jsonl/src/index.ts
index 39aa493a0b..4c45e6d5b6 100644
--- a/packages/session-persistence/session-persistence-jsonl/src/index.ts
+++ b/packages/session-persistence/session-persistence-jsonl/src/index.ts
@@ -180,6 +180,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
     return header + '\n' + body + '\n'
   }
 
+  /* v8 ignore start -- Windows uses the Win32 durable-publish path; POSIX coverage exercises this peer. */
   private async materializePosix(dir: string, finalPath: string, id: SessionId, content: string): Promise<void> {
     await mkdir(this.root, { recursive: true, mode: 0o700 })
     await this.syncDirPosix(dirname(this.root))
@@ -213,6 +214,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
       /* v8 ignore next -- redundant temp link; publish already durable, rm failure is an unreachable IO edge */
     }
   }
+  /* v8 ignore stop */
 
   /* v8 ignore start -- native Windows coverage exercises this integration path */
   private async materializeWin32(dir: string, finalPath: string, id: SessionId, content: string): Promise<void> {
@@ -254,6 +256,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
   }
 
   /** fsync a POSIX directory so a just-created/renamed entry is crash-durable. */
+  /* v8 ignore start -- Windows uses write-through namespace operations; POSIX coverage exercises directory fsync. */
   private async syncDirPosix(dir: string): Promise<void> {
     const handle = await open(dir, 'r')
     try {
@@ -262,6 +265,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
       await handle.close()
     }
   }
+  /* v8 ignore stop */
 
   /**
    * Append and fsync event lines. On a partial write or sync failure, restore the
@@ -395,6 +399,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
         await this.assertLogParentAllowsAbsence(path)
         return false
       }
+      /* v8 ignore next -- Windows repairs ENOTDIR from ENOENT above; POSIX covers direct ENOTDIR. */
       throw error
     }
   }
diff --git a/packages/skill/skill-local/src/index.ts b/packages/skill/skill-local/src/index.ts
index ee109fbb16..29f5c622b9 100644
--- a/packages/skill/skill-local/src/index.ts
+++ b/packages/skill/skill-local/src/index.ts
@@ -317,6 +317,7 @@ async function nodeEntryKind(fullPath: string, entry: { isDirectory(): boolean;
     const info = await stat(fullPath)
     if (info.isDirectory()) return 'directory'
     if (info.isFile()) return 'file'
+    /* v8 ignore next -- The special-file symlink fixture relies on POSIX /dev/null. */
     return undefined
   } catch (error) {
     ctx.logger.warn(`skill entry ${fullPath} ignored: failed to follow symbolic link: ${errorMessage(error)}`)

From b426c2f19c06a6132e2d21992af8f2e2f5679506 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 18 Jul 2026 12:13:53 +0800
Subject: [PATCH 20/74] docs(api): refresh sandbox source link

---
 website/zh-CN/api/harness/sandbox.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/zh-CN/api/harness/sandbox.md b/website/zh-CN/api/harness/sandbox.md
index bc5b1d38a5..51980d36d7 100644
--- a/website/zh-CN/api/harness/sandbox.md
+++ b/website/zh-CN/api/harness/sandbox.md
@@ -21,4 +21,4 @@ Wrap `argv` so it executes confined under `policy` on this host; the caller spaw
 
 **Returns** the argv to spawn instead, plus the enforcement completeness the selected backend achieves for it.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/sandbox/sandbox/src/index.ts#L127)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/sandbox/sandbox/src/index.ts#L128)

From f62cc439e9bbc7e26e674e3a82b53e4dbb05469c Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 18 Jul 2026 13:03:44 +0800
Subject: [PATCH 21/74] docs(windows): clarify portability rules

---
 .github/AGENTS.md                       | 4 ++--
 packages/support/acp-snapshot/README.md | 2 +-
 scripts/AGENTS.md                       | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/AGENTS.md b/.github/AGENTS.md
index 00e3ed8f87..5f03c8617d 100644
--- a/.github/AGENTS.md
+++ b/.github/AGENTS.md
@@ -1,3 +1,3 @@
-# AGENTS.md — CI gates
+# AGENTS.md — GitHub Actions
 
-Run Windows gates from native `pwsh`, invoke pnpm shell-free, and normalize repo-relative glob paths to `/` at ingestion. Keep platform fixes at each gate boundary; do not add a shared platform layer.
+Run Windows jobs under native `pwsh`.
diff --git a/packages/support/acp-snapshot/README.md b/packages/support/acp-snapshot/README.md
index 9969eadb46..57f7245d7c 100644
--- a/packages/support/acp-snapshot/README.md
+++ b/packages/support/acp-snapshot/README.md
@@ -37,7 +37,7 @@ defineAcpSnapshotSuite({
 
 A scenario booting a differently-composed tree sets its own `configPath` (an overlay whose basename still ends in `cordis.yml`, so the bin's replay swap finds the sibling `*cordis.snapshot.yml`) and, when that composition changes the request header, its own `headerClass` with its own pinning scenario — the acp-agent example's Code Mode and filesystem scenarios are templates. Each pinning directory stores the normalized full prompt sequence in generated `system-prompt.golden.md` and the corresponding full tool-schema sequence in generated `tool-schemas.golden.json`; `session.jsonl` stores `"system":"{{system}}","tools":"{{tools}}"` while retaining config, reason, and any model-visible prefix. A pin with legitimate mid-run header changes declares `expectedHeaderChanges`, which fixes the length of both sidecar sequences.
 
-Every scenario compares `stdout.golden.jsonl` with cwd-rooted separators canonicalized to `/`. A scenario may set `pinsNativeWindowsStdout` to add a Windows-only comparison against the complete `stdout.golden.windows.jsonl`; the shared golden still runs first on Windows, and the fixture guard requires the sidecar exactly when declared.
+Every scenario compares `stdout.golden.jsonl` with cwd-rooted separators canonicalized to `/`. On Windows, `pinsNativeWindowsStdout` additionally compares the complete `stdout.golden.windows.jsonl` after the shared golden and requires that sidecar exactly when enabled.
 
 Examples use a `cordis.snapshot.yml` overlay with [`dsh-llm-replay`](../llm-replay/README.md). Recording calls the live model and updates model fixtures; keyless refresh replays those fixtures and updates derived stdout, session-log, prompt, and tool-schema snapshots. See the [snapshot RFC](../../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md).
 
diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md
index 2d1ebafc27..68ea79ea7b 100644
--- a/scripts/AGENTS.md
+++ b/scripts/AGENTS.md
@@ -1,3 +1,3 @@
 # AGENTS.md — Repository scripts
 
-Gate-related scripts follow the [CI gate rules](../.github/AGENTS.md).
+Gate scripts invoke pnpm shell-free, normalize repository-relative glob paths to `/` at ingestion, and keep platform adaptation at the owning gate boundary instead of a shared platform layer.

From 7d28b611b2b72bec88c7e722add48d443c42f7e3 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 18 Jul 2026 15:55:37 +0800
Subject: [PATCH 22/74] test(windows): align platform coverage ignores

---
 packages/fs/fs-local/src/fsio.ts                             | 5 ++++-
 packages/sandbox/sandbox/src/index.ts                        | 2 +-
 .../session-persistence-jsonl/src/index.ts                   | 1 +
 packages/skill/skill-local/src/index.ts                      | 1 +
 4 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts
index 9592ba0349..05d957105a 100644
--- a/packages/fs/fs-local/src/fsio.ts
+++ b/packages/fs/fs-local/src/fsio.ts
@@ -133,6 +133,7 @@ export async function resolveLocalTarget(cwd: string, path: string): Promise<Loc
     // A path component is a file, not a directory (e.g. "afile/child.txt" where
     // "afile" is a regular file): the target can neither exist nor be created,
     // so surface the structured taxonomy instead of a raw Node ENOTDIR.
+    /* v8 ignore next -- Windows reports this case as ENOENT and repairs it in the ancestor walk below. */
     if (isENOTDIR(error)) throw new FsError(`cannot resolve "${displayPath}": a parent path segment is not a directory`, 'FS_NOT_FOUND')
     /* v8 ignore next -- non-ENOENT realpath failure needs a permission/IO fault; ENOENT falls through to ancestor resolution. */
     if (!isENOENT(error)) throw error
@@ -174,8 +175,9 @@ export async function resolveLocalTarget(cwd: string, path: string): Promise<Loc
 
 function pathType(info: Stats | BigIntStats): PathInfo['type'] {
   if (info.isFile()) return 'file'
+  /* v8 ignore else -- Windows has no special-entry fixture for the non-directory branch. */
   if (info.isDirectory()) return 'directory'
-  /* v8 ignore next -- Windows does not expose Unix-domain socket paths as special filesystem entries. */
+  /* v8 ignore next -- the corresponding special-entry return is covered on POSIX. */
   return 'other'
 }
 
@@ -239,6 +241,7 @@ function listingIoError(displayPath: string, error: unknown): FsError {
   if (error instanceof FsError) return error
   /* v8 ignore next -- requires the listed target/parent to disappear between successful preflight and listing/child resolution. */
   if (isENOENT(error) || isENOTDIR(error)) return new FsError(`cannot list "${displayPath}": not found`, 'FS_NOT_FOUND', { cause: error })
+  /* v8 ignore next -- Windows chmod does not deny directory listing; POSIX covers permission translation. */
   if (isPermissionError(error)) return new FsError(`cannot list "${displayPath}": permission denied`, 'FS_PERMISSION_DENIED', { cause: error })
   return new FsError(`cannot list "${displayPath}": ${errorMessage(error)}`, 'FS_IO_ERROR', { cause: error })
 }
diff --git a/packages/sandbox/sandbox/src/index.ts b/packages/sandbox/sandbox/src/index.ts
index 56f40471e2..d18f2796ee 100644
--- a/packages/sandbox/sandbox/src/index.ts
+++ b/packages/sandbox/sandbox/src/index.ts
@@ -109,8 +109,8 @@ declare module 'cordis' {
  * skipped for a sole candidate, whose own refusal remains the fail-closed end.
  */
 export abstract class SandboxProvider extends Service {
+  /* v8 ignore next -- Windows has no sandbox backend to instantiate this service. */
   constructor(ctx: Context) {
-    /* v8 ignore next -- Windows has no sandbox backend to instantiate this service. */
     super(ctx, 'sandbox')
   }
 
diff --git a/packages/session-persistence/session-persistence-jsonl/src/index.ts b/packages/session-persistence/session-persistence-jsonl/src/index.ts
index 4c45e6d5b6..fa001d6899 100644
--- a/packages/session-persistence/session-persistence-jsonl/src/index.ts
+++ b/packages/session-persistence/session-persistence-jsonl/src/index.ts
@@ -395,6 +395,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
       // than letting load or collision checks proceed under false absence.
       // Windows reports ENOENT, not ENOTDIR, for `regular-file/child`; verify
       // the immediate parent so a blocked cwd bucket remains a storage fault.
+      /* v8 ignore else -- Windows reports file-valued parents as ENOENT; POSIX covers direct ENOTDIR. */
       if (isENOENT(error)) {
         await this.assertLogParentAllowsAbsence(path)
         return false
diff --git a/packages/skill/skill-local/src/index.ts b/packages/skill/skill-local/src/index.ts
index 29f5c622b9..fd01e948c9 100644
--- a/packages/skill/skill-local/src/index.ts
+++ b/packages/skill/skill-local/src/index.ts
@@ -316,6 +316,7 @@ async function nodeEntryKind(fullPath: string, entry: { isDirectory(): boolean;
   try {
     const info = await stat(fullPath)
     if (info.isDirectory()) return 'directory'
+    /* v8 ignore else -- the special-file symlink branch relies on POSIX /dev/null. */
     if (info.isFile()) return 'file'
     /* v8 ignore next -- The special-file symlink fixture relies on POSIX /dev/null. */
     return undefined

From d36dc6ece9d1d389b827d94db59f1cc49cbe5b57 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 18 Jul 2026 16:25:16 +0800
Subject: [PATCH 23/74] test(windows): replace POSIX-only filesystem fixtures

---
 .../context/workspace-context/src/files.ts    |  1 -
 .../context/workspace-context/src/state.ts    |  1 -
 .../tests/workspace-context.spec.ts           | 43 ++++++++++++-------
 .../spill-local/tests/spill-local.spec.ts     | 13 ++++--
 4 files changed, 36 insertions(+), 22 deletions(-)

diff --git a/packages/context/workspace-context/src/files.ts b/packages/context/workspace-context/src/files.ts
index 770024c569..feb6304b4c 100644
--- a/packages/context/workspace-context/src/files.ts
+++ b/packages/context/workspace-context/src/files.ts
@@ -459,7 +459,6 @@ export async function readScopeInstruction(
   signal?: AbortSignal,
 ): Promise<LoadedInstructionFile | undefined> {
   const content = await readBounded(file, maxSourceBytes, fileSystem, signal)
-  /* v8 ignore next -- Windows cannot reproduce a post-probe unreadable file with POSIX mode bits. */
   if (content === undefined) return undefined
   return {
     absolutePath: file.absolutePath,
diff --git a/packages/context/workspace-context/src/state.ts b/packages/context/workspace-context/src/state.ts
index ab18f442f4..98b8fcc066 100644
--- a/packages/context/workspace-context/src/state.ts
+++ b/packages/context/workspace-context/src/state.ts
@@ -437,7 +437,6 @@ export async function reconcileInstructionContext(
     ) continue
 
     const file = await readScopeInstruction(probedFile, resolved.maxSourceBytes, fileSystem, options.signal)
-    /* v8 ignore next -- Windows cannot make the probed file unreadable through POSIX mode bits. */
     if (file === undefined) continue
     const currentDigest = instructionContentSha1(file.content)
     const nextVersion: InstructionVersionState = {
diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts
index 9de003ae8d..75238d6fb6 100644
--- a/packages/context/workspace-context/tests/workspace-context.spec.ts
+++ b/packages/context/workspace-context/tests/workspace-context.spec.ts
@@ -1,4 +1,4 @@
-import { chmod, mkdtemp, mkdir, rm, stat, symlink, utimes, writeFile } from 'node:fs/promises'
+import { mkdtemp, mkdir, rm, stat, symlink, utimes, writeFile } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
 import { tmpdir } from 'node:os'
 import { describe, expect, it, vi } from 'vitest'
@@ -53,6 +53,7 @@ class RecordingFileSystem extends FileSystem {
   entries = new Map<string, { type: FsInfo['type']; content?: string; version?: FsVersion }>()
   lstatTypes = new Map<string, FsPathInfo['type']>()
   throwOnStat = new Set<string>()
+  throwOnRead = new Set<string>()
   omitSizes = new Set<string>()
   readTargets: string[] = []
   readTextTargets: string[] = []
@@ -105,6 +106,7 @@ class RecordingFileSystem extends FileSystem {
     if (signal !== undefined) this.signals.push(signal)
     signal?.throwIfAborted()
     this.readTargets.push(target.targetKey)
+    if (this.throwOnRead.has(target.targetKey)) throw new Error(`read failed: ${target.displayPath}`)
     const content = this.entries.get(target.targetKey)?.content ?? ''
     return (async function* () {
       const midpoint = Math.ceil(content.length / 2)
@@ -336,22 +338,25 @@ describe('workspace context instruction discovery', () => {
     }
   })
 
-  it.skipIf(process.platform === 'win32')('skips a file that becomes unreadable after discovery without failing the request', async () => {
+  it('skips a provider file whose read fails after a successful metadata probe', async () => {
     const root = await tempRepo()
     const home = await tempRepo()
+    const ctx = new Context()
     try {
       const cwd = join(root, 'pkg')
-      await mkdir(join(root, '.git'), { recursive: true })
-      await mkdir(cwd, { recursive: true })
       const leaf = join(cwd, 'AGENTS.md')
-      await write(leaf, 'secret-ish rule')
-      await chmod(leaf, 0)
+      await ctx.plugin(RecordingFileSystem)
+      const fs = ctx.fs as RecordingFileSystem
+      fs.entries.set(join(root, '.git'), { type: 'directory' })
+      fs.entries.set(leaf, { type: 'file', content: 'secret-ish rule' })
+      fs.throwOnRead.add(leaf)
 
-      const loaded = await loadBaselineInstructions({ cwd, dshHome: home, maxBytes: 65536 })
+      const loaded = await loadBaselineInstructions({ cwd, dshHome: home, maxBytes: 65536 }, fs)
 
       expect(loaded).toBeUndefined()
-      await chmod(leaf, 0o600)
+      expect(fs.readTargets).toEqual([leaf])
     } finally {
+      await ctx.fiber.dispose()
       await rm(root, { recursive: true, force: true })
       await rm(home, { recursive: true, force: true })
     }
@@ -2403,17 +2408,22 @@ describe('dynamic nested workspace context injection', () => {
     }
   })
 
-  it.skipIf(process.platform === 'win32')('skips unreadable nested instruction files without attaching empty context', async () => {
+  it('skips unreadable nested instruction files without attaching empty context', async () => {
     const root = await tempRepo()
     const home = await tempRepo()
+    const ctx = new Context()
     try {
-      await mkdir(join(root, '.git'), { recursive: true })
       const nested = join(root, 'pkg/AGENTS.md')
-      await write(nested, 'nested package rule')
-      await write(join(root, 'pkg/deep/file.txt'), 'hello')
-      await chmod(nested, 0)
-      const ctx = new Context()
-      await mountFileToolsAndWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
+      await ctx.plugin(SystemPrompt)
+      await ctx.plugin(ToolRegistry)
+      await ctx.plugin(RecordingFileSystem)
+      const fs = ctx.fs as RecordingFileSystem
+      fs.entries.set(join(root, '.git'), { type: 'directory' })
+      fs.entries.set(nested, { type: 'file', content: 'nested package rule' })
+      fs.entries.set(join(root, 'pkg/deep/file.txt'), { type: 'file', content: 'hello' })
+      fs.throwOnRead.add(nested)
+      await ctx.plugin(ToolFs)
+      await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 })
 
       const result = await ctx.tools.execute({
         callId: CallId('read-with-unreadable-nested-instruction'),
@@ -2424,8 +2434,9 @@ describe('dynamic nested workspace context injection', () => {
 
       expect(result.isError).toBe(false)
       expect(result.additionalContexts).toBeUndefined()
-      await chmod(nested, 0o600)
+      expect(fs.readTargets).toContain(nested)
     } finally {
+      await ctx.fiber.dispose()
       await rm(root, { recursive: true, force: true })
       await rm(home, { recursive: true, force: true })
     }
diff --git a/packages/spill/spill-local/tests/spill-local.spec.ts b/packages/spill/spill-local/tests/spill-local.spec.ts
index 46fa0b66b2..3c6f9ac82d 100644
--- a/packages/spill/spill-local/tests/spill-local.spec.ts
+++ b/packages/spill/spill-local/tests/spill-local.spec.ts
@@ -85,11 +85,16 @@ describe('saveTextFile', () => {
     expect(saved.path.includes('/..')).toBe(false)
   })
 
-  it.skipIf(process.platform === 'win32')('creates the session dir with owner-only permissions', async () => {
+  it('creates the session directory and file with owner-only POSIX permissions', async () => {
     const saved = await saveTextFile({ root, sessionId: 'sess-1', suggestedName: 'r.txt', content: 'x' })
-    // 0o700 dir, 0o600 file (masked by umask, but the owner bits must hold).
-    expect(statSync(dirname(saved.path)).mode & 0o700).toBe(0o700)
-    expect(statSync(saved.path).mode & 0o600).toBe(0o600)
+    const directory = statSync(dirname(saved.path))
+    const file = statSync(saved.path)
+    expect(directory.isDirectory()).toBe(true)
+    expect(file.isFile()).toBe(true)
+    if (process.platform !== 'win32') {
+      expect(directory.mode & 0o777).toBe(0o700)
+      expect(file.mode & 0o777).toBe(0o600)
+    }
   })
 
   it('gives distinct paths to two saves of the same name', async () => {

From 64f64724e5caaca1c59db5bd953c4a8e1214c538 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 18 Jul 2026 16:25:51 +0800
Subject: [PATCH 24/74] fix(subprocess): honor Windows termination semantics

---
 docs/config-catalog.md                        |  2 +-
 packages/subagent/subagent-acp/README.md      |  6 ++---
 packages/subagent/subagent-acp/src/index.ts   |  2 +-
 packages/subagent/subagent-acp/src/run.ts     | 14 +++++------
 .../subagent-acp/tests/subagent-acp.spec.ts   | 16 ++++---------
 .../subagent/subagent-subprocess/README.md    | 10 ++++----
 .../subagent/subagent-subprocess/src/index.ts | 23 +++++++++++++------
 .../tests/subagent-subprocess.spec.ts         | 13 ++++++++---
 8 files changed, 48 insertions(+), 38 deletions(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index ba273888d1..b31721ef99 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -853,7 +853,7 @@ export interface Config {
    * before the parent escalates to a signal.
    */
   disposeEofGraceMs?: number
-  /** Grace period (ms) between `SIGTERM` and the `SIGKILL` escalation on dispose. */
+  /** POSIX grace period (ms) between `SIGTERM` and `SIGKILL`; unused on Windows. */
   disposeGraceMs?: number
 }
 
diff --git a/packages/subagent/subagent-acp/README.md b/packages/subagent/subagent-acp/README.md
index 69a5f14181..7b23d371a0 100644
--- a/packages/subagent/subagent-acp/README.md
+++ b/packages/subagent/subagent-acp/README.md
@@ -8,7 +8,7 @@ The ACP provider runs each subagent in a fresh subprocess and drives it as an Ag
 
 After publication, the provider sends the prompt and collects streamed `agent_message_chunk` text into `SubagentResult.output`. A prompt/transport failure resolves with `stopReason: 'error'`, or `aborted` when the required request signal or disposal requested cancellation.
 
-`dispose()` is idempotent. It removes the signal listener, requests ACP cancellation when possible, closes stdin, waits `disposeEofGraceMs`, escalates to SIGTERM, waits `disposeGraceMs`, and finally uses SIGKILL if necessary. Every run uses a fresh process; process pooling is not implemented.
+`dispose()` is idempotent. It removes the signal listener, requests ACP cancellation when possible, closes stdin, and waits `disposeEofGraceMs`. POSIX then escalates through SIGTERM and `disposeGraceMs` before SIGKILL; Windows force-terminates directly because Node maps both signals to `TerminateProcess`. Disposal resolves only after child exit. Every run uses a fresh process; process pooling is not implemented.
 
 ## Capabilities and context
 
@@ -24,8 +24,8 @@ ACP advertises no start-time capabilities because this process cannot enforce th
 | `cwd` | process cwd | Child process and ACP session working directory. |
 | `permission` | `reject` | Auto-answer permission requests by rejecting or choosing the first allow-shaped option. |
 | `env` | `{}` | Explicit child environment layered over a credential-scrubbed parent environment. |
-| `disposeEofGraceMs` | `6000` | Grace after stdin EOF before SIGTERM. |
-| `disposeGraceMs` | `3000` | Grace after SIGTERM before SIGKILL. |
+| `disposeEofGraceMs` | `6000` | Grace after stdin EOF before platform termination. |
+| `disposeGraceMs` | `3000` | POSIX grace after SIGTERM before SIGKILL; unused on Windows. |
 
 ```yaml
 - id: subagent-acp
diff --git a/packages/subagent/subagent-acp/src/index.ts b/packages/subagent/subagent-acp/src/index.ts
index 80766ed831..697be5b98a 100644
--- a/packages/subagent/subagent-acp/src/index.ts
+++ b/packages/subagent/subagent-acp/src/index.ts
@@ -46,7 +46,7 @@ export interface Config {
    * before the parent escalates to a signal.
    */
   disposeEofGraceMs?: number
-  /** Grace period (ms) between `SIGTERM` and the `SIGKILL` escalation on dispose. */
+  /** POSIX grace period (ms) between `SIGTERM` and `SIGKILL`; unused on Windows. */
   disposeGraceMs?: number
 }
 
diff --git a/packages/subagent/subagent-acp/src/run.ts b/packages/subagent/subagent-acp/src/run.ts
index 9416d58865..c9f1c59e10 100644
--- a/packages/subagent/subagent-acp/src/run.ts
+++ b/packages/subagent/subagent-acp/src/run.ts
@@ -56,9 +56,9 @@ export interface AcpRunSpec {
    */
   disposeEofGraceMs: number
   /**
-   * Grace period (ms) between `SIGTERM` and the `SIGKILL` escalation in
-   * {@link SubagentRun.dispose}. The plugin fills this from its
-   * `disposeGraceMs` config.
+   * POSIX grace period (ms) between `SIGTERM` and `SIGKILL` in
+   * {@link SubagentRun.dispose}; unused on Windows. The plugin fills this from
+   * its `disposeGraceMs` config.
    */
   disposeGraceMs: number
   /**
@@ -75,7 +75,7 @@ export interface AcpRunSpec {
 /** EOF grace for child flush and nested-process teardown; wider than the signal grace below. */
 export const DEFAULT_DISPOSE_EOF_GRACE_MS = 6_000
 
-/** Default grace between SIGTERM and SIGKILL on dispose (the `disposeGraceMs` config; mirrors the bash executor). */
+/** Default POSIX grace between SIGTERM and SIGKILL on dispose (the `disposeGraceMs` config). */
 export const DEFAULT_DISPOSE_GRACE_MS = 3_000
 
 /**
@@ -290,9 +290,9 @@ export async function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpe
       if (disposal !== undefined) return disposal
       request.signal.removeEventListener('abort', onAbort)
       requestCancel()
-      // The shared EOF → TERM → KILL ladder awaits exit. ACP normally quiesces
-      // from stdin EOF, including the final flush, so this backend uses a wider
-      // EOF grace before signals escalate.
+      // The shared platform-aware ladder awaits exit. ACP normally quiesces from
+      // stdin EOF, including the final flush, so this backend uses a wider EOF
+      // grace before process termination escalates.
       disposal = disposeProcess()
       return disposal
     },
diff --git a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts
index e3fd3eda48..a57263eb6c 100644
--- a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts
+++ b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts
@@ -263,13 +263,9 @@ describe('dsh-subagent-acp', () => {
     }
   })
 
-  it.skipIf(process.platform === 'win32')('escalates to SIGTERM for a child that ignores EOF but is not SIGTERM-trapping', async () => {
-    // A child that keeps its loop alive past stdin EOF (so the graceful window
-    // times out) but exits cooperatively on SIGTERM must die on the SIGTERM tier
-    // — dispose returns there, never reaching the SIGKILL tier. The child touches
-    // a SIGTERM marker from its signal handler: SIGKILL is uncatchable, so if
-    // dispose had skipped the middle rung (EOF→SIGKILL) the handler would never
-    // run and the marker would be absent — making this a GENUINE middle-tier guard.
+  it('terminates a child that ignores EOF using the host platform semantics', async () => {
+    // POSIX uses the catchable SIGTERM tier and records the marker. Windows has
+    // no distinct graceful signal, so disposal skips directly to forced exit.
     const tmp = mkdtempSync(join(tmpdir(), 'acp-ignore-eof-'))
     const ready = join(tmp, 'ready')
     const sigterm = join(tmp, 'sigterm')
@@ -283,7 +279,7 @@ describe('dsh-subagent-acp', () => {
           MOCK_HANG: '1', MOCK_IGNORE_EOF: '1', MOCK_TEXT: 'x',
           MOCK_READY_FILE: ready, MOCK_SIGTERM_FILE: sigterm,
         },
-        // Tiny EOF grace so the ignored-EOF window elapses fast, then SIGTERM.
+        // Tiny EOF grace so the ignored-EOF window elapses quickly.
         disposeEofGraceMs: 150,
         disposeGraceMs: 2000,
       }
@@ -294,9 +290,7 @@ describe('dsh-subagent-acp', () => {
         run.dispose(),
         new Promise((_r, reject) => { setTimeout(() => { reject(new Error('dispose did not return')) }, 5000) }),
       ])).resolves.toBeUndefined()
-      // The child caught SIGTERM and exited — proof the middle rung fired (not a
-      // jump straight to the uncatchable SIGKILL).
-      expect(existsSync(sigterm)).toBe(true)
+      expect(existsSync(sigterm)).toBe(process.platform !== 'win32')
     } finally {
       rmSync(tmp, { recursive: true, force: true })
     }
diff --git a/packages/subagent/subagent-subprocess/README.md b/packages/subagent/subagent-subprocess/README.md
index a3c0905422..48ce9ff0e4 100644
--- a/packages/subagent/subagent-subprocess/README.md
+++ b/packages/subagent/subagent-subprocess/README.md
@@ -20,13 +20,13 @@ Exit waits over a `ChildProcess`: resolve once the child exits by any code or si
 
 ### `disposeChildProcess(child, graces)`
 
-The three-tier dispose ladder. Resolves only once the child has ACTUALLY exited — quiescence reached, not merely requested (see [defensive patterns](../../../docs/defensive-patterns.md)):
+The platform-aware dispose ladder resolves only once the child has ACTUALLY exited — quiescence reached, not merely requested (see [defensive patterns](../../../docs/defensive-patterns.md)):
 
 1. stdin EOF (when stdin is piped), then wait `graces.disposeEofGraceMs` — a cooperative child quiesces on its own, its flushes and nested-subprocess teardown intact;
-2. `SIGTERM`, then wait `graces.disposeGraceMs`;
-3. `SIGKILL`, then await the now-certain exit — a child that ignores EOF and traps `SIGTERM` cannot wedge dispose forever.
+2. on POSIX, `SIGTERM`, then wait `graces.disposeGraceMs`;
+3. force termination and await exit — `SIGKILL` on POSIX and Node's `TerminateProcess` mapping on Windows.
 
-The two graces (`DisposeLadderGraces`) come from the consuming plugin's `disposeEofGraceMs`/`disposeGraceMs` Config fields; the EOF window is deliberately a separate — usually wider — grace than the signal tier, since a cooperative child's EOF teardown may itself await a signal-trapping grandchild plus a final flush.
+The two graces (`DisposeLadderGraces`) come from the consuming plugin's `disposeEofGraceMs`/`disposeGraceMs` Config fields; `disposeGraceMs` is unused on Windows because Node maps `SIGTERM` and `SIGKILL` to the same forced termination. The EOF window is deliberately separate and usually wider, since cooperative teardown may await a signal-trapping grandchild plus a final flush.
 
 ### `createIsolatedConfigDir(prefix, pinnedPath?)`
 
@@ -37,7 +37,7 @@ A per-run isolated config directory for an external CLI child (the target of `CL
 
 ## Testing
 
-`tests/subagent-subprocess.spec.ts`: the env scrub and config-dir helpers run against the real process env and real filesystem (the rm-failure path injects its rejection at the fs boundary — a real recursive-rm failure is not portably provokable, and root ignores permission bits); the exit waits and the dispose ladder run against a scriptable fake child, driving each escalation tier deterministically. The [ACP backend suite](../subagent-acp/README.md) exercises the same ladder against real subprocesses (EOF-cooperative, EOF-ignoring, and SIGTERM-trapping children) end to end.
+`tests/subagent-subprocess.spec.ts`: the env scrub and config-dir helpers run against the real process env and real filesystem (the rm-failure path injects its rejection at the fs boundary — a real recursive-rm failure is not portably provokable, and root ignores permission bits); the exit waits and platform termination paths run against a scriptable fake child. The [ACP backend suite](../subagent-acp/README.md) exercises them against real subprocesses end to end.
 
 ## Model Experience
 
diff --git a/packages/subagent/subagent-subprocess/src/index.ts b/packages/subagent/subagent-subprocess/src/index.ts
index 21bcca788e..360b12a70b 100644
--- a/packages/subagent/subagent-subprocess/src/index.ts
+++ b/packages/subagent/subagent-subprocess/src/index.ts
@@ -98,33 +98,42 @@ export interface DisposeLadderGraces {
   /**
    * Tier-1 window (ms): after stdin EOF, how long the child gets to quiesce
    * ON ITS OWN — flush durable state, tear down its own nested subprocesses —
-   * before the parent escalates to `SIGTERM`. A separate (usually WIDER)
+   * before the parent escalates to platform termination. A separate (usually WIDER)
    * grace than {@link DisposeLadderGraces.disposeGraceMs}: a cooperative
    * child's EOF-driven teardown may itself be waiting on a signal-trapping
    * grandchild plus a final flush, needing more than one signal-grace of
    * headroom.
    */
   disposeEofGraceMs: number
-  /** Tier-2 window (ms): between `SIGTERM` and the `SIGKILL` escalation. */
+  /** POSIX tier-2 window (ms): between `SIGTERM` and the `SIGKILL` escalation. */
   disposeGraceMs: number
 }
 
 /**
  * Tear a child process down to quiescence, resolving only after exit: close stdin and allow
- * cooperative flush, then send `SIGTERM`, then `SIGKILL` and await the forced exit.
+ * cooperative flush, then use the host's graceful and forced termination semantics. POSIX
+ * sends `SIGTERM` before `SIGKILL`; Windows skips directly to forced termination because Node
+ * maps both signals to `TerminateProcess`.
  *
  * @param child - the child process to tear down.
  * @param graces - the two grace periods, from the consuming plugin's Config.
+ * @param platform - the host platform, injectable for unit coverage.
  */
-export async function disposeChildProcess(child: ChildProcess, graces: DisposeLadderGraces): Promise<void> {
+export async function disposeChildProcess(
+  child: ChildProcess,
+  graces: DisposeLadderGraces,
+  platform: NodeJS.Platform = process.platform,
+): Promise<void> {
   // Already gone: nothing to reap.
   if (child.exitCode !== null || child.signalCode !== null) return
   // 1. Close stdin and allow cooperative teardown and durable-state flush.
   child.stdin?.end()
   if (await exitsWithin(child, graces.disposeEofGraceMs)) return
-  // 2. SIGTERM, escalating if the child still does not exit within the grace.
-  child.kill('SIGTERM')
-  if (await exitsWithin(child, graces.disposeGraceMs)) return
+  // 2. POSIX gets a catchable graceful signal; Windows signals all force-terminate.
+  if (platform !== 'win32') {
+    child.kill('SIGTERM')
+    if (await exitsWithin(child, graces.disposeGraceMs)) return
+  }
   // 3. Force-kill and await the (now-certain) exit.
   child.kill('SIGKILL')
   await waitForExit(child)
diff --git a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts
index 8ed3891578..9fedf37722 100644
--- a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts
+++ b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts
@@ -229,7 +229,7 @@ describe('disposeChildProcess', () => {
 
   it('tier 2: a child that ignores EOF but honors SIGTERM dies on the middle rung', async () => {
     const fake = new FakeChild({ diesOn: 'SIGTERM', delayMs: 5 })
-    await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 })
+    await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }, 'linux')
     expect(fake.stdinEnded).toBe(true)
     expect(fake.kills).toEqual(['SIGTERM'])
     expect(fake.signalCode).toBe('SIGTERM')
@@ -237,7 +237,7 @@ describe('disposeChildProcess', () => {
 
   it('tier 3: a SIGTERM-trapping child is SIGKILLed, and dispose resolves only after the exit', async () => {
     const fake = new FakeChild({ delayMs: 5 }) // only SIGKILL fells it
-    await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 20 })
+    await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 20 }, 'linux')
     expect(fake.kills).toEqual(['SIGTERM', 'SIGKILL'])
     // Quiescence, not a request: at resolution the child has ACTUALLY exited
     // (the exit event landed, despite the scripted post-SIGKILL delay).
@@ -246,9 +246,16 @@ describe('disposeChildProcess', () => {
 
   it('walks the ladder for a child spawned without a stdin pipe', async () => {
     const fake = new FakeChild({ stdin: false, diesOn: 'SIGTERM', delayMs: 5 })
-    await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 })
+    await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }, 'linux')
     expect(fake.kills).toEqual(['SIGTERM'])
   })
+
+  it('skips the redundant SIGTERM tier on Windows and awaits forced exit', async () => {
+    const fake = new FakeChild({ diesOn: 'SIGTERM', delayMs: 5 })
+    await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }, 'win32')
+    expect(fake.kills).toEqual(['SIGKILL'])
+    expect(fake.signalCode).toBe('SIGKILL')
+  })
 })
 
 describe('createIsolatedConfigDir', () => {

From 462519596860baad18e6f2c2a61d60de82eaee37 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 12:19:33 +0800
Subject: [PATCH 25/74] fix(subagent): bound forced child termination

Observe signal errors and bound the final forced-exit edge with disposeGraceMs so a refused or ineffective SIGKILL cannot leave disposal pending forever.

Apply the confirmation bound on POSIX and Windows, remove listeners and timers on every outcome, and update the ACP consumer contract plus the generated config catalog.

Cover emitted signal errors, synchronous kill exceptions, refused termination, and accepted termination that never reports exit.
---
 docs/config-catalog.md                        |  2 +-
 packages/subagent/subagent-acp/README.md      |  4 +-
 packages/subagent/subagent-acp/src/index.ts   |  2 +-
 packages/subagent/subagent-acp/src/run.ts     |  6 +-
 .../subagent/subagent-subprocess/README.md    |  4 +-
 .../subagent/subagent-subprocess/src/index.ts | 58 +++++++++++++----
 .../tests/subagent-subprocess.spec.ts         | 65 +++++++++++++++++++
 7 files changed, 118 insertions(+), 23 deletions(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 7921b98f55..dd652c7d45 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -866,7 +866,7 @@ export interface Config {
    * before the parent escalates to a signal.
    */
   disposeEofGraceMs?: number
-  /** POSIX grace period (ms) between `SIGTERM` and `SIGKILL`; unused on Windows. */
+  /** Termination confirmation window (ms), including forced exit on every platform. */
   disposeGraceMs?: number
 }
 
diff --git a/packages/subagent/subagent-acp/README.md b/packages/subagent/subagent-acp/README.md
index 830335bbb5..240b79c2d7 100644
--- a/packages/subagent/subagent-acp/README.md
+++ b/packages/subagent/subagent-acp/README.md
@@ -10,7 +10,7 @@ The returned run id is minted in the parent namespace. The child server's sessio
 
 After publication, the provider sends the prompt and collects streamed `agent_message_chunk` text into `SubagentResult.output`. A prompt/transport failure resolves with `stopReason: 'error'`, or `aborted` when the required request signal or disposal requested cancellation.
 
-`dispose()` is idempotent. It removes the signal listener, requests ACP cancellation when possible, closes stdin, and waits `disposeEofGraceMs`. POSIX then escalates through SIGTERM and `disposeGraceMs` before SIGKILL; Windows force-terminates directly because Node maps both signals to `TerminateProcess`. Disposal resolves only after child exit. Every run uses a fresh process; process pooling is not implemented.
+`dispose()` is idempotent. It removes the signal listener, requests ACP cancellation when possible, closes stdin, and waits `disposeEofGraceMs`. POSIX then escalates through SIGTERM and `disposeGraceMs` before SIGKILL; Windows force-terminates directly because Node maps both signals to `TerminateProcess`. After forced termination, every platform waits at most `disposeGraceMs` for exit and rejects on a signal error or missing exit. Every run uses a fresh process; process pooling is not implemented.
 
 ## Capabilities and context
 
@@ -27,7 +27,7 @@ ACP advertises no start-time capabilities because this process cannot enforce th
 | `permission` | `reject` | Auto-answer permission requests by rejecting or choosing the first allow-shaped option. |
 | `env` | `{}` | Explicit child environment layered over a credential-scrubbed parent environment. |
 | `disposeEofGraceMs` | `6000` | Grace after stdin EOF before platform termination. |
-| `disposeGraceMs` | `3000` | POSIX grace after SIGTERM before SIGKILL; unused on Windows. |
+| `disposeGraceMs` | `3000` | Exit-confirmation grace after termination; POSIX also waits this long after SIGTERM before SIGKILL. |
 
 ```yaml
 - id: subagent-acp
diff --git a/packages/subagent/subagent-acp/src/index.ts b/packages/subagent/subagent-acp/src/index.ts
index 697be5b98a..0a761831ea 100644
--- a/packages/subagent/subagent-acp/src/index.ts
+++ b/packages/subagent/subagent-acp/src/index.ts
@@ -46,7 +46,7 @@ export interface Config {
    * before the parent escalates to a signal.
    */
   disposeEofGraceMs?: number
-  /** POSIX grace period (ms) between `SIGTERM` and `SIGKILL`; unused on Windows. */
+  /** Termination confirmation window (ms), including forced exit on every platform. */
   disposeGraceMs?: number
 }
 
diff --git a/packages/subagent/subagent-acp/src/run.ts b/packages/subagent/subagent-acp/src/run.ts
index 9f037a170c..09a6ed81e9 100644
--- a/packages/subagent/subagent-acp/src/run.ts
+++ b/packages/subagent/subagent-acp/src/run.ts
@@ -56,9 +56,9 @@ export interface AcpRunSpec {
    */
   disposeEofGraceMs: number
   /**
-   * POSIX grace period (ms) between `SIGTERM` and `SIGKILL` in
-   * {@link SubagentRun.dispose}; unused on Windows. The plugin fills this from
-   * its `disposeGraceMs` config.
+   * Termination confirmation window (ms) in {@link SubagentRun.dispose}; POSIX applies it after
+   * `SIGTERM` and `SIGKILL`, while Windows applies it after direct forced termination. The plugin
+   * fills this from its `disposeGraceMs` config.
    */
   disposeGraceMs: number
   /**
diff --git a/packages/subagent/subagent-subprocess/README.md b/packages/subagent/subagent-subprocess/README.md
index 4a72f6279b..80be43125e 100644
--- a/packages/subagent/subagent-subprocess/README.md
+++ b/packages/subagent/subagent-subprocess/README.md
@@ -20,9 +20,9 @@ The platform-aware dispose ladder resolves only once the child has ACTUALLY exit
 
 1. stdin EOF (when stdin is piped), then wait `graces.disposeEofGraceMs` — a cooperative child quiesces on its own, its flushes and nested-subprocess teardown intact;
 2. on POSIX, `SIGTERM`, then wait `graces.disposeGraceMs`;
-3. force termination and await exit — `SIGKILL` on POSIX and Node's `TerminateProcess` mapping on Windows.
+3. force termination — `SIGKILL` on POSIX and Node's `TerminateProcess` mapping on Windows — then wait at most `graces.disposeGraceMs` for exit; a signal error or missing exit rejects disposal.
 
-The two graces (`DisposeLadderGraces`) come from the consuming plugin's `disposeEofGraceMs`/`disposeGraceMs` Config fields; `disposeGraceMs` is unused on Windows because Node maps `SIGTERM` and `SIGKILL` to the same forced termination. The EOF window is deliberately separate and usually wider, since cooperative teardown may await a signal-trapping grandchild plus a final flush.
+The two graces (`DisposeLadderGraces`) come from the consuming plugin's `disposeEofGraceMs`/`disposeGraceMs` Config fields. POSIX uses `disposeGraceMs` after both the graceful and forced signals; Windows skips the redundant graceful signal but uses it to bound forced-exit confirmation. The EOF window is deliberately separate and usually wider, since cooperative teardown may await a signal-trapping grandchild plus a final flush.
 
 The exit waits are internal to this ladder. They clean up their timer and listener on either outcome, so escalation never accumulates listeners on the child.
 
diff --git a/packages/subagent/subagent-subprocess/src/index.ts b/packages/subagent/subagent-subprocess/src/index.ts
index de4702bac9..47a97bafb6 100644
--- a/packages/subagent/subagent-subprocess/src/index.ts
+++ b/packages/subagent/subagent-subprocess/src/index.ts
@@ -51,16 +51,6 @@ export function spawnFailure(child: ChildProcess): Promise<Error> {
   })
 }
 
-/**
- * Resolve once the child process exits (any code/signal); immediate if it is
- * already gone.
- * @param child - the child process to await.
- */
-function waitForExit(child: ChildProcess): Promise<void> {
-  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve()
-  return new Promise<void>(resolve => child.once('exit', () => { resolve() }))
-}
-
 /**
  * Race the child's exit against a timer. Neither outcome leaves anything
  * behind on the child: the exit listener is removed on timeout and the timer
@@ -104,10 +94,49 @@ export interface DisposeLadderGraces {
    * headroom.
    */
   disposeEofGraceMs: number
-  /** POSIX tier-2 window (ms): between `SIGTERM` and the `SIGKILL` escalation. */
+  /**
+   * Termination confirmation window (ms): POSIX applies it after `SIGTERM` and again after
+   * `SIGKILL`; Windows applies it after the direct forced termination.
+   */
   disposeGraceMs: number
 }
 
+/** Force-terminate a child and reject if no exit edge arrives within the configured grace. */
+function forceTerminateWithin(child: ChildProcess, ms: number): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve()
+  return new Promise<void>((resolve, reject) => {
+    let accepted = false
+    let settled = false
+    const cleanup = (): void => {
+      clearTimeout(timer)
+      child.off('exit', onExit)
+      child.off('error', onError)
+    }
+    const settle = (complete: () => void): void => {
+      if (settled) return
+      settled = true
+      cleanup()
+      complete()
+    }
+    const onExit = (): void => { settle(resolve) }
+    const onError = (error: Error): void => { settle(() => { reject(error) }) }
+    child.once('exit', onExit)
+    child.once('error', onError)
+    const timer = setTimeout(() => {
+      const disposition = accepted ? 'accepted' : 'refused'
+      settle(() => {
+        reject(new Error(`child process did not exit within ${ms}ms after SIGKILL was ${disposition}`))
+      })
+    }, ms).unref()
+    try {
+      accepted = child.kill('SIGKILL')
+      if (child.exitCode !== null || child.signalCode !== null) settle(resolve)
+    } catch (error: unknown) {
+      settle(() => { reject(new Error('SIGKILL failed', { cause: error })) })
+    }
+  })
+}
+
 /**
  * Tear a child process down to quiescence, resolving only after exit: close stdin and allow
  * cooperative flush, then use the host's graceful and forced termination semantics. POSIX
@@ -117,6 +146,8 @@ export interface DisposeLadderGraces {
  * @param child - the child process to tear down.
  * @param graces - the two grace periods, from the consuming plugin's Config.
  * @param platform - the host platform, injectable for unit coverage.
+ * @throws When forced termination errors or the child does not report exit within
+ * `disposeGraceMs`.
  */
 export async function disposeChildProcess(
   child: ChildProcess,
@@ -133,9 +164,8 @@ export async function disposeChildProcess(
     child.kill('SIGTERM')
     if (await exitsWithin(child, graces.disposeGraceMs)) return
   }
-  // 3. Force-kill and await the (now-certain) exit.
-  child.kill('SIGKILL')
-  await waitForExit(child)
+  // 3. Force-kill and await a bounded exit edge.
+  await forceTerminateWithin(child, graces.disposeGraceMs)
 }
 
 /**
diff --git a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts
index 901989e074..7c17333c03 100644
--- a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts
+++ b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts
@@ -234,6 +234,71 @@ describe('disposeChildProcess', () => {
     expect(fake.kills).toEqual(['SIGKILL'])
     expect(fake.signalCode).toBe('SIGKILL')
   })
+
+  it('propagates a forced-termination error without waiting for the grace', async () => {
+    const fake = new FakeChild()
+    const failure = Object.assign(new Error('kill EPERM'), { code: 'EPERM' })
+    vi.spyOn(fake, 'kill').mockImplementation((signal) => {
+      fake.kills.push(signal)
+      fake.emit('error', failure)
+      return false
+    })
+
+    await expect(disposeChildProcess(
+      asChild(fake),
+      { disposeEofGraceMs: 1, disposeGraceMs: 1000 },
+      'win32',
+    )).rejects.toBe(failure)
+    expect(fake.kills).toEqual(['SIGKILL'])
+    expect(fake.listenerCount('error')).toBe(0)
+    expect(fake.listenerCount('exit')).toBe(0)
+  })
+
+  it('wraps a synchronous forced-termination exception and removes its listeners', async () => {
+    const fake = new FakeChild()
+    const failure = new Error('invalid signal state')
+    vi.spyOn(fake, 'kill').mockImplementation(() => { throw failure })
+
+    await expect(disposeChildProcess(
+      asChild(fake),
+      { disposeEofGraceMs: 1, disposeGraceMs: 1000 },
+      'win32',
+    )).rejects.toMatchObject({ message: 'SIGKILL failed', cause: failure })
+    expect(fake.listenerCount('error')).toBe(0)
+    expect(fake.listenerCount('exit')).toBe(0)
+  })
+
+  it('bounds a refused forced termination that produces no error or exit', async () => {
+    const fake = new FakeChild()
+    vi.spyOn(fake, 'kill').mockImplementation((signal) => {
+      fake.kills.push(signal)
+      return false
+    })
+
+    await expect(disposeChildProcess(
+      asChild(fake),
+      { disposeEofGraceMs: 1, disposeGraceMs: 10 },
+      'win32',
+    )).rejects.toThrow('child process did not exit within 10ms after SIGKILL was refused')
+    expect(fake.listenerCount('error')).toBe(0)
+    expect(fake.listenerCount('exit')).toBe(0)
+  })
+
+  it('bounds an accepted forced termination that never reports exit', async () => {
+    const fake = new FakeChild()
+    vi.spyOn(fake, 'kill').mockImplementation((signal) => {
+      fake.kills.push(signal)
+      return true
+    })
+
+    await expect(disposeChildProcess(
+      asChild(fake),
+      { disposeEofGraceMs: 1, disposeGraceMs: 10 },
+      'win32',
+    )).rejects.toThrow('child process did not exit within 10ms after SIGKILL was accepted')
+    expect(fake.listenerCount('error')).toBe(0)
+    expect(fake.listenerCount('exit')).toBe(0)
+  })
 })
 
 describe('createIsolatedConfigDir', () => {

From 46580e408329e027414273527bac39dbd39b1650 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 12:20:11 +0800
Subject: [PATCH 26/74] test(subagent): pin POSIX disposal scenarios

Pass an explicit Linux platform to the two remaining SIGTERM-specific ladder tests instead of inheriting the host platform.

This keeps their synchronous-exit assertions focused on the POSIX middle and final rungs while the dedicated Windows case continues to verify the direct SIGKILL path.

Without the pin, native Windows coverage deterministically expected SIGTERM but observed the intended SIGKILL-only behavior.
---
 .../subagent-subprocess/tests/subagent-subprocess.spec.ts     | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts
index 7c17333c03..e81957baa0 100644
--- a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts
+++ b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts
@@ -200,7 +200,7 @@ describe('disposeChildProcess', () => {
 
   it('recognizes a child that exits synchronously on SIGTERM', async () => {
     const fake = new FakeChild({ diesOn: 'SIGTERM', synchronousExit: true })
-    await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 })
+    await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }, 'linux')
     expect(fake.kills).toEqual(['SIGTERM'])
     expect(fake.signalCode).toBe('SIGTERM')
     expect(fake.listenerCount('exit')).toBe(0)
@@ -217,7 +217,7 @@ describe('disposeChildProcess', () => {
 
   it('recognizes a child already gone when the final exit wait begins', async () => {
     const fake = new FakeChild({ synchronousExit: true })
-    await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 20 })
+    await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 20 }, 'linux')
     expect(fake.kills).toEqual(['SIGTERM', 'SIGKILL'])
     expect(fake.signalCode).toBe('SIGKILL')
   })

From 2b673bd68dbc41798d138454e4def2b2f265046f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 12:38:18 +0800
Subject: [PATCH 27/74] fix(fs): preserve Windows DACLs across atomic
 replacement

Copy an existing target's DACL onto the empty staging file before any content is written, then publish with ReplaceFileW so Windows replacement keeps the target security descriptor instead of inheriting the broader parent policy.

Keep new-file inheritance and POSIX mode behavior unchanged, retain the already-protected temp when a concurrently removed target requires rename fallback, and translate native errors into Node-style codes for the filesystem error boundary.

Add host-independent Win32 binding coverage, native Windows descriptor assertions, package documentation, and a bilingual implemented RFC that supersedes the earlier inheritance-only replacement claim.
---
 docs/rfc/INDEX.md                             |   6 +
 .../2026-07-05-windows-fs-permissions.md      |  14 +-
 ...s-atomic-write-dacl-preservation.i18n.yaml |   6 +
 ...-windows-atomic-write-dacl-preservation.md |  27 ++++
 ...ndows-atomic-write-dacl-preservation.zh.md |  27 ++++
 packages/fs/fs-local/README.md                |   2 +-
 packages/fs/fs-local/package.json             |   1 +
 packages/fs/fs-local/src/fsio.ts              |  34 +++-
 packages/fs/fs-local/src/win32.ts             | 134 ++++++++++++++++
 packages/fs/fs-local/tests/fsio.spec.ts       |  89 ++++++++++-
 packages/fs/fs-local/tests/win32.spec.ts      | 145 ++++++++++++++++++
 pnpm-lock.yaml                                |   3 +
 12 files changed, 472 insertions(+), 16 deletions(-)
 create mode 100644 docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml
 create mode 100644 docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md
 create mode 100644 docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md
 create mode 100644 packages/fs/fs-local/src/win32.ts
 create mode 100644 packages/fs/fs-local/tests/win32.spec.ts

diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md
index ceaf70cd87..6ca005be8d 100644
--- a/docs/rfc/INDEX.md
+++ b/docs/rfc/INDEX.md
@@ -89,6 +89,12 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [Optional time-context plugin](implemented/feature/2026-07-14-time-context-plugin.md) | 2026-07-14 |
 | [Durable per-step time context](implemented/feature/2026-07-16-durable-per-step-time-context.md) | 2026-07-16 |
 
+### Bug-fix
+
+| Title | First proposed |
+|---|---|
+| [Preserve Windows DACLs during atomic file replacement](implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md) | 2026-07-19 |
+
 ### Simplification
 
 | Title | First proposed |
diff --git a/docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md b/docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md
index 0001e8223c..4d477990cd 100644
--- a/docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md
+++ b/docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md
@@ -2,21 +2,23 @@
 
 Status: implemented
 
+The replacement-file decision in this record is superseded by [Windows DACL preservation](../bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md).
+
 ## Problem
 
 `writeFileAtomic` in `@deepseek-ai/dsh-fs-local` protects write-in-progress content with POSIX mode bits: the staging directory is created `0o700`, the temp file is opened `0o600`, and new files default to `0o600`. On POSIX this keeps temporary content owner-only regardless of the parent directory's permissions.
 
-Windows has no working equivalent behind the same API. Node's `chmod` there drives only the read-only attribute (every mode this package passes carries owner-write, so the calls are benign no-ops), and `stat().mode` reports synthetic `0o666`/`0o444` bits. The real security state is the file's DACL, which this code never sets; a newly created file or directory inherits its DACL from its parent directory.
+Windows has no working equivalent behind the same API. Node's `chmod` there drives only the read-only attribute (every mode this package passes carries owner-write, so the calls are benign no-ops), and `stat().mode` reports synthetic `0o666`/`0o444` bits. The real security state is the file's DACL: a newly created file or directory inherits from its parent, while replacement needs the explicit handling owned by the superseding RFC.
 
 ## Decision
 
-Production code is unchanged: no platform fork, no DACL management. The Windows privacy invariant is structural rather than mode-driven — the staging directory is created inside the target's parent directory (`dirname(absolutePath)`), so it and the temp file inherit exactly the destination directory's DACL, and write-in-progress content is never exposed more widely than the destination itself. In the typical deployment (a coding agent writing the user's own project tree under `C:\Users\<user>\`) the inherited DACL is owner + SYSTEM + Administrators, matching the POSIX intent.
+New Windows files use directory inheritance rather than synthetic mode bits: the staging directory is created inside the target's parent directory (`dirname(absolutePath)`), so it and the temp file inherit the destination directory's DACL. Replacement files follow the stricter [DACL preservation contract](../bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md).
 
-Tests assert mode bits on POSIX only. There is no Windows-side ACL assertion because there is no Windows-side code behavior to pin: an ACL check on a `mkdtemp(tmpdir())` fixture would verify Windows DACL inheritance plus the machine's `%TEMP%` ACL — the operating system, not this package — and no change to this package could turn it red.
+Tests assert mode bits on POSIX only. Native Windows coverage pins the package-owned replacement behavior; new-file inheritance remains an operating-system contract rather than a machine-specific ACL allowlist.
 
 ## Alternatives considered
 
-**Explicit protected DACLs.** Granting owner-only access would require per-write FFI or a subprocess, break inheritance, and surprise users whose project directories are deliberately shared. This becomes appropriate only if the threat model includes hostile local readers of broadly accessible target directories.
+**Explicit owner-only DACLs for new files.** Rejected because they would break inheritance and surprise users whose project directories are deliberately shared. Replacement writes copy the target's existing DACL rather than inventing an owner-only policy.
 
 **Test-side ACL verification.** A `Get-Acl` SID allowlist or `icacls` would verify Windows inheritance and the machine's `%TEMP%` ACL rather than package behavior; `icacls` also localizes well-known account names, making parsing locale-fragile.
 
@@ -24,6 +26,6 @@ Tests assert mode bits on POSIX only. There is no Windows-side ACL assertion bec
 
 ## Consequences
 
-POSIX keeps the stronger guarantee: owner-only temp content regardless of the parent directory. Windows guarantees only "no wider than the destination": a target inside a broadly accessible directory (a share, a permissive `D:\` root) gets equally accessible write-in-progress content. The gap is deliberate and documented, not an oversight.
+POSIX keeps owner-only temp content regardless of the parent directory. A new Windows target inside a broadly accessible directory inherits that accessibility by design; a replacement retains the target's narrower DACL when one exists.
 
-Mode preservation across a replace degenerates to a no-op on Windows: a writable file probes as `0o666`, and replaying that through `chmod` leaves the read-only attribute clear. A read-only target cannot be replaced at all there — `rename` over it fails before the preserved mode would matter.
+Mode preservation across a replace degenerates to a no-op on Windows: a writable file probes as `0o666`, and replaying that through `chmod` leaves the read-only attribute clear. A read-only target cannot be replaced there because publication fails before the synthetic mode would matter.
diff --git a/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml
new file mode 100644
index 0000000000..5f37bf3ca3
--- /dev/null
+++ b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-19-windows-atomic-write-dacl-preservation.md: 393ce8a992b8c0b7b580f2c794e098d66e14258e
+2026-07-19-windows-atomic-write-dacl-preservation.zh.md: c7a0b6278cf739cc5ef4432d679e48b88b61d198
diff --git a/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md
new file mode 100644
index 0000000000..393ce8a992
--- /dev/null
+++ b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md
@@ -0,0 +1,27 @@
+# RFC: Preserve Windows DACLs during atomic file replacement
+
+Status: implemented
+
+English | [中文](2026-07-19-windows-atomic-write-dacl-preservation.zh.md)
+
+## Problem
+
+On Windows, creating the staging directory and temp file under the target's parent and relying only on inherited DACLs is sufficient for a new file, but not for replacing an existing file whose explicit or protected DACL is narrower than its parent: content is written under the broader parent DACL, and rename carries that staging descriptor onto the replacement.
+
+## Decision
+
+`dsh-fs-local` reads an existing target's DACL with `GetFileSecurityW`, applies it to the empty temp file with inheritance protected before writing content, and publishes the closed temp with `ReplaceFileW`. The protected staging descriptor prevents the temp directory's inherited entries from broadening access; `ReplaceFileW` preserves the original target security descriptor and other replacement metadata. New files have no prior descriptor to preserve and continue to inherit the destination directory's DACL.
+
+Native Windows coverage protects a target DACL, inspects the written staging file, and compares the final replacement descriptor. Host-independent binding tests cover Win32 error translation and every native call boundary.
+
+## Alternatives considered
+
+**Rely on directory inheritance for replacements.** Rejected because a target may carry a narrower explicit or protected DACL than its parent, so inheritance neither protects staged content nor preserves the target access policy.
+
+**Use `ReplaceFileW` without protecting the temp.** Rejected because it repairs the final descriptor only after the content has already been written under the staging file's inherited DACL.
+
+**Install an owner-only DACL for every write.** Rejected because it would discard deliberate project sharing. Copying the target DACL preserves the deployment's existing access policy instead of inventing one.
+
+## Consequences
+
+Replacing a Windows file now requires permission to read the target DACL and set the temp DACL; failure is loud before content is written. The package carries Koffi for the narrow Win32 calls, loaded only on Windows replacement paths. New-file behavior remains directory-inherited, and POSIX mode behavior is unchanged.
diff --git a/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md
new file mode 100644
index 0000000000..c7a0b6278c
--- /dev/null
+++ b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md
@@ -0,0 +1,27 @@
+# RFC: Windows 原子文件替换期间保留 DACL
+
+Status: implemented
+
+[English](2026-07-19-windows-atomic-write-dacl-preservation.md) | 中文
+
+## 问题
+
+在 Windows 上，在目标文件的父目录下创建暂存目录和临时文件，并且只依赖继承的 DACL，足以满足新建文件的需要，但无法安全替换显式或受保护 DACL 比父目录更严格的现有文件：内容会在权限更宽松的父目录 DACL 下写入，而重命名又会把这个暂存安全描述符带到替换后的文件上。
+
+## 决策
+
+`dsh-fs-local` 通过 `GetFileSecurityW` 读取现有目标文件的 DACL，在写入内容前将其以禁止继承的形式应用到空临时文件，并通过 `ReplaceFileW` 发布已关闭的临时文件。受保护的暂存安全描述符可防止暂存目录中的继承条目扩大访问权限；`ReplaceFileW` 会保留原目标文件的安全描述符及其他替换元数据。新建文件没有既有描述符需要保留，因此仍继承目标目录的 DACL。
+
+Windows 原生覆盖率测试会保护目标文件的 DACL、检查写入完成的暂存文件，并对比最终替换文件的描述符。与宿主平台无关的绑定测试覆盖 Win32 错误转换以及每个原生调用边界。
+
+## 备选方案
+
+**替换文件时依赖目录继承。** 不予采用，因为目标文件可能带有比父目录更严格的显式或受保护 DACL；目录继承既无法保护暂存内容，也无法保留目标文件的访问策略。
+
+**使用 `ReplaceFileW`，但不保护临时文件。** 不予采用，因为这只能在内容已经按暂存文件继承的 DACL 写入之后修复最终描述符。
+
+**每次写入都设置仅所有者可访问的 DACL。** 不予采用，因为这会破坏项目有意设置的共享权限。复制目标文件的 DACL 可以保留部署中已有的访问策略，无需另行创设策略。
+
+## 影响
+
+替换 Windows 文件现在要求调用方有权读取目标 DACL 并设置临时文件 DACL；如果权限不足，系统会在写入内容前明确失败。该包（package）引入 Koffi 以执行少量 Win32 调用，并且只在 Windows 替换路径上加载。新建文件仍按目录继承，POSIX mode 行为保持不变。
diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md
index 7c3899e5cb..551492db67 100644
--- a/packages/fs/fs-local/README.md
+++ b/packages/fs/fs-local/README.md
@@ -16,7 +16,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **`stat` / `lstat`** — return target metadata or `undefined` when absent. `stat` reports `FsInfo` for an already resolved target (`version` = an opaque token derived from bigint `dev:ino:size:mtimeNs:ctimeNs`, `type` of `file`/`directory`/`other`, byte `size`); path-shaped `lstat` reports `FsPathInfo` without following the final symlink and can therefore return `symlink`. Both check cancellation before and after their asynchronous metadata probe, so an abort that lands in flight reports `FS_ABORTED` rather than stale absence.
 - **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` streams it in chunks (cross-chunk decoding) so a huge file never has to be held whole in memory. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) decides which to call by size and owns the line windowing.
 - **`listDir`** — lists one directory level in stable `name.localeCompare()` order. Each entry carries the child basename, type, resolved child target (`displayPath` under the listed directory, `targetKey` as the realpath identity), and cheap stat metadata (`version`, plus `size` for regular files). It never opens or decodes file contents. Missing targets report `FS_NOT_FOUND`, file/special-file targets report `FS_NOT_DIRECTORY`, aborted calls report `FS_ABORTED`, permission failures report `FS_PERMISSION_DENIED`, and other listing or child metadata I/O failures report `FS_IO_ERROR`. Broken/disappeared children are returned as `other` without metadata, but permission/IO failures while resolving a child fail the whole listing with a structured `FsError`.
-- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`; on Windows the mode bits drive only the read-only attribute, and write-in-progress privacy comes instead from the staging dir inheriting the destination directory's DACL ([Windows write-permission RFC](../../../docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
+- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original descriptor survives ([Windows DACL preservation RFC](../../../docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
 - **`editText`** — atomic literal read-modify-write over the same primitive, serialized per target by a mutation lock. The `expected` guard is OPTIONAL: when supplied it verifies the version BEFORE literal matching (a stale edit reports `FS_STALE_VERSION`, never `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` against newer content); omitting it edits the current content unconditionally. A missing target reports `FS_STALE_VERSION` either way. LF-normalizes for matching, restores the file's dominant CRLF/LF style, and rejects empty `oldString` / zero matches (`FS_EDIT_NOT_FOUND`) or ambiguous multi-matches without `replace_all` (`FS_AMBIGUOUS_EDIT`).
 
 The package-root SDK surface is the default/named `LocalFileSystem` class plus `Config`. Raw I/O lives in `src/fsio.ts` (Cordis-free, independently unit-tested); `src/index.ts` is the thin service wiring.
diff --git a/packages/fs/fs-local/package.json b/packages/fs/fs-local/package.json
index dd80cb4d9c..ded2a9d55f 100644
--- a/packages/fs/fs-local/package.json
+++ b/packages/fs/fs-local/package.json
@@ -26,6 +26,7 @@
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
+    "koffi": "^3.1.0",
     "schemastery": "^3.18.0"
   },
   "devDependencies": {
diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts
index 05d957105a..549554043f 100644
--- a/packages/fs/fs-local/src/fsio.ts
+++ b/packages/fs/fs-local/src/fsio.ts
@@ -12,6 +12,7 @@ import type { BigIntStats, Dirent, Stats } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
 import { TextDecoder } from 'node:util'
 import { FsError, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
+import { copyFileDaclWin32, replaceFileWin32 } from './win32.ts'
 
 const BINARY_SAMPLE_BYTES = 8192
 
@@ -74,10 +75,16 @@ function versionOf(info: BigIntStats): FsVersion {
  * file before it is renamed over the target.
  */
 export interface FsIoInternals {
+  /** Override the host platform for native-publication unit coverage. */
+  platform?: NodeJS.Platform
   /** Override the generated private staging-dir name (relative to the target dir). */
   tempDirName?: (writePath: string) => string
   /** Override the generated temp-file name (relative to the private staging dir). */
   tempName?: (writePath: string) => string
+  /** Override the Win32 DACL copy boundary. */
+  copyFileDacl?: (source: string, destination: string) => Promise<void>
+  /** Override the Win32 security-preserving replacement boundary. */
+  replaceFile?: (replaced: string, replacement: string) => Promise<void>
   /** Test hook after the temp file is written/synced but before final chmod+rename. */
   inspectTemp?: (paths: { stagingDir: string; tempPath: string }) => void | Promise<void>
 }
@@ -412,11 +419,13 @@ async function removeStagingDirOrThrow(stagingDir: string, originalError: unknow
 
 /**
  * Atomically replace a file through a private, synced staging file in the same directory.
- * POSIX protects the staging directory and file with `0o700` and `0o600`; Windows
- * inherits the destination directory's DACL because Node mode bits are synthetic there.
+ * POSIX protects the staging directory and file with `0o700` and `0o600`. A new Windows file
+ * inherits the destination directory's DACL; a replacement copies the existing target's DACL
+ * onto the empty temp before writing and preserves the target descriptor at publication.
  * @param absolutePath - destination; missing parent directories are created.
  * @param content - the full UTF-8 text to write.
- * @param mode - final POSIX mode, or `0o600` when omitted; inert on Windows.
+ * @param mode - existing destination's POSIX mode to preserve, or `undefined` for a new file;
+ * inert as a mode on Windows but identifies replacement security semantics.
  * @param signal - cancellation checked before the final rename.
  * @param internals - test seam for pinning temp names and observing the staged file.
  */
@@ -436,6 +445,9 @@ export async function writeFileAtomic(
   const stagingDir = join(directory, stagingDirName)
   const tempName = internals.tempName?.(absolutePath) ?? `${basename(absolutePath)}.tmp`
   const tempPath = join(stagingDir, tempName)
+  const platform = internals.platform ?? process.platform
+  const copyFileDacl = internals.copyFileDacl ?? copyFileDaclWin32
+  const replaceFile = internals.replaceFile ?? replaceFileWin32
   let handle: Awaited<ReturnType<typeof open>> | undefined
   let stagingCreated = false
   try {
@@ -445,6 +457,9 @@ export async function writeFileAtomic(
 
     handle = await open(tempPath, 'wx', 0o600)
     await handle.chmod(0o600)
+    if (platform === 'win32' && mode !== undefined) {
+      await copyFileDacl(absolutePath, tempPath)
+    }
     await handle.writeFile(content, { encoding: 'utf8', ...signal ? { signal } : {} })
     await handle.sync()
     await internals.inspectTemp?.({ stagingDir, tempPath })
@@ -453,7 +468,18 @@ export async function writeFileAtomic(
     handle = undefined
 
     throwIfAborted(signal, 'write')
-    await rename(tempPath, absolutePath)
+    if (platform === 'win32' && mode !== undefined) {
+      try {
+        await replaceFile(absolutePath, tempPath)
+      } catch (error: unknown) {
+        // Preserve the old behavior when an external actor removes the observed target during
+        // staging: the temp already carries that target's protected DACL, so rename recreates it.
+        if (!isENOENT(error)) throw error
+        await rename(tempPath, absolutePath)
+      }
+    } else {
+      await rename(tempPath, absolutePath)
+    }
     await rm(stagingDir, { recursive: true, force: true })
   } catch (error: unknown) {
     /* v8 ignore next -- abort-mid-write needs a writeFile/signal race; the non-abort (rename/open) side is tested. */
diff --git a/packages/fs/fs-local/src/win32.ts b/packages/fs/fs-local/src/win32.ts
new file mode 100644
index 0000000000..6f459898a9
--- /dev/null
+++ b/packages/fs/fs-local/src/win32.ts
@@ -0,0 +1,134 @@
+/**
+ * Windows security-descriptor helpers for atomic local-file replacement. Koffi loads lazily so
+ * non-Windows processes never open Win32 libraries.
+ * @module @deepseek-ai/dsh-fs-local/win32
+ */
+
+import { toNamespacedPath } from 'node:path'
+
+type GetFileSecurityW = (
+  path: string,
+  requestedInformation: number,
+  descriptor: Buffer | null,
+  length: number,
+  needed: [number],
+) => number
+type SetFileSecurityW = (path: string, securityInformation: number, descriptor: Buffer) => number
+type ReplaceFileW = (
+  replaced: string,
+  replacement: string,
+  backup: null,
+  flags: number,
+  exclude: null,
+  reserved: null,
+) => number
+type GetLastError = () => number
+
+interface Win32Bindings {
+  getFileSecurityW: GetFileSecurityW
+  setFileSecurityW: SetFileSecurityW
+  replaceFileW: ReplaceFileW
+  getLastError: GetLastError
+}
+
+interface Win32ErrnoException extends NodeJS.ErrnoException {
+  win32Code: number
+}
+
+const DACL_SECURITY_INFORMATION = 0x00000004
+const PROTECTED_DACL_SECURITY_INFORMATION = 0x80000000
+const ERROR_FILE_NOT_FOUND = 2
+const ERROR_PATH_NOT_FOUND = 3
+const ERROR_ACCESS_DENIED = 5
+
+let bindings: Win32Bindings | undefined
+
+async function win32(): Promise<Win32Bindings> {
+  if (bindings !== undefined) return bindings
+  const koffi = (await import('koffi')).default
+  const advapi32 = koffi.load('advapi32.dll')
+  const kernel32 = koffi.load('kernel32.dll')
+  bindings = {
+    getFileSecurityW: advapi32.func('int __stdcall GetFileSecurityW(const char16_t *path, uint32_t requested, void *descriptor, uint32_t length, _Out_ uint32_t *needed)') as GetFileSecurityW,
+    setFileSecurityW: advapi32.func('int __stdcall SetFileSecurityW(const char16_t *path, uint32_t information, const void *descriptor)') as SetFileSecurityW,
+    replaceFileW: kernel32.func('int __stdcall ReplaceFileW(const char16_t *replaced, const char16_t *replacement, const char16_t *backup, uint32_t flags, void *exclude, void *reserved)') as ReplaceFileW,
+    getLastError: kernel32.func('uint32_t __stdcall GetLastError()') as GetLastError,
+  }
+  return bindings
+}
+
+function errnoCode(win32Code: number): string {
+  switch (win32Code) {
+    case ERROR_FILE_NOT_FOUND:
+    case ERROR_PATH_NOT_FOUND:
+      return 'ENOENT'
+    case ERROR_ACCESS_DENIED:
+      return 'EACCES'
+    default:
+      return 'EIO'
+  }
+}
+
+function win32Error(syscall: string, win32Code: number, path: string): Win32ErrnoException {
+  const code = errnoCode(win32Code)
+  const error = new Error(`${syscall} ${code} (Win32 ${win32Code}): ${path}`) as Win32ErrnoException
+  error.code = code
+  error.errno = win32Code
+  error.syscall = syscall
+  error.path = path
+  error.win32Code = win32Code
+  return error
+}
+
+/**
+ * Read a file's self-relative DACL security descriptor.
+ * @param path - existing file whose DACL is read.
+ * @returns a descriptor buffer accepted by `SetFileSecurityW`.
+ */
+export async function readFileDaclWin32(path: string): Promise<Buffer> {
+  const api = await win32()
+  const nativePath = toNamespacedPath(path)
+  const needed: [number] = [0]
+  api.getFileSecurityW(nativePath, DACL_SECURITY_INFORMATION, null, 0, needed)
+  if (needed[0] === 0) throw win32Error('GetFileSecurityW', api.getLastError(), path)
+
+  const descriptor = Buffer.alloc(needed[0])
+  if (api.getFileSecurityW(nativePath, DACL_SECURITY_INFORMATION, descriptor, descriptor.length, needed) === 0) {
+    throw win32Error('GetFileSecurityW', api.getLastError(), path)
+  }
+  return descriptor.subarray(0, needed[0])
+}
+
+/**
+ * Copy an existing file's DACL onto another file and protect it from staging-parent inheritance.
+ * The destination must still be empty when confidentiality depends on this call.
+ * @param source - existing file whose DACL is copied.
+ * @param destination - existing file that receives the protected DACL.
+ */
+export async function copyFileDaclWin32(source: string, destination: string): Promise<void> {
+  const descriptor = await readFileDaclWin32(source)
+  const api = await win32()
+  const information = (DACL_SECURITY_INFORMATION | PROTECTED_DACL_SECURITY_INFORMATION) >>> 0
+  if (api.setFileSecurityW(toNamespacedPath(destination), information, descriptor) === 0) {
+    throw win32Error('SetFileSecurityW', api.getLastError(), destination)
+  }
+}
+
+/**
+ * Replace a Windows file while preserving the replaced file's ACL and other replace metadata.
+ * @param replaced - existing destination file.
+ * @param replacement - closed staging file on the same volume.
+ */
+export async function replaceFileWin32(replaced: string, replacement: string): Promise<void> {
+  const api = await win32()
+  if (api.replaceFileW(
+    toNamespacedPath(replaced),
+    toNamespacedPath(replacement),
+    null,
+    0,
+    null,
+    null,
+  ) === 0) {
+    throw win32Error('ReplaceFileW', api.getLastError(), replaced)
+  }
+}
diff --git a/packages/fs/fs-local/tests/fsio.spec.ts b/packages/fs/fs-local/tests/fsio.spec.ts
index 559ef86563..d292f0bfb7 100644
--- a/packages/fs/fs-local/tests/fsio.spec.ts
+++ b/packages/fs/fs-local/tests/fsio.spec.ts
@@ -6,7 +6,7 @@
  */
 
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-import { chmod, mkdtemp, readFile, rm, stat, symlink, unlink, writeFile, mkdir, readdir, realpath } from 'node:fs/promises'
+import { chmod, mkdtemp, readFile, rename, rm, stat, symlink, unlink, writeFile, mkdir, readdir, realpath } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { createServer } from 'node:net'
@@ -23,6 +23,7 @@ import {
   writeFileAtomic,
 } from '../src/fsio.ts'
 import type { LocalTarget } from '../src/fsio.ts'
+import { copyFileDaclWin32, readFileDaclWin32 } from '../src/win32.ts'
 import { FsError, FsTargetKey } from '@deepseek-ai/dsh-fs'
 
 let dir: string
@@ -367,15 +368,15 @@ describe('streamWholeText', () => {
   })
 })
 
-// Windows drives only the read-only attribute through `chmod` and reports
-// synthetic `stat` mode bits, so mode assertions are POSIX-only; on Windows
-// write-in-progress privacy comes from the destination directory's inherited
-// DACL (docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md).
+// Windows drives only the read-only attribute through `chmod` and reports synthetic `stat` mode
+// bits, so mode assertions are POSIX-only; native DACL preservation is asserted separately.
 const posixModes = process.platform !== 'win32'
 
 describe('writeFileAtomic — temp-file safety', () => {
   it('writes through a private staging dir and owner-only temp file', async () => {
     const file = join(dir, 'a.txt')
+    await writeFile(file, 'old')
+    if (posixModes) await chmod(file, 0o640)
     let inspected = false
     await writeFileAtomic(file, 'hello', 0o640, undefined, {
       inspectTemp: async ({ stagingDir, tempPath }) => {
@@ -395,6 +396,84 @@ describe('writeFileAtomic — temp-file safety', () => {
     expect((await readdir(dir)).filter(n => n.includes('.tmp'))).toEqual([])
   })
 
+  it.skipIf(process.platform !== 'win32')('protects staged content with the existing target DACL and preserves it after replacement', async () => {
+    const file = join(dir, 'protected.txt')
+    await writeFile(file, 'old')
+    await copyFileDaclWin32(file, file)
+    const expectedDacl = await readFileDaclWin32(file)
+
+    await writeFileAtomic(file, 'new', (await stat(file)).mode, undefined, {
+      inspectTemp: async ({ tempPath }) => {
+        expect(await readFileDaclWin32(tempPath)).toEqual(expectedDacl)
+      },
+    })
+
+    expect(await readFile(file, 'utf8')).toBe('new')
+    expect(await readFileDaclWin32(file)).toEqual(expectedDacl)
+  })
+
+  it('copies a Windows target DACL before content and publishes through secure replacement', async () => {
+    const file = join(dir, 'a.txt')
+    await writeFile(file, 'old')
+    const calls: string[] = []
+
+    await writeFileAtomic(file, 'new', 0o666, undefined, {
+      platform: 'win32',
+      copyFileDacl: async (source, temp) => {
+        calls.push(`copy:${source}`)
+        expect(await readFile(temp, 'utf8')).toBe('')
+      },
+      replaceFile: async (target, temp) => {
+        calls.push(`replace:${target}`)
+        await rename(temp, target)
+      },
+    })
+
+    expect(calls).toEqual([`copy:${file}`, `replace:${file}`])
+    expect(await readFile(file, 'utf8')).toBe('new')
+  })
+
+  it('creates a new Windows file through directory inheritance without replacement calls', async () => {
+    const file = join(dir, 'new.txt')
+    const unexpected = async (): Promise<void> => { throw new Error('unexpected native replacement call') }
+
+    await writeFileAtomic(file, 'new', undefined, undefined, {
+      platform: 'win32',
+      copyFileDacl: unexpected,
+      replaceFile: unexpected,
+    })
+
+    expect(await readFile(file, 'utf8')).toBe('new')
+  })
+
+  it('recreates a vanished Windows target with the already-protected temp', async () => {
+    const file = join(dir, 'a.txt')
+    await writeFile(file, 'old')
+    const missing = Object.assign(new Error('target vanished'), { code: 'ENOENT' })
+
+    await writeFileAtomic(file, 'new', 0o666, undefined, {
+      platform: 'win32',
+      copyFileDacl: () => Promise.resolve(),
+      replaceFile: async () => { throw missing },
+    })
+
+    expect(await readFile(file, 'utf8')).toBe('new')
+  })
+
+  it('surfaces a Windows secure-replacement failure and cleans the staging directory', async () => {
+    const file = join(dir, 'a.txt')
+    await writeFile(file, 'old')
+    const denied = Object.assign(new Error('replace denied'), { code: 'EACCES' })
+
+    await expect(writeFileAtomic(file, 'new', 0o666, undefined, {
+      platform: 'win32',
+      copyFileDacl: () => Promise.resolve(),
+      replaceFile: async () => { throw denied },
+    })).rejects.toBe(denied)
+    expect(await readFile(file, 'utf8')).toBe('old')
+    expect((await readdir(dir)).filter(name => name.includes('.tmp'))).toEqual([])
+  })
+
   it.skipIf(!posixModes)('creates new files owner-only by default', async () => {
     const file = join(dir, 'a.txt')
     await writeFileAtomic(file, 'hello', undefined, undefined)
diff --git a/packages/fs/fs-local/tests/win32.spec.ts b/packages/fs/fs-local/tests/win32.spec.ts
new file mode 100644
index 0000000000..dc2b69ea82
--- /dev/null
+++ b/packages/fs/fs-local/tests/win32.spec.ts
@@ -0,0 +1,145 @@
+/** Host-independent binding tests for the Win32 DACL and replacement helpers. */
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+type GetFileSecurityW = (
+  path: string,
+  requestedInformation: number,
+  descriptor: Buffer | null,
+  length: number,
+  needed: [number],
+) => number
+type SetFileSecurityW = (path: string, securityInformation: number, descriptor: Buffer) => number
+type ReplaceFileW = (
+  replaced: string,
+  replacement: string,
+  backup: null,
+  flags: number,
+  exclude: null,
+  reserved: null,
+) => number
+
+interface NativeMock {
+  getFileSecurityW: GetFileSecurityW
+  setFileSecurityW: SetFileSecurityW
+  replaceFileW: ReplaceFileW
+  getLastError: () => number
+}
+
+async function importWithNative(native: NativeMock): Promise<typeof import('../src/win32.ts')> {
+  vi.resetModules()
+  vi.doMock('koffi', () => ({
+    default: {
+      load: () => ({
+        func: (definition: string) => {
+          if (definition.includes('GetFileSecurityW')) return native.getFileSecurityW
+          if (definition.includes('SetFileSecurityW')) return native.setFileSecurityW
+          if (definition.includes('ReplaceFileW')) return native.replaceFileW
+          if (definition.includes('GetLastError')) return native.getLastError
+          throw new Error(`unexpected native function: ${definition}`)
+        },
+      }),
+    },
+  }))
+  return import('../src/win32.ts')
+}
+
+function successfulNative(descriptor: Buffer): NativeMock & { installed: Buffer[]; replacements: string[][] } {
+  let lastError = 0
+  const installed: Buffer[] = []
+  const replacements: string[][] = []
+  return {
+    installed,
+    replacements,
+    getLastError: () => lastError,
+    getFileSecurityW: (_path, _requested, output, _length, needed) => {
+      needed[0] = descriptor.length
+      if (output === null) {
+        lastError = 122
+        return 0
+      }
+      descriptor.copy(output)
+      lastError = 0
+      return 1
+    },
+    setFileSecurityW: (_path, information, value) => {
+      expect(information).toBe(0x80000004)
+      installed.push(Buffer.from(value))
+      lastError = 0
+      return 1
+    },
+    replaceFileW: (replaced, replacement, backup, flags, exclude, reserved) => {
+      expect([backup, flags, exclude, reserved]).toEqual([null, 0, null, null])
+      replacements.push([replaced, replacement])
+      lastError = 0
+      return 1
+    },
+  }
+}
+
+afterEach(() => {
+  vi.doUnmock('koffi')
+  vi.resetModules()
+})
+
+describe('Windows file-security helpers', () => {
+  it('reads and installs a protected DACL before replacing the destination', async () => {
+    const descriptor = Buffer.from([1, 2, 3, 4])
+    const native = successfulNative(descriptor)
+    const { copyFileDaclWin32, readFileDaclWin32, replaceFileWin32 } = await importWithNative(native)
+
+    expect(await readFileDaclWin32('source')).toEqual(descriptor)
+    await copyFileDaclWin32('source', 'temp')
+    expect(native.installed).toEqual([descriptor])
+    await replaceFileWin32('target', 'temp')
+    expect(native.replacements).toEqual([['target', 'temp']])
+  })
+
+  it('maps descriptor-size probe failures to Node-style codes', async () => {
+    const cases = [[2, 'ENOENT'], [3, 'ENOENT'], [5, 'EACCES'], [9999, 'EIO']] as const
+    for (const [win32Code, code] of cases) {
+      const native = successfulNative(Buffer.from([1]))
+      native.getFileSecurityW = (_path, _requested, _output, _length, needed) => {
+        needed[0] = 0
+        return 0
+      }
+      native.getLastError = () => win32Code
+      const { readFileDaclWin32 } = await importWithNative(native)
+      await expect(readFileDaclWin32('source')).rejects.toMatchObject({ code, win32Code, path: 'source' })
+    }
+  })
+
+  it('surfaces a descriptor read failure after the size probe', async () => {
+    const native = successfulNative(Buffer.from([1, 2]))
+    native.getFileSecurityW = (_path, _requested, _output, _length, needed) => {
+      needed[0] = 2
+      return 0
+    }
+    native.getLastError = () => 5
+    const { readFileDaclWin32 } = await importWithNative(native)
+
+    await expect(readFileDaclWin32('source')).rejects.toMatchObject({ code: 'EACCES', syscall: 'GetFileSecurityW' })
+  })
+
+  it('surfaces DACL installation and replacement failures', async () => {
+    const setFailure = successfulNative(Buffer.from([1]))
+    setFailure.setFileSecurityW = () => 0
+    setFailure.getLastError = () => 5
+    const setModule = await importWithNative(setFailure)
+    await expect(setModule.copyFileDaclWin32('source', 'temp')).rejects.toMatchObject({
+      code: 'EACCES',
+      syscall: 'SetFileSecurityW',
+      path: 'temp',
+    })
+
+    const replaceFailure = successfulNative(Buffer.from([1]))
+    replaceFailure.replaceFileW = () => 0
+    replaceFailure.getLastError = () => 2
+    const replaceModule = await importWithNative(replaceFailure)
+    await expect(replaceModule.replaceFileWin32('target', 'temp')).rejects.toMatchObject({
+      code: 'ENOENT',
+      syscall: 'ReplaceFileW',
+      path: 'target',
+    })
+  })
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 5c591034cc..0ed8c8449c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -819,6 +819,9 @@ importers:
 
   packages/fs/fs-local:
     dependencies:
+      koffi:
+        specifier: ^3.1.0
+        version: 3.1.1
       schemastery:
         specifier: ^3.18.0
         version: 3.18.0

From f110c5e08377f4074a0ec5927226f72c821a742b Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 12:41:46 +0800
Subject: [PATCH 28/74] fix(acp-snapshot): accept Windows termination exit
 races

Treat a fallback kill refusal as successful termination when the child already carries an OS exit marker. Windows maps Node's supported signal names to forced termination, so the requested signal can end the process between the launcher error race and its fallback SIGKILL.

Drain inherited stdio, the ACP parser, and in-flight callbacks before propagating the original child error in either exit-race path. Preserve AggregateError reporting only for a refused fallback while the process is still live, and add a deterministic cross-platform regression for that ordering.
---
 packages/support/acp-snapshot/src/launcher.ts | 17 ++++++++++---
 .../acp-snapshot/tests/harness.spec.ts        | 24 +++++++++++++++++++
 2 files changed, 38 insertions(+), 3 deletions(-)

diff --git a/packages/support/acp-snapshot/src/launcher.ts b/packages/support/acp-snapshot/src/launcher.ts
index de5082eca4..e39c6552f0 100644
--- a/packages/support/acp-snapshot/src/launcher.ts
+++ b/packages/support/acp-snapshot/src/launcher.ts
@@ -231,6 +231,15 @@ export function launchAcpTestAgent(options: AcpTestLaunchOptions): LaunchedAcpTe
         return
       }
 
+      const propagateFailureAfterDrain = async (): Promise<never> => {
+        await drained
+        closeUpdateStream()
+        throw failure
+      }
+      // Windows implements the supported signal names as forced termination. The exit markers
+      // may therefore arrive after the error wins the race above but before fallback begins.
+      if (!isRunning(child)) return propagateFailureAfterDrain()
+
       // An `error` after spawn is not an exit edge: in particular, a failed
       // signal can leave the subprocess live. Force termination, await the
       // already-observed exit edge, and only then propagate the child error so
@@ -240,6 +249,10 @@ export function launchAcpTestAgent(options: AcpTestLaunchOptions): LaunchedAcpTe
       child.once('error', observeFallbackError)
       if (!child.kill('SIGKILL')) {
         child.off('error', observeFallbackError)
+        // A successful earlier signal may win between the live check and this fallback call.
+        // In that case `kill()` correctly reports no process to signal; the original child error
+        // remains the shutdown result once inherited stdio and callbacks have drained.
+        if (!isRunning(child)) return propagateFailureAfterDrain()
         closeUpdateStream()
         throw new AggregateError(
           [failure, new Error('Fallback SIGKILL was not accepted by the child process')],
@@ -258,9 +271,7 @@ export function launchAcpTestAgent(options: AcpTestLaunchOptions): LaunchedAcpTe
           'ACP test agent failed and fallback termination was refused',
         )
       }
-      await drained
-      closeUpdateStream()
-      throw failure
+      return propagateFailureAfterDrain()
     },
   }
 }
diff --git a/packages/support/acp-snapshot/tests/harness.spec.ts b/packages/support/acp-snapshot/tests/harness.spec.ts
index 5589858fe9..2c4478e158 100644
--- a/packages/support/acp-snapshot/tests/harness.spec.ts
+++ b/packages/support/acp-snapshot/tests/harness.spec.ts
@@ -176,6 +176,30 @@ describe('runScenario', () => {
     }
   })
 
+  it('preserves the child error when fallback refusal races with an exit marker', async () => {
+    const { dir } = await scenario({})
+    const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir })
+    await launched.spawned
+
+    const childFailure = Object.assign(new Error('signal failed while the child exited'), { code: 'EPERM' })
+    const originalKill = launched.child.kill.bind(launched.child)
+    const kill = vi.spyOn(launched.child, 'kill').mockImplementation((signal) => {
+      if (signal === 'SIGTERM') return true
+      originalKill('SIGKILL')
+      Object.defineProperty(launched.child, 'signalCode', { configurable: true, enumerable: true, writable: true, value: 'SIGKILL' })
+      return false
+    })
+    try {
+      launched.child.emit('error', childFailure)
+      await expect(launched.close('SIGTERM')).rejects.toBe(childFailure)
+      expect(kill).toHaveBeenNthCalledWith(1, 'SIGTERM')
+      expect(kill).toHaveBeenNthCalledWith(2, 'SIGKILL')
+    } finally {
+      kill.mockRestore()
+      if (launched.child.exitCode === null && launched.child.signalCode === null) originalKill('SIGKILL')
+    }
+  })
+
   it('rejects promptly when fallback termination emits an error', async () => {
     const { dir } = await scenario({})
     const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir })

From 0f4bc645dab2f4f03c45e59e0feaf36f64767a7c Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 12:42:59 +0800
Subject: [PATCH 29/74] test(acp-snapshot): inherit descendant stdio portably

Pass the fake descendant the parent process's stdout and stderr stream handles instead of Unix-style numeric file descriptors. This lets Windows duplicate the live ACP and diagnostic pipes so launcher shutdown can prove that inherited handles, buffered frames, and stderr all drain after the parent exits.

Observe the pending update promise before initiating shutdown as well, preventing a missing late frame from becoming a transient unhandled rejection before the assertion reports the fixture failure.
---
 .../support/acp-snapshot/tests/fixtures/fake-acp-agent.ts     | 4 +++-
 packages/support/acp-snapshot/tests/harness.spec.ts           | 3 +++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts b/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts
index 5dd5524ed0..647ffbb5d9 100644
--- a/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts
+++ b/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts
@@ -266,7 +266,9 @@ function flushLogsAndExit(): void {
       `setTimeout(() => process.stdout.write(${JSON.stringify(`${frame}\n`)}), 50)`,
       `setTimeout(() => process.stderr.write(${JSON.stringify('late inherited stderr\n')}), 75)`,
     ].join(';')
-    spawn(process.execPath, ['-e', code], { stdio: ['ignore', 1, 2] }).unref()
+    spawn(process.execPath, ['-e', code], {
+      stdio: ['ignore', process.stdout, process.stderr],
+    }).unref()
   }
   process.exit(0)
 }
diff --git a/packages/support/acp-snapshot/tests/harness.spec.ts b/packages/support/acp-snapshot/tests/harness.spec.ts
index 2c4478e158..08b069338c 100644
--- a/packages/support/acp-snapshot/tests/harness.spec.ts
+++ b/packages/support/acp-snapshot/tests/harness.spec.ts
@@ -139,6 +139,9 @@ describe('runScenario', () => {
       update.sessionUpdate === 'agent_message_chunk'
       && update.content.type === 'text'
       && update.content.text === 'late inherited stdout')
+    // Arm rejection handling before close may exhaust the stream; the later assertion still
+    // observes the original promise and turns a missing inherited frame into the test failure.
+    void lateUpdate.catch(() => undefined)
 
     await launched.close()
 

From 3dc82b1e870e2f1bd732093909d23ead9e605d14 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 12:43:58 +0800
Subject: [PATCH 30/74] test(snapshot): refresh Windows workspace permission
 prose

Update the workspace-edit Windows sidecar to the current permission preset description emitted by the ACP session configuration. The shared golden already carried this contract; only the native-Windows transcript retained the superseded wording.

Leave the platform-specific backslash path rendering unchanged so the sidecar continues to pin the one intentional Windows transcript difference.
---
 .../tests/snapshots/workspace-edit/stdout.golden.windows.jsonl  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/acp-agent/tests/snapshots/workspace-edit/stdout.golden.windows.jsonl b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.golden.windows.jsonl
index 5f8762adcd..7438c3f43f 100644
--- a/examples/acp-agent/tests/snapshots/workspace-edit/stdout.golden.windows.jsonl
+++ b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.golden.windows.jsonl
@@ -1,5 +1,5 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
-{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"Sets this session's sandbox and approval behavior.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
+{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}}

From 4bf2ef89c4d6c5164140e5e522612b19444a8008 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 12:44:47 +0800
Subject: [PATCH 31/74] fix(jsonl): bind MoveFileExW with the Win32 BOOL ABI

Declare MoveFileExW's return value as Koffi int and model it as a numeric 32-bit Win32 BOOL. The previous Koffi bool declaration represented a one-byte C boolean and could read the native return register with the wrong ABI.

Test zero and nonzero results explicitly and assert the binding result type while preserving the existing write-through flags, error translation, and durable directory race behavior.
---
 .../session-persistence-jsonl/src/win32.ts    |  6 ++---
 .../tests/win32.spec.ts                       | 23 ++++++++++---------
 2 files changed, 15 insertions(+), 14 deletions(-)

diff --git a/packages/session-persistence/session-persistence-jsonl/src/win32.ts b/packages/session-persistence/session-persistence-jsonl/src/win32.ts
index 143f230ea3..a8c1b6fb8d 100644
--- a/packages/session-persistence/session-persistence-jsonl/src/win32.ts
+++ b/packages/session-persistence/session-persistence-jsonl/src/win32.ts
@@ -14,7 +14,7 @@
 import { mkdtemp, rm, stat } from 'node:fs/promises'
 import { basename, join, parse, resolve, toNamespacedPath } from 'node:path'
 
-type MoveFileExW = (existing: string, replacement: string, flags: number) => boolean
+type MoveFileExW = (existing: string, replacement: string, flags: number) => number
 type GetLastError = () => number
 
 interface Win32Bindings {
@@ -44,7 +44,7 @@ async function win32(): Promise<Win32Bindings> {
   const koffi = (await import('koffi')).default
   const kernel32 = koffi.load('kernel32.dll')
   bindings = {
-    moveFileExW: kernel32.func('__stdcall', 'MoveFileExW', 'bool', ['str16', 'str16', 'uint']) as MoveFileExW,
+    moveFileExW: kernel32.func('__stdcall', 'MoveFileExW', 'int', ['str16', 'str16', 'uint']) as MoveFileExW,
     getLastError: kernel32.func('__stdcall', 'GetLastError', 'uint', []) as GetLastError,
   }
   return bindings
@@ -113,7 +113,7 @@ async function assertDirectory(path: string): Promise<boolean> {
 export async function publishNewFileWin32(existing: string, replacement: string): Promise<void> {
   const api = await win32()
   const ok = api.moveFileExW(toNamespacedPath(existing), toNamespacedPath(replacement), MOVEFILE_WRITE_THROUGH)
-  if (!ok) throw win32Error('MoveFileExW', api.getLastError(), existing, replacement)
+  if (ok === 0) throw win32Error('MoveFileExW', api.getLastError(), existing, replacement)
 }
 
 /**
diff --git a/packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts b/packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts
index 760eb3d455..b4a2d11f28 100644
--- a/packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts
+++ b/packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts
@@ -19,7 +19,7 @@ const ERROR_FILE_EXISTS = 80
 const ERROR_INVALID_NAME = 123
 const ERROR_ALREADY_EXISTS = 183
 
-type MoveFileExW = (existing: string, replacement: string, flags: number, setLastError: (code: number) => void) => boolean
+type MoveFileExW = (existing: string, replacement: string, flags: number, setLastError: (code: number) => void) => number
 
 const roots: string[] = []
 
@@ -42,14 +42,15 @@ async function importWithMove(moveFileExW: MoveFileExW): Promise<typeof import('
     const setLastError = (code: number): void => { lastError = code }
     const move: MoveFileExW = (existing, replacement, flags, setError) => {
       const ok = moveFileExW(existing, replacement, flags, setError)
-      lastError = ok ? 0 : lastError
+      lastError = ok === 0 ? lastError : 0
       return ok
     }
     return {
       default: {
         load: () => ({
-          func: (_convention: string, name: string) => {
+          func: (_convention: string, name: string, result: string) => {
             if (name === 'MoveFileExW') return (existing: string, replacement: string, flags: number) => {
+              expect(result).toBe('int')
               const ok = move(existing, replacement, flags, setLastError)
               return ok
             }
@@ -68,7 +69,7 @@ async function importWithError(code: number): Promise<typeof import('../src/win3
     default: {
       load: () => ({
         func: (_convention: string, name: string) => {
-          if (name === 'MoveFileExW') return () => false
+          if (name === 'MoveFileExW') return () => 0
           return () => code
         },
       }),
@@ -82,10 +83,10 @@ async function importWithFilesystemMove(): Promise<typeof import('../src/win32.t
     expect(flags).toBe(MOVEFILE_WRITE_THROUGH)
     const from = stripNamespace(existing)
     const to = stripNamespace(replacement)
-    if (!existsSync(from)) { setLastError(ERROR_FILE_NOT_FOUND); return false }
-    if (existsSync(to)) { setLastError(ERROR_ALREADY_EXISTS); return false }
+    if (!existsSync(from)) { setLastError(ERROR_FILE_NOT_FOUND); return 0 }
+    if (existsSync(to)) { setLastError(ERROR_ALREADY_EXISTS); return 0 }
     renameSync(from, to)
-    return true
+    return 1
   })
 }
 
@@ -135,12 +136,12 @@ describe('Windows durable namespace helpers', () => {
       if (to === raced) {
         mkdirSync(to)
         setLastError(ERROR_ALREADY_EXISTS)
-        return false
+        return 0
       }
-      if (!existsSync(from)) { setLastError(ERROR_FILE_NOT_FOUND); return false }
-      if (existsSync(to)) { setLastError(ERROR_ALREADY_EXISTS); return false }
+      if (!existsSync(from)) { setLastError(ERROR_FILE_NOT_FOUND); return 0 }
+      if (existsSync(to)) { setLastError(ERROR_ALREADY_EXISTS); return 0 }
       renameSync(from, to)
-      return true
+      return 1
     })
 
     await ensureDurableDirectoryWin32(join(root, 'a', 'b'))

From c660048759fa0e20bc4f7cd953652176cd8f5950 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 12:52:42 +0800
Subject: [PATCH 32/74] test(subagent): cover late forced-wait exit markers

Exercise both exitCode and signalCode arriving after the SIGTERM grace begins but before the bounded SIGKILL confirmation helper starts. This pins the fast path that avoids signaling an already-terminated child and restores the package's per-file 100% branch and statement coverage.

Keep the marker transition deterministic by withholding the synthetic exit event, matching the OS state race the defensive pre-check exists to absorb.
---
 .../tests/subagent-subprocess.spec.ts             | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts
index e81957baa0..d674937e92 100644
--- a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts
+++ b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts
@@ -222,6 +222,21 @@ describe('disposeChildProcess', () => {
     expect(fake.signalCode).toBe('SIGKILL')
   })
 
+  it.each(['exitCode', 'signalCode'] as const)('accepts a late OS %s marker before the final forced wait', async (marker) => {
+    const fake = new FakeChild()
+    vi.spyOn(fake, 'kill').mockImplementation((signal) => {
+      fake.kills.push(signal)
+      queueMicrotask(() => {
+        if (marker === 'exitCode') fake.exitCode = 0
+        else fake.signalCode = 'SIGTERM'
+      })
+      return true
+    })
+
+    await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 1, disposeGraceMs: 10 }, 'linux')
+    expect(fake.kills).toEqual(['SIGTERM'])
+  })
+
   it('walks the ladder for a child spawned without a stdin pipe', async () => {
     const fake = new FakeChild({ stdin: false, diesOn: 'SIGTERM', delayMs: 5 })
     await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }, 'linux')

From e9aac53fdec49c951db97f8a1c2e677c35818d98 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 12:53:41 +0800
Subject: [PATCH 33/74] test(acp-snapshot): cover pre-fallback Windows exit
 state

Model the requested signal setting a child termination marker before the launcher begins fallback handling. The regression proves close drains inherited stdio and propagates the original process error without sending a redundant SIGKILL.

This complements the post-check fallback-refusal race and restores the launcher's required 100% per-file statement and branch coverage.
---
 .../acp-snapshot/tests/harness.spec.ts        | 23 +++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/packages/support/acp-snapshot/tests/harness.spec.ts b/packages/support/acp-snapshot/tests/harness.spec.ts
index 08b069338c..61b40010df 100644
--- a/packages/support/acp-snapshot/tests/harness.spec.ts
+++ b/packages/support/acp-snapshot/tests/harness.spec.ts
@@ -179,6 +179,29 @@ describe('runScenario', () => {
     }
   })
 
+  it('preserves the child error when the requested signal sets an exit marker', async () => {
+    const { dir } = await scenario({})
+    const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir })
+    await launched.spawned
+
+    const childFailure = Object.assign(new Error('signal failed as the child exited'), { code: 'EPERM' })
+    const originalKill = launched.child.kill.bind(launched.child)
+    const kill = vi.spyOn(launched.child, 'kill').mockImplementation((signal) => {
+      expect(signal).toBe('SIGTERM')
+      originalKill('SIGKILL')
+      Object.defineProperty(launched.child, 'signalCode', { configurable: true, enumerable: true, writable: true, value: 'SIGTERM' })
+      return true
+    })
+    try {
+      launched.child.emit('error', childFailure)
+      await expect(launched.close('SIGTERM')).rejects.toBe(childFailure)
+      expect(kill).toHaveBeenCalledOnce()
+    } finally {
+      kill.mockRestore()
+      if (launched.child.exitCode === null && launched.child.signalCode === null) originalKill('SIGKILL')
+    }
+  })
+
   it('preserves the child error when fallback refusal races with an exit marker', async () => {
     const { dir } = await scenario({})
     const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir })

From 0f8d0082e4b916f2afed3fec850853a9d26dfb77 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 13:20:59 +0800
Subject: [PATCH 34/74] fix(tui): stabilize Windows terminal snapshots

Treat an absolute path.relative() result as a cross-volume path instead of incorrectly abbreviating it beneath the user's home directory.

Allow embeddings to project a logical footer cwd without changing the operational session cwd. The recorded-session harness now uses a POSIX-shaped display alias for both the footer and filesystem result paths, preserving the existing pre-normalization layout width on every host.

Keep runtime-provided labels behind terminal-control escaping, cover that boundary, and document the embedding contract.
---
 examples/tui-agent/tests/tui.snapshot.ts | 35 ++++++++++++++++++++----
 packages/ui/tui/README.md                |  2 ++
 packages/ui/tui/src/index.ts             | 27 ++++++++++++++----
 packages/ui/tui/tests/harness.ts         |  9 ++++--
 packages/ui/tui/tests/tui.spec.ts        |  7 +++++
 5 files changed, 68 insertions(+), 12 deletions(-)

diff --git a/examples/tui-agent/tests/tui.snapshot.ts b/examples/tui-agent/tests/tui.snapshot.ts
index c0537021e8..5c443ee474 100644
--- a/examples/tui-agent/tests/tui.snapshot.ts
+++ b/examples/tui-agent/tests/tui.snapshot.ts
@@ -1,6 +1,6 @@
 import { cp, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { basename, dirname, join } from 'node:path'
+import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { afterAll, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
@@ -106,6 +106,13 @@ function snapshotModeFromEnv(value: string | undefined): SnapshotMode {
 const MODE = snapshotModeFromEnv(process.env.DSH_SNAPSHOT)
 const observedScenarios = new Set<string>()
 
+function snapshotDisplayPath(displayPath: string, cwd: string, displayCwd: string): string {
+  const rel = relative(cwd, displayPath)
+  if (rel === '') return displayCwd
+  if (isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`)) return displayPath
+  return `${displayCwd}/${rel.split(sep).join('/')}`
+}
+
 function scenarioDir(scenario: Scenario): string {
   return join(SNAPSHOTS_DIR, scenario.name)
 }
@@ -136,9 +143,10 @@ function rawSessionLog(session: Session): string {
   ].join('\n')
 }
 
-function normalizeTerminalSnapshot(snapshot: string, cwd: string): string {
+function normalizeTerminalSnapshot(snapshot: string, cwd: string, displayCwd: string): string {
   return snapshot
     .split(`/private${cwd}`).join('/workspace/project')
+    .split(displayCwd).join('/workspace/project')
     .split(cwd).join('/workspace/project')
     .replace(UUID_RE, '{{uuid}}')
 }
@@ -157,9 +165,20 @@ async function settleTerminal(terminal: HeadlessTerminal): Promise<void> {
 async function mountScenarioContext(
   scenario: Scenario,
   cwd: string,
+  displayCwd: string,
   fixtureFile: string,
   childFiles: string[],
 ): Promise<Context> {
+  class SnapshotLocalFileSystem extends LocalFileSystem {
+    override async resolve(
+      path: string,
+      opts?: { cwd?: string; signal?: AbortSignal },
+    ): Promise<Awaited<ReturnType<LocalFileSystem['resolve']>>> {
+      const target = await super.resolve(path, opts)
+      return { ...target, displayPath: snapshotDisplayPath(target.displayPath, cwd, displayCwd) }
+    }
+  }
+
   const ctx = new Context()
   await ctx.plugin(AgentCore, {
     agents: [],
@@ -169,7 +188,7 @@ async function mountScenarioContext(
     skills: { local: { agentsHome: join(cwd, '.agents') } },
   })
   await ctx.plugin(LocalBashExecutor, { cwd, timeoutMs: 30_000 })
-  await ctx.plugin(LocalFileSystem, { cwd: '/' })
+  await ctx.plugin(SnapshotLocalFileSystem, { cwd: '/' })
   await ctx.plugin(FsPolicy)
   await ctx.plugin(ToolFs)
   await ctx.plugin(UserInteractionService)
@@ -207,6 +226,7 @@ async function runScenario(scenario: Scenario): Promise<ScenarioResult> {
   expect(prompts.length, `${scenario.name} must carry at least one recorded user prompt`).toBeGreaterThan(0)
 
   const cwd = await mkdtemp(join(SNAPSHOT_TMP_ROOT, `dsh-tui-snapshot-${scenario.name}-`))
+  const displayCwd = `/tmp/${basename(cwd)}`
   let ctx: Context | undefined
   let controller: ReturnType<typeof createTuiChat> | undefined
   const terminal = new HeadlessTerminal(100, 36)
@@ -215,7 +235,7 @@ async function runScenario(scenario: Scenario): Promise<ScenarioResult> {
       const source = join(scenarioDir(scenario), 'workspace')
       await cp(source, cwd, { recursive: true })
     }
-    ctx = await mountScenarioContext(scenario, cwd, fixtureFile, childFiles)
+    ctx = await mountScenarioContext(scenario, cwd, displayCwd, fixtureFile, childFiles)
     const disposedSessions: Session[] = []
     ctx.on('session/disposed', (session) => { disposedSessions.push(session) })
     const workflowEvents: string[] = []
@@ -235,7 +255,11 @@ async function runScenario(scenario: Scenario): Promise<ScenarioResult> {
       title: 'DSH TUI snapshot',
       welcome: `Recorded replay: ${scenario.name}`,
       maxToolOutputLines: 8,
-    }, { terminal, exit: () => {} })
+    }, {
+      terminal,
+      exit: () => {},
+      formatCwd: () => displayCwd,
+    })
     await settleTerminal(terminal)
 
     for (const prompt of prompts) {
@@ -266,6 +290,7 @@ async function runScenario(scenario: Scenario): Promise<ScenarioResult> {
     const snapshot = normalizeTerminalSnapshot(
       await terminal.snapshot({ includeScrollback: true }),
       cwd,
+      displayCwd,
     )
     await handle.dispose()
     const children = disposedSessions
diff --git a/packages/ui/tui/README.md b/packages/ui/tui/README.md
index e426640ae5..34987c5d55 100644
--- a/packages/ui/tui/README.md
+++ b/packages/ui/tui/README.md
@@ -8,6 +8,8 @@ This package owns interactive terminal presentation and input only. It injects `
 
 The TUI rebuilds resumed history from the active session surface, renders Markdown responses and reasoning, applies each tool's `presentCall` / `presentResult` intent to terminal, diff, or generic cards, keeps the latest `todo/write` plan above the editor, and presents `ctx.userInteraction` questions as keyboard-driven overlays. Surface replacement events rebuild the transcript so compacted history does not reappear.
 
+An embedding may provide `TuiRuntime.formatCwd` when its logical workspace label differs from the session's host directory. The override changes only the footer label; tools continue to use the session `cwd`.
+
 Before model output, session events, tool presenters, questions, configuration, or diagnostics reach pi-tui's ANSI-aware renderers or the terminal title, the TUI renders C0 and C1 controls other than line feeds as visible `\xNN` text. Those sources cannot add terminal control sequences; the TUI and pi-tui retain ownership of terminal rendering and styling.
 
 While the agent is running, editor submissions call `agent.steer()`; otherwise they call `agent.send()`. Ctrl+C or Escape cancels a running turn. Ctrl+O expands tool cards, Ctrl+R toggles reasoning, Ctrl+L redraws, and Ctrl+D exits while idle. `/help`, `/clear`, `/cancel`, `/reasoning`, `/tools`, `/redraw`, and `/exit` provide the same actions without key chords.
diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts
index 0906b7bc9f..210ff10071 100644
--- a/packages/ui/tui/src/index.ts
+++ b/packages/ui/tui/src/index.ts
@@ -6,7 +6,7 @@
  */
 
 import { homedir } from 'node:os'
-import { relative, resolve, sep } from 'node:path'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
 import {
   CombinedAutocompleteProvider,
   Container,
@@ -135,6 +135,12 @@ export interface TuiRuntime {
   terminal: Terminal
   /** Exit hook used by terminal shutdown or a target-agent startup failure. */
   exit(code: number): void
+  /**
+   * Override the footer's logical working-directory label without changing the session directory used by tools.
+   * @param cwd - Operational working directory from the session header.
+   * @returns Unescaped label; the TUI makes terminal controls visible.
+   */
+  formatCwd?: (cwd: string | undefined) => string
 }
 
 /**
@@ -608,8 +614,10 @@ function formatCwd(cwd: string | undefined): string {
   const home = homedir()
   const rel = relative(resolve(home), resolve(cwd))
   if (rel === '') return '~'
-  if (rel !== '..' && !rel.startsWith(`..${sep}`)) return displayText(`~${sep}${rel}`)
-  return displayText(cwd)
+  /* v8 ignore next -- Windows cross-drive coverage; POSIX relative() cannot return an absolute path. */
+  if (isAbsolute(rel)) return cwd
+  if (rel !== '..' && !rel.startsWith(`..${sep}`)) return `~${sep}${rel}`
+  return cwd
 }
 
 function sessionTokens(session: Session): { input: number; output: number } {
@@ -630,13 +638,15 @@ class FooterComponent implements Component {
     private readonly toolsExpanded: () => boolean,
     private readonly showReasoning: () => boolean,
     private readonly tokens: () => { input: number; output: number },
+    private readonly cwdFormatter: TuiRuntime['formatCwd'],
   ) {}
 
   invalidate(): void {}
 
   render(width: number): string[] {
     const { input, output } = this.tokens()
-    const left = `${formatCwd(this.agent.session.header.cwd)}  ↑${formatTokens(input)} ↓${formatTokens(output)}`
+    const cwd = this.cwdFormatter?.(this.agent.session.header.cwd) ?? formatCwd(this.agent.session.header.cwd)
+    const left = `${displayText(cwd)}  ↑${formatTokens(input)} ↓${formatTokens(output)}`
     const right = `${this.agent.status}  reasoning:${this.showReasoning() ? 'on' : 'off'}  tools:${this.toolsExpanded() ? 'expanded' : 'compact'}`
     const leftStyled = this.palette.dim(left)
     const available = Math.max(0, width - visibleWidth(left) - 2)
@@ -843,7 +853,14 @@ export function createTuiChat(
 
   const welcome = config.welcome ?? 'ready.'
   const header = new HeaderComponent(agent, welcome, palette)
-  const footer = new FooterComponent(agent, palette, () => toolsExpanded, () => showReasoning, () => tokens)
+  const footer = new FooterComponent(
+    agent,
+    palette,
+    () => toolsExpanded,
+    () => showReasoning,
+    () => tokens,
+    runtime.formatCwd,
+  )
   ui.addChild(header)
   ui.addChild(chat)
   ui.addChild(statusContainer)
diff --git a/packages/ui/tui/tests/harness.ts b/packages/ui/tui/tests/harness.ts
index 9994833308..7cef8ed185 100644
--- a/packages/ui/tui/tests/harness.ts
+++ b/packages/ui/tui/tests/harness.ts
@@ -5,7 +5,7 @@ import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId, type Session } from '@deepseek-ai/dsh-session'
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
-import { createTuiChat, type Config } from '../src/index.ts'
+import { createTuiChat, type Config, type TuiRuntime } from '../src/index.ts'
 
 interface FakeAgent extends Agent {
   status: AgentStatus
@@ -21,6 +21,7 @@ export interface TuiHarnessOptions {
   configureContext?: (ctx: Context) => Promise<void>
   beforeMount?: (session: Session) => void
   cwd?: string | null
+  formatCwd?: TuiRuntime['formatCwd']
 }
 
 export interface TuiHarness<TerminalType extends Terminal, Exit extends (code: number) => void> {
@@ -95,7 +96,11 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
     welcome: 'Coding agent ready.',
     sessionId,
     color: false,
-  }, options.config), { terminal, exit })
+  }, options.config), {
+    terminal,
+    exit,
+    ...(options.formatCwd === undefined ? {} : { formatCwd: options.formatCwd }),
+  })
   return { ctx, session, agent, terminal, exit, controller }
 }
 
diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts
index 27200e0fa9..4437369728 100644
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -364,6 +364,13 @@ describe('pi-tui chat lifecycle and transcript', () => {
     const outsideResult = await setup({ cwd: '/opt' })
     expect(outsideResult.terminal.output).toContain('/opt')
     await dispose(outsideResult)
+
+    const logicalResult = await setup({
+      cwd: '/host/worktree',
+      formatCwd: cwd => `logical:${cwd}\x1b`,
+    })
+    expect(logicalResult.terminal.output).toContain('logical:/host/worktree\\x1b')
+    await dispose(logicalResult)
   })
 
   it('sends, steers, handles commands, global keys, and disposed-agent input', async () => {

From a6b8ce456a94de5d19d29228fe4ed19903481280 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 13:25:15 +0800
Subject: [PATCH 35/74] test(fs): compare Windows DACL access policy

ReplaceFileW preserves ACLs by merging security information, which may reserialize auto-inheritance state and duplicate equivalent ACEs. Compare the final ordered, de-duplicated ACE policy instead of requiring byte-identical self-relative descriptor buffers.

Update the host-independent binding assertion to expect the namespaced absolute paths that the Win32 boundary actually receives, and align the package and bilingual RFC contracts with the semantic DACL guarantee.
---
 ...-windows-atomic-write-dacl-preservation.md |  4 ++--
 ...ndows-atomic-write-dacl-preservation.zh.md |  4 ++--
 packages/fs/fs-local/README.md                |  2 +-
 packages/fs/fs-local/tests/fsio.spec.ts       | 24 ++++++++++++++++++-
 packages/fs/fs-local/tests/win32.spec.ts      |  3 ++-
 5 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md
index 393ce8a992..13ec1546ce 100644
--- a/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md
+++ b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md
@@ -10,9 +10,9 @@ On Windows, creating the staging directory and temp file under the target's pare
 
 ## Decision
 
-`dsh-fs-local` reads an existing target's DACL with `GetFileSecurityW`, applies it to the empty temp file with inheritance protected before writing content, and publishes the closed temp with `ReplaceFileW`. The protected staging descriptor prevents the temp directory's inherited entries from broadening access; `ReplaceFileW` preserves the original target security descriptor and other replacement metadata. New files have no prior descriptor to preserve and continue to inherit the destination directory's DACL.
+`dsh-fs-local` reads an existing target's DACL with `GetFileSecurityW`, applies it to the empty temp file with inheritance protected before writing content, and publishes the closed temp with `ReplaceFileW`. The protected staging descriptor prevents the temp directory's inherited entries from broadening access; `ReplaceFileW` preserves the original target access policy and other replacement metadata. Its ACL merge may reserialize auto-inheritance state or duplicate equivalent ACEs, so self-relative descriptor buffers are not a stable equality contract. New files have no prior descriptor to preserve and continue to inherit the destination directory's DACL.
 
-Native Windows coverage protects a target DACL, inspects the written staging file, and compares the final replacement descriptor. Host-independent binding tests cover Win32 error translation and every native call boundary.
+Native Windows coverage protects a target DACL, inspects the written staging file, and compares the final replacement's ordered, de-duplicated ACE policy. Host-independent binding tests cover Win32 error translation and every native call boundary.
 
 ## Alternatives considered
 
diff --git a/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md
index c7a0b6278c..ca72ec2213 100644
--- a/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md
+++ b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md
@@ -10,9 +10,9 @@ Status: implemented
 
 ## 决策
 
-`dsh-fs-local` 通过 `GetFileSecurityW` 读取现有目标文件的 DACL，在写入内容前将其以禁止继承的形式应用到空临时文件，并通过 `ReplaceFileW` 发布已关闭的临时文件。受保护的暂存安全描述符可防止暂存目录中的继承条目扩大访问权限；`ReplaceFileW` 会保留原目标文件的安全描述符及其他替换元数据。新建文件没有既有描述符需要保留，因此仍继承目标目录的 DACL。
+`dsh-fs-local` 通过 `GetFileSecurityW` 读取现有目标文件的 DACL，在写入内容前将其以禁止继承的形式应用到空临时文件，并通过 `ReplaceFileW` 发布已关闭的临时文件。受保护的暂存安全描述符可防止暂存目录中的继承条目扩大访问权限；`ReplaceFileW` 会保留原目标文件的访问策略及其他替换元数据。其 ACL 合并过程可能重新序列化自动继承状态或复制等价 ACE，因此不能把自相对安全描述符缓冲区的逐字节相等作为稳定契约。新建文件没有既有描述符需要保留，因此仍继承目标目录的 DACL。
 
-Windows 原生覆盖率测试会保护目标文件的 DACL、检查写入完成的暂存文件，并对比最终替换文件的描述符。与宿主平台无关的绑定测试覆盖 Win32 错误转换以及每个原生调用边界。
+Windows 原生覆盖率测试会保护目标文件的 DACL、检查写入完成的暂存文件，并对比最终替换文件中保持顺序且去重后的 ACE 策略。与宿主平台无关的绑定测试覆盖 Win32 错误转换以及每个原生调用边界。
 
 ## 备选方案
 
diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md
index 551492db67..e8f57e5084 100644
--- a/packages/fs/fs-local/README.md
+++ b/packages/fs/fs-local/README.md
@@ -16,7 +16,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **`stat` / `lstat`** — return target metadata or `undefined` when absent. `stat` reports `FsInfo` for an already resolved target (`version` = an opaque token derived from bigint `dev:ino:size:mtimeNs:ctimeNs`, `type` of `file`/`directory`/`other`, byte `size`); path-shaped `lstat` reports `FsPathInfo` without following the final symlink and can therefore return `symlink`. Both check cancellation before and after their asynchronous metadata probe, so an abort that lands in flight reports `FS_ABORTED` rather than stale absence.
 - **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` streams it in chunks (cross-chunk decoding) so a huge file never has to be held whole in memory. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) decides which to call by size and owns the line windowing.
 - **`listDir`** — lists one directory level in stable `name.localeCompare()` order. Each entry carries the child basename, type, resolved child target (`displayPath` under the listed directory, `targetKey` as the realpath identity), and cheap stat metadata (`version`, plus `size` for regular files). It never opens or decodes file contents. Missing targets report `FS_NOT_FOUND`, file/special-file targets report `FS_NOT_DIRECTORY`, aborted calls report `FS_ABORTED`, permission failures report `FS_PERMISSION_DENIED`, and other listing or child metadata I/O failures report `FS_IO_ERROR`. Broken/disappeared children are returned as `other` without metadata, but permission/IO failures while resolving a child fail the whole listing with a structured `FsError`.
-- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original descriptor survives ([Windows DACL preservation RFC](../../../docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
+- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original access policy survives ([Windows DACL preservation RFC](../../../docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
 - **`editText`** — atomic literal read-modify-write over the same primitive, serialized per target by a mutation lock. The `expected` guard is OPTIONAL: when supplied it verifies the version BEFORE literal matching (a stale edit reports `FS_STALE_VERSION`, never `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` against newer content); omitting it edits the current content unconditionally. A missing target reports `FS_STALE_VERSION` either way. LF-normalizes for matching, restores the file's dominant CRLF/LF style, and rejects empty `oldString` / zero matches (`FS_EDIT_NOT_FOUND`) or ambiguous multi-matches without `replace_all` (`FS_AMBIGUOUS_EDIT`).
 
 The package-root SDK surface is the default/named `LocalFileSystem` class plus `Config`. Raw I/O lives in `src/fsio.ts` (Cordis-free, independently unit-tested); `src/index.ts` is the thin service wiring.
diff --git a/packages/fs/fs-local/tests/fsio.spec.ts b/packages/fs/fs-local/tests/fsio.spec.ts
index d292f0bfb7..15588e40b9 100644
--- a/packages/fs/fs-local/tests/fsio.spec.ts
+++ b/packages/fs/fs-local/tests/fsio.spec.ts
@@ -372,6 +372,28 @@ describe('streamWholeText', () => {
 // bits, so mode assertions are POSIX-only; native DACL preservation is asserted separately.
 const posixModes = process.platform !== 'win32'
 
+function daclAcePolicy(descriptor: Buffer): string[] {
+  const daclOffset = descriptor.readUInt32LE(16)
+  if (daclOffset === 0) return []
+  const aceCount = descriptor.readUInt16LE(daclOffset + 4)
+  const policy: string[] = []
+  const seen = new Set<string>()
+  let offset = daclOffset + 8
+  for (let index = 0; index < aceCount; index++) {
+    const size = descriptor.readUInt16LE(offset + 2)
+    const ace = Buffer.from(descriptor.subarray(offset, offset + size))
+    // INHERITED_ACE records provenance, not the entry's access policy.
+    ace.writeUInt8(ace.readUInt8(1) & ~0x10, 1)
+    const key = ace.toString('hex')
+    if (!seen.has(key)) {
+      seen.add(key)
+      policy.push(key)
+    }
+    offset += size
+  }
+  return policy
+}
+
 describe('writeFileAtomic — temp-file safety', () => {
   it('writes through a private staging dir and owner-only temp file', async () => {
     const file = join(dir, 'a.txt')
@@ -409,7 +431,7 @@ describe('writeFileAtomic — temp-file safety', () => {
     })
 
     expect(await readFile(file, 'utf8')).toBe('new')
-    expect(await readFileDaclWin32(file)).toEqual(expectedDacl)
+    expect(daclAcePolicy(await readFileDaclWin32(file))).toEqual(daclAcePolicy(expectedDacl))
   })
 
   it('copies a Windows target DACL before content and publishes through secure replacement', async () => {
diff --git a/packages/fs/fs-local/tests/win32.spec.ts b/packages/fs/fs-local/tests/win32.spec.ts
index dc2b69ea82..4a8687d9e8 100644
--- a/packages/fs/fs-local/tests/win32.spec.ts
+++ b/packages/fs/fs-local/tests/win32.spec.ts
@@ -1,5 +1,6 @@
 /** Host-independent binding tests for the Win32 DACL and replacement helpers. */
 
+import { toNamespacedPath } from 'node:path'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 
 type GetFileSecurityW = (
@@ -92,7 +93,7 @@ describe('Windows file-security helpers', () => {
     await copyFileDaclWin32('source', 'temp')
     expect(native.installed).toEqual([descriptor])
     await replaceFileWin32('target', 'temp')
-    expect(native.replacements).toEqual([['target', 'temp']])
+    expect(native.replacements).toEqual([[toNamespacedPath('target'), toNamespacedPath('temp')]])
   })
 
   it('maps descriptor-size probe failures to Node-style codes', async () => {

From 5d6b589922b0fde638d8ae855f2db4356f601d3a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 13:28:19 +0800
Subject: [PATCH 36/74] fix(acp-snapshot): await delayed Windows exit markers

A successful Windows termination request can end the process before Node publishes exitCode or signalCode. If a child error wins the shutdown race, give that accepted exit a bounded observation window before escalating or reporting fallback refusal.

Cover a delayed real exit edge, preserve prompt refusal behavior for a genuinely live child, and document the launcher grace without weakening the complete stdio and parser drain boundary.
---
 packages/support/acp-snapshot/README.md       |  2 +-
 packages/support/acp-snapshot/src/launcher.ts | 17 ++++++++++++--
 .../acp-snapshot/tests/harness.spec.ts        | 22 +++++++++++++++++++
 3 files changed, 38 insertions(+), 3 deletions(-)

diff --git a/packages/support/acp-snapshot/README.md b/packages/support/acp-snapshot/README.md
index 43a315e230..53289fda35 100644
--- a/packages/support/acp-snapshot/README.md
+++ b/packages/support/acp-snapshot/README.md
@@ -4,7 +4,7 @@ The ACP snapshot suite kit: the shared machinery behind the keyless snapshot tie
 
 Four layers, importable separately:
 
-- **`launchAcpTestAgent` (launcher)** — boots a source agent under tsx or a built `lib` agent under plain Node from a temp cwd, connects the SDK client over a raw-byte stdout tee, collects session updates and stderr, surfaces asynchronous spawn failures through startup, fails closed on unhandled permission requests, and owns graceful or signalled shutdown. Shutdown waits for process exit, inherited stdio closure, and ACP parser exhaustion before resolving or propagating a child error, so captures are complete and callers can remove owned paths after either outcome. Snapshot and ordinary e2e suites share this process boundary; a test supplies only agent paths, cwd, environment overrides, and any permission policy.
+- **`launchAcpTestAgent` (launcher)** — boots a source agent under tsx or a built `lib` agent under plain Node from a temp cwd, connects the SDK client over a raw-byte stdout tee, collects session updates and stderr, surfaces asynchronous spawn failures through startup, fails closed on unhandled permission requests, and owns graceful or signalled shutdown. Shutdown waits for process exit, inherited stdio closure, and ACP parser exhaustion before resolving or propagating a child error, so captures are complete and callers can remove owned paths after either outcome. When Windows accepts forced termination but publishes its exit marker asynchronously, shutdown gives that marker a bounded grace before treating fallback refusal as a second failure. Snapshot and ordinary e2e suites share this process boundary; a test supplies only agent paths, cwd, environment overrides, and any permission policy.
 - **`runScenario` (harness)** — drives ACP JSON-RPC stdio from a deterministic `input.json` script through the launcher, tees raw stdout for the golden and purity check, and harvests every persisted session JSONL (parent and subagent children, primary-first) after graceful stdin EOF. `AgentUnderTest` supplies absolute `binScript`, optional `libBinScript`, `configPath`, and `tsconfigPath` paths because the subprocess cwd is outside the repo. Startup failures preserve captured agent stderr in the rejected diagnostic.
 - **Normalizers** — pure functions turning the two captured surfaces into stable text: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs/cwd → tokens; cwd-rooted separators selected as canonical `/` or host-native; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept, the same cwd-path policy), `scrubSystemPrompts` (prompt text → `{{system}}`), `scrubToolSchemas` (schema bulk → `{{tools}}`), and `scrubRequestHeaders` (all header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}` outside each pin, structure kept — [pinned-header RFC](../../../docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
 - **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario shared golden and re-persisted-log compares, optional Windows-native stdout sidecars, record/refresh fixture write-back, rejection of structured `UNKNOWN_TOOL` results, the per-header-class pin (`system-prompt.golden.md` plus `tool-schemas.golden.json`) with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin per class, every JSONL prompt/schema-scrubbed, non-pinning fixtures fully header-scrubbed). Each scenario directory's `session.jsonl` plus contiguous `session.<n>.jsonl` siblings are the ordered primary/child inventory; the scenario table does not duplicate their count. Must be called at vitest collection time.
diff --git a/packages/support/acp-snapshot/src/launcher.ts b/packages/support/acp-snapshot/src/launcher.ts
index e39c6552f0..441ab463d7 100644
--- a/packages/support/acp-snapshot/src/launcher.ts
+++ b/packages/support/acp-snapshot/src/launcher.ts
@@ -21,6 +21,8 @@ import {
 } from '@agentclientprotocol/sdk'
 import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke'
 
+const EXIT_MARKER_GRACE_MS = 250
+
 /** The source/built agent entry, leaf config, and workspace tsconfig an ACP test boots. */
 export interface AgentUnderTest {
   /** The agent source bin entry (for example `packages/examples/acp-demo/src/bin.ts`). */
@@ -238,7 +240,7 @@ export function launchAcpTestAgent(options: AcpTestLaunchOptions): LaunchedAcpTe
       }
       // Windows implements the supported signal names as forced termination. The exit markers
       // may therefore arrive after the error wins the race above but before fallback begins.
-      if (!isRunning(child)) return propagateFailureAfterDrain()
+      if (!isRunning(child) || await exitMarkerWithinGrace(exited)) return propagateFailureAfterDrain()
 
       // An `error` after spawn is not an exit edge: in particular, a failed
       // signal can leave the subprocess live. Force termination, await the
@@ -252,7 +254,7 @@ export function launchAcpTestAgent(options: AcpTestLaunchOptions): LaunchedAcpTe
         // A successful earlier signal may win between the live check and this fallback call.
         // In that case `kill()` correctly reports no process to signal; the original child error
         // remains the shutdown result once inherited stdio and callbacks have drained.
-        if (!isRunning(child)) return propagateFailureAfterDrain()
+        if (!isRunning(child) || await exitMarkerWithinGrace(exited)) return propagateFailureAfterDrain()
         closeUpdateStream()
         throw new AggregateError(
           [failure, new Error('Fallback SIGKILL was not accepted by the child process')],
@@ -281,6 +283,17 @@ function waitForExit(child: ChildProcessWithoutNullStreams): Promise<void> {
   return new Promise<void>(resolve => child.once('exit', () => { resolve() }))
 }
 
+/** Give an accepted Windows termination request a bounded window to publish its exit marker. */
+function exitMarkerWithinGrace(exited: Promise<void>): Promise<boolean> {
+  return Promise.race([
+    exited.then(() => true),
+    new Promise<false>((resolve) => {
+      const timer = setTimeout(() => { resolve(false) }, EXIT_MARKER_GRACE_MS)
+      timer.unref()
+    }),
+  ])
+}
+
 /** Whether the child still lacks either OS termination marker. */
 function isRunning(child: ChildProcessWithoutNullStreams): boolean {
   return child.exitCode === null && child.signalCode === null
diff --git a/packages/support/acp-snapshot/tests/harness.spec.ts b/packages/support/acp-snapshot/tests/harness.spec.ts
index 61b40010df..5d12b2da97 100644
--- a/packages/support/acp-snapshot/tests/harness.spec.ts
+++ b/packages/support/acp-snapshot/tests/harness.spec.ts
@@ -202,6 +202,28 @@ describe('runScenario', () => {
     }
   })
 
+  it('preserves the child error when the requested signal publishes its exit marker later', async () => {
+    const { dir } = await scenario({})
+    const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir })
+    await launched.spawned
+
+    const childFailure = Object.assign(new Error('signal failed before the delayed exit marker'), { code: 'EPERM' })
+    const originalKill = launched.child.kill.bind(launched.child)
+    const kill = vi.spyOn(launched.child, 'kill').mockImplementation((signal) => {
+      expect(signal).toBe('SIGTERM')
+      setTimeout(() => { originalKill('SIGKILL') }, 10)
+      return true
+    })
+    try {
+      launched.child.emit('error', childFailure)
+      await expect(launched.close('SIGTERM')).rejects.toBe(childFailure)
+      expect(kill).toHaveBeenCalledOnce()
+    } finally {
+      kill.mockRestore()
+      if (launched.child.exitCode === null && launched.child.signalCode === null) originalKill('SIGKILL')
+    }
+  })
+
   it('preserves the child error when fallback refusal races with an exit marker', async () => {
     const { dir } = await scenario({})
     const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir })

From 97f9ec7c19f7651b06c4cd79f875510c64b99992 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 13:29:31 +0800
Subject: [PATCH 37/74] test(acp-snapshot): inherit descendant pipes portably

Use Node's explicit inherit stdio mode for the fake descendant instead of passing the parent process stream objects as child descriptors.

This keeps the grandchild's stdout and stderr handles open across the fake ACP parent's exit on Windows, so launcher shutdown must drain the late buffered update and stderr bytes just as it does on POSIX.
---
 packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts b/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts
index 647ffbb5d9..fbac6dfa10 100644
--- a/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts
+++ b/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts
@@ -267,7 +267,7 @@ function flushLogsAndExit(): void {
       `setTimeout(() => process.stderr.write(${JSON.stringify('late inherited stderr\n')}), 75)`,
     ].join(';')
     spawn(process.execPath, ['-e', code], {
-      stdio: ['ignore', process.stdout, process.stderr],
+      stdio: ['ignore', 'inherit', 'inherit'],
     }).unref()
   }
   process.exit(0)

From 37d2556a7bebfd6aeceba1932e0f039f66ae7ae9 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 13:33:08 +0800
Subject: [PATCH 38/74] docs(fs): record the revised DACL translation pair

Update the bilingual pairing checksum after the English and Chinese Windows DACL RFCs were revised together to describe semantic ACE-policy comparison.

This restores the repository's recorded translation-consistency contract without changing either document's content.
---
 ...026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml
index 5f37bf3ca3..e388c22c18 100644
--- a/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml
+++ b/docs/rfc/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-19-windows-atomic-write-dacl-preservation.md: 393ce8a992b8c0b7b580f2c794e098d66e14258e
-2026-07-19-windows-atomic-write-dacl-preservation.zh.md: c7a0b6278cf739cc5ef4432d679e48b88b61d198
+2026-07-19-windows-atomic-write-dacl-preservation.md: 13ec1546ce3a739039045ab5db9b935a83e84098
+2026-07-19-windows-atomic-write-dacl-preservation.zh.md: ca72ec22132777a12f1fcdc1b7f8816a710c0845

From b1b076f99333046ad4c6751dc031552d63056b78 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 13:49:48 +0800
Subject: [PATCH 39/74] test(acp-snapshot): cover accepted fallback termination

Drive the shutdown path where the requested signal reports a child error without exiting, the bounded marker grace expires, and fallback SIGKILL is accepted.

Assert that both signals are attempted and that close drains the successful fallback exit before preserving the original child error, restoring per-file 100% branch and line coverage for the launcher.
---
 .../acp-snapshot/tests/harness.spec.ts        | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/packages/support/acp-snapshot/tests/harness.spec.ts b/packages/support/acp-snapshot/tests/harness.spec.ts
index 5d12b2da97..64076c1217 100644
--- a/packages/support/acp-snapshot/tests/harness.spec.ts
+++ b/packages/support/acp-snapshot/tests/harness.spec.ts
@@ -248,6 +248,28 @@ describe('runScenario', () => {
     }
   })
 
+  it('preserves the child error after accepted fallback termination drains', async () => {
+    const { dir } = await scenario({})
+    const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir })
+    await launched.spawned
+
+    const childFailure = Object.assign(new Error('requested signal failed before fallback'), { code: 'EPERM' })
+    const originalKill = launched.child.kill.bind(launched.child)
+    const kill = vi.spyOn(launched.child, 'kill').mockImplementation((signal) => {
+      if (signal === 'SIGTERM') return true
+      return originalKill('SIGKILL')
+    })
+    try {
+      launched.child.emit('error', childFailure)
+      await expect(launched.close('SIGTERM')).rejects.toBe(childFailure)
+      expect(kill).toHaveBeenNthCalledWith(1, 'SIGTERM')
+      expect(kill).toHaveBeenNthCalledWith(2, 'SIGKILL')
+    } finally {
+      kill.mockRestore()
+      if (launched.child.exitCode === null && launched.child.signalCode === null) originalKill('SIGKILL')
+    }
+  })
+
   it('rejects promptly when fallback termination emits an error', async () => {
     const { dir } = await scenario({})
     const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir })

From a246afa33a424d831b6f5c59fac7f07aebdf4a03 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 14:14:00 +0800
Subject: [PATCH 40/74] test(acp-snapshot): detach the inherited-stdio fixture

Windows does not guarantee that an ordinary child process will continue after its parent exits. The fake ACP agent exited immediately after spawning its late-output descendant, so Windows could tear down that descendant and close the protocol stream before the delayed ACP update was written.

Launch the descendant in detached mode while continuing to inherit stdout and stderr, then unref it as before. This preserves the intended regression boundary: launcher shutdown must wait for descendant-held stdio and parse the final buffered frame after the direct ACP parent exits.
---
 packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts b/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts
index fbac6dfa10..c5a5810068 100644
--- a/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts
+++ b/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts
@@ -267,6 +267,7 @@ function flushLogsAndExit(): void {
       `setTimeout(() => process.stderr.write(${JSON.stringify('late inherited stderr\n')}), 75)`,
     ].join(';')
     spawn(process.execPath, ['-e', code], {
+      detached: true,
       stdio: ['ignore', 'inherit', 'inherit'],
     }).unref()
   }

From f6f984de06dd9542603120681201bbf72bb7a5a2 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 14:21:58 +0800
Subject: [PATCH 41/74] test(tui): cover same-volume cwd outside home

The existing /opt footer case reaches the ordinary outside-home return on POSIX, but Windows resolves it on the checkout drive while the user profile is on another drive. That exercises the cross-drive guard instead and leaves the same-volume fallback uncovered in Windows coverage.

Add the resolved parent of the home directory as a platform-neutral outside-home path. The case now covers the fallback on every host while retaining /opt to exercise the Windows cross-drive path, restoring per-file branch, statement, and line coverage without platform-specific expectations.
---
 packages/ui/tui/tests/tui.spec.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts
index 4437369728..c13c7a164e 100644
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -1,5 +1,5 @@
 import { homedir } from 'node:os'
-import { join } from 'node:path'
+import { join, resolve } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import type { Terminal } from '@earendil-works/pi-tui'
@@ -361,6 +361,11 @@ describe('pi-tui chat lifecycle and transcript', () => {
     expect(unsetResult.terminal.output).toContain('cwd unset')
     await dispose(unsetResult)
 
+    const homeParent = resolve(home, '..')
+    const parentResult = await setup({ cwd: homeParent })
+    expect(parentResult.terminal.output).toContain(homeParent)
+    await dispose(parentResult)
+
     const outsideResult = await setup({ cwd: '/opt' })
     expect(outsideResult.terminal.output).toContain('/opt')
     await dispose(outsideResult)

From 0c1bc50b9830266382f1e4d960cdd531d00c6423 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 14:30:46 +0800
Subject: [PATCH 42/74] test(code-runtime): widen the idle-budget timing margin

The slow-binding test used a 250 ms compute budget, which is below the instrumented worker startup cost seen intermittently in the four-worker Windows coverage job. That startup activity could exhaust the budget before the program settled into the awaited binding, making the timing assertion depend on runner load.

Use a one-second compute budget and a two-second binding delay. The awaited wall time still exceeds the busy-time allowance by a clear factor, so the test continues to prove that binding wait time is not charged while leaving enough headroom for worker initialization under coverage.
---
 .../code-runtime/code-runtime-worker/tests/runtime.spec.ts    | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
index 23c9a8ee60..e95f7cc95b 100644
--- a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
+++ b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
@@ -129,10 +129,10 @@ describe('WorkerCodeRuntime — budgets and containment (real workers)', () => {
   }, 15_000)
 
   it('does not charge time spent awaiting a slow binding against the compute budget', async () => {
-    const { runtime } = await setup({ computeMs: 250, maxWallMs: 30_000 })
+    const { runtime } = await setup({ computeMs: 1_000, maxWallMs: 30_000 })
     const result = await runtime.run({
       program: 'return await tools.slow({})',
-      bindings: tools({ slow: () => new Promise(resolve => setTimeout(() => { resolve('slow-done') }, 700)) }),
+      bindings: tools({ slow: () => new Promise(resolve => setTimeout(() => { resolve('slow-done') }, 2_000)) }),
     })
     expect(result.error).toBeUndefined()
     expect(result.value).toBe('slow-done')

From 95d803e53d700f18ee761978adac2cb4587e573d Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 19 Jul 2026 18:20:42 +0800
Subject: [PATCH 43/74] test(tui): pin footer-assertion cwd to a fixed path

The two transcript tests that assert footer token counters inherited
process.cwd() as the session cwd. In a checkout deep enough that the
footer label exceeds the 88-column fake terminal, the counters never
render and the assertions fail. Pin those tests to a short fixed cwd;
cwd rendering keeps its dedicated variants test.
---
 packages/ui/tui/tests/tui.spec.ts | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts
index c13c7a164e..d27051572e 100644
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -147,6 +147,10 @@ describe('TUI config', () => {
 describe('pi-tui chat lifecycle and transcript', () => {
   it('renders its header, footer, replay, streaming answer, todos, and status', async () => {
     const result = await setup({
+      // A fixed short cwd keeps the footer's token counters inside the 88-column
+      // fake terminal regardless of where the checkout lives; cwd rendering has
+      // its own dedicated variants test below.
+      cwd: '/workspace',
       beforeMount(session) {
         appendUser(session, 'restored prompt')
         appendAssistant(session, [
@@ -278,6 +282,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
 
   it('renders the ANSI palette and every markdown/content style', async () => {
     const result = await setup({
+      cwd: '/workspace',
       config: { color: true },
       beforeMount(session) {
         session.append('user/message', {

From 5faf8d120096d2193c1c2a2b3663871381b2cddd Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 19 Jul 2026 19:02:06 +0800
Subject: [PATCH 44/74] test(acp-snapshot): skip POSIX-cancel scenarios on
 Windows

The cancel-tool-calls scenario cancels a live bash call, which relies on
POSIX detached-process-group termination; bash has no Windows process-tree
kill yet (deferred with the Bash execution domain), so the hung call times
the scenario out on the native Windows snapshot lane.

Add a posixOnly scenario declaration that skips the run test on win32
while the fixture guards keep covering committed files on every platform,
and mark cancel-tool-calls with it.
---
 examples/acp-agent/tests/acp.snapshot.ts      |  4 ++-
 packages/support/acp-snapshot/README.md       |  2 +-
 packages/support/acp-snapshot/src/suite.ts    | 31 +++++++++++++++++--
 .../support/acp-snapshot/tests/suite.spec.ts  | 18 +++++++++++
 4 files changed, 51 insertions(+), 4 deletions(-)

diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts
index 6c34847295..7ec82d692d 100644
--- a/examples/acp-agent/tests/acp.snapshot.ts
+++ b/examples/acp-agent/tests/acp.snapshot.ts
@@ -111,7 +111,9 @@ const SCENARIOS: Scenario[] = [
     configPath: WORKSPACE_CONTEXT_CONFIG,
   },
   { name: 'cancel', hasModelTurn: true, recorded: false, overridden: true },
-  { name: 'cancel-tool-calls', hasModelTurn: true, recorded: false, overridden: true },
+  // Cancelling a live bash call relies on POSIX process-group termination;
+  // Windows bash process-tree kill is deferred with the Bash execution domain.
+  { name: 'cancel-tool-calls', hasModelTurn: true, recorded: false, overridden: true, posixOnly: true },
   { name: 'subagent-spawn', hasModelTurn: true, recorded: true },
   { name: 'subagent-multi', hasModelTurn: true, recorded: true },
   { name: 'subagent-fork', hasModelTurn: true, recorded: true },
diff --git a/packages/support/acp-snapshot/README.md b/packages/support/acp-snapshot/README.md
index 53289fda35..062a43a2fc 100644
--- a/packages/support/acp-snapshot/README.md
+++ b/packages/support/acp-snapshot/README.md
@@ -38,7 +38,7 @@ defineAcpSnapshotSuite({
 
 A scenario booting a differently-composed tree sets its own `configPath` (an overlay whose basename still ends in `cordis.yml`, so the bin's replay swap finds the sibling `*cordis.snapshot.yml`) and, when that composition changes the request header, its own `headerClass` with its own pinning scenario — the acp-agent example's Code Mode and filesystem scenarios are templates. Each pinning directory stores the normalized full prompt sequence in generated `system-prompt.golden.md` and the corresponding full tool-schema sequence in generated `tool-schemas.golden.json`; `session.jsonl` stores `"system":"{{system}}","tools":"{{tools}}"` while retaining config, reason, and any model-visible prefix. A pin with legitimate mid-run header changes declares `expectedHeaderChanges`, which fixes the length of both sidecar sequences.
 
-Every scenario compares `stdout.golden.jsonl` with cwd-rooted separators canonicalized to `/`. On Windows, `pinsNativeWindowsStdout` additionally compares the complete `stdout.golden.windows.jsonl` after the shared golden and requires that sidecar exactly when enabled.
+Every scenario compares `stdout.golden.jsonl` with cwd-rooted separators canonicalized to `/`. On Windows, `pinsNativeWindowsStdout` additionally compares the complete `stdout.golden.windows.jsonl` after the shared golden and requires that sidecar exactly when enabled. A scenario whose driven behavior needs POSIX process semantics (e.g. cancelling a live bash call kills a detached process group) declares `posixOnly`, which skips its run test on Windows while the fixture guards keep covering its committed files everywhere.
 
 The example also ships a `cordis.snapshot.yml` replay overlay next to its `cordis.yml` (the bin swaps them under `DSH_SNAPSHOT=replay` — [single-source replay config RFC](../../../docs/rfc/implemented/testing/2026-07-04-single-source-acp-replay-config.md)); replay fixtures are served by [`dsh-llm-replay`](../llm-replay/README.md), which this package points at via the `DSH_SNAPSHOT_*` env vars it sets on the child. `pnpm run test:snapshot:record` calls the live LLM and rewrites the recorded scenarios' model fixtures; `pnpm run test:snapshot:refresh` stays keyless, runs the replay overlay, and rewrites stdout, comparable session-log goldens, and each pin's prompt and tool-schema sidecars from the committed model scripts. Fixture roles, record/replay/refresh semantics, and scenario-table fields are documented on `Scenario` and in the [snapshot RFC](../../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md).
 
diff --git a/packages/support/acp-snapshot/src/suite.ts b/packages/support/acp-snapshot/src/suite.ts
index cd99f3d0c2..850afb1723 100644
--- a/packages/support/acp-snapshot/src/suite.ts
+++ b/packages/support/acp-snapshot/src/suite.ts
@@ -111,6 +111,32 @@ export interface Scenario {
    * exactly when the option is set.
    */
   pinsNativeWindowsStdout?: boolean
+  /**
+   * Whether the driven behavior needs POSIX process semantics the harness
+   * cannot exercise on Windows (e.g. cancelling a live bash tool call kills a
+   * detached process group). The scenario's run test is skipped on Windows;
+   * its fixtures stay guarded on every platform.
+   */
+  posixOnly?: boolean
+}
+
+/**
+ * Whether a scenario's run test is skipped for this mode and host: record mode
+ * skips authored (non-`recorded`) scenarios, and {@link Scenario.posixOnly}
+ * scenarios skip on Windows.
+ *
+ * @param scenario The scenario whose run test is being registered.
+ * @param recording Whether the suite runs in record mode.
+ * @param platform The running Node platform, injectable for unit coverage.
+ * @returns True when the scenario's run test must not execute.
+ */
+export function scenarioSkipped(
+  scenario: Scenario,
+  recording: boolean,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  if (recording && !scenario.recorded) return true
+  return scenario.posixOnly === true && platform === 'win32'
 }
 
 /** One stdout golden selected for a platform run. */
@@ -499,8 +525,9 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
   scenarioSuite('snapshot scenarios', () => {
     for (const scenario of scenarios) {
       // In RECORD mode, only re-run the `recorded` (live-API) scenarios; the `authored` ones
-      // (sidecar-driven errors/cancel) are never re-recorded.
-      it.skipIf(RECORDING && !scenario.recorded)(`snapshot: ${scenario.name} matches the goldens`, async ({ expect }) => {
+      // (sidecar-driven errors/cancel) are never re-recorded. `posixOnly` scenarios skip on
+      // Windows, where their process semantics cannot be driven.
+      it.skipIf(scenarioSkipped(scenario, RECORDING))(`snapshot: ${scenario.name} matches the goldens`, async ({ expect }) => {
         const dir = join(snapshotsDir, scenario.name)
         const input = JSON.parse(await readFile(join(dir, 'input.json'), 'utf8')) as InputScript
         const overrideFile = join(dir, 'replay.override.json')
diff --git a/packages/support/acp-snapshot/tests/suite.spec.ts b/packages/support/acp-snapshot/tests/suite.spec.ts
index da439378dd..e2ee55f5aa 100644
--- a/packages/support/acp-snapshot/tests/suite.spec.ts
+++ b/packages/support/acp-snapshot/tests/suite.spec.ts
@@ -15,6 +15,7 @@ import {
   normalizedToolSchemas,
   parseToolSchemasSnapshot,
   refreshFixtureReplacements,
+  scenarioSkipped,
   sessionFixtureNames,
   restorePinnedToolSchemas,
   stabilizeRefreshLog,
@@ -256,6 +257,23 @@ describe('stdoutGoldenVariants', () => {
   })
 })
 
+describe('scenarioSkipped', () => {
+  const authored: Scenario = { name: 'authored', hasModelTurn: true, recorded: false }
+  const posix: Scenario = { name: 'posix-cancel', hasModelTurn: true, recorded: false, posixOnly: true }
+
+  it('skips authored scenarios only while recording', () => {
+    expect(scenarioSkipped(authored, true, 'linux')).toBe(true)
+    expect(scenarioSkipped(authored, false, 'linux')).toBe(false)
+  })
+
+  it('skips posixOnly scenarios on Windows and nowhere else', () => {
+    expect(scenarioSkipped(posix, false, 'win32')).toBe(true)
+    expect(scenarioSkipped(posix, false, 'linux')).toBe(false)
+    expect(scenarioSkipped(posix, false, 'darwin')).toBe(false)
+    expect(scenarioSkipped(authored, false, 'win32')).toBe(false)
+  })
+})
+
 describe('fixtureContext', () => {
   it('reads the fixture header id and cwd', () => {
     const ctx = fixtureContext('{"type":"session","id":"abc","cwd":"/rec"}\n{"type":"turn/start"}\n')

From ed784cfdcef09749f814970088fb4f3672b95d07 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Mon, 20 Jul 2026 11:17:09 +0800
Subject: [PATCH 45/74] Render error cause chains at every diagnostic seam

A TUI run against an unreachable endpoint failed with only 'fetch failed':
undici wraps transport failures in a bare TypeError whose diagnosis lives
on .cause, and every diagnostic seam rendered only error.message. The
readline front door additionally rendered failed turns as pure silence.

- dsh-llm: new errorChain(value) renders the full cause chain and
  AggregateError members with circular/hostile-coercion containment.
- llm-deepseek: pre-response transport failures throw LlmError('NETWORK')
  naming the endpoint and chaining the fetch TypeError; aborts keep their
  DOMException so the loop still classifies them as cancellation.
- agent-loop: durable turn/end error messages and logger warnings render
  through errorChain; local renderThrown copies removed.
- ui-stdio: failure turn/end reasons now render ([turn failed <code>],
  [turn aborted], [turn rejected], output-token-limit); startup-failure
  logs use errorChain.
- ui-tui: agent/error notices and the startup-failure line use errorChain.
---
 ...20-error-cause-chain-diagnostics.i18n.yaml |  6 +++
 ...026-07-20-error-cause-chain-diagnostics.md | 37 ++++++++++++++
 ...-07-20-error-cause-chain-diagnostics.zh.md | 37 ++++++++++++++
 docs/config-catalog.md                        |  6 +--
 docs/cordis-catalog/events.md                 |  2 +-
 docs/cordis-catalog/services.md               |  2 +-
 packages/core/agent-loop/src/agent.ts         |  8 +---
 packages/core/agent-loop/src/index.ts         | 17 ++-----
 packages/core/agent-loop/src/loop.ts          | 13 +++--
 .../tests/config-session-id.spec.ts           | 12 ++---
 packages/llm/llm-deepseek/README.md           |  2 +-
 packages/llm/llm-deepseek/src/adapter.ts      | 48 +++++++++++++------
 .../llm/llm-deepseek/tests/adapter.spec.ts    | 35 +++++++++++++-
 packages/llm/llm/README.md                    |  1 +
 packages/llm/llm/src/error.ts                 | 45 +++++++++++++++++
 packages/llm/llm/tests/service.spec.ts        | 45 +++++++++++++++++
 packages/ui/stdio/README.md                   |  2 +-
 packages/ui/stdio/src/index.ts                | 29 ++++++-----
 packages/ui/stdio/tests/stdio.spec.ts         | 39 ++++++++++++++-
 packages/ui/tui/src/index.ts                  | 16 ++-----
 packages/ui/tui/tests/tui.spec.ts             |  4 +-
 website/zh-CN/api/harness/agent-loop.md       |  8 ++--
 website/zh-CN/api/harness/events.md           |  2 +-
 23 files changed, 333 insertions(+), 83 deletions(-)
 create mode 100644 .agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml
 create mode 100644 .agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md
 create mode 100644 .agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md

diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml
new file mode 100644
index 0000000000..630a1b05e6
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-20-error-cause-chain-diagnostics.md: 2d860d0e966158dd9ec12b45f88e3b031e1cb35a
+2026-07-20-error-cause-chain-diagnostics.zh.md: 6eac19dd08d50e4662d53889577b5e3ddabaafdd
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md
new file mode 100644
index 0000000000..2d860d0e96
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md
@@ -0,0 +1,37 @@
+# Agent Note: Render error cause chains at every diagnostic seam
+
+Status: implemented
+
+English | [中文](2026-07-20-error-cause-chain-diagnostics.zh.md)
+
+## Problem
+
+A TUI run against an unreachable DeepSeek endpoint failed with the single notice `fetch failed` and no further detail. Two independent gaps produced that dead end:
+
+1. undici's `fetch` wraps every transport failure (DNS, refused connection, TLS, proxy) in a bare `TypeError: fetch failed` whose actionable detail — `ECONNREFUSED`, `bad port`, the Happy Eyeballs AggregateError — lives on `error.cause`. Every diagnostic seam in the harness rendered only `error.message` (or `String(error)`, which is equivalent for Errors), so the wrapper masked the diagnosis in the TUI notice, the durable `turn/end` reason, and every logger line.
+2. The readline front door (`dsh-stdio`) rendered no failure reason at all: a `turn/end` with `reason.kind === 'error'` printed nothing but the next `> ` prompt, so the same failure in `demo:repl` was pure silence.
+
+## Decision
+
+- `dsh-llm` exports `errorChain(value)`: renders a thrown value with its full `cause` chain (`outer: inner: …`) and AggregateError members (`msg [m1; m2]`), with circular-cause and hostile-coercion containment. It is a diagnostic-surface renderer only; routing stays on `HarnessError.code`.
+- The DeepSeek adapter wraps a pre-response transport failure in `LlmError('NETWORK')` naming the configured `baseURL` and chaining the original `TypeError` as `cause`. An aborted request keeps its `DOMException` so the loop still classifies it as cancellation, not a provider failure.
+- Every diagnostic seam renders through `errorChain` instead of `error.message`/`String(error)`: the agent-loop's durable `turn/end` error message (`errorData`), its logger warnings, the TUI's `agent/error` notice and startup-failure line, and `dsh-stdio`'s startup-failure log lines. The per-package `renderThrown` copies in `dsh-agent-loop`, `dsh-stdio`, and `dsh-tui` are deleted in favor of the one shared renderer.
+- `dsh-stdio` renders failure `turn/end` reasons: `[turn failed <code>] <message>`, `[turn aborted] <reason>`, `[turn rejected] <reason>`, `[turn interrupted by a previous process exit]`, and the output-token-limit notice. Unknown merge-extended kinds fall through as ordinary turn ends.
+
+`errorChain` lives in `dsh-llm` beside `HarnessError` for the same reason the base class does: it is the leaf package every consumer already imports, so sharing costs no new dependency edge.
+
+## Alternatives considered
+
+**Chain rendering inside each error's constructor (bake the cause into `message`).** Rejected: it double-renders once consumers also walk `cause` (the first draft of the adapter fix produced `… fetch failed: bad port: fetch failed: bad port`), and it destroys the structured chain for consumers that want to route on the inner error.
+
+**A `cause`-aware logger exporter only.** Rejected: the durable `turn/end` reason and the TUI notice are not logger lines; the masked message would persist in the session log — the single durable record of an in-turn failure — and in the primary UI surface.
+
+**Per-package `renderThrown` upgrades.** Rejected: three packages already carried near-identical private copies; upgrading each separately entrenches the duplication the shared renderer removes.
+
+## Consequences
+
+- A transport failure now reads `DeepSeek API request to <baseURL> failed: fetch failed: connect ECONNREFUSED …` in the TUI notice, the readline transcript, and the persisted session log, at the cost of longer diagnostic strings.
+- Durable `turn/end` error messages include cause detail. Existing snapshot fixtures replay byte-identically because their scripted errors carry no `cause` (for such errors `errorChain(err)` equals `err.message`); only unit-test expectation strings changed. A fixture recorded from a real transport failure would carry the chain.
+- `errorChain` renders `message` without the class name (`String(error)` rendered `Error: <message>`), so a bare `TypeError` in a log line loses its type label unless its message is empty (then the name is the fallback). The chain detail was judged worth more than the class name at these seams.
+- `dsh-stdio` output for failed turns is no longer silent; piped consumers that parsed the transcript see new `[turn …]` lines.
+- Remaining `renderThrown` copies in `dsh-subagent`, `dsh-workflow`, `dsh-skill`, `dsh-workflow-workerthread`, and `cli-demo` still render without the chain; they wrap package-local errors that carry their own messages, and can adopt `errorChain` when their diagnostics prove insufficient.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md
new file mode 100644
index 0000000000..6eac19dd08
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md
@@ -0,0 +1,37 @@
+# Agent Note: 在每个诊断接缝处渲染错误 cause 链
+
+Status: implemented
+
+[English](2026-07-20-error-cause-chain-diagnostics.md) | 中文
+
+## Problem
+
+TUI 连接不可达的 DeepSeek 端点时，失败只显示一条 `fetch failed` 通知，没有任何进一步细节。两个独立缺口共同造成了这个死胡同：
+
+1. undici 的 `fetch` 把所有传输层失败（DNS、连接被拒、TLS、代理）包装成裸的 `TypeError: fetch failed`，可操作的细节——`ECONNREFUSED`、`bad port`、Happy Eyeballs 的 AggregateError——都在 `error.cause` 上。harness 里的每个诊断接缝都只渲染 `error.message`（或对 Error 等价的 `String(error)`），于是包装层在 TUI 通知、持久化的 `turn/end` reason 和所有日志行里都掩盖了诊断信息。
+2. readline 前门（`dsh-stdio`）完全不渲染失败原因：`reason.kind === 'error'` 的 `turn/end` 只打印下一个 `> ` 提示符，同样的失败在 `demo:repl` 里就是纯粹的沉默。
+
+## Decision
+
+- `dsh-llm` 导出 `errorChain(value)`：渲染抛出值及其完整 `cause` 链（`outer: inner: …`）与 AggregateError 成员（`msg [m1; m2]`），并容错循环 cause 和恶意强制转换。它只是诊断表面的渲染器；路由仍然基于 `HarnessError.code`。
+- DeepSeek 适配器把拿到响应之前的传输失败包装成 `LlmError('NETWORK')`，写明配置的 `baseURL` 并把原始 `TypeError` 链为 `cause`。被中止的请求保留其 `DOMException`，使循环仍将其归类为取消而非 provider 失败。
+- 每个诊断接缝改用 `errorChain` 而非 `error.message`/`String(error)`：agent-loop 的持久化 `turn/end` 错误消息（`errorData`）、其日志警告、TUI 的 `agent/error` 通知与启动失败行、以及 `dsh-stdio` 的启动失败日志行。`dsh-agent-loop`、`dsh-stdio`、`dsh-tui` 里各自的 `renderThrown` 副本被删除，统一使用这一个共享渲染器。
+- `dsh-stdio` 渲染失败的 `turn/end` reason：`[turn failed <code>] <message>`、`[turn aborted] <reason>`、`[turn rejected] <reason>`、`[turn interrupted by a previous process exit]` 以及输出 token 上限通知。未知的 merge 扩展 kind 按普通 turn 结束处理。
+
+`errorChain` 与 `HarnessError` 一样放在 `dsh-llm` 里，理由相同：它是每个消费者都已导入的叶子包，共享不增加新的依赖边。
+
+## Alternatives considered
+
+**在每个错误的构造函数里渲染链（把 cause 烤进 `message`）。** 否决：当消费者同时遍历 `cause` 时会双重渲染（适配器修复的第一版产出了 `… fetch failed: bad port: fetch failed: bad port`），并且破坏了想按内层错误路由的消费者所需的结构化链。
+
+**只做一个感知 `cause` 的日志导出器。** 否决：持久化的 `turn/end` reason 和 TUI 通知不是日志行；被掩盖的消息会留在会话日志——回合内失败的唯一持久记录——以及主要 UI 表面里。
+
+**逐包升级 `renderThrown`。** 否决：三个包已经各自持有几乎相同的私有副本；分别升级只会固化共享渲染器所要消除的重复。
+
+## Consequences
+
+- 传输失败现在在 TUI 通知、readline transcript 和持久化会话日志里显示为 `DeepSeek API request to <baseURL> failed: fetch failed: connect ECONNREFUSED …`，代价是更长的诊断字符串。
+- 持久化的 `turn/end` 错误消息包含 cause 细节。现有 snapshot fixture 字节级一致地回放，因为其脚本化错误不带 `cause`（对这类错误 `errorChain(err)` 等于 `err.message`）；只有单元测试的期望字符串有变化。从真实传输失败录制的 fixture 会携带完整链。
+- `errorChain` 渲染 `message` 而不带类名（`String(error)` 会渲染 `Error: <message>`），因此日志行里的裸 `TypeError` 会丢失类型标签，除非消息为空（此时回退到类名）。在这些接缝上，链细节被判断为比类名更有价值。
+- `dsh-stdio` 对失败回合的输出不再沉默；解析 transcript 的管道消费者会看到新的 `[turn …]` 行。
+- `dsh-subagent`、`dsh-workflow`、`dsh-skill`、`dsh-workflow-workerthread`、`cli-demo` 里剩余的 `renderThrown` 副本仍不渲染链；它们包装的是自带消息的包内错误，等诊断信息证明不足时再采用 `errorChain`。
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index e6934564ae..a4eedf25cc 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -101,7 +101,7 @@ export interface Config {
 
 Depends on: [`AgentOptions`](core-data-structures/core.md) · [`SessionId`](core-data-structures/core.md)
 
-Source: [`packages/core/agent-loop/src/index.ts:369`](../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:360`](../packages/core/agent-loop/src/index.ts)
 
 ## `@deepseek-ai/dsh-agent-spine-demo`
 
@@ -858,7 +858,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/ui/stdio/src/index.ts:33`](../packages/ui/stdio/src/index.ts)
+Source: [`packages/ui/stdio/src/index.ts:34`](../packages/ui/stdio/src/index.ts)
 
 ## `@deepseek-ai/dsh-stdio-demo`
 
@@ -1302,7 +1302,7 @@ export interface TuiConfig {
 }
 ```
 
-Source: [`packages/ui/tui/src/index.ts:100`](../packages/ui/tui/src/index.ts)
+Source: [`packages/ui/tui/src/index.ts:101`](../packages/ui/tui/src/index.ts)
 
 ## `@deepseek-ai/dsh-user-approval`
 
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 612de06e82..4728f2d65a 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -366,7 +366,7 @@ A declarative agent entry failed before it could publish a live agent. Consumers
 
 Types: [SessionId](../core-data-structures/core.md)
 
-Source: [`packages/core/agent-loop/src/index.ts:362`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:353`](../../packages/core/agent-loop/src/index.ts)
 
 ## `approval/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 42d645e6d9..af94bc90d3 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -44,7 +44,7 @@ async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandl
 
 Types: [Agent](../core-data-structures/core.md) · [AgentOptions](../core-data-structures/core.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md)
 
-Source: [`packages/core/agent-loop/src/index.ts:407`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:398`](../../packages/core/agent-loop/src/index.ts)
 
 ## `ctx.agents` — `AgentRegistry`
 
diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts
index a9c7f3b766..85e4c34e34 100644
--- a/packages/core/agent-loop/src/agent.ts
+++ b/packages/core/agent-loop/src/agent.ts
@@ -10,7 +10,7 @@ import type { Context } from 'cordis'
 import { agentEvents } from '@deepseek-ai/dsh-agent'
 import type { AgentOptions, AgentStatus, HookContext, InjectOptions, SendOptions } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import { deepFreeze } from '@deepseek-ai/dsh-llm'
+import { deepFreeze, errorChain } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
 import { snapshotJsonValue, type Session, type SessionId } from '@deepseek-ai/dsh-session'
 import { Inbox, type InboxMessage } from './inbox.ts'
@@ -290,7 +290,7 @@ export class ReactLoopAgent implements Agent {
       if (turnRecorded) {
         // Through the store's flush (the carrier owner), never a raw parallel.
         const flush = this.loopCtx.sessions.flush(this.session).catch((error: unknown) => {
-          const rendered = renderThrown(error)
+          const rendered = errorChain(error)
           const err = error instanceof Error ? error : new Error(rendered)
           this.loopCtx.logger.warn(`agent "${this.id}": flush after idle injection failed: ${rendered}`)
           agentEvents(this.loopCtx, this).emit('agent/error', turn, 0, err)
@@ -445,7 +445,3 @@ export class ReactLoopAgent implements Agent {
   }
 }
 
-/** Render an ordinary thrown value for the error event and log. */
-function renderThrown(value: unknown): string {
-  return value instanceof Error ? value.message : String(value)
-}
diff --git a/packages/core/agent-loop/src/index.ts b/packages/core/agent-loop/src/index.ts
index 2a77afc983..24e18d5c32 100644
--- a/packages/core/agent-loop/src/index.ts
+++ b/packages/core/agent-loop/src/index.ts
@@ -20,7 +20,7 @@ import type {
   ResumeAgentOptions,
   SessionStartSource,
 } from '@deepseek-ai/dsh-agent'
-import type {} from '@deepseek-ai/dsh-llm'
+import { errorChain } from '@deepseek-ai/dsh-llm'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import type { Session, SessionHeader } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-system-prompt'
@@ -41,15 +41,6 @@ const INACTIVE_STATES: ReadonlySet<FiberState> = new Set([
   FiberState.FAILED,
 ])
 
-/** Render an arbitrary thrown value without letting coercion escape containment. */
-function renderThrown(value: unknown): string {
-  try {
-    return String(value)
-  } catch {
-    return '<unrenderable thrown value>'
-  }
-}
-
 /** Factory-level ownership of every preparing or live transaction. */
 class FactoryOwnership {
   private accepting = true
@@ -475,16 +466,16 @@ export class AgentLoop extends Service implements AgentFactory {
     error: unknown,
   ): void {
     if (!this.ownership.isActive()) return
-    this.ctx.logger.warn(`agent "${configId}": config-driven ${action} of "${sessionId}" failed: ${renderThrown(error)}`)
+    this.ctx.logger.warn(`agent "${configId}": config-driven ${action} of "${sessionId}" failed: ${errorChain(error)}`)
     const args: unknown[] = ['agent-loop/config-start-failed', sessionId, error]
     for (const callback of this.ctx.events.dispatch('emit', args)) {
       try {
         const returned: unknown = callback(...args)
         void Promise.resolve(returned).catch((listenerError: unknown) => {
-          this.ctx.logger.warn(`agent "${configId}": config-start-failed listener rejected: ${renderThrown(listenerError)}`)
+          this.ctx.logger.warn(`agent "${configId}": config-start-failed listener rejected: ${errorChain(listenerError)}`)
         })
       } catch (listenerError: unknown) {
-        this.ctx.logger.warn(`agent "${configId}": config-start-failed listener threw: ${renderThrown(listenerError)}`)
+        this.ctx.logger.warn(`agent "${configId}": config-start-failed listener threw: ${errorChain(listenerError)}`)
       }
     }
   }
diff --git a/packages/core/agent-loop/src/loop.ts b/packages/core/agent-loop/src/loop.ts
index bc18ee52d3..80da07ea10 100644
--- a/packages/core/agent-loop/src/loop.ts
+++ b/packages/core/agent-loop/src/loop.ts
@@ -8,7 +8,7 @@
 import type { Context } from 'cordis'
 import type { ContentBlock, FinishReason, GenerateOptions, LlmCallConfig, Message } from '@deepseek-ai/dsh-llm'
 import { isDeepStrictEqual } from 'node:util'
-import { BlockAssembler, HarnessError, assertNever, deepFreeze, isLlmAdapterFailure } from '@deepseek-ai/dsh-llm'
+import { BlockAssembler, HarnessError, assertNever, deepFreeze, errorChain, isLlmAdapterFailure } from '@deepseek-ai/dsh-llm'
 import { agentEvents, assembleContextFor } from '@deepseek-ai/dsh-agent'
 import type { AgentEventDispatch, ContinuationDecision, HookContext, PromptDecision, RequestError, RequestErrorDecision } from '@deepseek-ai/dsh-agent'
 import { canonicalHeader } from '@deepseek-ai/dsh-session'
@@ -56,9 +56,12 @@ function finishError(finish: FinishReason): RequestError | undefined {
 /**
  * Build the `{ message, code? }` part of an error payload, omitting the
  * `code` key entirely when absent (exactOptionalPropertyTypes-correct).
+ * The durable message renders the full cause chain: `turn/end` is the single
+ * durable record of an in-turn failure, so a wrapper message alone (e.g.
+ * `fetch failed`) would lose the diagnosis the session log exists to keep.
  */
 function errorData(err: RequestError): { message: string; code?: string } {
-  return { message: err.message, ...typeof err.code === 'string' ? { code: err.code } : {} }
+  return { message: errorChain(err), ...typeof err.code === 'string' ? { code: err.code } : {} }
 }
 
 /** Map a successful max-token finish onto the turn reason; other successful finishes add nothing. */
@@ -151,7 +154,7 @@ export async function runLoop(ctx: Context, handle: LoopHandle): Promise<void> {
     } catch (error: unknown) {
       // Pre-turn failure has no durable boundary to close; report it without appending outside a turn.
       const err = toError(error)
-      ctx.logger.warn(`agent "${agent.id}": turn ${turn} failed before it started: ${err.message}`)
+      ctx.logger.warn(`agent "${agent.id}": turn ${turn} failed before it started: ${errorChain(err)}`)
       try {
         events.emit('agent/error', turn, 0, err)
       } catch { /* contained: a throwing agent/error listener must not kill the driver */ }
@@ -387,7 +390,7 @@ async function runTurn(
           )
         } catch (recoveryError: unknown) {
           ctx.logger.warn(
-            `agent "${agent.id}": request recovery failed at turn ${turn}, step ${step}: ${toError(recoveryError).message}`,
+            `agent "${agent.id}": request recovery failed at turn ${turn}, step ${step}: ${errorChain(recoveryError)}`,
           )
         }
         handle.setAbort(undefined)
@@ -551,7 +554,7 @@ async function runTurn(
   } catch (error: unknown) {
     // The turn is closed, so report the failed flush live rather than append outside a turn.
     const err = toError(error)
-    ctx.logger.warn(`agent "${agent.id}": session/flush failed at turn ${turn}: ${err.message}`)
+    ctx.logger.warn(`agent "${agent.id}": session/flush failed at turn ${turn}: ${errorChain(err)}`)
     try {
       events.emit('agent/error', turn, step, err)
     } catch {
diff --git a/packages/core/agent-loop/tests/config-session-id.spec.ts b/packages/core/agent-loop/tests/config-session-id.spec.ts
index cadc176aea..5f9bf3dd07 100644
--- a/packages/core/agent-loop/tests/config-session-id.spec.ts
+++ b/packages/core/agent-loop/tests/config-session-id.spec.ts
@@ -217,14 +217,14 @@ describe('config-driven session id', () => {
     })
 
     await expect.poll(() => warn).toHaveBeenCalledWith(expect.stringContaining(
-      'config-driven restore of "stdio-exact-failure" failed: Error: persistence index failed',
+      'config-driven restore of "stdio-exact-failure" failed: persistence index failed',
     ))
     expect(failures).toEqual([{ sessionId: SessionId('stdio-exact-failure'), error: failure }])
     expect(warn).toHaveBeenCalledWith(
-      'agent "main": config-start-failed listener threw: Error: failure observer failed',
+      'agent "main": config-start-failed listener threw: failure observer failed',
     )
     await expect.poll(() => warn).toHaveBeenCalledWith(
-      'agent "main": config-start-failed listener rejected: Error: async failure observer failed',
+      'agent "main": config-start-failed listener rejected: async failure observer failed',
     )
     expect(ctx.agents.get(SessionId('stdio-exact-failure'))).toBeUndefined()
     warn.mockRestore()
@@ -256,13 +256,13 @@ describe('config-driven session id', () => {
 
     await expect.poll(() => failures).toEqual([unrenderable])
     expect(warn).toHaveBeenCalledWith(
-      'agent "main": config-driven restore of "stdio-exact-unrenderable" failed: <unrenderable thrown value>',
+      'agent "main": config-driven restore of "stdio-exact-unrenderable" failed: <unrenderable value>',
     )
     expect(warn).toHaveBeenCalledWith(
-      'agent "main": config-start-failed listener threw: <unrenderable thrown value>',
+      'agent "main": config-start-failed listener threw: <unrenderable value>',
     )
     await expect.poll(() => warn).toHaveBeenCalledWith(
-      'agent "main": config-start-failed listener rejected: <unrenderable thrown value>',
+      'agent "main": config-start-failed listener rejected: <unrenderable value>',
     )
     await ctx.fiber.dispose()
   })
diff --git a/packages/llm/llm-deepseek/README.md b/packages/llm/llm-deepseek/README.md
index 27bf4b626a..ee4c705560 100644
--- a/packages/llm/llm-deepseek/README.md
+++ b/packages/llm/llm-deepseek/README.md
@@ -42,7 +42,7 @@ Every request carries the shared attribution header from dsh-llm's `attributionH
 
 ## Errors
 
-Non-2xx responses throw `LlmError` with stable codes: `AUTH` (401/403), `RATE_LIMIT` (429), `CONTEXT_WINDOW_EXCEEDED` (a 400 whose provider code, type, or message identifies context overflow), `INVALID_REQUEST` (other 400s), `SERVER` (5xx), `HTTP_<status>` otherwise. Protocol violations throw `STREAM_CLOSED` (no `[DONE]`) or `MALFORMED_RESPONSE` (bad JSON payload). Unknown wire `finish_reason`s (e.g. `content_filter`, `insufficient_system_resource`) become `finish {kind: 'error', code: <REASON>}` chunks.
+Non-2xx responses throw `LlmError` with stable codes: `AUTH` (401/403), `RATE_LIMIT` (429), `CONTEXT_WINDOW_EXCEEDED` (a 400 whose provider code, type, or message identifies context overflow), `INVALID_REQUEST` (other 400s), `SERVER` (5xx), `HTTP_<status>` otherwise. A transport failure before any response (DNS, refused connection, TLS, proxy) throws `NETWORK` naming the configured endpoint and chaining fetch's `TypeError: fetch failed` as `cause`, so `errorChain` renders the underlying diagnosis; an abort keeps its `DOMException` so the loop classifies it as cancellation. Protocol violations throw `STREAM_CLOSED` (no `[DONE]`) or `MALFORMED_RESPONSE` (bad JSON payload). Unknown wire `finish_reason`s (e.g. `content_filter`, `insufficient_system_resource`) become `finish {kind: 'error', code: <REASON>}` chunks.
 
 ## Testing
 
diff --git a/packages/llm/llm-deepseek/src/adapter.ts b/packages/llm/llm-deepseek/src/adapter.ts
index 918c8eee82..66520a83d4 100644
--- a/packages/llm/llm-deepseek/src/adapter.ts
+++ b/packages/llm/llm-deepseek/src/adapter.ts
@@ -81,23 +81,43 @@ export class DeepSeekAdapter extends LlmAdapter {
 
   async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
     const body = serializeRequest(options, this.options.defaults ?? {})
+    // Prepared outside the try so the NETWORK label below covers exactly the
+    // transport boundary, never a serialization failure.
+    const payload = JSON.stringify(body)
+    const headers = {
+      'authorization': `Bearer ${this.options.apiKey}`,
+      'content-type': 'application/json',
+      'accept': 'text/event-stream',
+      ...attributionHeaders(),
+      ...options.sessionId !== undefined
+        ? { 'x-deepseek-harness-session-id': String(options.sessionId) }
+        : {},
+    }
 
     // TODO(http): adopt the Cordis HTTP service when shared transport configuration
     // outweighs its additional runtime dependencies.
-    const response = await fetch(`${this.options.baseURL}/chat/completions`, {
-      method: 'POST',
-      headers: {
-        'authorization': `Bearer ${this.options.apiKey}`,
-        'content-type': 'application/json',
-        'accept': 'text/event-stream',
-        ...attributionHeaders(),
-        ...options.sessionId !== undefined
-          ? { 'x-deepseek-harness-session-id': String(options.sessionId) }
-          : {},
-      },
-      body: JSON.stringify(body),
-      ...options.signal ? { signal: options.signal } : {},
-    })
+    let response: Response
+    try {
+      response = await fetch(`${this.options.baseURL}/chat/completions`, {
+        method: 'POST',
+        headers,
+        body: payload,
+        ...options.signal ? { signal: options.signal } : {},
+      })
+    } catch (error: unknown) {
+      // An aborted request rethrows its original rejection (the signal's abort
+      // reason) so the loop classifies it as cancellation, not a provider failure.
+      if (options.signal?.aborted) throw error
+      // fetch wraps every transport failure (DNS, refused connection, TLS,
+      // proxy) in a bare `TypeError: fetch failed` whose actionable detail
+      // lives on `cause`. Wrapping with the endpoint and chaining the cause
+      // lets `errorChain` render the full diagnosis at every reporting seam.
+      throw new LlmError(
+        `DeepSeek API request to ${this.options.baseURL} failed`,
+        'NETWORK',
+        { cause: error },
+      )
+    }
 
     if (!response.ok) {
       let message = `DeepSeek API error (HTTP ${response.status})`
diff --git a/packages/llm/llm-deepseek/tests/adapter.spec.ts b/packages/llm/llm-deepseek/tests/adapter.spec.ts
index 954a0ecebd..b92f96dbda 100644
--- a/packages/llm/llm-deepseek/tests/adapter.spec.ts
+++ b/packages/llm/llm-deepseek/tests/adapter.spec.ts
@@ -2,7 +2,7 @@ import { createServer } from 'node:http'
 import type { IncomingMessage, Server, ServerResponse } from 'node:http'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import LlmService, { CONTEXT_WINDOW_EXCEEDED_CODE, LlmError, userAgent } from '@deepseek-ai/dsh-llm'
+import LlmService, { CONTEXT_WINDOW_EXCEEDED_CODE, errorChain, LlmError, userAgent } from '@deepseek-ai/dsh-llm'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
 import { DeepSeekAdapter } from '@deepseek-ai/dsh-llm-deepseek'
@@ -228,6 +228,39 @@ describe('DeepSeekAdapter against a mock server', () => {
     expect(httpErrorCode(418)).toBe('HTTP_418')
   })
 
+  it('wraps a transport failure in NETWORK with the fetch cause chain in the message', async () => {
+    // Port 1 is reserved/unbound: fetch rejects with `TypeError: fetch failed`
+    // whose actionable detail (ECONNREFUSED) lives on `cause`.
+    const ctx = await harness('http://127.0.0.1:1')
+    let caught: unknown
+    try {
+      await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
+    } catch (error: unknown) {
+      caught = error
+    }
+    expect(caught).toBeInstanceOf(LlmError)
+    const llmError = caught as LlmError
+    expect(llmError.code).toBe('NETWORK')
+    expect(llmError.message).toContain('http://127.0.0.1:1')
+    expect(llmError.cause).toBeInstanceOf(TypeError)
+    // The chain renderer reaches the transport diagnosis through the cause.
+    expect(errorChain(llmError)).toMatch(/ECONNREFUSED|EADDRNOTAVAIL|bad port/)
+  })
+
+  it('keeps an abort rejection unwrapped so the loop classifies it as cancellation', async () => {
+    const controller = new AbortController()
+    controller.abort()
+    const ctx = await harness('http://127.0.0.1:1')
+    let caught: unknown
+    try {
+      await assemble(ctx, { model: 'deepseek-v4-flash', messages: [], signal: controller.signal })
+    } catch (error: unknown) {
+      caught = error
+    }
+    expect(caught).not.toBeInstanceOf(LlmError)
+    expect((caught as Error).name).toBe('AbortError')
+  })
+
   it('throws EMPTY_RESPONSE when the response has no body', async () => {
     const adapter = new DeepSeekAdapter({ apiKey: 'k', baseURL: 'http://127.0.0.1:1' })
     const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(
diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md
index f9142dbc52..82ca7f901c 100644
--- a/packages/llm/llm/README.md
+++ b/packages/llm/llm/README.md
@@ -48,6 +48,7 @@ Every product adapter sends application identity on provider HTTP requests. `att
 - `BlockAssembler` — incrementally assembles raw chunks into complete content blocks and an assistant message. The agent loop feeds it raw chunks (logging them for replay) while reading the assembled blocks/message for history.
 - `HarnessError` — base class for the harness error taxonomy: a stable `code` string (distinct from the human `message`) plus `cause` chaining. Lives here, in the leaf package every other imports, so a single base is shared without a new dependency edge. Per-package errors (`LlmError`, `ToolArgsError`, `InvariantError`, …) extend it. `isHarnessError(value)` narrows at seams.
 - `LlmError` — extends `HarnessError`; its stable `code` string (`NO_ADAPTER`, `DUPLICATE_ADAPTER`, and adapter codes like `AUTH`/`RATE_LIMIT`) is the programmatic failure contract.
+- `errorChain(value)` — renders a thrown value with its full `cause` chain and AggregateError members for diagnostic surfaces (UI notices, logger lines, durable `turn/end` messages), so transport wrappers like undici's `TypeError: fetch failed` surface the underlying `ECONNREFUSED`/DNS/TLS detail instead of masking it. Rendering only — route on `code`, never by parsing the result.
 - `CONTEXT_WINDOW_EXCEEDED_CODE` — the provider-neutral code both DeepSeek adapters use when a request exceeds the model context window, regardless of thrown-HTTP versus in-band finish delivery. `isContextWindowExceededError(detail)` is their shared conservative classifier for OpenAI-compatible provider detail.
 
 ### Real adapters
diff --git a/packages/llm/llm/src/error.ts b/packages/llm/llm/src/error.ts
index 8c1c736492..c351060ee5 100644
--- a/packages/llm/llm/src/error.ts
+++ b/packages/llm/llm/src/error.ts
@@ -62,6 +62,51 @@ export function isContextWindowExceededError(detail: string): boolean {
     || EXCEEDS_MODEL_CONTEXT.test(detail)
 }
 
+/**
+ * Render a thrown value with its full `cause` chain and AggregateError
+ * members, so transport wrappers like undici's `TypeError: fetch failed`
+ * surface the underlying failure instead of masking it. Diagnostic-surface
+ * rendering only (messages, notices, logs) — never parse the result; route on
+ * {@link HarnessError.code}.
+ * @param value - the caught value (`unknown` in catch clauses).
+ * @returns the outermost message first, each cause appended with `: ` (skipped
+ * when it repeats the wrapper message verbatim), and AggregateError members
+ * bracketed and `; `-joined.
+ */
+export function errorChain(value: unknown): string {
+  // Tracks the active recursion path (entries removed on exit), so only true
+  // cycles are flagged and a diamond-shared cause still renders in full.
+  const path = new Set<unknown>()
+  const render = (current: unknown): string => {
+    if (path.has(current)) return '<circular cause>'
+    path.add(current)
+    try {
+      if (!(current instanceof Error)) return String(current)
+      const message = current.message === '' ? current.name : current.message
+      const members = current instanceof AggregateError && current.errors.length > 0
+        ? ` [${current.errors.map(render).join('; ')}]`
+        : ''
+      const causeText = current.cause === undefined || current.cause === null
+        ? ''
+        : render(current.cause)
+      // Wrappers like `new HarnessError(String(value), code, { cause: value })`
+      // repeat their cause verbatim; rendering it again would only add noise.
+      const cause = causeText === '' || causeText === message ? '' : `: ${causeText}`
+      return `${message}${members}${cause}`
+    } catch {
+      // Only hostile coercion or hostile accessors (a throwing toString /
+      // Symbol.toPrimitive on a non-Error, or a throwing message/name/cause/
+      // errors getter on an Error subclass): this renderer feeds UI notices
+      // and logs, so nothing may escape. Inner frames catch their own throws,
+      // so only the hostile node collapses, not the whole chain.
+      return '<unrenderable value>'
+    } finally {
+      path.delete(current)
+    }
+  }
+  return render(value)
+}
+
 /**
  * Narrow an arbitrary thrown value to a HarnessError (for `instanceof` at seams).
  * @param value - the caught value (`unknown` in catch clauses).
diff --git a/packages/llm/llm/tests/service.spec.ts b/packages/llm/llm/tests/service.spec.ts
index 6e14d749ba..67b90d1c2f 100644
--- a/packages/llm/llm/tests/service.spec.ts
+++ b/packages/llm/llm/tests/service.spec.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import LlmService, {
+  errorChain,
   GenerateOptions,
   HarnessError,
   isContextWindowExceededError,
@@ -80,6 +81,50 @@ describe('LlmService', () => {
     expect(isContextWindowExceededError('context window size must be positive')).toBe(false)
   })
 
+  it('errorChain renders the full cause chain of a wrapped transport failure', () => {
+    const chain = new TypeError('fetch failed', { cause: new Error('connect ECONNREFUSED 127.0.0.1:443') })
+    expect(errorChain(chain)).toBe('fetch failed: connect ECONNREFUSED 127.0.0.1:443')
+  })
+
+  it('errorChain renders AggregateError members (Happy Eyeballs multi-address failures)', () => {
+    const aggregate = new AggregateError(
+      [new Error('connect ECONNREFUSED ::1:443'), new Error('connect ECONNREFUSED 127.0.0.1:443')],
+      '',
+    )
+    const wrapped = new TypeError('fetch failed', { cause: aggregate })
+    expect(errorChain(wrapped)).toBe(
+      'fetch failed: AggregateError [connect ECONNREFUSED ::1:443; connect ECONNREFUSED 127.0.0.1:443]',
+    )
+  })
+
+  it('errorChain survives non-Error values, hostile coercion, and circular causes', () => {
+    expect(errorChain('plain string')).toBe('plain string')
+    expect(errorChain({ toString: () => { throw new Error('hostile') } })).toBe('<unrenderable value>')
+    const circular = new Error('outer')
+    circular.cause = circular
+    expect(errorChain(circular)).toBe('outer: <circular cause>')
+    // A hostile accessor collapses only its own node, not the whole chain.
+    const hostileNode = new Error('node')
+    Object.defineProperty(hostileNode, 'message', { get() { throw new Error('hostile getter') } })
+    expect(errorChain(new Error('outer', { cause: hostileNode }))).toBe('outer: <unrenderable value>')
+    // A diamond-shared (non-cyclic) cause renders in full on both paths.
+    const shared = new Error('shared')
+    const diamond = new AggregateError([new Error('a', { cause: shared }), new Error('b', { cause: shared })], 'agg')
+    expect(errorChain(diamond)).toBe('agg [a: shared; b: shared]')
+  })
+
+  it('errorChain falls back to the error name, skips empty aggregates, and stops at null causes', () => {
+    expect(errorChain(new TypeError('', { cause: null }))).toBe('TypeError')
+    expect(errorChain(new AggregateError([], 'all failed'))).toBe('all failed')
+  })
+
+  it('errorChain collapses a cause that repeats the wrapper message verbatim', () => {
+    // The `new HarnessError(String(value), code, { cause: value })` normalization
+    // pattern repeats its cause; rendering it twice would only add noise.
+    const wrapped = new HarnessError('boom', 'UNKNOWN', { cause: 'boom' })
+    expect(errorChain(wrapped)).toBe('boom')
+  })
+
   it('routes stream() to the registered adapter', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
diff --git a/packages/ui/stdio/README.md b/packages/ui/stdio/README.md
index eda7d00b8b..869dd7b4df 100644
--- a/packages/ui/stdio/README.md
+++ b/packages/ui/stdio/README.md
@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-stdio
 
-The terminal readline front door for DeepSeek Harness agents. It reads prompts from stdin, sends or steers them through `ctx.agents`, renders the durable `session/event` transcript to stdout, and answers `ctx.userInteraction` requests in the same terminal.
+The terminal readline front door for DeepSeek Harness agents. It reads prompts from stdin, sends or steers them through `ctx.agents`, renders the durable `session/event` transcript to stdout, and answers `ctx.userInteraction` requests in the same terminal. Failed turns render their durable `turn/end` reason — `[turn failed <code>]`, `[turn aborted]`, `[turn rejected]`, `[turn interrupted …]`, or the output-token-limit notice — so a provider or network failure is never silent; unknown merge-extended reason kinds fall through as ordinary turn ends.
 
 This package owns the terminal channel only. It injects `agents` and `userInteraction`, then drives an agent created or resumed by app or developer code. The agent spine, agent lifecycle, console logger, and model-facing [`ask_user_question`](../tool-ask-user/README.md) tool remain separate composition entries.
 
diff --git a/packages/ui/stdio/src/index.ts b/packages/ui/stdio/src/index.ts
index 6f73d948bf..4f7695d906 100644
--- a/packages/ui/stdio/src/index.ts
+++ b/packages/ui/stdio/src/index.ts
@@ -15,6 +15,7 @@ import type { Readable, Writable } from 'node:stream'
 import type { Context } from 'cordis'
 import z from 'schemastery'
 import type { Agent } from '@deepseek-ai/dsh-agent'
+import { errorChain } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-agent-loop'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import {
@@ -62,15 +63,6 @@ function isTTYPair(input: Readable, output: Writable): boolean {
   return Boolean((input as { isTTY?: boolean }).isTTY && (output as { isTTY?: boolean }).isTTY)
 }
 
-/** Render an arbitrary failure without allowing hostile coercion to escape the UI boundary. */
-function renderThrown(value: unknown): string {
-  try {
-    return String(value)
-  } catch {
-    return '<unrenderable thrown value>'
-  }
-}
-
 interface PendingQuestion {
   request: AskUserQuestionRequest
   questionIndex: number
@@ -138,6 +130,21 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt
     } else if (event.type === 'turn/end') {
       if (inReasoning) output.write('\x1B[0m')
       inReasoning = false
+      // Failure reasons must reach the terminal: turn/end is the durable record
+      // of an in-turn failure, and without this line a failed turn renders as
+      // silence. Merge-extensible unknown kinds fall through as ordinary ends.
+      const { reason } = event.data
+      if (reason.kind === 'error') {
+        output.write(`\n[turn failed${reason.code === undefined ? '' : ` ${reason.code}`}] ${reason.message}`)
+      } else if (reason.kind === 'aborted') {
+        output.write(`\n[turn aborted]${reason.reason === undefined ? '' : ` ${reason.reason}`}`)
+      } else if (reason.kind === 'rejected') {
+        output.write(`\n[turn rejected] ${reason.reason}`)
+      } else if (reason.kind === 'max-tokens') {
+        output.write('\n[turn hit the output-token limit]')
+      } else if (reason.kind === 'interrupted') {
+        output.write('\n[turn interrupted by a previous process exit]')
+      }
       output.write('\n> ')
     } else if (event.type === 'tool/call') {
       const { name: toolName, arguments: args } = event.data
@@ -235,7 +242,7 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt
       queuedInput.length = 0
       submittedWork = sawRunning
       if (dropped > 0) {
-        ctx.logger.error(`ui-stdio: main agent failed to start; dropped queued stdin (${dropped} line(s)): ${renderThrown(error)}`)
+        ctx.logger.error(`ui-stdio: main agent failed to start; dropped queued stdin (${dropped} line(s)): ${errorChain(error)}`)
       }
       maybeExit()
     })
@@ -395,7 +402,7 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt
       const text = line.trim()
       if (!text) return
       if (failedStartup !== undefined) {
-        ctx.logger.error(`ui-stdio: main agent failed to start; dropped queued stdin (1 line(s)): ${renderThrown(failedStartup.error)}`)
+        ctx.logger.error(`ui-stdio: main agent failed to start; dropped queued stdin (1 line(s)): ${errorChain(failedStartup.error)}`)
         return
       }
       const agent = target
diff --git a/packages/ui/stdio/tests/stdio.spec.ts b/packages/ui/stdio/tests/stdio.spec.ts
index a3069462ff..10fa956f25 100644
--- a/packages/ui/stdio/tests/stdio.spec.ts
+++ b/packages/ui/stdio/tests/stdio.spec.ts
@@ -227,6 +227,41 @@ describe('createStdioChat rendering', () => {
     expect(out.text()).toContain('\n> ')
   })
 
+  it('renders failure turn/end reasons so a failed turn is not silent', async () => {
+    const { ctx, out } = await setup()
+    const session = makeSession('main')
+    ctx.emit('session/event', session, {
+      type: 'turn/end', seq: 1, time: 0,
+      data: { turn: 1, reason: { kind: 'error', step: 1, message: 'fetch failed: connect ECONNREFUSED', code: 'NETWORK' } },
+    } as SessionEvent)
+    expect(out.text()).toContain('[turn failed NETWORK] fetch failed: connect ECONNREFUSED')
+    ctx.emit('session/event', session, {
+      type: 'turn/end', seq: 2, time: 0,
+      data: { turn: 2, reason: { kind: 'error', step: 1, message: 'uncoded failure' } },
+    } as SessionEvent)
+    expect(out.text()).toContain('[turn failed] uncoded failure')
+    ctx.emit('session/event', session, {
+      type: 'turn/end', seq: 3, time: 0, data: { turn: 3, reason: { kind: 'aborted', reason: 'user cancelled' } },
+    } as SessionEvent)
+    expect(out.text()).toContain('[turn aborted] user cancelled')
+    ctx.emit('session/event', session, {
+      type: 'turn/end', seq: 4, time: 0, data: { turn: 4, reason: { kind: 'aborted' } },
+    } as SessionEvent)
+    expect(out.text()).toContain('[turn aborted]\n> ')
+    ctx.emit('session/event', session, {
+      type: 'turn/end', seq: 5, time: 0, data: { turn: 5, reason: { kind: 'rejected', reason: 'policy veto' } },
+    } as SessionEvent)
+    expect(out.text()).toContain('[turn rejected] policy veto')
+    ctx.emit('session/event', session, {
+      type: 'turn/end', seq: 6, time: 0, data: { turn: 6, reason: { kind: 'max-tokens' } },
+    } as SessionEvent)
+    expect(out.text()).toContain('[turn hit the output-token limit]')
+    ctx.emit('session/event', session, {
+      type: 'turn/end', seq: 7, time: 0, data: { turn: 7, reason: { kind: 'interrupted' } },
+    } as SessionEvent)
+    expect(out.text()).toContain('[turn interrupted by a previous process exit]')
+  })
+
   it('uses the session id as the label for a non-target session', async () => {
     const { ctx, out } = await setup()
     // No target exists, so the event's durable identity is the label.
@@ -814,7 +849,7 @@ describe('createStdioChat input', () => {
     await new Promise(r => setImmediate(r))
 
     expect(error).toHaveBeenCalledWith(
-      'ui-stdio: main agent failed to start; dropped queued stdin (1 line(s)): <unrenderable thrown value>',
+      'ui-stdio: main agent failed to start; dropped queued stdin (1 line(s)): <unrenderable value>',
     )
   })
 
@@ -902,7 +937,7 @@ describe('createStdioChat EOF exit', () => {
     await flushExit()
 
     expect(error).toHaveBeenCalledWith(
-      'ui-stdio: main agent failed to start; dropped queued stdin (1 line(s)): <unrenderable thrown value>',
+      'ui-stdio: main agent failed to start; dropped queued stdin (1 line(s)): <unrenderable value>',
     )
     expect(exit).toHaveBeenCalledWith(0)
   })
diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts
index 1c3fc1315c..ae0c480dde 100644
--- a/packages/ui/tui/src/index.ts
+++ b/packages/ui/tui/src/index.ts
@@ -35,6 +35,7 @@ import type { Context } from 'cordis'
 import z from 'schemastery'
 import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
 import type {} from '@deepseek-ai/dsh-agent-loop'
+import { errorChain } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm'
 import { SessionId, type Session, type SessionEvent, type TodoItem } from '@deepseek-ai/dsh-session'
 import type {
@@ -191,15 +192,6 @@ function displayText(text: string): string {
     `\\x${control.charCodeAt(0).toString(16).padStart(2, '0')}`)
 }
 
-/** Render an arbitrary failure without allowing hostile coercion to escape the UI boundary. */
-function renderThrown(value: unknown): string {
-  try {
-    return String(value)
-  } catch {
-    return '<unrenderable thrown value>'
-  }
-}
-
 /**
  * Theme-agnostic palette built from the standard 16-color ANSI set plus SGR
  * attributes, which every terminal remaps to its active color scheme. Body
@@ -1263,7 +1255,9 @@ export function createTuiChat(
   const disposeError = ctx.on('agent/error', (subject, turn, step, error) => {
     if (subject !== agent) return
     liveErrors.add(`${turn}:${step}`)
-    appendNotice(error.message, 'error')
+    // Full cause chain: wrapper messages like `fetch failed` carry the
+    // actionable transport detail on `cause`.
+    appendNotice(errorChain(error), 'error')
   })
   const disposeAgent = ctx.on('agent/disposed', (subject) => {
     if (subject !== agent) return
@@ -1330,7 +1324,7 @@ export function mountTui(ctx: Context, config: Config, runtime: TuiRuntime): voi
     if (settled || failedSessionId !== sessionId) return
     settled = true
     stopWaiting()
-    runtime.terminal.write(displayText(`ui-tui: session "${sessionId}" failed to start: ${renderThrown(error)}\n`))
+    runtime.terminal.write(displayText(`ui-tui: session "${sessionId}" failed to start: ${errorChain(error)}\n`))
     runtime.exit(1)
   }
 
diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts
index 27200e0fa9..8e0df2cc75 100644
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -864,7 +864,7 @@ describe('terminal mounting', () => {
     expect(terminal.output).toBe('')
     expect(exit).not.toHaveBeenCalled()
     ctx.emit('agent-loop/config-start-failed', SessionId('main-session'), new Error('resume \u001b]2;failure-controlled\u0007'))
-    expect(terminal.output).toBe('ui-tui: session "main-session" failed to start: Error: resume \\x1b]2;failure-controlled\\x07\n')
+    expect(terminal.output).toBe('ui-tui: session "main-session" failed to start: resume \\x1b]2;failure-controlled\\x07\n')
     expect(exit).toHaveBeenCalledWith(1)
 
     const session = ctx.sessions.create(SessionId('main-session'))
@@ -892,7 +892,7 @@ describe('terminal mounting', () => {
     })
 
     expect(terminal.started).toBe(0)
-    expect(terminal.output).toBe('ui-tui: session "main-session" failed to start: <unrenderable thrown value>\n')
+    expect(terminal.output).toBe('ui-tui: session "main-session" failed to start: <unrenderable value>\n')
     expect(exit).toHaveBeenCalledWith(1)
     await ctx.fiber.dispose()
   })
diff --git a/website/zh-CN/api/harness/agent-loop.md b/website/zh-CN/api/harness/agent-loop.md
index 9a43a1ba14..750f6a49dc 100644
--- a/website/zh-CN/api/harness/agent-loop.md
+++ b/website/zh-CN/api/harness/agent-loop.md
@@ -6,7 +6,7 @@
 
 Concrete agent factory and driver service.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L407)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L398)
 
 ### ctx.agentLoop.create(id, options?, meta?)
 
@@ -31,7 +31,7 @@ Create an agent and session under one caller-supplied identity, owned by the acc
 
 **Returns** the published running agent.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L542)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L533)
 
 ### ctx.agentLoop.createAgent(ownerCtx, options)
 
@@ -52,7 +52,7 @@ Create an owned agent on a caller-supplied session id.
 
 **Returns** the published handle.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L564)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L555)
 
 ### ctx.agentLoop.resume(ownerCtx, options)
 
@@ -73,4 +73,4 @@ Resume an owned agent from the configured persistence service.
 
 **Returns** the published handle.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L596)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L587)
diff --git a/website/zh-CN/api/harness/events.md b/website/zh-CN/api/harness/events.md
index a9ce1990c0..30298bdc97 100644
--- a/website/zh-CN/api/harness/events.md
+++ b/website/zh-CN/api/harness/events.md
@@ -423,7 +423,7 @@ A declarative agent entry failed before it could publish a live agent. Consumers
 - `sessionId` — exact shared agent/session identity that failed startup.
 - `error` — persistence, setup, or publication failure.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L362)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent-loop/src/index.ts#L353)
 
 ## approval/*
 

From 3a1b500cefdcdcac688110b2ab218b0ed3c7dc21 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Mon, 20 Jul 2026 14:48:05 +0800
Subject: [PATCH 46/74] fix(tui): detect terminal color scheme and apply
 light-optimised palette

---
 packages/ui/tui/src/index.ts | 37 +++++++++++++++++++++++++++++++++---
 1 file changed, 34 insertions(+), 3 deletions(-)

diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts
index ae0c480dde..41abe9c7d8 100644
--- a/packages/ui/tui/src/index.ts
+++ b/packages/ui/tui/src/index.ts
@@ -30,6 +30,7 @@ import {
   type OverlayHandle,
   type SelectListTheme,
   type Terminal,
+  type TerminalColorScheme,
 } from '@earendil-works/pi-tui'
 import type { Context } from 'cordis'
 import z from 'schemastery'
@@ -199,17 +200,21 @@ function displayText(text: string): string {
  * backgrounds alike; grouping uses foreground-only gutter bars and reverse
  * video rather than fixed background fills.
  */
-function createPalette(enabled: boolean): Palette {
+function createPalette(enabled: boolean, scheme: TerminalColorScheme = 'dark'): Palette {
   return {
     accent: ansi('94', '39', enabled),
     accent2: ansi('95', '39', enabled),
     text: text => text,
     muted: ansi('90', '39', enabled),
-    dim: ansi('2', '22', enabled),
+    // SGR 2 (dim) lightens text on a light background — substitute ANSI 90
+    // (bright black / gray) which renders as a readable muted tone on any scheme.
+    dim: scheme === 'light' ? ansi('90', '39', enabled) : ansi('2', '22', enabled),
     success: ansi('32', '39', enabled),
     warning: ansi('33', '39', enabled),
     error: ansi('31', '39', enabled),
-    code: ansi('36', '39', enabled),
+    // ANSI 36 (cyan) is difficult to read on a light background — use
+    // ANSI 34 (blue) which is legible on both light and dark schemes.
+    code: scheme === 'light' ? ansi('34', '39', enabled) : ansi('36', '39', enabled),
     added: ansi('32', '39', enabled),
     removed: ansi('31', '39', enabled),
     bold: ansi('1', '22', enabled),
@@ -1123,6 +1128,31 @@ export function createTuiChat(
     { name: 'exit', description: 'Exit after the active turn reaches idle' },
   ], agent.session.header.cwd ?? process.cwd()))
 
+  /** Swap the palette and all derived themes for the given terminal color scheme. */
+  const applyColorScheme = (scheme: TerminalColorScheme): void => {
+    if (scheme === currentScheme) return
+    currentScheme = scheme
+    Object.assign(palette, createPalette(resolved.color, scheme))
+    Object.assign(mdTheme, markdownTheme(palette))
+    editor.borderColor = text => palette.dim(text)
+    rebuildTranscript(false)
+    setStatus(agent.status)
+    requestRender()
+  }
+  let currentScheme: TerminalColorScheme = 'dark'
+
+  // Detect the terminal's color scheme via device-status report. Most terminals
+  // do not respond, so the promise settles with `undefined` and we keep the
+  // dark-optimised palette.
+  ui.queryTerminalColorScheme({ timeoutMs: 2000 }).then((scheme) => {
+    if (scheme !== undefined) applyColorScheme(scheme)
+  }).catch(() => {
+    // Timeout or query failure — keep dark default.
+  })
+
+  // Live-update when the user switches their terminal theme behind us.
+  const disposeSchemeListener = ui.onTerminalColorSchemeChange(applyColorScheme)
+
   const toggleTools = (): void => {
     toolsExpanded = !toolsExpanded
     for (const card of allToolCards) card.setExpanded(toolsExpanded)
@@ -1271,6 +1301,7 @@ export function createTuiChat(
     disposeStatus()
     disposeError()
     disposeAgent()
+    disposeSchemeListener()
   }
 
   rebuildTranscript(true)

From a661f5c8f329c022e5510dc5f8ba6467d5a935ca Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Mon, 20 Jul 2026 14:54:09 +0800
Subject: [PATCH 47/74] test(tui): prove color scheme detection switches
 palette ANSI codes

---
 packages/ui/tui/tests/tui.spec.ts | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts
index 8e0df2cc75..51a3ee4ec0 100644
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -936,4 +936,31 @@ describe('terminal mounting', () => {
     expect(() => createTuiChat(ctx, { sessionId: 'missing' }, runtime)).toThrow('is not running')
     await ctx.fiber.dispose()
   })
+
+  it('detects a light terminal color scheme and switches from dark- to light-optimised ANSI codes', async () => {
+    const result = await setup({ config: { color: true } })
+    // Initial render uses dark-optimised palette: SGR 2 (dim) for dim text.
+    expect(result.terminal.output).toContain('\x1b[2mdeepseek-v4-flash')
+
+    // Simulate the terminal responding with a light color scheme report
+    // (ESC [?997;2n = light, ESC [?997;1n = dark).
+    result.terminal.send('\x1b[?997;2n')
+    await tick()
+    await tick()
+
+    // After switching to light-optimised palette: palette.dim uses ANSI 90
+    // (gray) instead of SGR 2. The header now uses \x1b[90m for the detail
+    // line. The cumulative output still contains the initial SGR 2 render,
+    // so we assert that a LATER write (appended after the scheme switch)
+    // uses ANSI 90 for the same header text.
+    expect(result.terminal.output).toContain('\x1b[90mdeepseek-v4-flash')
+
+    // Switch back to dark scheme.
+    result.terminal.send('\x1b[?997;1n')
+    await tick()
+    await tick()
+    // After switching back, a new write uses SGR 2 for the header detail.
+    expect(result.terminal.output).toContain('\x1b[2mdeepseek-v4-flash')
+    await dispose(result)
+  })
 })

From 734bd40bb67de5663715dbe7b02f63079d1b7345 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Mon, 20 Jul 2026 19:03:15 +0800
Subject: [PATCH 48/74] docs: regenerate config catalog after stacking on #425

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

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index a4eedf25cc..e5ac98b5c8 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1302,7 +1302,7 @@ export interface TuiConfig {
 }
 ```
 
-Source: [`packages/ui/tui/src/index.ts:101`](../packages/ui/tui/src/index.ts)
+Source: [`packages/ui/tui/src/index.ts:102`](../packages/ui/tui/src/index.ts)
 
 ## `@deepseek-ai/dsh-user-approval`
 

From 37f2c15e6854135d2b17316aaa291b8e3c862b9c Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 20 Jul 2026 21:03:01 +0800
Subject: [PATCH 49/74] fix(fs-sandbox): recognize Windows path aliases

---
 ...26-07-14-cross-family-fs-sandbox.i18n.yaml |  4 +-
 .../2026-07-14-cross-family-fs-sandbox.md     |  6 +-
 .../2026-07-14-cross-family-fs-sandbox.zh.md  |  6 +-
 packages/fs/fs-sandbox/README.md              |  4 +-
 packages/fs/fs-sandbox/src/containment.ts     | 74 +++++++++++++++++++
 packages/fs/fs-sandbox/src/index.ts           | 18 ++---
 .../fs/fs-sandbox/tests/containment.spec.ts   | 56 ++++++++++++++
 .../fs/fs-sandbox/tests/fs-sandbox.spec.ts    | 13 ++--
 8 files changed, 155 insertions(+), 26 deletions(-)
 create mode 100644 packages/fs/fs-sandbox/src/containment.ts
 create mode 100644 packages/fs/fs-sandbox/tests/containment.spec.ts

diff --git a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml
index 8e44e3a6bc..41246ca3b3 100644
--- a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-14-cross-family-fs-sandbox.md: 9b6312e5994469606bd1645902fc798f70258580
-2026-07-14-cross-family-fs-sandbox.zh.md: d4816e03d94bdf12b2db875d71dccb7db3a2c0d7
+2026-07-14-cross-family-fs-sandbox.md: 0897695cc14b7573ebb53f3ffa6a460652882b37
+2026-07-14-cross-family-fs-sandbox.zh.md: 15de061a0d2b18392f839c927e9b0f5d0cacf28b
diff --git a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md
index 9b6312e599..0897695cc1 100644
--- a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md
+++ b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md
@@ -31,7 +31,7 @@ Three coordinated pieces, all composed from the leaf `cordis.yml`, none touching
 `packages/fs/fs-sandbox/` (`@deepseek-ai/dsh-fs-sandbox`) mirrors the `bash-local`/`bash-sandbox` split: `SandboxedFileSystem extends LocalFileSystem`, registered as `ctx.fs`, injecting `sandboxPolicy`. Reads (`resolve`/`stat`/`readText`/`streamText`/`listDir`) pass through untouched — every mode permits reading. The two mutations enforce by mode before delegating to the inherited atomic write:
 
 - `read-only` denies `writeText`/`editText` outright.
-- `workspace-write` fences the canonicalized target against the writable-root set — `writableRoots(policy)` in `dsh-sandbox`: the workspace root plus the platform temp areas (`/tmp`, `os.tmpdir()`), each realpathed — the SAME set the Seatbelt profile grants, so the fs fence is the fourth dialect of one mode meaning alongside the bwrap/Landlock/Seatbelt profiles, and "the write tool cannot write `/tmp` but bash can" asymmetries cannot arise. Containment is prefix-inclusion on real paths; the target is re-canonicalized (`resolve` realpaths the deepest existing ancestor) immediately before delegating, so an ancestor symlink swapped since the tool resolved it is caught.
+- `workspace-write` fences the canonicalized target against the writable-root set — `writableRoots(policy)` in `dsh-sandbox`: the workspace root plus the platform temp areas (`/tmp`, `os.tmpdir()`), each realpathed — the SAME set the Seatbelt profile grants, so the fs fence is the fourth dialect of one mode meaning alongside the bwrap/Landlock/Seatbelt profiles, and "the write tool cannot write `/tmp` but bash can" asymmetries cannot arise. Canonical spellings take a lexical containment fast path; when Windows exposes one directory through different casing or long-name/8.3 spellings, an ancestor walk compares filesystem identity rather than weakening the boundary to textual prefix guesses. The target is re-canonicalized (`resolve` realpaths the deepest existing ancestor) immediately before delegating, so an ancestor symlink swapped since the tool resolved it is caught.
 - `danger-full-access` delegates unfenced.
 
 A denial is the structured `FS_SANDBOX_DENIED` carrying the effective mode — distinct from `FS_PERMISSION_DENIED` (a host EACCES is the world refusing; this is policy refusing). No text inference: an in-process fence knows exactly what it denied. The per-call carrier is a trailing optional `sandboxMode` on `writeText`/`editText` (the filesystem twin of `BashExecRequest.sandboxMode`); the seam stays session-free (the caller stamps, exactly as `resolve` takes a cwd), and the bare local backend carries-and-ignores it. `FileSystem.sandboxMode` is the capability fact (`undefined` on the base and `fs-local`, the default on `SandboxedFileSystem`), so the tool layer advertises escalation from composition truth.
@@ -74,7 +74,7 @@ The sandbox Agent Note's original cross-family sketch put fs enforcement on the
 What shipped — the tiers in § Testing hold each:
 
 - Under `read-only`, `write`/`edit` return the `[sandbox: file access denied under read-only mode]` marker and the disk is untouched; `read`/`listDir` behave identically to `dsh-fs-local`.
-- Under `workspace-write`, mutations land under the workspace root and the temp areas and are denied outside; the containment matrix — `..` traversal, absolute paths outside, a pre-existing symlinked directory inside pointing out, and a new file created under such a symlink — denies every escape on real disks.
+- Under `workspace-write`, mutations land under the workspace root and the temp areas and are denied outside; the containment matrix — `..` traversal, absolute paths outside, a pre-existing symlinked directory inside pointing out, a new file created under such a symlink, and alias-equivalent root spellings — denies every escape while admitting the same directory identity on real disks.
 - A denied fs mutation retried once with `sandbox_permissions` + `justification` prompts through the composed approval chain; a grant runs exactly that call under the wider mode and the write lands; rejected/cancelled/unavailable each produce their verbatim fail-closed text and mutate nothing.
 - One `permission` preset switch governs both families: after a session switches modes, the next bash call and the next fs mutation both honor the new mode from the same `sandbox/mode` fold.
 - A direct `ctx.fs.writeText` with no per-call stamp is confined at the deployment default.
@@ -90,5 +90,5 @@ Costs and accepted limits:
 
 ## Testing
 
-- Unit: `dsh-sandbox` pins the escalation ladder, the marker builders, the argument-pairing validation, and `approveEscalation`'s ordered fail-closed sequence (non-widening, no-approval, no-agent, each outcome), plus `writableRoots`/`canonicalPath`. `dsh-sandbox-policy` pins the default accessors, the fold/setter, the load-time mode rejection, and HMR safety. `dsh-fs-sandbox` pins the per-mode fence and the containment matrix (inside, temp area, absolute-outside, `..`, symlinked-out directory, new file under one, path-equals-root, root-ending-in-separator) on a real filesystem, plus the per-call override and HMR safety. `dsh-tool-fs` pins advertisement gating, the mode stamp, the fold, denial-marker mapping, and the full escalation matrix (grant, reject, no-service, no-agent, pairing, non-confining guard). `dsh-tool-bash`, `dsh-bash-sandbox`, and `dsh-permission` migrate to the relocated policy/kit.
+- Unit: `dsh-sandbox` pins the escalation ladder, the marker builders, the argument-pairing validation, and `approveEscalation`'s ordered fail-closed sequence (non-widening, no-approval, no-agent, each outcome), plus `writableRoots`/`canonicalPath`. `dsh-sandbox-policy` pins the default accessors, the fold/setter, the load-time mode rejection, and HMR safety. `dsh-fs-sandbox` pins the per-mode fence and the containment matrix (inside, temp area, absolute-outside, `..`, symlinked-out directory, new file under one, path-equals-root, filesystem-root, and alias-equivalent spelling) on a real filesystem, plus the per-call override and HMR safety. `dsh-tool-fs` pins advertisement gating, the mode stamp, the fold, denial-marker mapping, and the full escalation matrix (grant, reject, no-service, no-agent, pairing, non-confining guard). `dsh-tool-bash`, `dsh-bash-sandbox`, and `dsh-permission` migrate to the relocated policy/kit.
 - Snapshot: the acp-agent example composes `dsh-sandbox-policy` + `dsh-fs-sandbox`; the pinned header carries the fs escalation fields and the `sandbox/mode` event name, re-recorded once.
diff --git a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md
index d4816e03d9..15de061a0d 100644
--- a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md
@@ -31,7 +31,7 @@ Status: implemented
 `packages/fs/fs-sandbox/`(`@deepseek-ai/dsh-fs-sandbox`)镜像 `bash-local`/`bash-sandbox` 的拆分:`SandboxedFileSystem extends LocalFileSystem`,注册为 `ctx.fs`,注入 `sandboxPolicy`。读取(`resolve`/`stat`/`readText`/`streamText`/`listDir`)原样透传——每种模式都允许读。两个变更操作在委托给继承来的原子写之前按模式执行:
 
 - `read-only` 直接拒绝 `writeText`/`editText`。
-- `workspace-write` 把规范化后的目标围栏于可写根集合——`dsh-sandbox` 中的 `writableRoots(policy)`:工作区根加上平台临时目录(`/tmp`、`os.tmpdir()`),各自 realpath——与 Seatbelt profile 授予的是同一个集合,所以 fs 围栏是这一个模式含义在 bwrap/Landlock/Seatbelt profile 之外的第四种方言,因此不会出现「write 工具不能写 `/tmp` 而 bash 能」的不对称。包含判定是对真实路径的前缀包含;目标在委托前被立即重新规范化(`resolve` 对最深的既有祖先做 realpath),因此自工具解析该目标以来被换出的祖先符号链接会被捕获。
+- `workspace-write` 把规范化后的目标围栏于可写根集合——`dsh-sandbox` 中的 `writableRoots(policy)`:工作区根加上平台临时目录(`/tmp`、`os.tmpdir()`),各自 realpath——与 Seatbelt profile 授予的是同一个集合,所以 fs 围栏是这一个模式含义在 bwrap/Landlock/Seatbelt profile 之外的第四种方言,因此不会出现「write 工具不能写 `/tmp` 而 bash 能」的不对称。规范化路径写法采用词法包含的快速路径；当 Windows 以大小写不同的路径、长文件名或 8.3 短文件名表示同一目录时，系统会逐级遍历祖先目录并比较文件系统身份，而不会把边界弱化为依据文本前缀猜测包含关系。目标在委托前被立即重新规范化(`resolve` 对最深的既有祖先做 realpath),因此自工具解析该目标以来被换出的祖先符号链接会被捕获。
 - `danger-full-access` 不加围栏地委托。
 
 拒绝是结构化的 `FS_SANDBOX_DENIED`,携带生效模式——区别于 `FS_PERMISSION_DENIED`(宿主 EACCES 是世界在拒绝;这里是策略在拒绝)。无文本推断:进程内围栏确切知道它拒绝了什么。per-call 载体是 `writeText`/`editText` 上一个末尾可选的 `sandboxMode`(文件系统侧对应 `BashExecRequest.sandboxMode`);该 seam 保持无会话依赖(由调用方盖章,正如 `resolve` 接收一个 cwd),而裸的本地后端携带并忽略它。`FileSystem.sandboxMode` 是能力事实(在基类与 `fs-local` 上为 `undefined`,在 `SandboxedFileSystem` 上为默认值),所以工具层按组合真相来宣告升级。
@@ -74,7 +74,7 @@ Status: implemented
 已交付的部分——§ Testing 的各层各自钉住:
 
 - 在 `read-only` 下,`write`/`edit` 返回 `[sandbox: file access denied under read-only mode]` 标记,磁盘不受触动;`read`/`listDir` 与 `dsh-fs-local` 行为一致。
-- 在 `workspace-write` 下,变更落在工作区根与临时目录下,其外被拒;包含矩阵——`..` 穿越、指向外部的绝对路径、一个既有的、指向外部的工作区内符号链接目录,以及在这样一个符号链接下新建的文件——在真实磁盘上拒绝每一种逃逸。
+- 在 `workspace-write` 下,变更落在工作区根与临时目录下,其外被拒;包含矩阵——`..` 穿越、指向外部的绝对路径、一个既有的、指向外部的工作区内符号链接目录、在这样一个符号链接下新建的文件,以及根路径的等价别名形式——在真实磁盘上拒绝每一种逃逸,同时允许文件系统认定为同一目录的路径。
 - 一个被拒的 fs 变更,携带 `sandbox_permissions` + `justification` 重试一次,会经组合的审批链提示;一次授权让恰好那一次调用在更宽的模式下运行且写入落盘;rejected/cancelled/unavailable 各自产生其逐字的 fail-closed 文案且不做任何变更。
 - 一次 `permission` 预设切换同时管辖两个家族:会话切换模式后,下一次 bash 调用与下一次 fs 变更都从同一个 `sandbox/mode` 折叠遵循新模式。
 - 一次无 per-call 盖章的直连 `ctx.fs.writeText` 会被围栏于部署默认值。
@@ -90,5 +90,5 @@ Status: implemented
 
 ## Testing
 
-- 单元:`dsh-sandbox` 钉住升级阶梯、标记构造器、参数配对校验,以及 `approveEscalation` 的有序 fail-closed 序列(非加宽、无 approval、无 agent、各结果),外加 `writableRoots`/`canonicalPath`。`dsh-sandbox-policy` 钉住默认访问器、折叠/setter、加载期模式拒绝,以及 HMR 安全。`dsh-fs-sandbox` 在真实文件系统上钉住 per-mode 围栏与包含矩阵(内部、临时目录、绝对路径-外部、`..`、指向外部的符号链接目录、其下的新建文件、路径等于根、以分隔符结尾的根),外加 per-call 覆盖与 HMR 安全。`dsh-tool-fs` 钉住宣告门控、模式盖章、折叠、拒绝标记映射,以及完整的升级矩阵(授权、拒绝、无服务、无 agent、配对、非受限守卫)。`dsh-tool-bash`、`dsh-bash-sandbox` 与 `dsh-permission` 迁移到迁移后的策略/工具集。
+- 单元:`dsh-sandbox` 钉住升级阶梯、标记构造器、参数配对校验,以及 `approveEscalation` 的有序 fail-closed 序列(非加宽、无 approval、无 agent、各结果),外加 `writableRoots`/`canonicalPath`。`dsh-sandbox-policy` 钉住默认访问器、折叠/setter、加载期模式拒绝,以及 HMR 安全。`dsh-fs-sandbox` 在真实文件系统上钉住 per-mode 围栏与包含矩阵(内部、临时目录、绝对路径-外部、`..`、指向外部的符号链接目录、其下的新建文件、路径等于根、文件系统根、等价别名形式),外加 per-call 覆盖与 HMR 安全。`dsh-tool-fs` 钉住宣告门控、模式盖章、折叠、拒绝标记映射,以及完整的升级矩阵(授权、拒绝、无服务、无 agent、配对、非受限守卫)。`dsh-tool-bash`、`dsh-bash-sandbox` 与 `dsh-permission` 迁移到迁移后的策略/工具集。
 - 快照:acp-agent 示例组合 `dsh-sandbox-policy` + `dsh-fs-sandbox`;被钉住的 header 携带 fs 升级字段与 `sandbox/mode` 事件名,一次性重录。
diff --git a/packages/fs/fs-sandbox/README.md b/packages/fs/fs-sandbox/README.md
index 685ab838c8..c7043e2e70 100644
--- a/packages/fs/fs-sandbox/README.md
+++ b/packages/fs/fs-sandbox/README.md
@@ -9,14 +9,14 @@ Loading it INSTEAD OF `dsh-fs-local`, together with a [`ctx.sandboxPolicy`](../.
 The per-call mode is the tool-stamped effective mode (session override or escalation grant), falling back to the deployment default:
 
 - `read-only` — denies every mutation with the structured `FS_SANDBOX_DENIED`.
-- `workspace-write` — allows a mutation only when the target canonicalizes under a writable root: the workspace root plus the platform temp areas (`/tmp`, `os.tmpdir()`), the SAME set the Seatbelt profile grants, derived from the one [`writableRoots`](../../sandbox/README.md) function so the fs fence and the bash runner cannot drift. The target is re-canonicalized immediately before delegating, so an ancestor symlink swapped since the tool resolved it is caught.
+- `workspace-write` — allows a mutation only when the target canonicalizes under a writable root: the workspace root plus the platform temp areas (`/tmp`, `os.tmpdir()`), the SAME set the Seatbelt profile grants, derived from the one [`writableRoots`](../../sandbox/README.md) function so the fs fence and the bash runner cannot drift. Canonical spellings use a lexical fast path; an identity-based ancestor fallback recognizes alias-equivalent roots such as Windows long names and 8.3 names without treating unrelated prefixes as contained. The target is re-canonicalized immediately before delegating, so an ancestor symlink swapped since the tool resolved it is caught.
 - `danger-full-access` — delegates unfenced.
 
 ## Threat model: a policy fence, not a kernel boundary
 
 The fence is a check in TRUSTED code over a MODEL-CONTROLLED path — the operations are the seam's own (open, rename), only the target path is untrusted, so canonicalize-then-contain is the complete answer to this surface. This mirrors the `code-runtime` stance: containment, not a security boundary. Kernel-grade isolation of untrusted CODE stays `ctx.bash`'s job ([`dsh-bash-sandbox`](../../bash/bash-sandbox/README.md)). The residual TOCTOU (an ancestor symlink swapped between the containment re-check and the syscall) is narrowed by re-canonicalizing immediately before the write and is accepted for this threat model; a kernel-tight boundary needs `openat2`-class primitives not worth their portability cost here.
 
-A denial is a structured `FsError` (`FS_SANDBOX_DENIED`, carrying the effective mode) — no stderr text inference (unlike bash's kernel denials), because an in-process fence knows exactly what it refused. The model-facing `[sandbox: file access denied under <mode> mode]` marker and the one-approved-wider retry live in the tool layer (`dsh-tool-fs`), exactly as bash's do. See [the cross-family fs sandbox RFC](../../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md).
+A denial is a structured `FsError` (`FS_SANDBOX_DENIED`, carrying the effective mode) — no stderr text inference (unlike bash's kernel denials), because an in-process fence knows exactly what it refused. The model-facing `[sandbox: file access denied under <mode> mode]` marker and the one-approved-wider retry live in the tool layer (`dsh-tool-fs`), exactly as bash's do. See [the cross-family fs sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md).
 
 ## Model Experience
 
diff --git a/packages/fs/fs-sandbox/src/containment.ts b/packages/fs/fs-sandbox/src/containment.ts
new file mode 100644
index 0000000000..782ceb151d
--- /dev/null
+++ b/packages/fs/fs-sandbox/src/containment.ts
@@ -0,0 +1,74 @@
+/**
+ * Path-containment mechanics for the filesystem sandbox. Canonical spellings
+ * take the fast lexical path; filesystem identity supplies the conservative
+ * fallback for alias-equivalent roots such as Windows 8.3 names and casing.
+ * @module @deepseek-ai/dsh-fs-sandbox/containment
+ */
+
+import type { BigIntStats } from 'node:fs'
+import { stat } from 'node:fs/promises'
+import { dirname, sep } from 'node:path'
+
+function isMissing(error: unknown): boolean {
+  const code = (error as NodeJS.ErrnoException).code
+  return code === 'ENOENT' || code === 'ENOTDIR'
+}
+
+function comparablePath(path: string, caseSensitive: boolean): string {
+  return caseSensitive ? path : path.toLowerCase()
+}
+
+function isLexicallyUnder(path: string, root: string, caseSensitive: boolean): boolean {
+  const comparableTarget = comparablePath(path, caseSensitive)
+  const comparableRoot = comparablePath(root, caseSensitive)
+  if (comparableTarget === comparableRoot) return true
+  const prefix = comparableRoot.endsWith(sep) ? comparableRoot : comparableRoot + sep
+  return comparableTarget.startsWith(prefix)
+}
+
+async function statIfPresent(path: string): Promise<BigIntStats | undefined> {
+  try {
+    return await stat(path, { bigint: true })
+  } catch (error: unknown) {
+    /* v8 ignore else -- a non-missing stat failure requires a host permission or I/O fault after resolve reached this ancestor. */
+    if (isMissing(error)) return undefined
+    /* v8 ignore next -- requires a host permission or I/O fault after resolve already reached this ancestor. */
+    throw error
+  }
+}
+
+function sameIdentity(left: BigIntStats, right: BigIntStats): boolean {
+  return left.dev === right.dev && left.ino === right.ino
+}
+
+/**
+ * Determine whether a canonical target is a writable root or lies beneath it.
+ * The lexical fast path handles normal canonical spellings. When spellings
+ * differ, walk the target's existing ancestors and compare filesystem identity
+ * with the root; this recognizes Windows long-name/8.3 aliases and casing
+ * without weakening containment to a textual approximation.
+ * @param path - canonical target key, which may end in a missing suffix.
+ * @param root - canonical writable root.
+ * @param caseSensitive - whether lexical comparison preserves case; defaults
+ *   to the host filesystem convention used by supported platforms.
+ * @returns whether the target is the root or a descendant of it.
+ */
+export async function isPathUnder(
+  path: string,
+  root: string,
+  caseSensitive = process.platform !== 'win32',
+): Promise<boolean> {
+  if (isLexicallyUnder(path, root, caseSensitive)) return true
+
+  const rootInfo = await statIfPresent(root)
+  if (!rootInfo) return false
+
+  let ancestor = path
+  while (true) {
+    const ancestorInfo = await statIfPresent(ancestor)
+    if (ancestorInfo && sameIdentity(ancestorInfo, rootInfo)) return true
+    const parent = dirname(ancestor)
+    if (parent === ancestor) return false
+    ancestor = parent
+  }
+}
diff --git a/packages/fs/fs-sandbox/src/index.ts b/packages/fs/fs-sandbox/src/index.ts
index 314778968e..5268412955 100644
--- a/packages/fs/fs-sandbox/src/index.ts
+++ b/packages/fs/fs-sandbox/src/index.ts
@@ -30,7 +30,6 @@
  * @module @deepseek-ai/dsh-fs-sandbox
  */
 
-import { sep } from 'node:path'
 import { Context } from 'cordis'
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
 import type { Config as LocalConfig } from '@deepseek-ai/dsh-fs-local'
@@ -39,6 +38,7 @@ import type { FsEditOutcome, FsEditRequest, FsTarget, FsVersion, FsWriteIntent,
 import { writableRoots } from '@deepseek-ai/dsh-sandbox'
 import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import type {} from '@deepseek-ai/dsh-sandbox-policy'
+import { isPathUnder } from './containment.ts'
 
 /**
  * Plugin config: the local backend's knobs, verbatim (only `cwd`, the resolve
@@ -48,13 +48,6 @@ import type {} from '@deepseek-ai/dsh-sandbox-policy'
  */
 export type Config = LocalConfig
 
-/** Whether `path` is `root` itself or lies beneath it (both already canonical). */
-function isUnder(path: string, root: string): boolean {
-  if (path === root) return true
-  const prefix = root.endsWith(sep) ? root : root + sep
-  return path.startsWith(prefix)
-}
-
 /**
  * Sandbox-enforcing filesystem backend. Registers as `ctx.fs` (loading it
  * INSTEAD OF `dsh-fs-local`, together with a `ctx.sandboxPolicy`, is the whole
@@ -147,7 +140,14 @@ export class SandboxedFileSystem extends LocalFileSystem {
     // symlink ancestor swapped since the tool resolved this target), and the
     // mutation delegates with THIS fresh target — never the stale one.
     const fresh = await this.resolve(target.displayPath)
-    if (!this.writableRoots.some(root => isUnder(fresh.targetKey, root))) {
+    let contained = false
+    for (const root of this.writableRoots) {
+      if (await isPathUnder(fresh.targetKey, root)) {
+        contained = true
+        break
+      }
+    }
+    if (!contained) {
       throw new FsError(`cannot write "${target.displayPath}": file access denied under workspace-write mode`, 'FS_SANDBOX_DENIED')
     }
     return fresh
diff --git a/packages/fs/fs-sandbox/tests/containment.spec.ts b/packages/fs/fs-sandbox/tests/containment.spec.ts
new file mode 100644
index 0000000000..30821cc826
--- /dev/null
+++ b/packages/fs/fs-sandbox/tests/containment.spec.ts
@@ -0,0 +1,56 @@
+/**
+ * Containment tests for lexical canonical paths and filesystem-identity aliases.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { mkdir, mkdtemp, realpath, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, parse } from 'node:path'
+import { isPathUnder } from '../src/containment.ts'
+
+let base: string
+
+beforeEach(async () => {
+  base = await mkdtemp(join(tmpdir(), 'dsh-fssbx-containment-'))
+})
+
+afterEach(async () => {
+  await rm(base, { recursive: true, force: true })
+})
+
+describe('filesystem sandbox containment', () => {
+  it('accepts equal paths, descendants, and a filesystem-root boundary', async () => {
+    expect(await isPathUnder(base, base)).toBe(true)
+    expect(await isPathUnder(join(base, 'child'), base)).toBe(true)
+    expect(await isPathUnder(base, parse(base).root)).toBe(true)
+  })
+
+  it('uses case-insensitive lexical comparison for Windows-style containment', async () => {
+    expect(await isPathUnder(join(base.toUpperCase(), 'child'), base.toLowerCase(), false)).toBe(true)
+  })
+
+  it('recognizes an alias-equivalent root by filesystem identity for a missing target', async () => {
+    const realRoot = join(base, 'real')
+    const aliasRoot = join(base, 'alias')
+    await mkdir(realRoot)
+    await symlink(realRoot, aliasRoot)
+    expect(await isPathUnder(join(await realpath(realRoot), 'missing', 'file.txt'), aliasRoot)).toBe(true)
+  })
+
+  it('denies unrelated and missing roots', async () => {
+    const allowed = join(base, 'allowed')
+    const outside = join(base, 'outside')
+    await mkdir(allowed)
+    await mkdir(outside)
+    expect(await isPathUnder(join(outside, 'file.txt'), allowed)).toBe(false)
+    expect(await isPathUnder(join(outside, 'file.txt'), join(base, 'missing-root'))).toBe(false)
+  })
+
+  it('treats a regular-file path segment as a missing target, not containment', async () => {
+    const allowed = join(base, 'allowed')
+    const blocker = join(base, 'blocker')
+    await mkdir(allowed)
+    await writeFile(blocker, 'not a directory')
+    expect(await isPathUnder(join(blocker, 'child.txt'), allowed)).toBe(false)
+  })
+})
diff --git a/packages/fs/fs-sandbox/tests/fs-sandbox.spec.ts b/packages/fs/fs-sandbox/tests/fs-sandbox.spec.ts
index 12f0abb0df..65472f2ece 100644
--- a/packages/fs/fs-sandbox/tests/fs-sandbox.spec.ts
+++ b/packages/fs/fs-sandbox/tests/fs-sandbox.spec.ts
@@ -12,7 +12,7 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { homedir, tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { join, parse } from 'node:path'
 import { Context } from 'cordis'
 import { FsError, FsTargetKey } from '@deepseek-ai/dsh-fs'
 import type { FsTarget } from '@deepseek-ai/dsh-fs'
@@ -167,16 +167,15 @@ describe('workspace-write containment', () => {
 })
 
 describe('workspace-write with the filesystem root as the workspace (a root ending in the path separator)', () => {
-  it('grants writes anywhere: containment against `/` allows any absolute path', async () => {
-    // A degenerate but valid config — workspaceRoot '/'. It exercises isUnder's
-    // separator-suffixed-root branch: `/` already ends in the separator, so the
-    // prefix stays `/` and every absolute path is contained.
+  it('grants writes anywhere on that volume', async () => {
+    // A degenerate but valid config: the filesystem root containing the target.
+    // It exercises the separator-suffixed-root branch on POSIX and Windows.
     const rootCtx = new Context()
-    await rootCtx.plugin(SandboxPolicyService, { mode: 'workspace-write', workspaceRoot: '/' })
+    await rootCtx.plugin(SandboxPolicyService, { mode: 'workspace-write', workspaceRoot: parse(base).root })
     const rootFiber = await rootCtx.plugin(SandboxedFileSystem, { cwd: workspace })
     const rootFs = rootCtx.fs as SandboxedFileSystem
     try {
-      const path = join(base, 'anywhere.txt') // under HOME, outside /tmp — allowed only via the `/` root
+      const path = join(base, 'anywhere.txt') // under HOME, outside temp — allowed only via the filesystem root
       await rootFs.writeText(await rootFs.resolve(path), 'anywhere')
       expect(await readFile(path, 'utf8')).toBe('anywhere')
     } finally {

From 23379de6298c66b771a2d69332f534803ad9e133 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 20 Jul 2026 21:10:53 +0800
Subject: [PATCH 50/74] docs: retire removed stdio paths

---
 .../simplification/2026-07-04-fold-stdio-ui-helper.md           | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.md b/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.md
index c44201b4e6..5ed4150883 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-fold-stdio-ui-helper.md
@@ -12,7 +12,7 @@ The boundary bought package metadata, workspace and tsconfig references, module-
 
 ## Decision
 
-The helper lives in `@deepseek-ai/dsh-stdio` as the terminal-channel plugin (`packages/ui/stdio/src/index.ts`): `createStdioChat`, its `StdioRuntime` test seam, and its unit tests (`packages/ui/stdio/tests/stdio.spec.ts`, `readline.spec.ts`) moved with it, so EOF handling, rendering, disposal, and piped-vs-TTY behavior stay unit-covered under the per-file coverage gate without hijacking process globals. The module keeps the named `name`/`inject`/`Config`/`apply` export shape — the contract the app's `ctx.plugin(uiStdio, …)` mount consumes — and the keyless Loader-path smokes in `examples/echo-agent` and `examples/repl-agent` keep proving the composed tree boots through the real Loader (the stdio package's plugin-shape unit suite pins the explicit `unwrapExports` assertion, since a bundle without `inject` would boot past a stray default rather than crash).
+At the time, the helper moved into `@deepseek-ai/dsh-stdio` as its terminal-channel plugin: `createStdioChat`, its `StdioRuntime` test seam, and its unit tests moved with it, so EOF handling, rendering, disposal, and piped-vs-TTY behavior stayed unit-covered under the per-file coverage gate without hijacking process globals. The module kept the named `name`/`inject`/`Config`/`apply` export shape — the contract the app's `ctx.plugin(uiStdio, …)` mount consumed — and the keyless Loader-path smokes in `examples/echo-agent` and `examples/repl-agent` kept proving the composed tree booted through the real Loader (the stdio package's plugin-shape unit suite pinned the explicit `unwrapExports` assertion, since a bundle without `inject` would boot past a stray default rather than crash).
 
 The `packages/support/ui-stdio` package is gone: manifest, tsconfig references, module-graph rows, and README rows deleted; the doc comments that named the package (the example e2e module docs, `packages/README.md`, the support and todo READMEs, [the ui group README](../../../../packages/ui/README.md)) describe the in-package module.
 

From 7239513b982201abc1641b3960ad41a85af51bf9 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 20 Jul 2026 21:20:55 +0800
Subject: [PATCH 51/74] test(fs-sandbox): keep Windows coverage portable

---
 packages/fs/fs-sandbox/src/containment.ts        | 4 +++-
 packages/fs/fs-sandbox/tests/containment.spec.ts | 1 +
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/fs/fs-sandbox/src/containment.ts b/packages/fs/fs-sandbox/src/containment.ts
index 782ceb151d..41b9bdd08a 100644
--- a/packages/fs/fs-sandbox/src/containment.ts
+++ b/packages/fs/fs-sandbox/src/containment.ts
@@ -9,9 +9,11 @@ import type { BigIntStats } from 'node:fs'
 import { stat } from 'node:fs/promises'
 import { dirname, sep } from 'node:path'
 
+const MISSING_CODES: ReadonlySet<NodeJS.ErrnoException['code']> = new Set(['ENOENT', 'ENOTDIR'])
+
 function isMissing(error: unknown): boolean {
   const code = (error as NodeJS.ErrnoException).code
-  return code === 'ENOENT' || code === 'ENOTDIR'
+  return MISSING_CODES.has(code)
 }
 
 function comparablePath(path: string, caseSensitive: boolean): string {
diff --git a/packages/fs/fs-sandbox/tests/containment.spec.ts b/packages/fs/fs-sandbox/tests/containment.spec.ts
index 30821cc826..35dc52029b 100644
--- a/packages/fs/fs-sandbox/tests/containment.spec.ts
+++ b/packages/fs/fs-sandbox/tests/containment.spec.ts
@@ -27,6 +27,7 @@ describe('filesystem sandbox containment', () => {
 
   it('uses case-insensitive lexical comparison for Windows-style containment', async () => {
     expect(await isPathUnder(join(base.toUpperCase(), 'child'), base.toLowerCase(), false)).toBe(true)
+    expect(await isPathUnder(join(base, 'case-sensitive-child'), base, true)).toBe(true)
   })
 
   it('recognizes an alias-equivalent root by filesystem identity for a missing target', async () => {

From f81d382230c77b9d5cd53a64d29f203972166d08 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Mon, 20 Jul 2026 22:06:13 +0800
Subject: [PATCH 52/74] fix(tui): make color-scheme detection fully covered and
 race-free
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The color-scheme detection block left packages/ui/tui/src/index.ts below
the 100% per-file coverage gate on three counts: the .then callback's
`scheme === undefined` branch was reachable only via the 2s query
timeout, the .catch only via a query-write failure, and the
`editor.borderColor` assignment inside applyColorScheme was dead code —
the next line's setStatus() immediately reassigns editor.borderColor.

Register the scheme listener before firing the startup query so the
query's own reply is delivered through the listener (the same path as
later theme switches), which removes the redundant .then re-application
and its uncoverable undefined branch, and closes the theoretical window
where a synchronous reply lands before the listener exists. Drop the
dead editor.borderColor line. Cover the rest: a same-scheme report
(early return) and a terminal that throws on the query write (the
swallowed .catch).
---
 packages/ui/tui/src/index.ts      | 21 ++++++++++-----------
 packages/ui/tui/tests/tui.spec.ts | 26 ++++++++++++++++++++++++++
 2 files changed, 36 insertions(+), 11 deletions(-)

diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts
index 9544d13cb0..17fef4c1e6 100644
--- a/packages/ui/tui/src/index.ts
+++ b/packages/ui/tui/src/index.ts
@@ -1134,25 +1134,24 @@ export function createTuiChat(
     currentScheme = scheme
     Object.assign(palette, createPalette(resolved.color, scheme))
     Object.assign(mdTheme, markdownTheme(palette))
-    editor.borderColor = text => palette.dim(text)
     rebuildTranscript(false)
     setStatus(agent.status)
     requestRender()
   }
   let currentScheme: TerminalColorScheme = 'dark'
 
-  // Detect the terminal's color scheme via device-status report. Most terminals
-  // do not respond, so the promise settles with `undefined` and we keep the
-  // dark-optimised palette.
-  ui.queryTerminalColorScheme({ timeoutMs: 2000 }).then((scheme) => {
-    if (scheme !== undefined) applyColorScheme(scheme)
-  }).catch(() => {
-    // Timeout or query failure — keep dark default.
-  })
-
-  // Live-update when the user switches their terminal theme behind us.
+  // Apply any color scheme the terminal reports. Registering before the query
+  // below means even a synchronous reply reaches `applyColorScheme`; in practice
+  // the startup query's reply is the only report, since dsh-tui leaves
+  // unsolicited color-scheme notifications disabled.
   const disposeSchemeListener = ui.onTerminalColorSchemeChange(applyColorScheme)
 
+  // Ask the terminal for its color scheme via device-status report; the reply,
+  // if any, arrives through the listener above. Most terminals do not respond,
+  // so we keep the dark-optimised palette. Swallow a query-write failure for the
+  // same reason.
+  ui.queryTerminalColorScheme({ timeoutMs: 2000 }).catch(() => {})
+
   const toggleTools = (): void => {
     toolsExpanded = !toolsExpanded
     for (const card of allToolCards) card.setExpanded(toolsExpanded)
diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts
index 51a3ee4ec0..3eacfa4fcf 100644
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -942,6 +942,13 @@ describe('terminal mounting', () => {
     // Initial render uses dark-optimised palette: SGR 2 (dim) for dim text.
     expect(result.terminal.output).toContain('\x1b[2mdeepseek-v4-flash')
 
+    // A report matching the current scheme is a no-op: no palette rebuild or
+    // re-render (ESC [?997;1n = dark, the startup default).
+    const beforeSameScheme = result.terminal.output.length
+    result.terminal.send('\x1b[?997;1n')
+    await tick()
+    expect(result.terminal.output.length).toBe(beforeSameScheme)
+
     // Simulate the terminal responding with a light color scheme report
     // (ESC [?997;2n = light, ESC [?997;1n = dark).
     result.terminal.send('\x1b[?997;2n')
@@ -963,4 +970,23 @@ describe('terminal mounting', () => {
     expect(result.terminal.output).toContain('\x1b[2mdeepseek-v4-flash')
     await dispose(result)
   })
+
+  it('keeps the dark palette when the terminal rejects the color-scheme query', async () => {
+    class QueryFailTerminal extends FakeTerminal {
+      override write(data: string): void {
+        // The device-status query is the only write that fails; the promise
+        // rejects and the swallowed `.catch` leaves the dark palette in place.
+        if (data === '\x1b[?996n') throw new Error('query write failed')
+        super.write(data)
+      }
+    }
+    const terminal = new QueryFailTerminal()
+    const result = await createTuiTestHarness(terminal, vi.fn(), {
+      config: { color: true },
+      cwd: process.cwd(),
+    })
+    await tick()
+    expect(terminal.output).toContain('\x1b[2mdeepseek-v4-flash')
+    await disposeTuiTestHarness(result)
+  })
 })

From 16163434233c3849b2bbd970ae92065dcf7be8d0 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 20 Jul 2026 22:50:19 +0800
Subject: [PATCH 53/74] test(tui): await validation render

---
 packages/ui/tui/tests/tui.spec.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts
index 5e38967f42..fa8fed6381 100644
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -819,8 +819,9 @@ describe('TUI user-interaction dialogs', () => {
     result.terminal.send('x')
     result.terminal.send(' ')
     result.terminal.send('\r')
-    await tick()
-    expect(result.terminal.output).toContain('Select at least one option')
+    await vi.waitFor(() => {
+      expect(result.terminal.output).toContain('Select at least one option')
+    })
     result.terminal.send('c')
     await tick()
     result.terminal.send('\x1b')

From a205ba4c29a514838638ff988a6b07fd6e4556c0 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Tue, 21 Jul 2026 09:42:12 +0800
Subject: [PATCH 54/74] test(sandbox): give the probe-timeout test headroom
 over vitest's default
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`bounds the default probes` runs a real launcher that sleeps 1s under the
5000ms default probe budget, all wrapped in vitest's 5000ms default test
timeout. The blocking spawnSync races that wrapper and tips over under the
load spike of a full parallel run — a pre-existing, load-sensitive flake
(noted as unrelated in this PR's original description). Give the test an
explicit 20s timeout so its bounded subprocess work never races the default.
---
 packages/sandbox/sandbox-local/tests/local.spec.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/sandbox/sandbox-local/tests/local.spec.ts b/packages/sandbox/sandbox-local/tests/local.spec.ts
index f9efbf992c..3ef5f7a586 100644
--- a/packages/sandbox/sandbox-local/tests/local.spec.ts
+++ b/packages/sandbox/sandbox-local/tests/local.spec.ts
@@ -339,7 +339,10 @@ describe('probeTimeoutMs config', () => {
       { platform: 'linux', probeBwrap: () => false, landlockLauncher: launcher },
     )
     expect(() => impatient.sandbox.confine(['true'], RO)).toThrow(expect.objectContaining({ code: SANDBOX_UNAVAILABLE }))
-  })
+    // The patient probe blocks on a real 1s launcher under the 5000ms default
+    // budget; an explicit timeout keeps the test clear of vitest's 5000ms
+    // default, which the blocking spawnSync would otherwise race under load.
+  }, 20_000)
 })
 
 describe('the default seatbelt probe (sandbox-exec contract)', () => {

From dd57d3009d12ac2272a6ca42973823f6fa23aedc Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Tue, 21 Jul 2026 10:07:03 +0800
Subject: [PATCH 55/74] test(sandbox): decouple the probe-timeout test from the
 racy default budget

The earlier fix only widened the vitest timeout, but the real race is the
patient probe reading the 1s launcher under the 5000ms *default* probe budget:
under a full parallel run spawnSync blocks the worker and fork/exec latency can
push the launcher's wall-clock past 5000ms, so the patient probe wrongly reads
unusable and the assertion fails. Give the patient probe a generous explicit
15000ms budget (still far below its 1s launcher runtime margin) so only the
250ms impatient probe races the launcher; keep a 30s vitest timeout above the
patient budget.
---
 .../sandbox/sandbox-local/tests/local.spec.ts   | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/packages/sandbox/sandbox-local/tests/local.spec.ts b/packages/sandbox/sandbox-local/tests/local.spec.ts
index 3ef5f7a586..f7cc952498 100644
--- a/packages/sandbox/sandbox-local/tests/local.spec.ts
+++ b/packages/sandbox/sandbox-local/tests/local.spec.ts
@@ -325,13 +325,19 @@ describe('probeTimeoutMs config', () => {
   })
 
   it('bounds the default probes: a launcher slower than the configured timeout reads as unusable', async () => {
-    // The same sleeping launcher passes under the default 5000ms budget and
-    // fails under a 250ms one — the config demonstrably reaches spawnSync.
+    // The same 1s launcher reads usable under a generous budget and unusable
+    // under a 250ms one — the config demonstrably reaches spawnSync. Both bounds
+    // keep a wide margin from the launcher's 1s runtime so a loaded host (where
+    // spawnSync blocks the worker and fork/exec latency inflates wall-clock)
+    // cannot flip either verdict; the vitest timeout clears the patient budget.
     const dir = mkdtempSync(join(tmpdir(), 'dsh-slow-landlock-'))
     const launcher = join(dir, 'landlock-run')
     writeFileSync(launcher, '#!/bin/sh\nsleep 1\necho "landlock: fully enforced"\nexit 0\n', { mode: 0o755 })
 
-    const patient = await setup({}, { platform: 'linux', probeBwrap: () => false, landlockLauncher: launcher })
+    const patient = await setup(
+      { probeTimeoutMs: 15_000 },
+      { platform: 'linux', probeBwrap: () => false, landlockLauncher: launcher },
+    )
     expect(patient.sandbox.confine(['true'], RO).enforcement).toBe('full')
 
     const impatient = await setup(
@@ -339,10 +345,7 @@ describe('probeTimeoutMs config', () => {
       { platform: 'linux', probeBwrap: () => false, landlockLauncher: launcher },
     )
     expect(() => impatient.sandbox.confine(['true'], RO)).toThrow(expect.objectContaining({ code: SANDBOX_UNAVAILABLE }))
-    // The patient probe blocks on a real 1s launcher under the 5000ms default
-    // budget; an explicit timeout keeps the test clear of vitest's 5000ms
-    // default, which the blocking spawnSync would otherwise race under load.
-  }, 20_000)
+  }, 30_000)
 })
 
 describe('the default seatbelt probe (sandbox-exec contract)', () => {

From 92180069ea29acc726baf882d506cefc26dd9bc0 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 21 Jul 2026 17:26:36 +0800
Subject: [PATCH 56/74] test(acp-snapshot): sync Windows goal command
 transcript

---
 .../tests/snapshots/workspace-edit/stdout.expected.windows.jsonl | 1 +
 1 file changed, 1 insertion(+)

diff --git a/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.windows.jsonl b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.windows.jsonl
index 7438c3f43f..754b9c5841 100644
--- a/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.windows.jsonl
+++ b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.windows.jsonl
@@ -1,5 +1,6 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}}

From d80dc2138742d3b80ae86f84109527a88d965cac Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 21 Jul 2026 21:54:37 +0800
Subject: [PATCH 57/74] docs(agent-note): refresh shared scoped-layer proposal

---
 .../2026-07-12-scoped-layers-store.i18n.yaml  |   4 +-
 .../2026-07-12-scoped-layers-store.md         | 142 ++++++++----------
 .../2026-07-12-scoped-layers-store.zh.md      | 142 ++++++++----------
 3 files changed, 122 insertions(+), 166 deletions(-)

diff --git a/.agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml
index c12497f016..40694cc6d2 100644
--- a/.agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-12-scoped-layers-store.md: f2056446abb3b8d0793b6ef7898c01001ccf0460
-2026-07-12-scoped-layers-store.zh.md: 9726eb3de953af1086d8bcdd779fc02b3c324596
+2026-07-12-scoped-layers-store.md: 64d565542e39a5ffcea98bc3343504760f31a416
+2026-07-12-scoped-layers-store.zh.md: ebe823b980864f4f24d4888312a73d2a5ee34fb5
diff --git a/.agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.md b/.agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.md
index c89850b4ca..64d565542e 100644
--- a/.agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.md
+++ b/.agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.md
@@ -1,4 +1,4 @@
-# Agent Note: Scoped-layers store — one aggregate layer per scope behind a scheduling helper
+# Agent Note: Shared scoped-layer storage
 
 Status: proposed
 
@@ -6,34 +6,25 @@ English | [中文](2026-07-12-scoped-layers-store.zh.md)
 
 ## Problem
 
-Agent scoping ([the agent-scope Agent Note](../../implemented/architecture/2026-07-08-agent-scope-contexts.md), [runtime design](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)) made "a registry with a global layer plus per-agent layers" a recurring shape, and every occurrence is hand-written. Six registration sites exist today — `tools.register`/`tools.restrict`/`tools.guard` in `dsh-tools` and `section`/`tools`/`variable` in `dsh-system-prompt` — each repeating the same 10-15-line effect choreography around its applicable global or scoped containers: read the calling context's tag, get or create the layer, validate, mutate, yield a rollback that deletes the entry and reclaims an emptied scoped layer, emit the applicable change event, and return the exact Cordis effect disposer.
+Agent scoping ([decision](../../implemented/architecture/2026-07-08-agent-scope-contexts.md), [runtime design](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)) gives scope-aware registries the same recurring shape: one global registration layer plus one exact agent layer. Seven registration facades implement that shape independently: `tools.register`, `tools.restrict`, and `tools.guard` in `dsh-tools`; `SystemPrompt.section`, `SystemPrompt.tools`, and `SystemPrompt.variable` in `dsh-system-prompt`; and `CommandService.register` in `dsh-commands`.
 
-Beyond the duplication, the risk concentrates in the choreography details:
-- The rollback must be collected before the change emit (so a throwing listener unwinds the insertion instead of leaking it)
-- The returned disposer must be Cordis's own function (a wrapper silently breaks nested ordered teardown)
-- Emptied scoped layers must be reclaimed (a disposed agent must not leave residue keyed by its dead `ScopeKey`)
+Each facade repeats the lifecycle choreography around its domain state: derive visibility from the calling context, create a scoped container on demand, attach ownership to the same Cordis fiber, install undo before notifying observers, return Cordis's exact disposer, and reclaim empty scoped state. The copies use separate maps and collection types, so a service has no object representing one scope's complete contribution and must reproduce cleanup for every table.
 
-Every new consumer has to rewrite all of that correctly, and the copies have already diverged stylistically — two private layer helpers in `dsh-tools`, three inline IIFEs in `dsh-system-prompt`.
+The duplicated code carries three non-obvious requirements:
 
-Finally, one agent's contribution to one service is scattered across several maps that know nothing of each other — there is no object that means "what this scope contributes here" — and the consumer count keeps growing: scoped guards and per-agent prompt/tool composition landed recently, while per-agent `fs/*` policy, `llm/*` overrides, and compaction policy are plausible future users of the same pattern.
+- Visibility and ownership must come from the same context; accepting them separately permits a registration visible in one scope but disposed with another.
+- Undo must be collected before a change callback runs, so a throwing callback rolls the mutation back.
+- The public disposer must be the exact function returned by `ctx.effect()`; wrapping it breaks Cordis's identity-based ordered teardown.
+
+The shared part is lifecycle and insertion-ordered storage, not registry policy. Tool restrictions, reserved transport handling, prompt evaluation timing, command normalization, exact diagnostics, and callback containment remain different domain contracts.
 
 ## Proposal
 
-`dsh-scope` gains a key-agnostic `store.ts`, with Cordis as its only peer dependency. The module implements the smallest abstraction shared by the six current sites: **business state and validation stay in an explicit layer class; one helper owns layer selection, effect attachment, rollback, notification, and reclamation**. One helper instance belongs to one service, and one layer instance aggregates everything a scope contributes to that service.
+`@deepseek-ai/dsh-scope` gains a key-agnostic `store.ts` implementation module. The package continues to peer on Cordis and `@deepseek-ai/dsh-invariants`, and its invariant companion remains unchanged. The package root exports four storage symbols: `ScopeLayer`, `ScopedLayers`, `NamedEntries`, and `AnonymousEntries`. `EntryValues` remains internal, and `store.ts` is not a package subpath.
 
-- **`ScopedLayers<L>`** is a concrete scheduler, not a base class. It owns the global layer plus one `Map<ScopeKey, L>`, constructs scoped layers on demand through an explicit factory, and reclaims a layer when `isEmpty()`. Its `effect(ctx, action, options?)` accepts one synchronous action that returns one synchronous undo because that is the complete shape of all six current sites. The single `ctx` decides both the visible layer (`scopeOf(ctx)`) and the owning Cordis fiber (`ctx.effect`), so "visible to X, disposed with Y" stays unrepresentable. The helper yields the undo before notifying listeners, returns Cordis's exact disposer, and reclaims a newly created empty layer if validation or mutation throws. Reads are `global`/`peek` plus `merge` (named entries with scoped shadowing and an optional global-admission predicate), `values` (global then scoped concatenation without shadowing), and `keys` (the pre-restriction name universe).
-- **Explicit `ScopeLayer` classes** make each service's state visible to readers. `ToolLayer` and `PromptLayer` declare their three table properties and their `isEmpty()` aggregation directly; a small layer factory receives only the scope, while its closure may capture real constructor dependencies. Domain methods stay ordinary class methods. This costs a few repetitive declarations but avoids a mapped-type class factory, a scheduler/layer ownership cycle, reserved property names, and generated runtime structure.
-- **`NamedEntries<V>` and `AnonymousEntries<V>`** are the two shared insertion-ordered tables. Named entries expose `insert`/lookup and retain the current global/scoped duplicate wording through domain `kind` and per-agent-alternative labels; anonymous entries expose only `append`, using process-unique symbol keys for O(1) undo removal. Keeping the classes separate makes meaningless mixed named/anonymous operations unrepresentable and keeps key types sound. Their iterators borrow membership and typed contribution values; they do not clone or freeze values. `ScopedLayers` materializes only the merged arrays/maps already required by the service read paths.
+`ScopeLayer` keeps the aggregate concept explicit while requiring only whole-layer emptiness. A service defines one concrete layer whose tables and domain helpers fit that service; `ScopedLayers` owns construction, selection, lifecycle attachment, notification, and aggregate reclamation.
 
-`dsh-tools` migrates its three tables into one `ToolLayer`: tools, compiled restrictions, and guards. The layer owns restriction admission and guard evaluation; the facade retains domain validation that needs service configuration, such as the reserved `run_code` name and the current known-global-name universe. Readonly allow/deny inputs are compiled once into internal sets. `dsh-system-prompt` likewise migrates sections, tool providers, and variables into one `PromptLayer`. Every registration facade performs its public argument validation and then makes one `effect` call with a label and, for guards, `silent: true`. A generic helper does not learn domain rules such as "restrictions require a scoped context."
-
-`assemble` stays in the `SystemPrompt` facade for three reasons: the subject scope's layer may not exist and reads must not create it; shadowing requires merge-before-evaluate so a hidden section provider is never called; and the assembly waterfall and `toolOrder` use service-level resources. Sections and tool providers keep their current materialized derived views. Variable providers instead iterate the global and scoped `NamedEntries` directly, preserving today's live Map behavior when a provider registers another variable during assembly. Tool guards likewise iterate their `AnonymousEntries` directly.
-
-Migration preserves public behavior and exact duplicate messages. The internal aggregate layer is reclaimed only after all three tables empty rather than when one table empties; no service API exposes layer identity. Direct live iteration retains current re-entrant variable-provider and guard behavior, while selector helpers continue to materialize the same section, tool-provider, and tool-resolution views their facades build today.
-
-`ScopeLayer`, `EntryValues`, `ScopedLayers`, `NamedEntries`, and `AnonymousEntries` are public `dsh-scope` root exports with export JSDoc. Consumers import them from `@deepseek-ai/dsh-scope`; `store.ts` is an implementation module, not a package subpath.
-
-## API sketch
+## Public interface
 
 ```ts ignore-check
 export interface ScopeLayer {
@@ -41,22 +32,28 @@ export interface ScopeLayer {
 }
 
 export class ScopedLayers<L extends ScopeLayer> {
-  constructor(createLayer: (scope: ScopeKey | undefined) => L, options: { onChange?: () => void })
+  constructor(
+    createLayer: (scope: ScopeKey | undefined) => L,
+    onChange: () => void,
+  )
+
   readonly global: L
   peek(scope: ScopeKey | undefined): L | undefined
-  merge<T>(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries<T>, admitGlobal?: (name: string) => boolean): Map<string, T>
-  values<T>(scope: ScopeKey | undefined, pick: (layer: L) => EntryValues<T>): T[]
-  keys<T>(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries<T>): string[]
-  effect(ctx: Context, action: (layer: L) => () => void, options: { label: string; silent?: boolean }): () => void
+
+  merge<V>(
+    scope: ScopeKey | undefined,
+    pick: (layer: L) => NamedEntries<V>,
+  ): Map<string, V>
+
+  effect(
+    ctx: Context,
+    action: (layer: L) => () => void,
+    options: { label: string; notify?: boolean },
+  ): () => void
 }
 
-export interface EntryValues<V> {
-  values(): IterableIterator<V>
-  isEmpty(): boolean
-}
-
-export class NamedEntries<V> implements EntryValues<V> {
-  constructor(kind: string, perAgentAlternative: string, scope: ScopeKey | undefined)
+export class NamedEntries<V> {
+  constructor(duplicateError: (name: string) => Error)
   insert(name: string, value: V): () => void
   get(name: string): V | undefined
   has(name: string): boolean
@@ -66,80 +63,61 @@ export class NamedEntries<V> implements EntryValues<V> {
   isEmpty(): boolean
 }
 
-export class AnonymousEntries<V> implements EntryValues<V> {
+export class AnonymousEntries<V> {
   append(value: V): () => void
   values(): IterableIterator<V>
   isEmpty(): boolean
 }
 ```
 
-What a migrated consumer looks like — the heaviest current site shrinks from 30+ lines of choreography to a declaration and one-line facades:
+## Storage contract
 
-```ts ignore-check
-class ToolLayer implements ScopeLayer {
-  readonly tools = new NamedEntries<ToolDefinition>('tool', 'variant', this.scope)
-  readonly restrictions = new AnonymousEntries<CompiledToolRestriction>()
-  readonly guards = new AnonymousEntries<ToolGuardRegistration>()
+- The constructor creates `global` once with `createLayer(undefined)`. A scoped layer is created only by `effect()`; `peek()` and `merge()` never create one, and `peek(undefined)` returns `undefined` because the global layer is already explicit.
+- `merge()` is the only materialized generic read. It copies named global entries in insertion order, then applies matching scoped entries in their insertion order so same-name entries shadow without moving unrelated names.
+- `NamedEntries.insert()` checks and inserts atomically, returns an idempotent exact-entry undo, and obtains the registry's exact duplicate diagnostic from the caller-supplied factory. Lookup and iterators retain native `Map` order and live iteration.
+- `AnonymousEntries.append()` assigns a unique internal key per registration, so equal callbacks or values remain independent. Its iterator is live and insertion-ordered.
+- `effect()` derives the key with `scopeOf(ctx)` and attaches the action to that same `ctx.effect()`. It accepts one synchronous action returning one synchronous undo; actions must either return their undo or throw before retaining a contribution. The helper does not normalize the wider Cordis `Effect` union.
+- `effect()` collects the action's undo before calling `onChange` and returns the exact `ctx.effect()` disposer. Disposal runs the action undo before notification, is idempotent through Cordis, and removes a scoped layer only after its complete `ScopeLayer.isEmpty()` becomes true.
+- `options.notify` defaults to `true`. The callback's own policy stays authoritative: tool and prompt change callbacks may throw and trigger registration rollback; `CommandService.notifyChange()` contains observer failures; tool guards pass `notify: false`.
 
-  constructor(
-    readonly scope: ScopeKey | undefined,
-  ) {}
+## Registry migrations
 
-  isEmpty(): boolean { return this.tools.isEmpty() && this.restrictions.isEmpty() && this.guards.isEmpty() }
-  addRestriction(filter: ToolRestriction): () => void { /* compile to sets, append */ }
-  admits(name: string): boolean { /* intersection over this.restrictions.values() */ }
-  guardReason(view: Readonly<ToolExecution>): string | undefined { /* first monotonic denial */ }
-}
+`dsh-tools` defines one `ToolLayer` containing named tools plus anonymous compiled restrictions and guard registrations. `ToolRegistry` retains its private domain resolver for visible definitions, pre-restriction known names, restrictable global names, scoped shadowing, restrictions, and reserved `run_code` insertion. Guard evaluation continues to live-iterate global then scoped registrations so re-entrant additions retain current behavior.
 
-class ToolRegistry extends Service {
-  private readonly layers = new ScopedLayers(
-    scope => new ToolLayer(scope),
-    { onChange: () => this.ctx.emit('tools/change') },
-  )
+`dsh-system-prompt` defines one `PromptLayer` containing named sections and variables plus anonymous tool providers. Assembly merges sections before evaluating them, so a shadowed provider is never called. Tool-provider membership is materialized once per assembly. Variable providers continue to live-iterate global then scoped tables, preserving re-entrant registration behavior.
 
-  register(definition: ToolDefinition): () => void {
-    return this.layers.effect(this.ctx,
-      layer => layer.tools.insert(definition.name, definition),
-      { label: 'tools.register()' })
-  }
+`dsh-commands` defines a one-table layer containing `NamedEntries<RegisteredCommand>`. Effective views use `merge()`, while `CommandService` retains definition normalization and freezing, exact duplicate diagnostics, sorted immutable descriptors, direct execution, HMR cleanup, and independently contained `commands/change` observers.
 
-  private resolveVisible(scope?: ScopeKey): ToolDefinition[] {
-    const scoped = this.layers.peek(scope)
-    return Array.from(this.layers.merge(scope, layer => layer.tools, name => scoped?.admits(name) ?? true).values())
-  }
-}
-```
+All seven facades keep validation and diagnostics in their owning registry and continue to return the exact Cordis disposer. The migration changes neither public registry behavior nor model-, human-, wire-, persistence-, or configuration-visible output.
 
 ## Alternatives considered
 
-**Per-scope registry instances behind a parent/child delegation chain.** Instance explosion; the "deployment tools plus my tools" merged view needs a hand-built delegating registry per service; single-subscription observers (persistence, the ACP bridge) would have to discover and subscribe per instance; and a delegation chain cannot express subtraction (restrictions). A child registry would also have to reach back into a parent context, widening the exposure surface.
+**Keep the independent implementations.** This avoids a new library interface but leaves lifecycle ordering, disposer identity, and scope reclamation duplicated across seven facades.
 
-**Explicit scope parameters on registration APIs.** Already rejected by the agent-scope Agent Note: omitting the parameter silently registers globally, and the shape can express visible-to-X-disposed-with-Y, which is almost always a bug.
+**One helper per table.** This removes some local code but preserves multiple per-scope maps and cannot reclaim one scope's aggregate contribution correctly.
 
-**Extracting only the data structure, leaving the choreography in services.** Removes the safe half of the duplication and keeps the dangerous half — the rollback-before-emit ordering, raw-disposer, and reclamation rules are exactly where the bugs live.
+**Per-scope registry instances.** Child registries would need delegation for global-plus-scoped views, special subtraction for restrictions, and observer discovery across instances. They would move complexity rather than remove it.
 
-**Accepting the full Cordis `Effect` union as a layer action.** None of the six sites has asynchronous setup, multiple undos, or an independent settlement boundary. Normalizing promises, iterables, async iterables, LIFO sealing, and partial failure would duplicate lifecycle machinery speculatively. The store accepts one synchronous action and one undo; a future real boundary can justify widening it.
+**Explicit scope parameters on registration methods.** Separate visibility and ownership inputs make mismatched lifetimes representable, while an omitted scope silently becomes global.
 
-**Generating layer classes from a mapped-type table DSL.** The two consumers each declare three tables. A class factory would save a handful of lines while adding generated runtime shape, reserved names, polymorphic-`this` typing, and a second construction model. Explicit classes are easier to inspect and can still share the entry tables and `ScopedLayers`.
+**Accept the complete Cordis `Effect` union.** None of the seven registrations has asynchronous setup, multiple undos, or an independent settlement boundary. General normalization would duplicate Cordis lifecycle machinery without a current consumer.
 
-**A fixed-container helper with built-in view semantics.** Pins container shapes and merge policy inside the helper; business gets no freedom, and every naming or single-value variation becomes a helper feature request.
+**Expose `ScopedLayers.values()`, `ScopedLayers.keys()`, or a global-admission predicate.** Those operations encode consumer-specific live/materialized and filtering policies. Direct table iteration preserves explicit live semantics, `merge()` covers the shared named shadowing operation, and `ToolRegistry` keeps its richer private resolver.
 
-**One helper per table.** Reproduces today's scattered bookkeeping — that is the status quo being replaced, with N scope maps per service and no aggregate for an agent's contribution.
+**Put `values()` on `ScopeLayer` or export `EntryValues`.** A layer aggregates heterogeneous tables and has no coherent value type or iteration policy. `EntryValues` is useful only to share implementation details between the two table classes; making it public would enlarge the interface without giving callers a meaningful layer-wide read.
 
-**`helper.get(ctx).effect(...)` two-step registration.** Splits layer creation from lifecycle attachment; a throw between the steps strands an empty layer, and the returned handle is an extra allocation per call.
-
-**Layers holding a ctx and registering their own effects.** Turns data objects into lifecycle managers and reinstates the choreography once per business class.
+**Generate layers from a mapped-type table description.** Three-table and one-table concrete layers are short, inspectable, and free to hold domain helpers. A class generator would add a second construction model and generated runtime shape for little leverage.
 
 ## Acceptance criteria
 
-- `store.ts` ships in `dsh-scope` (peer dependencies unchanged: Cordis only; module-graph position unchanged) with per-file 100% coverage of layer selection and reclamation, synchronous action/undo ordering, throwing-action cleanup, throwing-change-listener rollback, exact disposer identity, `label`/`silent`, factory typing, merge selectors, and separate named/anonymous entry semantics. Its five public symbols are re-exported from the package root and carry export JSDoc.
-- `dsh-tools` and `dsh-system-prompt` each collapse to one `ScopedLayers`; every registration facade validates its domain contract and then makes one `effect` call, and all keep returning the exact Cordis effect disposer.
-- Existing behavior, duplicate messages, validation order, live variable-provider re-entrancy, and live guard re-entrancy remain unchanged. Tests additionally pin aggregate reclamation timing and selector materialization.
-- Documentation lands in the same change: `dsh-scope`/`dsh-tools`/`dsh-system-prompt` READMEs; on implementation this Agent Note moves to `implemented/` and the [runtime-design Agent Note](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)'s registration section is updated in place.
+- `dsh-scope` exports exactly the four proposed storage symbols from its root and covers global construction, lazy scoped construction, non-creating reads, named shadowing, aggregate reclamation, failure cleanup, notification ordering, exact disposer identity, caller-owned duplicate errors, independent anonymous duplicates, and live iterators.
+- `dsh-tools`, `dsh-system-prompt`, and `dsh-commands` migrate all seven registration facades while preserving validation order, exact diagnostics, views, notification policy, re-entrancy, and HMR disposal.
+- The `dsh-scope` README and scoped core-data documentation describe the public contract; architecture and runtime-design references identify the shared store without duplicating it. Consumer READMEs remain focused on their unchanged public behavior.
+- This pair moves to `implemented/architecture` in the implementation PR, changes `Proposal` to present-tense `Decision`, and records shipped consequences and verification. Existing keyless snapshots remain byte-identical.
 
 ## Risks
 
-- The layer/facade boundary may not fit a future consumer's shape. Mitigation: `ScopeLayer` requires only `isEmpty()`, while the factory closure can capture constructor dependencies without giving a layer ownership of its scheduler.
-- A future registration may genuinely need asynchronous setup or several independently owned undos. The helper deliberately does not predict that lifecycle; such a consumer must first identify its owner and settlement boundary, then widen the contract with tests.
-- Explicit layer declarations repeat three property initializers and `isEmpty()` in each consumer. Accepted: the repetition keeps runtime state and types visible and avoids a second DSL for two classes.
-- Two core registries migrate at once. Mitigated by the behavior comparison performed during design and by landing the store with equivalence-pinning tests before either migration commit.
+- A future registration may need asynchronous setup or several independently owned undos. That consumer must identify its ownership and settlement boundary before widening this deliberately synchronous interface.
+- A throwing action that mutates outside the returned undo contract cannot be repaired generically. Entry operations are atomic, migrations perform fallible validation before insertion, and tests pin cleanup for factory and pre-retention action failures.
+- Aggregate reclamation keeps a scoped layer alive until every table empties. This is intentional and observable only as internal storage lifetime; tests pin that one table's disposal does not discard sibling contributions.
+- The public classes add a reusable package contract. Keeping reads narrow and domain policy in consumers limits how much future code must preserve.
diff --git a/.agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.zh.md b/.agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.zh.md
index 0f766b822a..ebe823b980 100644
--- a/.agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 作用域分层存储——每 scope 一个聚合层与统一调度 helper
+# Agent Note: 共享作用域分层存储
 
 Status: proposed
 
@@ -6,34 +6,25 @@ Status: proposed
 
 ## 问题
 
-agent 作用域落地之后（[agent-scope Agent Note](../../implemented/architecture/2026-07-08-agent-scope-contexts.md)、[运行时设计篇](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)），「一张全局层加若干 per-agent 层的注册表」成为反复出现的形态，而每一处都是手写的。今天已有六个登记口——`dsh-tools` 的 `tools.register`/`tools.restrict`/`tools.guard` 与 `dsh-system-prompt` 的 `section`/`tools`/`variable`——每处都围绕适用的全局或专属容器重复同一段 10-15 行的 effect 编排：读调用方上下文的标签、按需建层、校验、变更、yield 一个删除条目并回收空专属层的回滚、发适用的 change 事件，然后返回 Cordis effect 的原始 disposer。
+agent（智能体）作用域机制（[决策](../../implemented/architecture/2026-07-08-agent-scope-contexts.md)、[运行时设计](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)）让支持作用域的注册表反复呈现同一种形态：一个全局注册层，加上一个与具体 agent 精确对应的层。七个注册门面各自独立实现这一形态：`tools.register`、`tools.restrict` 和 `tools.guard`（位于 `dsh-tools`）；`SystemPrompt.section`、`SystemPrompt.tools` 和 `SystemPrompt.variable`（位于 `dsh-system-prompt`）；以及 `CommandService.register`（位于 `dsh-commands`）。
 
-除此之外：风险集中在编排细节上：
-- 回滚必须在 change 发出之前被收集（抛错的监听器才能回卷插入而不是泄漏）
-- 返回的 disposer 必须是 Cordis 自己的那个函数（包装器会静默破坏嵌套的有序拆除）
-- 清空的专属层必须被回收（被 dispose 的 agent 不得留下以死 `ScopeKey` 为键的残余）
+每个门面都围绕自己的领域状态重复相同的生命周期编排：从调用方上下文导出可见性，按需创建专属容器，把属主绑定到同一个 Cordis fiber，先装入 undo 再通知观察者，原样返回 Cordis 的 disposer，并回收空的专属状态。各份实现采用不同的映射与集合类型，因此服务内没有一个对象能表示某个 scope 的完整贡献，而且每张表都必须重复清理逻辑。
 
-每个新消费者都要把这一切重新写对一遍，而各副本的写法已经分叉——`dsh-tools` 里有两个私有建层 helper，`dsh-system-prompt` 里是三处内联 IIFE。
+重复代码承载着三项不明显的要求：
 
-最后，一个 agent 在一个服务里的贡献散落在几张互不相识的 Map 里——不存在一个「这个 scope 在这里贡献了什么」的对象——而消费者还在持续增多：专属 guard 与 per-agent 提示词/工具组合是最近落地的一批，per-agent 的 `fs/*` 策略、`llm/*` 覆盖与 compaction 策略则是同一模式的潜在后续用户。
+- 可见性与属主必须来自同一个上下文；若分开接受二者，就能登记出对一个 scope 可见、却随另一个 scope 销毁的贡献。
+- change 回调运行前必须收集 undo，抛错的回调才能回滚变更。
+- 公开 disposer 必须就是 `ctx.effect()` 返回的那个函数；包装它会破坏 Cordis 基于身份的有序拆除。
+
+共享的是生命周期与保持插入顺序的存储，而不是注册表策略。工具限制、保留传输处理、提示词求值时机、命令规范化、精确诊断和回调异常隔离，仍分别属于不同的领域契约。
 
 ## 提案
 
-`dsh-scope` 新增与键类型无关的 `store.ts`，peer 依赖仍只有 Cordis。模块只抽取六个现有登记口已经共同证明的最小形状：**业务状态与校验留在显式层类里；一个 helper 统一负责选层、挂 effect、回滚、通知与回收**。一个 helper 实例属于一个服务；一个层实例聚合某 scope 对该服务的全部贡献。
+`@deepseek-ai/dsh-scope` 新增与键类型无关的 `store.ts` 实现模块。该包（package）继续将 Cordis 和 `@deepseek-ai/dsh-invariants` 列为对等依赖（peer dependency），其不变量配套模块保持不变。包根导出四个存储符号：`ScopeLayer`、`ScopedLayers`、`NamedEntries` 和 `AnonymousEntries`。`EntryValues` 仍是内部接口，`store.ts` 不是包子路径。
 
-- **`ScopedLayers<L>`** 是具体调度器，不作基类。它持有全局层与一张 `Map<ScopeKey, L>`，通过显式工厂按需构造专属层，并在层 `isEmpty()` 时回收。`effect(ctx, action, options?)` 只接受一个同步 action，action 只返回一个同步 undo，因为六个现有登记口的完整形状就是如此。单一 `ctx` 同时决定可见层（`scopeOf(ctx)`）与属主 Cordis fiber（`ctx.effect`），「对 X 可见、随 Y 销毁」因此不可表达。helper 在通知监听器前 yield undo，返回 Cordis 的原始 disposer，并在校验或变更抛错时回收刚建出的空层。读取接口是 `global`/`peek`，以及 `merge`（命名条目的专属遮蔽与可选全局放行谓词）、`values`（不遮蔽地依次拼接全局与专属条目）和 `keys`（限制前名字全集）。
-- **显式 `ScopeLayer` 类**让每个服务的状态一眼可见。`ToolLayer` 与 `PromptLayer` 直接声明各自三项表属性与 `isEmpty()` 聚合；一个小工厂只向构造器传入 scope，闭包仍可捕获真实构造依赖。领域方法仍是普通类方法。代价是几行重复声明，收益是不用引入 mapped-type 类工厂、scheduler/layer 属主环、保留属性名和生成式运行时结构。
-- **`NamedEntries<V>` 与 `AnonymousEntries<V>`** 是两种共用的保插入序条目表。命名表暴露 `insert`/查询，并通过领域 `kind` 与 per-agent alternative 标签保持现有全局/专属重名文案；匿名表只暴露 `append`，以进程内唯一 symbol 作键支持 O(1) 撤销删除。分成两类以后，无意义的命名/匿名混用不可表达，key 类型也保持健全。迭代器借用表成员与带类型的贡献值，不会 clone 或 freeze 值；`ScopedLayers` 只物化服务读路径本来就需要的合并数组或 Map。
+`ScopeLayer` 保留显式的聚合概念，同时只要求判断整个层是否为空。服务定义一个具体层，使其表结构与领域 helper 适合该服务；`ScopedLayers` 负责构造、选择、生命周期挂接、通知和聚合回收。
 
-`dsh-tools` 把工具、已编译 restriction 与 guard 三张表合并进一个 `ToolLayer`。restriction 放行判断与 guard 求值归层所有；`run_code` 保留名、当前已知全局名集合等依赖服务配置的领域校验仍留在门面。只读 allow/deny 输入只编译一次，成为内部 Set。`dsh-system-prompt` 同样把 section、tool provider 与 variable 合并进一个 `PromptLayer`。每个登记门面先完成公开参数校验，再以 label 做一次 `effect` 调用；guard 额外传 `silent: true`。通用 helper 不理解「restriction 必须由 scoped context 调用」之类领域规则。
-
-`assemble` 留在 `SystemPrompt` 门面，三条理由：主体 scope 的层可能不存在，读路径不得创建它；遮蔽语义要求先合并再求值，被遮蔽的 section provider 绝不能被调用；组装 waterfall 与 `toolOrder` 使用服务级资源。section 与 tool provider 保持既有的派生视图物化；variable provider 则直接遍历全局与专属 `NamedEntries`，保留 provider 在组装期间登记另一 variable 时的现有活 Map 行为。tool guard 同样直接遍历其 `AnonymousEntries`。
-
-迁移保持公开行为与精确重名文案不变。内部聚合层会在三张表全部清空后才回收，而不是某一张表清空时回收；服务 API 不暴露层身份。直接活遍历保留现有 variable-provider 与 guard 重入行为，selector helper 则继续物化门面今天已经在构造的 section、tool-provider 与工具解析视图。
-
-`ScopeLayer`、`EntryValues`、`ScopedLayers`、`NamedEntries` 与 `AnonymousEntries` 都是带 export JSDoc 的 `dsh-scope` 根导出。消费者从 `@deepseek-ai/dsh-scope` 导入；`store.ts` 是实现模块，不是 package subpath。
-
-## API 草图
+## 公开接口
 
 ```ts ignore-check
 export interface ScopeLayer {
@@ -41,22 +32,28 @@ export interface ScopeLayer {
 }
 
 export class ScopedLayers<L extends ScopeLayer> {
-  constructor(createLayer: (scope: ScopeKey | undefined) => L, options: { onChange?: () => void })
+  constructor(
+    createLayer: (scope: ScopeKey | undefined) => L,
+    onChange: () => void,
+  )
+
   readonly global: L
   peek(scope: ScopeKey | undefined): L | undefined
-  merge<T>(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries<T>, admitGlobal?: (name: string) => boolean): Map<string, T>
-  values<T>(scope: ScopeKey | undefined, pick: (layer: L) => EntryValues<T>): T[]
-  keys<T>(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries<T>): string[]
-  effect(ctx: Context, action: (layer: L) => () => void, options: { label: string; silent?: boolean }): () => void
+
+  merge<V>(
+    scope: ScopeKey | undefined,
+    pick: (layer: L) => NamedEntries<V>,
+  ): Map<string, V>
+
+  effect(
+    ctx: Context,
+    action: (layer: L) => () => void,
+    options: { label: string; notify?: boolean },
+  ): () => void
 }
 
-export interface EntryValues<V> {
-  values(): IterableIterator<V>
-  isEmpty(): boolean
-}
-
-export class NamedEntries<V> implements EntryValues<V> {
-  constructor(kind: string, perAgentAlternative: string, scope: ScopeKey | undefined)
+export class NamedEntries<V> {
+  constructor(duplicateError: (name: string) => Error)
   insert(name: string, value: V): () => void
   get(name: string): V | undefined
   has(name: string): boolean
@@ -66,80 +63,61 @@ export class NamedEntries<V> implements EntryValues<V> {
   isEmpty(): boolean
 }
 
-export class AnonymousEntries<V> implements EntryValues<V> {
+export class AnonymousEntries<V> {
   append(value: V): () => void
   values(): IterableIterator<V>
   isEmpty(): boolean
 }
 ```
 
-迁移后的消费者长什么样——现存最重的登记口从 30+ 行编排缩为一份声明加一行门面：
+## 存储契约
 
-```ts ignore-check
-class ToolLayer implements ScopeLayer {
-  readonly tools = new NamedEntries<ToolDefinition>('tool', 'variant', this.scope)
-  readonly restrictions = new AnonymousEntries<CompiledToolRestriction>()
-  readonly guards = new AnonymousEntries<ToolGuardRegistration>()
+- 构造器只创建一次 `global`，调用的是 `createLayer(undefined)`。只有 `effect()` 会创建专属层；`peek()` 和 `merge()` 从不创建专属层，而 `peek(undefined)` 返回 `undefined`，因为全局层已经显式存在。
+- `merge()` 是唯一会物化结果的通用读取接口。它按插入顺序复制全局命名条目，再按专属条目的插入顺序应用这些条目；同名条目完成遮蔽，但不会移动无关名称。
+- `NamedEntries.insert()` 以原子方式检查并插入，返回幂等且只撤销该精确条目的 undo，并通过调用方提供的工厂取得所属注册表的精确重名诊断。查询与迭代器保留 `Map` 的原生顺序和活遍历语义。
+- `AnonymousEntries.append()` 为每次登记分配唯一内部键，因此值相等的回调或其他值仍彼此独立。其迭代器是保留插入顺序的活迭代器。
+- `effect()` 通过 `scopeOf(ctx)` 导出键，并把 action 挂到同一个 `ctx.effect()` 上。它只接受一个同步 action，且该 action 只返回一个同步 undo；action 要么返回其 undo，要么必须在保留任何贡献之前抛错。helper 不会规范化更宽泛的 Cordis `Effect` union。
+- `effect()` 在调用 `onChange` 前收集 action 的 undo，并原样返回 `ctx.effect()` 的 disposer。销毁时先运行 action undo 再通知；Cordis 保证其幂等性；只有整个层的 `ScopeLayer.isEmpty()` 变为 true 后，helper 才删除专属层。
+- `options.notify` 默认为 `true`。回调自身的策略仍具最终效力：工具与提示词的 change 回调可以抛错并触发登记回滚；`CommandService.notifyChange()` 会隔离观察者失败；工具 guard 传入 `notify: false`。
 
-  constructor(
-    readonly scope: ScopeKey | undefined,
-  ) {}
+## 注册表迁移
 
-  isEmpty(): boolean { return this.tools.isEmpty() && this.restrictions.isEmpty() && this.guards.isEmpty() }
-  addRestriction(filter: ToolRestriction): () => void { /* compile to sets, append */ }
-  admits(name: string): boolean { /* intersection over this.restrictions.values() */ }
-  guardReason(view: Readonly<ToolExecution>): string | undefined { /* first monotonic denial */ }
-}
+`dsh-tools` 定义一个 `ToolLayer`，其中包含命名工具以及匿名的已编译 restriction 和 guard 登记。`ToolRegistry` 保留其私有领域解析器，由它处理可见定义、限制前的已知名称、可限制的全局名称、专属遮蔽、restriction，以及保留的 `run_code` 插入。guard 求值继续先活遍历全局登记，再活遍历专属登记，因此重入时新增的登记保持现有行为。
 
-class ToolRegistry extends Service {
-  private readonly layers = new ScopedLayers(
-    scope => new ToolLayer(scope),
-    { onChange: () => this.ctx.emit('tools/change') },
-  )
+`dsh-system-prompt` 定义一个 `PromptLayer`，其中包含命名的段落与变量，以及匿名工具提供方。组装流程在求值前合并段落，因此被遮蔽的提供方不会被调用。每次组装只物化一次工具提供方成员集合。变量提供方继续先活遍历全局表，再活遍历专属表，从而保留重入登记行为。
 
-  register(definition: ToolDefinition): () => void {
-    return this.layers.effect(this.ctx,
-      layer => layer.tools.insert(definition.name, definition),
-      { label: 'tools.register()' })
-  }
+`dsh-commands` 定义一个单表层，其中包含 `NamedEntries<RegisteredCommand>`。生效视图使用 `merge()`；`CommandService` 则保留对定义的规范化与冻结处理、精确重名诊断、经过排序的不可变描述符、直接执行、HMR（热模块替换）清理，以及对各个 `commands/change` 观察者分别隔离失败的行为。
 
-  private resolveVisible(scope?: ScopeKey): ToolDefinition[] {
-    const scoped = this.layers.peek(scope)
-    return Array.from(this.layers.merge(scope, layer => layer.tools, name => scoped?.admits(name) ?? true).values())
-  }
-}
-```
+七个门面都把校验与诊断留在所属注册表中，并继续返回 Cordis 的原始 disposer。迁移既不改变公开注册表行为，也不改变模型可见或人类可见的输出，以及协议、持久化或配置层面的可见输出。
 
 ## 备选方案
 
-**每 scope 一个注册表实例，父子委托链。** 实例爆炸；「部署工具加我的工具」的合并视图要每个服务手写一个委托注册表；单订阅观察者（持久化、ACP bridge）必须逐实例发现并订阅；委托链表达不了减法（restriction）。子注册表还得反向触及父上下文，扩大暴露面。
+**保留彼此独立的实现。** 这样不必新增库接口，但七个门面仍会重复生命周期顺序、disposer 身份和 scope 回收。
 
-**注册 API 上的显式 scope 参数。** agent-scope Agent Note 已否决：漏传参数即静默注册为全局，且该形状能表达「对 X 可见、随 Y 销毁」——几乎必然是 bug。
+**每张表一个 helper。** 这能减少一部分局部代码，但会保留多张按 scope 划分的映射，而且无法正确回收某个 scope 的聚合贡献。
 
-**只抽数据结构、编排留在服务。** 消掉的是重复里安全的那一半，留下的是危险的那一半——回滚先于 emit 的顺序、原始 disposer、回收规则，恰是 bug 所在。
+**每 scope 一个注册表实例。** 子注册表需要通过委托获得全局加专属的视图，对 restriction 进行特殊的减法处理，并跨实例发现观察者。这只会转移复杂度，而不会消除复杂度。
 
-**让 layer action 接受完整 Cordis `Effect` union。** 六个现有登记口都没有异步 setup、多份 undo 或独立 settlement 边界。现在就规范化 Promise、iterable、async iterable、LIFO 合成与部分失败，会重复一套纯属推测的生命周期 machinery。store 只接受一个同步 action 与一个 undo；未来出现真实边界时再凭证据拓宽。
+**注册方法上的显式 scope 参数。** 分开的可见性与属主输入让不匹配的生命周期成为可表达状态，而遗漏 scope 则会静默变成全局登记。
 
-**由 mapped-type 表 DSL 生成层类。** 两个消费者各自只有三张表。类工厂省下几行代码，却引入生成式运行时形状、保留名、多态 `this` 类型和第二种构造模型。显式类更易检查，同时仍可复用两种条目表与 `ScopedLayers`。
+**接受完整的 Cordis `Effect` union。** 七个登记口都没有异步 setup、多份 undo 或独立 settlement 边界。通用规范化会在没有现有消费者需要它时重复 Cordis 的生命周期 machinery。
 
-**内置视图语义的固定容器 helper。** 容器形态与合并策略被钉死在 helper 里；业务没有自由度，任何命名或单值变体都变成对 helper 的功能诉求。
+**暴露 `ScopedLayers.values()`、`ScopedLayers.keys()` 或全局放行谓词。** 这些操作会编码消费方特有的活遍历或物化策略，以及过滤策略。直接遍历条目表可保留显式的活语义，`merge()` 覆盖共享的命名遮蔽操作，而 `ToolRegistry` 继续保有功能更丰富的私有解析器。
 
-**每张表一个 helper。** 复刻今天的散装簿记——那正是被替换的现状：每服务 N 张 scope Map，agent 的贡献没有聚合。
+**把 `values()` 放在 `ScopeLayer` 上，或导出 `EntryValues`。** 一个层会聚合异构表，因而没有一致的值类型或迭代策略。`EntryValues` 只适合在两个表类之间共享实现细节；将其公开只会扩大接口，却不能为调用方提供有意义的整层读取方式。
 
-**`helper.get(ctx).effect(...)` 两步式登记。** 把建层与挂生命周期拆成两步；两步之间抛错会搁浅一个空层，返回的 handle 还是每次调用一笔额外分配。
-
-**层持有 ctx、自己注册 effect。** 把数据对象变成生命周期管理者，编排在每个业务类里重演一遍。
+**通过 mapped-type 表描述生成层。** 三表与单表具体层都很短、易于检查，并可自由持有领域 helper。类生成器会增加第二种构造模型和生成式运行时形状，收益却很小。
 
 ## 验收标准
 
-- `store.ts` 落在 `dsh-scope`（peer 依赖不变：仅 Cordis；模块图位置不变），逐文件 100% 覆盖选层与回收、同步 action/undo 顺序、action 抛错清理、change 监听器抛错回滚、原始 disposer 身份、`label`/`silent`、工厂类型、合并 selector，以及分开的命名/匿名条目语义。五个公开符号从 package 根重导出并带 export JSDoc。
-- `dsh-tools` 与 `dsh-system-prompt` 各收敛为一个 `ScopedLayers`；每个登记门面先校验领域契约再做一次 `effect` 调用，并继续返回 Cordis effect 的原始 disposer。
-- 既有行为、重名文案、校验顺序、variable-provider 活重入与 guard 活重入不变。测试另行钉住聚合回收时机与 selector 物化。
-- 文档随同一变更落地：`dsh-scope`/`dsh-tools`/`dsh-system-prompt` 的 README；实现后本 Agent Note 移入 `implemented/`，并就地更新[运行时设计 Agent Note](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md) 的注册章节。
+- `dsh-scope` 从包根恰好导出拟议的四个存储符号，并覆盖全局构造、专属层延迟构造、非创建式读取、命名遮蔽、聚合回收、失败清理、通知顺序、原始 disposer 身份、调用方拥有的重名错误、相同匿名值的独立登记和活迭代器。
+- `dsh-tools`、`dsh-system-prompt` 与 `dsh-commands` 迁移全部七个注册门面，同时保留校验顺序、精确诊断、视图、通知策略、重入行为和 HMR 清理。
+- `dsh-scope` README 与作用域核心数据文档描述公开契约；架构和运行时设计引用标识共享 store，但不重复其内容。各消费方 README 继续聚焦其未改变的公开行为。
+- 实现 PR 将本组文件移入 `implemented/architecture`，把 `Proposal` 改为以现在时书写的 `Decision`，并记录已落地的后果与验证。现有无密钥快照保持逐字节一致。
 
 ## 风险
 
-- 层/门面边界可能不适配某个未来消费者的形状。缓解：`ScopeLayer` 只要求 `isEmpty()`；工厂闭包可捕获构造依赖，无需让层反向持有 scheduler。
-- 未来登记口可能真的需要异步 setup 或多份独立属主的 undo。helper 刻意不预测这种生命周期；该消费者必须先说明 owner 与 settlement 边界，再连同测试拓宽契约。
-- 显式层声明会在两个消费者中各重复三行属性初始化与一段 `isEmpty()`。接受：这点重复让运行时状态和类型保持可见，避免为两个类引入第二套 DSL。
-- 两个核心注册表同时迁移。缓解：设计期已完成逐行为对比，且 store 连同钉住等价性的测试先于任一迁移 commit 落地。
+- 未来的登记可能需要异步 setup 或多份分别拥有属主的 undo。该消费方必须先明确其属主与 settlement 边界，再拓宽这个刻意保持同步的接口。
+- 抛错的 action 若在返回的 undo 契约之外产生变更，通用 helper 无法修复。条目操作是原子的；迁移会在插入前执行可能失败的校验；测试会钉住工厂失败和保留贡献前的 action 失败清理。
+- 聚合回收会让专属层一直存活到所有表都清空。这是有意行为，并且只能通过内部存储生命周期观察到；测试会钉住销毁一张表时不会丢弃同层的其他贡献。
+- 公开类新增了一项可复用的包契约。保持读取接口狭窄并把领域策略留在消费方，可以减少未来代码必须维持的契约范围。

From 8351cdbe65d51677d96360d415dcae322c72e755 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 21 Jul 2026 22:09:19 +0800
Subject: [PATCH 58/74] feat(scope): add scoped-layer storage

---
 packages/core/scope/src/index.ts        |   3 +
 packages/core/scope/src/store.ts        | 241 ++++++++++++++++++++++
 packages/core/scope/tests/store.spec.ts | 263 ++++++++++++++++++++++++
 3 files changed, 507 insertions(+)
 create mode 100644 packages/core/scope/src/store.ts
 create mode 100644 packages/core/scope/tests/store.spec.ts

diff --git a/packages/core/scope/src/index.ts b/packages/core/scope/src/index.ts
index f09844e9ab..fc5b1fa5fa 100644
--- a/packages/core/scope/src/index.ts
+++ b/packages/core/scope/src/index.ts
@@ -8,6 +8,9 @@
 import type { Context, Fiber } from 'cordis'
 import { Context as CordisContext } from 'cordis'
 
+export { AnonymousEntries, NamedEntries, ScopedLayers } from './store.ts'
+export type { ScopeLayer } from './store.ts'
+
 /** An opaque, identity-compared scope key. */
 export type ScopeKey = object
 
diff --git a/packages/core/scope/src/store.ts b/packages/core/scope/src/store.ts
new file mode 100644
index 0000000000..5f016df929
--- /dev/null
+++ b/packages/core/scope/src/store.ts
@@ -0,0 +1,241 @@
+/**
+ * Shared insertion-ordered storage and effect ownership for scope-aware registries.
+ *
+ * @module @deepseek-ai/dsh-scope
+ */
+
+import type { Context } from 'cordis'
+import { scopeOf } from './index.ts'
+import type { ScopeKey } from './index.ts'
+
+/** One scope's aggregate contribution to a registry. */
+export interface ScopeLayer {
+  /** Whether every table in this layer is empty. */
+  isEmpty(): boolean
+}
+
+/** Internal common read contract for the two entry-table implementations. */
+interface EntryValues<V> {
+  values(): IterableIterator<V>
+  isEmpty(): boolean
+}
+
+/**
+ * Insertion-ordered named entries with caller-owned duplicate diagnostics.
+ *
+ * Values are borrowed. Iterators are live native `Map` iterators, and each
+ * successful insertion returns an idempotent undo for that exact entry.
+ */
+export class NamedEntries<V> implements EntryValues<V> {
+  private readonly data = new Map<string, V>()
+
+  constructor(
+    private readonly duplicateError: (name: string) => Error,
+  ) {}
+
+  /**
+   * Insert one unique name.
+   * @param name - name unique within this table.
+   * @param value - borrowed value to retain.
+   * @returns an idempotent undo that removes only this insertion.
+   */
+  insert(name: string, value: V): () => void {
+    if (this.data.has(name)) throw this.duplicateError(name)
+    this.data.set(name, value)
+    let active = true
+    return () => {
+      if (!active) return
+      active = false
+      this.data.delete(name)
+    }
+  }
+
+  /**
+   * Read one named value.
+   * @param name - name to resolve.
+   * @returns the retained value, or `undefined` when absent.
+   */
+  get(name: string): V | undefined {
+    return this.data.get(name)
+  }
+
+  /**
+   * Test one name for membership.
+   * @param name - name to test.
+   * @returns whether the table contains that name.
+   */
+  has(name: string): boolean {
+    return this.data.has(name)
+  }
+
+  /**
+   * Iterate live names in insertion order.
+   * @returns the native live key iterator.
+   */
+  keys(): IterableIterator<string> {
+    return this.data.keys()
+  }
+
+  /**
+   * Iterate live entries in insertion order.
+   * @returns the native live entry iterator.
+   */
+  entries(): IterableIterator<[string, V]> {
+    return this.data.entries()
+  }
+
+  /**
+   * Iterate live values in insertion order.
+   * @returns the native live value iterator.
+   */
+  values(): IterableIterator<V> {
+    return this.data.values()
+  }
+
+  /**
+   * Test whether this table has no entries.
+   * @returns whether the table is empty.
+   */
+  isEmpty(): boolean {
+    return this.data.size === 0
+  }
+}
+
+/**
+ * Insertion-ordered anonymous entries with independent registration identity.
+ *
+ * Equal values remain separate registrations. Values are borrowed and the
+ * returned iterator retains native live `Map` semantics.
+ */
+export class AnonymousEntries<V> implements EntryValues<V> {
+  private readonly data = new Map<symbol, V>()
+
+  /**
+   * Append one independently owned value.
+   * @param value - borrowed value to retain.
+   * @returns an idempotent undo for this exact append.
+   */
+  append(value: V): () => void {
+    const key = Symbol()
+    this.data.set(key, value)
+    let active = true
+    return () => {
+      if (!active) return
+      active = false
+      this.data.delete(key)
+    }
+  }
+
+  /**
+   * Iterate live values in insertion order.
+   * @returns the native live value iterator.
+   */
+  values(): IterableIterator<V> {
+    return this.data.values()
+  }
+
+  /**
+   * Test whether this table has no entries.
+   * @returns whether the table is empty.
+   */
+  isEmpty(): boolean {
+    return this.data.size === 0
+  }
+}
+
+/**
+ * Own the global and exact-scope layers for one registry.
+ *
+ * Reads never create scoped layers. Registrations derive both visibility and
+ * effect ownership from the supplied Cordis context, collect undo before
+ * notification, and reclaim only a completely empty aggregate layer.
+ */
+export class ScopedLayers<L extends ScopeLayer> {
+  /** The eagerly constructed context-global layer. */
+  readonly global: L
+
+  private readonly scoped = new Map<ScopeKey, L>()
+
+  constructor(
+    private readonly createLayer: (scope: ScopeKey | undefined) => L,
+    private readonly onChange: () => void,
+  ) {
+    this.global = createLayer(undefined)
+  }
+
+  /**
+   * Read an existing exact-scope overlay.
+   * @param scope - exact scope key; `undefined` denotes no overlay.
+   * @returns the existing scoped layer, or `undefined` without creating one.
+   */
+  peek(scope: ScopeKey | undefined): L | undefined {
+    if (scope === undefined) return undefined
+    return this.scoped.get(scope)
+  }
+
+  /**
+   * Materialize global named entries followed by exact-scope shadows.
+   * @param scope - exact viewing scope, or `undefined` for the global view.
+   * @param pick - select the named table from a layer.
+   * @returns an insertion-ordered effective map.
+   */
+  merge<V>(
+    scope: ScopeKey | undefined,
+    pick: (layer: L) => NamedEntries<V>,
+  ): Map<string, V> {
+    const merged = new Map(pick(this.global).entries())
+    const layer = this.peek(scope)
+    if (layer === undefined) return merged
+    for (const [name, value] of pick(layer).entries()) merged.set(name, value)
+    return merged
+  }
+
+  /**
+   * Attach one synchronous layer mutation to its registration context.
+   * @param ctx - context that determines both scope visibility and effect ownership.
+   * @param action - atomic mutation returning its synchronous undo.
+   * @param options - Cordis effect label and optional change notification.
+   * @returns the exact disposer returned by `ctx.effect()`.
+   */
+  effect(
+    ctx: Context,
+    action: (layer: L) => () => void,
+    options: { label: string; notify?: boolean },
+  ): () => void {
+    const scope = scopeOf(ctx)
+    const notify = options.notify ?? true
+    const dispose = ctx.effect(function* (this: ScopedLayers<L>) {
+      let layer: L
+      let created = false
+      if (scope === undefined) {
+        layer = this.global
+      } else {
+        const existing = this.scoped.get(scope)
+        if (existing === undefined) {
+          layer = this.createLayer(scope)
+          this.scoped.set(scope, layer)
+          created = true
+        } else {
+          layer = existing
+        }
+      }
+
+      let undo: () => void
+      try {
+        undo = action(layer)
+      } catch (error) {
+        if (scope !== undefined && created && layer.isEmpty()) this.scoped.delete(scope)
+        throw error
+      }
+
+      yield () => {
+        undo()
+        if (scope !== undefined && layer.isEmpty()) this.scoped.delete(scope)
+        if (notify) this.onChange()
+      }
+      if (notify) this.onChange()
+    }.bind(this), options.label)
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises -- exact synchronous disposer preserves Cordis effect identity
+    return dispose
+  }
+}
diff --git a/packages/core/scope/tests/store.spec.ts b/packages/core/scope/tests/store.spec.ts
new file mode 100644
index 0000000000..9f70d2b527
--- /dev/null
+++ b/packages/core/scope/tests/store.spec.ts
@@ -0,0 +1,263 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import {
+  AnonymousEntries,
+  createScope,
+  NamedEntries,
+  ScopedLayers,
+  type Scope,
+  type ScopeKey,
+  type ScopeLayer,
+} from '@deepseek-ai/dsh-scope'
+
+class TestLayer implements ScopeLayer {
+  readonly named: NamedEntries<number>
+  readonly anonymous = new AnonymousEntries<string>()
+
+  constructor(scope: ScopeKey | undefined) {
+    this.named = new NamedEntries(name =>
+      new Error(`${scope === undefined ? 'global' : 'scoped'} duplicate: ${name}`))
+  }
+
+  isEmpty(): boolean {
+    return this.named.isEmpty() && this.anonymous.isEmpty()
+  }
+}
+
+/** Mint one active scope for lifecycle tests. */
+async function mintScope(ctx: Context, key: ScopeKey): Promise<Scope> {
+  let scope!: Scope
+  await ctx.plugin((inner: Context) => { scope = createScope(inner, key) })
+  return scope
+}
+
+describe('NamedEntries', () => {
+  it('owns duplicate diagnostics, lookup, insertion order, live iteration, and exact idempotent undo', () => {
+    const duplicate = new Error('caller duplicate')
+    const duplicateError = vi.fn(() => duplicate)
+    const entries = new NamedEntries<number>(duplicateError)
+    const undoA = entries.insert('a', 1)
+    const values = entries.values()
+    expect(values.next()).toEqual({ value: 1, done: false })
+    const undoB = entries.insert('b', 2)
+
+    expect([...values]).toEqual([2])
+    expect([...entries.keys()]).toEqual(['a', 'b'])
+    expect([...entries.entries()]).toEqual([['a', 1], ['b', 2]])
+    expect(entries.get('a')).toBe(1)
+    expect(entries.get('missing')).toBeUndefined()
+    expect(entries.has('b')).toBe(true)
+    expect(entries.has('missing')).toBe(false)
+    expect(entries.isEmpty()).toBe(false)
+    expect(() => entries.insert('a', 3)).toThrow(duplicate)
+    expect(duplicateError).toHaveBeenCalledWith('a')
+
+    undoA()
+    entries.insert('a', 3)
+    undoA()
+    expect(entries.get('a')).toBe(3)
+    undoB()
+    expect([...entries.entries()]).toEqual([['a', 3]])
+  })
+})
+
+describe('AnonymousEntries', () => {
+  it('owns equal values independently with live insertion-ordered iteration and idempotent undo', () => {
+    const entries = new AnonymousEntries<object>()
+    const value = {}
+    const undoFirst = entries.append(value)
+    const values = entries.values()
+    expect(values.next()).toEqual({ value, done: false })
+    const undoSecond = entries.append(value)
+
+    expect([...values]).toEqual([value])
+    expect([...entries.values()]).toEqual([value, value])
+    undoFirst()
+    undoFirst()
+    expect([...entries.values()]).toEqual([value])
+    undoSecond()
+    expect(entries.isEmpty()).toBe(true)
+  })
+})
+
+describe('ScopedLayers', () => {
+  it('constructs global state eagerly while reads stay non-creating and merge named shadows in order', () => {
+    const created: Array<ScopeKey | undefined> = []
+    const layers = new ScopedLayers(
+      (scope) => {
+        created.push(scope)
+        return new TestLayer(scope)
+      },
+      vi.fn(),
+    )
+    const key = {}
+    layers.global.named.insert('a', 1)
+    layers.global.named.insert('shared', 2)
+
+    expect(created).toEqual([undefined])
+    expect(layers.peek(undefined)).toBeUndefined()
+    expect(layers.peek(key)).toBeUndefined()
+    expect([...layers.merge(key, layer => layer.named)]).toEqual([['a', 1], ['shared', 2]])
+    expect(created).toEqual([undefined])
+  })
+
+  it('uses the same scoped context for lazy visibility and ownership, and reclaims only an empty aggregate', async () => {
+    const ctx = new Context()
+    const key = {}
+    const scope = await mintScope(ctx, key)
+    const changed = vi.fn()
+    const created: Array<ScopeKey | undefined> = []
+    const layers = new ScopedLayers(
+      (selected) => {
+        created.push(selected)
+        return new TestLayer(selected)
+      },
+      changed,
+    )
+    layers.global.named.insert('a', 1)
+    layers.global.named.insert('shared', 1)
+    const removeNamed = layers.effect(
+      scope.ctx,
+      layer => layer.named.insert('shared', 2),
+      { label: 'test.named', notify: false },
+    )
+    const removeTail = layers.effect(
+      scope.ctx,
+      layer => layer.named.insert('c', 3),
+      { label: 'test.tail', notify: false },
+    )
+    const removeAnonymous = layers.effect(
+      scope.ctx,
+      layer => layer.anonymous.append('kept'),
+      { label: 'test.anonymous', notify: false },
+    )
+
+    expect(created).toEqual([undefined, key])
+    expect([...layers.merge(key, layer => layer.named)]).toEqual([['a', 1], ['shared', 2], ['c', 3]])
+    expect(changed).not.toHaveBeenCalled()
+    removeNamed()
+    expect(layers.peek(key)).toBeDefined()
+    expect([...layers.merge(key, layer => layer.named)]).toEqual([['a', 1], ['shared', 1], ['c', 3]])
+    removeTail()
+    expect(layers.peek(key)).toBeDefined()
+    removeAnonymous()
+    expect(layers.peek(key)).toBeUndefined()
+    await scope.dispose()
+  })
+
+  it('runs action, notification, undo, and disposal notification in order with Cordis idempotence and labels', async () => {
+    const ctx = new Context()
+    const events: string[] = []
+    const layers = new ScopedLayers(
+      scope => new TestLayer(scope),
+      () => void events.push('notify'),
+    )
+    const dispose = layers.effect(
+      ctx,
+      (layer) => {
+        events.push('action')
+        const undo = layer.named.insert('x', 1)
+        return () => {
+          events.push('undo')
+          undo()
+        }
+      },
+      { label: 'store.order' },
+    )
+
+    expect(events).toEqual(['action', 'notify'])
+    expect(ctx.fiber.getEffects().map(effect => effect.label)).toContain('store.order')
+    dispose()
+    dispose()
+    expect(events).toEqual(['action', 'notify', 'undo', 'notify'])
+    expect(layers.global.isEmpty()).toBe(true)
+  })
+
+  it('returns the exact context effect disposer', () => {
+    const rawDispose = vi.fn()
+    const effect = vi.fn(() => rawDispose)
+    const ctx = { effect } as unknown as Context
+    const action = vi.fn(() => vi.fn())
+    const layers = new ScopedLayers(scope => new TestLayer(scope), vi.fn())
+
+    const returned = layers.effect(ctx, action, { label: 'store.identity', notify: false })
+
+    expect(returned).toBe(rawDispose)
+    expect(effect).toHaveBeenCalledWith(expect.any(Function), 'store.identity')
+    expect(action).not.toHaveBeenCalled()
+  })
+
+  it('cleans up failed factories and empty failed actions without discarding an existing layer', async () => {
+    const ctx = new Context()
+    const key = {}
+    const scope = await mintScope(ctx, key)
+    let failFactory = true
+    const layers = new ScopedLayers(
+      (selected) => {
+        if (selected !== undefined && failFactory) throw new Error('factory failed')
+        return new TestLayer(selected)
+      },
+      vi.fn(),
+    )
+
+    expect(() => layers.effect(
+      scope.ctx,
+      layer => layer.named.insert('never', 1),
+      { label: 'store.factory', notify: false },
+    )).toThrow('factory failed')
+    expect(layers.peek(key)).toBeUndefined()
+
+    failFactory = false
+    expect(() => layers.effect(
+      scope.ctx,
+      () => { throw new Error('action failed') },
+      { label: 'store.action', notify: false },
+    )).toThrow('action failed')
+    expect(layers.peek(key)).toBeUndefined()
+
+    const dispose = layers.effect(
+      scope.ctx,
+      layer => layer.named.insert('kept', 1),
+      { label: 'store.kept', notify: false },
+    )
+    expect(() => layers.effect(
+      scope.ctx,
+      () => { throw new Error('second action failed') },
+      { label: 'store.existing-action', notify: false },
+    )).toThrow('second action failed')
+    expect(layers.peek(key)?.named.get('kept')).toBe(1)
+    dispose()
+    await scope.dispose()
+  })
+
+  it('rolls back a scoped insertion when notification throws', async () => {
+    const ctx = new Context()
+    const key = {}
+    const scope = await mintScope(ctx, key)
+    const events: string[] = []
+    let notifications = 0
+    const layers = new ScopedLayers(
+      selected => new TestLayer(selected),
+      () => {
+        events.push('notify')
+        if (++notifications === 1) throw new Error('change failed')
+      },
+    )
+
+    expect(() => layers.effect(
+      scope.ctx,
+      (layer) => {
+        const undo = layer.named.insert('rollback', 1)
+        return () => {
+          events.push('undo')
+          undo()
+        }
+      },
+      { label: 'store.rollback' },
+    )).toThrow('change failed')
+
+    expect(events).toEqual(['notify', 'undo', 'notify'])
+    expect(layers.peek(key)).toBeUndefined()
+    await scope.dispose()
+  })
+})

From 1d209932d6e13ffd2c592090c0a43ff9ecea7747 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 21 Jul 2026 22:14:49 +0800
Subject: [PATCH 59/74] refactor(scope): migrate tool and prompt layers

---
 packages/core/system-prompt/src/index.ts      | 156 +++++++---------
 .../core/system-prompt/tests/scoped.spec.ts   |  17 +-
 .../system-prompt/tests/system-prompt.spec.ts |  36 ++++
 packages/core/tools/src/index.ts              | 168 +++++++-----------
 packages/core/tools/tests/scoped.spec.ts      |  21 +++
 5 files changed, 195 insertions(+), 203 deletions(-)

diff --git a/packages/core/system-prompt/src/index.ts b/packages/core/system-prompt/src/index.ts
index 12171f1b2e..c46c38515c 100644
--- a/packages/core/system-prompt/src/index.ts
+++ b/packages/core/system-prompt/src/index.ts
@@ -6,8 +6,8 @@
 
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
-import { scopeOf, scopeTarget } from '@deepseek-ai/dsh-scope'
-import type { ScopeKey, Scoped } from '@deepseek-ai/dsh-scope'
+import { AnonymousEntries, NamedEntries, ScopedLayers, scopeTarget } from '@deepseek-ai/dsh-scope'
+import type { ScopeKey, ScopeLayer, Scoped } from '@deepseek-ai/dsh-scope'
 import type { ToolSchema } from '@deepseek-ai/dsh-llm'
 
 declare module 'cordis' {
@@ -209,6 +209,39 @@ function interpolate(section: AssembledSection, variables: Record<string, string
   return result + text.slice(last)
 }
 
+/** One tool-schema provider stored in a prompt layer. */
+type ToolProvider = (context: AssembleContext) => ToolProviderResult
+
+/** One prompt-variable provider stored in a prompt layer. */
+type VariableProvider = (context: AssembleContext) => string | undefined
+
+/** All prompt registrations owned by one global or scoped layer. */
+class PromptLayer implements ScopeLayer {
+  readonly sections: NamedEntries<PromptSection>
+  readonly toolProviders = new AnonymousEntries<ToolProvider>()
+  readonly variables: NamedEntries<VariableProvider>
+
+  /**
+   * Create one prompt layer with diagnostics specific to its ownership scope.
+   * @param scope - the scoped owner, or `undefined` for global registrations.
+   */
+  constructor(scope: ScopeKey | undefined) {
+    this.sections = new NamedEntries(name => new Error(scope === undefined
+      ? `prompt section "${name}" is already registered (for a per-agent override, register through that agent's \`agent.ctx\` instead)`
+      : `prompt section "${name}" is already registered in this scope`))
+    this.variables = new NamedEntries(name => new Error(scope === undefined
+      ? `prompt variable "${name}" is already registered (for a per-agent value, register through that agent's \`agent.ctx\` instead)`
+      : `prompt variable "${name}" is already registered in this scope`))
+  }
+
+  /** @returns whether this layer owns no prompt registrations. */
+  isEmpty(): boolean {
+    return this.sections.isEmpty()
+      && this.toolProviders.isEmpty()
+      && this.variables.isEmpty()
+  }
+}
+
 /** Registry service for the prompt inputs assembled before each model step. */
 export class SystemPrompt extends Service {
   static Config: z<Config> = z.object({
@@ -217,13 +250,10 @@ export class SystemPrompt extends Service {
     toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
   })
 
-  private sections: PromptSection[] = []
-  private toolProviders: ((context: AssembleContext) => ToolProviderResult)[] = []
-  private variableProviders = new Map<string, (context: AssembleContext) => string | undefined>()
-  /** Per-scope layers (`@deepseek-ai/dsh-scope`); entries drop when a layer empties, so a disposed scope leaves no residue. */
-  private scopedSections = new Map<ScopeKey, PromptSection[]>()
-  private scopedToolProviders = new Map<ScopeKey, ((context: AssembleContext) => ToolProviderResult)[]>()
-  private scopedVariableProviders = new Map<ScopeKey, Map<string, (context: AssembleContext) => string | undefined>>()
+  private readonly layers = new ScopedLayers(
+    scope => new PromptLayer(scope),
+    () => { this.ctx.emit('system-prompt/change') },
+  )
   private readonly toolOrder: string[] | undefined
 
   constructor(ctx: Context, config: Config) {
@@ -255,34 +285,11 @@ export class SystemPrompt extends Service {
     if (!Number.isFinite(section.order)) {
       throw new TypeError(`prompt section "${section.name}" order must be a finite number`)
     }
-    const scope = scopeOf(this.ctx)
-    const dispose = this.ctx.effect(function* (this: SystemPrompt) {
-      const layer = scope === undefined
-        ? this.sections
-        : this.scopedSections.get(scope) ?? (() => {
-          const created: PromptSection[] = []
-          this.scopedSections.set(scope, created)
-          return created
-        })()
-      if (layer.some(existing => existing.name === section.name)) {
-        throw new Error(scope === undefined
-          ? `prompt section "${section.name}" is already registered (for a per-agent override, register through that agent's \`agent.ctx\` instead)`
-          : `prompt section "${section.name}" is already registered in this scope`)
-      }
-      layer.push(section)
-      // Install rollback before notifying listeners that may throw.
-      yield () => {
-        const index = layer.indexOf(section)
-        /* v8 ignore next 3 -- defensive: section was registered, so indexOf is guaranteed >= 0 */
-        if (index >= 0) layer.splice(index, 1)
-        if (scope !== undefined && layer.length === 0) this.scopedSections.delete(scope)
-        this.ctx.emit('system-prompt/change')
-      }
-      this.ctx.emit('system-prompt/change')
-    }.bind(this), 'systemPrompt.section()')
-    // Return the exact disposer so composite effects preserve teardown order.
-    // eslint-disable-next-line @typescript-eslint/no-misused-promises -- synchronous cleanup; direct return preserves disposer identity
-    return dispose
+    return this.layers.effect(
+      this.ctx,
+      layer => layer.sections.insert(section.name, section),
+      { label: 'systemPrompt.section()' },
+    )
   }
 
   /**
@@ -293,29 +300,11 @@ export class SystemPrompt extends Service {
    * @returns the exact Cordis effect disposer.
    */
   tools(provider: (context: AssembleContext) => ToolProviderResult): () => void {
-    const scope = scopeOf(this.ctx)
-    const dispose = this.ctx.effect(function* (this: SystemPrompt) {
-      const layer = scope === undefined
-        ? this.toolProviders
-        : this.scopedToolProviders.get(scope) ?? (() => {
-          const created: ((context: AssembleContext) => ToolProviderResult)[] = []
-          this.scopedToolProviders.set(scope, created)
-          return created
-        })()
-      layer.push(provider)
-      // Install rollback before notifying listeners that may throw.
-      yield () => {
-        const index = layer.indexOf(provider)
-        /* v8 ignore next 3 -- defensive: provider was registered, so indexOf is guaranteed >= 0 */
-        if (index >= 0) layer.splice(index, 1)
-        if (scope !== undefined && layer.length === 0) this.scopedToolProviders.delete(scope)
-        this.ctx.emit('system-prompt/change')
-      }
-      this.ctx.emit('system-prompt/change')
-    }.bind(this), 'systemPrompt.tools()')
-    // Return the exact disposer so composite effects preserve teardown order.
-    // eslint-disable-next-line @typescript-eslint/no-misused-promises -- synchronous cleanup; direct return preserves disposer identity
-    return dispose
+    return this.layers.effect(
+      this.ctx,
+      layer => layer.toolProviders.append(provider),
+      { label: 'systemPrompt.tools()' },
+    )
   }
 
   /**
@@ -330,32 +319,11 @@ export class SystemPrompt extends Service {
     if (!VARIABLE_NAME.test(name)) {
       throw new Error(`invalid prompt variable name "${name}" (must match ${String(VARIABLE_NAME)})`)
     }
-    const scope = scopeOf(this.ctx)
-    const dispose = this.ctx.effect(function* (this: SystemPrompt) {
-      const layer = scope === undefined
-        ? this.variableProviders
-        : this.scopedVariableProviders.get(scope) ?? (() => {
-          const created = new Map<string, (context: AssembleContext) => string | undefined>()
-          this.scopedVariableProviders.set(scope, created)
-          return created
-        })()
-      if (layer.has(name)) {
-        throw new Error(scope === undefined
-          ? `prompt variable "${name}" is already registered (for a per-agent value, register through that agent's \`agent.ctx\` instead)`
-          : `prompt variable "${name}" is already registered in this scope`)
-      }
-      layer.set(name, provider)
-      // Install rollback before notifying listeners that may throw.
-      yield () => {
-        layer.delete(name)
-        if (scope !== undefined && layer.size === 0) this.scopedVariableProviders.delete(scope)
-        this.ctx.emit('system-prompt/change')
-      }
-      this.ctx.emit('system-prompt/change')
-    }.bind(this), 'systemPrompt.variable()')
-    // Return the exact disposer so composite effects preserve teardown order.
-    // eslint-disable-next-line @typescript-eslint/no-misused-promises -- synchronous cleanup; direct return preserves disposer identity
-    return dispose
+    return this.layers.effect(
+      this.ctx,
+      layer => layer.variables.insert(name, provider),
+      { label: 'systemPrompt.variable()' },
+    )
   }
 
   /**
@@ -370,23 +338,19 @@ export class SystemPrompt extends Service {
     const scope = context.scope
     // Scoped variables shadow globals.
     const variables: Record<string, string | undefined> = {}
-    for (const [name, provider] of this.variableProviders) {
+    for (const [name, provider] of this.layers.global.variables.entries()) {
       variables[name] = provider(context)
     }
-    const scopedVariables = scope === undefined ? undefined : this.scopedVariableProviders.get(scope)
-    for (const [name, provider] of scopedVariables ?? []) {
+    const scopedVariables = this.layers.peek(scope)?.variables
+    for (const [name, provider] of scopedVariables?.entries() ?? []) {
       variables[name] = provider(context)
     }
     // Scoped sections shadow globals before the stable order sort.
-    const sectionByName = new Map<string, PromptSection>()
-    for (const section of this.sections) sectionByName.set(section.name, section)
-    for (const section of (scope === undefined ? [] : this.scopedSections.get(scope)) ?? []) {
-      sectionByName.set(section.name, section)
-    }
+    const sectionByName = this.layers.merge(scope, layer => layer.sections)
     // Validate order against pre-restriction names while collecting visible schemas.
     const providers = [
-      ...this.toolProviders,
-      ...(scope === undefined ? [] : this.scopedToolProviders.get(scope)) ?? [],
+      ...this.layers.global.toolProviders.values(),
+      ...(this.layers.peek(scope)?.toolProviders.values() ?? []),
     ]
     const collected: ToolSchema[] = []
     const knownNames = new Set<string>()
diff --git a/packages/core/system-prompt/tests/scoped.spec.ts b/packages/core/system-prompt/tests/scoped.spec.ts
index aac3f79e88..a3c85b7886 100644
--- a/packages/core/system-prompt/tests/scoped.spec.ts
+++ b/packages/core/system-prompt/tests/scoped.spec.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import { createScope, scopeOf } from '@deepseek-ai/dsh-scope'
 import type { Scope, ScopeKey } from '@deepseek-ai/dsh-scope'
@@ -63,6 +63,21 @@ describe('scoped sections', () => {
     expect(() => scope.ctx.systemPrompt.section({ name: 'y', order: 1, text: 'b' })).toThrow(/already registered in this scope/)
   })
 
+  it('shadows a global section before evaluating either text provider', async () => {
+    const ctx = await mount()
+    const scope = await mintScope(ctx, 'child')
+    const globalText = vi.fn(() => 'global text')
+    const scopedText = vi.fn(() => 'scoped text')
+    ctx.systemPrompt.section({ name: 'shared', order: 1, text: globalText })
+    scope.ctx.systemPrompt.section({ name: 'shared', order: 1, text: scopedText })
+
+    const assembly = await ctx.systemPrompt.assemble({ scope: scopeKeyOf(scope) })
+
+    expect(assembly.sections.find(section => section.name === 'shared')?.text).toBe('scoped text')
+    expect(globalText).not.toHaveBeenCalled()
+    expect(scopedText).toHaveBeenCalledOnce()
+  })
+
 })
 
 describe('scoped variables', () => {
diff --git a/packages/core/system-prompt/tests/system-prompt.spec.ts b/packages/core/system-prompt/tests/system-prompt.spec.ts
index b084104d22..d4fdbdd684 100644
--- a/packages/core/system-prompt/tests/system-prompt.spec.ts
+++ b/packages/core/system-prompt/tests/system-prompt.spec.ts
@@ -157,6 +157,24 @@ describe('SystemPrompt', () => {
     expect((await ctx.systemPrompt.assemble()).tools.map(t => t.name)).toEqual(['t'])
   })
 
+  it('snapshots tool-provider membership before evaluating an assembly', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    let added = false
+    ctx.systemPrompt.tools(() => {
+      if (!added) {
+        added = true
+        ctx.systemPrompt.tools(() => ({
+          schemas: [{ name: 'late', description: '', parameters: {} }],
+        }))
+      }
+      return { schemas: [{ name: 'first', description: '', parameters: {} }] }
+    })
+
+    expect((await ctx.systemPrompt.assemble()).tools.map(tool => tool.name)).toEqual(['first'])
+    expect((await ctx.systemPrompt.assemble()).tools.map(tool => tool.name)).toEqual(['first', 'late'])
+  })
+
   it('rolls back a variable when a system-prompt/change listener throws (P1-1)', async () => {
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
@@ -314,6 +332,24 @@ describe('SystemPrompt', () => {
       expect((await ctx.systemPrompt.assemble()).variables).toEqual({})
     })
 
+    it('live-iterates variables registered by an earlier provider', async () => {
+      const ctx = new Context()
+      await ctx.plugin(SystemPrompt)
+      let added = false
+      ctx.systemPrompt.variable('first', () => {
+        if (!added) {
+          added = true
+          ctx.systemPrompt.variable('late', () => 'second value')
+        }
+        return 'first value'
+      })
+
+      expect((await ctx.systemPrompt.assemble()).variables).toEqual({
+        first: 'first value',
+        late: 'second value',
+      })
+    })
+
     it('rejects a duplicate variable name and an unreferenceable name', async () => {
       const ctx = new Context()
       await ctx.plugin(SystemPrompt)
diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts
index 086d6a3271..11f57995e9 100644
--- a/packages/core/tools/src/index.ts
+++ b/packages/core/tools/src/index.ts
@@ -6,8 +6,8 @@
 
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
-import { scopeOf, scopeTarget } from '@deepseek-ai/dsh-scope'
-import type { ScopeKey, Scoped } from '@deepseek-ai/dsh-scope'
+import { AnonymousEntries, NamedEntries, ScopedLayers, scopeOf, scopeTarget } from '@deepseek-ai/dsh-scope'
+import type { ScopeKey, ScopeLayer, Scoped } from '@deepseek-ai/dsh-scope'
 import type { CallId, ContentBlock, ToolSchema } from '@deepseek-ai/dsh-llm'
 import { assertNever, deepFreeze, HarnessError } from '@deepseek-ai/dsh-llm'
 import type { Agent, HookContext } from '@deepseek-ai/dsh-agent'
@@ -463,9 +463,40 @@ interface ToolView {
  */
 export type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined
 
-/** One guard registration; the wrapper preserves independent duplicate registrations. */
-interface ToolGuardRegistration {
-  guard: ToolGuard
+/** One scope's complete tool-registry contribution. */
+class ToolLayer implements ScopeLayer {
+  readonly tools: NamedEntries<ToolDefinition>
+  readonly restrictions = new AnonymousEntries<CompiledToolRestriction>()
+  readonly guards = new AnonymousEntries<ToolGuard>()
+
+  constructor(scope: ScopeKey | undefined) {
+    this.tools = new NamedEntries(name => new Error(scope === undefined
+      ? `tool "${name}" is already registered (for a per-agent variant, register through that agent's \`agent.ctx\` instead)`
+      : `tool "${name}" is already registered in this scope`))
+  }
+
+  /** Whether every contribution table in this aggregate layer is empty. */
+  isEmpty(): boolean {
+    return this.tools.isEmpty() && this.restrictions.isEmpty() && this.guards.isEmpty()
+  }
+
+  /** Whether every compiled restriction in this layer admits a global tool name. */
+  admits(name: string): boolean {
+    for (const filter of this.restrictions.values()) {
+      if ((filter.allow !== undefined && !filter.allow.has(name))
+        || (filter.deny !== undefined && filter.deny.has(name))) return false
+    }
+    return true
+  }
+
+  /** First monotonic denial from this layer's live guard registrations. */
+  guardReason(exec: ToolExecution): string | undefined {
+    for (const guard of this.guards.values()) {
+      const reason = guard(exec)
+      if (reason !== undefined) return reason
+    }
+    return undefined
+  }
 }
 
 /** Approval decision plus whether the approval channel reported cancellation. */
@@ -509,13 +540,10 @@ export class ToolRegistry extends Service {
   private deferredContexts = new WeakMap<ToolRunContext, HookContext[]>()
   /** Original caller cancellation, kept outside the wrapper-mutable execution object. */
   private cancellationStates = new WeakMap<ToolRunContext, ToolCancellationState>()
-  private global = new Map<string, ToolDefinition>()
-  private scoped = new Map<ScopeKey, Map<string, ToolDefinition>>()
-  /** Compiled restriction filters, per scope (see {@link restrict}). */
-  private restrictions = new Map<ScopeKey, CompiledToolRestriction[]>()
-  /** Monotonic post-policy guards, split into global and per-agent layers. */
-  private globalGuards = new Set<ToolGuardRegistration>()
-  private scopedGuards = new Map<ScopeKey, Set<ToolGuardRegistration>>()
+  private readonly layers = new ScopedLayers(
+    scope => new ToolLayer(scope),
+    () => { this.ctx.emit('tools/change') },
+  )
   private readonly mode: ToolPresentationMode
   /** Reserved presentation transport, kept outside the filterable registration layers. */
   private readonly codeTransport: ToolDefinition | undefined
@@ -593,7 +621,6 @@ export class ToolRegistry extends Service {
    * @returns the exact disposer that unregisters the tool.
    */
   register(definition: ToolDefinition): () => void {
-    const scope = scopeOf(this.ctx)
     const name = definition.name
     const timeoutMs = definition.timeoutMs
     if (timeoutMs !== undefined
@@ -603,26 +630,11 @@ export class ToolRegistry extends Service {
     if (this.codeTransport !== undefined && name === RUN_CODE_NAME) {
       throw new Error(`tool name "${RUN_CODE_NAME}" is reserved for the Code Mode presentation transport and cannot be registered or shadowed`)
     }
-    const dispose = this.ctx.effect(function* (this: ToolRegistry) {
-      const layer = scope === undefined ? this.global : this.layerFor(scope)
-      if (layer.has(name)) {
-        throw new Error(scope === undefined
-          ? `tool "${name}" is already registered (for a per-agent variant, register through that agent's \`agent.ctx\` instead)`
-          : `tool "${name}" is already registered in this scope`)
-      }
-      layer.set(name, definition)
-      // Install rollback before notifying listeners.
-      yield () => {
-        layer.delete(name)
-        // Drop empty scope layers.
-        if (scope !== undefined && layer.size === 0) this.scoped.delete(scope)
-        this.ctx.emit('tools/change')
-      }
-      this.ctx.emit('tools/change')
-    }.bind(this), 'tools.register()')
-    // Return the exact disposer so composite effects preserve teardown order.
-    // eslint-disable-next-line @typescript-eslint/no-misused-promises -- synchronous cleanup; direct return preserves disposer identity
-    return dispose
+    return this.layers.effect(
+      this.ctx,
+      layer => layer.tools.insert(name, definition),
+      { label: 'tools.register()' },
+    )
   }
 
   /**
@@ -655,22 +667,11 @@ export class ToolRegistry extends Service {
     if (unknown.length > 0) {
       throw new Error(`tools.restrict() names unknown global tool${unknown.length > 1 ? 's' : ''} ${unknown.map(n => `"${n}"`).join(', ')}; known global tools: ${[...known].sort().join(', ') || '(none)'}`)
     }
-    const dispose = this.ctx.effect(function* (this: ToolRegistry) {
-      const list = this.restrictions.get(scope) ?? []
-      this.restrictions.set(scope, list)
-      list.push(compiled)
-      yield () => {
-        const index = list.indexOf(compiled)
-        /* v8 ignore next 3 -- defensive: the compiled restriction was pushed, so indexOf is guaranteed >= 0 */
-        if (index >= 0) list.splice(index, 1)
-        if (list.length === 0) this.restrictions.delete(scope)
-        this.ctx.emit('tools/change')
-      }
-      this.ctx.emit('tools/change')
-    }.bind(this), 'tools.restrict()')
-    // Return the exact disposer so composite effects preserve teardown order.
-    // eslint-disable-next-line @typescript-eslint/no-misused-promises -- synchronous cleanup; direct return preserves disposer identity
-    return dispose
+    return this.layers.effect(
+      this.ctx,
+      layer => layer.restrictions.append(compiled),
+      { label: 'tools.restrict()' },
+    )
   }
 
   /**
@@ -684,63 +685,18 @@ export class ToolRegistry extends Service {
    * @returns the exact disposer that unregisters the guard.
    */
   guard(guard: ToolGuard): () => void {
-    const scope = scopeOf(this.ctx)
-    const registration = { guard }
-    const dispose = this.ctx.effect(function* (this: ToolRegistry) {
-      const layer = scope === undefined ? this.globalGuards : this.guardLayerFor(scope)
-      layer.add(registration)
-      yield () => {
-        layer.delete(registration)
-        if (scope !== undefined && layer.size === 0) this.scopedGuards.delete(scope)
-      }
-    }.bind(this), 'tools.guard()')
-    // eslint-disable-next-line @typescript-eslint/no-misused-promises -- synchronous cleanup; direct return preserves disposer identity
-    return dispose
-  }
-
-  /** The (created-on-demand) scoped layer for `scope`. */
-  private layerFor(scope: ScopeKey): Map<string, ToolDefinition> {
-    let layer = this.scoped.get(scope)
-    if (!layer) {
-      layer = new Map()
-      this.scoped.set(scope, layer)
-    }
-    return layer
-  }
-
-  /** Get or create the guard layer for one agent scope. */
-  private guardLayerFor(scope: ScopeKey): Set<ToolGuardRegistration> {
-    let layer = this.scopedGuards.get(scope)
-    if (layer === undefined) {
-      layer = new Set()
-      this.scopedGuards.set(scope, layer)
-    }
-    return layer
+    return this.layers.effect(
+      this.ctx,
+      layer => layer.guards.append(guard),
+      { label: 'tools.guard()', notify: false },
+    )
   }
 
   /** First monotonic denial from the global then matching scoped guard layers. */
   private guardReason(exec: ToolExecution): string | undefined {
-    for (const { guard } of this.globalGuards) {
-      const reason = guard(exec)
-      if (reason !== undefined) return reason
-    }
-    if (exec.agent !== undefined) {
-      for (const { guard } of this.scopedGuards.get(exec.agent) ?? []) {
-        const reason = guard(exec)
-        if (reason !== undefined) return reason
-      }
-    }
-    return undefined
-  }
-
-  /** Whether every restriction registered for `scope` admits the global tool `name` (intersection semantics). */
-  private admits(scope: ScopeKey | undefined, name: string): boolean {
-    if (scope === undefined) return true
-    const filters = this.restrictions.get(scope)
-    if (!filters) return true
-    return filters.every(filter =>
-      (filter.allow === undefined || filter.allow.has(name))
-      && (filter.deny === undefined || !filter.deny.has(name)))
+    const globalReason = this.layers.global.guardReason(exec)
+    if (globalReason !== undefined) return globalReason
+    return exec.agent === undefined ? undefined : this.layers.peek(exec.agent)?.guardReason(exec)
   }
 
   /**
@@ -752,18 +708,18 @@ export class ToolRegistry extends Service {
    * @returns the complete derived view for that scope.
    */
   private view(scope?: ScopeKey): ToolView {
-    const layer = scope === undefined ? undefined : this.scoped.get(scope)
+    const layer = this.layers.peek(scope)
     const visible = new Map<string, ToolDefinition>()
     const knownNames = new Set<string>()
     const restrictableNames = new Set<string>()
-    for (const [name, definition] of this.global) {
+    for (const [name, definition] of this.layers.global.tools.entries()) {
       knownNames.add(name)
       restrictableNames.add(name)
-      if (this.admits(scope, name)) visible.set(name, definition)
+      if (layer?.admits(name) ?? true) visible.set(name, definition)
     }
     // Scoped layer second: same-name entries REPLACE (shadow) the global ones,
     // and scope-local registrations are never part of the global filter above.
-    for (const [name, definition] of layer ?? []) {
+    for (const [name, definition] of layer?.tools.entries() ?? []) {
       knownNames.add(name)
       visible.set(name, definition)
     }
diff --git a/packages/core/tools/tests/scoped.spec.ts b/packages/core/tools/tests/scoped.spec.ts
index ab3b869953..cab0ee7155 100644
--- a/packages/core/tools/tests/scoped.spec.ts
+++ b/packages/core/tools/tests/scoped.spec.ts
@@ -266,6 +266,27 @@ describe('scoped execution dispatch', () => {
     expect(bodyCalls).toBe(0)
   })
 
+  it('live-iterates a guard registered by an earlier guard', async () => {
+    const ctx = await mount()
+    const calls: string[] = []
+    let added = false
+    ctx.tools.register(tool('t'))
+    ctx.tools.guard(() => {
+      calls.push('first')
+      if (!added) {
+        added = true
+        ctx.tools.guard(() => {
+          calls.push('late')
+          return 'late denial'
+        })
+      }
+      return undefined
+    })
+
+    expect(await run(ctx, 't')).toBe('Error: late denial')
+    expect(calls).toEqual(['first', 'late'])
+  })
+
   it('shares one token and materialized argument value across the pipeline', async () => {
     const ctx = await mount()
     const { scope, key } = await mintAgentScope(ctx, 'a')

From e56bcb4d5ce669b438ad2d083d437c7eea86cec0 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 21 Jul 2026 22:16:06 +0800
Subject: [PATCH 60/74] refactor(commands): use shared scoped layers

---
 packages/ui/commands/src/index.ts           | 67 ++++++++++-----------
 packages/ui/commands/tests/commands.spec.ts | 13 ++++
 2 files changed, 45 insertions(+), 35 deletions(-)

diff --git a/packages/ui/commands/src/index.ts b/packages/ui/commands/src/index.ts
index 16e665e71f..56f88a9f20 100644
--- a/packages/ui/commands/src/index.ts
+++ b/packages/ui/commands/src/index.ts
@@ -5,8 +5,8 @@
 
 import { Context, Service } from 'cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import { scopeOf } from '@deepseek-ai/dsh-scope'
-import type { ScopeKey } from '@deepseek-ai/dsh-scope'
+import { NamedEntries, ScopedLayers } from '@deepseek-ai/dsh-scope'
+import type { ScopeKey, ScopeLayer } from '@deepseek-ai/dsh-scope'
 
 export const name = 'commands'
 
@@ -68,6 +68,26 @@ interface RegisteredCommand {
   readonly descriptor: CommandDescriptor
 }
 
+/** All command registrations owned by one global or scoped layer. */
+class CommandLayer implements ScopeLayer {
+  readonly commands: NamedEntries<RegisteredCommand>
+
+  /**
+   * Create one command layer with diagnostics specific to its ownership scope.
+   * @param scope - the scoped owner, or `undefined` for global registrations.
+   */
+  constructor(scope: ScopeKey | undefined) {
+    this.commands = new NamedEntries(name => new Error(scope === undefined
+      ? `command "${name}" is already registered (for a per-agent variant, mount a command-injected plugin under that agent's \`agent.ctx\`)`
+      : `command "${name}" is already registered in this scope`))
+  }
+
+  /** @returns whether this layer owns no command registrations. */
+  isEmpty(): boolean {
+    return this.commands.isEmpty()
+  }
+}
+
 declare module 'cordis' {
   interface Context {
     commands: CommandService
@@ -205,8 +225,10 @@ function normalizeResult(command: string, value: unknown): CommandResult {
  * globals for that agent.
  */
 export class CommandService extends Service {
-  private readonly global = new Map<string, RegisteredCommand>()
-  private readonly scoped = new Map<ScopeKey, Map<string, RegisteredCommand>>()
+  private readonly layers = new ScopedLayers(
+    scope => new CommandLayer(scope),
+    () => { this.notifyChange() },
+  )
 
   constructor(ctx: Context) {
     super(ctx, 'commands')
@@ -218,25 +240,12 @@ export class CommandService extends Service {
    * @returns the exact effect disposer that unregisters this definition.
    */
   register(definition: CommandDefinition): () => void {
-    const scope = scopeOf(this.ctx)
     const registered = normalizeDefinition(definition)
-    const dispose = this.ctx.effect(function* (this: CommandService) {
-      const layer = scope === undefined ? this.global : this.layerFor(scope)
-      if (layer.has(registered.definition.name)) {
-        throw new Error(scope === undefined
-          ? `command "${registered.definition.name}" is already registered (for a per-agent variant, mount a command-injected plugin under that agent's \`agent.ctx\`)`
-          : `command "${registered.definition.name}" is already registered in this scope`)
-      }
-      layer.set(registered.definition.name, registered)
-      yield () => {
-        layer.delete(registered.definition.name)
-        if (scope !== undefined && layer.size === 0) this.scoped.delete(scope)
-        this.notifyChange()
-      }
-      this.notifyChange()
-    }.bind(this), 'commands.register()')
-    // eslint-disable-next-line @typescript-eslint/no-misused-promises -- exact synchronous disposer preserves composite teardown order
-    return dispose
+    return this.layers.effect(
+      this.ctx,
+      layer => layer.commands.insert(registered.definition.name, registered),
+      { label: 'commands.register()' },
+    )
   }
 
   /**
@@ -285,19 +294,7 @@ export class CommandService extends Service {
 
   /** Resolve global definitions followed by exact scoped shadows. */
   private view(agent: Agent): Map<string, RegisteredCommand> {
-    const visible = new Map(this.global)
-    for (const [name, command] of this.scoped.get(agent) ?? []) visible.set(name, command)
-    return visible
-  }
-
-  /** Create the registration layer for one agent scope on demand. */
-  private layerFor(scope: ScopeKey): Map<string, RegisteredCommand> {
-    let layer = this.scoped.get(scope)
-    if (layer === undefined) {
-      layer = new Map()
-      this.scoped.set(scope, layer)
-    }
-    return layer
+    return this.layers.merge(agent, layer => layer.commands)
   }
 
   /** Notify every registry observer without making UI refresh load-bearing. */
diff --git a/packages/ui/commands/tests/commands.spec.ts b/packages/ui/commands/tests/commands.spec.ts
index 839ccb0297..7b6fefb2d2 100644
--- a/packages/ui/commands/tests/commands.spec.ts
+++ b/packages/ui/commands/tests/commands.spec.ts
@@ -94,6 +94,19 @@ describe('CommandService', () => {
     expect((await ctx.commands.execute(agent, '/shared', new AbortController().signal))?.text).toBe('global')
   })
 
+  it('removes a registration when its contributing plugin fiber is disposed', async () => {
+    const ctx = await mount()
+    const { agent } = await mintAgentScope(ctx, 'a')
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      inner.commands.register(command('temporary'))
+    }, { inject: ['commands'] }))
+    expect(ctx.commands.find(agent, 'temporary')).toBeDefined()
+
+    await fiber.dispose()
+
+    expect(ctx.commands.find(agent, 'temporary')).toBeUndefined()
+  })
+
   it('rejects duplicates within one layer while allowing a scoped shadow', async () => {
     const ctx = await mount()
     const { scope } = await mintAgentScope(ctx, 'a')

From 04d7b435d28a70eae8802ff11ec19187ad8db3ac Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 21 Jul 2026 22:24:45 +0800
Subject: [PATCH 61/74] docs(scope): record shared scoped-layer decision

---
 .../2026-07-12-agent-scope-runtime-design.md  | 10 +++---
 .../2026-07-12-scoped-layers-store.i18n.yaml  |  4 +--
 .../2026-07-12-scoped-layers-store.md         | 33 ++++++++++---------
 .../2026-07-12-scoped-layers-store.zh.md      | 33 ++++++++++---------
 docs/architecture.md                          |  4 +--
 docs/cordis-catalog/events.md                 |  2 +-
 docs/cordis-catalog/services.md               |  6 ++--
 docs/core-data-structures/scope.md            | 20 +++++++++--
 docs/event-producer-consumer.md               |  2 +-
 packages/core/scope/README.md                 |  6 ++++
 scripts/type-equiv.manifest.json              |  1 +
 11 files changed, 75 insertions(+), 46 deletions(-)
 rename .agents/notes/{proposed => implemented}/architecture/2026-07-12-scoped-layers-store.i18n.yaml (65%)
 rename .agents/notes/{proposed => implemented}/architecture/2026-07-12-scoped-layers-store.md (64%)
 rename .agents/notes/{proposed => implemented}/architecture/2026-07-12-scoped-layers-store.zh.md (67%)

diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
index eb7b1d873d..e0de18e90a 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
@@ -12,13 +12,13 @@ The implementation needs enough state to preserve real ownership and settlement
 
 ## Decision
 
-The runtime uses one mechanism per independent fact. Scope routing has an opaque carrier; each live registry object has one entry record; each create or resume operation has one transaction; typed same-process calls borrow readonly values; real data boundaries materialize once; the cooperative prompt-assembly result is authoritative; and worker/process code retains separate terminal and quiescence state only where different owners can genuinely race.
+The runtime uses one mechanism per independent fact. Scope routing has an opaque carrier and shared layer store; each live registry object has one entry record; each create or resume operation has one transaction; typed same-process calls borrow readonly values; real data boundaries materialize once; the cooperative prompt-assembly result is authoritative; and worker/process code retains separate terminal and quiescence state only where different owners can genuinely race.
 
 The design can be skimmed as seven choices:
 
 | Problem | Authoritative mechanism |
 |---|---|
-| Select global plus one agent's registrations | Opaque scope key and routing carrier |
+| Select global plus one agent's registrations | Opaque scope key, routing carrier, and shared layer store |
 | Own one live agent or session | One registry entry captured by its disposer |
 | Coordinate create/resume | One `AgentCreationTransaction` |
 | Protect durable, queued, model, or wire data | Materialize once at that boundary |
@@ -68,11 +68,11 @@ A `ScopeKey` is an opaque object compared by identity. The harness uses the live
 
 The receiver is a small carrier rather than a transparent proxy for the domain object. Code that needs the agent receives the explicit event argument; code that needs registration ownership receives `agent.ctx`.
 
-### Registry reads overlay one exact map
+### Registry reads overlay one exact layer
 
-Scope-aware registries store global contributions separately from identity-keyed local contributions. A read resolves the global layer and at most one local layer; it never traverses parentage.
+Scope-aware registries use `ScopedLayers` to own one eager global aggregate and lazily created identity-keyed aggregates. A read resolves the global layer and at most one exact local layer; it never creates state or traverses parentage. Registration visibility and Cordis effect ownership derive from the same context, and reclamation waits until the concrete layer's complete aggregate is empty ([decision](2026-07-12-scoped-layers-store.md)).
 
-Each service retains its domain rule. Named prompt values and tools use local shadowing, tool restrictions filter globals before local tools are added, and events select listener audiences rather than registered data. Scope supplies identity and ownership, not a universal merge algorithm.
+Each service retains its domain rule. Named command and prompt views use the shared insertion-ordered shadow merge; tools keep a richer resolver because restrictions filter globals before local tools are added and the reserved Code Mode transport is inserted separately. Prompt variables and tool guards retain live iteration, while tool-provider membership is materialized per assembly. Scope supplies storage lifecycle and named shadowing, not a universal registry view.
 
 ### Fused dispatch helpers prevent subject drift
 
diff --git a/.agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.i18n.yaml
similarity index 65%
rename from .agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml
rename to .agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.i18n.yaml
index 40694cc6d2..4ece091d15 100644
--- a/.agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-12-scoped-layers-store.md: 64d565542e39a5ffcea98bc3343504760f31a416
-2026-07-12-scoped-layers-store.zh.md: ebe823b980864f4f24d4888312a73d2a5ee34fb5
+2026-07-12-scoped-layers-store.md: 5ba91f33eb079a44f966d7f0b5ff097ff529e700
+2026-07-12-scoped-layers-store.zh.md: c84792e468a435e2463b5ff682fad8a8129189ed
diff --git a/.agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.md b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md
similarity index 64%
rename from .agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.md
rename to .agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md
index 64d565542e..5ba91f33eb 100644
--- a/.agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md
@@ -1,14 +1,14 @@
 # Agent Note: Shared scoped-layer storage
 
-Status: proposed
+Status: implemented
 
 English | [中文](2026-07-12-scoped-layers-store.zh.md)
 
 ## Problem
 
-Agent scoping ([decision](../../implemented/architecture/2026-07-08-agent-scope-contexts.md), [runtime design](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)) gives scope-aware registries the same recurring shape: one global registration layer plus one exact agent layer. Seven registration facades implement that shape independently: `tools.register`, `tools.restrict`, and `tools.guard` in `dsh-tools`; `SystemPrompt.section`, `SystemPrompt.tools`, and `SystemPrompt.variable` in `dsh-system-prompt`; and `CommandService.register` in `dsh-commands`.
+Agent scoping ([decision](2026-07-08-agent-scope-contexts.md), [runtime design](2026-07-12-agent-scope-runtime-design.md)) gives scope-aware registries the same recurring shape: one global registration layer plus one exact agent layer. Seven registration facades use that shape: `tools.register`, `tools.restrict`, and `tools.guard` in `dsh-tools`; `SystemPrompt.section`, `SystemPrompt.tools`, and `SystemPrompt.variable` in `dsh-system-prompt`; and `CommandService.register` in `dsh-commands`.
 
-Each facade repeats the lifecycle choreography around its domain state: derive visibility from the calling context, create a scoped container on demand, attach ownership to the same Cordis fiber, install undo before notifying observers, return Cordis's exact disposer, and reclaim empty scoped state. The copies use separate maps and collection types, so a service has no object representing one scope's complete contribution and must reproduce cleanup for every table.
+Without a shared primitive, each facade repeats the lifecycle choreography around its domain state: derive visibility from the calling context, create a scoped container on demand, attach ownership to the same Cordis fiber, install undo before notifying observers, return Cordis's exact disposer, and reclaim empty scoped state. Separate maps and collection types also leave a service without one object representing a scope's complete contribution.
 
 The duplicated code carries three non-obvious requirements:
 
@@ -18,9 +18,9 @@ The duplicated code carries three non-obvious requirements:
 
 The shared part is lifecycle and insertion-ordered storage, not registry policy. Tool restrictions, reserved transport handling, prompt evaluation timing, command normalization, exact diagnostics, and callback containment remain different domain contracts.
 
-## Proposal
+## Decision
 
-`@deepseek-ai/dsh-scope` gains a key-agnostic `store.ts` implementation module. The package continues to peer on Cordis and `@deepseek-ai/dsh-invariants`, and its invariant companion remains unchanged. The package root exports four storage symbols: `ScopeLayer`, `ScopedLayers`, `NamedEntries`, and `AnonymousEntries`. `EntryValues` remains internal, and `store.ts` is not a package subpath.
+`@deepseek-ai/dsh-scope` provides a key-agnostic `store.ts` implementation module. The package continues to peer on Cordis and `@deepseek-ai/dsh-invariants`, and its invariant companion remains unchanged. The package root exports four storage symbols: `ScopeLayer`, `ScopedLayers`, `NamedEntries`, and `AnonymousEntries`. `EntryValues` remains internal, and `store.ts` is not a package subpath.
 
 `ScopeLayer` keeps the aggregate concept explicit while requiring only whole-layer emptiness. A service defines one concrete layer whose tables and domain helpers fit that service; `ScopedLayers` owns construction, selection, lifecycle attachment, notification, and aggregate reclamation.
 
@@ -108,16 +108,19 @@ All seven facades keep validation and diagnostics in their owning registry and c
 
 **Generate layers from a mapped-type table description.** Three-table and one-table concrete layers are short, inspectable, and free to hold domain helpers. A class generator would add a second construction model and generated runtime shape for little leverage.
 
-## Acceptance criteria
+## Consequences
 
-- `dsh-scope` exports exactly the four proposed storage symbols from its root and covers global construction, lazy scoped construction, non-creating reads, named shadowing, aggregate reclamation, failure cleanup, notification ordering, exact disposer identity, caller-owned duplicate errors, independent anonymous duplicates, and live iterators.
-- `dsh-tools`, `dsh-system-prompt`, and `dsh-commands` migrate all seven registration facades while preserving validation order, exact diagnostics, views, notification policy, re-entrancy, and HMR disposal.
-- The `dsh-scope` README and scoped core-data documentation describe the public contract; architecture and runtime-design references identify the shared store without duplicating it. Consumer READMEs remain focused on their unchanged public behavior.
-- This pair moves to `implemented/architecture` in the implementation PR, changes `Proposal` to present-tense `Decision`, and records shipped consequences and verification. Existing keyless snapshots remain byte-identical.
+- Scope-aware registries express one aggregate layer and reuse the same construction, ownership, rollback, notification, and reclamation choreography. Domain-specific validation, diagnostics, filtering, evaluation, and observer policy remain in each registry.
+- The public read surface stays narrow: direct table iteration preserves explicitly live behavior, while `merge()` is the one shared materialized shadowing operation. A heterogeneous `ScopeLayer` has no layer-wide `values()` contract.
+- The helper is deliberately synchronous. A future registration that needs asynchronous setup or several independently owned undos must identify its ownership and settlement boundaries before widening this contract.
+- An action must throw before retaining a contribution or return an undo for everything it retained; the helper cannot repair mutation outside that contract. The provided entry operations are atomic, and migrated registries perform fallible validation before insertion.
+- A scoped layer remains allocated until every table in its aggregate is empty. Disposing one facade therefore cannot discard sibling contributions owned by the same scope.
+- The four public symbols become a reusable package contract. Keeping `EntryValues` internal and consumer policy outside the helper limits the compatibility surface.
+- The migration changes no public registry behavior and no model-, human-, wire-, persistence-, configuration-, or dependency-graph output.
 
-## Risks
+## Verification
 
-- A future registration may need asynchronous setup or several independently owned undos. That consumer must identify its ownership and settlement boundary before widening this deliberately synchronous interface.
-- A throwing action that mutates outside the returned undo contract cannot be repaired generically. Entry operations are atomic, migrations perform fallible validation before insertion, and tests pin cleanup for factory and pre-retention action failures.
-- Aggregate reclamation keeps a scoped layer alive until every table empties. This is intentional and observable only as internal storage lifetime; tests pin that one table's disposal does not discard sibling contributions.
-- The public classes add a reusable package contract. Keeping reads narrow and domain policy in consumers limits how much future code must preserve.
+- `dsh-scope` unit tests cover global construction, lazy scoped construction, non-creating reads, named merge order and shadowing, aggregate reclamation, factory and action failure cleanup, notification ordering and rollback, `notify: false`, effect labels, exact disposer identity, idempotent teardown, caller-owned duplicate errors, independent anonymous duplicates, and live iterators.
+- Focused tool, system-prompt, and command suites cover restrictions, reserved transport handling, known/restrictable-name agreement, guard re-entrancy, validation order, exact diagnostics, section shadow-before-evaluate, provider snapshot membership, variable re-entrancy, contained command observers, frozen and sorted views, direct execution, and lifecycle disposal.
+- The scoped core-data type-equivalence check ties `ScopeLayer` documentation to its source declaration. Repository documentation, module-graph, build, hygiene, coverage, and built-artifact gates exercise the root export and package boundary.
+- Existing ACP, headless, and TUI keyless snapshots remain the regression boundary for tool schemas, prompt assembly, and human commands. The implementation does not update any expected transcript.
diff --git a/.agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.zh.md b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.zh.md
similarity index 67%
rename from .agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.zh.md
rename to .agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.zh.md
index ebe823b980..c84792e468 100644
--- a/.agents/notes/proposed/architecture/2026-07-12-scoped-layers-store.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.zh.md
@@ -1,14 +1,14 @@
 # Agent Note: 共享作用域分层存储
 
-Status: proposed
+Status: implemented
 
 [English](2026-07-12-scoped-layers-store.md) | 中文
 
 ## 问题
 
-agent（智能体）作用域机制（[决策](../../implemented/architecture/2026-07-08-agent-scope-contexts.md)、[运行时设计](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)）让支持作用域的注册表反复呈现同一种形态：一个全局注册层，加上一个与具体 agent 精确对应的层。七个注册门面各自独立实现这一形态：`tools.register`、`tools.restrict` 和 `tools.guard`（位于 `dsh-tools`）；`SystemPrompt.section`、`SystemPrompt.tools` 和 `SystemPrompt.variable`（位于 `dsh-system-prompt`）；以及 `CommandService.register`（位于 `dsh-commands`）。
+agent（智能体）作用域机制（[决策](2026-07-08-agent-scope-contexts.md)、[运行时设计](2026-07-12-agent-scope-runtime-design.md)）让支持作用域的注册表反复呈现同一种形态：一个全局注册层，加上一个与具体 agent 精确对应的层。七个注册门面都采用这一形态：`tools.register`、`tools.restrict` 和 `tools.guard`（位于 `dsh-tools`）；`SystemPrompt.section`、`SystemPrompt.tools` 和 `SystemPrompt.variable`（位于 `dsh-system-prompt`）；以及 `CommandService.register`（位于 `dsh-commands`）。
 
-每个门面都围绕自己的领域状态重复相同的生命周期编排：从调用方上下文导出可见性，按需创建专属容器，把属主绑定到同一个 Cordis fiber，先装入 undo 再通知观察者，原样返回 Cordis 的 disposer，并回收空的专属状态。各份实现采用不同的映射与集合类型，因此服务内没有一个对象能表示某个 scope 的完整贡献，而且每张表都必须重复清理逻辑。
+如果没有共享原语，每个门面都要围绕自己的领域状态重复相同的生命周期编排：从调用方上下文导出可见性，按需创建专属容器，把属主绑定到同一个 Cordis fiber，先装入 undo 再通知观察者，原样返回 Cordis 的 disposer，并回收空的专属状态。各自分离的映射与集合类型也会让服务缺少一个表示某个 scope 完整贡献的对象。
 
 重复代码承载着三项不明显的要求：
 
@@ -18,9 +18,9 @@ agent（智能体）作用域机制（[决策](../../implemented/architecture/20
 
 共享的是生命周期与保持插入顺序的存储，而不是注册表策略。工具限制、保留传输处理、提示词求值时机、命令规范化、精确诊断和回调异常隔离，仍分别属于不同的领域契约。
 
-## 提案
+## 决策
 
-`@deepseek-ai/dsh-scope` 新增与键类型无关的 `store.ts` 实现模块。该包（package）继续将 Cordis 和 `@deepseek-ai/dsh-invariants` 列为对等依赖（peer dependency），其不变量配套模块保持不变。包根导出四个存储符号：`ScopeLayer`、`ScopedLayers`、`NamedEntries` 和 `AnonymousEntries`。`EntryValues` 仍是内部接口，`store.ts` 不是包子路径。
+`@deepseek-ai/dsh-scope` 提供与键类型无关的 `store.ts` 实现模块。该包（package）继续将 Cordis 和 `@deepseek-ai/dsh-invariants` 列为对等依赖（peer dependency），其不变量配套模块保持不变。包根导出四个存储符号：`ScopeLayer`、`ScopedLayers`、`NamedEntries` 和 `AnonymousEntries`。`EntryValues` 仍是内部接口，`store.ts` 不是包子路径。
 
 `ScopeLayer` 保留显式的聚合概念，同时只要求判断整个层是否为空。服务定义一个具体层，使其表结构与领域 helper 适合该服务；`ScopedLayers` 负责构造、选择、生命周期挂接、通知和聚合回收。
 
@@ -108,16 +108,19 @@ export class AnonymousEntries<V> {
 
 **通过 mapped-type 表描述生成层。** 三表与单表具体层都很短、易于检查，并可自由持有领域 helper。类生成器会增加第二种构造模型和生成式运行时形状，收益却很小。
 
-## 验收标准
+## 后果
 
-- `dsh-scope` 从包根恰好导出拟议的四个存储符号，并覆盖全局构造、专属层延迟构造、非创建式读取、命名遮蔽、聚合回收、失败清理、通知顺序、原始 disposer 身份、调用方拥有的重名错误、相同匿名值的独立登记和活迭代器。
-- `dsh-tools`、`dsh-system-prompt` 与 `dsh-commands` 迁移全部七个注册门面，同时保留校验顺序、精确诊断、视图、通知策略、重入行为和 HMR 清理。
-- `dsh-scope` README 与作用域核心数据文档描述公开契约；架构和运行时设计引用标识共享 store，但不重复其内容。各消费方 README 继续聚焦其未改变的公开行为。
-- 实现 PR 将本组文件移入 `implemented/architecture`，把 `Proposal` 改为以现在时书写的 `Decision`，并记录已落地的后果与验证。现有无密钥快照保持逐字节一致。
+- 支持作用域的注册表各自通过一个聚合层表达状态，并复用相同的构造、属主、回滚、通知和回收编排。各注册表仍各自保有领域特有的校验、诊断、过滤、求值和观察者策略。
+- 公开读取接口保持狭窄：直接遍历条目表可保留显式的活语义，`merge()` 是唯一共享的物化遮蔽操作。异构的 `ScopeLayer` 不具备整层 `values()` 契约。
+- helper 刻意保持同步。未来的登记若需要异步 setup 或多份分别拥有属主的 undo，必须先明确属主与 settlement 边界，再拓宽这项契约。
+- action 必须在保留贡献前抛错，或者为自己保留的一切返回 undo；helper 无法修复超出这项契约的变更。提供的条目操作是原子的，迁移后的注册表会在插入前执行可能失败的校验。
+- 专属层会一直保持已分配状态，直到其聚合内的所有表都为空。因此，销毁一个门面不会丢弃同一 scope 拥有的其他贡献。
+- 四个公开符号构成一项可复用的包契约。将 `EntryValues` 保持为内部接口，并把消费方策略留在 helper 之外，可以限制兼容性范围。
+- 迁移不改变任何公开注册表行为，也不改变模型、人类、协议、持久化、配置或依赖图层面的任何输出。
 
-## 风险
+## 验证
 
-- 未来的登记可能需要异步 setup 或多份分别拥有属主的 undo。该消费方必须先明确其属主与 settlement 边界，再拓宽这个刻意保持同步的接口。
-- 抛错的 action 若在返回的 undo 契约之外产生变更，通用 helper 无法修复。条目操作是原子的；迁移会在插入前执行可能失败的校验；测试会钉住工厂失败和保留贡献前的 action 失败清理。
-- 聚合回收会让专属层一直存活到所有表都清空。这是有意行为，并且只能通过内部存储生命周期观察到；测试会钉住销毁一张表时不会丢弃同层的其他贡献。
-- 公开类新增了一项可复用的包契约。保持读取接口狭窄并把领域策略留在消费方，可以减少未来代码必须维持的契约范围。
+- `dsh-scope` 单元测试覆盖全局构造、专属层延迟构造、非创建式读取、命名合并顺序与遮蔽、聚合回收、工厂与 action 失败清理、通知顺序与回滚、`notify: false`、effect 标签、原始 disposer 身份、幂等拆除、调用方提供的重名错误、相同匿名值的独立登记和活迭代器。
+- 工具、系统提示词和命令专项测试套件覆盖 restriction、保留传输处理、已知名称与可限制名称的一致性、guard 重入、校验顺序、精确诊断、section 先遮蔽再求值、提供方快照成员关系、variable 重入、隔离失败的命令观察者、冻结且有序的视图、直接执行和生命周期销毁。
+- 作用域核心数据的类型等价性检查将 `ScopeLayer` 文档与其源声明绑定。仓库级的文档、模块图、构建、hygiene、覆盖率与构建产物门禁会覆盖包根导出与包边界。
+- 现有 ACP（Agent Client Protocol）、headless 和 TUI 无密钥快照继续作为工具 schema、提示词组装和人类命令的回归边界。实现不会更新任何预期 transcript（文本记录）。
diff --git a/docs/architecture.md b/docs/architecture.md
index 3844b981ab..5aaba96092 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -12,7 +12,7 @@ Harnesses are [Cordis](cordis-primer.md) contexts whose packages contribute disp
 
 | ctx key | Package | Role |
 |---|---|---|
-| — | [`dsh-scope`](../packages/core/scope/README.md) | scoped-context registration primitive (library) |
+| — | [`dsh-scope`](../packages/core/scope/README.md) | scoped-context registration and shared layer storage (library) |
 | `ctx.sessions` | `dsh-session` | in-memory event-sourced sessions |
 | `ctx.systemPrompt` | `dsh-system-prompt` | ordered prompt sections, tool schemas, and prompt variables |
 | `ctx.tools` | `dsh-tools` | tool registry and [execution pipeline](tool-execution-pipeline.md) |
@@ -130,7 +130,7 @@ Every session event is turn-enclosed. Reloading preserves an interrupted tail an
 
 ### Agent Scope
 
-Every live agent owns a scoped `agent.ctx`. Its registrations shadow globals, receive only that agent's dispatches, and unwind with it; async effects such as background-task cleanup are awaited. `CreateAgentOptions.setup(agentCtx)` composes the scope before publication. Typed resolvers derive carrier checks from merged `Events` signatures and `scopeTarget` ([semantic gates](../.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md)). See [agent scope](../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md) and [subagent composition controls](../.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md). `AgentLoop` runs drivers inside `ctx.agents.withInitiator()`; private orchestration derives `agent.session`; turn, step, signal, cwd, and authority stay explicit ([decision](../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)).
+`agent.ctx` owns each live agent's scoped registrations; shared storage overlays global tool, prompt, and command entries while preserving domain views ([decision](../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md)). Listeners match the agent; cleanup is awaited. `CreateAgentOptions.setup(agentCtx)` composes the scope before publication. Typed resolvers derive carrier checks from merged `Events` signatures and `scopeTarget` ([semantic gates](../.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md)). See [agent scope](../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md) and [subagent composition controls](../.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md). `AgentLoop` runs drivers inside `ctx.agents.withInitiator()`; private orchestration derives `agent.session`; turn, step, signal, cwd, and authority stay explicit ([decision](../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)).
 
 ## State
 
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 86118735d3..145a05a7fd 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -435,7 +435,7 @@ A command was registered or unregistered. This is an unfiltered registry notific
 'commands/change'(): void
 ```
 
-Source: [`packages/ui/commands/src/index.ts:83`](../../packages/ui/commands/src/index.ts)
+Source: [`packages/ui/commands/src/index.ts:103`](../../packages/ui/commands/src/index.ts)
 
 ## `fs/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index a0f65a1fae..922076a88b 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -379,7 +379,7 @@ async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<Comma
 
 Types: [Agent](../core-data-structures/core.md) · [CommandDefinition](../core-data-structures/commands.md) · [CommandDescriptor](../core-data-structures/commands.md) · [CommandResult](../core-data-structures/commands.md)
 
-Source: [`packages/ui/commands/src/index.ts:207`](../../packages/ui/commands/src/index.ts)
+Source: [`packages/ui/commands/src/index.ts:227`](../../packages/ui/commands/src/index.ts)
 
 ## `ctx.compact` — `CompactService` (abstract seam)
 
@@ -1150,7 +1150,7 @@ async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
 
 Types: [AssembleContext](../core-data-structures/system-prompt.md) · [PromptSection](../core-data-structures/system-prompt.md) · [ToolProviderResult](../core-data-structures/system-prompt.md)
 
-Source: [`packages/core/system-prompt/src/index.ts:213`](../../packages/core/system-prompt/src/index.ts)
+Source: [`packages/core/system-prompt/src/index.ts:246`](../../packages/core/system-prompt/src/index.ts)
 
 ## `ctx.tasks` — `TaskService`
 
@@ -1393,7 +1393,7 @@ async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
 
 Types: [ScopeKey](../core-data-structures/scope.md) · [ToolDefinition](../core-data-structures/tools.md) · [ToolExecutionInput](../core-data-structures/tools.md) · [ToolExecutionMode](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolGuard](../core-data-structures/tools.md) · [ToolRestriction](../core-data-structures/tools.md) · [ToolSchema](../core-data-structures/tools.md)
 
-Source: [`packages/core/tools/src/index.ts:493`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:524`](../../packages/core/tools/src/index.ts)
 
 ## `ctx.userInteraction` — `UserInteractionService`
 
diff --git a/docs/core-data-structures/scope.md b/docs/core-data-structures/scope.md
index 93e6d76598..d23de86477 100644
--- a/docs/core-data-structures/scope.md
+++ b/docs/core-data-structures/scope.md
@@ -1,8 +1,8 @@
 # Scoped Registration
 
-The [scope package](../../packages/core/scope) supplies the identity and carrier vocabulary that makes one registration context mean both per-agent visibility and shared lifetime ownership. It is a library primitive rather than a Cordis service; the [agent-scope runtime-design Agent Note](../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#scope-routing-one-opaque-key-selects-one-layer) owns the implementation rationale, while the package [README](../../packages/core/scope/README.md) owns the callable API and filtering semantics.
+The [scope package](../../packages/core/scope) supplies the identity, carrier, and scoped-layer vocabulary that makes one registration context mean both per-agent visibility and shared lifetime ownership. It is a library primitive rather than a Cordis service; the [agent-scope runtime-design Agent Note](../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#scope-routing-one-opaque-key-selects-one-layer) owns the lifecycle rationale, the [shared-storage Agent Note](../../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md) owns the registry-layer decision, and the package [README](../../packages/core/scope/README.md) owns the callable API and filtering semantics.
 
-Source: [`packages/core/scope/src/index.ts`](../../packages/core/scope/src/index.ts).
+Sources: [`packages/core/scope/src/index.ts`](../../packages/core/scope/src/index.ts) and [`packages/core/scope/src/store.ts`](../../packages/core/scope/src/store.ts).
 
 ## Identity and dispatch carrier
 
@@ -39,3 +39,19 @@ interface Scope {
   dispose(): Promise<void>
 }
 ```
+
+## Scoped registry layer
+
+`ScopeLayer` represents one registry's complete contribution at the global or exact-scope level. A concrete layer may aggregate multiple named and anonymous tables; whole-layer emptiness lets `ScopedLayers` reclaim scoped state without discarding a sibling table.
+
+```ts type-equiv
+/** One scope's aggregate contribution to a registry. */
+interface ScopeLayer {
+  /** Whether every table in this layer is empty. */
+  isEmpty(): boolean
+}
+```
+
+`ScopedLayers<L>` owns the eager global layer and lazily created exact-scope layers. Reads do not create layers: `peek(undefined)` means no overlay, while `merge()` materializes insertion-ordered global named entries followed by scoped shadows. Registrations use one context for both visibility and Cordis effect ownership, collect one synchronous undo before optional notification, return Cordis's exact disposer, and reclaim a scoped layer only when its complete `ScopeLayer` is empty.
+
+`NamedEntries<V>` supplies live insertion-ordered lookup and iteration with caller-owned duplicate errors. `AnonymousEntries<V>` gives every append a unique identity so equal values remain independent. Both return idempotent exact-entry undos; the shared `EntryValues` implementation interface is not public.
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index bcccfb7785..60edc07705 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -25,7 +25,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:322`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `agent/turn-stop` | `serial` | [`packages/core/agent/src/types.ts:333`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`tool-goal`](../packages/goal/tool-goal) |
 | `approval/request` | `waterfall` | [`packages/ui/user-approval/src/index.ts:31`](../packages/ui/user-approval/src/index.ts) | [`user-approval`](../packages/ui/user-approval) (`waterfall`) | [`acp`](../packages/ui/acp) |
-| `commands/change` | `emit` | [`packages/ui/commands/src/index.ts:83`](../packages/ui/commands/src/index.ts) | [`commands`](../packages/ui/commands) (`events.dispatch`) | [`acp`](../packages/ui/acp), [`tui`](../packages/ui/tui) |
+| `commands/change` | `emit` | [`packages/ui/commands/src/index.ts:103`](../packages/ui/commands/src/index.ts) | [`commands`](../packages/ui/commands) (`events.dispatch`) | [`acp`](../packages/ui/acp), [`tui`](../packages/ui/tui) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:62`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:71`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:54`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
diff --git a/packages/core/scope/README.md b/packages/core/scope/README.md
index 7fc4a49102..1c83aec89b 100644
--- a/packages/core/scope/README.md
+++ b/packages/core/scope/README.md
@@ -12,6 +12,10 @@ Scoped registration primitive. `createScope(ctx, key)` creates a tagged Cordis c
 - `scopeTarget(base: T, key: ScopeKey | undefined): Scoped<T>` Build the opaque dispatch `thisArg` for a scope-filtered event. It composes `base`'s existing `Context.filter` with the scope predicate (untagged listener ⇒ admitted; tagged ⇒ admitted iff tag === key; `key === undefined` ⇒ untagged only). The carrier contains routing state only; the real subject is carried by the event arguments. `{ global: true }` listeners bypass filtering (Cordis semantics).
 - `Scoped<T>` The compile-time opaque carrier brand: scope-filtered events demand it as their `this` type, so dispatching with a bare subject is a compile error. The type parameter records the subject type but does not expose its properties.
 - `isScopeCarrier(value)` / `carrierKeyOf(value)` Runtime carrier marks, used by the dev invariants to assert every scope-filtered dispatch carries a carrier keyed to the subject its arguments name.
+- `ScopeLayer` Aggregate contract for one registry's complete global or exact-scope contribution; `isEmpty()` controls scoped-layer reclamation.
+- `ScopedLayers<L>` Own one eager global layer and lazy exact-scope layers. `peek()` never creates, `merge()` materializes insertion-ordered named shadows, and `effect()` derives visibility and ownership from the same context while returning the exact Cordis disposer.
+- `NamedEntries<V>` Insertion-ordered named storage with caller-owned duplicate diagnostics, live lookup/iteration, and an idempotent exact-entry undo from `insert()`.
+- `AnonymousEntries<V>` Insertion-ordered anonymous storage whose unique internal keys keep equal values as independent registrations; `append()` returns an idempotent exact-entry undo.
 
 The optional `@deepseek-ai/dsh-scope/invariant` companion owns that runtime assertion. It uses the generated `scoped-events.generated.ts` resolver map to require a carrier for every declared scoped event and, when the payload exposes its routing subject, require identity with the carrier key. The Program-backed generator derives the map from event declarations and real `scopeTarget(base, key)` calls.
 
@@ -19,6 +23,8 @@ The optional `@deepseek-ai/dsh-scope/invariant` companion owns that runtime asse
 
 The registration context determines both visibility and ownership, preventing a registration from being visible in one scope but disposed with another. Scopes route trusted same-process plugins; they are not sandboxes or authority boundaries. See the [agent-scope Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals) for rationale and security non-goals.
 
+Scope-aware services define a concrete `ScopeLayer` that aggregates their heterogeneous tables and domain helpers. `ScopedLayers.effect()` accepts one synchronous action returning one synchronous undo, installs that undo before optional notification, and reclaims an exact-scope layer only when the complete aggregate is empty. `notify` defaults to `true`; the supplied callback owns whether observer failures throw or are contained. `EntryValues` remains internal, the storage classes are imported from the package root rather than a `/store` subpath, and the shared storage does not define registry-specific filtering or iteration policy. See the [shared scoped-layer storage Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md).
+
 Handing out a scoped context hands out the minting plugin's service-resolution surface (resolution walks the minting fiber's dependency chain, not the holder's) — mint it from the plugin whose dependencies the scoped registrations need to resolve.
 
 ## Known Limitations and Deferred Work
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index d7446b2a58..b2919d8a0e 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -28,6 +28,7 @@
     { "doc": "docs/core-data-structures/scope.md", "symbol": "ScopeKey", "source": "packages/core/scope/src/index.ts" },
     { "doc": "docs/core-data-structures/scope.md", "symbol": "Scoped", "source": "packages/core/scope/src/index.ts" },
     { "doc": "docs/core-data-structures/scope.md", "symbol": "Scope", "source": "packages/core/scope/src/index.ts" },
+    { "doc": "docs/core-data-structures/scope.md", "symbol": "ScopeLayer", "source": "packages/core/scope/src/store.ts" },
 
     { "doc": "docs/core-data-structures/goal.md", "symbol": "GoalRef", "source": "packages/goal/goal/src/types.ts" },
     { "doc": "docs/core-data-structures/goal.md", "symbol": "GoalPhase", "source": "packages/goal/goal/src/types.ts" },

From f8008b571dbaa10d6b24197faf3a32e09e9c94f5 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 21 Jul 2026 23:47:14 +0800
Subject: [PATCH 62/74] fix(tui): preserve footer truncation after merge

---
 .../snapshots/workspace-edit/stdout.expected.windows.jsonl   | 1 +
 packages/ui/tui/src/index.ts                                 | 5 +----
 packages/ui/tui/tests/tui.spec.ts                            | 4 ++--
 3 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.windows.jsonl b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.windows.jsonl
index 754b9c5841..f39ff91716 100644
--- a/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.windows.jsonl
+++ b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.expected.windows.jsonl
@@ -1,6 +1,7 @@
 {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"available_commands_update","availableCommands":[{"name":"goal","description":"set or view the goal for a long-running task","input":{"hint":"[<objective>|clear|edit <objective>|pause|resume]"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"session_info_update","title":"A file named greeting.txt in","updatedAt":"{{updatedAt}}"}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}}
diff --git a/packages/ui/tui/src/index.ts b/packages/ui/tui/src/index.ts
index 5cb23b31c0..2b16036ada 100644
--- a/packages/ui/tui/src/index.ts
+++ b/packages/ui/tui/src/index.ts
@@ -777,10 +777,7 @@ class FooterComponent implements Component {
       return [`${' '.repeat(Math.max(0, width - visibleWidth(compact)))}${this.palette.dim(compact)}`]
     }
     const rightAvailable = width - visibleWidth(counters) - 1
-    const fullWidth = visibleWidth(formattedCwd) + visibleWidth(counters) + visibleWidth(fullRight) + 3
-    const right = this.cwdFormatter === undefined
-      ? (visibleWidth(fullRight) <= rightAvailable ? fullRight : compactRight)
-      : (fullWidth <= width ? fullRight : compactRight)
+    const right = visibleWidth(fullRight) <= rightAvailable ? fullRight : compactRight
     const rightClipped = truncateToWidth(right, rightAvailable, '')
     const cwdAvailable = Math.max(0, width - visibleWidth(counters) - visibleWidth(rightClipped) - 3)
     const cwd = truncateToWidth(formattedCwd, cwdAvailable, '')
diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts
index 796f84b895..7474add504 100644
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -511,10 +511,10 @@ describe('pi-tui chat lifecycle and transcript', () => {
     await dispose(outsideResult)
 
     const logicalResult = await setup({
-      cwd: '/host/worktree',
+      cwd: '/w',
       formatCwd: cwd => `logical:${cwd}\x1b`,
     })
-    expect(logicalResult.terminal.output).toContain('logical:/host/worktree\\x1b')
+    expect(logicalResult.terminal.output).toContain('logical:/w\\x1b')
     await dispose(logicalResult)
   })
 

From 0180cdecd05f13b021569dcd45c9c98feaff4a01 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 22 Jul 2026 12:06:42 +0800
Subject: [PATCH 63/74] fix(scope): detach drained entry generations

---
 .../2026-07-12-scoped-layers-store.i18n.yaml  |  4 +--
 .../2026-07-12-scoped-layers-store.md         | 12 ++++-----
 .../2026-07-12-scoped-layers-store.zh.md      | 12 ++++-----
 docs/core-data-structures/scope.md            |  2 +-
 packages/core/scope/README.md                 |  4 +--
 packages/core/scope/src/store.ts              | 26 ++++++++++++-------
 packages/core/scope/tests/store.spec.ts       | 26 +++++++++++++++++++
 .../core/system-prompt/tests/scoped.spec.ts   | 22 ++++++++++++++++
 packages/core/tools/tests/scoped.spec.ts      | 22 ++++++++++++++++
 9 files changed, 103 insertions(+), 27 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.i18n.yaml
index 4ece091d15..b49506364b 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-12-scoped-layers-store.md: 5ba91f33eb079a44f966d7f0b5ff097ff529e700
-2026-07-12-scoped-layers-store.zh.md: c84792e468a435e2463b5ff682fad8a8129189ed
+2026-07-12-scoped-layers-store.md: b850b6bcbb22401b386b4458b6d5c65a160c85cd
+2026-07-12-scoped-layers-store.zh.md: 8bfc0a0e8ec1e3de624ff8d9e48b7517833fc025
diff --git a/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md
index 5ba91f33eb..b850b6bcbb 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md
@@ -74,17 +74,17 @@ export class AnonymousEntries<V> {
 
 - The constructor creates `global` once with `createLayer(undefined)`. A scoped layer is created only by `effect()`; `peek()` and `merge()` never create one, and `peek(undefined)` returns `undefined` because the global layer is already explicit.
 - `merge()` is the only materialized generic read. It copies named global entries in insertion order, then applies matching scoped entries in their insertion order so same-name entries shadow without moving unrelated names.
-- `NamedEntries.insert()` checks and inserts atomically, returns an idempotent exact-entry undo, and obtains the registry's exact duplicate diagnostic from the caller-supplied factory. Lookup and iterators retain native `Map` order and live iteration.
-- `AnonymousEntries.append()` assigns a unique internal key per registration, so equal callbacks or values remain independent. Its iterator is live and insertion-ordered.
+- `NamedEntries.insert()` checks and inserts atomically, returns an idempotent exact-entry undo, and obtains the registry's exact duplicate diagnostic from the caller-supplied factory. Lookup and iterators retain native `Map` order and stay live within one nonempty table generation; draining the table starts a new generation so an in-flight iterator cannot observe a self-replacement.
+- `AnonymousEntries.append()` assigns a unique internal key per registration, so equal callbacks or values remain independent. Its iterator is insertion-ordered and uses the same live-generation boundary.
 - `effect()` derives the key with `scopeOf(ctx)` and attaches the action to that same `ctx.effect()`. It accepts one synchronous action returning one synchronous undo; actions must either return their undo or throw before retaining a contribution. The helper does not normalize the wider Cordis `Effect` union.
 - `effect()` collects the action's undo before calling `onChange` and returns the exact `ctx.effect()` disposer. Disposal runs the action undo before notification, is idempotent through Cordis, and removes a scoped layer only after its complete `ScopeLayer.isEmpty()` becomes true.
 - `options.notify` defaults to `true`. The callback's own policy stays authoritative: tool and prompt change callbacks may throw and trigger registration rollback; `CommandService.notifyChange()` contains observer failures; tool guards pass `notify: false`.
 
 ## Registry migrations
 
-`dsh-tools` defines one `ToolLayer` containing named tools plus anonymous compiled restrictions and guard registrations. `ToolRegistry` retains its private domain resolver for visible definitions, pre-restriction known names, restrictable global names, scoped shadowing, restrictions, and reserved `run_code` insertion. Guard evaluation continues to live-iterate global then scoped registrations so re-entrant additions retain current behavior.
+`dsh-tools` defines one `ToolLayer` containing named tools plus anonymous compiled restrictions and guard registrations. `ToolRegistry` retains its private domain resolver for visible definitions, pre-restriction known names, restrictable global names, scoped shadowing, restrictions, and reserved `run_code` insertion. Guard evaluation live-iterates global then scoped registrations: additions to a nonempty generation can run in the current dispatch, while a self-replacement after draining the guard table begins with the next dispatch.
 
-`dsh-system-prompt` defines one `PromptLayer` containing named sections and variables plus anonymous tool providers. Assembly merges sections before evaluating them, so a shadowed provider is never called. Tool-provider membership is materialized once per assembly. Variable providers continue to live-iterate global then scoped tables, preserving re-entrant registration behavior.
+`dsh-system-prompt` defines one `PromptLayer` containing named sections and variables plus anonymous tool providers. Assembly merges sections before evaluating them, so a shadowed provider is never called. Tool-provider membership is materialized once per assembly. Variable providers live-iterate global then scoped tables: additions to a nonempty generation can run in the current assembly, while a self-replacement after draining the variable table begins with the next assembly.
 
 `dsh-commands` defines a one-table layer containing `NamedEntries<RegisteredCommand>`. Effective views use `merge()`, while `CommandService` retains definition normalization and freezing, exact duplicate diagnostics, sorted immutable descriptors, direct execution, HMR cleanup, and independently contained `commands/change` observers.
 
@@ -120,7 +120,7 @@ All seven facades keep validation and diagnostics in their owning registry and c
 
 ## Verification
 
-- `dsh-scope` unit tests cover global construction, lazy scoped construction, non-creating reads, named merge order and shadowing, aggregate reclamation, factory and action failure cleanup, notification ordering and rollback, `notify: false`, effect labels, exact disposer identity, idempotent teardown, caller-owned duplicate errors, independent anonymous duplicates, and live iterators.
-- Focused tool, system-prompt, and command suites cover restrictions, reserved transport handling, known/restrictable-name agreement, guard re-entrancy, validation order, exact diagnostics, section shadow-before-evaluate, provider snapshot membership, variable re-entrancy, contained command observers, frozen and sorted views, direct execution, and lifecycle disposal.
+- `dsh-scope` unit tests cover global construction, lazy scoped construction, non-creating reads, named merge order and shadowing, aggregate reclamation, factory and action failure cleanup, notification ordering and rollback, `notify: false`, effect labels, exact disposer identity, idempotent teardown, caller-owned duplicate errors, independent anonymous duplicates, live iterators, and drained-generation detachment.
+- Focused tool, system-prompt, and command suites cover restrictions, reserved transport handling, known/restrictable-name agreement, guard re-entrancy and self-replacement, validation order, exact diagnostics, section shadow-before-evaluate, provider snapshot membership, variable re-entrancy and self-replacement, contained command observers, frozen and sorted views, direct execution, and lifecycle disposal.
 - The scoped core-data type-equivalence check ties `ScopeLayer` documentation to its source declaration. Repository documentation, module-graph, build, hygiene, coverage, and built-artifact gates exercise the root export and package boundary.
 - Existing ACP, headless, and TUI keyless snapshots remain the regression boundary for tool schemas, prompt assembly, and human commands. The implementation does not update any expected transcript.
diff --git a/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.zh.md b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.zh.md
index c84792e468..8bfc0a0e8e 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.zh.md
@@ -74,17 +74,17 @@ export class AnonymousEntries<V> {
 
 - 构造器只创建一次 `global`，调用的是 `createLayer(undefined)`。只有 `effect()` 会创建专属层；`peek()` 和 `merge()` 从不创建专属层，而 `peek(undefined)` 返回 `undefined`，因为全局层已经显式存在。
 - `merge()` 是唯一会物化结果的通用读取接口。它按插入顺序复制全局命名条目，再按专属条目的插入顺序应用这些条目；同名条目完成遮蔽，但不会移动无关名称。
-- `NamedEntries.insert()` 以原子方式检查并插入，返回幂等且只撤销该精确条目的 undo，并通过调用方提供的工厂取得所属注册表的精确重名诊断。查询与迭代器保留 `Map` 的原生顺序和活遍历语义。
-- `AnonymousEntries.append()` 为每次登记分配唯一内部键，因此值相等的回调或其他值仍彼此独立。其迭代器是保留插入顺序的活迭代器。
+- `NamedEntries.insert()` 以原子方式检查并插入，返回幂等且只撤销该精确条目的 undo，并通过调用方提供的工厂取得所属注册表的精确重名诊断。查询与迭代器保留 `Map` 的原生顺序，并在同一个非空表 generation 内保持活遍历；清空表会开启新的 generation，因此尚未结束的迭代器无法观察到自我替换。
+- `AnonymousEntries.append()` 为每次登记分配唯一内部键，因此值相等的回调或其他值仍彼此独立。其迭代器保留插入顺序，并采用同样的 generation 活遍历边界。
 - `effect()` 通过 `scopeOf(ctx)` 导出键，并把 action 挂到同一个 `ctx.effect()` 上。它只接受一个同步 action，且该 action 只返回一个同步 undo；action 要么返回其 undo，要么必须在保留任何贡献之前抛错。helper 不会规范化更宽泛的 Cordis `Effect` union。
 - `effect()` 在调用 `onChange` 前收集 action 的 undo，并原样返回 `ctx.effect()` 的 disposer。销毁时先运行 action undo 再通知；Cordis 保证其幂等性；只有整个层的 `ScopeLayer.isEmpty()` 变为 true 后，helper 才删除专属层。
 - `options.notify` 默认为 `true`。回调自身的策略仍具最终效力：工具与提示词的 change 回调可以抛错并触发登记回滚；`CommandService.notifyChange()` 会隔离观察者失败；工具 guard 传入 `notify: false`。
 
 ## 注册表迁移
 
-`dsh-tools` 定义一个 `ToolLayer`，其中包含命名工具以及匿名的已编译 restriction 和 guard 登记。`ToolRegistry` 保留其私有领域解析器，由它处理可见定义、限制前的已知名称、可限制的全局名称、专属遮蔽、restriction，以及保留的 `run_code` 插入。guard 求值继续先活遍历全局登记，再活遍历专属登记，因此重入时新增的登记保持现有行为。
+`dsh-tools` 定义一个 `ToolLayer`，其中包含命名工具以及匿名的已编译 restriction 和 guard 登记。`ToolRegistry` 保留其私有领域解析器，由它处理可见定义、限制前的已知名称、可限制的全局名称、专属遮蔽、restriction，以及保留的 `run_code` 插入。guard 求值会先活遍历全局登记，再活遍历专属登记：向非空 generation 新增的登记可以在当前分发中运行，而 guard 表清空后的自我替换则从下一次分发开始运行。
 
-`dsh-system-prompt` 定义一个 `PromptLayer`，其中包含命名的段落与变量，以及匿名工具提供方。组装流程在求值前合并段落，因此被遮蔽的提供方不会被调用。每次组装只物化一次工具提供方成员集合。变量提供方继续先活遍历全局表，再活遍历专属表，从而保留重入登记行为。
+`dsh-system-prompt` 定义一个 `PromptLayer`，其中包含命名的段落与变量，以及匿名工具提供方。组装流程在求值前合并段落，因此被遮蔽的提供方不会被调用。每次组装只物化一次工具提供方成员集合。变量提供方会先活遍历全局表，再活遍历专属表：向非空 generation 新增的提供方可以在当前组装中运行，而变量表清空后的自我替换则从下一次组装开始运行。
 
 `dsh-commands` 定义一个单表层，其中包含 `NamedEntries<RegisteredCommand>`。生效视图使用 `merge()`；`CommandService` 则保留对定义的规范化与冻结处理、精确重名诊断、经过排序的不可变描述符、直接执行、HMR（热模块替换）清理，以及对各个 `commands/change` 观察者分别隔离失败的行为。
 
@@ -120,7 +120,7 @@ export class AnonymousEntries<V> {
 
 ## 验证
 
-- `dsh-scope` 单元测试覆盖全局构造、专属层延迟构造、非创建式读取、命名合并顺序与遮蔽、聚合回收、工厂与 action 失败清理、通知顺序与回滚、`notify: false`、effect 标签、原始 disposer 身份、幂等拆除、调用方提供的重名错误、相同匿名值的独立登记和活迭代器。
-- 工具、系统提示词和命令专项测试套件覆盖 restriction、保留传输处理、已知名称与可限制名称的一致性、guard 重入、校验顺序、精确诊断、section 先遮蔽再求值、提供方快照成员关系、variable 重入、隔离失败的命令观察者、冻结且有序的视图、直接执行和生命周期销毁。
+- `dsh-scope` 单元测试覆盖全局构造、专属层延迟构造、非创建式读取、命名合并顺序与遮蔽、聚合回收、工厂与 action 失败清理、通知顺序与回滚、`notify: false`、effect 标签、原始 disposer 身份、幂等拆除、调用方提供的重名错误、相同匿名值的独立登记、活迭代器，以及表清空后的 generation 脱离。
+- 工具、系统提示词和命令专项测试套件覆盖 restriction、保留传输处理、已知名称与可限制名称的一致性、guard 重入与自我替换、校验顺序、精确诊断、section 先遮蔽再求值、提供方快照成员关系、variable 重入与自我替换、隔离失败的命令观察者、冻结且有序的视图、直接执行和生命周期销毁。
 - 作用域核心数据的类型等价性检查将 `ScopeLayer` 文档与其源声明绑定。仓库级的文档、模块图、构建、hygiene、覆盖率与构建产物门禁会覆盖包根导出与包边界。
 - 现有 ACP（Agent Client Protocol）、headless 和 TUI 无密钥快照继续作为工具 schema、提示词组装和人类命令的回归边界。实现不会更新任何预期 transcript（文本记录）。
diff --git a/docs/core-data-structures/scope.md b/docs/core-data-structures/scope.md
index d23de86477..e9869f3152 100644
--- a/docs/core-data-structures/scope.md
+++ b/docs/core-data-structures/scope.md
@@ -54,4 +54,4 @@ interface ScopeLayer {
 
 `ScopedLayers<L>` owns the eager global layer and lazily created exact-scope layers. Reads do not create layers: `peek(undefined)` means no overlay, while `merge()` materializes insertion-ordered global named entries followed by scoped shadows. Registrations use one context for both visibility and Cordis effect ownership, collect one synchronous undo before optional notification, return Cordis's exact disposer, and reclaim a scoped layer only when its complete `ScopeLayer` is empty.
 
-`NamedEntries<V>` supplies live insertion-ordered lookup and iteration with caller-owned duplicate errors. `AnonymousEntries<V>` gives every append a unique identity so equal values remain independent. Both return idempotent exact-entry undos; the shared `EntryValues` implementation interface is not public.
+`NamedEntries<V>` supplies insertion-ordered lookup and live iteration with caller-owned duplicate errors. `AnonymousEntries<V>` gives every append a unique identity so equal values remain independent. Iteration stays live within one nonempty table generation; draining the table detaches existing iterators from later insertions. Both return idempotent exact-entry undos; the shared `EntryValues` implementation interface is not public.
diff --git a/packages/core/scope/README.md b/packages/core/scope/README.md
index 1c83aec89b..cfc09c1dca 100644
--- a/packages/core/scope/README.md
+++ b/packages/core/scope/README.md
@@ -14,8 +14,8 @@ Scoped registration primitive. `createScope(ctx, key)` creates a tagged Cordis c
 - `isScopeCarrier(value)` / `carrierKeyOf(value)` Runtime carrier marks, used by the dev invariants to assert every scope-filtered dispatch carries a carrier keyed to the subject its arguments name.
 - `ScopeLayer` Aggregate contract for one registry's complete global or exact-scope contribution; `isEmpty()` controls scoped-layer reclamation.
 - `ScopedLayers<L>` Own one eager global layer and lazy exact-scope layers. `peek()` never creates, `merge()` materializes insertion-ordered named shadows, and `effect()` derives visibility and ownership from the same context while returning the exact Cordis disposer.
-- `NamedEntries<V>` Insertion-ordered named storage with caller-owned duplicate diagnostics, live lookup/iteration, and an idempotent exact-entry undo from `insert()`.
-- `AnonymousEntries<V>` Insertion-ordered anonymous storage whose unique internal keys keep equal values as independent registrations; `append()` returns an idempotent exact-entry undo.
+- `NamedEntries<V>` Insertion-ordered named storage with caller-owned duplicate diagnostics, lookup, and live iteration within one nonempty table generation; draining the table detaches existing iterators from later insertions, and `insert()` returns an idempotent exact-entry undo.
+- `AnonymousEntries<V>` Insertion-ordered anonymous storage whose unique internal keys keep equal values as independent registrations; it uses the same drained-generation iterator boundary, and `append()` returns an idempotent exact-entry undo.
 
 The optional `@deepseek-ai/dsh-scope/invariant` companion owns that runtime assertion. It uses the generated `scoped-events.generated.ts` resolver map to require a carrier for every declared scoped event and, when the payload exposes its routing subject, require identity with the carrier key. The Program-backed generator derives the map from event declarations and real `scopeTarget(base, key)` calls.
 
diff --git a/packages/core/scope/src/store.ts b/packages/core/scope/src/store.ts
index 5f016df929..53f7e34135 100644
--- a/packages/core/scope/src/store.ts
+++ b/packages/core/scope/src/store.ts
@@ -23,11 +23,12 @@ interface EntryValues<V> {
 /**
  * Insertion-ordered named entries with caller-owned duplicate diagnostics.
  *
- * Values are borrowed. Iterators are live native `Map` iterators, and each
+ * Values are borrowed. Iterators are live within one nonempty table
+ * generation; draining the table detaches them from later insertions. Each
  * successful insertion returns an idempotent undo for that exact entry.
  */
 export class NamedEntries<V> implements EntryValues<V> {
-  private readonly data = new Map<string, V>()
+  private data = new Map<string, V>()
 
   constructor(
     private readonly duplicateError: (name: string) => Error,
@@ -40,13 +41,15 @@ export class NamedEntries<V> implements EntryValues<V> {
    * @returns an idempotent undo that removes only this insertion.
    */
   insert(name: string, value: V): () => void {
-    if (this.data.has(name)) throw this.duplicateError(name)
-    this.data.set(name, value)
+    const data = this.data
+    if (data.has(name)) throw this.duplicateError(name)
+    data.set(name, value)
     let active = true
     return () => {
       if (!active) return
       active = false
-      this.data.delete(name)
+      data.delete(name)
+      if (data.size === 0 && this.data === data) this.data = new Map()
     }
   }
 
@@ -104,11 +107,12 @@ export class NamedEntries<V> implements EntryValues<V> {
 /**
  * Insertion-ordered anonymous entries with independent registration identity.
  *
- * Equal values remain separate registrations. Values are borrowed and the
- * returned iterator retains native live `Map` semantics.
+ * Equal values remain separate registrations. Values are borrowed, and
+ * iterators are live within one nonempty table generation; draining the table
+ * detaches them from later appends.
  */
 export class AnonymousEntries<V> implements EntryValues<V> {
-  private readonly data = new Map<symbol, V>()
+  private data = new Map<symbol, V>()
 
   /**
    * Append one independently owned value.
@@ -116,13 +120,15 @@ export class AnonymousEntries<V> implements EntryValues<V> {
    * @returns an idempotent undo for this exact append.
    */
   append(value: V): () => void {
+    const data = this.data
     const key = Symbol()
-    this.data.set(key, value)
+    data.set(key, value)
     let active = true
     return () => {
       if (!active) return
       active = false
-      this.data.delete(key)
+      data.delete(key)
+      if (data.size === 0 && this.data === data) this.data = new Map()
     }
   }
 
diff --git a/packages/core/scope/tests/store.spec.ts b/packages/core/scope/tests/store.spec.ts
index 9f70d2b527..622dbeb541 100644
--- a/packages/core/scope/tests/store.spec.ts
+++ b/packages/core/scope/tests/store.spec.ts
@@ -59,6 +59,19 @@ describe('NamedEntries', () => {
     undoB()
     expect([...entries.entries()]).toEqual([['a', 3]])
   })
+
+  it('starts a fresh iterator generation after the table drains', () => {
+    const entries = new NamedEntries<number>(name => new Error(`duplicate: ${name}`))
+    const undo = entries.insert('first', 1)
+    const values = entries.values()
+
+    expect(values.next()).toEqual({ value: 1, done: false })
+    undo()
+    entries.insert('replacement', 2)
+
+    expect(values.next().done).toBe(true)
+    expect([...entries.values()]).toEqual([2])
+  })
 })
 
 describe('AnonymousEntries', () => {
@@ -78,6 +91,19 @@ describe('AnonymousEntries', () => {
     undoSecond()
     expect(entries.isEmpty()).toBe(true)
   })
+
+  it('starts a fresh iterator generation after the table drains', () => {
+    const entries = new AnonymousEntries<number>()
+    const undo = entries.append(1)
+    const values = entries.values()
+
+    expect(values.next()).toEqual({ value: 1, done: false })
+    undo()
+    entries.append(2)
+
+    expect(values.next().done).toBe(true)
+    expect([...entries.values()]).toEqual([2])
+  })
 })
 
 describe('ScopedLayers', () => {
diff --git a/packages/core/system-prompt/tests/scoped.spec.ts b/packages/core/system-prompt/tests/scoped.spec.ts
index a3c85b7886..23b55201b2 100644
--- a/packages/core/system-prompt/tests/scoped.spec.ts
+++ b/packages/core/system-prompt/tests/scoped.spec.ts
@@ -101,6 +101,28 @@ describe('scoped variables', () => {
     const again = await mintScope(ctx, 'child2')
     again.ctx.systemPrompt.variable('v', () => '3')
   })
+
+  it('defers a scoped variable that replaces the last provider in its generation', async () => {
+    const ctx = await mount({ persona: 'Mode: {{mode}}.' })
+    const scope = await mintScope(ctx, 'child')
+    const key = scopeKeyOf(scope)
+    const calls: string[] = []
+    scope.ctx.systemPrompt.section({ name: 'scope:sibling', order: 1, text: 'Scoped.' })
+    const dispose = scope.ctx.systemPrompt.variable('mode', () => {
+      calls.push('first')
+      dispose()
+      scope.ctx.systemPrompt.variable('mode', () => {
+        calls.push('replacement')
+        return 'replacement'
+      })
+      return 'first'
+    })
+
+    expect(renderPrompt(await ctx.systemPrompt.assemble({ scope: key }))).toContain('Mode: first.')
+    expect(calls).toEqual(['first'])
+    expect(renderPrompt(await ctx.systemPrompt.assemble({ scope: key }))).toContain('Mode: replacement.')
+    expect(calls).toEqual(['first', 'replacement'])
+  })
 })
 
 describe('scoped tool providers and toolOrder × restriction', () => {
diff --git a/packages/core/tools/tests/scoped.spec.ts b/packages/core/tools/tests/scoped.spec.ts
index cab0ee7155..a18adf8593 100644
--- a/packages/core/tools/tests/scoped.spec.ts
+++ b/packages/core/tools/tests/scoped.spec.ts
@@ -287,6 +287,28 @@ describe('scoped execution dispatch', () => {
     expect(calls).toEqual(['first', 'late'])
   })
 
+  it('defers a scoped guard that replaces the last guard in its generation', async () => {
+    const ctx = await mount()
+    const { scope, key } = await mintAgentScope(ctx, 'a')
+    const calls: string[] = []
+    ctx.tools.register(tool('t'))
+    scope.ctx.tools.register(tool('scope_sibling'))
+    const lift = scope.ctx.tools.guard(() => {
+      calls.push('first')
+      lift()
+      scope.ctx.tools.guard(() => {
+        calls.push('replacement')
+        return 'replacement denial'
+      })
+      return undefined
+    })
+
+    expect(await run(ctx, 't', key)).toBe('ran:t')
+    expect(calls).toEqual(['first'])
+    expect(await run(ctx, 't', key)).toBe('Error: replacement denial')
+    expect(calls).toEqual(['first', 'replacement'])
+  })
+
   it('shares one token and materialized argument value across the pipeline', async () => {
     const ctx = await mount()
     const { scope, key } = await mintAgentScope(ctx, 'a')

From 48395a937cfada484d90e613d42d8456d121dc44 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 22 Jul 2026 12:37:42 +0800
Subject: [PATCH 64/74] test(web): disable unreliable DeepSeek search smoke

---
 .../implemented/testing/2026-06-19-real-api-e2e-ci.md  |  2 ++
 packages/web/web-search-deepseek/tests/deepseek.e2e.ts | 10 ++++------
 2 files changed, 6 insertions(+), 6 deletions(-)

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 36160de354..05da5152ff 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
@@ -56,6 +56,8 @@ The repo secret is named `DEEPSEEK_API_KEY_EXTERNAL`; it is mapped to the `DEEPS
 
 The job runs only `test:e2e` on Node 24; keyless gates and version compatibility belong to the main CI workflow. Tests run unbuilt through the workspace paths map with a bounded configurable worker pool, per-test retries, and a job timeout. Superseded PR runs are cancelled, while push and scheduled runs complete for post-merge signal.
 
+The DeepSeek native `web_search` probe is registered but skipped. The live Anthropic-compatible endpoint can return a successful response without structured source blocks, so its positive-source assertion is not a reliable merge signal; unit coverage still pins response parsing, but CI does not prove the live source-block wire shape.
+
 ## Security
 
 The repository's first CI secret requires a recorded threat model because access differs between same-repository, fork, and Dependabot pull requests and changes when the repository becomes public.
diff --git a/packages/web/web-search-deepseek/tests/deepseek.e2e.ts b/packages/web/web-search-deepseek/tests/deepseek.e2e.ts
index 03c99f9d9b..e86be695b2 100644
--- a/packages/web/web-search-deepseek/tests/deepseek.e2e.ts
+++ b/packages/web/web-search-deepseek/tests/deepseek.e2e.ts
@@ -9,17 +9,15 @@ import {
 } from '@deepseek-ai/dsh-web-search-deepseek'
 
 /**
- * Real-API smoke for the DeepSeek search provider. Self-skips without
- * `$DEEPSEEK_API_KEY`, per the with-key e2e policy in docs/testing.md. This
- * is the only test that proves DeepSeek's Anthropic-compatible endpoint actually
- * triggers native `web_search` and returns the structured result blocks the
- * provider parses — a mock cannot confirm the wire shape is real.
+ * Disabled real-API probe for the DeepSeek search provider. The live endpoint
+ * can complete without structured source blocks, so this is not a reliable
+ * merge signal. Its body remains because mocks cannot confirm the wire shape.
  */
 const apiKey = process.env.DEEPSEEK_API_KEY
 const maybe = apiKey !== undefined && apiKey.length > 0 ? describe : describe.skip
 
 maybe('DeepSeekSearchProvider real API', () => {
-  it('returns citeable sources for a live query via native web_search', async () => {
+  it.skip('returns citeable sources for a live query via native web_search', async () => {
     const provider = new DeepSeekSearchProvider({
       apiKey: apiKey!,
       baseURL: process.env.DEEPSEEK_SEARCH_BASE_URL ?? DEEPSEEK_DEFAULT_BASE_URL,

From d1236963bfc2ef5bea37f5d69de0244991b436b5 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 22 Jul 2026 12:37:51 +0800
Subject: [PATCH 65/74] docs(config): refresh catalog after Windows merge

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

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 34d643f360..496c254ef3 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1493,7 +1493,7 @@ export interface TuiConfig {
 }
 ```
 
-Source: [`packages/ui/tui/src/index.ts:128`](../packages/ui/tui/src/index.ts)
+Source: [`packages/ui/tui/src/index.ts:129`](../packages/ui/tui/src/index.ts)
 
 ## `@deepseek-ai/dsh-tui-demo`
 

From 4643e0de10e683e307dd44d6c463c8134ecb33c0 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 22 Jul 2026 13:10:48 +0800
Subject: [PATCH 66/74] test(windows): make coverage fixtures portable

---
 ...-22-cross-platform-test-fixtures.i18n.yaml |  6 +++
 ...2026-07-22-cross-platform-test-fixtures.md | 31 +++++++++++++++
 ...6-07-22-cross-platform-test-fixtures.zh.md | 31 +++++++++++++++
 .../tests/workspace-context.spec.ts           |  4 +-
 .../lsp/lsp-local/tests/connection.spec.ts    |  2 +-
 .../lsp/lsp-local/tests/fixture-server.ts     | 15 ++++++--
 packages/lsp/lsp-local/tests/host.spec.ts     |  3 +-
 packages/lsp/lsp-local/tests/provider.spec.ts |  3 +-
 packages/lsp/tool-lsp/tests/render.spec.ts    | 13 ++++---
 packages/lsp/tool-lsp/tests/tool-lsp.spec.ts  | 38 ++++++++++---------
 .../sdk/telemetry/tests/anonymous-id.spec.ts  |  2 +-
 .../subagent-acp/tests/subagent-acp.spec.ts   |  3 +-
 12 files changed, 117 insertions(+), 34 deletions(-)
 create mode 100644 .agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml
 create mode 100644 .agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md
 create mode 100644 .agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md

diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml
new file mode 100644
index 0000000000..d1b133cb72
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-22-cross-platform-test-fixtures.md: 83af904db5d004366021d4ba6bead656ff813dae
+2026-07-22-cross-platform-test-fixtures.zh.md: 3570c393f8d2fc3344aa43ff0eb8291500d07e1c
diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md
new file mode 100644
index 0000000000..83af904db5
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md
@@ -0,0 +1,31 @@
+# Agent Note: Keep supported-platform tests semantic
+
+Status: implemented
+
+English | [中文](2026-07-22-cross-platform-test-fixtures.zh.md)
+
+## Problem
+
+The unit and coverage suites run on Windows, macOS, and Linux, but a platform-neutral behavior can be hidden behind a platform-specific fixture. Literal POSIX paths become drive-relative paths on Windows, a hosted `file:` URI can be a valid UNC path there, and numeric file descriptor `0` is not the sole owner of Node's pipe-backed child stdin. POSIX-only filesystem states such as FIFOs, executable mode bits, and directory search bits have no direct Windows fixture.
+
+Treating fixture syntax as product behavior either reports false regressions or encourages production normalization that erases native path semantics.
+
+## Decision
+
+Tests of platform-neutral behavior construct absolute paths and `file:` URIs with the host's `node:path` and `node:url` APIs, then assert native absolute output or stable workspace-relative output as the contract requires. Invalid-URI fixtures use encodings rejected by `fileURLToPath()` on every supported platform.
+
+Subprocess fixtures that require the parent write side to fail close both the CRT descriptor and the libuv handle owning child stdin. This pins the connection failure contract across POSIX descriptor-backed and Windows pipe-backed processes while keeping the child alive long enough to distinguish pipe failure from process exit.
+
+Tests for a genuinely POSIX-only primitive use a narrow Windows exclusion on that case. Adjacent cross-platform cases continue to pin non-regular file rejection, unavailable command rejection, and inaccessible working-directory rejection.
+
+## Alternatives considered
+
+**Normalize all paths and URIs to POSIX strings.** This would make assertions uniform but would change correct Windows behavior: external paths are native absolute paths, UNC file URIs are valid, and configured homes resolve through the host path rules.
+
+**Run POSIX fixtures through a compatibility shell on Windows.** A compatibility environment would test different filesystem and process semantics from the native Node runtime exercised by the product.
+
+**Skip whole files or packages on Windows.** Broad exclusions would hide supported behavior. Only the individual fixture whose state cannot exist on Windows is excluded; the surrounding contract remains covered.
+
+## Consequences
+
+Portable fixtures are slightly more verbose because expected paths derive from shared native constants. Platform-only exclusions require a neighboring cross-platform assertion for the product behavior they support. Pipe-failure fixtures depend on Node's test-runtime handle shape, but that dependency stays inside the scripted child and proves the real parent-side stream behavior rather than mocking it.
diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md
new file mode 100644
index 0000000000..3570c393f8
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md
@@ -0,0 +1,31 @@
+# Agent Note: 让受支持平台的测试聚焦语义
+
+Status: implemented
+
+[English](2026-07-22-cross-platform-test-fixtures.md) | 中文
+
+## 问题
+
+单元测试与覆盖率测试套件会在 Windows、macOS 和 Linux 上运行，但平台无关行为可能被平台特有的 fixture（测试前置数据）掩盖。字面 POSIX 路径在 Windows 上会变成相对于驱动器的路径；带主机名的 `file:` URI 在 Windows 上可能是有效的 UNC 路径；在 Node 中，编号为 `0` 的文件描述符也不是子进程管道型 stdin 的唯一持有者。FIFO、可执行模式位和目录搜索权限位等仅存在于 POSIX 的文件系统状态，在 Windows 上没有可直接构造的 fixture。
+
+把 fixture 语法当成产品行为，要么会误报回归，要么会促使生产代码引入抹去原生路径语义的归一化。
+
+## 决策
+
+测试平台无关行为时，使用宿主的 `node:path` 和 `node:url` API 构造绝对路径与 `file:` URI，再根据契约要求断言原生绝对输出或稳定的工作区相对输出。无效 URI fixture 使用一种在所有受支持平台上都会被 `fileURLToPath()` 拒绝的编码形式。
+
+需要使父进程写端失败的子进程 fixture 会同时关闭 CRT 文件描述符和持有子进程 stdin 的 libuv 句柄。这种方式在以 POSIX 文件描述符为后端的进程和以 Windows 管道为后端的进程上固定了连接失败契约，同时让子进程存活足够长的时间，以区分管道故障与进程退出。
+
+对于真正仅存在于 POSIX 的原语，测试只在该用例上排除 Windows。相邻的跨平台用例仍会固定拒绝非普通文件、不可用命令和无法访问的工作目录的行为。
+
+## 曾考虑的替代方案
+
+**将所有路径和 URI 归一化为 POSIX 字符串。**这会使断言保持一致，但也会改变正确的 Windows 行为：外部路径是原生绝对路径，UNC 文件 URI 有效，而且已配置的主目录会按照宿主路径规则解析。
+
+**在 Windows 上通过兼容性 shell 运行 POSIX fixture。**这种兼容环境测试的文件系统与进程语义不同于产品实际使用的原生 Node 运行时。
+
+**在 Windows 上跳过整个测试文件或包。**过宽的排除会隐藏受支持的行为。只排除无法在 Windows 上构造相应状态的单项 fixture；相关契约仍保持覆盖。
+
+## 后果
+
+可移植 fixture 略显冗长，因为预期路径需要从共享的原生常量派生。仅适用于特定平台的排除项必须配有相邻的跨平台断言，以继续覆盖相应的产品行为。管道故障 fixture 依赖 Node 测试运行时的句柄形态，但这种依赖仅存在于脚本化的子进程内；因此，这类 fixture 验证的是真实的父进程侧流行为，而不是对它进行 mock。
diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts
index 658c636d82..9c5cb3b0d3 100644
--- a/packages/context/workspace-context/tests/workspace-context.spec.ts
+++ b/packages/context/workspace-context/tests/workspace-context.spec.ts
@@ -1143,8 +1143,8 @@ describe('workspace context request injection', () => {
   })
 
   it('keeps the direct provider API usable without an operation signal', async () => {
-    const root = '/virtual/no-signal-repo'
-    const home = '/virtual/no-signal-home'
+    const root = resolve('/virtual/no-signal-repo')
+    const home = resolve('/virtual/no-signal-home')
     const ctx = new Context()
     try {
       await ctx.plugin(RecordingFileSystem)
diff --git a/packages/lsp/lsp-local/tests/connection.spec.ts b/packages/lsp/lsp-local/tests/connection.spec.ts
index 6d9ca6d6a3..aa8e1aa817 100644
--- a/packages/lsp/lsp-local/tests/connection.spec.ts
+++ b/packages/lsp/lsp-local/tests/connection.spec.ts
@@ -210,7 +210,7 @@ describe('LspConnection edge behavior', () => {
   })
 
   it('rejects a pending request when child stdin closes but the process stays alive', async () => {
-    const conn = connectScript('require("node:fs").closeSync(0); setInterval(()=>{}, 1000)')
+    const conn = connectScript('const stdin=process.stdin; require("node:fs").closeSync(0); stdin._handle?.close(); setInterval(()=>{}, 1000)')
     await new Promise<void>(resolve => setTimeout(resolve, 100))
     const timeout = new Promise<never>((_resolve, reject) => {
       setTimeout(() => { reject(new Error('request timed out')) }, 1000)
diff --git a/packages/lsp/lsp-local/tests/fixture-server.ts b/packages/lsp/lsp-local/tests/fixture-server.ts
index c418ada519..2b7fb76b2f 100644
--- a/packages/lsp/lsp-local/tests/fixture-server.ts
+++ b/packages/lsp/lsp-local/tests/fixture-server.ts
@@ -16,8 +16,8 @@
  * - LSP_FAKE_OPEN_MARKER: appends each didOpen document text as one JSON line to this path.
  * - LSP_FAKE_INITIALIZED_MARKER: records when the initialized notification is received.
  * - LSP_FAKE_PAUSE_STDIN_AFTER_INITIALIZED: "1" stops consuming stdin after initialized.
- * - LSP_FAKE_CLOSE_STDIN_AFTER_INITIALIZED: "1" closes fd 0 after the initialized notification.
- * - LSP_FAKE_CLOSE_STDIN_AFTER_REPLY: "1" closes fd 0 before sending the first query response.
+ * - LSP_FAKE_CLOSE_STDIN_AFTER_INITIALIZED: "1" closes the stdin pipe after initialization.
+ * - LSP_FAKE_CLOSE_STDIN_AFTER_REPLY: "1" closes the stdin pipe before the first query response.
  * - LSP_FAKE_EXIT_DELAY_MS / LSP_FAKE_EXIT_MARKER: delay protocol exit and record exit/termination.
  * - LSP_FAKE_NO_SHUTDOWN: "1" ignores the shutdown request (forces kill escalation).
  * - LSP_FAKE_ON_OPEN: server→client request to emit when a didOpen arrives, one of
@@ -146,14 +146,14 @@ function handle(message: { id?: number; method?: string; params?: unknown; resul
   if (method === 'initialized') {
     if (initializedMarker !== undefined) appendFileSync(initializedMarker, 'INITIALIZED\n')
     if (pauseStdinAfterInitialized) process.stdin.pause()
-    if (closeStdinAfterInitialized) closeSync(0)
+    if (closeStdinAfterInitialized) closeStdinPipe()
     return
   }
   if (method === 'textDocument/didClose') return
   if (method?.startsWith('textDocument/')) {
     if (hang) return
     const reply = (): void => {
-      if (closeStdinAfterReply) closeSync(0)
+      if (closeStdinAfterReply) closeStdinPipe()
       if (errorReply) {
         send({ id, error: { code: -32000, message: 'server refused the request' } })
       } else {
@@ -171,6 +171,13 @@ function handle(message: { id?: number; method?: string; params?: unknown; resul
   if (id !== undefined) send({ id, result: null })
 }
 
+/** Close both the CRT descriptor and libuv handle that can own a platform's child-stdin pipe. */
+function closeStdinPipe(): void {
+  const stdin = process.stdin as NodeJS.ReadStream & { _handle?: { close(): void } }
+  closeSync(0)
+  stdin._handle?.close()
+}
+
 /** Append one teardown event when the fixture is configured to expose process ordering. */
 function markExit(event: string): void {
   if (exitMarker !== undefined) appendFileSync(exitMarker, `${event}\n`)
diff --git a/packages/lsp/lsp-local/tests/host.spec.ts b/packages/lsp/lsp-local/tests/host.spec.ts
index 8629502fd1..26aacdc1f4 100644
--- a/packages/lsp/lsp-local/tests/host.spec.ts
+++ b/packages/lsp/lsp-local/tests/host.spec.ts
@@ -92,7 +92,8 @@ describe('readHostSource', () => {
     await expect(readHostSource('dir', ws, BIG)).rejects.toThrow(/not a regular file/)
   })
 
-  it('rejects a FIFO with no writer without blocking in open', async () => {
+  // Windows has no filesystem FIFO; the directory case above pins non-regular rejection there.
+  it.skipIf(process.platform === 'win32')('rejects a FIFO with no writer without blocking in open', async () => {
     const fifo = join(ws, 'pipe.ts')
     await execFileAsync('mkfifo', [fifo])
     using d = deadline(undefined, 1000, 'FIFO_READ_TIMEOUT')
diff --git a/packages/lsp/lsp-local/tests/provider.spec.ts b/packages/lsp/lsp-local/tests/provider.spec.ts
index 8746b7a903..7a969781f3 100644
--- a/packages/lsp/lsp-local/tests/provider.spec.ts
+++ b/packages/lsp/lsp-local/tests/provider.spec.ts
@@ -116,7 +116,8 @@ describe('lsp-local provider resolution', () => {
     await ctx.fiber.dispose()
   })
 
-  it('rejects an absolute command that is not executable at load', async () => {
+  // Node's X_OK probe is an existence check on Windows, which has no executable mode bit.
+  it.skipIf(process.platform === 'win32')('rejects an absolute command that is not executable at load', async () => {
     const notExe = join(root, 'not-exe.txt')
     await writeFile(notExe, 'plain text, not executable')
     const ctx = new Context()
diff --git a/packages/lsp/tool-lsp/tests/render.spec.ts b/packages/lsp/tool-lsp/tests/render.spec.ts
index a277539879..1fd0eeba51 100644
--- a/packages/lsp/tool-lsp/tests/render.spec.ts
+++ b/packages/lsp/tool-lsp/tests/render.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { pathToFileURL } from 'node:url'
-import { join } from 'node:path'
+import { join, resolve } from 'node:path'
 import {
   DEFAULT_MAX_LOCATIONS,
   DEFAULT_MAX_RESULT_CHARS,
@@ -13,7 +13,7 @@ import {
 } from '@deepseek-ai/dsh-tool-lsp'
 import type { LspLocation } from '@deepseek-ai/dsh-lsp'
 
-const WS = '/home/u/proj'
+const WS = resolve('/home/u/proj')
 
 function loc(uri: string, line: number, character = 0): LspLocation {
   return { uri, range: { start: { line, character }, end: { line, character: character + 1 } } }
@@ -52,8 +52,9 @@ describe('renderUri', () => {
   })
 
   it('returns an absolute path for a file: URI outside the workspace', () => {
-    const uri = pathToFileURL('/other/lib/b.ts').href
-    expect(renderUri(uri, WS)).toBe('/other/lib/b.ts')
+    const outside = resolve(WS, '..', 'other', 'lib', 'b.ts')
+    const uri = pathToFileURL(outside).href
+    expect(renderUri(uri, WS)).toBe(outside)
   })
 
   it('renders the workspace root itself as "."', () => {
@@ -72,8 +73,8 @@ describe('renderUri', () => {
   })
 
   it('keeps a malformed file: URI verbatim when it cannot be parsed to a path', () => {
-    // A file: URI with a host that fileURLToPath rejects falls through to the verbatim path.
-    expect(renderUri('file://host/notlocal', WS)).toBe('file://host/notlocal')
+    // An encoded path separator is invalid on every platform and must remain verbatim.
+    expect(renderUri('file:///bad%2Fpath', WS)).toBe('file:///bad%2Fpath')
   })
 })
 
diff --git a/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts b/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts
index 143e923b38..b141fd00dd 100644
--- a/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts
+++ b/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts
@@ -1,4 +1,6 @@
 import { describe, expect, it } from 'vitest'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import { Context } from 'cordis'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
@@ -40,8 +42,11 @@ async function mount(
 
 let seq = 0
 const testToolSignal = new AbortController().signal
+const workspaceRoot = resolve('/virtual/workspace')
+const resolvedWorkspaceRoot = resolve('/virtual/real-workspace')
+const workspaceAlias = resolve('/virtual/workspace-alias')
 /** `cwd: null` means "no agent" (tests LSP_WORKSPACE_REQUIRED); a string is the session cwd. */
-function call(ctx: Context, args: unknown, cwd: string | null = '/ws') {
+function call(ctx: Context, args: unknown, cwd: string | null = workspaceRoot) {
   return ctx.tools.execute({
     signal: testToolSignal,
     callId: `c-${++seq}` as never,
@@ -53,8 +58,8 @@ function call(ctx: Context, args: unknown, cwd: string | null = '/ws') {
 
 const okLocations: LspQueryResult = {
   kind: 'locations',
-  locations: [{ uri: 'file:///ws/a.ts', range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } } }],
-  resolvedWorkspaceRoot: '/ws',
+  locations: [{ uri: pathToFileURL(join(workspaceRoot, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } } }],
+  resolvedWorkspaceRoot: workspaceRoot,
 }
 
 describe('tool-lsp registration', () => {
@@ -107,40 +112,39 @@ describe('tool-lsp execution', () => {
   it('converts one-based coordinates and passes the session cwd as workspaceRoot', async () => {
     const provider = stubProvider(() => okLocations)
     const { ctx } = await mount(provider)
-    const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 3, character: 5 }, '/ws')
+    const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 3, character: 5 }, workspaceRoot)
     expect(result.isError).toBe(false)
     expect(provider.seen[0]).toMatchObject({
       operation: 'goToDefinition',
       filePath: 'a.ts',
       position: { line: 2, character: 4 },
-      workspaceRoot: '/ws',
+      workspaceRoot,
     })
   })
 
   it('renders locations relative to the workspace', async () => {
     const { ctx } = await mount(stubProvider(() => okLocations))
-    const result = await call(ctx, { operation: 'findReferences', file_path: 'a.ts', line: 1, character: 1 }, '/ws')
+    const result = await call(ctx, { operation: 'findReferences', file_path: 'a.ts', line: 1, character: 1 }, workspaceRoot)
     expect(result.content[0]).toEqual({ type: 'text', text: 'a.ts:1:1' })
   })
 
   it('relativizes against the provider resolvedWorkspaceRoot, not the session cwd', async () => {
-    // A symlinked session cwd (`/alias`) resolves to a real path (`/real/ws`) that the provider's
-    // location URIs are under. Relativizing against the alias would misclassify the location as
-    // external and print an absolute path; the tool must use resolvedWorkspaceRoot.
+    // A symlinked session cwd resolves to the real path that contains the provider's location URIs.
+    // Relativizing against the alias would misclassify the location as external.
     const provider = stubProvider(() => ({
       kind: 'locations',
-      locations: [{ uri: 'file:///real/ws/a.ts', range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } } }],
-      resolvedWorkspaceRoot: '/real/ws',
+      locations: [{ uri: pathToFileURL(join(resolvedWorkspaceRoot, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } } }],
+      resolvedWorkspaceRoot,
     }))
     const { ctx } = await mount(provider)
-    const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 1 }, '/alias')
-    expect(provider.seen[0]).toMatchObject({ workspaceRoot: '/alias' })
+    const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 1 }, workspaceAlias)
+    expect(provider.seen[0]).toMatchObject({ workspaceRoot: workspaceAlias })
     expect(result.content[0]).toEqual({ type: 'text', text: 'a.ts:1:1' })
   })
 
   it('renders hover content', async () => {
     const { ctx } = await mount(stubProvider(() => ({ kind: 'hover', hover: { contents: 'number' } })))
-    const result = await call(ctx, { operation: 'hover', file_path: 'a.ts', line: 1, character: 1 }, '/ws')
+    const result = await call(ctx, { operation: 'hover', file_path: 'a.ts', line: 1, character: 1 }, workspaceRoot)
     expect(result.content[0]).toEqual({ type: 'text', text: 'number' })
   })
 
@@ -153,14 +157,14 @@ describe('tool-lsp execution', () => {
 
   it('surfaces a structured LSP_UNAVAILABLE when no provider handles the file', async () => {
     const { ctx } = await mount(stubProvider(() => okLocations, { '.py': 'python' }))
-    const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 1 }, '/ws')
+    const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 1 }, workspaceRoot)
     expect(result.isError).toBe(true)
     expect(result.error?.code).toBe('LSP_UNAVAILABLE')
   })
 
   it('returns a structured INVALID_ARGS on a bad operation', async () => {
     const { ctx } = await mount(stubProvider(() => okLocations))
-    const result = await call(ctx, { operation: 'rename', file_path: 'a.ts', line: 1, character: 1 }, '/ws')
+    const result = await call(ctx, { operation: 'rename', file_path: 'a.ts', line: 1, character: 1 }, workspaceRoot)
     expect(result.isError).toBe(true)
     expect(result.error?.code).toBe('INVALID_ARGS')
   })
@@ -176,7 +180,7 @@ describe('tool-lsp execution', () => {
       },
     }
     const { ctx } = await mount(provider)
-    await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 1 }, '/ws')
+    await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 1 }, workspaceRoot)
     // The timeout policy is not mounted here, so the signal is whatever the registry passes (may be
     // undefined); the point is the tool threads it through without throwing.
     expect(seen).toHaveLength(1)
diff --git a/packages/sdk/telemetry/tests/anonymous-id.spec.ts b/packages/sdk/telemetry/tests/anonymous-id.spec.ts
index 7bd5fb1924..13ba3a8b76 100644
--- a/packages/sdk/telemetry/tests/anonymous-id.spec.ts
+++ b/packages/sdk/telemetry/tests/anonymous-id.spec.ts
@@ -25,7 +25,7 @@ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 
 describe('globalConfigDir', () => {
   it('prefers an explicit DSH_HOME override', () => {
-    expect(globalConfigDir({ env: { DSH_HOME: '/custom/dsh' } })).toBe('/custom/dsh')
+    expect(globalConfigDir({ env: { DSH_HOME: '/custom/dsh' } })).toBe(resolve('/custom/dsh'))
   })
 
   it('falls back to ~/.dsh when DSH_HOME is unset', () => {
diff --git a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts
index 6592aa43fc..79ef8831cf 100644
--- a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts
+++ b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts
@@ -215,7 +215,8 @@ describe('cwd resolution', () => {
     await ctx.fiber.dispose()
   })
 
-  it('rejects a config cwd directory without search permission at load', async () => {
+  // Windows ACLs do not expose the POSIX directory search-bit state this fixture creates.
+  it.skipIf(process.platform === 'win32')('rejects a config cwd directory without search permission at load', async () => {
     // statSync().isDirectory() is true for a mode-600 directory, but a
     // subprocess cwd needs SEARCH permission — spawn would fail EACCES.
     const tmp = mkdtempSync(join(tmpdir(), 'acp-noexec-'))

From cfdc6fcdfb29a0a608cfe1fc97328a05e551a703 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 22 Jul 2026 13:28:52 +0800
Subject: [PATCH 67/74] test(windows): skip remaining unstable coverage cases

---
 packages/lsp/lsp-local/tests/connection.spec.ts | 2 +-
 packages/lsp/lsp-local/tests/instance.spec.ts   | 4 ++--
 packages/lsp/lsp-local/tests/lifecycle.spec.ts  | 2 +-
 packages/ui/tui/tests/tui.spec.ts               | 2 +-
 4 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/lsp/lsp-local/tests/connection.spec.ts b/packages/lsp/lsp-local/tests/connection.spec.ts
index aa8e1aa817..464848bbf5 100644
--- a/packages/lsp/lsp-local/tests/connection.spec.ts
+++ b/packages/lsp/lsp-local/tests/connection.spec.ts
@@ -209,7 +209,7 @@ describe('LspConnection edge behavior', () => {
     await expect(conn.request('initialize', {})).rejects.toThrow(/exited|closed/)
   })
 
-  it('rejects a pending request when child stdin closes but the process stays alive', async () => {
+  it.skipIf(process.platform === 'win32')('rejects a pending request when child stdin closes but the process stays alive', async () => {
     const conn = connectScript('const stdin=process.stdin; require("node:fs").closeSync(0); stdin._handle?.close(); setInterval(()=>{}, 1000)')
     await new Promise<void>(resolve => setTimeout(resolve, 100))
     const timeout = new Promise<never>((_resolve, reject) => {
diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts
index 328c8b7313..aeb6410e61 100644
--- a/packages/lsp/lsp-local/tests/instance.spec.ts
+++ b/packages/lsp/lsp-local/tests/instance.spec.ts
@@ -200,7 +200,7 @@ describe('LspInstance query and abort', () => {
     expect(instance.dead).toBe(true)
   })
 
-  it('terminates when stdin fails during the didOpen write', async () => {
+  it.skipIf(process.platform === 'win32')('terminates when stdin fails during the didOpen write', async () => {
     // Closing stdin after initialized makes a large didOpen fail before `opened` can arm didClose;
     // the instance must still become dead so its provider can replace it.
     await writeFile(join(ws, 'a.ts'), 'x'.repeat(2_000_000))
@@ -225,7 +225,7 @@ describe('LspInstance query and abort', () => {
     await expect(run(instance, 'goToDefinition', controller.signal)).rejects.toThrow(/server refused/)
   })
 
-  it('keeps a settled result but awaits teardown when didClose cannot be written', async () => {
+  it.skipIf(process.platform === 'win32')('keeps a settled result but awaits teardown when didClose cannot be written', async () => {
     const instance = makeInstance({
       LSP_FAKE_DEF: 'null',
       LSP_FAKE_CLOSE_STDIN_AFTER_REPLY: '1',
diff --git a/packages/lsp/lsp-local/tests/lifecycle.spec.ts b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
index 826905ed26..7ba76d03de 100644
--- a/packages/lsp/lsp-local/tests/lifecycle.spec.ts
+++ b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
@@ -237,7 +237,7 @@ describe('lsp-local end to end over a fake server', () => {
     await ctx.fiber.dispose()
   })
 
-  it('evicts a pooled server that died while idle and serves the next query from a fresh one', async () => {
+  it.skipIf(process.platform === 'win32')('evicts a pooled server that died while idle and serves the next query from a fresh one', async () => {
     // The first query succeeds, then the server exits before the second arrives, leaving a dead
     // instance in the pool. The next query must evict-and-replace it and still succeed, rather than
     // failing once on the closed connection first.
diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts
index 17c9709860..fc4f92dfad 100644
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -198,7 +198,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
     await dispose(result)
   })
 
-  it('renders its header, footer, replay, streaming answer, todos, and status', async () => {
+  it.skipIf(process.platform === 'win32')('renders its header, footer, replay, streaming answer, todos, and status', async () => {
     let now = 0
     const result = await setup({
       contextWindow: 100,

From 6f167152993b85458f6a3ec921e180d2a6e15578 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 22 Jul 2026 13:37:44 +0800
Subject: [PATCH 68/74] test(windows): skip process-group disposal race

---
 packages/lsp/lsp-local/tests/instance.spec.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts
index aeb6410e61..343233c4f5 100644
--- a/packages/lsp/lsp-local/tests/instance.spec.ts
+++ b/packages/lsp/lsp-local/tests/instance.spec.ts
@@ -281,7 +281,7 @@ describe('LspInstance disposal', () => {
     await expect(instance.dispose()).resolves.toBeUndefined()
   })
 
-  it('awaits a surviving process-group helper on every concurrent dispose', async () => {
+  it.skipIf(process.platform === 'win32')('awaits a surviving process-group helper on every concurrent dispose', async () => {
     const marker = join(root, 'helper.pid')
     const helper = 'process.on("SIGTERM",()=>{});setInterval(()=>{},1000);'
     const script = 'const{spawn}=require("node:child_process");const{writeFileSync}=require("node:fs");'

From 450e1fff6acb6074f0267b68e2553013d18e5a86 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 22 Jul 2026 13:47:24 +0800
Subject: [PATCH 69/74] test(windows): exclude deferred coverage paths

---
 vitest.config.ts | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/vitest.config.ts b/vitest.config.ts
index c5b5c06d11..8baa7c7b32 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -11,6 +11,17 @@ const windowsUnsupportedPackages = process.platform === 'win32'
     ]
   : []
 
+// These files retain 100% per-file coverage on POSIX, where their process-pipe and terminal timing
+// tests are deterministic; Windows skips those cases and must not fail solely on their uncovered paths.
+const windowsCoverageExclusions = process.platform === 'win32'
+  ? [
+      'packages/lsp/lsp-local/src/connection.ts',
+      'packages/lsp/lsp-local/src/index.ts',
+      'packages/lsp/lsp-local/src/instance.ts',
+      'packages/ui/tui/src/index.ts',
+    ]
+  : []
+
 export default defineConfig({
   // Native path resolution reads each package's nearest tsconfig, but only the root defines
   // workspace paths. Keep this plugin pinned to the root map so unbuilt bare package imports resolve
@@ -33,6 +44,7 @@ export default defineConfig({
         'packages/*/*/src/bin.ts',
         'packages/*/*/src/worker.ts',
         ...windowsUnsupportedPackages.map(path => `${path}/src/**/*.ts`),
+        ...windowsCoverageExclusions,
       ],
       // 100% or it doesn't merge (docs/testing.md: excessive tests are welcome).
       // Per-file so a well-covered big file can't subsidize a bare one.

From 5da343126ccb71228492cf535a1700f28fac0ee0 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 22 Jul 2026 14:23:44 +0800
Subject: [PATCH 70/74] fix(windows): restore LSP and TUI coverage

---
 ...-22-cross-platform-test-fixtures.i18n.yaml |   4 +-
 ...2026-07-22-cross-platform-test-fixtures.md |  12 +-
 ...6-07-22-cross-platform-test-fixtures.zh.md |  12 +-
 packages/lsp/lsp-local/README.md              |   3 +-
 packages/lsp/lsp-local/src/connection.ts      | 157 ++++++++++++++----
 packages/lsp/lsp-local/src/index.ts           |  14 +-
 packages/lsp/lsp-local/src/instance.ts        |  21 +--
 .../lsp/lsp-local/tests/connection.spec.ts    |  80 +++++++--
 .../lsp/lsp-local/tests/fixture-server.ts     |  17 +-
 packages/lsp/lsp-local/tests/instance.spec.ts |  47 ++++--
 .../lsp/lsp-local/tests/lifecycle.spec.ts     |   2 +-
 packages/ui/tui/tests/tui.spec.ts             |   7 +-
 vitest.config.ts                              |  12 --
 13 files changed, 281 insertions(+), 107 deletions(-)

diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml
index d1b133cb72..511b66e345 100644
--- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-22-cross-platform-test-fixtures.md: 83af904db5d004366021d4ba6bead656ff813dae
-2026-07-22-cross-platform-test-fixtures.zh.md: 3570c393f8d2fc3344aa43ff0eb8291500d07e1c
+2026-07-22-cross-platform-test-fixtures.md: 56deaf6306e15c6cf17e83fcbaf36137e5c543f4
+2026-07-22-cross-platform-test-fixtures.zh.md: f61441e2dbe86fa5a580e666fcd08d23b0fadf0b
diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md
index 83af904db5..56deaf6306 100644
--- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md
+++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-22-cross-platform-test-fixtures.zh.md)
 
 ## Problem
 
-The unit and coverage suites run on Windows, macOS, and Linux, but a platform-neutral behavior can be hidden behind a platform-specific fixture. Literal POSIX paths become drive-relative paths on Windows, a hosted `file:` URI can be a valid UNC path there, and numeric file descriptor `0` is not the sole owner of Node's pipe-backed child stdin. POSIX-only filesystem states such as FIFOs, executable mode bits, and directory search bits have no direct Windows fixture.
+The unit and coverage suites run on Windows, macOS, and Linux, but a platform-neutral behavior can be hidden behind a platform-specific fixture. Literal POSIX paths become drive-relative paths on Windows, a hosted `file:` URI can be a valid UNC path there, and child-pipe closure or event-loop scheduling does not settle at the same point on every host. POSIX-only filesystem states such as FIFOs, executable mode bits, and directory search bits have no direct Windows fixture.
 
 Treating fixture syntax as product behavior either reports false regressions or encourages production normalization that erases native path semantics.
 
@@ -14,18 +14,20 @@ Treating fixture syntax as product behavior either reports false regressions or
 
 Tests of platform-neutral behavior construct absolute paths and `file:` URIs with the host's `node:path` and `node:url` APIs, then assert native absolute output or stable workspace-relative output as the contract requires. Invalid-URI fixtures use encodings rejected by `fileURLToPath()` on every supported platform.
 
-Subprocess fixtures that require the parent write side to fail close both the CRT descriptor and the libuv handle owning child stdin. This pins the connection failure contract across POSIX descriptor-backed and Windows pipe-backed processes while keeping the child alive long enough to distinguish pipe failure from process exit.
+Transport-failure tests inject the connection's message writer and deliver the same asynchronous write callback error that a real Node stream would report. The production writer still writes framed messages to child stdin. This keeps a real child alive while the test deterministically distinguishes transport failure from process exit without reaching into platform-specific pipe handles.
 
-Tests for a genuinely POSIX-only primitive use a narrow Windows exclusion on that case. Adjacent cross-platform cases continue to pin non-regular file rejection, unavailable command rejection, and inaccessible working-directory rejection.
+Language-server teardown targets the whole descendant tree through a negative process-group id on POSIX and synchronous `taskkill /T /F` on Windows, with a direct-child fallback when the tree is already gone. A read-only provider query retries once only when its pooled transport becomes dead after the liveness check; errors from a still-live server are not replayed. Terminal tests wait for their observable rendered output instead of assuming one event-loop turn is sufficient.
+
+Tests for a genuinely POSIX-only primitive use a narrow Windows exclusion on that case. Adjacent cross-platform cases continue to pin non-regular file rejection, unavailable command rejection, and inaccessible working-directory rejection. Supported Windows paths remain inside the per-file coverage gate rather than being excluded with their test files.
 
 ## Alternatives considered
 
 **Normalize all paths and URIs to POSIX strings.** This would make assertions uniform but would change correct Windows behavior: external paths are native absolute paths, UNC file URIs are valid, and configured homes resolve through the host path rules.
 
-**Run POSIX fixtures through a compatibility shell on Windows.** A compatibility environment would test different filesystem and process semantics from the native Node runtime exercised by the product.
+**Manipulate child-pipe internals until a write fails.** CRT descriptors and libuv handles have different ownership across hosts and Node versions, so this would test undocumented fixture machinery instead of the connection's write-failure contract.
 
 **Skip whole files or packages on Windows.** Broad exclusions would hide supported behavior. Only the individual fixture whose state cannot exist on Windows is excluded; the surrounding contract remains covered.
 
 ## Consequences
 
-Portable fixtures are slightly more verbose because expected paths derive from shared native constants. Platform-only exclusions require a neighboring cross-platform assertion for the product behavior they support. Pipe-failure fixtures depend on Node's test-runtime handle shape, but that dependency stays inside the scripted child and proves the real parent-side stream behavior rather than mocking it.
+Portable fixtures are slightly more explicit because expected paths derive from shared native constants and transport failures enter through a narrow writer seam. Platform-only exclusions require a neighboring cross-platform assertion for the product behavior they support. Windows teardown depends on the host `taskkill` command after graceful protocol shutdown has failed; a synchronous result keeps disposal bounded and makes descendant exit observable before cleanup returns.
diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md
index 3570c393f8..f61441e2db 100644
--- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md
+++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-单元测试与覆盖率测试套件会在 Windows、macOS 和 Linux 上运行，但平台无关行为可能被平台特有的 fixture（测试前置数据）掩盖。字面 POSIX 路径在 Windows 上会变成相对于驱动器的路径；带主机名的 `file:` URI 在 Windows 上可能是有效的 UNC 路径；在 Node 中，编号为 `0` 的文件描述符也不是子进程管道型 stdin 的唯一持有者。FIFO、可执行模式位和目录搜索权限位等仅存在于 POSIX 的文件系统状态，在 Windows 上没有可直接构造的 fixture。
+单元测试与覆盖率测试套件会在 Windows、macOS 和 Linux 上运行，但平台无关行为可能被平台特有的 fixture（测试前置数据）掩盖。字面 POSIX 路径在 Windows 上会变成相对于驱动器的路径；带主机名的 `file:` URI 在 Windows 上可能是有效的 UNC 路径；子进程管道关闭或事件循环调度在不同宿主上的稳定时点也不一致。FIFO、可执行模式位和目录搜索权限位等仅存在于 POSIX 的文件系统状态，在 Windows 上没有可直接构造的 fixture。
 
 把 fixture 语法当成产品行为，要么会误报回归，要么会促使生产代码引入抹去原生路径语义的归一化。
 
@@ -14,18 +14,20 @@ Status: implemented
 
 测试平台无关行为时，使用宿主的 `node:path` 和 `node:url` API 构造绝对路径与 `file:` URI，再根据契约要求断言原生绝对输出或稳定的工作区相对输出。无效 URI fixture 使用一种在所有受支持平台上都会被 `fileURLToPath()` 拒绝的编码形式。
 
-需要使父进程写端失败的子进程 fixture 会同时关闭 CRT 文件描述符和持有子进程 stdin 的 libuv 句柄。这种方式在以 POSIX 文件描述符为后端的进程和以 Windows 管道为后端的进程上固定了连接失败契约，同时让子进程存活足够长的时间，以区分管道故障与进程退出。
+传输故障测试会注入连接的消息写入器，并传入与真实 Node 流相同的异步写入回调错误。生产写入器仍会把分帧消息写入子进程 stdin。这种方式让真实子进程保持存活，使测试无需触及平台特有的管道句柄，也能确定性地区分传输故障与进程退出。
 
-对于真正仅存在于 POSIX 的原语，测试只在该用例上排除 Windows。相邻的跨平台用例仍会固定拒绝非普通文件、不可用命令和无法访问的工作目录的行为。
+语言服务器的资源清理会终止整棵后代进程树：POSIX 使用负数进程组 ID，Windows 同步执行 `taskkill /T /F`；若进程树已经不存在，则回退到直接终止子进程。只读的提供方查询仅在池化传输于存活检查后失效时重试一次；服务器仍存活时返回的错误不会重放。终端测试会等待可观察的渲染输出，不假设一次事件循环轮转已经足够。
+
+对于真正仅存在于 POSIX 的原语，测试只在该用例上排除 Windows。相邻的跨平台用例仍会固定拒绝非普通文件、不可用命令和无法访问的工作目录的行为。Windows 上受支持的路径仍受逐文件覆盖率门禁约束，不会随测试文件一起排除。
 
 ## 曾考虑的替代方案
 
 **将所有路径和 URI 归一化为 POSIX 字符串。**这会使断言保持一致，但也会改变正确的 Windows 行为：外部路径是原生绝对路径，UNC 文件 URI 有效，而且已配置的主目录会按照宿主路径规则解析。
 
-**在 Windows 上通过兼容性 shell 运行 POSIX fixture。**这种兼容环境测试的文件系统与进程语义不同于产品实际使用的原生 Node 运行时。
+**操纵子进程管道内部状态，直至写入失败。**CRT 描述符与 libuv 句柄在不同宿主和 Node 版本上的所有权不同，因此这种做法测试的是未文档化的 fixture 机制，而非连接的写入失败契约。
 
 **在 Windows 上跳过整个测试文件或包。**过宽的排除会隐藏受支持的行为。只排除无法在 Windows 上构造相应状态的单项 fixture；相关契约仍保持覆盖。
 
 ## 后果
 
-可移植 fixture 略显冗长，因为预期路径需要从共享的原生常量派生。仅适用于特定平台的排除项必须配有相邻的跨平台断言，以继续覆盖相应的产品行为。管道故障 fixture 依赖 Node 测试运行时的句柄形态，但这种依赖仅存在于脚本化的子进程内；因此，这类 fixture 验证的是真实的父进程侧流行为，而不是对它进行 mock。
+可移植 fixture 需要更显式地构造，因为预期路径要从共享的原生常量派生，传输故障则通过狭窄的写入器 seam 注入。仅适用于特定平台的排除项必须配有相邻的跨平台断言，以继续覆盖相应的产品行为。协议级优雅关停失败后，Windows 上的资源清理依赖宿主的 `taskkill` 命令；同步取得命令结果让 dispose 的完成边界明确，并确保清理返回前即可观察到后代进程退出。
diff --git a/packages/lsp/lsp-local/README.md b/packages/lsp/lsp-local/README.md
index 85cc7945dd..269fe6b666 100644
--- a/packages/lsp/lsp-local/README.md
+++ b/packages/lsp/lsp-local/README.md
@@ -7,9 +7,10 @@ Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export).
 ## What it does
 
 - Resolves every server-local setting before registration; an invalid mapping or registration conflict rolls back earlier entries, so a failed load leaves no provider routes.
-- Lazily single-flights one server process per `(server id, canonical workspace realpath)`. A crash fails the active query without replay; a later query may replace the process.
+- Lazily single-flights one server process per `(server id, canonical workspace realpath)`. A live server error is not replayed; if the transport becomes dead between the pool's liveness check and a read-only query, the provider evicts it and retries that query once on a fresh process.
 - Uses a compatibility-first **transient-open** sequence per query: canonicalize and read the source with Node APIs, `textDocument/didOpen` (version 1, full text), the requested request, then `textDocument/didClose` in `finally`. A failed or canceled `didOpen` write terminates the instance before the pool can reuse it. Documents close after each call, so the first version needs no `didChange`, content cache, or document LRU.
 - Serializes each source-read/open/query/close lifecycle through one abortable per-workspace queue so queued calls read current source only when their turn starts; distinct workspaces run in parallel.
+- After protocol shutdown fails, terminates the server's descendant tree through POSIX process-group signaling or synchronous Windows `taskkill /T /F`, with a direct-child fallback for teardown races.
 - Reads sources through Node filesystem APIs in the subprocess's host namespace — NOT `ctx.fs`, and emits no `fs/observed`: only the LSP result is model-visible, so a query does not satisfy read-before-write policy.
 
 ## Configuration
diff --git a/packages/lsp/lsp-local/src/connection.ts b/packages/lsp/lsp-local/src/connection.ts
index ae725b56f7..201cd87bdd 100644
--- a/packages/lsp/lsp-local/src/connection.ts
+++ b/packages/lsp/lsp-local/src/connection.ts
@@ -8,7 +8,7 @@
  */
 
 import type { ChildProcessByStdio } from 'node:child_process'
-import { spawn } from 'node:child_process'
+import { spawn, spawnSync } from 'node:child_process'
 import type { Readable, Writable } from 'node:stream'
 import { setImmediate as yieldToEventLoop } from 'node:timers/promises'
 import { encodeMessage, MessageDecoder } from './framing.ts'
@@ -36,6 +36,105 @@ interface Pending {
   reject: (error: Error) => void
 }
 
+/**
+ * Write one JSON-RPC message to the child stdin.
+ * @param stdin - the spawned server stdin.
+ * @param message - the unencoded JSON-RPC message.
+ * @param done - callback that reports asynchronous stream settlement.
+ */
+export type ConnectionWriter = (
+  stdin: Writable,
+  message: unknown,
+  done: (error?: Error | null) => void,
+) => void
+
+/** Host operations used to signal a detached process tree. */
+export interface ProcessTreeOperations {
+  /** Signal a POSIX process group. */
+  readonly signal: (target: number, signal: NodeJS.Signals) => void
+  /** Signal the direct child when group/tree signalling is unavailable. */
+  readonly killChild: (signal: NodeJS.Signals) => void
+  /** Terminate a Windows process tree by root pid. */
+  readonly taskkill: (pid: number) => void
+}
+
+/** Narrow taskkill runner result used by the Windows process-tree adapter. */
+export interface TaskkillResult {
+  /** Process exit status, or null when spawning failed. */
+  readonly status: number | null
+  /** Spawn failure, when the executable could not run. */
+  readonly error?: Error
+}
+
+/** Invoke a command synchronously for the Windows taskkill adapter. */
+export type TaskkillRunner = (
+  command: string,
+  args: string[],
+  options: { stdio: 'ignore' },
+) => TaskkillResult
+
+/** Invoke the host process-signal primitive for a POSIX process group. */
+export type ProcessSignalRunner = (target: number, signal: NodeJS.Signals) => boolean
+
+const processSignalRunner: ProcessSignalRunner = process.kill.bind(process)
+
+const writeConnectionMessage: ConnectionWriter = (stdin, message, done) => {
+  stdin.write(encodeMessage(message), done)
+}
+
+/**
+ * Terminate one Windows process tree and wait for taskkill to finish.
+ * @param pid - root process id.
+ * @param run - command runner; tests inject results without requiring Windows.
+ */
+export function taskkillProcessTree(
+  pid: number,
+  run: TaskkillRunner = spawnSync,
+): void {
+  const result = run('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' })
+  if (result.error !== undefined) throw result.error
+  if (result.status !== 0) throw new Error(`taskkill exited with status ${String(result.status)}`)
+}
+
+/**
+ * Signal one POSIX process group through an injectable host primitive.
+ * @param target - negative process-group id.
+ * @param signal - requested signal.
+ * @param run - host signal runner; tests inject it without touching real processes.
+ */
+export function signalProcessGroup(
+  target: number,
+  signal: NodeJS.Signals,
+  run: ProcessSignalRunner = processSignalRunner,
+): void {
+  run(target, signal)
+}
+
+/**
+ * Signal a detached process tree with platform-correct semantics and a direct-child fallback.
+ * @param platform - host platform.
+ * @param pid - detached root process id.
+ * @param signal - requested termination signal.
+ * @param operations - host operations.
+ */
+export function signalProcessTree(
+  platform: NodeJS.Platform,
+  pid: number,
+  signal: NodeJS.Signals,
+  operations: ProcessTreeOperations,
+): void {
+  try {
+    if (platform === 'win32') operations.taskkill(pid)
+    else operations.signal(-pid, signal)
+  } catch {
+    try {
+      operations.killChild(signal)
+    } catch {
+      // The direct child already exited; teardown remains idempotent.
+    }
+  }
+}
+
 /** A live JSON-RPC endpoint bound to one child process. */
 export class LspConnection {
   private readonly child: ChildProcessByStdio<Writable, Readable, Readable>
@@ -50,14 +149,16 @@ export class LspConnection {
   /**
    * @param spec - how to launch the server and answer its config requests.
    * @param onServerRequest - answers a server→client request; rejects to send an error response.
+   * @param writer - message writer; tests inject callback failures without relying on OS pipe races.
    */
   constructor(
     private readonly spec: ConnectionSpec,
     private readonly onServerRequest: (method: string, params: unknown) => Promise<unknown>,
+    private readonly writer: ConnectionWriter = writeConnectionMessage,
   ) {
     this.decoder = new MessageDecoder(spec.maxMessageBytes)
-    // `detached` puts the server in its own process group so teardown can signal the WHOLE group
-    // (via `process.kill(-pid)`), reaching helper processes a language server spawns (e.g. tsserver).
+    // `detached` gives teardown a process-tree root: POSIX signals its negative process-group id,
+    // while Windows passes the root pid to taskkill /T so helpers such as tsserver cannot outlive it.
     this.child = spawn(spec.command, [...spec.args], {
       cwd: spec.cwd,
       env: spec.env,
@@ -94,6 +195,11 @@ export class LspConnection {
     return this.stderr.toString('utf8')
   }
 
+  /** Whether the transport has failed even if the child close event has not arrived yet. */
+  get failed(): boolean {
+    return this.closeReason !== undefined
+  }
+
   /**
    * Send a request and await its result.
    * @param method - the JSON-RPC method.
@@ -147,23 +253,23 @@ export class LspConnection {
     return this.nextId
   }
 
-  /** Send SIGTERM to the server's process group (idempotent-safe; a dead group ignores it). */
+  /** Request termination of the server's process tree. */
   terminate(): void {
-    this.signalGroup('SIGTERM')
+    this.signalTree('SIGTERM')
   }
 
-  /** Send SIGKILL to the server's process group. */
+  /** Force termination of the server's process tree. */
   kill(): void {
-    this.signalGroup('SIGKILL')
+    this.signalTree('SIGKILL')
   }
 
   /**
-   * Wait until the owned process group has no members.
+   * Wait until the owned process tree has exited.
    * @param signal - optional bound for the wait.
-   * @returns `true` when the group exited, or `false` when the signal aborted first.
+   * @returns `true` when the tree exited, or `false` when the signal aborted first.
    */
-  async waitForProcessGroupExit(signal?: AbortSignal): Promise<boolean> {
-    while (this.processGroupAlive()) {
+  async waitForProcessTreeExit(signal?: AbortSignal): Promise<boolean> {
+    while (this.processTreeAlive()) {
       if (signal?.aborted) return false
       await yieldToEventLoop()
     }
@@ -171,26 +277,21 @@ export class LspConnection {
   }
 
   /**
-   * Signal the whole process group (negative pid) so helper processes are reached; fall back to the
-   * direct child if the group send fails. Never throws — teardown races process exit.
+   * Signal the whole process tree so helper processes are reached; fall back to the direct child if
+   * tree signaling fails. Never throws because teardown races process exit.
    */
-  private signalGroup(sig: NodeJS.Signals): void {
+  private signalTree(sig: NodeJS.Signals): void {
     const pid = this.child.pid
     if (pid === undefined) return
-    try {
-      process.kill(-pid, sig)
-    } catch {
-      // The group is gone (already exited) or could not be signalled; try the direct child.
-      try {
-        this.child.kill(sig)
-      } catch {
-        // Already dead; nothing to signal.
-      }
-    }
+    signalProcessTree(process.platform, pid, sig, {
+      signal: signalProcessGroup,
+      killChild: this.child.kill.bind(this.child),
+      taskkill: taskkillProcessTree,
+    })
   }
 
-  /** Whether the detached process group still has at least one member. */
-  private processGroupAlive(): boolean {
+  /** Whether the detached tree's root or POSIX process group is still alive. */
+  private processTreeAlive(): boolean {
     const pid = this.child.pid
     /* v8 ignore next -- only an asynchronous spawn failure omits pid; its close path owns cleanup. */
     if (pid === undefined) return false
@@ -218,7 +319,7 @@ export class LspConnection {
       // A framing/JSON failure corrupts the stream position irrecoverably: fail the instance and
       // SIGKILL the whole group so helper processes don't outlive the leader.
       this.fail(asError(error))
-      this.signalGroup('SIGKILL')
+      this.signalTree('SIGKILL')
       return
     }
     for (const message of messages) this.dispatch(message)
@@ -293,7 +394,7 @@ export class LspConnection {
         reject(error)
       }
       try {
-        this.child.stdin.write(encodeMessage(message), done)
+        this.writer(this.child.stdin, message, done)
       /* v8 ignore start -- Node stream write failures are callback-delivered; this guards a
          nonconforming Writable implementation throwing synchronously. */
       } catch (error) {
diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts
index 095d761624..340d5a4df0 100644
--- a/packages/lsp/lsp-local/src/index.ts
+++ b/packages/lsp/lsp-local/src/index.ts
@@ -2,9 +2,9 @@
  * Generic stdio language-server backend for `ctx.lsp`. One plugin instance configures a named table
  * of server commands and registers one isolated provider for each entry. Every provider lazily
  * single-flights one server process per canonical workspace realpath, serves transient-open queries
- * through it, and evicts a crashed process so a later query can replace it. Providers read sources
- * through Node APIs in the host namespace (not `ctx.fs`) and trust their configured servers — no
- * sandbox confinement.
+ * through it, and replaces a transport that dies between a pool liveness check and the next
+ * read-only query. Providers read sources through Node APIs in the host namespace (not `ctx.fs`)
+ * and trust their configured servers — no sandbox confinement.
  *
  * Namespace plugin (named exports, no default export). Lifecycle is effect-scoped: disposal
  * unregisters from `ctx.lsp` and tears down every live server.
@@ -227,6 +227,14 @@ class LocalLspProvider implements LspProvider {
       }
       try {
         return await instance.query(request, source, signal)
+      } catch (error) {
+        // A child can die after the pre-query liveness check but before or during the next write.
+        // Queries are read-only, so replace a newly failed transport once and retry transparently.
+        if (!instance.dead) throw error
+        this.evictIfCurrent(workspace, instance)
+        this.assertActive(signal)
+        instance = this.instanceFor(workspace)
+        return await instance.query(request, source, signal)
       } finally {
         // Drop a crashed slot only when it still owns this instance; a replacement must survive.
         if (instance.dead) this.evictIfCurrent(workspace, instance)
diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts
index 74381c1483..02bdd160d4 100644
--- a/packages/lsp/lsp-local/src/instance.ts
+++ b/packages/lsp/lsp-local/src/instance.ts
@@ -17,7 +17,7 @@ import type {
 import { deadline } from '@deepseek-ai/dsh-timeout'
 import { abortable, abortError } from './abort.ts'
 import { LspConnection } from './connection.ts'
-import type { ConnectionSpec } from './connection.ts'
+import type { ConnectionSpec, ConnectionWriter } from './connection.ts'
 import type { HostSource } from './host.ts'
 import type { WireInitializeResult, WireServerCapabilities } from './protocol.ts'
 import {
@@ -58,9 +58,10 @@ export class LspInstance {
 
   /**
    * @param spec - the launch, initialize, and teardown parameters.
+   * @param writer - optional connection writer used by transport conformance tests.
    */
-  constructor(private readonly spec: InstanceSpec) {
-    this.connection = new LspConnection(spec, (method, params) => this.answerServerRequest(method, params))
+  constructor(private readonly spec: InstanceSpec, writer?: ConnectionWriter) {
+    this.connection = new LspConnection(spec, (method, params) => this.answerServerRequest(method, params), writer)
     this.ready = this.initialize()
     // A handshake rejection must not surface as an unhandled rejection before the first query awaits
     // it; queries attach the real handler.
@@ -70,7 +71,7 @@ export class LspInstance {
 
   /** Synchronous liveness check: true once the process has closed or the instance was disposed. */
   get dead(): boolean {
-    return this.processClosed || this.disposed
+    return this.processClosed || this.disposed || this.connection.failed
   }
 
   /**
@@ -272,7 +273,7 @@ export class LspInstance {
     try {
       await this.gracefulShutdown(shutdownDeadline.signal)
     } catch {
-      // Graceful shutdown failed or timed out; process-group cleanup below remains authoritative.
+      // Graceful shutdown failed or timed out; process-tree cleanup below remains authoritative.
     } finally {
       shutdownDeadline[Symbol.dispose]()
     }
@@ -286,20 +287,20 @@ export class LspInstance {
     await abortable(this.connection.closed, signal)
   }
 
-  /** SIGTERM the group, escalate after `killGraceMs`, then await leader and helper exit. */
+  /** Terminate the tree, escalate after `killGraceMs`, then await leader and helper exit. */
   private async forceTerminate(): Promise<void> {
     this.connection.terminate()
     const graceDeadline = deadline(undefined, this.spec.killGraceMs, 'LSP_KILL_GRACE')
-    let groupExited: boolean
+    let treeExited: boolean
     try {
-      groupExited = await this.connection.waitForProcessGroupExit(graceDeadline.signal)
+      treeExited = await this.connection.waitForProcessTreeExit(graceDeadline.signal)
     } finally {
       graceDeadline[Symbol.dispose]()
     }
-    if (!groupExited) this.connection.kill()
+    if (!treeExited) this.connection.kill()
     await Promise.all([
       this.connection.closed,
-      this.connection.waitForProcessGroupExit(),
+      this.connection.waitForProcessTreeExit(),
     ])
   }
 }
diff --git a/packages/lsp/lsp-local/tests/connection.spec.ts b/packages/lsp/lsp-local/tests/connection.spec.ts
index 464848bbf5..18cb7a1bce 100644
--- a/packages/lsp/lsp-local/tests/connection.spec.ts
+++ b/packages/lsp/lsp-local/tests/connection.spec.ts
@@ -1,6 +1,17 @@
-import { afterEach, describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { fileURLToPath } from 'node:url'
 import { LspConnection } from '@deepseek-ai/dsh-lsp-local'
+import {
+  signalProcessGroup,
+  signalProcessTree,
+  taskkillProcessTree,
+} from '@deepseek-ai/dsh-lsp-local/src/connection.ts'
+import type {
+  ConnectionWriter,
+  ProcessSignalRunner,
+  ProcessTreeOperations,
+  TaskkillRunner,
+} from '@deepseek-ai/dsh-lsp-local/src/connection.ts'
 
 const fixtureServer = fileURLToPath(new URL('./fixture-server.ts', import.meta.url))
 
@@ -125,7 +136,7 @@ describe('LspConnection', () => {
 })
 
 /** Spawn a raw connection running an inline node script as the "server". */
-function connectScript(script: string, maxStderrBytes = 100_000): LspConnection {
+function connectScript(script: string, maxStderrBytes = 100_000, writer?: ConnectionWriter): LspConnection {
   const conn = new LspConnection({
     command: process.execPath,
     args: ['-e', script],
@@ -134,7 +145,7 @@ function connectScript(script: string, maxStderrBytes = 100_000): LspConnection
     maxMessageBytes: 16_000_000,
     maxStderrBytes,
     configuration: null,
-  }, () => Promise.resolve(null))
+  }, () => Promise.resolve(null), writer)
   open.push(conn)
   return conn
 }
@@ -209,13 +220,13 @@ describe('LspConnection edge behavior', () => {
     await expect(conn.request('initialize', {})).rejects.toThrow(/exited|closed/)
   })
 
-  it.skipIf(process.platform === 'win32')('rejects a pending request when child stdin closes but the process stays alive', async () => {
-    const conn = connectScript('const stdin=process.stdin; require("node:fs").closeSync(0); stdin._handle?.close(); setInterval(()=>{}, 1000)')
-    await new Promise<void>(resolve => setTimeout(resolve, 100))
-    const timeout = new Promise<never>((_resolve, reject) => {
-      setTimeout(() => { reject(new Error('request timed out')) }, 1000)
-    })
-    await expect(Promise.race([conn.request('initialize', {}), timeout])).rejects.not.toThrow(/timed out/)
+  it('rejects a pending request when child stdin fails but the process stays alive', async () => {
+    const failure = new Error('fixture stdin failure')
+    const writer: ConnectionWriter = (_stdin, _message, done) => {
+      queueMicrotask(() => { done(failure) })
+    }
+    const conn = connectScript('setInterval(()=>{}, 1000)', 100_000, writer)
+    await expect(conn.request('initialize', {})).rejects.toThrow(/fixture stdin failure/)
   })
 
   it('ignores a frame that is neither a valid request nor a numeric-id response', async () => {
@@ -230,6 +241,55 @@ describe('LspConnection edge behavior', () => {
   })
 })
 
+describe('process-tree signaling', () => {
+  it('forwards POSIX process-group signals through the host runner', () => {
+    const run: ProcessSignalRunner = vi.fn(() => true)
+    signalProcessGroup(-42, 'SIGKILL', run)
+    expect(run).toHaveBeenCalledWith(-42, 'SIGKILL')
+  })
+
+  it('uses taskkill for a Windows tree and a negative pid for a POSIX group', () => {
+    const operations = fakeProcessTreeOperations()
+    signalProcessTree('win32', 42, 'SIGTERM', operations)
+    expect(operations.taskkill).toHaveBeenCalledWith(42)
+    expect(operations.signal).not.toHaveBeenCalled()
+
+    signalProcessTree('linux', 42, 'SIGKILL', operations)
+    expect(operations.signal).toHaveBeenCalledWith(-42, 'SIGKILL')
+  })
+
+  it('falls back to the direct child and tolerates an already-dead child', () => {
+    const fallback = fakeProcessTreeOperations()
+    vi.mocked(fallback.taskkill).mockImplementation(() => { throw new Error('taskkill unavailable') })
+    signalProcessTree('win32', 42, 'SIGTERM', fallback)
+    expect(fallback.killChild).toHaveBeenCalledWith('SIGTERM')
+
+    const gone = fakeProcessTreeOperations()
+    vi.mocked(gone.signal).mockImplementation(() => { throw new Error('group gone') })
+    vi.mocked(gone.killChild).mockImplementation(() => { throw new Error('child gone') })
+    expect(() => { signalProcessTree('linux', 42, 'SIGKILL', gone) }).not.toThrow()
+  })
+
+  it('runs taskkill for the full tree and rejects command failures', () => {
+    const success: TaskkillRunner = vi.fn(() => ({ status: 0 }))
+    taskkillProcessTree(42, success)
+    expect(success).toHaveBeenCalledWith('taskkill', ['/PID', '42', '/T', '/F'], { stdio: 'ignore' })
+
+    const spawnFailure = new Error('cannot spawn taskkill')
+    expect(() => { taskkillProcessTree(42, () => ({ status: null, error: spawnFailure })) }).toThrow(spawnFailure)
+    expect(() => { taskkillProcessTree(42, () => ({ status: 1 })) }).toThrow(/status 1/)
+  })
+})
+
+/** Create observable process-tree operations without touching host processes. */
+function fakeProcessTreeOperations(): ProcessTreeOperations {
+  return {
+    signal: vi.fn(),
+    killChild: vi.fn(),
+    taskkill: vi.fn(),
+  }
+}
+
 /** Poll a predicate until it holds or a deadline elapses. */
 async function waitFor(predicate: () => boolean, timeoutMs = 3000): Promise<void> {
   const start = Date.now()
diff --git a/packages/lsp/lsp-local/tests/fixture-server.ts b/packages/lsp/lsp-local/tests/fixture-server.ts
index 2b7fb76b2f..1a30ed5628 100644
--- a/packages/lsp/lsp-local/tests/fixture-server.ts
+++ b/packages/lsp/lsp-local/tests/fixture-server.ts
@@ -16,8 +16,6 @@
  * - LSP_FAKE_OPEN_MARKER: appends each didOpen document text as one JSON line to this path.
  * - LSP_FAKE_INITIALIZED_MARKER: records when the initialized notification is received.
  * - LSP_FAKE_PAUSE_STDIN_AFTER_INITIALIZED: "1" stops consuming stdin after initialized.
- * - LSP_FAKE_CLOSE_STDIN_AFTER_INITIALIZED: "1" closes the stdin pipe after initialization.
- * - LSP_FAKE_CLOSE_STDIN_AFTER_REPLY: "1" closes the stdin pipe before the first query response.
  * - LSP_FAKE_EXIT_DELAY_MS / LSP_FAKE_EXIT_MARKER: delay protocol exit and record exit/termination.
  * - LSP_FAKE_NO_SHUTDOWN: "1" ignores the shutdown request (forces kill escalation).
  * - LSP_FAKE_ON_OPEN: server→client request to emit when a didOpen arrives, one of
@@ -28,7 +26,7 @@
  * Run: node fixture-server.ts (Node's erasable TypeScript syntax support).
  */
 
-import { appendFileSync, closeSync } from 'node:fs'
+import { appendFileSync } from 'node:fs'
 
 const enc = process.env.LSP_FAKE_ENCODING ?? 'utf-16'
 const sync: unknown = process.env.LSP_FAKE_SYNC !== undefined ? JSON.parse(process.env.LSP_FAKE_SYNC) : 1
@@ -40,8 +38,6 @@ const replyDelayMs = Number(process.env.LSP_FAKE_REPLY_DELAY_MS ?? 0)
 const openMarker = process.env.LSP_FAKE_OPEN_MARKER
 const initializedMarker = process.env.LSP_FAKE_INITIALIZED_MARKER
 const pauseStdinAfterInitialized = process.env.LSP_FAKE_PAUSE_STDIN_AFTER_INITIALIZED === '1'
-const closeStdinAfterInitialized = process.env.LSP_FAKE_CLOSE_STDIN_AFTER_INITIALIZED === '1'
-const closeStdinAfterReply = process.env.LSP_FAKE_CLOSE_STDIN_AFTER_REPLY === '1'
 const exitDelayMs = Number(process.env.LSP_FAKE_EXIT_DELAY_MS ?? 0)
 const exitMarker = process.env.LSP_FAKE_EXIT_MARKER
 const noShutdown = process.env.LSP_FAKE_NO_SHUTDOWN === '1'
@@ -146,14 +142,12 @@ function handle(message: { id?: number; method?: string; params?: unknown; resul
   if (method === 'initialized') {
     if (initializedMarker !== undefined) appendFileSync(initializedMarker, 'INITIALIZED\n')
     if (pauseStdinAfterInitialized) process.stdin.pause()
-    if (closeStdinAfterInitialized) closeStdinPipe()
     return
   }
   if (method === 'textDocument/didClose') return
   if (method?.startsWith('textDocument/')) {
     if (hang) return
     const reply = (): void => {
-      if (closeStdinAfterReply) closeStdinPipe()
       if (errorReply) {
         send({ id, error: { code: -32000, message: 'server refused the request' } })
       } else {
@@ -171,13 +165,6 @@ function handle(message: { id?: number; method?: string; params?: unknown; resul
   if (id !== undefined) send({ id, result: null })
 }
 
-/** Close both the CRT descriptor and libuv handle that can own a platform's child-stdin pipe. */
-function closeStdinPipe(): void {
-  const stdin = process.stdin as NodeJS.ReadStream & { _handle?: { close(): void } }
-  closeSync(0)
-  stdin._handle?.close()
-}
-
 /** Append one teardown event when the fixture is configured to expose process ordering. */
 function markExit(event: string): void {
   if (exitMarker !== undefined) appendFileSync(exitMarker, `${event}\n`)
@@ -209,6 +196,6 @@ function send(message: Record<string, unknown>): void {
 
 // Keep the event loop alive.
 process.stdin.resume()
-if (pauseStdinAfterInitialized || closeStdinAfterInitialized || closeStdinAfterReply) {
+if (pauseStdinAfterInitialized) {
   setInterval(() => {}, 1000)
 }
diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts
index 343233c4f5..cfa8120dbc 100644
--- a/packages/lsp/lsp-local/tests/instance.spec.ts
+++ b/packages/lsp/lsp-local/tests/instance.spec.ts
@@ -4,6 +4,8 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { pathToFileURL, fileURLToPath } from 'node:url'
 import { LspInstance, readHostSource } from '@deepseek-ai/dsh-lsp-local'
+import { encodeMessage } from '@deepseek-ai/dsh-lsp-local'
+import type { ConnectionWriter } from '@deepseek-ai/dsh-lsp-local/src/connection.ts'
 import type { InstanceSpec } from '@deepseek-ai/dsh-lsp-local/src/instance.ts'
 import type { LspProviderQuery, LspQueryResult } from '@deepseek-ai/dsh-lsp'
 
@@ -26,7 +28,11 @@ afterEach(async () => {
   await rm(root, { recursive: true, force: true })
 })
 
-function makeInstance(env: Record<string, string> = {}, overrides: Partial<InstanceSpec> = {}): LspInstance {
+function makeInstance(
+  env: Record<string, string> = {},
+  overrides: Partial<InstanceSpec> = {},
+  writer?: ConnectionWriter,
+): LspInstance {
   const instance = new LspInstance({
     command: process.execPath,
     args: [fixtureServer],
@@ -39,7 +45,7 @@ function makeInstance(env: Record<string, string> = {}, overrides: Partial<Insta
     shutdownTimeoutMs: 200,
     killGraceMs: 200,
     ...overrides,
-  })
+  }, writer)
   live.push(instance)
   return instance
 }
@@ -200,14 +206,11 @@ describe('LspInstance query and abort', () => {
     expect(instance.dead).toBe(true)
   })
 
-  it.skipIf(process.platform === 'win32')('terminates when stdin fails during the didOpen write', async () => {
-    // Closing stdin after initialized makes a large didOpen fail before `opened` can arm didClose;
-    // the instance must still become dead so its provider can replace it.
-    await writeFile(join(ws, 'a.ts'), 'x'.repeat(2_000_000))
-    const instance = makeInstance({ LSP_FAKE_CLOSE_STDIN_AFTER_INITIALIZED: '1' }, {
+  it('terminates when stdin fails during the didOpen write', async () => {
+    const instance = makeInstance({}, {
       shutdownTimeoutMs: 100,
       killGraceMs: 100,
-    })
+    }, failingWriter('textDocument/didOpen'))
     await expect(run(instance, 'goToDefinition')).rejects.toThrow()
     expect(instance.dead).toBe(true)
   })
@@ -225,11 +228,10 @@ describe('LspInstance query and abort', () => {
     await expect(run(instance, 'goToDefinition', controller.signal)).rejects.toThrow(/server refused/)
   })
 
-  it.skipIf(process.platform === 'win32')('keeps a settled result but awaits teardown when didClose cannot be written', async () => {
+  it('keeps a settled result but awaits teardown when didClose cannot be written', async () => {
     const instance = makeInstance({
       LSP_FAKE_DEF: 'null',
-      LSP_FAKE_CLOSE_STDIN_AFTER_REPLY: '1',
-    }, { shutdownTimeoutMs: 100, killGraceMs: 100 })
+    }, { shutdownTimeoutMs: 100, killGraceMs: 100 }, failingWriter('textDocument/didClose'))
     await expect(run(instance, 'goToDefinition')).resolves.toEqual({
       kind: 'locations',
       locations: [],
@@ -281,7 +283,7 @@ describe('LspInstance disposal', () => {
     await expect(instance.dispose()).resolves.toBeUndefined()
   })
 
-  it.skipIf(process.platform === 'win32')('awaits a surviving process-group helper on every concurrent dispose', async () => {
+  it('awaits a surviving process-tree helper on every concurrent dispose', async () => {
     const marker = join(root, 'helper.pid')
     const helper = 'process.on("SIGTERM",()=>{});setInterval(()=>{},1000);'
     const script = 'const{spawn}=require("node:child_process");const{writeFileSync}=require("node:fs");'
@@ -298,6 +300,7 @@ describe('LspInstance disposal', () => {
       await first
     } finally {
       if (processAlive(helperPid)) process.kill(helperPid, 'SIGKILL')
+      await waitForProcessExit(helperPid)
     }
   })
 
@@ -322,6 +325,26 @@ function processAlive(pid: number): boolean {
   }
 }
 
+/** Wait until a process id disappears so temporary-workspace cleanup cannot race handle release. */
+async function waitForProcessExit(pid: number, timeoutMs = 3_000): Promise<void> {
+  const started = Date.now()
+  while (processAlive(pid)) {
+    if (Date.now() - started > timeoutMs) throw new Error(`process ${pid} did not exit`)
+    await new Promise<void>(resolve => setTimeout(resolve, 10))
+  }
+}
+
+/** Write normally except for one method whose callback receives a deterministic transport error. */
+function failingWriter(method: string): ConnectionWriter {
+  return (stdin, message, done) => {
+    if ((message as { method?: unknown }).method === method) {
+      queueMicrotask(() => { done(new Error(`fixture ${method} failure`)) })
+      return
+    }
+    stdin.write(encodeMessage(message), done)
+  }
+}
+
 /** Wait until a fixture marker exists, bounded so a broken handshake cannot hang the test. */
 async function waitForFile(path: string, timeoutMs = 3000): Promise<void> {
   const started = Date.now()
diff --git a/packages/lsp/lsp-local/tests/lifecycle.spec.ts b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
index 7ba76d03de..826905ed26 100644
--- a/packages/lsp/lsp-local/tests/lifecycle.spec.ts
+++ b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
@@ -237,7 +237,7 @@ describe('lsp-local end to end over a fake server', () => {
     await ctx.fiber.dispose()
   })
 
-  it.skipIf(process.platform === 'win32')('evicts a pooled server that died while idle and serves the next query from a fresh one', async () => {
+  it('evicts a pooled server that died while idle and serves the next query from a fresh one', async () => {
     // The first query succeeds, then the server exits before the second arrives, leaving a dead
     // instance in the pool. The next query must evict-and-replace it and still succeed, rather than
     // failing once on the closed connection first.
diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts
index fc4f92dfad..2b48e9de1f 100644
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -198,7 +198,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
     await dispose(result)
   })
 
-  it.skipIf(process.platform === 'win32')('renders its header, footer, replay, streaming answer, todos, and status', async () => {
+  it('renders its header, footer, replay, streaming answer, todos, and status', async () => {
     let now = 0
     const result = await setup({
       contextWindow: 100,
@@ -320,7 +320,9 @@ describe('pi-tui chat lifecycle and transcript', () => {
       { inputTokens: 500, outputTokens: 8 },
       { turn: 3, step: 1 },
     )
-    await tick()
+    await vi.waitFor(() => {
+      expect(result.terminal.output).toContain('final live answer')
+    })
 
     expect(result.terminal.output).toContain('◒ Working · 8s')
     expect(result.terminal.output).toContain('esc interrupt')
@@ -328,7 +330,6 @@ describe('pi-tui chat lifecycle and transcript', () => {
     expect(result.terminal.output).toContain('user context')
     expect(result.terminal.output).toContain('Prompt blocked')
     expect(result.terminal.output).toContain('Turn cancelled')
-    expect(result.terminal.output).toContain('final live answer')
     expect(result.terminal.progress).toContain(true)
 
     result.session.append('assistant/chunk', {
diff --git a/vitest.config.ts b/vitest.config.ts
index 8baa7c7b32..c5b5c06d11 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -11,17 +11,6 @@ const windowsUnsupportedPackages = process.platform === 'win32'
     ]
   : []
 
-// These files retain 100% per-file coverage on POSIX, where their process-pipe and terminal timing
-// tests are deterministic; Windows skips those cases and must not fail solely on their uncovered paths.
-const windowsCoverageExclusions = process.platform === 'win32'
-  ? [
-      'packages/lsp/lsp-local/src/connection.ts',
-      'packages/lsp/lsp-local/src/index.ts',
-      'packages/lsp/lsp-local/src/instance.ts',
-      'packages/ui/tui/src/index.ts',
-    ]
-  : []
-
 export default defineConfig({
   // Native path resolution reads each package's nearest tsconfig, but only the root defines
   // workspace paths. Keep this plugin pinned to the root map so unbuilt bare package imports resolve
@@ -44,7 +33,6 @@ export default defineConfig({
         'packages/*/*/src/bin.ts',
         'packages/*/*/src/worker.ts',
         ...windowsUnsupportedPackages.map(path => `${path}/src/**/*.ts`),
-        ...windowsCoverageExclusions,
       ],
       // 100% or it doesn't merge (docs/testing.md: excessive tests are welcome).
       // Per-file so a well-covered big file can't subsidize a bare one.

From 7b6b544243b1109d23a21e7e10d9db1cd62d2389 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 22 Jul 2026 14:34:26 +0800
Subject: [PATCH 71/74] test(windows): cover teardown decisions
 deterministically

---
 packages/lsp/lsp-local/src/connection.ts      | 25 +++++++++++++++----
 packages/lsp/lsp-local/src/index.ts           |  4 ---
 packages/lsp/lsp-local/src/instance.ts        | 11 +++++++-
 .../lsp/lsp-local/tests/connection.spec.ts    | 14 +++++++++++
 packages/lsp/lsp-local/tests/instance.spec.ts | 11 +++++++-
 5 files changed, 54 insertions(+), 11 deletions(-)

diff --git a/packages/lsp/lsp-local/src/connection.ts b/packages/lsp/lsp-local/src/connection.ts
index 201cd87bdd..7ed3e09054 100644
--- a/packages/lsp/lsp-local/src/connection.ts
+++ b/packages/lsp/lsp-local/src/connection.ts
@@ -110,6 +110,25 @@ export function signalProcessGroup(
   run(target, signal)
 }
 
+/**
+ * Wait until a process-tree liveness probe reports exit.
+ * @param isAlive - process-tree liveness probe.
+ * @param signal - optional bound for the wait.
+ * @param yieldNow - event-loop yield primitive.
+ * @returns `true` when the tree exited, or `false` when the signal aborted first.
+ */
+export async function waitForTreeExit(
+  isAlive: () => boolean,
+  signal?: AbortSignal,
+  yieldNow: () => Promise<unknown> = yieldToEventLoop,
+): Promise<boolean> {
+  while (isAlive()) {
+    if (signal?.aborted) return false
+    await yieldNow()
+  }
+  return true
+}
+
 /**
  * Signal a detached process tree with platform-correct semantics and a direct-child fallback.
  * @param platform - host platform.
@@ -269,11 +288,7 @@ export class LspConnection {
    * @returns `true` when the tree exited, or `false` when the signal aborted first.
    */
   async waitForProcessTreeExit(signal?: AbortSignal): Promise<boolean> {
-    while (this.processTreeAlive()) {
-      if (signal?.aborted) return false
-      await yieldToEventLoop()
-    }
-    return true
+    return await waitForTreeExit(this.processTreeAlive.bind(this), signal)
   }
 
   /**
diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts
index 340d5a4df0..7a4b1b6b6d 100644
--- a/packages/lsp/lsp-local/src/index.ts
+++ b/packages/lsp/lsp-local/src/index.ts
@@ -221,10 +221,6 @@ class LocalLspProvider implements LspProvider {
       // synchronous get-or-create so every spawned process remains owned by teardown.
       this.assertActive(signal)
       let instance = this.instanceFor(workspace)
-      if (instance.dead) {
-        this.evictIfCurrent(workspace, instance)
-        instance = this.instanceFor(workspace)
-      }
       try {
         return await instance.query(request, source, signal)
       } catch (error) {
diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts
index 02bdd160d4..eecc5d4e5e 100644
--- a/packages/lsp/lsp-local/src/instance.ts
+++ b/packages/lsp/lsp-local/src/instance.ts
@@ -39,6 +39,15 @@ export interface InstanceSpec extends ConnectionSpec {
   readonly killGraceMs: number
 }
 
+/**
+ * Force-kill a process tree only when graceful termination did not make it exit.
+ * @param treeExited - whether the tree exited within its grace period.
+ * @param forceKill - forceful process-tree termination primitive.
+ */
+export function escalateProcessTree(treeExited: boolean, forceKill: () => void): void {
+  if (!treeExited) forceKill()
+}
+
 /**
  * A single initialized server process. Not exported as a provider — the provider single-flights and
  * pools these. `query()` serializes; `dispose()` rejects queued work and tears the process down.
@@ -297,7 +306,7 @@ export class LspInstance {
     } finally {
       graceDeadline[Symbol.dispose]()
     }
-    if (!treeExited) this.connection.kill()
+    escalateProcessTree(treeExited, this.connection.kill.bind(this.connection))
     await Promise.all([
       this.connection.closed,
       this.connection.waitForProcessTreeExit(),
diff --git a/packages/lsp/lsp-local/tests/connection.spec.ts b/packages/lsp/lsp-local/tests/connection.spec.ts
index 18cb7a1bce..9fea82b43f 100644
--- a/packages/lsp/lsp-local/tests/connection.spec.ts
+++ b/packages/lsp/lsp-local/tests/connection.spec.ts
@@ -5,6 +5,7 @@ import {
   signalProcessGroup,
   signalProcessTree,
   taskkillProcessTree,
+  waitForTreeExit,
 } from '@deepseek-ai/dsh-lsp-local/src/connection.ts'
 import type {
   ConnectionWriter,
@@ -248,6 +249,19 @@ describe('process-tree signaling', () => {
     expect(run).toHaveBeenCalledWith(-42, 'SIGKILL')
   })
 
+  it('waits for tree exit and stops when its bound aborts', async () => {
+    const isAlive = vi.fn()
+      .mockReturnValueOnce(true)
+      .mockReturnValue(false)
+    const yieldNow = vi.fn(() => Promise.resolve())
+    await expect(waitForTreeExit(isAlive, undefined, yieldNow)).resolves.toBe(true)
+    expect(yieldNow).toHaveBeenCalledOnce()
+
+    const controller = new AbortController()
+    controller.abort()
+    await expect(waitForTreeExit(() => true, controller.signal, yieldNow)).resolves.toBe(false)
+  })
+
   it('uses taskkill for a Windows tree and a negative pid for a POSIX group', () => {
     const operations = fakeProcessTreeOperations()
     signalProcessTree('win32', 42, 'SIGTERM', operations)
diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts
index cfa8120dbc..d08a431192 100644
--- a/packages/lsp/lsp-local/tests/instance.spec.ts
+++ b/packages/lsp/lsp-local/tests/instance.spec.ts
@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { mkdtemp, mkdir, readFile, rm, writeFile, realpath } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
@@ -6,6 +6,7 @@ import { pathToFileURL, fileURLToPath } from 'node:url'
 import { LspInstance, readHostSource } from '@deepseek-ai/dsh-lsp-local'
 import { encodeMessage } from '@deepseek-ai/dsh-lsp-local'
 import type { ConnectionWriter } from '@deepseek-ai/dsh-lsp-local/src/connection.ts'
+import { escalateProcessTree } from '@deepseek-ai/dsh-lsp-local/src/instance.ts'
 import type { InstanceSpec } from '@deepseek-ai/dsh-lsp-local/src/instance.ts'
 import type { LspProviderQuery, LspQueryResult } from '@deepseek-ai/dsh-lsp'
 
@@ -242,6 +243,14 @@ describe('LspInstance query and abort', () => {
 })
 
 describe('LspInstance disposal', () => {
+  it('escalates only when the process tree survives its grace period', () => {
+    const forceKill = vi.fn()
+    escalateProcessTree(false, forceKill)
+    expect(forceKill).toHaveBeenCalledOnce()
+    escalateProcessTree(true, forceKill)
+    expect(forceKill).toHaveBeenCalledOnce()
+  })
+
   it('lets a server finish protocol exit before signal escalation', async () => {
     const marker = join(root, 'graceful-exit.log')
     const instance = makeInstance({

From 2a8e7c661d2a9937993e1a8d67fa47818d8e1990 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 22 Jul 2026 14:42:11 +0800
Subject: [PATCH 72/74] test(windows): use native PATH delimiter

---
 packages/lsp/lsp-local/tests/provider.spec.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/lsp/lsp-local/tests/provider.spec.ts b/packages/lsp/lsp-local/tests/provider.spec.ts
index 7a969781f3..829a84264b 100644
--- a/packages/lsp/lsp-local/tests/provider.spec.ts
+++ b/packages/lsp/lsp-local/tests/provider.spec.ts
@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import { chmod, mkdtemp, mkdir, rm, writeFile, realpath } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { delimiter, join } from 'node:path'
 import { Context } from 'cordis'
 import Lsp, { type LspQueryRequest } from '@deepseek-ai/dsh-lsp'
 import * as LspLocal from '@deepseek-ai/dsh-lsp-local'
@@ -57,7 +57,7 @@ describe('lsp-local provider resolution', () => {
     await expect(ctx.plugin(LspLocal, config('nope', {
       command: 'fake-lsp',
       args: [],
-      env: { PATH: `::${join(root, 'empty')}` },
+      env: { PATH: `${delimiter}${delimiter}${join(root, 'empty')}` },
       extensionToLanguage: { '.ts': 'typescript' },
     }))).rejects.toThrow(/was not found on PATH/)
     await ctx.fiber.dispose()

From 769710cfb990fa93376cfaa3e9042be38f028f9f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 22 Jul 2026 15:56:29 +0800
Subject: [PATCH 73/74] fix(lsp): make transport recovery ownership-safe

---
 ...-22-cross-platform-test-fixtures.i18n.yaml |  4 +--
 ...2026-07-22-cross-platform-test-fixtures.md |  4 +--
 ...6-07-22-cross-platform-test-fixtures.zh.md |  4 +--
 packages/lsp/lsp-local/README.md              |  4 +--
 packages/lsp/lsp-local/src/connection.ts      | 30 ++++++++++++++-----
 packages/lsp/lsp-local/src/index.ts           | 18 ++++++-----
 packages/lsp/lsp-local/src/instance.ts        | 16 +++++++++-
 .../lsp/lsp-local/tests/connection.spec.ts    | 28 +++++++++++------
 packages/lsp/lsp-local/tests/instance.spec.ts | 11 +++++++
 .../lsp/lsp-local/tests/lifecycle.spec.ts     | 10 +++++--
 10 files changed, 94 insertions(+), 35 deletions(-)

diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml
index 511b66e345..f5fc9ecef6 100644
--- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-22-cross-platform-test-fixtures.md: 56deaf6306e15c6cf17e83fcbaf36137e5c543f4
-2026-07-22-cross-platform-test-fixtures.zh.md: f61441e2dbe86fa5a580e666fcd08d23b0fadf0b
+2026-07-22-cross-platform-test-fixtures.md: 6217aabfdbe8f14f869004c8dafb7e19f4b7443a
+2026-07-22-cross-platform-test-fixtures.zh.md: 43942ec0468df822d04b39e318010c2b260c734f
diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md
index 56deaf6306..6217aabfdb 100644
--- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md
+++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md
@@ -16,7 +16,7 @@ Tests of platform-neutral behavior construct absolute paths and `file:` URIs wit
 
 Transport-failure tests inject the connection's message writer and deliver the same asynchronous write callback error that a real Node stream would report. The production writer still writes framed messages to child stdin. This keeps a real child alive while the test deterministically distinguishes transport failure from process exit without reaching into platform-specific pipe handles.
 
-Language-server teardown targets the whole descendant tree through a negative process-group id on POSIX and synchronous `taskkill /T /F` on Windows, with a direct-child fallback when the tree is already gone. A read-only provider query retries once only when its pooled transport becomes dead after the liveness check; errors from a still-live server are not replayed. Terminal tests wait for their observable rendered output instead of assuming one event-loop turn is sufficient.
+Language-server teardown targets the whole descendant tree through a negative process-group id on POSIX and synchronous `taskkill /T /F` on Windows. Windows suppresses only taskkill's already-absent-tree status; command, permission, and other tree-kill failures remain teardown failures. A read-only provider query retries once only when its selected pooled transport fails before or during that query; errors from a still-live server are not replayed. Terminal tests wait for their observable rendered output instead of assuming one event-loop turn is sufficient.
 
 Tests for a genuinely POSIX-only primitive use a narrow Windows exclusion on that case. Adjacent cross-platform cases continue to pin non-regular file rejection, unavailable command rejection, and inaccessible working-directory rejection. Supported Windows paths remain inside the per-file coverage gate rather than being excluded with their test files.
 
@@ -30,4 +30,4 @@ Tests for a genuinely POSIX-only primitive use a narrow Windows exclusion on tha
 
 ## Consequences
 
-Portable fixtures are slightly more explicit because expected paths derive from shared native constants and transport failures enter through a narrow writer seam. Platform-only exclusions require a neighboring cross-platform assertion for the product behavior they support. Windows teardown depends on the host `taskkill` command after graceful protocol shutdown has failed; a synchronous result keeps disposal bounded and makes descendant exit observable before cleanup returns.
+Portable fixtures are slightly more explicit because expected paths derive from shared native constants and transport failures enter through a narrow writer seam. Platform-only exclusions require a neighboring cross-platform assertion for the product behavior they support. Windows teardown depends on the host `taskkill` command after graceful protocol shutdown has failed; a successful synchronous result keeps disposal bounded and makes descendant exit observable before cleanup returns, while a failed tree kill remains visible to the disposer.
diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md
index f61441e2db..43942ec046 100644
--- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md
+++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 传输故障测试会注入连接的消息写入器，并传入与真实 Node 流相同的异步写入回调错误。生产写入器仍会把分帧消息写入子进程 stdin。这种方式让真实子进程保持存活，使测试无需触及平台特有的管道句柄，也能确定性地区分传输故障与进程退出。
 
-语言服务器的资源清理会终止整棵后代进程树：POSIX 使用负数进程组 ID，Windows 同步执行 `taskkill /T /F`；若进程树已经不存在，则回退到直接终止子进程。只读的提供方查询仅在池化传输于存活检查后失效时重试一次；服务器仍存活时返回的错误不会重放。终端测试会等待可观察的渲染输出，不假设一次事件循环轮转已经足够。
+语言服务器的资源清理会终止整棵后代进程树：POSIX 使用负数进程组 ID，Windows 同步执行 `taskkill /T /F`。Windows 只会忽略 taskkill 返回的「进程树已经不存在」状态；命令执行失败、权限错误及其他终止进程树的失败仍属于资源清理失败。只读的提供方查询仅在选定的池化传输于该次查询开始前或执行期间失效时重试一次；服务器仍存活时返回的错误不会重放。终端测试会等待可观察的渲染输出，不假设一次事件循环轮转已经足够。
 
 对于真正仅存在于 POSIX 的原语，测试只在该用例上排除 Windows。相邻的跨平台用例仍会固定拒绝非普通文件、不可用命令和无法访问的工作目录的行为。Windows 上受支持的路径仍受逐文件覆盖率门禁约束，不会随测试文件一起排除。
 
@@ -30,4 +30,4 @@ Status: implemented
 
 ## 后果
 
-可移植 fixture 需要更显式地构造，因为预期路径要从共享的原生常量派生，传输故障则通过狭窄的写入器 seam 注入。仅适用于特定平台的排除项必须配有相邻的跨平台断言，以继续覆盖相应的产品行为。协议级优雅关停失败后，Windows 上的资源清理依赖宿主的 `taskkill` 命令；同步取得命令结果让 dispose 的完成边界明确，并确保清理返回前即可观察到后代进程退出。
+可移植 fixture 需要更显式地构造，因为预期路径要从共享的原生常量派生，传输故障则通过狭窄的写入器 seam 注入。仅适用于特定平台的排除项必须配有相邻的跨平台断言，以继续覆盖相应的产品行为。协议级优雅关停失败后，Windows 上的资源清理依赖宿主的 `taskkill` 命令；命令同步执行成功时，dispose 的完成边界明确，并确保清理返回前即可观察到后代进程退出；若进程树终止失败，dispose 的调用方仍能观察到该失败。
diff --git a/packages/lsp/lsp-local/README.md b/packages/lsp/lsp-local/README.md
index 269fe6b666..7c6c05b7df 100644
--- a/packages/lsp/lsp-local/README.md
+++ b/packages/lsp/lsp-local/README.md
@@ -7,10 +7,10 @@ Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export).
 ## What it does
 
 - Resolves every server-local setting before registration; an invalid mapping or registration conflict rolls back earlier entries, so a failed load leaves no provider routes.
-- Lazily single-flights one server process per `(server id, canonical workspace realpath)`. A live server error is not replayed; if the transport becomes dead between the pool's liveness check and a read-only query, the provider evicts it and retries that query once on a fresh process.
+- Lazily single-flights one server process per `(server id, canonical workspace realpath)`. A live server error is not replayed; if the selected pooled transport fails before or during a read-only query, the provider awaits its disposal and retries that query once on a fresh process.
 - Uses a compatibility-first **transient-open** sequence per query: canonicalize and read the source with Node APIs, `textDocument/didOpen` (version 1, full text), the requested request, then `textDocument/didClose` in `finally`. A failed or canceled `didOpen` write terminates the instance before the pool can reuse it. Documents close after each call, so the first version needs no `didChange`, content cache, or document LRU.
 - Serializes each source-read/open/query/close lifecycle through one abortable per-workspace queue so queued calls read current source only when their turn starts; distinct workspaces run in parallel.
-- After protocol shutdown fails, terminates the server's descendant tree through POSIX process-group signaling or synchronous Windows `taskkill /T /F`, with a direct-child fallback for teardown races.
+- After protocol shutdown fails, terminates the server's descendant tree through POSIX process-group signaling or synchronous Windows `taskkill /T /F`. Windows suppresses only taskkill's already-absent-tree result; command, permission, and other tree-kill failures remain visible.
 - Reads sources through Node filesystem APIs in the subprocess's host namespace — NOT `ctx.fs`, and emits no `fs/observed`: only the LSP result is model-visible, so a query does not satisfy read-before-write policy.
 
 ## Configuration
diff --git a/packages/lsp/lsp-local/src/connection.ts b/packages/lsp/lsp-local/src/connection.ts
index 7ed3e09054..1103c4dbd2 100644
--- a/packages/lsp/lsp-local/src/connection.ts
+++ b/packages/lsp/lsp-local/src/connection.ts
@@ -52,7 +52,7 @@ export type ConnectionWriter = (
 export interface ProcessTreeOperations {
   /** Signal a POSIX process group. */
   readonly signal: (target: number, signal: NodeJS.Signals) => void
-  /** Signal the direct child when group/tree signalling is unavailable. */
+  /** Signal the direct child when POSIX group signaling is unavailable. */
   readonly killChild: (signal: NodeJS.Signals) => void
   /** Terminate a Windows process tree by root pid. */
   readonly taskkill: (pid: number) => void
@@ -78,6 +78,9 @@ export type ProcessSignalRunner = (target: number, signal: NodeJS.Signals) => bo
 
 const processSignalRunner: ProcessSignalRunner = process.kill.bind(process)
 
+/** taskkill status for "process not found": the requested process tree is already absent. */
+const TASKKILL_TREE_NOT_FOUND_STATUS = 128
+
 const writeConnectionMessage: ConnectionWriter = (stdin, message, done) => {
   stdin.write(encodeMessage(message), done)
 }
@@ -93,6 +96,7 @@ export function taskkillProcessTree(
 ): void {
   const result = run('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' })
   if (result.error !== undefined) throw result.error
+  if (result.status === TASKKILL_TREE_NOT_FOUND_STATUS) return
   if (result.status !== 0) throw new Error(`taskkill exited with status ${String(result.status)}`)
 }
 
@@ -130,7 +134,8 @@ export async function waitForTreeExit(
 }
 
 /**
- * Signal a detached process tree with platform-correct semantics and a direct-child fallback.
+ * Signal a detached process tree with platform-correct semantics. POSIX falls back to the direct
+ * child; Windows requires taskkill to reach the full tree.
  * @param platform - host platform.
  * @param pid - detached root process id.
  * @param signal - requested termination signal.
@@ -142,9 +147,12 @@ export function signalProcessTree(
   signal: NodeJS.Signals,
   operations: ProcessTreeOperations,
 ): void {
+  if (platform === 'win32') {
+    operations.taskkill(pid)
+    return
+  }
   try {
-    if (platform === 'win32') operations.taskkill(pid)
-    else operations.signal(-pid, signal)
+    operations.signal(-pid, signal)
   } catch {
     try {
       operations.killChild(signal)
@@ -219,6 +227,15 @@ export class LspConnection {
     return this.closeReason !== undefined
   }
 
+  /**
+   * Test whether a caught error is this connection's retained fatal transport cause.
+   * @param error - error caught by the instance or provider.
+   * @returns `true` only when this connection produced that exact failure.
+   */
+  failedWith(error: unknown): boolean {
+    return this.closeReason === error
+  }
+
   /**
    * Send a request and await its result.
    * @param method - the JSON-RPC method.
@@ -291,10 +308,7 @@ export class LspConnection {
     return await waitForTreeExit(this.processTreeAlive.bind(this), signal)
   }
 
-  /**
-   * Signal the whole process tree so helper processes are reached; fall back to the direct child if
-   * tree signaling fails. Never throws because teardown races process exit.
-   */
+  /** Signal the whole process tree. */
   private signalTree(sig: NodeJS.Signals): void {
     const pid = this.child.pid
     if (pid === undefined) return
diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts
index 7a4b1b6b6d..dda3558130 100644
--- a/packages/lsp/lsp-local/src/index.ts
+++ b/packages/lsp/lsp-local/src/index.ts
@@ -2,8 +2,8 @@
  * Generic stdio language-server backend for `ctx.lsp`. One plugin instance configures a named table
  * of server commands and registers one isolated provider for each entry. Every provider lazily
  * single-flights one server process per canonical workspace realpath, serves transient-open queries
- * through it, and replaces a transport that dies between a pool liveness check and the next
- * read-only query. Providers read sources through Node APIs in the host namespace (not `ctx.fs`)
+ * through it, and replaces a selected transport that fails before or during the next read-only
+ * query. Providers read sources through Node APIs in the host namespace (not `ctx.fs`)
  * and trust their configured servers — no sandbox confinement.
  *
  * Namespace plugin (named exports, no default export). Lifecycle is effect-scoped: disposal
@@ -224,16 +224,20 @@ class LocalLspProvider implements LspProvider {
       try {
         return await instance.query(request, source, signal)
       } catch (error) {
-        // A child can die after the pre-query liveness check but before or during the next write.
-        // Queries are read-only, so replace a newly failed transport once and retry transparently.
-        if (!instance.dead) throw error
+        // A selected child can have died while idle or fail during the next write. Queries are
+        // read-only, so replace that transport once and retry transparently.
+        if (!instance.isTransportFailure(error)) throw error
+        await instance.dispose()
         this.evictIfCurrent(workspace, instance)
         this.assertActive(signal)
         instance = this.instanceFor(workspace)
         return await instance.query(request, source, signal)
       } finally {
-        // Drop a crashed slot only when it still owns this instance; a replacement must survive.
-        if (instance.dead) this.evictIfCurrent(workspace, instance)
+        // Reach quiescence before dropping a dead slot; a replacement must survive this ownership check.
+        if (instance.dead) {
+          await instance.dispose()
+          this.evictIfCurrent(workspace, instance)
+        }
       }
     })
   }
diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts
index eecc5d4e5e..266dd3c59f 100644
--- a/packages/lsp/lsp-local/src/instance.ts
+++ b/packages/lsp/lsp-local/src/instance.ts
@@ -83,6 +83,15 @@ export class LspInstance {
     return this.processClosed || this.disposed || this.connection.failed
   }
 
+  /**
+   * Test whether a caught query error came from this instance's transport.
+   * @param error - error caught by the provider.
+   * @returns `true` only for the connection's retained fatal transport cause.
+   */
+  isTransportFailure(error: unknown): boolean {
+    return this.connection.failedWith(error)
+  }
+
   /**
    * Run one query through the serialized queue.
    * @param request - the resolved provider query.
@@ -94,7 +103,12 @@ export class LspInstance {
     // Serialize behind prior work, but observe abort DURING the queue wait too: if an earlier query
     // hangs (e.g. a signal-less seam caller), a later tool's timeout must still be able to give up
     // rather than block on the shared tail forever.
-    const run = abortable(this.queue, signal).then(() => this.runQuery(request, source, signal))
+    const run = abortable(this.queue, signal)
+      .then(() => this.runQuery(request, source, signal))
+      .catch(async (error: unknown) => {
+        if (this.isTransportFailure(error)) await this.startTeardown()
+        throw error
+      })
     // Keep the tail alive regardless of this query's outcome so the next caller still serializes. The
     // tail follows the ACTUAL prior work (this.queue), not the abortable view, so a caller giving up
     // on the wait does not deserialize the queue.
diff --git a/packages/lsp/lsp-local/tests/connection.spec.ts b/packages/lsp/lsp-local/tests/connection.spec.ts
index 9fea82b43f..aa7e819cb6 100644
--- a/packages/lsp/lsp-local/tests/connection.spec.ts
+++ b/packages/lsp/lsp-local/tests/connection.spec.ts
@@ -65,6 +65,12 @@ describe('LspConnection', () => {
     await expect(conn.request('textDocument/hover', {})).rejects.toThrow(/server refused the request/)
   })
 
+  it('treats signaling an already-closed child as a teardown race', async () => {
+    const conn = connectScript('')
+    await conn.closed
+    expect(() => { conn.kill() }).not.toThrow()
+  })
+
   it('answers a server workspace/configuration request from static config', async () => {
     const seen: SeenRequest[] = []
     const conn = connect(
@@ -272,23 +278,27 @@ describe('process-tree signaling', () => {
     expect(operations.signal).toHaveBeenCalledWith(-42, 'SIGKILL')
   })
 
-  it('falls back to the direct child and tolerates an already-dead child', () => {
+  it('surfaces a Windows taskkill failure without downgrading to the direct child', () => {
     const fallback = fakeProcessTreeOperations()
     vi.mocked(fallback.taskkill).mockImplementation(() => { throw new Error('taskkill unavailable') })
-    signalProcessTree('win32', 42, 'SIGTERM', fallback)
-    expect(fallback.killChild).toHaveBeenCalledWith('SIGTERM')
-
-    const gone = fakeProcessTreeOperations()
-    vi.mocked(gone.signal).mockImplementation(() => { throw new Error('group gone') })
-    vi.mocked(gone.killChild).mockImplementation(() => { throw new Error('child gone') })
-    expect(() => { signalProcessTree('linux', 42, 'SIGKILL', gone) }).not.toThrow()
+    expect(() => { signalProcessTree('win32', 42, 'SIGTERM', fallback) }).toThrow(/taskkill unavailable/)
+    expect(fallback.killChild).not.toHaveBeenCalled()
   })
 
-  it('runs taskkill for the full tree and rejects command failures', () => {
+  it('tolerates a POSIX tree-signaling race after the direct child is already gone', () => {
+    const posixGone = fakeProcessTreeOperations()
+    vi.mocked(posixGone.signal).mockImplementation(() => { throw new Error('group gone') })
+    vi.mocked(posixGone.killChild).mockImplementation(() => { throw new Error('child gone') })
+    expect(() => { signalProcessTree('linux', 42, 'SIGKILL', posixGone) }).not.toThrow()
+  })
+
+  it('runs taskkill for the full tree, accepts an absent tree, and rejects command failures', () => {
     const success: TaskkillRunner = vi.fn(() => ({ status: 0 }))
     taskkillProcessTree(42, success)
     expect(success).toHaveBeenCalledWith('taskkill', ['/PID', '42', '/T', '/F'], { stdio: 'ignore' })
 
+    expect(() => { taskkillProcessTree(42, () => ({ status: 128 })) }).not.toThrow()
+
     const spawnFailure = new Error('cannot spawn taskkill')
     expect(() => { taskkillProcessTree(42, () => ({ status: null, error: spawnFailure })) }).toThrow(spawnFailure)
     expect(() => { taskkillProcessTree(42, () => ({ status: 1 })) }).toThrow(/status 1/)
diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts
index d08a431192..9f246e602a 100644
--- a/packages/lsp/lsp-local/tests/instance.spec.ts
+++ b/packages/lsp/lsp-local/tests/instance.spec.ts
@@ -216,6 +216,17 @@ describe('LspInstance query and abort', () => {
     expect(instance.dead).toBe(true)
   })
 
+  it('awaits process exit before rejecting a request write failure', async () => {
+    const instance = makeInstance({}, {
+      shutdownTimeoutMs: 100,
+      killGraceMs: 100,
+    }, failingWriter('textDocument/definition'))
+    // The pid is observed only to prove the owned subprocess reached quiescence before rejection.
+    const pid = (instance as unknown as { connection: { pid: number } }).connection.pid
+    await expect(run(instance, 'goToDefinition')).rejects.toThrow(/fixture textDocument\/definition failure/)
+    expect(processAlive(pid)).toBe(false)
+  })
+
   it('rejects when the server lacks the operation capability', async () => {
     const instance = makeInstance({ LSP_FAKE_CAPS: JSON.stringify({ definitionProvider: false }), LSP_FAKE_DEF: 'null' })
     await expect(run(instance, 'goToDefinition')).rejects.toThrow(/does not support goToDefinition/)
diff --git a/packages/lsp/lsp-local/tests/lifecycle.spec.ts b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
index 826905ed26..47b8d78bb4 100644
--- a/packages/lsp/lsp-local/tests/lifecycle.spec.ts
+++ b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
@@ -122,9 +122,15 @@ describe('lsp-local end to end over a fake server', () => {
     await ctx.fiber.dispose()
   })
 
-  it('rejects a non-utf-16 position encoding at initialize', async () => {
-    const ctx = await mount({ LSP_FAKE_ENCODING: 'utf-8', LSP_FAKE_DEF: 'null' })
+  it('rejects a non-utf-16 position encoding at initialize without retrying', async () => {
+    const marker = join(root, 'initialize-rejection-exit.log')
+    const ctx = await mount({
+      LSP_FAKE_ENCODING: 'utf-8',
+      LSP_FAKE_DEF: 'null',
+      LSP_FAKE_EXIT_MARKER: marker,
+    })
     await expect(ctx.lsp.query(query('goToDefinition'))).rejects.toThrow(/unsupported position encoding/)
+    expect(await readFile(marker, 'utf8')).toBe('EXIT\nCLEAN\n')
     await ctx.fiber.dispose()
   })
 

From a6a3807a07d39c1cd066679a5ccc0d37db65ccb6 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 19 Jul 2026 21:17:57 +0800
Subject: [PATCH 74/74] =?UTF-8?q?feat(gui):=20step1=20skeleton=20=E2=80=94?=
 =?UTF-8?q?=20dsc=20web=20serves=20built=20web=20UI=20over=20booted=20harn?=
 =?UTF-8?q?ess=20host?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Five new modules: apps/dsc (bin: parseArgs + node:http static server +
signal shutdown), packages/host/apiproxy (programmatic harness core
composition, agents:[]), packages/client/web-runtime (React-free browser
runtime), packages/client/web-ui (React mount), apps/web (vite build
entry producing dist consumed by apps/dsc via package exports).

Root wiring: apps/* workspace glob, dsh-* paths for host/client groups,
demo:web script, apps/web/dist gitignore. No protocol/API routes yet —
contract lands in step2 (see missions/tasks/20260719-1902-apiproxy-api-design).

Includes the design + implementation archives (spec v2.1, deepseekchat
baseline and harness boot research, implementation run log).

Acceptance: 12/12 passed incl. real-key llm.stream smoke (51 chunks).

feat(gui): apiproxy — four-quadrant RPC contract + fetch carriers, live end to end

Contract layer (src/api/, 14 files): four named wire message types
(ClientRequest / ServerResponse / ServerRequest / ClientResponse) as a
discriminated union over strict bidirectional rpcId (initiator mints,
responder echoes; channel and message fully decoupled — HTTP is the
client->server pipe, SSE the reverse); narrow RpcRequest<P>/
RpcResponse<T> signature forms; RpcMethodMap with RequestPayload<K>/
ResponseValue<K> derivation; typed RpcError details map; approval/
question responses modeled as ClientResponse via a single /api/respond
endpoint (RpcReceipt carrier ack); zod schemas anchored per Wire<T>
against exactOptionalPropertyTypes.

impl/api-proxy.ts: describe/list/create, both SSE streams (frame queue
pump, subscribed baseline, lifecycle frames, signal cleanup); history
pages on message boundaries (tail-back scan, partial included in the
tail page); prompt dispatches queue->agent.send / steer->agent.steer
with rpcId carried through MessageSource; cancel for attached sessions;
cold-session resume deduped via a per-id promise map; host-level
provider/model defaults injected at create/resume.

fetch/: mechanical UNARY_ROUTES table, two-level parse with
path==method check, SSE frames completed to ServerRequest full form;
client mints -> narrows -> envelopes outbound, verifies rpcId echo
inbound, streams SSE frames, four-quadrant onEnvelope tap (debug panel
choke point). Real-browser fixes: URL base resolves to location.origin
(hardcoded internal base broke real pages), browser-safe export paths.

Design archives: contract design.md v2.0 with decision log,
core-coverage audit, comparative studies, step2 impl run log. Probed
end to end over real HTTP: prompt -> live model stream -> history
returns the finished reply.

feat(gui): RpcLog debug panel — fixture-driven milestone, playwright-verified 10/10

web-runtime: rpcLog + ui slices (zustand), four-quadrant RpcLogEntry
(client-request / server-response / server-request / client-response),
onEnvelope tap -> microtask-batched pump with 500-entry ring buffer,
ConnectionController (private state, backoff reconnect), fixture API
with fake envelopes (?fixture switch), bootWebRuntime; contract types
via temporary local copies (api-types.ts, swapped for real imports when
W3 client lands).

web-ui: components/panels/RpcLog five-piece set (badge with unread
count, floating panel, direction glyphs per quadrant, same-rpcId
pair highlighting in two families, JSON payload expand, follow/pause,
clear), App shell, utils/formatRelative, light-theme CSS variables with
dark placeholders.

dsc bin: mime lookup fixed to use the actually-served file (naked
'/?query' no longer falls through to octet-stream download); shutdown
closes SSE keep-alive connections so SIGTERM actually exits.

Acceptance: scripts/verify-rpclog-panel.mjs (chromium headless) ALL
PASS 10/10 over design.md §D 1-6.

pkg: add web scripts for building

feat(gui): session milestone — list + conversation over Session OOP, styled RpcLog v2.1

web-runtime: Session/SessionManager object layer (resident instances,
mux frame routing, lineage flattening), foldSurface adapter with padding
sentinels for paged windows, chunk accumulator for streaming partials,
batched change notification (useSyncExternalStore contract), connection
sinks + reconnect fix (the 300ms self-abort reconnect storm that made
the session list flap is gone), fixture rewritten as a scripted host
(60-turn history, typewriter replay, resident pending approval, child
session); temporary contract copies deleted in favor of real apiproxy
imports.

web-ui: sessions screen (list with lineage indent + selection as
container-local state), conversation view (turn grouping, reasoning
fold, tool cards, steering, pending interaction cards, upward paging
with scroll anchoring), input bar with queue/steer/stop; RpcLog panel
restyled per docs/web-styling.md (tokenized palette, quadrant badge
glyphs now vertical ↑↓⇟⇞, pair highlighting, floating shadow).

docs/web-styling.md: living style guide (tokens, visual baseline,
coding rules, evolution log).

Acceptance: verify-session.mjs 31/31, verify-session-real.mjs 5/5
(real model streaming), verify-rpclog-panel.mjs 10/10.

feat(gui): hostruntime split + repo-wide package prefix rename

Package split (design: 20260720-0101-hostruntime-split-design):
dsh-host-runtime carries bootHost + createApiProxy + startHost()
(RunningHost {api, handler, defaults, ctx, dispose} — the seam Electron
and any future shell reuses; ctx is the official front-door mount
point); dsh-host-webserver carries the node:http static+API bridge
(fixed: abort now keys on res 'close' + writableEnded — req 'close'
fires on body end since Node 16 and was killing every SSE stream
instantly, the reconnect-storm root cause); apps/dsc is now a thin
assembly with web/-p subcommands. dsc -p runs the full isomorphic
carrier chain in process (second real protocol consumer; probed
end-to-end against the live model).

Naming rule (user decree): packages under host/ and client/ carry the
directory prefix in their npm name — dsh-host-apiproxy,
dsh-client-web-runtime, dsh-client-web-ui renamed repo-wide in one
frozen batch; explicit tsconfig paths entries added where the wildcard
no longer matches.

Acceptance: verify-session 31/31, verify-rpclog-panel 10/10,
verify-session-real 7/7 (incl. new 12s connection-stability sentinels),
tsc green, dsc web + dsc -p smoke both pass.

refactor(gui): AbstractApiClient class hierarchy — OO client with inheritable seams

AbstractApiClient (apiproxy) carries every protocol invariant: rpcId
minting, four-quadrant envelope wrap/unwrap, zod parsing, SSE frame
parsing, the payload-direct IApiClient surface (callers no longer mint
rpcIds — the carrier does), and the instance-level envelope observation
pump (batched via microtask; moved off module-level globals in
rpc-log.ts, which is now a pure subscriber mapping envelopes into store
entries — the debug panel observes the connection, it is not part of
it).

Platform subclasses own two abstract seams (doFetch, onEnvelope) plus
three protocol-level virtuals for transportless overrides:
InProcessApiClient (apiproxy; dsc -p uses new InProcessApiClient(
host.handler)), WebApiClient (web-runtime), FixtureApiClient (fixture
now subclasses instead of wrapping). Naming per decree: AbstractApiClient
/ IApiClient; ApiProxy stays the impl-side narrow-form contract.

headless.ts call sites drop rpcRequest wrappers (payload-direct);
split-design archive updated with the naming-rule ledger.

tsc green; verify-session 31/31, verify-rpclog-panel 10/10,
verify-session-real 7/7 (12s connection sentinel count=4); dsc -p smoke
CALLER-OK.

feat(gui): InputBar final form — bug batch, deepseekchat layout, single primary button, running locks input

Squashes the whole InputBar iteration batch: IME/caret/auto-grow/focus/dedup
bug fixes, layout aligned to the deepseekchat baseline, single primary button
with hover flyout, finalized button semantics with the Codex-style icon
circle, and running-state locking where stop is the only mid-turn action.
The same batch carried the Chinese-to-English code comment sweep
(density pruned), folded in here.

docs(gui): purge work-log references from code comments

76 design-doc references cleared across the GUI packages: section
pointers inlined as self-contained constraint statements, pure pointer
comments dropped, milestone codenames and ruling tags out, and the 14
contract file headers switched to the formal RFC (the only sanctioned
external reference). web-styling.md now cites the styling RFC instead
of the disposable research archive. grep for work-log reference
variants is clean across the GUI packages.

docs(gui): file-header comments self-contained — drop RFC filename references

RFC renames/reorgs must not require a source sweep (the 2026-07-20
two-way merge proved it). 11 headers lose only the '(RFC …)' tail and
stay self-contained; api-proxy.ts keeps its minimal-first note.

fix(gui): session streaming — freeze interrupted partials, sweep stale running calls, send force-scrolls

Aborted turns never emit the finalizing assistant/message, so the
accumulated partial and its running tool cards kept rendering below
later messages — the "new message lands above the stopped reply"
illusion. turn/end side effects now freeze content-bearing partials
into interrupted terminal nodes (fractional seq keeps flow order; the
live freeze and history replay converge through applyEventSideEffects,
so a refresh reconstructs identical frozen nodes) and turn running tool
cards into interrupted terminal cards; only content-free partials are
swept outright. ConversationView gains the send-force-scroll rule (own
words must be visible) alongside the pre-update atBottom follow flag.
Regressions pinned as E2-4a–c (real host) and §E1-11h (fixture).

feat(gui): webserver hardening verify script

feat(gui): dark-mode toggle pinned to the sidebar bottom

Interim home before the Settings page exists (the button re-homes with
zero logic change — mechanics live in utils/theme.ts): html[data-theme]
flip + dsc.theme localStorage, stored choice wins over the OS
prefers-color-scheme default, applied in mount() before first paint so
a dark reload never flashes light. Moon/sun inline SVG icon button at
the sidebar's pinned bottom row. Pure front-end local concern: no RPC,
no Session/store involvement. Dark sweep of list/conversation/input
card/RPC panel found no unreadable pairs — no token changes needed.

docs(gui): GUI RFCs and web styling handbook

Layering+RPC protocol and web client architecture RFCs (post-reorg,
developer-facing polish folded in) plus the styling engineering
handbook. Mission work logs live in the commit above; PRs can be cut
from this commit to include formal docs only.

fix(gui): client object-layer hardening — audit timing/reference/resilience batches (S3-S5,C1-C3,C5-C8)

fix(gui): carrier error channel + webserver backpressure (audit A1-A5,A7-A10,R2,R5)

feat(gui): session persistence surface — cold list, project cwd, legacy no-cwd retirement

refactor: rename dsc CLI to dsh — apps/cli, bin name, package scope

Includes the root tsconfig project-references fix for host/* and
client/web-runtime (originally a separate build fix commit).

test(gui): three-tier suite — protocol/object/browser lanes, tier-a fill to per-file 100%

test(gui): jsdom lane for web-ui + web-runtime coverage gate entry

docs(gui): GUI testing system RFC (zh)

feat(gui): tool-card views — contract slot, host-computed delivery, three-level card fallback

fix(gui): lint clean across GUI packages — wrap long doc comments, drop dead type args, sync-return methods without awaits

docs(gui): doc-sync mechanical fixes — JSDoc on apiproxy/host exports, RFC sketch fences ignore-check, md-wrap paragraphs, drop missions links, web-ui plain-ts entry

chore(gui): module-graph regen + knip clean — drop dead re-exports, internalize createFixtureApi, scan web-ui tsx and verify mjs scripts

build(gui): wire client/host packages into the lib build shape — tsc references + tsdown (web-ui css-external), lib manifests, cordis peer, apiproxy typed subpaths, vite src aliases

test(gui): host-side per-file 100% coverage — apiproxy schema/carrier suites, webserver http-bridge suite, host-runtime composition suite; client/* coverage excluded pending the browser-side testing work item

docs(gui): package READMEs for the five GUI packages — model-experience audit entries, limitations sections

docs(gui): bilingual RFC pairs + client JSDoc completion — translate the three GUI RFCs to English with i18n records and manifest ratchet, Consequences sections both sides, full client/* export JSDoc, regen doc graphs and RFC index

fix(scripts): doc-typecheck built-declarations mode maps /src/* subpath wildcards (apiproxy browser-safe channels)

docs(gui): apply dsh rename across pr-gates docs — READMEs, layering RFC en, web-ui entry comment, i18n re-record

fix(gui): post-rebase lint reconciliation — wrap main-tree long doc comments, read-through narrowing guards, abortError Error normalization, handleUnary generic justification

fix(gui): post-rebase doc/test reconciliation — align host specs with evolved carrier contracts (sentinel rpcId, stream/error surfacing, url-path transport messages, defaults.cwd), Agent Note titles and relocated links, KV Cache effect sections, JSDoc on evolved exports

fix(gui): second-rebase reconciliation to 509db0cb3 — restore api panel exports the baseline suites consume, knip workspace entries for jsdom lane and apps/web smokes, hoist result narrowing, align testing.md to the narrowed web-ui exclusion

fix(test): vitest-scoped tsconfig maps bare imports for tsx specs — with GUI manifests now pointing at lib, an unmapped importer loaded a second copy of the web-runtime singletons

fix(gui): typecheck + lint clean over the tool-card batch — brand callIds and object-form turn/end reason in the view spec, narrow fixture arg stringification, wrap long v8-ignore comments

docs(gui): export JSDoc for tool-card surfaces + testing-note pairing header

docs: rfc for web testing

feat: add tools to host-runtime

fix(gui): dispatch agent/error via agentEvents in host-runtime spec — mounted invariants plugin rejects raw ctx.emit without the scope carrier

fix(gui): restore GUI knip workspaces + scripts/mjs entries and regenerate lockfile after master rebase

fix(gui): post-rebase gate repairs — drop context-node envelope (master unwrapped injected content envelopes), regen event matrix, condense testing.md web-ui exclusion within budget

fix(session): browser-safe deep-equal in surface — node:util import broke the vite bundle

ci(gates): frontend vite build joins pre-push — node: imports in the client closure pass tsc but break the browser bundle

test(tui): drop the checkout-dependent process.cwd() harness default — a long worktree path pushes the footer token counters past the 88-column fake terminal

test(gui): jsdom behavior E2E — conversation main path over fixture runtime, reconnect banner lifecycle

test(gui): jsdom RPC panel behavior — ledger rows, expand, pairing, pause/clear, follow-pause, payload truncation

test(gui): jsdom tier-2 — InputBar guards, reasoning fold, JSON blocks, message variants, theme, create-then-select; act-harden banner case

test(gui): jsdom tier-3 — ConversationView states/paging/force-bottom, ToolCallCard arms, PendingCard, list rows

test(gui): jsdom tails — view-card variants, LogRow directions, registry hygiene, badge overflow, hook ops, mount glue

test(gui): jsdom tails round 2 — call-ref blocks, resume follow, view precedence, failed create, empty-diff arm

test(gui): jsdom final arms — anchor compensation, follow-off, interval ticks, view halves, node-over-running precedence

test(gui): web-ui joins the per-file 100% coverage gate

Annotation-only src changes plus the config swap. The web-ui exclusion is
replaced by a single index.tsx entry (stale byte-identical duplicate of
mount.tsx, nothing imports it; same entry-glue treatment as bin.ts) and the
coverage include gains .tsx.

v8-ignore sites (each with its reason inline):
- ConversationView 3x ref-null guards; InputBar disabled-click guard
- ToolCallCard both-null arms + windowless-custom argsRaw arm
- LogRow css-module key fallbacks (start/stop block); RpcLogBody 3x ref-null guards
- web-runtime drift from the tool-card batch: fixture presenter catch/str
  typo-guards, dense-array guards (fold-adapter reset, session rebuild,
  fixture backscan), live view-present arm (fixture replays are text-only;
  view vocabulary is covered by the history samples)

test(gui): close the PR #443 host-side coverage gaps — apiproxy client abort arms, api-proxy cold/view paths, webserver drain

- apiproxy fetch/client.ts: 3 new cases (pre-aborted signal short-circuits
  before transport + string reason mapping, non-Error/string reason falls to
  the default AbortError message, signal-less doFetch passthrough)
- runtime/api-proxy.ts: one v8-ignore (summarizeCold cwd arm — list()
  filters cwd-less legacy metas) + api-proxy-cold.spec.ts (cold list merge:
  mtime source, locate-undefined and vanished-log fallbacks, lineage;
  no-persistence/no-factory resume → internal) + 2 view cases (history views
  with meta passthrough and orphan/bad-args/presenterless soft-falls,
  session/disposed open-call cleanup on the mux stream)
- webserver/index.ts: /api/big fixture drives both drain-wait legs (full
  8MiB readback after drain, mid-chunk disconnect wakes via 'close')

feat: app shell

fix: rebase conflicts

fix: coverage

fix(gui): lint clean after rebase — wrap long v8-ignore comments, unconditional v1 detail-block claim

chore(gui): remove browser/probe verify scripts from scripts/

The six GUI acceptance/probe scripts (carrier-errors, rpclog-panel,
session, session-real, webserver-backpressure, webserver-hardening)
leave the repo's scripts/ tree; the three code comments that pointed at
them now describe the coverage lane without naming a script path.

fix(webserver): guard the request callback — one malformed request must not kill the process

The async handle() had no top-level catch, so any throw inside it (a bad
%-escape reaching decodeURIComponent, a client dropping mid-body, a
response stream erroring) became an unhandled rejection and took the whole
process down (audit R1 must-fix). The guard answers 400 when headers are
not out yet, destroys the socket when they are, and reports the failure to
onError (the package never prints). Spec covers all three legs: %-escape
barrage → 400 + server stays alive, non-Error throw wrapped for onError,
mid-stream explosion → socket teardown.

feat: client AGENTS.md

fix: client/AGENTS.md

fix: rebase

feat(gui): T0 cut 1 — 12 client package skeletons with contract stubs, dshClient declarations, tsdown client preset, theme token sheets

feat(gui): T0 cut 2 — pure git mv migration per v3 §11 (connection six, runtime sessions/kernel, ui-conversation chat, ui-primitives markdown family, web shell + e2e)

feat(gui): T0 cuts 3+4 — import rewiring to new package names, .legacy demotion of owner-rewrite files, legacy web-runtime/web-ui/apps-web retired to attic

feat(gui): connection 对账刀——index.ts 精确导出清单替换 export *，intents.legacy 溶解删除

feat(client/ui-slots): SlotCore real implementation — kind semantics, sync version + microtask-batched notify, onMutate bridge

feat(gui): web shell vite alias — retarget to new client packages, shell static surface only

feat(gui): host 侧刀属地半——HostWebPluginRegistry（entries 扫描+internal/plugin 去抖重扫+dshClient 校验+exports./client 解析）、GET /plugins/<id>/client.js 分发端点、GET / 与 SPA fallback 注入 __DSH_BOOT__（webPlugins 可选注入，不传行为不变）

feat(web-react): add use-sync-external-store dep + local shim typings

feat(web-react): bindSnapshotSelector via uSES with-selector shim

feat(gui): ui-layout concession-chain solver — pure computeColumns with contract geometry

feat(gui): ui-layout LayoutService — four persisted stores, clamped actions, list-driven prune

feat(gui): ui-layout AppFrame styles — grid columns, collapse-safe borders, edge drag handles

test(gui): 存量 spec 平移——connection 三件+runtime 六件自 attic 捞回改包名路径全绿；api-helpers 按归属拆分（wire 半留 connection、classifier 半随 conversation.ts 入 runtime）；boot-intents/preinit/rpc-log 随 intents/rpc-log 退役不迁（记 v3 §3.2 溶解项）

feat(client/ui-primitives): StateDot/Button/Pill/Input/Menu atoms, ConnectionBanner de-legacied to pure props, JsonBlock CSS on --dsw tokens

feat(web-react): createSnapshotStore engine (rafFlush batch, persist opt-in, dev freeze) + spec

feat(gui): ui-layout AppFrame — grid tracks, pointer-capture drag handles with rAF throttle, frame ResizeObserver

feat(web-react): useInvoke (external pending store, stable invoke, concurrency count) + spec

test(web-react): bind spec — equality bail, custom eq, zero resubscribe, StrictMode, method sources

feat(gui): ui-layout index rewiring — real exports, client apply provides ctx.layout and defines three slots

feat(web-react): SessionProvider (renderBody deps) + RootBindingProvider + binding contexts + spec

feat(gui): web shell AppRoot boot-page styles — self-contained with neutral token fallbacks

feat(gui): web shell AppRoot — boot gate over loader status, fail-loud plugin failure list

fix(gui): AppRoot gates on explicit settled signal — status-derived readiness races the incrementally filled table

feat(client/ui-theme): ThemeService real implementation — registry with built-in light/dark, apply toggles body[data-ds-dark-theme], third-party token overrides as body inline vars

feat(web-react): scopedSlots outlet (kind matrix, inject WeakMap caches, per-entry error boundary) + spec

feat(gui): web shell module-table seed — pure-library entities for the loader require surface

feat(client/i18n): I18nService real implementation — ns×locale registry, stable bind(ns) reference, zh fallback chain, zh/en skeleton dictionaries

feat(gui): web shell assembly closure — layout exports via module table, SessionProvider + scopedSlots + RootBindingProvider

feat: client/ui-conversation

feat: code

codedoc

build(gui): root bundle green — web shell excluded from the lib workspace (vite app), ui-primitives lib externalizes css side-effect imports (web-ui precedent)

gates(gui): verify-cordis-config follows aggregate tsconfig references (root is a shell over host/client programs); module graph regenerated for the twelve client packages

chore(gui): retire legacy migration sources — every owner rewrite landed (t0-checklist §7 ledger honored); orphan css of retired components removed

gates(gui): knip green groundwork — e2e/tsx entries for the new packages, loader-runtime deps ignored where loading is by specifier string, fake plugin ids un-bare-named, dead test export dropped

chore(client): manifest shape batch A — ui-slots/web-react/ui-primitives invariant companions, files whitelist, cordis+invariants peer/dev, tsconfig refs

chore(client): manifest shape batch B — connection/runtime/ui-conversation/ui-trajectory files whitelist, cordis peer+dev, explicit invariant lib entries (clientBundle signature)

chore(client): manifest shape batch C — i18n/ui-layout/ui-sidebar/ui-theme invariant companions, files whitelist, invariants peer/dev, tsconfig refs

chore(client): manifest shape batch D — web shell gains node-half lib entry + invariant companion + uniform files whitelist

chore(client): drop verified-unused deps — dsh-tools from runtime/ui-conversation (types ride /presentation), ui-primitives+clsx from ui-layout

gates(gui): doc-gate fixes — theme JSDoc prose, three client type-link exemptions, agent-note paths follow the migration, config catalog regenerated

gates(gui): type-equiv manifest follows the types.ts extraction, approval JSDoc keeps its link form, persistence catalog regenerated

docs(gui): per-constant JSDoc on the contract geometry exports (export-jsdoc gate)

test(gates): loader-composition budget covers cold tsx resolution after the program split (was flaking at the default 5s)

docs(gui): README substantiation batch 1 — ui-slots/ui-primitives/web-react/connection: Model Experience short form, real deferred-work ledgers, description accuracy pass

fix(client): theme/i18n dual-entry split — service classes + cordis merges move to src/client (host catalog scanner no longer misclassifies client services), node halves keep types + empty apply; catalogs regenerated

docs(gui): README substantiation batch 2 — runtime/ui-layout/ui-sidebar/ui-conversation: Model Experience short form, package-owned deferred-work ledgers (unload stub, watch approximation, /client value-import rule, global details state, two-state dots, stats duration gap, single-bundle caches)

docs(gui): README substantiation batch 3 — ui-trajectory/ui-theme/i18n/web: Model Experience short form, deferred-work ledgers (placeholder charter, no theme toggle owner, empty locale dictionaries, one-shot rendering); both README gates green

test(scripts): purity spec adopts clientBundle two-arg signature (explicit libEntry, no default)

gates(gui): knip green — declaration-merge dep ignored, fake plugin id assembled at runtime, invariants dep de-duplicated to peer+dev, stale apps/web section dropped

feat(gui): 门禁波次 host 三包 invariant 形状——apiproxy explained-empty 伴生（wire 契约层零事件面）、webserver 真关系伴生（manifest 行必解析出 clientPath，防 __DSH_BOOT__ 广告 404 bundle；apps/cli 发布 webPlugins 键供审计）、runtime 补 files 白名单；三包 exports/files/peer+dev/tsconfig refs 齐 fw-react 形状；constraints+invariants 双 gate 零违规

build(client): ui-layout/ui-sidebar tsdown configs adopt the explicit two-arg clientBundle signature (orphaned follow-up of the manifest shape batch)

refactor(gui): shell boot becomes a library face — bootWebShell(el) exported for the apps/web entry; main.ts retired

refactor(gui): exports 纪律刀1——ui-theme/i18n node index 收敛为只空 apply（Translate/LocaleDict/ThemeTokens 类型下沉 src/client/），ui-conversation 的 I18nService import 改 /client 子路径

build(typecheck): converge to root host aggregate + tsconfig.client.json — delete tsconfig.host.json, verify-cordis-config seeds both aggregates

feat(gui): apps/web restored as the vite application — thin main over bootWebShell; dsh-client-web becomes a plain lib (index exports shell surface, vite files and e2e moved out)

chore(gates): knip.json rewritten on the master base — same semantics, minimal diff (formatting churn dropped)

docs(gui): 时效清扫②——testing.md 删 web-ui 覆盖豁免残句；web-styling.md 加 token 换代头注（--dsw-* 现行、工程约束条款仍有效并注明收编处）

docs(gui): 时效清扫③——四对 GUI Agent Note 加路径更新头注（web-runtime/web-ui/dsh-frontend→现行 12 包结构；设计结论存续声明；双语对同步）

docs(gui): 时效清扫③b——四对 note 头注的 i18n 配对哈希重录

build(typecheck): minimal-diff tsconfig shape — drop root files entry (purity spec + preset move to client program), compress comments, drop redundant util/home root ref

feat(gui): apps/web restoration follow-through — dsh-frontend package name, cli dist resolve, root build:web filter, tsdown exemption dropped, vitest web lane + knip + client aggregate retargeted, e2e paths rebased

refactor(gui): exports 纪律刀2——connection wire 六件 git mv 进 src/client/（wire 即该 dshClient 插件的 client 半），node index=只空 apply，/client 半边整面导出（v3 §3.2 清单原样），包内 tests 改 src/client 直取

refactor(gui): exports 纪律刀3——runtime 实现整体下沉 src/client/（sessions/slots/loader；契约类型与 cordis merge 随迁 client/index），node index=只空 apply；./loader exports 指 client/loader；全消费面（web 壳/ui-sidebar/ui-trajectory/tests）bare→/client 机械跟改；vitest.e2e 换 tsconfig.vitest paths（root tsconfig 排除 client 会把 /client import 掉到 exports 的浏览器 dist bundle）

refactor(gui): exports 纪律刀3 补遗——ui-layout 三处 bare runtime import 改 /client（刀3 消费面机械跟改漏提交件；跨属地机械一行×3 报备 ui-shell）

test(gui): drop the getSessionManager singleton case — the init/get pair is a dead legacy-boot surface with zero live consumers (SessionsService constructs and holds the manager under the plugin architecture); source removal tracked with rt-core

refactor(gui): 删 manager.ts 尾部 initSessionManager/getSessionManager 单例对——旧 boot 直连遗物，插件化下 SessionsService 构造持有 manager，全仓零活消费者（convo-b 测试清扫对表，其测试用例已先行退役 7e2c51898）；头注释同步去单例措辞

code

refactor
---
 ...19-gui-layering-and-rpc-protocol.i18n.yaml |    6 +
 ...026-07-19-gui-layering-and-rpc-protocol.md |  253 +++
 ...-07-19-gui-layering-and-rpc-protocol.zh.md |  251 +++
 ...7-19-gui-web-client-architecture.i18n.yaml |    6 +
 .../2026-07-19-gui-web-client-architecture.md |  148 ++
 ...26-07-19-gui-web-client-architecture.zh.md |  148 ++
 ...2-slot-type-chain-implementation.i18n.yaml |    6 +
 ...26-07-22-slot-type-chain-implementation.md |   47 +
 ...07-22-slot-type-chain-implementation.zh.md |   47 +
 .../2026-07-19-web-styling-system.i18n.yaml   |    6 +
 .../process/2026-07-19-web-styling-system.md  |   61 +
 .../2026-07-19-web-styling-system.zh.md       |   61 +
 .../2026-07-20-gui-testing-system.i18n.yaml   |    6 +
 .../process/2026-07-20-gui-testing-system.md  |   59 +
 .../2026-07-20-gui-testing-system.zh.md       |   59 +
 .gitignore                                    |    2 +
 apps/cli/package.json                         |   23 +
 apps/cli/src/bin.ts                           |   22 +
 apps/cli/src/headless.ts                      |  104 ++
 apps/cli/src/web.ts                           |   89 +
 apps/cli/tsconfig.json                        |   18 +
 apps/web/index.html                           |   12 +
 apps/web/package.json                         |   37 +
 apps/web/src/main.ts                          |   10 +
 apps/web/tests/smoke-fixture.e2e.ts           |  147 ++
 apps/web/tests/smoke-real.e2e.ts              |  235 +++
 apps/web/tests/support.ts                     |   47 +
 apps/web/tsconfig.json                        |   22 +
 apps/web/vite.config.ts                       |   26 +
 docs/config-catalog.md                        |   17 +-
 docs/cordis-catalog/events.md                 |    2 +-
 docs/cordis-catalog/services.md               |    4 +-
 docs/event-producer-consumer.md               |   16 +-
 docs/module-graph.md                          |   49 +
 docs/persistence-catalog.md                   |    6 +-
 docs/web-styling.md                           |  107 ++
 eslint.config.mjs                             |   16 +
 knip.json                                     |  536 +++++-
 package.json                                  |   11 +-
 packages/client/AGENTS.md                     |   71 +
 packages/client/connection/README.md          |   16 +
 packages/client/connection/package.json       |   53 +
 packages/client/connection/src/client/api.ts  |   47 +
 .../connection/src/client/connection.ts       |  190 +++
 .../client/connection/src/client/fixture.ts   |  554 +++++++
 .../client/connection/src/client/index.ts     |   76 +
 .../connection/src/client/web-api-client.ts   |   12 +
 packages/client/connection/src/index.ts       |   10 +
 packages/client/connection/src/invariant.ts   |   32 +
 .../connection/tests/api-helpers.spec.ts      |   21 +
 .../connection/tests/connection.spec.ts       |  238 +++
 packages/client/connection/tests/fake-api.ts  |  154 ++
 .../client/connection/tests/fixture.spec.ts   |  338 ++++
 .../client/connection/tests/node-half.spec.ts |   10 +
 packages/client/connection/tsconfig.json      |   42 +
 packages/client/connection/tsdown.config.ts   |    3 +
 packages/client/i18n/README.md                |   16 +
 packages/client/i18n/package.json             |   54 +
 packages/client/i18n/src/client/index.ts      |  108 ++
 packages/client/i18n/src/index.ts             |   11 +
 packages/client/i18n/src/invariant.ts         |   32 +
 packages/client/i18n/src/locales/en.ts        |    2 +
 packages/client/i18n/src/locales/zh.ts        |    2 +
 packages/client/i18n/tests/i18n.spec.ts       |   53 +
 packages/client/i18n/tests/invariant.spec.ts  |   30 +
 packages/client/i18n/tsconfig.json            |   27 +
 packages/client/i18n/tsdown.config.ts         |    3 +
 packages/client/runtime/README.md             |   18 +
 packages/client/runtime/package.json          |   63 +
 packages/client/runtime/src/client/index.ts   |  128 ++
 .../client/runtime/src/client/loader/index.ts |  247 +++
 .../src/client/sessions/conversation.ts       |  165 ++
 .../src/client/sessions/fold-adapter.ts       |  194 +++
 .../runtime/src/client/sessions/lineage.ts    |   63 +
 .../runtime/src/client/sessions/manager.ts    |  250 +++
 .../runtime/src/client/sessions/notifier.ts   |   61 +
 .../runtime/src/client/sessions/partial.ts    |   89 +
 .../runtime/src/client/sessions/service.ts    |  221 +++
 .../runtime/src/client/sessions/session.ts    |  527 ++++++
 packages/client/runtime/src/client/slots.ts   |  107 ++
 packages/client/runtime/src/index.ts          |   11 +
 packages/client/runtime/src/invariant.ts      |   52 +
 .../runtime/tests/client-loader-bundle.e2e.ts |   77 +
 .../runtime/tests/client-loader.spec.ts       |  192 +++
 .../client/runtime/tests/conversation.spec.ts |   23 +
 packages/client/runtime/tests/event-script.ts |   50 +
 packages/client/runtime/tests/fake-api.ts     |  157 ++
 .../client/runtime/tests/fold-adapter.spec.ts |  145 ++
 packages/client/runtime/tests/lineage.spec.ts |   55 +
 packages/client/runtime/tests/manager.spec.ts |  223 +++
 .../client/runtime/tests/node-half.spec.ts    |   10 +
 .../client/runtime/tests/notifier.spec.ts     |   75 +
 packages/client/runtime/tests/partial.spec.ts |   91 +
 packages/client/runtime/tests/session.spec.ts |  625 +++++++
 .../runtime/tests/sessions-service.spec.ts    |  141 ++
 .../runtime/tests/slots-service.spec.ts       |   65 +
 packages/client/runtime/tsconfig.json         |   39 +
 packages/client/runtime/tsdown.config.ts      |   23 +
 packages/client/tsdown.client.ts              |  152 ++
 packages/client/ui-conversation/README.md     |   22 +
 packages/client/ui-conversation/package.json  |   63 +
 .../ui-conversation/src/client/apply.ts       |  185 +++
 .../client/chat/AssistantMarkdown.module.css  |   33 +
 .../src/client/chat/AssistantMarkdown.tsx     |   56 +
 .../src/client/chat/ChatView.module.css       |  101 ++
 .../src/client/chat/ChatView.tsx              |  293 ++++
 .../src/client/chat/GenericToolCard.tsx       |   36 +
 .../src/client/chat/IconSparkle16.tsx         |   15 +
 .../src/client/chat/MessageItem.module.css    |   34 +
 .../src/client/chat/MessageItem.tsx           |   56 +
 .../src/client/chat/PendingCard.module.css    |   31 +
 .../src/client/chat/PendingCard.tsx           |   31 +
 .../src/client/chat/StatsLine.module.css      |   13 +
 .../src/client/chat/StatsLine.tsx             |   68 +
 .../src/client/chat/ToolRow.module.css        |   88 +
 .../src/client/chat/ToolRow.tsx               |   75 +
 .../src/client/chat/ToolViewOutlet.tsx        |   89 +
 .../src/client/chat/chat-flow.ts              |   46 +
 .../src/client/chat/register.ts               |   52 +
 .../src/client/contract/slots.ts              |   63 +
 .../src/client/contract/tool-call-model.ts    |  126 ++
 .../src/client/contract/toolview.ts           |   77 +
 .../src/client/contract/views.ts              |   68 +
 .../ui-conversation/src/client/index.ts       |   42 +
 .../ui-conversation/src/client/service.ts     |  251 +++
 .../skeleton/ConversationRoot.module.css      |  129 ++
 .../src/client/skeleton/ConversationRoot.tsx  |  109 ++
 .../client/skeleton/DetailsPanel.module.css   |   94 ++
 .../src/client/skeleton/DetailsPanel.tsx      |  111 ++
 .../src/client/skeleton/EmptyState.module.css |   68 +
 .../src/client/skeleton/EmptyState.tsx        |  106 ++
 .../src/client/skeleton/InputBar.module.css   |  160 ++
 .../src/client/skeleton/InputBar.tsx          |  142 ++
 .../client/toolviews/bash-sample.module.css   |   48 +
 .../src/client/toolviews/bash-sample.tsx      |   52 +
 .../src/client/toolviews/registry.ts          |  102 ++
 .../ui-conversation/src/css-modules.d.ts      |    6 +
 packages/client/ui-conversation/src/index.ts  |   10 +
 .../client/ui-conversation/src/invariant.ts   |   33 +
 .../tests/apply-inject.spec.tsx               |  276 ++++
 .../ui-conversation/tests/chat-apply.spec.tsx |  105 ++
 .../tests/chat-branch-tails.spec.tsx          |  156 ++
 .../tests/chat-stats-bash-sample.spec.tsx     |  178 ++
 .../tests/chat-tool-row.spec.tsx              |  147 ++
 .../ui-conversation/tests/chat-view.spec.tsx  |  305 ++++
 .../tests/coverage-tails.spec.tsx             |  127 ++
 .../tests/gate-branch-tails.spec.tsx          |  140 ++
 .../ui-conversation/tests/input-bar.spec.tsx  |  131 ++
 .../tests/selection-survival.spec.ts          |  121 ++
 .../tests/service-orchestration.spec.ts       |  190 +++
 .../tests/service-stores.spec.ts              |  176 ++
 .../tests/skeleton-branches.spec.tsx          |  245 +++
 .../ui-conversation/tests/skeleton.spec.tsx   |  181 ++
 .../tests/toolview-entry-types.spec.ts        |   62 +
 .../tests/toolview-registry.spec.ts           |  101 ++
 .../tests/toolviews-type-chain.spec.ts        |   96 ++
 .../tests/views-type-chain.spec.tsx           |  100 ++
 packages/client/ui-conversation/tsconfig.json |   46 +
 .../client/ui-conversation/tsdown.config.ts   |    3 +
 packages/client/ui-layout/README.md           |   19 +
 packages/client/ui-layout/package.json        |   59 +
 .../ui-layout/src/client/AppFrame.module.css  |   73 +
 .../client/ui-layout/src/client/AppFrame.tsx  |  149 ++
 .../client/ui-layout/src/client/columns.ts    |   79 +
 packages/client/ui-layout/src/client/index.ts |   81 +
 .../client/ui-layout/src/client/service.ts    |  132 ++
 .../client/ui-layout/src/css-modules.d.ts     |    6 +
 packages/client/ui-layout/src/index.ts        |   10 +
 packages/client/ui-layout/src/invariant.ts    |   31 +
 .../client/ui-layout/tests/app-frame.spec.tsx |  208 +++
 packages/client/ui-layout/tests/apply.spec.ts |   71 +
 .../client/ui-layout/tests/columns.spec.ts    |  100 ++
 .../client/ui-layout/tests/service.spec.ts    |  138 ++
 packages/client/ui-layout/tsconfig.json       |   37 +
 packages/client/ui-layout/tsdown.config.ts    |    3 +
 packages/client/ui-primitives/README.md       |   18 +
 packages/client/ui-primitives/package.json    |   42 +
 .../ui-primitives/src/Button.module.css       |   73 +
 packages/client/ui-primitives/src/Button.tsx  |   31 +
 .../src/ConnectionBanner.module.css           |   13 +
 .../ui-primitives/src/ConnectionBanner.tsx    |   16 +
 .../client/ui-primitives/src/FishLogo.tsx     |   27 +
 .../client/ui-primitives/src/Input.module.css |   38 +
 packages/client/ui-primitives/src/Input.tsx   |   23 +
 .../client/ui-primitives/src/Menu.module.css  |   68 +
 packages/client/ui-primitives/src/Menu.tsx    |   81 +
 .../client/ui-primitives/src/Pill.module.css  |   27 +
 packages/client/ui-primitives/src/Pill.tsx    |   31 +
 .../ui-primitives/src/StateDot.module.css     |   65 +
 .../client/ui-primitives/src/StateDot.tsx     |   55 +
 .../client/ui-primitives/src/css-modules.d.ts |    6 +
 .../client/ui-primitives/src/icons/index.tsx  |  575 +++++++
 .../client/ui-primitives/src/icons/props.ts   |    8 +
 packages/client/ui-primitives/src/index.ts    |   19 +
 .../client/ui-primitives/src/invariant.ts     |   31 +
 .../src/markdown/JsonBlock.module.css         |   32 +
 .../ui-primitives/src/markdown/JsonBlock.tsx  |   32 +
 .../src/markdown/MessageText.module.css       |    9 +
 .../src/markdown/MessageText.tsx              |    7 +
 .../client/ui-primitives/tests/atoms.spec.tsx |  122 ++
 .../client/ui-primitives/tests/icons.spec.tsx |   58 +
 .../ui-primitives/tests/invariant.spec.ts     |   12 +
 .../ui-primitives/tests/markdown.spec.tsx     |   49 +
 .../ui-primitives/tests/state-dot.spec.tsx    |   45 +
 packages/client/ui-primitives/tsconfig.json   |   25 +
 .../client/ui-primitives/tsdown.config.ts     |   31 +
 packages/client/ui-sidebar/README.md          |   19 +
 packages/client/ui-sidebar/package.json       |   62 +
 .../ui-sidebar/src/client/Rows.module.css     |  158 ++
 .../client/ui-sidebar/src/client/Rows.tsx     |  122 ++
 .../src/client/SidebarRoot.module.css         |  248 +++
 .../ui-sidebar/src/client/SidebarRoot.tsx     |  164 ++
 .../ui-sidebar/src/client/contract/slots.ts   |   49 +
 .../client/ui-sidebar/src/client/index.ts     |   71 +
 .../client/ui-sidebar/src/client/store.ts     |   94 ++
 packages/client/ui-sidebar/src/client/tree.ts |  265 +++
 .../client/ui-sidebar/src/css-modules.d.ts    |    6 +
 packages/client/ui-sidebar/src/index.ts       |   10 +
 packages/client/ui-sidebar/src/invariant.ts   |   32 +
 .../client/ui-sidebar/tests/apply.spec.tsx    |  158 ++
 .../client/ui-sidebar/tests/invariant.spec.ts |   18 +
 .../ui-sidebar/tests/sidebar-root.spec.tsx    |  195 +++
 .../client/ui-sidebar/tests/store.spec.ts     |  111 ++
 packages/client/ui-sidebar/tests/tree.spec.ts |  234 +++
 packages/client/ui-sidebar/tsconfig.json      |   40 +
 packages/client/ui-sidebar/tsdown.config.ts   |    3 +
 packages/client/ui-slots/README.md            |   18 +
 packages/client/ui-slots/package.json         |   38 +
 packages/client/ui-slots/src/index.ts         |  407 +++++
 packages/client/ui-slots/src/invariant.ts     |   32 +
 packages/client/ui-slots/tests/core.spec.ts   |  209 +++
 .../client/ui-slots/tests/invariant.spec.ts   |   12 +
 .../client/ui-slots/tests/surface.spec.ts     |   52 +
 .../client/ui-slots/tests/type-chain.spec.tsx |  140 ++
 packages/client/ui-slots/tsconfig.json        |   21 +
 packages/client/ui-theme/README.md            |   17 +
 packages/client/ui-theme/package.json         |   52 +
 packages/client/ui-theme/src/client/index.ts  |   85 +
 packages/client/ui-theme/src/index.ts         |   11 +
 packages/client/ui-theme/src/invariant.ts     |   31 +
 packages/client/ui-theme/src/styles/base.css  |   10 +
 .../ui-theme/src/styles/design-platform.css   |  326 ++++
 .../src/styles/gradient-shadow-text.css       |  224 +++
 .../client/ui-theme/tests/invariant.spec.ts   |   27 +
 packages/client/ui-theme/tests/theme.spec.ts  |   61 +
 packages/client/ui-theme/tsconfig.json        |   24 +
 packages/client/ui-theme/tsdown.config.ts     |    3 +
 packages/client/ui-trajectory/README.md       |   15 +
 packages/client/ui-trajectory/package.json    |   59 +
 .../client/TrajectoryStatsHeader.module.css   |    7 +
 .../src/client/TrajectoryStatsHeader.tsx      |   28 +
 .../src/client/TrajectoryView.tsx             |   28 +
 .../src/client/WaterfallView.tsx              |   49 +
 .../client/ui-trajectory/src/client/index.ts  |   46 +
 .../client/ui-trajectory/src/client/spans.ts  |   71 +
 .../ui-trajectory/src/client/views.module.css |   37 +
 .../client/ui-trajectory/src/css-modules.d.ts |    6 +
 packages/client/ui-trajectory/src/index.ts    |   10 +
 .../client/ui-trajectory/src/invariant.ts     |   32 +
 .../ui-trajectory/tests/client-bundle.spec.ts |   81 +
 .../client/ui-trajectory/tests/views.spec.tsx |  197 +++
 packages/client/ui-trajectory/tsconfig.json   |   34 +
 .../client/ui-trajectory/tsdown.config.ts     |    3 +
 packages/client/web-react/README.md           |   17 +
 packages/client/web-react/package.json        |   50 +
 packages/client/web-react/src/bind.ts         |   22 +
 packages/client/web-react/src/env.d.ts        |    5 +
 packages/client/web-react/src/index.ts        |   41 +
 packages/client/web-react/src/invariant.ts    |   32 +
 .../client/web-react/src/scoped-slots.tsx     |  191 +++
 .../client/web-react/src/session-provider.tsx |   74 +
 packages/client/web-react/src/store/index.ts  |  150 ++
 packages/client/web-react/src/use-invoke.ts   |   62 +
 .../src/use-sync-external-store.d.ts          |   14 +
 packages/client/web-react/tests/bind.spec.tsx |  125 ++
 .../tests/scoped-slots-real-core.spec.tsx     |   70 +
 .../web-react/tests/scoped-slots.spec.tsx     |  274 +++
 .../web-react/tests/session-provider.spec.tsx |  106 ++
 packages/client/web-react/tests/store.spec.ts |  135 ++
 .../web-react/tests/use-invoke.spec.tsx       |   84 +
 packages/client/web-react/tsconfig.json       |   25 +
 packages/client/web-react/tsdown.config.ts    |   42 +
 packages/client/web/README.md                 |   19 +
 packages/client/web/package.json              |   51 +
 packages/client/web/src/AppRoot.module.css    |   66 +
 packages/client/web/src/AppRoot.tsx           |   52 +
 packages/client/web/src/app.tsx               |   89 +
 packages/client/web/src/base.css              |   19 +
 packages/client/web/src/boot.tsx              |   66 +
 packages/client/web/src/css-modules.d.ts      |    6 +
 packages/client/web/src/index.ts              |   11 +
 packages/client/web/src/invariant.ts          |   32 +
 packages/client/web/src/seed.ts               |   35 +
 packages/client/web/tests/app-root.spec.tsx   |   73 +
 packages/client/web/tests/boot.spec.tsx       |  200 +++
 packages/client/web/tsconfig.json             |   49 +
 packages/client/web/tsdown.config.ts          |   31 +
 packages/core/session/package.json            |   11 +-
 packages/core/session/src/surface.ts          |   24 +-
 packages/core/session/tests/surface.spec.ts   |   32 +
 packages/core/tools/package.json              |    5 +
 packages/host/apiproxy/README.md              |   27 +
 packages/host/apiproxy/package.json           |   59 +
 .../host/apiproxy/src/api/approvals.schema.ts |   21 +
 packages/host/apiproxy/src/api/approvals.ts   |   21 +
 .../host/apiproxy/src/api/events.schema.ts    |   42 +
 packages/host/apiproxy/src/api/events.ts      |   69 +
 packages/host/apiproxy/src/api/host.schema.ts |   19 +
 packages/host/apiproxy/src/api/host.ts        |   25 +
 packages/host/apiproxy/src/api/index.ts       |   46 +
 .../host/apiproxy/src/api/questions.schema.ts |   26 +
 packages/host/apiproxy/src/api/questions.ts   |   19 +
 packages/host/apiproxy/src/api/rpc-map.ts     |   26 +
 packages/host/apiproxy/src/api/rpc.schema.ts  |   97 ++
 packages/host/apiproxy/src/api/rpc.ts         |  113 ++
 .../host/apiproxy/src/api/sessions.schema.ts  |  110 ++
 packages/host/apiproxy/src/api/sessions.ts    |   73 +
 packages/host/apiproxy/src/fetch/client.ts    |  302 ++++
 packages/host/apiproxy/src/fetch/handler.ts   |  197 +++
 packages/host/apiproxy/src/index.ts           |   13 +
 packages/host/apiproxy/src/invariant.ts       |   33 +
 .../apiproxy/tests/client-handler.spec.ts     |  407 +++++
 .../host/apiproxy/tests/fetch-carrier.spec.ts |  305 ++++
 .../host/apiproxy/tests/rpc-schemas.spec.ts   |  161 ++
 packages/host/apiproxy/tsconfig.json          |   33 +
 packages/host/runtime/README.md               |   31 +
 packages/host/runtime/package.json            |   82 +
 packages/host/runtime/src/api-proxy.ts        |  429 +++++
 packages/host/runtime/src/boot.ts             |  133 ++
 packages/host/runtime/src/index.ts            |   14 +
 packages/host/runtime/src/invariant.ts        |   31 +
 packages/host/runtime/src/start.ts            |   58 +
 packages/host/runtime/src/web-plugins.ts      |   63 +
 .../host/runtime/tests/api-proxy-cold.spec.ts |   94 ++
 .../host/runtime/tests/api-proxy-view.spec.ts |  179 ++
 .../host/runtime/tests/host-runtime.spec.ts   |  367 +++++
 .../host/runtime/tests/web-plugins.e2e.ts     |   71 +
 .../host/runtime/tests/web-plugins.spec.ts    |  114 ++
 packages/host/runtime/tsconfig.json           |  144 ++
 packages/host/webserver/README.md             |   23 +
 packages/host/webserver/package.json          |   37 +
 packages/host/webserver/src/index.ts          |  208 +++
 packages/host/webserver/src/invariant.ts      |   49 +
 packages/host/webserver/src/static.ts         |   58 +
 packages/host/webserver/src/web-plugins.ts    |  184 +++
 .../host/webserver/tests/invariant.spec.ts    |   50 +
 .../host/webserver/tests/web-plugins.spec.ts  |  210 +++
 .../host/webserver/tests/webserver.spec.ts    |  337 ++++
 packages/host/webserver/tsconfig.json         |   18 +
 .../tests/loader-composition.spec.ts          |    5 +-
 packages/llm/llm/package.json                 |    9 +
 packages/ui/tui/tests/tui.spec.ts             |    8 +-
 packages/ui/user-approval/package.json        |    5 +
 packages/ui/user-approval/src/index.ts        |   24 +-
 packages/ui/user-approval/src/types.ts        |   29 +
 packages/ui/user-approval/tsdown.config.ts    |   30 +
 packages/ui/user-interaction/package.json     |    5 +
 packages/ui/user-interaction/src/index.ts     |   40 +-
 packages/ui/user-interaction/src/types.ts     |   44 +
 pnpm-lock.yaml                                | 1463 ++++++++++++++++-
 pnpm-workspace.yaml                           |    1 +
 scripts/check-workspace-constraints.ts        |   22 +
 scripts/client-bundle-purity.spec.ts          |   60 +
 scripts/doc-typecheck-paths.ts                |   11 +
 scripts/gen-cordis-catalog.ts                 |    3 +
 scripts/run-gates.ts                          |    2 +
 scripts/translation-pairing.manifest.json     |   10 +-
 scripts/type-equiv.manifest.json              | 1185 ++++++++++---
 scripts/verify-client-domain-graph.ts         |  102 ++
 scripts/verify-cordis-config.ts               |   30 +-
 .../verify-package-readme-model-experience.ts |   15 +
 tsconfig.base.json                            |   36 +-
 tsconfig.build.json                           |   15 +
 tsconfig.client.json                          |   42 +
 tsconfig.json                                 |    9 +
 tsconfig.vitest.json                          |   15 +
 vitest.config.ts                              |   17 +-
 vitest.e2e.config.ts                          |    9 +-
 vitest.web.config.ts                          |   30 +
 379 files changed, 33246 insertions(+), 411 deletions(-)
 create mode 100644 .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
 create mode 100644 .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
 create mode 100644 .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
 create mode 100644 .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
 create mode 100644 .agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md
 create mode 100644 .agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md
 create mode 100644 .agents/notes/implemented/process/2026-07-19-web-styling-system.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-07-19-web-styling-system.md
 create mode 100644 .agents/notes/implemented/process/2026-07-19-web-styling-system.zh.md
 create mode 100644 .agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-07-20-gui-testing-system.md
 create mode 100644 .agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
 create mode 100644 apps/cli/package.json
 create mode 100644 apps/cli/src/bin.ts
 create mode 100644 apps/cli/src/headless.ts
 create mode 100644 apps/cli/src/web.ts
 create mode 100644 apps/cli/tsconfig.json
 create mode 100644 apps/web/index.html
 create mode 100644 apps/web/package.json
 create mode 100644 apps/web/src/main.ts
 create mode 100644 apps/web/tests/smoke-fixture.e2e.ts
 create mode 100644 apps/web/tests/smoke-real.e2e.ts
 create mode 100644 apps/web/tests/support.ts
 create mode 100644 apps/web/tsconfig.json
 create mode 100644 apps/web/vite.config.ts
 create mode 100644 docs/web-styling.md
 create mode 100644 packages/client/AGENTS.md
 create mode 100644 packages/client/connection/README.md
 create mode 100644 packages/client/connection/package.json
 create mode 100644 packages/client/connection/src/client/api.ts
 create mode 100644 packages/client/connection/src/client/connection.ts
 create mode 100644 packages/client/connection/src/client/fixture.ts
 create mode 100644 packages/client/connection/src/client/index.ts
 create mode 100644 packages/client/connection/src/client/web-api-client.ts
 create mode 100644 packages/client/connection/src/index.ts
 create mode 100644 packages/client/connection/src/invariant.ts
 create mode 100644 packages/client/connection/tests/api-helpers.spec.ts
 create mode 100644 packages/client/connection/tests/connection.spec.ts
 create mode 100644 packages/client/connection/tests/fake-api.ts
 create mode 100644 packages/client/connection/tests/fixture.spec.ts
 create mode 100644 packages/client/connection/tests/node-half.spec.ts
 create mode 100644 packages/client/connection/tsconfig.json
 create mode 100644 packages/client/connection/tsdown.config.ts
 create mode 100644 packages/client/i18n/README.md
 create mode 100644 packages/client/i18n/package.json
 create mode 100644 packages/client/i18n/src/client/index.ts
 create mode 100644 packages/client/i18n/src/index.ts
 create mode 100644 packages/client/i18n/src/invariant.ts
 create mode 100644 packages/client/i18n/src/locales/en.ts
 create mode 100644 packages/client/i18n/src/locales/zh.ts
 create mode 100644 packages/client/i18n/tests/i18n.spec.ts
 create mode 100644 packages/client/i18n/tests/invariant.spec.ts
 create mode 100644 packages/client/i18n/tsconfig.json
 create mode 100644 packages/client/i18n/tsdown.config.ts
 create mode 100644 packages/client/runtime/README.md
 create mode 100644 packages/client/runtime/package.json
 create mode 100644 packages/client/runtime/src/client/index.ts
 create mode 100644 packages/client/runtime/src/client/loader/index.ts
 create mode 100644 packages/client/runtime/src/client/sessions/conversation.ts
 create mode 100644 packages/client/runtime/src/client/sessions/fold-adapter.ts
 create mode 100644 packages/client/runtime/src/client/sessions/lineage.ts
 create mode 100644 packages/client/runtime/src/client/sessions/manager.ts
 create mode 100644 packages/client/runtime/src/client/sessions/notifier.ts
 create mode 100644 packages/client/runtime/src/client/sessions/partial.ts
 create mode 100644 packages/client/runtime/src/client/sessions/service.ts
 create mode 100644 packages/client/runtime/src/client/sessions/session.ts
 create mode 100644 packages/client/runtime/src/client/slots.ts
 create mode 100644 packages/client/runtime/src/index.ts
 create mode 100644 packages/client/runtime/src/invariant.ts
 create mode 100644 packages/client/runtime/tests/client-loader-bundle.e2e.ts
 create mode 100644 packages/client/runtime/tests/client-loader.spec.ts
 create mode 100644 packages/client/runtime/tests/conversation.spec.ts
 create mode 100644 packages/client/runtime/tests/event-script.ts
 create mode 100644 packages/client/runtime/tests/fake-api.ts
 create mode 100644 packages/client/runtime/tests/fold-adapter.spec.ts
 create mode 100644 packages/client/runtime/tests/lineage.spec.ts
 create mode 100644 packages/client/runtime/tests/manager.spec.ts
 create mode 100644 packages/client/runtime/tests/node-half.spec.ts
 create mode 100644 packages/client/runtime/tests/notifier.spec.ts
 create mode 100644 packages/client/runtime/tests/partial.spec.ts
 create mode 100644 packages/client/runtime/tests/session.spec.ts
 create mode 100644 packages/client/runtime/tests/sessions-service.spec.ts
 create mode 100644 packages/client/runtime/tests/slots-service.spec.ts
 create mode 100644 packages/client/runtime/tsconfig.json
 create mode 100644 packages/client/runtime/tsdown.config.ts
 create mode 100644 packages/client/tsdown.client.ts
 create mode 100644 packages/client/ui-conversation/README.md
 create mode 100644 packages/client/ui-conversation/package.json
 create mode 100644 packages/client/ui-conversation/src/client/apply.ts
 create mode 100644 packages/client/ui-conversation/src/client/chat/AssistantMarkdown.module.css
 create mode 100644 packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
 create mode 100644 packages/client/ui-conversation/src/client/chat/ChatView.module.css
 create mode 100644 packages/client/ui-conversation/src/client/chat/ChatView.tsx
 create mode 100644 packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx
 create mode 100644 packages/client/ui-conversation/src/client/chat/IconSparkle16.tsx
 create mode 100644 packages/client/ui-conversation/src/client/chat/MessageItem.module.css
 create mode 100644 packages/client/ui-conversation/src/client/chat/MessageItem.tsx
 create mode 100644 packages/client/ui-conversation/src/client/chat/PendingCard.module.css
 create mode 100644 packages/client/ui-conversation/src/client/chat/PendingCard.tsx
 create mode 100644 packages/client/ui-conversation/src/client/chat/StatsLine.module.css
 create mode 100644 packages/client/ui-conversation/src/client/chat/StatsLine.tsx
 create mode 100644 packages/client/ui-conversation/src/client/chat/ToolRow.module.css
 create mode 100644 packages/client/ui-conversation/src/client/chat/ToolRow.tsx
 create mode 100644 packages/client/ui-conversation/src/client/chat/ToolViewOutlet.tsx
 create mode 100644 packages/client/ui-conversation/src/client/chat/chat-flow.ts
 create mode 100644 packages/client/ui-conversation/src/client/chat/register.ts
 create mode 100644 packages/client/ui-conversation/src/client/contract/slots.ts
 create mode 100644 packages/client/ui-conversation/src/client/contract/tool-call-model.ts
 create mode 100644 packages/client/ui-conversation/src/client/contract/toolview.ts
 create mode 100644 packages/client/ui-conversation/src/client/contract/views.ts
 create mode 100644 packages/client/ui-conversation/src/client/index.ts
 create mode 100644 packages/client/ui-conversation/src/client/service.ts
 create mode 100644 packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css
 create mode 100644 packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
 create mode 100644 packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css
 create mode 100644 packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
 create mode 100644 packages/client/ui-conversation/src/client/skeleton/EmptyState.module.css
 create mode 100644 packages/client/ui-conversation/src/client/skeleton/EmptyState.tsx
 create mode 100644 packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
 create mode 100644 packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
 create mode 100644 packages/client/ui-conversation/src/client/toolviews/bash-sample.module.css
 create mode 100644 packages/client/ui-conversation/src/client/toolviews/bash-sample.tsx
 create mode 100644 packages/client/ui-conversation/src/client/toolviews/registry.ts
 create mode 100644 packages/client/ui-conversation/src/css-modules.d.ts
 create mode 100644 packages/client/ui-conversation/src/index.ts
 create mode 100644 packages/client/ui-conversation/src/invariant.ts
 create mode 100644 packages/client/ui-conversation/tests/apply-inject.spec.tsx
 create mode 100644 packages/client/ui-conversation/tests/chat-apply.spec.tsx
 create mode 100644 packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
 create mode 100644 packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx
 create mode 100644 packages/client/ui-conversation/tests/chat-tool-row.spec.tsx
 create mode 100644 packages/client/ui-conversation/tests/chat-view.spec.tsx
 create mode 100644 packages/client/ui-conversation/tests/coverage-tails.spec.tsx
 create mode 100644 packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
 create mode 100644 packages/client/ui-conversation/tests/input-bar.spec.tsx
 create mode 100644 packages/client/ui-conversation/tests/selection-survival.spec.ts
 create mode 100644 packages/client/ui-conversation/tests/service-orchestration.spec.ts
 create mode 100644 packages/client/ui-conversation/tests/service-stores.spec.ts
 create mode 100644 packages/client/ui-conversation/tests/skeleton-branches.spec.tsx
 create mode 100644 packages/client/ui-conversation/tests/skeleton.spec.tsx
 create mode 100644 packages/client/ui-conversation/tests/toolview-entry-types.spec.ts
 create mode 100644 packages/client/ui-conversation/tests/toolview-registry.spec.ts
 create mode 100644 packages/client/ui-conversation/tests/toolviews-type-chain.spec.ts
 create mode 100644 packages/client/ui-conversation/tests/views-type-chain.spec.tsx
 create mode 100644 packages/client/ui-conversation/tsconfig.json
 create mode 100644 packages/client/ui-conversation/tsdown.config.ts
 create mode 100644 packages/client/ui-layout/README.md
 create mode 100644 packages/client/ui-layout/package.json
 create mode 100644 packages/client/ui-layout/src/client/AppFrame.module.css
 create mode 100644 packages/client/ui-layout/src/client/AppFrame.tsx
 create mode 100644 packages/client/ui-layout/src/client/columns.ts
 create mode 100644 packages/client/ui-layout/src/client/index.ts
 create mode 100644 packages/client/ui-layout/src/client/service.ts
 create mode 100644 packages/client/ui-layout/src/css-modules.d.ts
 create mode 100644 packages/client/ui-layout/src/index.ts
 create mode 100644 packages/client/ui-layout/src/invariant.ts
 create mode 100644 packages/client/ui-layout/tests/app-frame.spec.tsx
 create mode 100644 packages/client/ui-layout/tests/apply.spec.ts
 create mode 100644 packages/client/ui-layout/tests/columns.spec.ts
 create mode 100644 packages/client/ui-layout/tests/service.spec.ts
 create mode 100644 packages/client/ui-layout/tsconfig.json
 create mode 100644 packages/client/ui-layout/tsdown.config.ts
 create mode 100644 packages/client/ui-primitives/README.md
 create mode 100644 packages/client/ui-primitives/package.json
 create mode 100644 packages/client/ui-primitives/src/Button.module.css
 create mode 100644 packages/client/ui-primitives/src/Button.tsx
 create mode 100644 packages/client/ui-primitives/src/ConnectionBanner.module.css
 create mode 100644 packages/client/ui-primitives/src/ConnectionBanner.tsx
 create mode 100644 packages/client/ui-primitives/src/FishLogo.tsx
 create mode 100644 packages/client/ui-primitives/src/Input.module.css
 create mode 100644 packages/client/ui-primitives/src/Input.tsx
 create mode 100644 packages/client/ui-primitives/src/Menu.module.css
 create mode 100644 packages/client/ui-primitives/src/Menu.tsx
 create mode 100644 packages/client/ui-primitives/src/Pill.module.css
 create mode 100644 packages/client/ui-primitives/src/Pill.tsx
 create mode 100644 packages/client/ui-primitives/src/StateDot.module.css
 create mode 100644 packages/client/ui-primitives/src/StateDot.tsx
 create mode 100644 packages/client/ui-primitives/src/css-modules.d.ts
 create mode 100644 packages/client/ui-primitives/src/icons/index.tsx
 create mode 100644 packages/client/ui-primitives/src/icons/props.ts
 create mode 100644 packages/client/ui-primitives/src/index.ts
 create mode 100644 packages/client/ui-primitives/src/invariant.ts
 create mode 100644 packages/client/ui-primitives/src/markdown/JsonBlock.module.css
 create mode 100644 packages/client/ui-primitives/src/markdown/JsonBlock.tsx
 create mode 100644 packages/client/ui-primitives/src/markdown/MessageText.module.css
 create mode 100644 packages/client/ui-primitives/src/markdown/MessageText.tsx
 create mode 100644 packages/client/ui-primitives/tests/atoms.spec.tsx
 create mode 100644 packages/client/ui-primitives/tests/icons.spec.tsx
 create mode 100644 packages/client/ui-primitives/tests/invariant.spec.ts
 create mode 100644 packages/client/ui-primitives/tests/markdown.spec.tsx
 create mode 100644 packages/client/ui-primitives/tests/state-dot.spec.tsx
 create mode 100644 packages/client/ui-primitives/tsconfig.json
 create mode 100644 packages/client/ui-primitives/tsdown.config.ts
 create mode 100644 packages/client/ui-sidebar/README.md
 create mode 100644 packages/client/ui-sidebar/package.json
 create mode 100644 packages/client/ui-sidebar/src/client/Rows.module.css
 create mode 100644 packages/client/ui-sidebar/src/client/Rows.tsx
 create mode 100644 packages/client/ui-sidebar/src/client/SidebarRoot.module.css
 create mode 100644 packages/client/ui-sidebar/src/client/SidebarRoot.tsx
 create mode 100644 packages/client/ui-sidebar/src/client/contract/slots.ts
 create mode 100644 packages/client/ui-sidebar/src/client/index.ts
 create mode 100644 packages/client/ui-sidebar/src/client/store.ts
 create mode 100644 packages/client/ui-sidebar/src/client/tree.ts
 create mode 100644 packages/client/ui-sidebar/src/css-modules.d.ts
 create mode 100644 packages/client/ui-sidebar/src/index.ts
 create mode 100644 packages/client/ui-sidebar/src/invariant.ts
 create mode 100644 packages/client/ui-sidebar/tests/apply.spec.tsx
 create mode 100644 packages/client/ui-sidebar/tests/invariant.spec.ts
 create mode 100644 packages/client/ui-sidebar/tests/sidebar-root.spec.tsx
 create mode 100644 packages/client/ui-sidebar/tests/store.spec.ts
 create mode 100644 packages/client/ui-sidebar/tests/tree.spec.ts
 create mode 100644 packages/client/ui-sidebar/tsconfig.json
 create mode 100644 packages/client/ui-sidebar/tsdown.config.ts
 create mode 100644 packages/client/ui-slots/README.md
 create mode 100644 packages/client/ui-slots/package.json
 create mode 100644 packages/client/ui-slots/src/index.ts
 create mode 100644 packages/client/ui-slots/src/invariant.ts
 create mode 100644 packages/client/ui-slots/tests/core.spec.ts
 create mode 100644 packages/client/ui-slots/tests/invariant.spec.ts
 create mode 100644 packages/client/ui-slots/tests/surface.spec.ts
 create mode 100644 packages/client/ui-slots/tests/type-chain.spec.tsx
 create mode 100644 packages/client/ui-slots/tsconfig.json
 create mode 100644 packages/client/ui-theme/README.md
 create mode 100644 packages/client/ui-theme/package.json
 create mode 100644 packages/client/ui-theme/src/client/index.ts
 create mode 100644 packages/client/ui-theme/src/index.ts
 create mode 100644 packages/client/ui-theme/src/invariant.ts
 create mode 100644 packages/client/ui-theme/src/styles/base.css
 create mode 100644 packages/client/ui-theme/src/styles/design-platform.css
 create mode 100644 packages/client/ui-theme/src/styles/gradient-shadow-text.css
 create mode 100644 packages/client/ui-theme/tests/invariant.spec.ts
 create mode 100644 packages/client/ui-theme/tests/theme.spec.ts
 create mode 100644 packages/client/ui-theme/tsconfig.json
 create mode 100644 packages/client/ui-theme/tsdown.config.ts
 create mode 100644 packages/client/ui-trajectory/README.md
 create mode 100644 packages/client/ui-trajectory/package.json
 create mode 100644 packages/client/ui-trajectory/src/client/TrajectoryStatsHeader.module.css
 create mode 100644 packages/client/ui-trajectory/src/client/TrajectoryStatsHeader.tsx
 create mode 100644 packages/client/ui-trajectory/src/client/TrajectoryView.tsx
 create mode 100644 packages/client/ui-trajectory/src/client/WaterfallView.tsx
 create mode 100644 packages/client/ui-trajectory/src/client/index.ts
 create mode 100644 packages/client/ui-trajectory/src/client/spans.ts
 create mode 100644 packages/client/ui-trajectory/src/client/views.module.css
 create mode 100644 packages/client/ui-trajectory/src/css-modules.d.ts
 create mode 100644 packages/client/ui-trajectory/src/index.ts
 create mode 100644 packages/client/ui-trajectory/src/invariant.ts
 create mode 100644 packages/client/ui-trajectory/tests/client-bundle.spec.ts
 create mode 100644 packages/client/ui-trajectory/tests/views.spec.tsx
 create mode 100644 packages/client/ui-trajectory/tsconfig.json
 create mode 100644 packages/client/ui-trajectory/tsdown.config.ts
 create mode 100644 packages/client/web-react/README.md
 create mode 100644 packages/client/web-react/package.json
 create mode 100644 packages/client/web-react/src/bind.ts
 create mode 100644 packages/client/web-react/src/env.d.ts
 create mode 100644 packages/client/web-react/src/index.ts
 create mode 100644 packages/client/web-react/src/invariant.ts
 create mode 100644 packages/client/web-react/src/scoped-slots.tsx
 create mode 100644 packages/client/web-react/src/session-provider.tsx
 create mode 100644 packages/client/web-react/src/store/index.ts
 create mode 100644 packages/client/web-react/src/use-invoke.ts
 create mode 100644 packages/client/web-react/src/use-sync-external-store.d.ts
 create mode 100644 packages/client/web-react/tests/bind.spec.tsx
 create mode 100644 packages/client/web-react/tests/scoped-slots-real-core.spec.tsx
 create mode 100644 packages/client/web-react/tests/scoped-slots.spec.tsx
 create mode 100644 packages/client/web-react/tests/session-provider.spec.tsx
 create mode 100644 packages/client/web-react/tests/store.spec.ts
 create mode 100644 packages/client/web-react/tests/use-invoke.spec.tsx
 create mode 100644 packages/client/web-react/tsconfig.json
 create mode 100644 packages/client/web-react/tsdown.config.ts
 create mode 100644 packages/client/web/README.md
 create mode 100644 packages/client/web/package.json
 create mode 100644 packages/client/web/src/AppRoot.module.css
 create mode 100644 packages/client/web/src/AppRoot.tsx
 create mode 100644 packages/client/web/src/app.tsx
 create mode 100644 packages/client/web/src/base.css
 create mode 100644 packages/client/web/src/boot.tsx
 create mode 100644 packages/client/web/src/css-modules.d.ts
 create mode 100644 packages/client/web/src/index.ts
 create mode 100644 packages/client/web/src/invariant.ts
 create mode 100644 packages/client/web/src/seed.ts
 create mode 100644 packages/client/web/tests/app-root.spec.tsx
 create mode 100644 packages/client/web/tests/boot.spec.tsx
 create mode 100644 packages/client/web/tsconfig.json
 create mode 100644 packages/client/web/tsdown.config.ts
 create mode 100644 packages/host/apiproxy/README.md
 create mode 100644 packages/host/apiproxy/package.json
 create mode 100644 packages/host/apiproxy/src/api/approvals.schema.ts
 create mode 100644 packages/host/apiproxy/src/api/approvals.ts
 create mode 100644 packages/host/apiproxy/src/api/events.schema.ts
 create mode 100644 packages/host/apiproxy/src/api/events.ts
 create mode 100644 packages/host/apiproxy/src/api/host.schema.ts
 create mode 100644 packages/host/apiproxy/src/api/host.ts
 create mode 100644 packages/host/apiproxy/src/api/index.ts
 create mode 100644 packages/host/apiproxy/src/api/questions.schema.ts
 create mode 100644 packages/host/apiproxy/src/api/questions.ts
 create mode 100644 packages/host/apiproxy/src/api/rpc-map.ts
 create mode 100644 packages/host/apiproxy/src/api/rpc.schema.ts
 create mode 100644 packages/host/apiproxy/src/api/rpc.ts
 create mode 100644 packages/host/apiproxy/src/api/sessions.schema.ts
 create mode 100644 packages/host/apiproxy/src/api/sessions.ts
 create mode 100644 packages/host/apiproxy/src/fetch/client.ts
 create mode 100644 packages/host/apiproxy/src/fetch/handler.ts
 create mode 100644 packages/host/apiproxy/src/index.ts
 create mode 100644 packages/host/apiproxy/src/invariant.ts
 create mode 100644 packages/host/apiproxy/tests/client-handler.spec.ts
 create mode 100644 packages/host/apiproxy/tests/fetch-carrier.spec.ts
 create mode 100644 packages/host/apiproxy/tests/rpc-schemas.spec.ts
 create mode 100644 packages/host/apiproxy/tsconfig.json
 create mode 100644 packages/host/runtime/README.md
 create mode 100644 packages/host/runtime/package.json
 create mode 100644 packages/host/runtime/src/api-proxy.ts
 create mode 100644 packages/host/runtime/src/boot.ts
 create mode 100644 packages/host/runtime/src/index.ts
 create mode 100644 packages/host/runtime/src/invariant.ts
 create mode 100644 packages/host/runtime/src/start.ts
 create mode 100644 packages/host/runtime/src/web-plugins.ts
 create mode 100644 packages/host/runtime/tests/api-proxy-cold.spec.ts
 create mode 100644 packages/host/runtime/tests/api-proxy-view.spec.ts
 create mode 100644 packages/host/runtime/tests/host-runtime.spec.ts
 create mode 100644 packages/host/runtime/tests/web-plugins.e2e.ts
 create mode 100644 packages/host/runtime/tests/web-plugins.spec.ts
 create mode 100644 packages/host/runtime/tsconfig.json
 create mode 100644 packages/host/webserver/README.md
 create mode 100644 packages/host/webserver/package.json
 create mode 100644 packages/host/webserver/src/index.ts
 create mode 100644 packages/host/webserver/src/invariant.ts
 create mode 100644 packages/host/webserver/src/static.ts
 create mode 100644 packages/host/webserver/src/web-plugins.ts
 create mode 100644 packages/host/webserver/tests/invariant.spec.ts
 create mode 100644 packages/host/webserver/tests/web-plugins.spec.ts
 create mode 100644 packages/host/webserver/tests/webserver.spec.ts
 create mode 100644 packages/host/webserver/tsconfig.json
 create mode 100644 packages/ui/user-approval/src/types.ts
 create mode 100644 packages/ui/user-approval/tsdown.config.ts
 create mode 100644 packages/ui/user-interaction/src/types.ts
 create mode 100644 scripts/client-bundle-purity.spec.ts
 create mode 100644 scripts/verify-client-domain-graph.ts
 create mode 100644 tsconfig.client.json
 create mode 100644 tsconfig.vitest.json
 create mode 100644 vitest.web.config.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
new file mode 100644
index 0000000000..d3e5608c22
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-19-gui-layering-and-rpc-protocol.md: ebe21a6060ec69ba9807ab9fbf9906ae24b07823
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: 0c256b60ce44a8e16ec6edfba146c776c4ae2129
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
new file mode 100644
index 0000000000..ebe21a6060
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
@@ -0,0 +1,253 @@
+# Agent Note: GUI layering and the RPC protocol — host/client layering by capability provider, the four-quadrant message model, and the fetch carrier
+
+Status: implemented
+
+English | [中文](2026-07-19-gui-layering-and-rpc-protocol.zh.md)
+
+> Division of labor: this document = the layering model + the channel-independent RPC protocol; the protocol's Web implementation (HTTP+SSE) is in the [web client architecture RFC](2026-07-19-gui-web-client-architecture.md).
+
+## Problem
+
+We need a UI integration layer. Beyond the existing ACP/stdio baseline, more product UI shapes are coming — Web (server), Electron, and others. We call these shapes Clients, uniformly, and want the following capabilities:
+
+- One `dsh` process supporting both `dsh web` (serve) and `dsh -p` (headless) — one process, two modes (a design reservation)
+- Launching inside Electron with the same Web technology shape as `dsh web`
+
+That demands a stable layered responsibility model in the engineering codebase, so future client shapes plug in cleanly.
+
+At the same time the physical channels differ per consumer (HTTP/SSE, in-process direct calls, IPC later), so we also need a channel-independent message model and a single contract source of truth — "adding a method" and "swapping a carrier" must not entangle each other, and every message on the wire must be type-validatable, observable, and reconcilable.
+
+## Decision
+
+### Layering
+
+Directories layer as follows:
+
+- `packages/host/*`: packages provide host-side capability only (representing the Node.js engineering core built on the existing harness plugin system), and additionally
+    - the unified backend protocol (fetch, HTTP, streaming interfaces…) — definitions and support, see the "Message protocol" sections below
+- `packages/client/*`: packages provide client-side capability only; every package stays single-sided. Two kinds live here:
+    - **Pure libraries** (`ui-slots`, `web-react`, `ui-primitives`): ordinary root-index packages, statically bundled into the shell and seeded into the browser plugin loader's module table.
+    - **dshClient plugin packages** (`connection`, `runtime`, `ui-theme`, `i18n`, `ui-layout`, `ui-sidebar`, `ui-conversation`, `ui-trajectory`): dual-entry — the root index is the node half (an empty `apply`, existing so the host Loader governs lifecycle and the web plugin registry discovers the package.json `dshClient` declaration); the entire implementation and its types live under `src/client/`, shipped as the `./client` subpath (a tsdown closure-factory bundle), and cross-package consumption imports the `/client` form. `runtime` additionally exports `./loader` (the shell-held browser bundle loader — a loader cannot load itself).
+- `apps/` holds the externally exported application shapes, assembled from Client / Host mixtures.
+    - `apps/web` (`dsh-frontend`) is the vite application: a thin `main.ts` over the shell surface exported by `dsh-client-web`.
+    - `apps/cli` (`@deepseek-ai/dsh`) dispatches shapes: `dsh web` = startHost + webserver + the built `dsh-frontend` dist; `dsh -p` = headless in-process calls, zero HTTP.
+    - A future Electron shape reuses the same web client packages over an IPC fetch carrier.
+
+```
+apps/*  (application shapes: apps/web = vite app, apps/cli = bin dispatch)
+  │ consume
+  ▼
+packages/host/*                      packages/client/*
+  apiproxy   front layer: protocol     pure libs: ui-slots / web-react / ui-primitives
+  runtime    assembly / host entity    dshClient plugins ×8 (node half = empty apply,
+  webserver  web-shape HTTP carriage                        client half = src/client/)
+  │ ctx.plugin(...)                      ▲ import only apiproxy's /api /client subpaths
+  ▼                                      │ (type-only + the client base class)
+harness core packages ──────────────────┘ (types reach the browser via import type)
+```
+
+Direction discipline (every rule auditable from package deps):
+
+- `runtime → apiproxy` is one-way; apiproxy depends only on type definitions.
+- Client-side packages **never import** host-side package runtime (they consume only the two browser-safe subpaths `/api` and `/client`).
+- `webserver` does not depend on `runtime`: it provides a `{ fetch }`-shaped implementation — "webserver ← runtime" is a runtime injection relationship, not a package dependency.
+- Cross-package client imports use the `/client` subpath for plugin packages (a bare package name would inline a second runtime instance into a browser bundle; the tsdown purity gate rewrites or rejects it).
+
+TypeScript checks in **two aggregate programs** (`tsconfig.json` = host side + tests, excluding `packages/client`; `tsconfig.client.json` = client packages and their tests): both sides merge the cordis `Context` interface under the same keys (`sessions`, `loader`) with different services, so one program would see both declaration merges and report a collision. Shared leaves (session/llm/tools/apiproxy…) build once and are referenced by both programs.
+
+On the protocol side: TS interfaces (`packages/host/apiproxy/src/api/`, zero Node dependencies, browser-importable); wire messages unify under a **bidirectional model** — each logical message is shaped by "who initiates × request/response" (two axes, four cells, called the four quadrants below), decoupled from the physical channel; clients all inherit `AbstractApiClient` (protocol invariants live entirely in the base class, platform differences are just the `doFetch` transport aspect).
+
+#### Layer roles
+
+| Layer | Package | Responsibility | Key discipline |
+|---|---|---|---|
+| Front layer | `dsh-host-apiproxy` | TS/zod definitions (api/) + the fetch abstraction (fetch/: handler + client base class) | Keep it simple — every consumer needs it; importable from Node and browser alike; protocol content in the "Message protocol" sections below; clients must not bypass api through ctx |
+| Assembly layer | `dsh-host-runtime` | Plugin composition + ApiProxy integration + the web UI plugin mount (in-memory Loader tree over the eight dshClient packages); home of host-level configuration (defaults/persistenceRoot, future user profile) | Which plugins mount and with what defaults is decided only here; shells must not alter the assembly |
+| Carrier layer | `dsh-host-webserver` | Web-shape HTTP: static serving + `/api/*`→handler forwarding + SSE write-out + close semantics; plugin bundle endpoint + `__DSH_BOOT__` manifest injection (fed by the web plugin registry) | Web (browser access) only; zero workspace dependencies (the registry arrives by structural injection); Electron does not reuse it |
+| Client libraries | `dsh-client-ui-slots` / `dsh-client-web-react` / `dsh-client-ui-primitives` | Slot registry core / ctx↔React glue / pure React atoms | Zero cordis runtime dependency in components; seeded into the loader module table by the shell |
+| Client plugins | `dsh-client-connection` / `dsh-client-runtime` / `dsh-client-ui-theme` / `dsh-client-i18n` / `dsh-client-ui-layout` / `dsh-client-ui-sidebar` / `dsh-client-ui-conversation` / `dsh-client-ui-trajectory` | Browser-side cordis plugin tree (wire consumer, core services, theme, i18n, layout, sidebar, conversation, trajectory) — see the web client architecture RFC | Dual entry (node half = empty apply; implementation in `src/client/`); the consumption face goes exclusively through ApiProxy |
+| Application shape | `@deepseek-ai/dsh` (apps/cli) + `dsh-frontend` (apps/web, the vite application) | Coarse bin dispatch + one assembly module per shape (web.ts / headless.ts); the vite app is a thin main over the `dsh-client-web` shell surface | Shapes dynamic-import so they never load each other; workspace knowledge like dist location stays in the app |
+
+#### Naming rule
+
+Packages under `packages/host/*` and `packages/client/*` **must carry the directory-group prefix in the package name**: host/runtime → `dsh-host-runtime`, client/runtime → `dsh-client-runtime`. The directory name does not repeat the group prefix (host/ already expresses it). The package-name tail therefore ≠ the directory name, so the `dsh-*` wildcard in tsconfig.base.json (which resolves by directory name) misses them — **each package in these two groups needs an explicit paths entry**, including separate entries for the plugin packages' `/client` (and runtime's `/loader`) subpaths so source-level resolution matches the exports map.
+
+#### How to integrate a new shape (operational checklist)
+
+1. **Pick a fetch impersonation**: browser same-origin HTTP / in-process `host.handler.fetch` injection / your own transport-aspect subclass (e.g. future Electron IPC, see the "Subclass table" below).
+2. **Write an assembly module under `apps/`**: `startHost()` + a client subclass + the shape's private signal/print/exit semantics; a mixture never becomes a package — assembly is written in the app.
+3. **Import `dsh-host-webserver` only if you need HTTP carriage**, otherwise zero ports.
+
+The two existing shapes are the template: `apps/cli/src/web.ts` (startHost + dist location + startWebServer + signal shutdown) and `headless.ts` (startHost + InProcessApiClient isomorphic direct calls, zero HTTP zero ports). ACP-class protocol bridges do not follow this checklist: they expose core to the external ecosystem, mount via `ctx.plugin(front-door plugin)` directly, and wear no fetch.
+
+## Message protocol
+
+The sections from here down are the protocol body carried by the front layer (`dsh-host-apiproxy`). The wire has exactly four message kinds (the four quadrants) — the Web carriage in the right column is only an example; swapping the carrier (in-process/IPC) leaves the quadrants unchanged:
+
+```
+                 client 发起                      server 发起
+  request   ① ClientRequest                 ③ ServerRequest
+            （POST /api/<method> body）      （SSE 帧：session 事件、审批/问答 requested）
+  response  ② ServerResponse                ④ ClientResponse
+            （该 POST 的 HTTP 应答体）        （POST /api/respond body，回填 ③ 的 rpcId）
+```
+
+### Wire full forms: a four-member named discriminated union (`api/rpc.ts`)
+
+| Type | Discriminant tag | Fields | rpcId ownership | Web carriage |
+|---|---|---|---|---|
+| `ClientRequest` | `'client-request'` | `rpcId` `method` `payload` | client mints | `POST /api/<method>` body |
+| `ServerResponse` | `'server-response'` | `rpcId` `result` | echoes ① | that POST's response body (always HTTP 200) |
+| `ServerRequest` | `'server-request'` | `rpcId` `method` `payload` | server mints | SSE `data:` line |
+| `ClientResponse` | `'client-response'` | `rpcId` `result` | echoes ③ | `POST /api/respond` body |
+
+`RpcMessage = ClientRequest | ServerResponse | ServerRequest | ClientResponse`, narrowed via `switch (message.type)`.
+
+**rpcId discipline** (`RpcId` is a branded string with constructor `RpcId()`):
+
+- Whoever initiates mints; a response always echoes the corresponding request's rpcId and **never mints a new id**.
+- server-requests split into two kinds, distinguished statically by `method` (= the frame type), with **no third kind**: answerable frames (`approval/requested`, `question/requested`) carry a stable logical request id (minted once on acceptance, reused verbatim on baseline replay, echoed by the client's answer); pure-push frames (`session/event` etc.) carry an rpcId identifying that one push (freshly minted each time).
+- Business code never mints: unary minting funnels into the client base class `callUnary`, frame minting funnels into the host side.
+
+### Signature narrow forms and carrier completion
+
+Domain interface signatures perceive only the narrow forms: `RpcRequest<P> = { rpcId, payload }`, `RpcResponse<T> = { rpcId, result: RpcResult<T> }`. The carrier layer completes narrow forms into full forms (adding the `type` tag and `method`); direction is never inferred from the channel. `RpcResult<T> = { ok: true; value } | { ok: false; error: RpcError }` — methods do not throw business errors.
+
+### RpcReceipt: the carrier receipt
+
+The HTTP response body of a `ClientResponse` is `RpcReceipt = { accepted: true } | { accepted: false; reason: 'not-pending' | 'bad-response' }` — a carrier-layer receipt, **not** an RpcMessage (a response has no response); late/duplicate answers get `not-pending`, and the logical convergence surface is the `*/resolved` frames.
+
+## The type system: signatures are the source of truth
+
+### RpcMethodMap and derived generics (`api/rpc-map.ts`)
+
+Method parameter/return structures **live only in the interface method signatures**; the map registers the methods themselves; every other position (handler, client, store, tests) references the derived generics — copying literals or introducing flat named types is banned:
+
+```ts ignore-check
+export interface RpcMethodMap {
+  'session.list': SessionsApi['list']        // map key 即 wire 路径段
+  // …其余方法同形登记，全集见 api/rpc-map.ts
+}
+// 派生泛型（穿透窄形取业务类型；实际声明带 K extends keyof RpcMethodMap 约束）
+export type RequestPayload<K> = Parameters<RpcMethodMap[K]>[0]['payload']
+export type ResponseValue<K> =
+  Awaited<ReturnType<RpcMethodMap[K]>> extends RpcResponse<infer T> ? T : never
+```
+
+Stream methods (`events.mux`/`events.host`) stay out of the map (not unary); `respond` stays out of the map (it is a client-response, not a method call).
+
+### The error model (`RpcErrorDetailsMap`)
+
+One example row of an error code:
+
+| code | details | when |
+|---|---|---|
+| `bad-request` | `{ issues: ZodIssue[] }` | wire/payload zod validation failed |
+
+The full code set is `RpcErrorDetailsMap` in `api/rpc.ts`. `RpcError` is the distributive union expanded from the map: `code` discriminates, `details` narrows automatically after a `switch`; **details is required** — a new code = one map row + one error-schema branch, and omission is a compile error. Transport failures (network down, host not up) are thrown by the carrier as exceptions; the two layers never mix.
+
+### Bidirectional zod validation and anchoring
+
+- **Two-level parse**: the full-form schema once (type/rpcId/method structure + the handler checking path==method) → the business payload dispatched by method/frame type for a second parse; rejection = `bad-request`.
+- **Anchoring**: schemas uniformly `satisfies z.ZodType<Wire<T>>` (`api/rpc.schema.ts`). `Wire<T>` is a deep "| undefined" widening — the repo enables `exactOptionalPropertyTypes` while zod `.optional()` outputs `T | undefined`, so anchoring the original type is unusable across the board; on the JSON wire, absence and undefined are indistinguishable, so the widening loses no validation semantics. Passthrough wide branches (`SessionEvent`/`ContentBlock`/frame unions/`RpcError`) and brand-id schemas use explicit casts with comments.
+- Brand casts have one point each: every schema file funnels its id cast into one place (`rpcIdSchema` is the only cast point in rpc.schema.ts).
+
+## The contract face (ApiProxy)
+
+The root interface is `ApiProxy = { sessions, host, events, respond }` (`api/index.ts`). A new client-request domain = one new file pair (`<domain>.ts` + `<domain>.schema.ts`) + one root-interface field + one map row.
+
+### The unary method table
+
+One example row (the table structure is the reading key):
+
+| method key | request payload | return value | semantics |
+|---|---|---|---|
+| `session.list` | `{ cursor?: string }` (cursor is a reserved seat, unimplemented) | `{ items: SessionSummary[] }` | persisted sessions, updatedAt descending; v1 builds no index |
+
+The remaining methods (`session.create`/`session.history`/`session.prompt`/`session.cancel`/`host.describe`) are not re-copied here — signatures are the source of truth; see `api/sessions.ts`, `api/host.ts`, and `RpcMethodMap`.
+
+### Frames (server→client, named unions)
+
+Two SSE streams: the mux stream (`GET /api/events.mux`, all-session aggregate) and the host stream (`GET /api/events.host`, host-level events). One example frame row:
+
+| frame type | payload | when |
+|---|---|---|
+| `session/event` | `{ sessionId; event: SessionEvent }` | core passthrough: core events pass verbatim, `assistant/chunk` IS the token stream, no separate delta frame |
+
+The remaining frame types are not re-copied here; the full unions are `MuxFrame`/`HostFrame` in `api/events.ts`. Three semantic points to know: `session/subscribed` carries lastSeq for history seam-race detection; the `approval/question` requested frames are answerable (stable rpcId) and the resolved frames are the convergence surface; `host/agent-error` is the only outlet for live failures with no turn position.
+
+**Passthrough discipline**: events/messages/content blocks on the wire ARE the core types (`SessionEvent`/`ContentBlock`) — no second DTO set; types reach the browser through the `import type` dependency chain. `SessionEventMap` is merge-extensible: the client applies its documented default (ignore) to unknown types, and the event schema keeps a "valid envelope + unknown type" branch — the envelope stays strict; this is not field-level passthrough.
+
+### Session semantics (impl-side commitments)
+
+- **History = event replay**: one fold (client side); history pagination and live increments share one code path; the server maintains no second materialized-snapshot system. History **page boundaries align to message boundaries** (never cut mid-message; chunks group with their finalized message), and the tail page includes the in-flight partial's chunks.
+- **Prompt correlation**: the prompt's rpcId rides MessageSource (`'user-rpc'`) into the `user/message` event; the client uses it to promote the optimistic echo.
+- **Reconnect = rebuild**: no resume cursor (`mux`'s `since` signature is a reserved seat, ignored if passed); on disconnect reopen the stream + refetch history; compare `subscribed.lastSeq` with the history tail seq and backfill once if there is a seam.
+- **Cold sessions resume implicitly**: when `history`/`prompt` hits an unattached session the impl auto-resumes, deduplicating concurrent triggers with an in-flight table; attachment status is not exposed to clients (`running` already covers it).
+- **Approvals/questions**: the requested frame mints a stable rpcId on acceptance; first answer wins, and the host's in-memory pending table (keyed by rpcId) is the only referee; after a mux reopen, still-pending requested frames replay after the subscribed frame (rpcId reused verbatim — refresh recovery). The audit events `approval/asked`/`decided` continue through the durable log — frames = the live control plane, events = the durable audit. **Status**: the contract and frame types are shipped; the host-side pending table/wire answerer is unimplemented (`respond` in `api-proxy.ts` is a stub, always `not-pending`); PendingCard v1 is display-only.
+- **No protocol version**: client and host release bound together; `host.describe` has no protocolVersion field; introduce one when an independently released client appears.
+- **Reserved-seam discipline**: the map holds only implemented methods; an unknown method fails loud at envelope parse (`bad-request`) — no not-implemented fallback code. The reservation list (implementing = copy the signature into the domain interface + add the map row + add the schema pair): `session.fork`, `prompt.mode` gaining `'inject'`, `task.list`, `host.listModels`, describe gaining `hostInstanceId`.
+
+## The client carrier: the AbstractApiClient class family (`fetch/client.ts`)
+
+**Protocol invariants live in the base class; platform differences are two aspects**: the abstract method `doFetch(url, init)` (transport) + the overridable `onEnvelope` (observation).
+
+### IApiClient: the caller view
+
+The same domain tree as `ApiProxy`, but unary methods **take the business payload directly** — the carrier mints the rpcId and wraps the envelope; business code never mints, and code needing this call's rpcId reads it from the returned `RpcResponse` echo. `ApiProxy` is the narrow-form signature contract the impl side implements; `IApiClient` is the payload-direct view clients consume; `AbstractApiClient` bridges the two. Methods derive per key from `RpcMethodMap` — a map row addition updates them mechanically.
+
+### Protocol paths held by the base class
+
+| Path | Content |
+|---|---|
+| `callUnary` | mint → tap → POST full form → `serverResponseSchema` parse → **rpcId echo check** (mismatch throws) → tap → emit narrow form |
+| `readSse` | streaming fetch (not EventSource), `\n\n` framing, `data:` concatenation, ServerRequest full-form parse, tap, emit narrow `RpcRequest<frame>` |
+| `respond` | client-response passthrough (rpcId is an echo — never minted here); response body parsed by `rpcReceiptSchema` |
+| unary timeout | `AbortSignal.timeout` (default 30s, constructor-tunable); streams have no timeout (long-lived by nature) |
+| `resolveBase` | browser = same-origin origin; no-location environment (Node) = the `http://dsh.internal` fake authority |
+
+### The instance-level envelope observation aspect
+
+All four quadrant full forms pass through `onEnvelope`; the base implementation is an **instance-owned microtask-batched buffer** (frame storms must not disturb consumers per frame; module-level state would leak across instances/tests, hence instance-owned). Observers subscribe via `subscribeEnvelopes(listener)` (receiving whole batches as `readonly RpcMessage[]`, returning an unsubscribe function); a listener throw is isolated (observation must never bite the carrier). With no subscribers the buffering costs nothing. No shipped consumer subscribes today — the aspect is the designated seat for wire diagnostics (the retired RPC debug panel was its first consumer, and a future one plugs in without touching the carrier).
+
+### The subclass table (transport carriage)
+
+| Subclass | Package | doFetch | Purpose |
+|---|---|---|---|
+| `InProcessApiClient` | apiproxy itself | the injected `{ fetch }` handler | **The isomorphic point**: `new InProcessApiClient(toFetchHandler(api))` never touches the network yet runs the real wire serialization/zod/SSE framing — `dsh -p` headless is the protocol's second real consumer |
+| `WebApiClient` | dsh-client-connection | `globalThis.fetch` (same-origin `/api/*`) | the browser shape; HTTP+SSE carriage details in the web client architecture RFC |
+| `FixtureApiClient` | dsh-client-connection | unused (protocol-layer override) | serverless UI development (`?fixture`): overrides the `callUnary`/`openMux`/`openHost`/`respond` virtuals and is itself the fake server (frame rpcIds minted by it, semantics self-consistent) |
+| (future) IPC bridge subclass | apps/electron | IPC serialization round trip | swaps only doFetch; contract and base class unchanged |
+
+## How to extend (operational checklists)
+
+**Add a unary method (5 steps)**: ① add the method signature to the domain interface (parameters/return inline — this is the single source of truth); ② add one `RpcMethodMap` row; ③ add the request/value schema pair in `<domain>.schema.ts` (anchored `Wire<RequestPayload<'…'>>`); ④ add one handler `UNARY_ROUTES` row (the handler's Web carriage is in the web client architecture RFC); ⑤ implement in the impl (echo `request.rpcId`). On the client side, add the passthrough row to the `IApiClient`/`AbstractApiClient` domain method tables.
+
+**Add a frame type (3 steps)**: ① add a branch to the `MuxFrame`/`HostFrame` union (answerable frames must note the stable-rpcId semantics); ② add a frame-schema branch; ③ the consumers' fold/routing documented-default already covers unknown types — add an explicit branch as needed.
+
+**Add an error code (2 steps)**: ① add one `RpcErrorDetailsMap` row (details required); ② add one `rpcErrorSchema` discriminatedUnion branch.
+
+**Plug in a new carrier**: subclass `AbstractApiClient` implementing only `doFetch`; to intercept at the protocol layer (like the fixture), override the `callUnary`/`openMux`/`openHost` virtuals instead. Contract and base class stay unchanged.
+
+**Promote a reserved seam**: copy the reserved signature into the domain interface → add the map row → add the schema pair → add the UNARY_ROUTES row → implement.
+
+## Consequences
+
+Every client shape consumes one contract: adding a unary method is a five-step mechanical change radiating from a single signature, swapping a carrier touches only a `doFetch` subclass, and every wire message is zod-validated, observable through the envelope tap, and reconcilable by rpcId. The accepted costs: two groups of packages need explicit tsconfig paths entries, and the reserved seams (fork/inject/task.list/listModels/hostInstanceId) stay dormant until a real consumer arrives.
+
+## Alternatives considered
+
+| Rejected | One-line reason |
+|---|---|
+| Packaging by "product shape" (a web family, an electron family) | What shapes share is host/client capability, not the shape itself; capability-provider layering means a new shape needs zero new packages |
+| A package per mixture (e.g. a standalone headless package) | A mixture has exactly one consumer (its own app); packaging it is ownerless abstraction, while assembly in the app is readable and disposable |
+| Consuming clients connecting to ctx directly (skipping the apiproxy layer) | A second command plane bypasses the contract, losing wire validation/observability/multi-client consistency; ctx keeps exactly two formal uses — front doors and headless event subscription |
+| webserver depending on runtime (saving the handler injection) | Structural-typing injection keeps webserver reusable by sidecars/tests with zero workspace deps; a package dependency would drag assembly knowledge into the carrier layer |
+| Package names without the group prefix (continuing dsh-<tail>) | `dsh-runtime`/`dsh-web-ui` lose their belonging in the flat npm namespace; the cost is one explicit paths entry per package |
+| Reusing the in-repo JSON-RPC 2.0 (dsh-jsonrpc) | Numeric error codes degrade to a single fallback code, contracts get aligned by hand in two copies, and naming drifts without a convention |
+| A three-envelope model (Request/Response/Frame envelopes, signatures direction-blind) | rpcId correlation is logical-layer; frame and response direction semantics inferred from the channel break the moment the carrier changes |
+| Named Request/Response type pairs as the source of truth (map registering type pairs) | Flat named types are a second name for the same fact; signature inference makes adding a method a one-place change |
+| REST-style paths | The consumer is our own client with no third-party REST expectations; RPC mapping straight onto the method table is more mechanical |
+| A DTO layer (a second wire-only structure set) | Core types reach the browser type-only at zero cost; a DTO is a permanent two-way synchronization tax |
+| Cursor resumption (implementing mux since) | Reconnect = rebuild (opencode-style) covers all v1 needs; the signature keeps the seat, implementation waits for a real consumer |
+| A createApiClient factory function (the original implementation) | Platform differences (transport/observation) are inheritance aspects, not parameters; the class family lets the fixture substitute at the protocol layer instead of wrapping a fake envelope |
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
new file mode 100644
index 0000000000..0c256b60ce
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
@@ -0,0 +1,251 @@
+# RFC: GUI 分层与 RPC 协议——host/client 按能力支持方分层、四象限消息模型与 fetch 载体
+
+Status: implemented
+
+[English](2026-07-19-gui-layering-and-rpc-protocol.md) | 中文
+
+> 分工线：本篇 = 分层模型 + 通道无关的 RPC 协议；协议的 Web 实现（HTTP+SSE）见 [Web 客户端架构 RFC](2026-07-19-gui-web-client-architecture.md)。
+
+## Problem
+
+需要提供 UI 对接层，除已有 ACP/stdio基础版本外，还需要 Web(server) 、 Electron 、等其他产品 UI 形态。我们把这些形态统一称为 Client。希望有如下能力支持:
+- 以 `dsh` 进程，同时支持 `dsh web`(启动) 和 `dsh -p`(headless) ，一个进程两种模式（设计预留）
+- 以与 `dsh web` 同构的 Web 技术形态，在 Electron 中启动
+
+那么当前的工程代码需要稳定的分层职责模型，便于以后接入各类 client 形态。
+
+同时各消费端的物理通道不同（HTTP/SSE、进程内直调、将来 IPC），还需要一个通道无关的消息模型和单一契约事实源，让「加一个方法」「换一种载体」互不牵连，且 wire 上的每条消息可类型校验、可观测、可对账。
+
+## Decision
+
+### 分层
+
+目录按照如下分层:
+- `packages/host/*`: 包只提供 Host 侧能力（代表了以现在 Harness 实体插件系统为主体的 Node.js 代码核心工程），除此之外，还包含
+    - 统一后端协议（fetch、HTTP、流式接口等）定义和支持，见本篇「消息协议」起各节
+- `packages/client/*`：包只提供 Client 侧能力，每包单边不混。这里住两类包：
+    - **纯库**（`ui-slots`、`web-react`、`ui-primitives`）：普通根入口包，静态打包进壳，并播种进浏览器插件 loader 的模块表。
+    - **dshClient 插件包**（`connection`、`runtime`、`ui-theme`、`i18n`、`ui-layout`、`ui-sidebar`、`ui-conversation`、`ui-trajectory`）：双入口——根入口是 node 半边（空 `apply`，其存在是为了让 host Loader 管辖生命周期、让 web 插件注册表发现 package.json 的 `dshClient` 声明）；实现与类型全部住在 `src/client/` 下，经 `./client` 子路径发布（tsdown 闭包工厂 bundle），跨包消费一律 import `/client` 形式。`runtime` 额外导出 `./loader`（壳持有的浏览器 bundle loader——loader 加载不了自己）。
+- `apps/` 作为对外导出的应用形态入口，可以由 Client / Host 混合组装。
+    - `apps/web`（`dsh-frontend`）是 vite 应用：`dsh-client-web` 导出的壳表面之上的一层薄 `main.ts`。
+    - `apps/cli`（`@deepseek-ai/dsh`）做形态分发：`dsh web` = startHost + webserver + 构建出的 `dsh-frontend` dist；`dsh -p` = headless 进程内直调，零 HTTP。
+    - 将来的 Electron 形态经由 IPC fetch 载体复用同一套 web client 包。
+
+```
+apps/*  (application shapes: apps/web = vite app, apps/cli = bin dispatch)
+  │ consume
+  ▼
+packages/host/*                      packages/client/*
+  apiproxy   front layer: protocol     pure libs: ui-slots / web-react / ui-primitives
+  runtime    assembly / host entity    dshClient plugins ×8 (node half = empty apply,
+  webserver  web-shape HTTP carriage                        client half = src/client/)
+  │ ctx.plugin(...)                      ▲ import only apiproxy's /api /client subpaths
+  ▼                                      │ (type-only + the client base class)
+harness core packages ──────────────────┘ (types reach the browser via import type)
+```
+
+方向纪律（每条都由包 deps 可核）：
+
+- `runtime → apiproxy` 单向；apiproxy 仅依赖类型定义。
+- client 侧包**永不 import** host 侧包的运行时（只吃 `/api`、`/client` 两个浏览器安全子路径）。
+- `webserver` 不依赖 `runtime`：它提供 `{ fetch }` 特定实现 ——「webserver ← runtime」只是运行时注入关系，不是包依赖。
+- client 侧跨包 import 插件包一律走 `/client` 子路径（裸包名会把第二份运行时实例内联进浏览器 bundle；tsdown 纯度门禁会改写或拒收）。
+
+TypeScript 以**两个聚合 program** 检查（`tsconfig.json` = host 侧 + 测试，排除 `packages/client`；`tsconfig.client.json` = client 各包及其测试）：两侧在相同键（`sessions`、`loader`）下以不同服务合并 cordis `Context` 接口，单一 program 会同时看到两份声明合并而报冲突。共享叶子包（session/llm/tools/apiproxy 等）只构建一次，由两个 program 共同引用。
+
+协议侧：TS interface（`packages/host/apiproxy/src/api/`，零 Node 依赖，浏览器可 import）；wire 消息统一为**双向模型**——每条逻辑消息由「谁发起 × request/response」定形（两轴四格，后文称四象限），与物理通道解耦；客户端统一继承 `AbstractApiClient`（协议不变量全在基类，平台差异只是 `doFetch` 传输切面）。
+
+#### 分层角色
+
+| 层 | 包 | 职责 | 关键纪律 |
+|---|---|---|---|
+| 前置层 | `dsh-host-apiproxy` | TS/zod 定义 (api/)+ fetch 抽象 (fetch/：handler + 客户端基类) | 做简单、所有接入方都要；Node/浏览器皆可 import；协议内容见下文「消息协议」起各节；client 不得经 ctx 绕开 api |
+| 装配层 | `dsh-host-runtime` | 插件组合 + ApiProxy 集成 + web UI 插件挂载（覆盖八个 dshClient 包的内存 Loader 树）；host 级配置归属地（defaults/persistenceRoot，将来用户 profile） | 装什么插件、给什么默认值只在这里定；壳不得改装配 |
+| 承载层 | `dsh-host-webserver` | Web 形态 HTTP：静态服务 + `/api/*`→handler 转发 + SSE 写出 + close 语义；插件 bundle 端点 + `__DSH_BOOT__` manifest（元数据清单）注入（由 web 插件注册表供给） | Web（浏览器访问）专用；零 workspace 依赖（注册表经结构注入到达）；Electron 不复用它 |
+| client 库 | `dsh-client-ui-slots` / `dsh-client-web-react` / `dsh-client-ui-primitives` | slot 注册表核心 / ctx↔React 胶合 / 纯 React 原子组件 | 组件零 cordis 运行时依赖；由壳播种进 loader 模块表 |
+| client 插件 | `dsh-client-connection` / `dsh-client-runtime` / `dsh-client-ui-theme` / `dsh-client-i18n` / `dsh-client-ui-layout` / `dsh-client-ui-sidebar` / `dsh-client-ui-conversation` / `dsh-client-ui-trajectory` | 浏览器侧 cordis 插件树（wire 消费者、核心服务、主题、i18n、布局、侧栏、对话、轨迹）——见 Web 客户端架构 RFC | 双入口（node 半边=空 apply；实现在 `src/client/`）；消费面唯一经 ApiProxy |
+| 应用态 | `@deepseek-ai/dsh`（apps/cli）+ `dsh-frontend`（apps/web，vite 应用） | bin 粗分发 + 每形态一个拼装模块（web.ts / headless.ts）；vite 应用是 `dsh-client-web` 壳表面之上的薄 main | 形态间动态 import 互不加载；dist 定位等 workspace 知识留在 app |
+
+#### 命名规则
+
+`packages/host/*` 与 `packages/client/*` 下的包名**必须含目录组前缀**：host/runtime → `dsh-host-runtime`、client/runtime → `dsh-client-runtime`。目录名不重复组前缀（host/ 已表达）。因此包名尾段 ≠ 目录名，tsconfig.base.json 的 `dsh-*` 通配（按目录名解析）命不中——**这两组的每包需显式 paths 条目**，且插件包的 `/client`（以及 runtime 的 `/loader`）子路径要单列条目，使源码级解析与 exports map 一致。
+
+#### 怎么接入一个新形态（操作清单）
+
+1. **选 fetch 伪造方式**：浏览器同源 HTTP / 进程内 `host.handler.fetch` 注入 / 自写传输切面子类（如将来 Electron IPC，见下文「子类表」）。
+2. **在 `apps/` 下写拼装模块**：`startHost()` + 客户端子类 + 该形态私有的信号/打印/退出语义；混合体不建包，拼装写在 app 里。
+3. **需要 HTTP 承载才 import `dsh-host-webserver`**，否则零端口。
+
+现有两形态即模板：`apps/cli/src/web.ts`（startHost + dist 定位 + startWebServer + 信号停机）与 `headless.ts`（startHost + InProcessApiClient 同构直调，零 HTTP 零端口）。ACP 类协议桥不走本清单：它把 core 暴露给外部生态，直接 `ctx.plugin(前门插件)` 挂载、不套 fetch。
+
+## 消息协议
+
+以下各节是前置层（`dsh-host-apiproxy`）承载的协议本体。wire 上只有四种消息（四象限）——右列的 Web 承载只是示例，换载体（进程内/IPC）时四象限不变：
+
+```
+                 client 发起                      server 发起
+  request   ① ClientRequest                 ③ ServerRequest
+            （POST /api/<method> body）      （SSE 帧：session 事件、审批/问答 requested）
+  response  ② ServerResponse                ④ ClientResponse
+            （该 POST 的 HTTP 应答体）        （POST /api/respond body，回填 ③ 的 rpcId）
+```
+
+### wire 全形：四具名判别 union（`api/rpc.ts`）
+
+| 类型 | 判别 tag | 字段 | rpcId 归属 | Web 承载 |
+|---|---|---|---|---|
+| `ClientRequest` | `'client-request'` | `rpcId` `method` `payload` | client mint | `POST /api/<method>` body |
+| `ServerResponse` | `'server-response'` | `rpcId` `result` | 回填 ① | 该 POST 的应答体（恒 HTTP 200） |
+| `ServerRequest` | `'server-request'` | `rpcId` `method` `payload` | server mint | SSE `data:` 行 |
+| `ClientResponse` | `'client-response'` | `rpcId` `result` | 回填 ③ | `POST /api/respond` body |
+
+`RpcMessage = ClientRequest | ServerResponse | ServerRequest | ClientResponse`，`switch (message.type)` 窄化。
+
+**rpcId 纪律**（`RpcId` 是 branded string，构造函数 `RpcId()`）：
+
+- 谁发起谁 mint；应答一律回填对应 request 的 rpcId，**绝不 mint 新 id**。
+- server-request 分两类，静态按 `method`（=帧 type）区分，**不设第三种 kind**：可应答帧（`approval/requested`、`question/requested`）的 rpcId 是稳定逻辑请求 id（受理时 mint 一次、基线重放原样复用、client 以它回填应答）；纯推送帧（`session/event` 等）的 rpcId 标识该次推送（每次新 mint）。
+- 业务代码不 mint：unary 的 mint 收口在客户端基类 `callUnary`，帧的 mint 收口在 host 侧。
+
+### 签名窄形与载体补全
+
+域接口签名只感知窄形：`RpcRequest<P> = { rpcId, payload }`、`RpcResponse<T> = { rpcId, result: RpcResult<T> }`。载体层把窄形补全为全形（补 `type` tag 与 `method`），方向不靠通道推断。`RpcResult<T> = { ok: true; value } | { ok: false; error: RpcError }`——方法不 throw 业务错误。
+
+### RpcReceipt：载体回执
+
+`ClientResponse` 的 HTTP 应答体是 `RpcReceipt = { accepted: true } | { accepted: false; reason: 'not-pending' | 'bad-response' }`——载体层回执，**不是** RpcMessage（response 不再有 response）；迟到/重复应答收 `not-pending`，逻辑收敛面是 `*/resolved` 帧。
+
+## 类型体系：函数签名即事实源
+
+### RpcMethodMap 与派生泛型（`api/rpc-map.ts`）
+
+方法的参数/返回结构**只住在接口方法签名里**；map 登记方法本身；其余一切位置（handler、client、store、测试）引用派生泛型，禁止复写字面量或另起平铺具名类型：
+
+```ts ignore-check
+export interface RpcMethodMap {
+  'session.list': SessionsApi['list']        // map key 即 wire 路径段
+  // …其余方法同形登记，全集见 api/rpc-map.ts
+}
+// 派生泛型（穿透窄形取业务类型；实际声明带 K extends keyof RpcMethodMap 约束）
+export type RequestPayload<K> = Parameters<RpcMethodMap[K]>[0]['payload']
+export type ResponseValue<K> =
+  Awaited<ReturnType<RpcMethodMap[K]>> extends RpcResponse<infer T> ? T : never
+```
+
+流方法（`events.mux`/`events.host`）不进 map（不是 unary）；`respond` 不进 map（是 client-response 不是方法调用）。
+
+### 错误模型（`RpcErrorDetailsMap`）
+
+错误码示例一行：
+
+| code | details | 何时 |
+|---|---|---|
+| `bad-request` | `{ issues: ZodIssue[] }` | wire/payload zod 校验失败 |
+
+码全集见 `api/rpc.ts` 的 `RpcErrorDetailsMap`。`RpcError` 是 map 展开的分布式 union：`code` 判别、`switch` 后 `details` 自动窄化；**details 必填**——新码=map 加一行+错误 schema 加一支，漏填是编译错误。transport 故障（断网、host 没起）由载体抛异常，与业务错误两层不混。
+
+### zod 双向校验与锚定
+
+- **两级 parse**：全形 schema 一次（type/rpcId/method 结构 + handler 校验 path==method）→ 业务 payload 按 method/帧型分派二次 parse；拒收 = `bad-request`。
+- **锚定**：schema 统一 `satisfies z.ZodType<Wire<T>>`（`api/rpc.schema.ts`）。`Wire<T>` 是深度「| undefined」宽化——仓库开 `exactOptionalPropertyTypes` 而 zod `.optional()` 输出 `T | undefined`，直接锚原类型全线不可用；JSON wire 上缺席与 undefined 同形，宽化不损失校验语义。透传宽分支（`SessionEvent`/`ContentBlock`/帧 union/`RpcError`）与 brand id schema 用显式 cast + 注释。
+- brand cast 单点：每个 schema 文件的 id cast 收口一处（`rpcIdSchema` 是 rpc.schema.ts 唯一 cast 点）。
+
+## 契约面（ApiProxy）
+
+根接口 `ApiProxy = { sessions, host, events, respond }`（`api/index.ts`）。新 client-request 域 = 新的一对文件（`<域>.ts` + `<域>.schema.ts`）+ 根接口一个字段 + map 加行。
+
+### unary 方法表
+
+方法示例一行（表结构即读法）：
+
+| method key | 请求 payload | 返回 value | 语义 |
+|---|---|---|---|
+| `session.list` | `{ cursor?: string }`（cursor 留座不实现） | `{ items: SessionSummary[] }` | 已持久化 session，updatedAt 倒序；v1 不建索引 |
+
+其余方法（`session.create`/`session.history`/`session.prompt`/`session.cancel`/`host.describe`）的参数与返回不在此复写——签名即事实源，见 `api/sessions.ts`、`api/host.ts` 与 `RpcMethodMap`。
+
+### 帧（server→client，具名 union）
+
+两条 SSE 流：mux 流（`GET /api/events.mux`，全 session 聚合）与 host 流（`GET /api/events.host`，host 级事件）。帧示例一行：
+
+| 帧 type | 载荷 | 何时发 |
+|---|---|---|
+| `session/event` | `{ sessionId; event: SessionEvent }` | 核心透传：core 事件原样过，`assistant/chunk` 即 token 流，无独立 delta 帧 |
+
+其余帧型不在此复写，union 全集见 `api/events.ts` 的 `MuxFrame`/`HostFrame`。语义上须知三点：`session/subscribed` 的 lastSeq 供 history 补缝竞态检测；`approval/question` 的 requested 帧可应答（rpcId 稳定）、resolved 帧是收敛面；`host/agent-error` 是无 turn 位置 live 失败的唯一出口。
+
+**透传纪律**：wire 上的事件/消息/内容块就是 core 类型（`SessionEvent`/`ContentBlock`），不造第二套 DTO；类型经 `import type` 依赖链直达浏览器。`SessionEventMap` merge-extensible：client 对未知 type documented-default（忽略），事件 schema 留「合法信封+未知类型」分支——信封仍严格，不是字段级 passthrough。
+
+### 会话语义（impl 侧承诺）
+
+- **历史 = 事件重放**：一套 fold（client 侧），历史分页与 live 增量同一条代码路径；server 不做物化快照第二套。history **页边界对齐消息边界**（绝不从消息中间截断；chunk 随定稿消息归组），尾页含进行中 partial 的 chunk。
+- **prompt 关联**：prompt 的 rpcId 经 MessageSource（`'user-rpc'`）透传进 `user/message` 事件，client 以此把乐观回显转正。
+- **重连 = 重建**：不做续传 cursor（`mux` 的 `since` 签名留座、传了忽略）；断线重开流 + 重拉 history；`subscribed.lastSeq` 与 history 尾 seq 比对，有缝再补拉一次。
+- **冷 session 隐式 resume**：`history`/`prompt` 命中未 attach 的 session 时 impl 自动 resume，并发触发用在途表去重；attach 与否不对客暴露（`running` 已覆盖）。
+- **审批/问答**：requested 帧受理时 mint 稳定 rpcId；先到先赢，host 内存 pending 表（keyed by rpcId）是唯一裁判；mux 重开后在 subscribed 帧后重放仍 pending 的 requested 帧（rpcId 原样复用，刷新恢复）。审计事件 `approval/asked`/`decided` 照旧走 durable 日志——帧=live 控制面，事件=durable 审计。**现状**：契约与帧类型已 shipped，host 侧 pending 表/wire answerer 未实现（`api-proxy.ts` 的 `respond` 是 stub，恒回 `not-pending`）；PendingCard v1 只展示。
+- **不设协议版本**：client 与 host 绑定发布，`host.describe` 无 protocolVersion 字段；出现独立发布的 client 时再引入。
+- **预留接缝纪律**：map 只含已实现方法，未知 method 在信封 parse 即 fail loud（`bad-request`），不设 not-implemented 兜底码。预留清单（实现时把签名抄进域接口+map 加行+schema 加对即升格）：`session.fork`、`prompt.mode` 加 `'inject'`、`task.list`、`host.listModels`、describe 加 `hostInstanceId`。
+
+## 客户端载体：AbstractApiClient 类体系（`fetch/client.ts`）
+
+**协议不变量住基类，平台差异是两个切面**：抽象方法 `doFetch(url, init)`（传输）+ 可覆写 `onEnvelope`（观测）。
+
+### IApiClient：caller 视图
+
+与 `ApiProxy` 同域树，但 unary 方法**收业务 payload 直传**——载体 mint rpcId 并包信封，业务代码永不 mint；需要本次调用 rpcId 的从返回的 `RpcResponse` 回显里读。`ApiProxy` 是 impl 侧实现的窄形签名契约，`IApiClient` 是 client 侧消费的 payload 直传视图，`AbstractApiClient` 桥接两者。方法逐 key 从 `RpcMethodMap` 派生——map 加行即机械更新。
+
+### 基类持有的协议路径
+
+| 路径 | 内容 |
+|---|---|
+| `callUnary` | mint → tap → POST 全形 → `serverResponseSchema` parse → **rpcId 回显校验**（不符即 throw）→ tap → 吐窄形 |
+| `readSse` | streaming fetch（非 EventSource）、`\n\n` 分帧、`data:` 拼接、ServerRequest 全形 parse、tap、吐窄形 `RpcRequest<帧>` |
+| `respond` | client-response 透传（rpcId 是回填，此处不 mint）；应答体 `rpcReceiptSchema` parse |
+| unary 超时 | `AbortSignal.timeout`（默认 30s，构造参数可调）；流不设超时（长连接本性） |
+| `resolveBase` | 浏览器=同源 origin；无 location 环境（Node）=`http://dsh.internal` 假 authority |
+
+### 实例级 envelope 观测切面
+
+四象限全形均过 `onEnvelope`；基类实现是**实例持有的微任务合批缓冲**（帧风暴不逐帧惊扰消费者；模块级状态会跨实例/测试泄漏，故实例持有）。观测者经 `subscribeEnvelopes(listener)` 订阅（收整批 `readonly RpcMessage[]`，返回退订函数）；listener 抛异常被隔离（观测不得反噬载体）。无订阅者时零缓冲成本。当前没有任何现役消费者订阅——该切面是 wire 诊断的预留位（已退役的 RPC 调试面板是它的首个消费者，将来的诊断消费者接入时不动载体）。
+
+### 子类表（传输承载）
+
+| 子类 | 所在包 | doFetch | 用途 |
+|---|---|---|---|
+| `InProcessApiClient` | apiproxy 本包 | 注入的 `{ fetch }` handler | **同构点**：`new InProcessApiClient(toFetchHandler(api))` 全程不过网络但真跑 wire 序列化/zod/SSE 帧——`dsh -p` headless 即协议第二真实消费者 |
+| `WebApiClient` | dsh-client-connection | `globalThis.fetch`（同源 `/api/*`） | 浏览器形态；HTTP+SSE 承载落地见 Web 客户端架构 RFC |
+| `FixtureApiClient` | dsh-client-connection | 不用（协议层覆写） | 无 server 的 UI 开发（`?fixture`）：覆写 `callUnary`/`openMux`/`openHost`/`respond` 虚方法，自己就是假 server（帧 rpcId 由它 mint，语义自洽） |
+| （将来）IPC 桥子类 | apps/electron | IPC 序列化往返 | 仅换 doFetch，契约/基类零改 |
+
+## 怎么扩展（操作清单）
+
+**加一个 unary 方法（5 步）**：①域接口加方法签名（参数/返回内联，这是唯一事实源）；②`RpcMethodMap` 加一行；③`<域>.schema.ts` 加 request/value schema 对（锚 `Wire<RequestPayload<'…'>>`）；④handler `UNARY_ROUTES` 加一行（handler 的 Web 承载见 Web 客户端架构 RFC）；⑤impl 实现（回显 `request.rpcId`）。client 侧 `IApiClient`/`AbstractApiClient` 的域方法表同步加一行透传。
+
+**加一个帧型（3 步）**：①`MuxFrame`/`HostFrame` union 加一支（可应答帧须注明 rpcId 稳定语义）；②帧 schema 加一支；③消费端 fold/路由的 documented-default 已兜底未知型，按需加显式分支。
+
+**加一个错误码（2 步）**：①`RpcErrorDetailsMap` 加一行（details 必填）；②`rpcErrorSchema` discriminatedUnion 加一支。
+
+**接一种新载体**：继承 `AbstractApiClient` 只实现 `doFetch`；需要拦截协议层（如 fixture）再覆写 `callUnary`/`openMux`/`openHost` 虚方法。契约与基类零改。
+
+**升格一个预留接缝**：把预留签名抄进域接口 → map 加行 → schema 加对 → UNARY_ROUTES 加行 → impl 实现。
+
+## Consequences
+
+所有 client 形态消费同一契约：加一个 unary 方法是从单一签名辐射的五步机械改动，换载体只动一个 `doFetch` 子类，wire 上每条消息可 zod 校验、可经 envelope tap 观测、可按 rpcId 对账。接受的代价：两组包需要显式 tsconfig paths 条目；预留接缝（fork/inject/task.list/listModels/hostInstanceId）在真实消费者出现前保持休眠。
+
+## Alternatives considered
+
+| 放弃项 | 一句话理由 |
+|---|---|
+| 按「产品形态」分包（web 一族、electron 一族） | 形态间共享的是 host/client 两侧能力而非形态本身；能力支持方分层让新形态零新包 |
+| 混合体建包（如 headless 独立包） | 混合体只有一个消费者（它自己的 app），建包是无主抽象；拼装写在 app 里可读可弃 |
+| 消费型 client 直连 ctx（省 apiproxy 一层） | 第二命令面绕开契约，wire 校验/观测/多端一致性全失；ctx 只留给前门与 headless 事件订阅两个正式用途 |
+| webserver 依赖 runtime（省 handler 注入） | 结构 typing 注入让 webserver 可被 sidecar/测试复用且零 workspace 依赖；包依赖会把装配知识拖进承载层 |
+| 包名不带组前缀（沿用 dsh-<尾段>） | `dsh-runtime`/`dsh-web-ui` 在扁平 npm 命名空间里失去归属信息；代价只是每包一条显式 paths |
+| 复用仓内 JSON-RPC 2.0（dsh-jsonrpc） | 数字错误码退化成单码兜底、契约双份人肉对齐、命名无 convention 自然漂移 |
+| 三信封模型（Request/Response/Frame 各一信封，签名不感知方向） | rpcId 是逻辑层关联，帧与应答的方向语义靠通道推断在换载体时即失效 |
+| 具名 Request/Response 类型对为事实源（map 登记类型对） | 平铺具名类型是同一事实的第二个名字；签名 infer 反推让加方法只改一处 |
+| REST 风格路径 | 消费者是自家 client，无第三方 REST 体验诉求；RPC 直映方法表更机械 |
+| DTO 层（wire 专用第二套结构） | core 类型 type-only 直达浏览器零成本；DTO 是永久的双向同步税 |
+| cursor 续传（mux since 实装） | 重连=重建（opencode 同款）覆盖 v1 全部需求；签名留座，实装等真实消费者 |
+| createApiClient 工厂函数（原实现） | 平台差异（传输/观测）是继承切面不是参数；类体系让 fixture 在协议层替换而不是包一层假信封 |
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
new file mode 100644
index 0000000000..91abd32a3e
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-19-gui-web-client-architecture.md: 58320570f752d4259004172d3b4527172c2cc646
+2026-07-19-gui-web-client-architecture.zh.md: 744fdaa4b89a01e2710f85b177228713189e3025
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
new file mode 100644
index 0000000000..58320570f7
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
@@ -0,0 +1,148 @@
+# Agent Note: Web client architecture — the client cordis plugin tree, the slot system, and the React-free object layer
+
+Status: implemented
+
+English | [中文](2026-07-19-gui-web-client-architecture.zh.md)
+
+> Division of labor: the channel-independent layering model and RPC protocol (message model / type system / contract face / client base class) are in the [layering and RPC protocol RFC](2026-07-19-gui-layering-and-rpc-protocol.md); this document = the browser side: how the client cordis tree loads, how UI plugins compose through slots and services, and how the React-free object layer feeds React through immutable snapshots.
+
+## Problem
+
+Two forces shape the browser client. First, streaming: in an event-driven conversation UI, if business state (the event window, streaming accumulation, pending interactions, the connection state machine) scatters across React components and a global store, every token chunk shakes the render tree, and swapping the UI library means rewriting the business logic. Second, modularity: UI features (layout, sidebar, conversation, theme, locale) must be independently loadable plugins — composed at runtime from a host-served manifest, not compiled into one bundle — without giving up compile-time type safety across plugin boundaries.
+
+## Decision
+
+Both ends run cordis. The host is a cordis plugin tree; the browser runs a second, client-side cordis tree whose every UI capability is a plugin loaded dynamically by a shell-held loader. Inside that tree, cordis ctx hosts all runtime facts (services, stores, session scopes) and React is pure projection: components import nothing from the framework, receive everything through props, and subscribe to immutable snapshots via `useSyncExternalStore` (uSES below).
+
+```
+┌─ Host ─────────────────────────┐   ┌─ Browser ─────────────────────────────────────────┐
+│ sessions/agents/SessionLog     │   │ client cordis root ctx                             │
+│ apiproxy: RPC + mux/host 双流  │◀─▶│  ├ loader（壳静态持有，不能经自己装载）             │
+│ webserver:                     │   │  ├ immediately 先行组: connection/runtime/         │
+│  ├ GET /plugins/<id>/client.js │   │  │   ui-theme/i18n（动态 bundle，并行先装）        │
+│  └ GET / 注入 __DSH_BOOT__     │   │  ├ 后续组: layout/sidebar/conversation/trajectory  │
+└────────────────────────────────┘   │  └ session scope ×N（观看驱动，惰性建）            │
+                                     │ React: loading 页 → settled → 整 UI 一次成型       │
+                                     └────────────────────────────────────────────────────┘
+```
+
+## The client cordis tree and the loading chain
+
+Every UI plugin is simultaneously a host plugin (dual-entry package): the node half sits in the host's plugin tree so the host Loader governs its lifecycle, and the browser half is a tsdown closure bundle under the package's `exports["./client"]`. The host webserver derives the boot manifest from loaded plugins carrying a `dshClient` manifest field and injects it into the page as `window.__DSH_BOOT__` — the HTML alone tells the browser everything to fetch, zero extra round trips.
+
+The loading chain, end to end:
+
+1. `GET /` → the shell boots, mounts `ctx.loader` (the loader mechanism is held statically by the shell — a loader cannot load itself; its code home is `packages/client/runtime/src/client/loader/`, imported through the `./loader` subpath so the shell bundle does not swallow the rest of the runtime package), seeds the require module table with the pure-library instances (react, react-dom, cordis, ui-slots, web-react, ui-primitives), and renders a plugin-independent loading page.
+2. `loader.start()` reads `__DSH_BOOT__`. Entries flagged `immediately` form the early-load group (connection, runtime, ui-theme, i18n): fetched in parallel, applied in intra-group `inject` topological order, and **the whole group must land before anything else loads**. Remaining plugins then load in inject order.
+3. Each bundle executes `window.DSHClientProxy.loadPlugin({ id, factory })`. The loader calls `factory(require)` — bundles are closure factories whose external dependencies arrive through the injected `require`, resolved against the module table (no globals, no import maps; an unresolvable specifier fails loud). The factory returns its module export surface (including the cordis `apply`); the loader runs `ctx.plugin(apply)`, then **registers that export surface into the module table under the package name**, so inject topology guarantees later plugins can `require` earlier ones. Plugin CSS is inlined in the bundle and injected as `<style data-plugin="<id>">` (CSS Modules hashing + ownership tag = isolation).
+4. `await loader.settled()` → the shell flips from the loading page to the real UI in one pass. A single failed plugin fails loud on the loading page; there is no partial-availability mode (progressive rendering is deferred work).
+
+**The dual-instance ban**: a module-table package inlined into a plugin bundle would duplicate runtime identity (two React copies, two store registries — the root cause of an actual white-screen P0). The tsdown client preset enforces purity at build time: a bare-name import of a module-table package must resolve external (rewritten to its `/client` form where applicable), and any other workspace leak that is not an inline-safe wire/type layer fails the build (`packages/client/tsdown.client.ts`, pinned by `scripts/client-bundle-purity.spec.ts`).
+
+Dev equals prod: plugins rebuild under `tsdown --watch`, refresh reloads the same chain; vite serves only the shell (`apps/web`). Type universes stay split at the aggregate level — the root `tsconfig.json` is the host program, `tsconfig.client.json` the client program, because both sides merge cordis `Context` under the same keys (`sessions`, `loader`) with different services; client packages consume the wire vocabulary through pure type subpaths (`@deepseek-ai/dsh-session/types` and kin) so no host augmentation rides into the client program.
+
+## The slot system: how the page composes
+
+A page is a tree of slots; whoever owns a region declares its slots. Contracts live in one place — the `SlotMap` interface in `@deepseek-ai/dsh-client-ui-slots`, extended by declaration merging. An entry declares the slot's axes and the **owner share** only; the registrant's injected props never enter the global table ("whoever injects it, owns its type"):
+
+```ts ignore-check
+declare module '@deepseek-ai/dsh-client-ui-slots' { interface SlotMap {
+  sidebar:      { kind: 'single'; scope: 'root';    owner: SidebarOwnerProps }
+  conversation: { kind: 'single'; scope: 'session'; owner: ConvOwnerProps; children: 'conversation.empty' }
+} }
+ctx.slots.define('sidebar', { kind: 'single', scope: 'root' })   // declare=类型，define=落账
+ctx.slots.register('sidebar', SidebarRoot, { inject: (b) => ({ /* ... */ }) })
+```
+
+- Three kinds: `single` (duplicate registration throws), `list` (id/order), `keyed` (runtime dispatch, duplicate key throws). Register before define throws. Two scopes: `root` (no session context) and `session` — the scope decides the injection shape below.
+- **Full component props are composed by reference, never re-typed**: a registrant's component declares `OwnerOf<K> & StandardOf<K> & OwnInjected` — the owner share referenced from the slot owner's package, the standard share supplied by the framework (session slots: `useSession`), and the registrant's own injected share declared locally next to the component. `register<K, I>` enforces the composition at the call site: the component parameter is `SlotComponent<ComposedProps<K, NoInfer<I>>>` (a bare call signature, not `FC` — FC's `propTypes` static position generates contravariance noise against the standard share), and `I` is inferred exclusively from the inject factory's return type (`NoInfer` pins it), so a drifted component or a mismatched factory is a compile error at the registration point. In ui-conversation the injected shares live in `src/client/contract/slots.ts` (`ConversationInjected` and kin) and each skeleton component's props is a one-line reference composition.
+- **Delegation is a hand-written whitelist with an optional declared ceiling**: an owner component receives a whitelist-narrowed `slots: ScopedSlots<'a' | 'b'>` through its own props and calls `slots.renderSlot(key, props)`; passing a narrowed subset to a child goes through `narrowSlots` (pure type covariance). Overreach is a compile error, and the runtime whitelist backstops plain-JS callers. An entry may additionally declare `children: <key>` — register then validates the component's whitelist ⊆ the declared ceiling (opt-in visibility layer, not mandatory). Every rendered entry is wrapped in a per-entry error boundary: a crashing registrant (component or inject factory) blacks out only its own entry, while assembly errors (missing providers) rethrow — a miswired shell fails loud instead of degrading.
+- **Props merge from three sources** (the outlet does it; owners write only the first): ① owner-supplied props (identity, display parameters, frozen slices) — typed as the entry's owner share, exact at the renderSlot point; ② scope-standard injection — session slots automatically receive `useSession` bound to the right Session; ③ the registrant's `inject` factory, called once per (entry × session) for session slots and once per entry for root slots, cached in WeakMaps so a session switch-back reuses the cached result. Inject factories receive the assembly handle (`SessionBinding { sessionId, session, ctx }` or `RootBinding { ctx }`) — an apply-world object that never enters React.
+- Two supply channels close the loop: `RootBindingProvider` (mounted once by the shell) feeds root-slot inject factories their ctx; `createSessionProvider(deps)` builds the single session provider — dependency-inverted (`useCurrent` / `resolveBinding` / `renderBody`), so web-react never imports the runtime. It subscribes to the current session id, resolves a reference-stable binding, remounts its body under `key={id}`, and delegates body rendering to the assembler's `renderBody` closure (slot ownership stays with layout; the provider knows no slot names).
+
+Implementation homes: registry core in `packages/client/ui-slots` (zero dependencies), outlet/providers/uSES bridge in `packages/client/web-react`.
+
+## Services and scope addressing
+
+A service is a plugin's only API surface toward other plugins (UI components and injection faces are not APIs; a plugin nobody calls mounts no service — ui-trajectory is the minimal-plugin exemplar: no ctx service, only view-map merges). The roster: `ctx.connection` (api client + stream handles), `ctx.slots` (registry wrapper emitting `slots/changed`), `ctx.sessions` (list store, scope tree, bindings), `ctx.loader`, `ctx.theme`, `ctx.i18n`, `ctx.layout` (navigation + panel viewing state), `ctx.conversation` (send/cancel/selection/views/startSession), `ctx.toolviews` (named per-tool render registry with per-session scope filters).
+
+Beyond SlotMap, two more typed registration rings follow the same declare-merge idiom: the **view ring** (`ConversationViewMap` — an entry may declare `chromeProps`/`extraProps` extension shapes; `ConvViewPropsOf<Id>`/`ChromePropsOf<Id>` compose base + extension, so a view with no declaration gets the base for free while ui-trajectory's entries carry real per-view props) and the **tool ring** (tool names stay an open set — no global key table; typing hardens inside the entry: `ToolViewProps.block` is the real `ToolCallBlock` union defined in runtime, and register infers the registrant's injected share like slots do).
+
+**Scope addressing** mirrors the host's agent-scope idiom: services are root singletons whose methods take no sessionId — they read the caller's scope mark (`scopeOf(ctx)`). Inside a session scope, `ctx.conversation.send('hi', 'queue')` targets that session; cross-session calls re-target by switching ctx (`ctx.sessions.scope(id)!.conversation.send(...)`); calling a scoped method from root ctx throws. Client session scopes are minted like host agent scopes (a no-op plugin fiber + a scope-key extend), built lazily on first viewing and torn down only when the session is removed and unwatched — host-session death alone does not tear a scope (it freezes into a read-only viewport).
+
+## The data object layer (`packages/client/runtime/src/client/sessions/`)
+
+Frames enter, snapshots exit, the fold sits between — React-free (zero React imports, grep-assertable):
+
+```
+mux/host 帧（ConnectionController 泵入，sinks 注入）
+        │
+        ▼
+SessionManager.handleMuxEnvelope / handleHostEnvelope
+        │ 带 sessionId 的帧只投已存在实例（审批/问答 requested 例外：进 pendingBuffers 缓冲）
+        ▼
+Session.handleMuxEnvelope ──► events 窗口（seq 连续升序）
+        │                        │ 定稿事件            │ chunk
+        │                        ▼                    ▼
+        │                   FoldAdapter        PartialAccumulator
+        │                  （→ nodes）          （→ partial）
+        ▼
+Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES──► 组件
+```
+
+- **Session** (session.ts): lazily built, resident — once created it keeps eating frames in the background, so switching away and back renders instantly. Operations: `prompt`/`cancel` (RPC passthrough; failures land in the snapshot's `promptError`), `open` (pull the tail history page, idempotent), `loadOlder` (upward paging, reentry-guarded), `resync` (reconnect = clear the window and rerun open). Subscription: `subscribe`/`getSnapshot` (always the cached reference) — `implements ObservableSnapshot<ConversationSnapshot>`, with `useSelector = bindSnapshotSelector(this)` attached at construction, so a Session is directly a uSES source. Frame dispatch is one switch: `session/event` frames dedup by seq (the only dedup key), buffer while open is in flight, otherwise append + incremental fold; open/stitch merges the live buffer by seq and backfills once if `subscribed.lastSeq` outruns the window tail.
+- **ConversationSnapshot** (conversation.ts): the immutable snapshot contract — `nodes` (folded, surface-ordered), `partial`, `runningCalls`, `pending`, `running`, `removed`, `openState`, `hasMore`, `promptError` and kin. **Reference discipline** (the premise of memo and uSES): the top-level object is fresh on every change; the nodes array is rebuilt but element references come from the cache; unchanged substructures reuse the previous snapshot's references.
+- **SessionManager** (manager.ts): instance cluster + frame entry + the session list. sessionId-bearing frames go only to existing instances (a mux broadcast must not instantiate every session); approval/question `requested` frames are the exception — they never land in history, so they buffer in `pendingBuffers` and replay on instantiation.
+- **Notifier** (notifier.ts): two channels chosen by change source. `markDirty()` (default; frame-driven changes always) batches per microtask — N changes, one notification, one re-render; the flush rebuilds the snapshot cache before notifying. `notifyNow()` (only direct echoes of user gestures) rebuilds and notifies in the same tick — controlled inputs roll the DOM back and jump the caret if their echo defers to a microtask. Frame-driven code using notifyNow collapses batching back to per-frame renders; banned.
+- **FoldAdapter / PartialAccumulator**: the fold reuses the core SurfaceManager (`@deepseek-ai/dsh-session/surface`), padding sentinel events so a paged window starting at seq > 0 satisfies the core's `seq === index` assertion; a cross-window replace degrades to a tolerant linear scan and sets `foldDegraded`. Chunks stay out of the fold entirely (O(1) skip): the accumulator folds StreamChunks into `AssistantBlock[]`, a delta swapping only that block's reference, and the finalizing message discards the accumulator in the same batch (no flicker on promotion). Cost model: one chunk = one string concatenation + a dirty mark; an unsubscribed Session under a frame storm costs only the mark.
+- **ConnectionController** (in `packages/client/connection`): opens the mux/host streams, pumps with for-await, reconnects with exponential backoff (500ms doubling to 10s, jitter, unlimited) behind a generation fence; sinks are injected one-way (the Controller does not know Session). Reconnect = rebuild: `onConnected` → list refresh + per-open-session resync. The object layer faces only `IApiClient`; the Web carriage (HTTP POST for the two client→server quadrants, SSE for the two server→client) and the client class family are the layering RFC's territory.
+
+## The React face (`packages/client/web-react`)
+
+The glue package is the whole ctx↔React boundary; components stay framework-free.
+
+- `createSnapshotStore<T>(init, opts)`: the store engine for plugin-owned data and shell viewing state — zustand vanilla with draft-based updates, `flush: 'sync'` by default (controlled inputs need same-tick echo) with opt-in `'raf'` batching for frame-driven stores, opt-in whole-value localStorage persistence, dev-mode deep freeze. Both a Session object and a snapshot store satisfy the one data contract React consumes: `ObservableSnapshot<T>` (`getSnapshot`/`subscribe`).
+- `bindSnapshotSelector(source)`: binds a source into a typed selector hook over uSES-with-selector. The four uSES contract clauses hold by construction: getSnapshot returns the cached reference; subscribe is a bind-time closure (reference-stable forever); pure CSR passes no server snapshot; equality defaults to `Object.is` with `shallowEqual` opt-in per call.
+- `useInvoke(fn)`: wraps an async action into a stable trigger plus pending flag; pending rides a per-hook external store read through uSES (no setState on the render path), concurrent invocations are counted, and the invoke reference never changes.
+- Equality protocol, whole chain: producers use structural sharing; consumers short-circuit with `Object.is` or `shallowEqual`; `React.memo` shallow. Deep comparison is banned everywhere.
+
+## Directory shape
+
+Twelve `packages/client/*` packages (ui-slots, ui-primitives, web-react, connection, runtime, ui-layout, ui-sidebar, ui-conversation, ui-trajectory, ui-theme, i18n, web) plus `apps/web` — the vite application, a thin `main` over the shell's boot export. Plugin packages keep their browser half under `src/client/`; **every build artifact lands in `lib/`** — the node half as `lib/index.js`/`lib/invariant.js`, the browser bundle as `lib/client.js` (the shared tsdown client preset emits both; there is no `dist/` directory, and `exports["./client"]` points at `./lib/client.js`). Dependency direction: `ui-slots ← web-react ← runtime ← ui-* (peers) ← web`, with ui-primitives/ui-theme/i18n as zero-dependency side paths.
+
+A multi-domain plugin package additionally splits its client half by future package boundaries — ui-conversation is the exemplar:
+
+```
+src/client/
+  contract/    the only shared face between domains (types + composed props shares)
+  service.ts   cross-domain orchestration (imports contract only)
+  skeleton/    domain: shell components (ConversationRoot/InputBar/EmptyState/DetailsPanel)
+  chat/        domain: the chat view
+  toolviews/   domain: the tool-row registry and samples
+  apply.ts     the ONLY file allowed to import across domains (assembly point)
+  index.ts     thin re-export shell (contract + apply + components)
+```
+
+Domain implementation files never import a sibling domain — shared surfaces route through `contract/` (e.g. chat consumes the tool registry through a `ToolViewResolver` read-face interface, not the registry class). `scripts/verify-client-domain-graph.ts` enforces the layering (contract=0, domains=1, apply/index=2; imports may only point at levels ≤ own; sibling-domain edges fail). A future package split promotes each domain directory to a package and mechanically rewrites import paths.
+
+## How to develop
+
+- **A new UI feature** = a new plugin package: declare `dshClient` (+ `inject` topology) in package.json, write the browser half under `src/client/` (apply mounts services/stores, registers slots and toolviews), keep the node half an empty apply unless there is host logic, build with the shared preset. Add the plugin to the host config; the manifest and loading follow automatically.
+- **A new slot**: merge the contract into `SlotMap`, `define` at the owner, render through the owner's own `ScopedSlots` whitelist; registrants `register` with an optional inject factory. Never export components globally.
+- **Consuming a new frame type**: sessionId-bearing → a branch in Session's dispatch switch; host-level → the Manager routing table; if the UI needs it, a `ConversationSnapshot` field with the reference discipline kept.
+- **Where does this state live**: per-session and must survive switches → the Session object / scope-mounted store; private to one view (selection, scroll) → component state; shell viewing state (navigation, panel widths, preferences) → `ctx.layout`'s stores; business data → always the object layer, never a viewing-state store.
+- **Notification channel**: frame-driven/async = `markDirty` batching; direct user-gesture echo whose controlled input needs the same tick = `notifyNow`.
+
+## Consequences
+
+Token streams no longer shake the render tree: a frame storm costs unsubscribed sessions one dirty bit and the subscribed view one batched re-render per microtask (raf-batched for frame-driven stores). UI features load, fail, and get disabled as independent plugins — one crashing slot entry blacks out one card, one failed bundle fails loud before the UI flips in. The accepted costs: the loader/module-table machinery is bespoke infrastructure the team owns end to end; the one-flip boot (no progressive rendering) trades first-paint granularity for assembly simplicity; and the dual type programs make "which aggregate sees this file" a question developers occasionally have to answer.
+
+## Alternatives considered
+
+| Rejected | One-line reason |
+|---|---|
+| One statically-linked SPA bundle | Plugins must be host-composable at runtime (config-driven); a monolith re-couples every UI feature to one build |
+| window globals / import maps for shared deps | The DI require table keeps sharing explicit, fail-loud, and swappable; globals leak identity and version silently |
+| Business data in zustand slices | The event window/accumulator is a behavioral state machine, not a flat slice; the object layer keeps snapshot granularity and batching controllable |
+| String-keyed global component registry for tool rows | Tool views are consumed by multiple views and need per-session differentiation — a named service (`ctx.toolviews`) with scope filters is the honest shape |
+| Progressive/Suspense boot in P-I | One-flip boot is strictly simpler; the loader's per-plugin status face is kept so progressive lighting can land later without re-architecture |
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
new file mode 100644
index 0000000000..744fdaa4b8
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
@@ -0,0 +1,148 @@
+# RFC: Web 客户端架构——client cordis 插件树、slot 体系与 React-free 对象层
+
+Status: implemented
+
+[English](2026-07-19-gui-web-client-architecture.md) | 中文
+
+> 分工线：通道无关的分层模型与 RPC 协议（消息模型/类型体系/契约面/客户端基类）见 [分层与 RPC 协议 RFC](2026-07-19-gui-layering-and-rpc-protocol.md)；本篇 = 浏览器侧：client cordis 树如何装载、UI 插件如何经 slot 与服务组合、React-free 对象层如何以不可变快照供给 React。
+
+## Problem
+
+浏览器客户端受两股力塑形。其一是流式：事件驱动的对话 UI 里，若业务状态（事件窗口、流式累积、待答交互、连接状态机）散落在 React 组件与全局 store 中，每个 token 分片都会震荡渲染树，且换 UI 库等于重写业务逻辑。其二是模块化：UI 功能（布局、侧栏、对话、主题、语言包）必须是可独立装载的插件——按 host 下发的 manifest（元数据清单）在运行时组合，而非编译进单一 bundle——同时不放弃跨插件边界的编译期类型安全。
+
+## Decision
+
+两端都跑 cordis。host 是一棵 cordis 插件树；浏览器里跑第二棵 client 侧 cordis 树，其中每一项 UI 能力都是插件，由壳静态持有的 loader 动态装载。树内 cordis ctx 承载一切运行时事实（服务、store、会话 scope），React 是纯投影：组件对框架零 import，一切经 props 注入，经 `useSyncExternalStore`（下称 uSES）订阅不可变快照。
+
+```
+┌─ Host ─────────────────────────┐   ┌─ Browser ─────────────────────────────────────────┐
+│ sessions/agents/SessionLog     │   │ client cordis root ctx                             │
+│ apiproxy: RPC + mux/host 双流  │◀─▶│  ├ loader（壳静态持有，不能经自己装载）             │
+│ webserver:                     │   │  ├ immediately 先行组: connection/runtime/         │
+│  ├ GET /plugins/<id>/client.js │   │  │   ui-theme/i18n（动态 bundle，并行先装）        │
+│  └ GET / 注入 __DSH_BOOT__     │   │  ├ 后续组: layout/sidebar/conversation/trajectory  │
+└────────────────────────────────┘   │  └ session scope ×N（观看驱动，惰性建）            │
+                                     │ React: loading 页 → settled → 整 UI 一次成型       │
+                                     └────────────────────────────────────────────────────┘
+```
+
+## client cordis 树与装载链
+
+每个 UI 插件同时是一个 host 插件（双入口包）：node 半边住在 host 的插件树里，由 host Loader 管辖其生命周期；浏览器半边是 tsdown 闭包 bundle，挂在包的 `exports["./client"]` 下。host webserver 从带 `dshClient` manifest 字段的已加载插件推导启动清单，注入页面为 `window.__DSH_BOOT__`——HTML 到手即知要拉什么，零额外往返。
+
+装载链全程：
+
+1. `GET /` → 壳启动，挂 `ctx.loader`（loader 机件由壳静态持有——装载器不能经自己装载；其代码家在 `packages/client/runtime/src/client/loader/`，壳经 `./loader` 子路径 import，避免壳 bundle 吞掉 runtime 包其余部分），把纯库实体（react、react-dom、cordis、ui-slots、web-react、ui-primitives）播种进 require 模块表，渲染一张不依赖任何插件的 loading 页。
+2. `loader.start()` 读取 `__DSH_BOOT__`。带 `immediately` 标记的条目构成先行装载组（connection、runtime、ui-theme、i18n）：并行拉取、按组内 `inject` 拓扑序 apply，**全组就位后才开始装载其余插件**。其余插件随后按 inject 序装载。
+3. 每个 bundle 执行 `window.DSHClientProxy.loadPlugin({ id, factory })`。loader 调 `factory(require)`——bundle 是闭包工厂，external 依赖经注入的 `require` 到达，从模块表解析（无全局变量、无 import map；解析不到的标识符即刻大声失败）。factory 返回其模块导出面（含 cordis `apply`）；loader 执行 `ctx.plugin(apply)`，随后**以包名把该导出面登记进模块表**——inject 拓扑保证后装插件可 `require` 先装插件。插件 CSS 内联在 bundle 里，注入为 `<style data-plugin="<id>">`（CSS Modules 哈希 + 归属标记 = 隔离）。
+4. `await loader.settled()` → 壳从 loading 页一次切换到真 UI。单插件装载失败在 loading 页大声报错；不存在部分可用模式（渐进渲染为后置工作）。
+
+**双实例禁令**：模块表包若被内联进插件 bundle，会复制运行时身份（两份 React、两套 store 注册表——一次真实白屏 P0 的根因）。tsdown client 预设在构建期把守纯度：模块表包的裸名 import 必须解析为 external（适用时改写为其 `/client` 形态），其余任何非 inline 安全 wire/类型层的 workspace 泄漏都令构建大声失败（`packages/client/tsdown.client.ts`，由 `scripts/client-bundle-purity.spec.ts` 钉住）。
+
+dev 与 prod 同链：插件在 `tsdown --watch` 下重编译，刷新即重走同一条链；vite 只管壳（`apps/web`）。类型宇宙在聚合层拆分——根 `tsconfig.json` 是 host program，`tsconfig.client.json` 是 client program，因为两侧都在相同键（`sessions`、`loader`）上对 cordis `Context` 做声明合并且服务不同；client 包经纯类型子路径（`@deepseek-ai/dsh-session/types` 等）消费协议词汇，host 侧的声明合并不会搭车进入 client program。
+
+## slot 体系：页面怎么拼
+
+页面是一棵坑位树；谁拥有区域谁声明坑位。契约只有一个家——`@deepseek-ai/dsh-client-ui-slots` 的 `SlotMap` 接口，经声明合并扩展。entry 只声明坑的轴与 **owner 份额**；注册方的注入 props 永不进全局表（「谁注入的放谁那里」）：
+
+```ts ignore-check
+declare module '@deepseek-ai/dsh-client-ui-slots' { interface SlotMap {
+  sidebar:      { kind: 'single'; scope: 'root';    owner: SidebarOwnerProps }
+  conversation: { kind: 'single'; scope: 'session'; owner: ConvOwnerProps; children: 'conversation.empty' }
+} }
+ctx.slots.define('sidebar', { kind: 'single', scope: 'root' })   // declare=类型，define=落账
+ctx.slots.register('sidebar', SidebarRoot, { inject: (b) => ({ /* ... */ }) })
+```
+
+- 三型：`single`（重复注册即 throw）、`list`（id/order）、`keyed`（运行时按 key 分发，重 key 即 throw）。define 之前 register 即 throw。两 scope：`root`（无会话语境）与 `session`——scope 决定下述注入形态。
+- **组件全量 props 一律引用组合，不重抄**：注册方组件声明 `OwnerOf<K> & StandardOf<K> & OwnInjected`——owner 份额从坑位 owner 的包引用、标配份额由框架供给（session 坑：`useSession`）、注册方自己的注入份额就地声明在组件旁。`register<K, I>` 在调用点强制组合：组件形参位是 `SlotComponent<ComposedProps<K, NoInfer<I>>>`（裸调用签名而非 `FC`——FC 的 `propTypes` 静态位对标配份额产生反变噪音），`I` 只从 inject 工厂返回值推断（`NoInfer` 钉死），组件漂移或工厂不匹配都在注册点编译报错。ui-conversation 的注入份额住 `src/client/contract/slots.ts`（`ConversationInjected` 族），各骨架组件的 props 是一行引用组合。
+- **转授=手写白名单+可选声明上限**：owner 组件经自己的 props 拿到白名单收窄的 `slots: ScopedSlots<'a' | 'b'>`，调 `slots.renderSlot(key, props)` 渲染；把收窄子集递给子组件走 `narrowSlots`（纯类型协变）。越权是编译错误，运行时白名单再兜住纯 JS 调用方。entry 可另声明 `children: <key>`——register 校验组件白名单 ⊆ 声明上限（可选可见层，不强制）。每个被渲染的注册项都包在 per-entry 错误边界里：注册方崩溃（组件或 inject 工厂）只黑自己那一格，装配错误（缺 provider）则重抛——接错线的壳大声失败而不是静默降级。
+- **props 三源合并**（出口组件来做；owner 只写第一份）：① owner 供参（身份、展示参数、冻结切片）——按 entry 的 owner 份额强类型，renderSlot 点即精确；② scope 标配注入——session 坑自动获得绑定正确 Session 的 `useSession`；③ 注册方的 `inject` 工厂，session 坑 per-(注册项 × 会话) 调一次、root 坑 per-注册项调一次，以 WeakMap 缓存——切回会话时复用缓存结果。inject 工厂收到装配句柄（`SessionBinding { sessionId, session, ctx }` 或 `RootBinding { ctx }`）——apply 世界的对象，永不进入 React。
+- 两条供给通道收拢闭环：`RootBindingProvider`（壳顶部挂一次）为 root 坑 inject 工厂供给 ctx；`createSessionProvider(deps)` 构造唯一的会话 provider——依赖倒置（`useCurrent` / `resolveBinding` / `renderBody`），web-react 永不 import runtime。它订阅当前会话 id、解析引用恒等的 binding、以 `key={id}` 重挂其 body，并把 body 渲染委托给装配方的 `renderBody` 闭包（坑位所有权留在 layout；provider 不认识坑名）。
+
+实现的家：注册表纯核在 `packages/client/ui-slots`（零依赖），出口组件/provider/uSES 桥在 `packages/client/web-react`。
+
+## 服务与 scope 寻址
+
+服务是插件对其他插件的唯一 API 面（UI 组件与注入面都不是 API；无人调用的插件不挂服务——ui-trajectory 即最小插件样板：无 ctx 服务，只 merge 视图表）。名册：`ctx.connection`（api client + 流句柄）、`ctx.slots`（注册表包装层，发 `slots/changed`）、`ctx.sessions`（列表 store、scope 树、binding）、`ctx.loader`、`ctx.theme`、`ctx.i18n`、`ctx.layout`（导航 + 面板观看态）、`ctx.conversation`（send/cancel/selection/views/startSession）、`ctx.toolviews`（具名按工具渲染注册表，带按会话 scope 过滤）。
+
+SlotMap 之外还有两条同 declare-merge 惯例的类型化注册环：**视图环**（`ConversationViewMap`——entry 可声明 `chromeProps`/`extraProps` 扩展形状；`ConvViewPropsOf<Id>`/`ChromePropsOf<Id>` 组合基座+扩展，无声明的视图免费得基座，ui-trajectory 的两个 entry 带真 per-view props）与**工具环**（tool 名保持开放集——无全局键表；类型强化在 entry 内部：`ToolViewProps.block` 是 runtime 定义的真 `ToolCallBlock` union，register 同 slots 一样推断注册方注入份额）。
+
+**scope 寻址**与 host 侧 agent scope 惯例同构：服务是 root 单例，方法不收 sessionId——它们读调用方 ctx 上的 scope 标（`scopeOf(ctx)`）。在会话 scope 内，`ctx.conversation.send('hi', 'queue')` 自动打到该会话；跨会话调用换 ctx 定向（`ctx.sessions.scope(id)!.conversation.send(...)`）；从 root ctx 直接调 scoped 方法即 throw。client 会话 scope 的铸造方式与 host agent scope 相同（no-op 插件 fiber + scope 键 extend），首次观看时惰性建，只有会话被移除且无人观看才拆——仅 host 会话死亡不拆 scope（冻结为只读视窗）。
+
+## 数据对象层（`packages/client/runtime/src/client/sessions/`）
+
+帧从这里进、快照从这里出、fold 坐在中间——React-free（零 React import，grep 可断言）：
+
+```
+mux/host 帧（ConnectionController 泵入，sinks 注入）
+        │
+        ▼
+SessionManager.handleMuxEnvelope / handleHostEnvelope
+        │ 带 sessionId 的帧只投已存在实例（审批/问答 requested 例外：进 pendingBuffers 缓冲）
+        ▼
+Session.handleMuxEnvelope ──► events 窗口（seq 连续升序）
+        │                        │ 定稿事件            │ chunk
+        │                        ▼                    ▼
+        │                   FoldAdapter        PartialAccumulator
+        │                  （→ nodes）          （→ partial）
+        ▼
+Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES──► 组件
+```
+
+- **Session**（session.ts）：懒建、常驻——建成后在后台持续吃帧，切走切回秒显。操作面：`prompt`/`cancel`（RPC 透传；失败落进快照的 `promptError`）、`open`（拉尾页 history，幂等）、`loadOlder`（向上翻页，防重入）、`resync`（重连 = 清窗口重跑 open）。订阅面：`subscribe`/`getSnapshot`（恒返缓存引用）——`implements ObservableSnapshot<ConversationSnapshot>`，构造时挂 `useSelector = bindSnapshotSelector(this)`，Session 本身就是 uSES 源。帧分发是一个 switch：`session/event` 帧按 seq 去重（唯一去重键），open 在途时缓冲，否则追加 + 增量 fold；open/缝合按 seq 合并 live 缓冲并去重，`subscribed.lastSeq` 超出窗口尾则回补一次。
+- **ConversationSnapshot**（conversation.ts）：不可变快照契约——`nodes`（fold 产物，surface 序）、`partial`、`runningCalls`、`pending`、`running`、`removed`、`openState`、`hasMore`、`promptError` 等。**引用纪律**（memo 与 uSES 的前提）：顶层对象每变必新；nodes 数组重建但元素引用来自缓存；未变的子结构复用上一快照的引用。
+- **SessionManager**（manager.ts）：实例簇 + 帧总入口 + 会话列表。带 sessionId 的帧只投已存在实例（mux 广播不得把每个会话都实例化）；例外是审批/问答 `requested` 帧——它们不落 history、open 无法回补，故缓冲进 `pendingBuffers`，实例化时回放。
+- **Notifier**（notifier.ts）：两条通知通道，按变更来源取用。`markDirty()`（默认；帧驱动一律用它）按微任务合批——N 次变更、一次通知、一次重渲染；flush 先重建快照缓存再通知。`notifyNow()`（仅用户手势的直接回响）同 tick 重建并通知——受控输入的回响若延到微任务，DOM 会回滚、光标跳尾。帧驱动代码用 notifyNow 会让合批塌回逐帧渲染；禁。
+- **FoldAdapter / PartialAccumulator**：fold 复用核心 SurfaceManager（`@deepseek-ai/dsh-session/surface`），垫哨兵事件使 seq > 0 起头的分页窗口满足核心的 `seq === index` 断言；跨窗口 replace 时降级为容错线性扫描并置 `foldDegraded`。分片完全不进 fold（O(1) 跳过）：累积器把 StreamChunk 折叠成 `AssistantBlock[]`，一次增量只换该块引用；定稿消息到达即在同一批内弃掉累积器（提升无闪烁）。成本模型：一个分片 = 一次字符串拼接 + 一个脏标记；帧风暴下未订阅的 Session 只花那个标记。
+- **ConnectionController**（在 `packages/client/connection`）：开 mux/host 双流、for-await 泵入，代际围栏之内指数退避重连（500ms 翻倍至 10s 封顶、抖动、无限重试）；sinks 单向注入（Controller 不认识 Session）。重连 = 重建：`onConnected` → 列表刷新 + 各已打开会话 resync。对象层只面向 `IApiClient`；Web 承载（HTTP POST 载两个 client→server 象限、SSE 载两个 server→client 象限）与客户端类族归分层 RFC 属地。
+
+## React 面（`packages/client/web-react`）
+
+胶水包就是整条 ctx↔React 边界；组件保持零框架依赖。
+
+- `createSnapshotStore<T>(init, opts)`：插件自有数据与壳观看态的 store 引擎——zustand vanilla + 草稿式更新，缺省 `flush: 'sync'`（受控输入要求同 tick 回响），帧驱动 store 可选 `'raf'` 合批，可选整值 localStorage 持久化，dev 深冻结。Session 对象与快照 store 同构满足 React 消费的唯一数据契约：`ObservableSnapshot<T>`（`getSnapshot`/`subscribe`）。
+- `bindSnapshotSelector(source)`：把一个源绑定为经 uSES-with-selector 的带类型 selector hook。uSES 契约四条按构造成立：getSnapshot 恒返缓存引用；subscribe 是绑定期闭包（引用永稳）；纯 CSR 不传 server snapshot；相等性缺省 `Object.is`，按调用可选 `shallowEqual`。
+- `useInvoke(fn)`：把异步动作包成引用恒定的触发器加 pending 标志；pending 走 per-hook 外部 store 经 uSES 读出（渲染路径零 setState），并发调用计数，invoke 引用永不变。
+- 相等性协议，全链一致：生产端结构共享；消费端以 `Object.is` 或 `shallowEqual` 短路；`React.memo` 浅比较。深比较全链禁止。
+
+## 目录形态
+
+十二个 `packages/client/*` 包（ui-slots、ui-primitives、web-react、connection、runtime、ui-layout、ui-sidebar、ui-conversation、ui-trajectory、ui-theme、i18n、web）加 `apps/web`——vite 应用，壳 boot 导出之上的薄 `main`。插件包的浏览器半边在 `src/client/` 下；**一切构建产物落 `lib/`**——node 半边为 `lib/index.js`/`lib/invariant.js`，浏览器 bundle 为 `lib/client.js`（共享 tsdown client 预设两者皆出；无 `dist/` 目录，`exports["./client"]` 指向 `./lib/client.js`）。依赖方向：`ui-slots ← web-react ← runtime ← ui-*（并列）← web`，ui-primitives/ui-theme/i18n 为零依赖旁路。
+
+多域插件包的 client 半边还按未来包边界再拆——ui-conversation 即样板：
+
+```
+src/client/
+  contract/    the only shared face between domains (types + composed props shares)
+  service.ts   cross-domain orchestration (imports contract only)
+  skeleton/    domain: shell components (ConversationRoot/InputBar/EmptyState/DetailsPanel)
+  chat/        domain: the chat view
+  toolviews/   domain: the tool-row registry and samples
+  apply.ts     the ONLY file allowed to import across domains (assembly point)
+  index.ts     thin re-export shell (contract + apply + components)
+```
+
+域实现文件永不 import 兄弟域——共享面一律走 `contract/`（如 chat 经 `ToolViewResolver` 读面接口消费工具注册表，不碰注册表类）。`scripts/verify-client-domain-graph.ts` 把守分层（contract=0、域=1、apply/index=2；import 只准指向 ≤ 自己的层级；兄弟域边即失败）。将来拆包=每个域目录升格为包+机械改写 import 路径。
+
+## 怎么开发
+
+- **新 UI 功能** = 新插件包：package.json 声明 `dshClient`（+ `inject` 拓扑），浏览器半边写在 `src/client/`（apply 挂服务/建 store、注册 slot 与 toolview），无 host 逻辑时 node 半边保持空 apply，用共享预设构建。把插件加进 host 配置；清单与装载随之自动跟上。
+- **新 slot**：契约合并进 `SlotMap`，owner 处 `define`，经 owner 自己的 `ScopedSlots` 白名单渲染；注册方 `register`，按需带 inject 工厂。永不全局导出组件。
+- **消费新帧类型**：带 sessionId → Session 分发 switch 加一个分支；host 级 → Manager 路由表；UI 需要时给 `ConversationSnapshot` 加字段并守住引用纪律。
+- **状态住哪**：per-session 且要跨切换存续 → Session 对象 / scope 挂账 store；单视图私有（选中、滚动）→ 组件状态；壳观看态（导航、面板宽、偏好）→ `ctx.layout` 的 store；业务数据 → 永远对象层，永不进观看态 store。
+- **通知通道**：帧驱动/异步 = `markDirty` 合批；受控输入需要同 tick 的用户手势直接回响 = `notifyNow`。
+
+## Consequences
+
+token 流不再震荡渲染树：帧风暴对未订阅会话只花一个脏位，对被订阅视图每微任务一次合批重渲染（帧驱动 store 走 raf 合批）。UI 功能以独立插件的粒度装载、失败、停用——一个崩溃的 slot 注册项只黑一张卡，一个装载失败的 bundle 在 UI 切入之前大声报错。接受的代价：loader/模块表机件是团队端到端自持的定制基建；一次成型启动（无渐进渲染）用首屏粒度换装配简单；双类型 program 让「这个文件归哪个聚合」成为开发者偶尔要回答的问题。
+
+## Alternatives considered
+
+| Rejected | One-line reason |
+|---|---|
+| 静态链接的单 SPA bundle | 插件必须由 host 在运行时按配置组合；单体把每个 UI 功能重新耦回一次构建 |
+| window 全局变量 / import map 供共享依赖 | DI require 表让共享显式、大声失败、可替换；全局变量静默泄漏身份与版本 |
+| 业务数据进 zustand 切片 | 事件窗口/累积器是行为状态机，不是扁平切片；对象层保住快照粒度与合批的可控性 |
+| 工具行走字符串键的全局组件注册表 | 工具视图被多个视图共同消费且要按会话差异化——带 scope 过滤的具名服务（`ctx.toolviews`）才是诚实形态 |
+| P-I 就做渐进/Suspense 启动 | 一次成型严格更简单；loader 的按插件状态面已保留，渐进点亮日后可落地而无需重构 |
diff --git a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.i18n.yaml
new file mode 100644
index 0000000000..06fed08671
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-22-slot-type-chain-implementation.md: b4ec761b9777f5dfbd59efde8c472f9be4c2e1b6
+2026-07-22-slot-type-chain-implementation.zh.md: 28b6e4a3db0c87322582125825492703e62371b2
diff --git a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md
new file mode 100644
index 0000000000..b4ec761b97
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md
@@ -0,0 +1,47 @@
+# Agent Note: Slot type-chain hardening — the non-obvious implementation rulings
+
+Status: implemented
+
+English | [中文](2026-07-22-slot-type-chain-implementation.zh.md)
+
+> Scope: why the slot registration/render type chain (`packages/client/ui-slots/src/index.ts`, consumed by `packages/client/web-react/src/scoped-slots.tsx`) is implemented the way it is. The design-level trade-offs (registration-site inference over declaration tables, hand-written whitelists over derived ones) live in the web client architecture RFC; this note pins the five implementation decisions a future editor would otherwise re-litigate or accidentally revert.
+
+## Problem
+
+The hardened chain types every hop from `SlotMap` declaration to rendered component: owner share + framework-standard share + registrant-injected share compose into the component's props, checked at `register()`. Making that constraint hold without false rejections forced five choices that look arbitrary from the code alone — each one exists because the obvious alternative fails in a specific, reproducible way.
+
+## Decision
+
+### 1. `SlotComponent<P>` (bare call signature) instead of `FC<P>` at the registration position
+
+`register()` constrains components as `SlotComponent<ComposedProps<K, NoInfer<I>>>` where `SlotComponent<P> = (props: P) => ReactNode`. React's `FC` carries static fields (`propTypes`, `defaultProps`) whose types reference `P` in covariant positions; assignability between two `FC` instantiations therefore checks those statics too, and the bottom-typed standard share (see ruling 4's `useSession: never`) makes those covariant checks reject components that narrow it — precisely the components the design wants to accept. The bare call signature checks through clean parameter contravariance only. Components stay ordinary functions; nothing observable changes at runtime.
+
+### 2. `NoInfer<I>` pins the registrant share's inference to the inject factory
+
+`I` (the registrant's injected share) must be inferred from the `inject` factory's return type — the single authoritative source. Without `NoInfer`, TS also collects inference candidates from the component parameter position, and a drifted component (consuming a key the factory does not supply) silently WIDENS `I` to make the call check, absorbing the drift instead of reporting it. `NoInfer<I>` at the component position removes that candidate site, so negative sample ⑥ (a hand-drifted copy of the owner share fails at `register`) actually fails — with inference bleed it would pass. If the `NoInfer` ever gets "simplified away", the type-chain spec's expect-error site goes red first.
+
+### 3. `ComposedProps` dispatches on the entry's `owner` key for progressive migration
+
+`ComposedProps<K, I>` composes `owner & standard & I` only when the SlotMap entry declares an `owner` share; entries without one fall back to the legacy full-`props` constraint (`PropsShape`). This conditional is the migration seam: legacy declarations keep compiling unchanged while entries opt into the composed model one at a time, and both forms flow through the same `register()` overload — no parallel API, no flag. Removing the fallback branch is the flip-the-switch moment for the whole repo, not a cleanup.
+
+### 4. The standard share is bottom-typed, and bare `register` bivariance is accepted, not fought
+
+Session slots' framework-supplied hook is constrained as `{ useSession: never }` (`StandardOf`): `never` in a parameter-ish position means any registrant narrowing (e.g. a runtime-typed conversation hook) is accepted, and the responsibility for what actually arrives lives with the injecting renderer. Known boundary rider: for components typed with METHOD syntax or otherwise bivariant parameter positions, TS can accept a `register` call it strictly shouldn't (parameter bivariance is unsound by design in TS). The accepted stance is documented rather than tested: we do not add negative samples that depend on strictness TS does not guarantee — they would pin compiler-version behavior, not our contract. The samples we do pin (six expect-error sites in `packages/client/ui-slots/tests/type-chain.spec.tsx`) all fail for contract reasons.
+
+### 5. `ChildrenChecked` is an opt-in validation layer keyed on the entry's `children` declaration
+
+Sub-slot delegation authority stays a hand-written whitelist (`slots: ScopedSlots<'a' | 'b'>` in the component's own props). `ChildrenChecked<K, P>` adds an optional second check: only when the entry declares `children` does the component's `slots` face get validated against the authorized union (violation collapses `slots` to `never`, surfacing at the register call). Entries without `children` pass through untouched. The hook point is inside `ComposedProps` — i.e. it fires exactly at the registration boundary, not at render — because register is where both halves (entry declaration, component face) are statically visible at once; a render-time check would need runtime plumbing for a purely static guarantee.
+
+## Consequences
+
+The register call site is now the chain's single choke point: share drift, missing inject keys, unauthorized sub-slot faces, and keyed/list option omissions all surface there at compile time, and the six-sample negative spec pins each failure mode. Costs: the conditional types make hover-signatures at register sites noticeably wider; the bottom-typed standard share shifts arrival-type responsibility onto web-react's renderer (documented on `StandardOf`); and the bivariance boundary means one unsound-accept class is knowingly tolerated.
+
+## Alternatives considered
+
+| Rejected | One-line reason |
+|---|---|
+| Keep `FC` and cast at register sites | The casts hide exactly the drift the chain exists to catch; FC statics' covariant noise is the mechanical cause, so remove the noise, not the check |
+| Infer `I` from the component parameter | Inference bleed absorbs props drift silently — negative sample ⑥ becomes unwritable |
+| Big-bang migration to composed props | Every SlotMap declarant lands in one PR; the `owner`-keyed conditional lets entries migrate one by one with both forms live |
+| Test the bivariant-accept edge as a negative sample | Would pin TS soundness behavior we don't own; compiler upgrades would break the spec without any contract change |
+| Derive delegation whitelists from `children` declarations | The hand-written face is the API the component author reads; derivation inverts ownership and was rejected at design level — `ChildrenChecked` validates instead of generating |
diff --git a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md
new file mode 100644
index 0000000000..28b6e4a3db
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md
@@ -0,0 +1,47 @@
+# Agent Note: slot 类型链硬化——五条非显然实现裁定
+
+Status: implemented
+
+[English](2026-07-22-slot-type-chain-implementation.md) | 中文
+
+> 范围：slot 注册/渲染类型链（`packages/client/ui-slots/src/index.ts`，消费方 `packages/client/web-react/src/scoped-slots.tsx`）为什么这样实现。设计层取舍（注册点推断优于声明表、手写白名单优于派生）住 Web 客户端架构 RFC；本文钉住五条实现决定——不写下来，将来的编辑者要么重新争论一遍，要么不经意地回退它们。
+
+## Problem
+
+硬化后的类型链给从 `SlotMap` 声明到组件渲染的每一跳定型：owner 份额 + 框架标配份额 + 注册方注入份额组合成组件 props，在 `register()` 处校验。让这条约束既成立又不误伤，逼出了五个单看代码显得任意的选择——每一个的存在都是因为显然的替代方案会以一种具体的、可复现的方式失败。
+
+## Decision
+
+### 1. 注册位用 `SlotComponent<P>`（裸调用签名）而非 `FC<P>`
+
+`register()` 以 `SlotComponent<ComposedProps<K, NoInfer<I>>>` 约束组件，其中 `SlotComponent<P> = (props: P) => ReactNode`。React 的 `FC` 携带静态字段（`propTypes`、`defaultProps`），其类型在协变位引用 `P`；两个 `FC` 实例化之间的可赋性因此连这些静态位一起查，而 bottom 型的标配份额（见裁定 4 的 `useSession: never`）使这些协变检查拒绝掉收窄它的组件——恰恰是设计想接受的那批组件。裸调用签名只走干净的参数逆变检查。组件仍是普通函数；运行时零可见差异。
+
+### 2. `NoInfer<I>` 把注册方份额的推断钉在 inject 工厂上
+
+`I`（注册方注入份额）必须从 `inject` 工厂的返回类型推断——唯一权威源。没有 `NoInfer` 时，TS 还会从组件参数位收集推断候选，漂移的组件（消费一个工厂并不供给的键）会静默地把 `I` 加宽到让调用通过，把漂移吸收掉而不是报出来。组件位的 `NoInfer<I>` 移除了那个候选位，负样本⑥（owner 份额的手抄漂移件在 register 处失败）才得以成立——有推断渗漏时它会通过。将来若有人把这个 `NoInfer`「顺手简化」掉，类型链 spec 的 expect-error 位会第一个变红。
+
+### 3. `ComposedProps` 按条目的 `owner` 键分派，支撑渐进迁移
+
+`ComposedProps<K, I>` 只在 SlotMap 条目声明了 `owner` 份额时才组合 `owner & standard & I`；未声明的条目回落到 legacy 全量 `props` 约束（`PropsShape`）。这个条件类型就是迁移接缝：legacy 声明原样编译，条目逐个转入组合模型，两种形态走同一个 `register()`——无平行 API、无开关旗。删掉回落分支的那一刻=全仓切换时刻，不是一次清理。
+
+### 4. 标配份额 bottom 型化；裸 `register` 的双变接受面认账不硬测
+
+session 坑的框架供给 hook 约束为 `{ useSession: never }`（`StandardOf`）：参数性位置上的 `never` 意味着任何注册方收窄（如 runtime 定型的会话 hook）都被接受，实际到达什么的类型责任归注入侧渲染器。已知边界搭车项：对以方法语法定型或参数位本就双变的组件，TS 可能接受一个严格意义上不该过的 `register` 调用（参数双变是 TS 的有意不健全）。这个立场以文档记账而不加测试：我们不写依赖 TS 并不承诺的严格性的负样本——那钉住的是编译器版本行为，不是我们的契约。真正钉住的六个 expect-error 位（`packages/client/ui-slots/tests/type-chain.spec.tsx`）全部因契约原因失败。
+
+### 5. `ChildrenChecked` 是按条目 `children` 声明挂载的 opt-in 校验层
+
+子坑转授权威仍是手写白名单（组件自己 props 上的 `slots: ScopedSlots<'a' | 'b'>`）。`ChildrenChecked<K, P>` 加一层可选的第二道检查：仅当条目声明了 `children`，组件的 `slots` 面才对照授权并集校验（越界时 `slots` 坍缩为 `never`，在 register 调用处暴露）。未声明 `children` 的条目原样通过。挂点选在 `ComposedProps` 内部——即恰好在注册边界而非渲染期起效——因为 register 是条目声明与组件面两个半边同时静态可见的唯一位置；渲染期检查要为一个纯静态保证铺运行时管线。
+
+## Consequences
+
+register 调用点成为全链唯一收口：份额漂移、inject 键缺失、越权子坑面、keyed/list options 缺省全部在编译期于此暴露，六样本负样本 spec 逐一钉住失败模式。代价：条件类型让 register 位的悬停签名明显变宽；bottom 型标配份额把到达类型的责任转给 web-react 渲染器（记录于 `StandardOf`）；双变边界意味着一类不健全接受被知情容忍。
+
+## Alternatives considered
+
+| Rejected | One-line reason |
+|---|---|
+| 保留 `FC`、在 register 位 cast | cast 恰好藏起类型链要抓的漂移；FC 静态位的协变噪音是机械成因，该移除噪音而非移除检查 |
+| 从组件参数位推断 `I` | 推断渗漏静默吸收 props 漂移——负样本⑥无从写起 |
+| 组合 props 一次性全仓迁移 | 所有 SlotMap 声明方挤进一个 PR；`owner` 键分派让条目逐个迁移、两形态共存 |
+| 给双变接受边缘加负样本 | 钉住的是我们不拥有的 TS 健全性行为；编译器升级会在契约零变化时打红 spec |
+| 从 `children` 声明派生转授白名单 | 手写面才是组件作者读到的 API；派生反转所有权，设计层已否——`ChildrenChecked` 做校验不做生成 |
diff --git a/.agents/notes/implemented/process/2026-07-19-web-styling-system.i18n.yaml b/.agents/notes/implemented/process/2026-07-19-web-styling-system.i18n.yaml
new file mode 100644
index 0000000000..eacf4ef13d
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-19-web-styling-system.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-19-web-styling-system.md: c80ef0d56a0e57b38fbb52bd07cbc0f69ec85912
+2026-07-19-web-styling-system.zh.md: 59013a4a950196f3a065ac18415f9b5ed42f3ec3
diff --git a/.agents/notes/implemented/process/2026-07-19-web-styling-system.md b/.agents/notes/implemented/process/2026-07-19-web-styling-system.md
new file mode 100644
index 0000000000..c80ef0d56a
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-19-web-styling-system.md
@@ -0,0 +1,61 @@
+# Agent Note: Web styling system — the token framework and engineering constraints
+
+Status: implemented
+
+> Token-system update (2026-07-22): the framework rulings here (CSS Modules + clsx, no component library, no tailwind, tokens-only colors) remain in force, but the two-layer `--bg-*`/`--text-*` token table and its `web-ui/src/style/global.css` home were replaced by the `--dsw-*` static+alias sheets in `packages/client/ui-theme/src/styles/` (dark = `body[data-ds-dark-theme]` override). Current authority: `missions/tasks/20260721-1520-web-plugin-rfc/architecture.md` §15.
+
+English | [中文](2026-07-19-web-styling-system.zh.md)
+
+> Division of labor: this RFC fixes the framework and constraints (rarely changes); [docs/web-styling.md](../../../../docs/web-styling.md) is the living spec (authoritative token values, the coding-rule checklist, the deviation record — it evolves with the implementation). Token changes and new rules go there; only changes to the framework itself come back here (overturning it requires a new RFC).
+
+## Problem
+
+The GUI has no designer supply; styles are written by an agent and reviewed. Without a machine-checkable token system and coding rules, colors/radii/motion drift as literals across components, and dark mode grows into conditional branches scattered inside components.
+
+## Decision
+
+| # | Decision | Content |
+|---|---|---|
+| 1 | **Visual baseline = Chat alignment** | Every value comes from the Chat front-end survey (brand blue `--accent: #3964fe`, gray scale, bubble/sidebar geometry, shadow tiers…); deviation is allowed but must be recorded in the web-styling.md deviation table |
+| 2 | **Two token layers, not three** | The baseline repo uses static→alias→specific three layers; at our size this compresses to "a semantic layer holding real values directly (comments cite the base palette source) + a handful of component-specific slots (`--bg-sidebar`/`--bubble-bg`)" — two layers, all living in `web-ui/src/style/global.css` |
+| 3 | **Font sizes/spacing are not tokenized** | Same decision as the baseline repo: font sizes are written in px inside components and **always paired with a line height** (16/24, 14/22, 12/18); spacing uses multiples of 4; tokenization covers only colors/radii/motion/font stacks/shadows |
+| 4 | **Borders and interaction states use the opacity scheme** | Borders `rgba(0,0,0,.04/.1)`, hover/active `rgba(38,49,72,.06/.1)` — they hold when layered on any elevation background, no new solid grays |
+| 5 | **Dark mode happens only in the token table** | `:root` holds light real values + `[data-theme='dark']` overrides the same-named variables; **component CSS has zero theme selectors**; when a non-token value genuinely must vary by theme, use the "CSS variable bridge" (the component defines a local variable, the theme block only overrides the variable) |
+
+## Engineering constraints
+
+- **CSS Modules + clsx, no component library, no tailwind**: each component has a same-named `.module.css` in the same directory; class names are camelCase, single-adjective state classes are attached via clsx; components pass `className` through.
+- **`composes` is banned**; `:global` only pierces third-party/cross-package class names and never defines new global classes; global utility classes live only in global.css and stay in the single digits (currently `.scrollable`).
+- **PostCSS plugins are currently zero** (vite has no postcss config; flat CSS suffices — adopting nested/custom-media requires recording it in web-styling.md first); CSS Modules type declarations use the wildcard declare in `css-modules.d.ts` (re-evaluate typed-css-modules per-file generation past 20 components).
+- **Dynamic styles go through the CSS variable bridge**: JS writes only variables (`style={{'--x': v}}`), rules stay in CSS; assembling style objects in TSX for theme/state branches is banned.
+- Transitions are always `var(--dur*) var(--ease)` and only transition opacity/transform/background-color/shadow; scroll containers uniformly use `.scrollable` (writing `::-webkit-scrollbar` inside components is banned).
+
+## The execution shape for agents
+
+The spec is maintained as a **review checklist** (web-styling.md §3, 12 items): each item is a decidable "see X, reject" — not a style suggestion — and writing styles and reviewing styles share the same table.
+
+Entry points for common tasks (operational checklists):
+
+- **Styling a new component**: same-named `.module.css` in the same directory, self-check against web-styling.md §3 item by item; colors/radii/motion reference only §1 tokens.
+- **Adding a token**: first add a row to the web-styling.md §1 table (light value + dark column + base palette source comment) → update both the global.css `:root` and `[data-theme='dark']` blocks → only then reference it in a component.
+- **Deviating from a visual-baseline constant** (the geometry/shadow values of web-styling.md §2): record a row in the §5 deviation table first (date/item/reason), then land the code.
+- **A non-token value that must vary by theme** (gradient endpoints and the like): the component defines a local CSS variable and the theme block only overrides the variable (the variable bridge); component CSS keeps zero `[data-theme]` selectors.
+
+## Division of labor with web-styling.md
+
+| Content | Home |
+|---|---|
+| The five framework rules, engineering constraints, why two layers / why font sizes are not tokenized | This RFC (changing it = a new superseding RFC) |
+| Per-token authoritative values (dark included), visual-baseline constants (sidebar/bubble/session-row/input-card geometry), the RPC four-quadrant direction-marker visual vocabulary, the 12 coding rules, the deviation record | web-styling.md (living document, evolves with the implementation) |
+| Value evidence (deepseekchat file:line) | The survey archive has served its purpose; git history keeps it |
+
+## Consequences
+
+Styles converge machine-checkably: colors/radii/motion/shadows reference only the §1 tokens of web-styling.md, dark mode is a single attribute-selector override table, and review runs off the same 12-item checklist the author self-checks against. The cost accepted: font sizes/spacing rely on the paired-line-height and multiples-of-4 disciplines rather than tokens, and any framework change requires a superseding RFC.
+
+## Alternatives considered
+
+| Rejected | One-line reason |
+|---|---|
+| Tokenizing font sizes/spacing | The baseline repo demonstrates convergence without it (the paired-line-height discipline substitutes); a bloated token table dilutes the authority of the color tokens |
+| Dark mode via `prefers-color-scheme` or in-component branches | Attribute-selector whole-table override keeps components oblivious; system preference can be layered onto the toggle later without touching the token mechanism |
diff --git a/.agents/notes/implemented/process/2026-07-19-web-styling-system.zh.md b/.agents/notes/implemented/process/2026-07-19-web-styling-system.zh.md
new file mode 100644
index 0000000000..59013a4a95
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-19-web-styling-system.zh.md
@@ -0,0 +1,61 @@
+# RFC: Web 样式体系——token 框架与工程约束
+
+Status: implemented
+
+> token 体系更新（2026-07-22）：本文框架裁决（CSS Modules + clsx、无组件库、无 tailwind、组件只用 token）仍然生效，但两层 `--bg-*`/`--text-*` token 表及其宿主 `web-ui/src/style/global.css` 已被 `packages/client/ui-theme/src/styles/` 的 `--dsw-*` static+alias 双层表取代（暗色=`body[data-ds-dark-theme]` 覆写）。现行权威：`missions/tasks/20260721-1520-web-plugin-rfc/architecture.md` §15。
+
+[English](2026-07-19-web-styling-system.md) | 中文
+
+> 分工：本 RFC 定框架与约束（少变）；[docs/web-styling.md](../../../../docs/web-styling.md) 是活规范（token 权威值、编码规范打勾清单、偏离记录，随实现演进）。改 token/加规则去那边；动框架本身才回这里（推翻须新 RFC）。
+
+## Problem
+
+GUI 无设计师供给，样式由 agent 编写并 review；没有一套机器可对照的 token 体系与编码规范，颜色/圆角/动效会在组件间字面量漂移，暗色主题会长成组件内散落的条件分支。
+
+## Decision（框架五条）
+
+| # | 决策 | 内容 |
+|---|---|---|
+| 1 | **视觉基线 = Chat 对齐** | 取值全部来自对 Chat 前端调研（品牌蓝 `--accent: #3964fe`、灰阶、气泡/侧边栏几何、阴影分级……）；允许偏离但须在 web-styling.md 偏离表记录 |
+| 2 | **token 两层不三层** | 基线仓是 static→alias→specific 三层；我们体量下压成「语义层直接持实值（注释标 base 色板出处）+ 极少数组件专属槽位（`--bg-sidebar`/`--bubble-bg`）」两层，全部住 `web-ui/src/style/global.css` |
+| 3 | **字号/间距不 token 化** | 基线仓同款决策：字号在组件里写 px 且**成对写行高**（16/24、14/22、12/18），间距用 4 的倍数；token 化只覆盖颜色/圆角/动效/字体栈/阴影 |
+| 4 | **边框与交互态用透明度制** | 边框 `rgba(0,0,0,.04/.1)`、hover/active `rgba(38,49,72,.06/.1)`——叠加在任意海拔底色上都成立，不新造实色灰 |
+| 5 | **暗色只在 token 表做** | `:root` 亮色实值 + `[data-theme='dark']` 覆盖同名变量；**组件 CSS 零主题选择器**；确需按主题换非 token 值时用「CSS 变量桥」（组件定义局部变量、主题块只覆写变量） |
+
+## 工程约束
+
+- **CSS Modules + clsx，无组件库、无 tailwind**：每组件同目录同名 `.module.css`；类名 camelCase、状态类单形容词由 clsx 挂载；组件透传 `className`。
+- **禁 `composes`**；`:global` 仅穿透第三方/跨包类名，不定义新全局类；全局工具类只住 global.css 且个位数（现状 `.scrollable`）。
+- **PostCSS 插件现状为零**（vite 无 postcss 配置，平铺 CSS 即够用；引入 nested/custom-media 前需先记入 web-styling.md）；CSS Modules 类型声明用 `css-modules.d.ts` 通配 declare（组件数超 20 再评估 typed-css-modules 逐文件生成）。
+- **动态样式走 CSS 变量桥**：JS 只写变量（`style={{'--x': v}}`），规则留在 CSS；禁止 TSX 内拼样式对象做主题/状态分支。
+- 过渡一律 `var(--dur*) var(--ease)` 且只过渡 opacity/transform/背景色/阴影；滚动容器统一 `.scrollable`（组件内禁写 `::-webkit-scrollbar`）。
+
+## 给 agent 的执行形态
+
+规范以 **review 对照打勾清单**形态维护（web-styling.md §3，12 条）：每条是可判定的「见 X 即打回」，不是风格建议——写样式与 review 样式共用同一张表。
+
+常见事项的入口（操作清单）：
+
+- **写新组件样式**：同目录同名 `.module.css`，对照 web-styling.md §3 逐条自查；颜色/圆角/动效只引 §1 token。
+- **加一个 token**：先进 web-styling.md §1 表补一行（亮色值+暗色列+base 色板出处注释）→ global.css `:root` 与 `[data-theme='dark']` 两块同步 → 再在组件里引用。
+- **偏离视觉基线常数**（web-styling.md §2 的几何/阴影值）：先在 §5 偏离表记一行（日期/项/理由）再落码。
+- **需要按主题变化的非 token 值**（渐变端点等）：组件定义局部 CSS 变量、主题块只覆写变量（变量桥），组件 CSS 保持零 `[data-theme]` 选择器。
+
+## 与 web-styling.md 的分工
+
+| 内容 | 归属 |
+|---|---|
+| 框架五条、工程约束、为何两层/为何不 token 化字号 | 本 RFC（改=新 RFC 供替） |
+| token 逐项权威值（含暗色）、视觉基线常数（侧边栏/气泡/会话列/输入卡片几何）、RPC 四象限方向符视觉词汇、编码规范 12 条、偏离记录 | web-styling.md（活文档，随实现演进） |
+| 取值证据（deepseekchat file:line） | 调研归档已完成使命，git 历史留档 |
+
+## Consequences
+
+样式收敛到机器可对照：颜色/圆角/动效/阴影只引 web-styling.md §1 token，暗色是单一属性选择器覆盖表，review 与自查共用同一张 12 条清单。接受的代价：字号/间距靠成对行高与 4 倍数纪律而非 token；动框架本身须新 RFC 供替。
+
+## Alternatives considered
+
+| 放弃项 | 一句话理由 |
+|---|---|
+| 字号/间距 token 化 | 基线仓实证不 token 化也能收敛（成对写行高纪律替代）；token 表膨胀降低颜色 token 的权威性 |
+| 暗色用 `prefers-color-scheme` 或组件内分支 | 属性选择器整表覆盖让组件零感知；系统偏好可后续在 toggle 层适配，不动 token 机制 |
diff --git a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml
new file mode 100644
index 0000000000..6b2f1de1e0
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-20-gui-testing-system.md: db1b47566f5aa089ffcb10d130ecde1851b93112
+2026-07-20-gui-testing-system.zh.md: 691c6baf50c1025a09461effd28ac0f1650fb933
diff --git a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.md b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.md
new file mode 100644
index 0000000000..db1b47566f
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.md
@@ -0,0 +1,59 @@
+# Agent Note: GUI testing system — the three-tier structure
+
+Status: implemented
+
+> Path update (2026-07-22, plugin-system refactor): the three-tier philosophy and golden-path method here remain current; homes moved — object-layer specs now live in `packages/client/runtime/tests/` (was web-runtime), wire specs in `packages/client/connection/tests/`, and the `web-ui` coverage exclusion is gone with the package (component specs are per-plugin jsdom suites under each `packages/client/*/tests/`). Current test-system authority: `missions/tasks/20260721-1520-web-plugin-rfc/architecture.md` §18.
+
+English | [中文](2026-07-20-gui-testing-system.zh.md)
+
+> Division of labor: this note covers only the test structure specific to the GUI (`packages/{client,host}/*` + `apps/web`); repo-wide testing policy (tiering principles, the with-key policy, real-implementation-first, REAL-composition) lives in [docs/testing.md](../../../../docs/testing.md) and is not restated here.
+
+## Problem
+
+The GUI stack spans multiple application shapes, and within one shape multiple runtime environments (the Node host, the data protocol layer, the browser object layer, React/DOM); a single-lane test suite cannot give a meaningful signal. Every link needs effective tests of its own, plus the base capability for full-chain testing.
+
+## Decision
+
+Cut along the architecture's natural test seams into three tiers, bottom-up:
+
+| Tier | Under test | Key technique | File location |
+|---|---|---|---|
+| 1 Protocol isomorphism | `AbstractApiClient` + `toFetchHandler` (bidirectional data / rpcId / zod types / SSE streams / batching / timeouts) | **The full chain at the isomorphic point**: `InProcessApiClient(toFetchHandler(脚本化 impl))` skips the network but genuinely runs the wire serialization — zero browser, pure node env | `packages/host/apiproxy/tests/client-handler.spec.ts` |
+| 2 Object-layer orchestration | `Session`/`SessionManager`/`ConnectionController` (state machines and timing: stitching / dedup / paging / optimistic draft clearing / pendingBuffers / reconnect / backoff) | **The "event sequence in → snapshot out" golden path**: programmable fakes + deferreds controlling timing + fake timers controlling backoff | `packages/client/web-runtime/tests/{session,manager,connection,…}.spec.ts` |
+| 3 Browser smoke | Build artifacts × a real browser (the page boots, one conversation round-trips) | Bare playwright library (chromium headless, no @playwright/test framework), minimal pass-through; fixture level + real-host level (self-skips without a key) | `apps/web/tests/smoke-{fixture,real}.e2e.ts` |
+
+Inter-tier discipline: **each tier tests its own layer, upper tiers never re-test lower ones** — smoke only proves the wiring is alive (the fixture level asserts zero `/api` requests and zero pageerror), interaction detail belongs to the verify scripts (see the lane map), wire semantics to tier 1, data semantics to tier 2. Pure-function layers (lineage/partial/notifier/fold-adapter) are tested directly with zero fakes in the same package's tests/ alongside tier 2.
+
+- **Host side** (apiproxy/runtime/webserver): under the repo-wide `test:coverage` gate, per-file 100%.
+- **Client side**: web-runtime **is already under the per-file 100% gate** (12 defensive unreachable arms carry reasoned `/* v8 ignore */` comments); the `vitest.config.ts` coverage.exclude is down to `packages/client/web-ui/src/**` (temporary — lifted progressively as component specs fill in after the component redo); tests still run, the exclusion only keeps web-ui src out of the thresholds. web-ui takes the **jsdom route (landed)**: jsdom + @testing-library/react entered root devDependencies (dev-only), first spec `web-ui/tests/utils.spec.tsx` (utils pure functions + component RTL render + hook uSES probe); the environment uses the per-file `// @vitest-environment jsdom` pragma, zero impact on the other node-env packages.
+- The exclusion is an **explicitly annotated ruling**, not a silent waiver; the lift path = delete the exclude line + add a justified exclusion or the missing tests.
+
+## Lane map
+
+| Scenario | Command | Content | When to run |
+|---|---|---|---|
+| Baseline | `pnpm run test:gui` | Tier 1+2 vitest (`packages/client packages/host`), seconds-fast, no browser, no server | Casually, after touching any GUI source |
+| Browser end-to-end | `pnpm run test:web` | Rebuilds the front-end dist first, then runs the tier-3 two-level smoke (fixture level + real-host level self-skip) | After touching the build surface/boot/carriage; before delivery |
+| Gate | `pnpm run test:coverage` | The repo-wide gate (host-side GUI packages included, client side excluded) | The PR window |
+
+**Division of labor between the verify scripts and vitest**: verify owns browser black-box regression (sequential steps = a user-operation script, one shared browser session, streaming PASS/FAIL output for the agent to locate the break), vitest owns first-class data-layer semantic assertions (reference stability `toBe`, state-machine timing, wire shapes). The two lanes complement each other, neither absorbs the other — scripts do not migrate to vitest (tearing apart an ordered script is a net loss); promoting one means wrapping a spawn shell hooked into the e2e lane, never rewriting the script body.
+
+## Anti-regression discipline
+
+- **Every bug fix pins an assertion**: a browser-visible bug is pinned into the regression section of its owning verify script (one pin = one report line); a data-layer bug is pinned into the matching spec (precedent: the res-close misjudgment pinned in the webserver bridge suite — pure Node, reproduces in seconds, no longer needs the 12s browser sentinel as the only defense).
+- **All-green on fixture is not done, the real host must pass too**: what the fixture short-circuits is exactly the wire carriage chain (node:http bridge close semantics, real network timing); both empirically confirmed bugs hid there. Changes touching connection/bridge/handler/SSE must run `verify-session-real`.
+- The code-on-disk-is-the-answer reconciliation workflow: when a behavior change lands and turns existing cases red, reconcile on the spot (fix the test or fix the code, with the RFC/contract as arbiter); no red left hanging.
+
+## Consequences
+
+Each lane tests its own tier: touching any GUI source gets seconds-fast `test:gui` feedback, wire/object-layer semantics assert in milliseconds in node env, and the browser carries only wiring-liveness smoke. On the gate surface, the host side is fully under per-file 100%; on the client side web-runtime is under the gate while web-ui waits behind the explicitly annotated exclude. The accepted cost: the inter-tier discipline (upper tiers never re-test lower ones) is upheld by review rather than a machine gate, and web-ui's coverage gap persists until component specs fill in after the component redo.
+
+## Alternatives considered
+
+| Rejected | One-line reason |
+|---|---|
+| Single e2e (everything through the browser) | Browser startup is seconds × N slower and timing is uncontrollable; wire/object-layer invariants can be fully asserted in milliseconds in node env |
+| Migrating the verify scripts to vitest | An ordered script shares one browser session; splitting the cases either formalizes it (sequential + shared page) or re-runs the preamble × N; streaming PASS/FAIL output is exactly the agent's locating interface |
+| Reusing FixtureApiClient in tests | The demo script runs on a real clock, tests need deferred hand-controlled timing — orthogonal purposes; forced reuse chains the tests to the demo's rhythm |
+| A standalone vitest config for GUI packages (once designed as vitest.gui.config.ts) | Package-level tests/ are already scanned by the root include; `vitest run packages/client packages/host` path filtering is the tight loop — zero new config |
+| Deferring hooks/component-layer unit tests (the original ruling) | Once deferred as "components are consumables, revisit after the redo"; overturned by the user on 2026-07-20 — **the jsdom mainline enters coverage** (no browser infrastructure in CI is the decisive reason, playwright demoted to a local enhancement), the RTL dependencies entered devDependencies, the first spec landed |
diff --git a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
new file mode 100644
index 0000000000..691c6baf50
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
@@ -0,0 +1,59 @@
+# RFC: GUI 测试体系——三层结构
+
+Status: implemented
+
+> 路径更新（2026-07-22，插件体系重构）：本文三层理念与金路径方法仍为现行；家搬了——对象层 spec 现居 `packages/client/runtime/tests/`（原 web-runtime）、wire spec 现居 `packages/client/connection/tests/`，`web-ui` 覆盖豁免随包消亡（组件 spec 为各 `packages/client/*/tests/` 的 jsdom 套件）。测试体系现行权威：`missions/tasks/20260721-1520-web-plugin-rfc/architecture.md` §18。
+
+[English](2026-07-20-gui-testing-system.md) | 中文
+
+> 分工线：本篇只讲 GUI（`packages/{client,host}/*` + `apps/web`）特有的测试结构；全仓测试政策（分层原则、with-key 政策、真实体优先、REAL-composition）见 [docs/testing.md](../../../../docs/testing.md)，不在此复述。
+
+## Problem
+
+GUI 栈需要考虑多种应用形态，同应用形态内的不同运行环境（Node host、数据协议层、浏览器对象层、React/DOM），单一车道的测试给不了有效信号。需要对各环节都进行有效测试，并具备全链路测试的基础能力
+
+## Decision（三层结构）
+
+贴架构天然测试缝切三层，自底向上：
+
+| 层 | 被测物 | 关键手段 | 文件落点 |
+|---|---|---|---|
+| 1 协议同构层 | `AbstractApiClient` + `toFetchHandler`（双向数据/rpcId/ZOD类型/SSE 流/合批/超时） | **同构点全链**：`InProcessApiClient(toFetchHandler(脚本化 impl))` 不过网络但真跑 wire 序列化——零浏览器、纯 node env | `packages/host/apiproxy/tests/client-handler.spec.ts` |
+| 2 对象层编排 | `Session`/`SessionManager`/`ConnectionController`（状态机与时序：缝合/去重/翻页/乐观清稿/pendingBuffers/重连/退避） | **「事件序列进→快照出」黄金路径**：可编程假体 + deferred 控时序 + fake timers 控退避 | `packages/client/web-runtime/tests/{session,manager,connection,…}.spec.ts` |
+| 3 浏览器 smoke | 构建产物 × 真浏览器（页面起得来、一轮对话跑得通） | playwright 裸库（chromium headless，无 @playwright/test 框架）最简跑通；fixture 级 + 真 host 级（无 key self-skip） | `apps/web/tests/smoke-{fixture,real}.e2e.ts` |
+
+层间纪律：**下层各测各的，上层不重测下层**——smoke 只证接线活着（fixture 级断零 `/api` 请求、零 pageerror），交互细节归 verify 脚本（见车道地图），wire 语义归 1 层，数据语义归 2 层。纯函数层（lineage/partial/notifier/fold-adapter）随 2 层同包 tests/ 零假体直测。
+
+- **host 侧**（apiproxy/runtime/webserver）：进全仓 `test:coverage` 门禁，per-file 100%。
+- **client 侧**：web-runtime **已进 per-file 100% 门禁**（12 处防御性不可达臂带理由 `/* v8 ignore */` 注释）；`vitest.config.ts` coverage.exclude 只剩 `packages/client/web-ui/src/**`（暂时——组件重做后随组件 specs 铺满逐步解除），测试照跑，只是不拉 web-ui src 进阈值。web-ui 走 **jsdom 路线（已落地）**：jsdom + @testing-library/react 入 root devDeps（dev-only），首个 spec `web-ui/tests/utils.spec.tsx`（utils 纯函数 + 组件 RTL render + hook uSES 探针）；环境用 per-file `// @vitest-environment jsdom` pragma，node env 的其他包零影响。
+- 排除是**显式注释的裁决**不是静默豁免；解除路径=删 exclude 行 + 补 justified 排除或补测。
+
+## 车道地图
+
+| 场景 | 命令 | 内容 | 何时跑 |
+|---|---|---|---|
+| 基础 | `pnpm run test:gui` | 1+2 层 vitest（`packages/client packages/host`），秒级、无浏览器无 server | 改 GUI 任意源码后随手跑 |
+| 浏览器端到端 | `pnpm run test:web` | 先重建前端 dist，再跑 3 层双级 smoke（fixture 级 + 真 host 级 self-skip） | 改构建面/boot/承载后；交付前 |
+| 门禁 | `pnpm run test:coverage` | 全仓 gate（host 侧 GUI 包在内，client 侧 excluded） | PR 窗口 |
+
+**verify 脚本与 vitest 的分工**：verify 管浏览器黑盒回归（顺序步骤=用户操作剧本，共享一次浏览器会话，PASS/FAIL 流式输出供 agent 定位断点），vitest 管数据层语义一等断言（引用稳定性 `toBe`、状态机时序、wire 形）。两车道互补不收编——脚本不迁 vitest（拆散有序剧本是负收益），转正时包一层 spawn 壳挂 e2e 车道即可，脚本本体不改写。
+
+## 防回归纪律
+
+- **修一个 bug 钉一条断言**：浏览器可见的 bug 钉进所属 verify 脚本的回归节（一钉一行 report）；数据层 bug 钉进对应 spec（先例：res-close 误判钉在 webserver 桥 suite——纯 Node 秒级复现，不再需要 12s 浏览器哨兵作唯一防线）。
+- **fixture 全绿不算完，真 host 也要过**：fixture 短路的恰是 wire 承载链（node:http 桥 close 语义、真网络时序），两次实证 bug 都藏在那里。改动触及连接/桥/handler/SSE 的，`verify-session-real` 必跑。
+- 落盘代码即答案的对表工作流：行为改动落盘打红既有用例时，当场对表校准（改测试还是改代码以 RFC/契约为裁），不留悬红。
+
+## Consequences
+
+各车道各测各层：改任意 GUI 源码有秒级 `test:gui` 反馈，wire/对象层语义在 node env 毫秒级断言，浏览器只承担接线存活冒烟。门禁面上 host 侧全量进 per-file 100%；client 侧 web-runtime 已进门，web-ui 暂留显式注释的 exclude 之后。接受的代价：层间纪律（上层不重测下层）靠 review 而非机器门禁维持；web-ui 的覆盖缺口持续到组件重做后组件 specs 铺满为止。
+
+## Alternatives considered
+
+| 放弃项 | 一句话理由 |
+|---|---|
+| 单一 e2e （全走浏览器） | 浏览器起步秒级×N 倍慢+时序不可控；wire/对象层不变量在 node env 可毫秒级全断言 |
+| verify 脚本迁 vitest | 有序剧本共享浏览器会话，拆 case 要么形式化（sequential+共享 page）要么重走前置×N；PASS/FAIL 流式输出正是 agent 定位接口 |
+| 测试复用 FixtureApiClient | 演示脚本走真实时钟，测试需要 deferred 手控时序——用途正交，硬复用把测试绑死在演示节奏上 |
+| GUI 包独立 vitest config（曾设计 vitest.gui.config.ts） | 包级 tests/ 本就被根 include 扫到，`vitest run packages/client packages/host` 路径过滤即窄循环——零新 config |
+| hooks/组件层暂缓单测（原裁决） | 曾以「组件是耗材、等重做后再议」暂缓；2026-07-20 用户改判——**jsdom 主线进覆盖率**（CI 无浏览器基建是决定性理由，playwright 降级为本地增强），RTL 依赖入 devDeps、首个 spec 已落 |
diff --git a/.gitignore b/.gitignore
index bb700f23e5..ae9b4b5ddd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -25,3 +25,5 @@ python/sdk-runtime/src/deepseek_harness_runtime/runtime/dsh-jsonrpc-agent-*
 python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/
 python/**/__pycache__/
 python/**/.pytest_cache/
+apps/web/dist/
+.artifacts/
diff --git a/apps/cli/package.json b/apps/cli/package.json
new file mode 100644
index 0000000000..d245ebe705
--- /dev/null
+++ b/apps/cli/package.json
@@ -0,0 +1,23 @@
+{
+  "name": "@deepseek-ai/dsh",
+  "description": "dsh CLI: `dsh web` serves the built web UI over HTTP; `dsh -p` runs one headless task through the in-process ApiProxy carrier",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "bin": {
+    "dsh": "lib/bin.js"
+  },
+  "files": [
+    "lib/bin.js",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-app-boot": "workspace:^",
+    "@deepseek-ai/dsh-frontend": "workspace:^",
+    "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
+    "@deepseek-ai/dsh-host-runtime": "workspace:^",
+    "@deepseek-ai/dsh-host-webserver": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^"
+  }
+}
diff --git a/apps/cli/src/bin.ts b/apps/cli/src/bin.ts
new file mode 100644
index 0000000000..672b5dfb9a
--- /dev/null
+++ b/apps/cli/src/bin.ts
@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * dsh — command-line entry. Coarse dispatch only; each subcommand module owns
+ * its parseArgs. Dynamic imports keep the shapes independent: `web` never
+ * loads the headless consumer, `-p` never loads node:http or the static server.
+ */
+
+import { loadEnv } from '@deepseek-ai/dsh-app-boot'
+
+loadEnv('dsh')
+const argv = process.argv.slice(2)
+
+if (argv[0] === 'web') {
+  const { runWeb } = await import('./web.ts')
+  await runWeb(argv.slice(1))
+} else if (argv.includes('-p') || argv.includes('--prompt')) {
+  const { runHeadless } = await import('./headless.ts')
+  await runHeadless(argv)
+} else {
+  process.stderr.write('usage: dsh web [--port N] | dsh -p "task"\n')
+  process.exit(1)
+}
diff --git a/apps/cli/src/headless.ts b/apps/cli/src/headless.ts
new file mode 100644
index 0000000000..9c35c0e27a
--- /dev/null
+++ b/apps/cli/src/headless.ts
@@ -0,0 +1,104 @@
+/**
+ * `dsh -p "task"` — the headless assembly: startHost + in-process isomorphic
+ * injection (InProcessApiClient over the host handler, so the full carrier
+ * chain — wire serialization, zod, SSE framing — really runs; this is the
+ * protocol's second real consumer). No HTTP server, no port, no dist
+ * resolution. Runs one task turn, prints the final assistant text, exits
+ * (completed → 0, else 1).
+ */
+
+import { parseArgs } from 'node:util'
+import { startHost } from '@deepseek-ai/dsh-host-runtime'
+import { InProcessApiClient } from '@deepseek-ai/dsh-host-apiproxy'
+import type { MuxFrame } from '@deepseek-ai/dsh-host-apiproxy/api'
+import type { RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+
+/** Outcome of one headless turn: aggregated final text plus the turn-end reason kind. */
+interface TurnOutcome {
+  text: string
+  reason: string
+}
+
+/** Unwrap an RpcResponse or fail loud: business errors print and exit 1 (dispose first). */
+async function unwrap<T>(response: RpcResponse<T>, dispose: () => Promise<void>): Promise<T> {
+  if (response.result.ok) return response.result.value
+  const { code, message } = response.result.error
+  process.stderr.write(`dsh: ${code}: ${message}\n`)
+  await dispose()
+  process.exit(1)
+}
+
+/**
+ * Consume mux frames until the task turn ends, per the cli-demo runOneShot
+ * correlation precedent: anchor on the first turn/start whose trigger kind is
+ * 'message' (startup-injected turns are skipped), aggregate text from that
+ * turn's assistant/message events (last one wins), finish on its turn/end.
+ */
+async function consumeUntilTurnEnd(frames: AsyncIterable<RpcRequest<MuxFrame>>, sessionId: SessionId): Promise<TurnOutcome> {
+  let targetTurn: number | undefined
+  let text = ''
+  try {
+    for await (const frame of frames) {
+      const payload = frame.payload
+      if (payload.type === 'stream/error') {
+        process.stderr.write(`dsh: stream error: ${payload.error.message}\n`)
+        return { text, reason: 'error' }
+      }
+      if (payload.type !== 'session/event' || payload.sessionId !== sessionId) continue
+      const event = payload.event
+      if (targetTurn === undefined) {
+        if (event.type === 'turn/start' && event.data.trigger.kind === 'message') targetTurn = event.data.turn
+        continue
+      }
+      if (event.type === 'assistant/message' && event.data.turn === targetTurn) {
+        const joined = event.data.content.filter(block => block.type === 'text').map(block => block.text).join('')
+        if (joined !== '') text = joined
+      }
+      if (event.type === 'turn/end' && event.data.turn === targetTurn) {
+        return { text, reason: event.data.reason.kind }
+      }
+    }
+  } catch (error: unknown) {
+    process.stderr.write(`dsh: event stream failed: ${String(error)}\n`)
+  }
+  return { text, reason: 'error' }
+}
+
+export async function runHeadless(argv: string[]): Promise<void> {
+  const { values } = parseArgs({
+    args: argv,
+    options: { prompt: { type: 'string', short: 'p' } },
+    allowPositionals: false,
+  })
+  const task = values.prompt
+  if (task === undefined || task === '') {
+    process.stderr.write('usage: dsh -p "task"\n')
+    process.exit(1)
+  }
+
+  // A missing DEEPSEEK_API_KEY throws here (plugin load is fail-loud, uncaught by design).
+  const host = await startHost({ boot: { persistenceRoot: './.sessions' } })
+  const api = new InProcessApiClient(host.handler)
+
+  const created = await unwrap(await api.sessions.create({}), host.dispose)
+
+  // Open the stream before prompting so no frame is lost — kept in this order
+  // even though in-process delivery has no race, so the code survives a move
+  // to a remote HTTP carrier unchanged.
+  const abort = new AbortController()
+  const frames = api.events.mux({}, abort.signal)
+  const done = consumeUntilTurnEnd(frames, created.sessionId)
+
+  await unwrap(await api.sessions.prompt({
+    sessionId: created.sessionId,
+    mode: 'queue',
+    content: [{ type: 'text', text: task }],
+  }), host.dispose)
+
+  const outcome = await done
+  process.stdout.write(outcome.text + '\n')
+  abort.abort()
+  await host.dispose()
+  process.exit(outcome.reason === 'completed' ? 0 : 1)
+}
diff --git a/apps/cli/src/web.ts b/apps/cli/src/web.ts
new file mode 100644
index 0000000000..5e03f2bb19
--- /dev/null
+++ b/apps/cli/src/web.ts
@@ -0,0 +1,89 @@
+/**
+ * `dsh web` — the web-shape assembly: startHost + dist resolution +
+ * startWebServer + the URL line + signal wiring. Mixing host and carrier
+ * concerns is this app module's job (packages stay single-sided).
+ */
+
+import { parseArgs } from 'node:util'
+import { networkInterfaces } from 'node:os'
+import { createRequire } from 'node:module'
+import { mountWebPlugins, startHost } from '@deepseek-ai/dsh-host-runtime'
+import { createHostWebPluginRegistry, startWebServer } from '@deepseek-ai/dsh-host-webserver'
+
+export async function runWeb(argv: string[]): Promise<void> {
+  const { values } = parseArgs({
+    args: argv,
+    options: { port: { type: 'string', default: '3080' } },
+    allowPositionals: false,
+  })
+  const port = Number(values.port)
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    process.stderr.write(`dsh web: invalid --port ${values.port}\n`)
+    process.exit(1)
+  }
+
+  // A missing DEEPSEEK_API_KEY throws here (plugin load is fail-loud, uncaught by design).
+  const host = await startHost({ boot: { persistenceRoot: './.sessions' } })
+
+  // Web UI plugin chain: in-memory Loader tree over the eight UI packages,
+  // then the registry that feeds __DSH_BOOT__ and /plugins/<id>/client.js.
+  const mounted = await mountWebPlugins(host.ctx)
+  const webPlugins = createHostWebPluginRegistry({
+    ctx: host.ctx,
+    loader: mounted.loader,
+    resolvePkgJson: mounted.resolvePkgJson,
+    onError: (err: Error) => { process.stderr.write(`dsh web: plugin rescan: ${String(err)}\n`) },
+  })
+  // Published so the webserver invariant companion can audit manifest/bundle
+  // consistency; nothing else reads this key.
+  host.ctx.reflect.provide('webPlugins', webPlugins)
+
+  // Dist location is workspace knowledge of this app: resolved through
+  // @deepseek-ai/dsh-frontend's package exports, not configured.
+  const require = createRequire(import.meta.url)
+  let distIndex: string
+  try {
+    distIndex = require.resolve('@deepseek-ai/dsh-frontend/dist/index.html')
+  } catch {
+    process.stderr.write('dsh web: frontend dist not built; run pnpm --filter @deepseek-ai/dsh-frontend build first\n')
+    await host.dispose()
+    process.exit(1)
+  }
+
+  let exiting = false
+  async function shutdown(code: number): Promise<void> {
+    if (exiting) return
+    exiting = true
+    try {
+      await server.close()
+      await host.dispose()
+    } finally {
+      process.exit(code)
+    }
+  }
+
+  let server: Awaited<ReturnType<typeof startWebServer>>
+  try {
+    server = await startWebServer(
+      { port, distIndex, apiHandler: host.handler, webPlugins },
+      (err: Error) => {
+        process.stderr.write(`dsh web: ${String(err)}\n`)
+        void shutdown(1)
+      },
+    )
+  } catch (error: unknown) {
+    // listen failed (EADDRINUSE…): no server to close, dispose the host directly.
+    process.stderr.write(`dsh web: ${String(error)}\n`)
+    await host.dispose()
+    process.exit(1)
+  }
+
+  // The server binds 0.0.0.0 (remote-container + LAN-browser is the primary scenario);
+  // print the LAN address alongside loopback so the printed URL is copy-usable from outside.
+  const lan = Object.values(networkInterfaces()).flat()
+    .find(iface => iface !== undefined && iface.family === 'IPv4' && !iface.internal)
+  console.log(`dsh web: http://127.0.0.1:${server.port}${lan === undefined ? '' : ` (LAN: http://${lan.address}:${server.port})`}`)
+
+  process.on('SIGTERM', () => { void shutdown(0) })
+  process.on('SIGINT', () => { void shutdown(130) })
+}
diff --git a/apps/cli/tsconfig.json b/apps/cli/tsconfig.json
new file mode 100644
index 0000000000..237de29279
--- /dev/null
+++ b/apps/cli/tsconfig.json
@@ -0,0 +1,18 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    { "path": "../../vendor/cordis" },
+    { "path": "../../packages/host/apiproxy" },
+    { "path": "../../packages/host/runtime" },
+    { "path": "../../packages/host/webserver" },
+    { "path": "../../packages/core/session" },
+    { "path": "../../packages/ui/app-boot" }
+  ]
+}
diff --git a/apps/web/index.html b/apps/web/index.html
new file mode 100644
index 0000000000..fe5901f353
--- /dev/null
+++ b/apps/web/index.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>DeepSeek Harness</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
diff --git a/apps/web/package.json b/apps/web/package.json
new file mode 100644
index 0000000000..1b55f75d0d
--- /dev/null
+++ b/apps/web/package.json
@@ -0,0 +1,37 @@
+{
+  "name": "@deepseek-ai/dsh-frontend",
+  "description": "Web application entry: vite build over the @deepseek-ai/dsh-client-web shell library; dist/ served by apps/cli's dsh web",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./dist/*": "./dist/*",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite",
+    "watch": "vite build --watch"
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-client-web": "workspace:^",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-client-web-react": "workspace:^",
+    "@deepseek-ai/dsh-host-webserver": "workspace:^",
+    "@types/node": "^22.0.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "playwright": "^1.49.0",
+    "typescript": "^6.0.3",
+    "vite": "^6.0.0",
+    "vitest": "^4.1.8"
+  }
+}
diff --git a/apps/web/src/main.ts b/apps/web/src/main.ts
new file mode 100644
index 0000000000..16ae6e9ed9
--- /dev/null
+++ b/apps/web/src/main.ts
@@ -0,0 +1,10 @@
+/**
+ * Web application entry: thin bootstrap over the shell library. Everything —
+ * loader holding, module-table seeding, AppRoot gate, plugin assembly — lives
+ * in @deepseek-ai/dsh-client-web; this file only finds the mount point.
+ */
+import { bootWebShell } from '@deepseek-ai/dsh-client-web'
+
+const el = document.getElementById('root')
+if (el === null) throw new Error('web app: missing #root')
+bootWebShell(el)
diff --git a/apps/web/tests/smoke-fixture.e2e.ts b/apps/web/tests/smoke-fixture.e2e.ts
new file mode 100644
index 0000000000..0c32be5310
--- /dev/null
+++ b/apps/web/tests/smoke-fixture.e2e.ts
@@ -0,0 +1,147 @@
+// Keyless boot-chain smoke over the REAL carrier: startWebServer + web-plugins
+// registry surface + __DSH_BOOT__ injection + built shell dist in a real
+// chromium. First describe: manifest injection + fail-loud half. Second
+// describe: the settled success pass — five REAL tsdown bundles (the
+// infrastructure four + layout) load through the DI chain in ?fixture mode
+// and the three-column frame appears in one flip. The full conversation
+// round lands in smoke-real under the W5 real-host standard.
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import { startWebServer } from '@deepseek-ai/dsh-host-webserver'
+import type { WebPluginBootEntry } from '@deepseek-ai/dsh-host-webserver'
+import { DIST_INDEX, probeFreePort, requireDist, saveFailureShot } from './support.ts'
+
+const bundlePath = (dir: string): string =>
+  fileURLToPath(new URL(`../../../packages/client/${dir}/lib/client.js`, import.meta.url))
+
+/** id ↔ bundle table for the success pass (immediately four + layout). */
+const REAL_PLUGINS: { id: string; dir: string; inject: string[]; immediately?: boolean }[] = [
+  { id: '@deepseek-ai/dsh-client-connection', dir: 'connection', inject: [], immediately: true },
+  { id: '@deepseek-ai/dsh-client-runtime', dir: 'runtime', inject: ['@deepseek-ai/dsh-client-connection'], immediately: true },
+  { id: '@deepseek-ai/dsh-client-ui-theme', dir: 'ui-theme', inject: [], immediately: true },
+  { id: '@deepseek-ai/dsh-client-i18n', dir: 'i18n', inject: [], immediately: true },
+  { id: '@deepseek-ai/dsh-client-ui-layout', dir: 'ui-layout', inject: ['@deepseek-ai/dsh-client-runtime'] },
+]
+
+/** Manifest served by the fake registry: one live bundle row, one missing row. */
+const ROWS: WebPluginBootEntry[] = [
+  { id: '@deepseek-ai/dsh-client-ui-layout', url: '/plugins/@deepseek-ai/dsh-client-ui-layout/client.js', inject: [] },
+  { id: '@probe/absent', url: '/plugins/@probe/absent/client.js', inject: [] },
+]
+const LAYOUT_BUNDLE = bundlePath('ui-layout')
+
+describe('web boot chain (keyless, real carrier)', () => {
+  let server: Awaited<ReturnType<typeof startWebServer>>
+  let browser: Browser
+  let page: Page
+  const pageErrors: string[] = []
+
+  beforeAll(async () => {
+    requireDist()
+    const port = await probeFreePort()
+    const apiHandler = { fetch: () => Promise.resolve(new Response('boot smoke must not call /api', { status: 500 })) }
+    server = await startWebServer({
+      port,
+      distIndex: DIST_INDEX,
+      apiHandler,
+      webPlugins: {
+        snapshot: () => ROWS,
+        clientPath: (id) => (id === ROWS[0]!.id ? LAYOUT_BUNDLE : undefined),
+      },
+    }, (err) => { pageErrors.push(`server: ${String(err)}`) })
+    browser = await chromium.launch()
+    page = await browser.newPage()
+    page.on('pageerror', (e) => pageErrors.push(String(e)))
+    await page.goto(`http://127.0.0.1:${port}/`, { waitUntil: 'load' })
+  })
+
+  afterAll(async () => {
+    await browser?.close()
+    await server?.close()
+  })
+
+  it('GET / injects the manifest verbatim', async () => {
+    onTestFailed(() => saveFailureShot(page, 'smoke-boot-manifest'))
+    const boot = await page.evaluate(() => (window as { __DSH_BOOT__?: unknown }).__DSH_BOOT__)
+    expect(boot).toEqual({ plugins: ROWS })
+  })
+
+  it('serves a real bundle through the plugins endpoint', async () => {
+    const res = await page.request.get(`${new URL(page.url()).origin}${ROWS[0]!.url}`)
+    expect(res.status()).toBe(200)
+    expect(await res.text()).toContain('window.DSHClientProxy.loadPlugin')
+  })
+
+  it('boots to the loading page and fail-louds the absent plugin', async () => {
+    onTestFailed(() => saveFailureShot(page, 'smoke-boot-fail-loud'))
+    await page.waitForSelector('text=HARNESS', { timeout: 10_000 })
+    await page.waitForSelector('text=Failed to load plugins', { timeout: 10_000 })
+    await page.waitForSelector('text=@probe/absent', { timeout: 2000 })
+    // The real UI must not have flipped in: the gate opens only on settled().
+    expect(await page.locator('[class*="frame"]').count()).toBe(0)
+  })
+
+  it('applies the token sheets before any plugin CSS', async () => {
+    const family = await page.evaluate(() => getComputedStyle(document.body).getPropertyValue('--dsw-font-family'))
+    expect(family.trim().length).toBeGreaterThan(0)
+  })
+})
+
+describe('web boot chain success pass (keyless, five real bundles, ?fixture)', () => {
+  const missing = REAL_PLUGINS.filter((p) => !existsSync(bundlePath(p.dir)))
+  let server: Awaited<ReturnType<typeof startWebServer>>
+  let browser: Browser
+  let page: Page
+  const pageErrors: string[] = []
+
+  beforeAll(async () => {
+    requireDist()
+    if (missing.length > 0) throw new Error(`client bundles not built (pnpm --filter <pkg> bundle): ${missing.map((m) => m.dir).join(', ')}`)
+    const port = await probeFreePort()
+    const rows: WebPluginBootEntry[] = REAL_PLUGINS.map((p) => {
+      const row: WebPluginBootEntry = { id: p.id, url: `/plugins/${p.id}/client.js`, inject: p.inject }
+      if (p.immediately === true) row.immediately = true
+      return row
+    })
+    const byId = new Map(REAL_PLUGINS.map((p) => [p.id, bundlePath(p.dir)]))
+    // ?fixture never opens HTTP streams; /api is a tripwire like the first describe.
+    const apiHandler = { fetch: () => Promise.resolve(new Response('fixture mode must not call /api', { status: 500 })) }
+    server = await startWebServer({
+      port,
+      distIndex: DIST_INDEX,
+      apiHandler,
+      webPlugins: { snapshot: () => rows, clientPath: (id) => byId.get(id) },
+    }, (err) => { pageErrors.push(`server: ${String(err)}`) })
+    browser = await chromium.launch()
+    page = await browser.newPage()
+    page.on('pageerror', (e) => pageErrors.push(String(e)))
+    await page.goto(`http://127.0.0.1:${port}/?fixture`, { waitUntil: 'load' })
+  })
+
+  afterAll(async () => {
+    await browser?.close()
+    await server?.close()
+  })
+
+  it('settles and flips to the three-column frame in one pass', async () => {
+    onTestFailed(() => saveFailureShot(page, 'smoke-boot-settled'))
+    await page.waitForSelector('[class*="frame"]', { timeout: 15_000 })
+    // Loading page is gone; the grid carries the three tracks.
+    expect(await page.locator('text=Failed to load plugins').count()).toBe(0)
+    const template = await page.locator('[class*="frame"]').evaluate((el) => getComputedStyle(el).gridTemplateColumns)
+    expect(template.split(' ').length).toBe(3)
+  })
+
+  it('every plugin CSS landed with its ownership tag', async () => {
+    const owners = await page.evaluate(() =>
+      [...document.querySelectorAll('style[data-plugin]')].map((s) => (s as HTMLElement).dataset['plugin']))
+    expect(owners).toContain('@deepseek-ai/dsh-client-ui-layout')
+  })
+
+  it('stayed clean: no page errors across the whole load chain', () => {
+    expect(pageErrors).toEqual([])
+  })
+})
diff --git a/apps/web/tests/smoke-real.e2e.ts b/apps/web/tests/smoke-real.e2e.ts
new file mode 100644
index 0000000000..4e280af0c7
--- /dev/null
+++ b/apps/web/tests/smoke-real.e2e.ts
@@ -0,0 +1,235 @@
+// W5 real-host smoke: spawn `dsh web` with a real key, walk the full W5 flow
+// list in a real chromium, screenshot every screen into .artifacts/ for the
+// figma comparison pass. Self-skips without DEEPSEEK_API_KEY (repo e2e
+// convention); the runner loads the repo-root .env explicitly because the CLI
+// only auto-loads .env from its cwd (a temp dir here, so sessions never land
+// in the repo's .sessions).
+//
+// Selector convention: CSS Modules hash as [hash]_[local], so class-substring
+// selectors are unreliable — anchor on data-* attributes (data-variant /
+// data-clickable / data-sample) or visible text. The one [class*=] use below
+// (frame/handle) rides local names that survive hashing as suffixes; prefer
+// data-* for anything new.
+//
+// Flow order matters: chat rounds first (5 depends on 3's session), geometry
+// and theme after, reload recovery last. Tests run sequentially in-file.
+import type { ChildProcess } from 'node:child_process'
+import { spawn } from 'node:child_process'
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import { REPO_ROOT, probeFreePort, requireDist, saveFailureShot } from './support.ts'
+
+/** Repo-root .env → process.env (never overrides an already-set variable). */
+function loadRootEnv(): void {
+  const envPath = join(REPO_ROOT, '.env')
+  if (!existsSync(envPath)) return
+  for (const line of readFileSync(envPath, 'utf8').split('\n')) {
+    const m = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(line.trim())
+    if (m !== null && process.env[m[1]!] === undefined) process.env[m[1]!] = m[2]
+  }
+}
+loadRootEnv()
+
+function waitForReadyLine(child: ChildProcess): Promise<string> {
+  return new Promise((resolveReady, reject) => {
+    let out = ''
+    const timer = setTimeout(() => reject(new Error(`dsh web not ready in 90s; output:\n${out}`)), 90_000)
+    const onData = (chunk: Buffer): void => {
+      out += chunk.toString()
+      const match = /dsh web: (http:\/\/[^\s]+)/.exec(out)
+      if (match?.[1] !== undefined) {
+        clearTimeout(timer)
+        resolveReady(match[1])
+      }
+    }
+    child.stdout?.on('data', onData)
+    child.stderr?.on('data', onData)
+    child.once('exit', (code) => {
+      clearTimeout(timer)
+      reject(new Error(`dsh web exited early (code ${code}); output:\n${out}`))
+    })
+  })
+}
+
+/** W5 screenshot: evidence for the figma comparison, not a failure artifact. */
+async function screen(page: Page, name: string): Promise<void> {
+  await page.screenshot({ path: join(REPO_ROOT, '.artifacts', `w5-${name}.png`) })
+}
+
+/** First column track (px string) of the frame grid. */
+async function firstTrack(page: Page): Promise<string> {
+  return (await page.locator('[class*="frame"]').evaluate(
+    (el) => getComputedStyle(el).gridTemplateColumns)).split(' ')[0]!
+}
+
+/** Last column track (details) as a number of pixels. */
+async function detailsTrack(page: Page): Promise<number> {
+  const cols = await page.locator('[class*="frame"]').evaluate(
+    (el) => getComputedStyle(el).gridTemplateColumns)
+  return Number(cols.split(' ').pop()!.replace('px', ''))
+}
+
+// Readiness gate: `dsh web` serves ALL eight manifest plugins; until every UI
+// plugin's client bundle exists and exports apply, the loader fail-louds and
+// the frame never appears.
+const UI_PLUGIN_DIRS = ['connection', 'runtime', 'ui-theme', 'i18n', 'ui-layout', 'ui-sidebar', 'ui-conversation', 'ui-trajectory']
+const notReady = UI_PLUGIN_DIRS.filter((dir) => {
+  const bundle = join(REPO_ROOT, 'packages/client', dir, 'lib/client.js')
+  return !existsSync(bundle) || !readFileSync(bundle, 'utf8').includes('exports.apply')
+})
+if (notReady.length > 0) console.warn(`[smoke-real] skipped — client bundles not ready: ${notReady.join(', ')}`)
+
+describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke (real host, real key, W5)', () => {
+  let child: ChildProcess
+  let sessionsDir: string
+  let baseUrl: string
+  let browser: Browser
+  let page: Page
+  const pageErrors: string[] = []
+
+  beforeAll(async () => {
+    requireDist()
+    sessionsDir = mkdtempSync(join(tmpdir(), 'dsh-web-w5-'))
+    const port = await probeFreePort()
+    // tsx boot mirrors demo:web — lib/ may be unbuilt in this worktree. cwd is a
+    // temp dir (persistenceRoot is cwd-relative), so tsx needs the repo's loader
+    // and tsconfig paths pointed at explicitly.
+    const tsxLoader = pathToFileURL(createRequire(join(REPO_ROOT, 'package.json')).resolve('tsx')).href
+    child = spawn(
+      process.execPath,
+      ['--import', tsxLoader, join(REPO_ROOT, 'apps/cli/src/bin.ts'), 'web', '--port', String(port)],
+      {
+        cwd: sessionsDir,
+        env: { ...process.env, TSX_TSCONFIG_PATH: join(REPO_ROOT, 'tsconfig.json') },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      },
+    )
+    baseUrl = (await waitForReadyLine(child)).replace('0.0.0.0', '127.0.0.1')
+    browser = await chromium.launch()
+    page = await browser.newPage({ viewport: { width: 1680, height: 1000 } })
+    page.on('pageerror', (e) => pageErrors.push(String(e)))
+    await page.goto(baseUrl, { waitUntil: 'load' })
+  }, 120_000)
+
+  afterAll(async () => {
+    await browser?.close()
+    if (child !== undefined && child.exitCode === null) {
+      const gone = new Promise<void>((resolveExit) => child.once('exit', () => resolveExit()))
+      child.kill('SIGTERM')
+      await Promise.race([gone, new Promise((r) => setTimeout(r, 10_000).unref())])
+      if (child.exitCode === null) child.kill('SIGKILL')
+    }
+    if (sessionsDir !== undefined) rmSync(sessionsDir, { recursive: true, force: true })
+  })
+
+  it('1 cold start: loading page settles into the three-column frame', async () => {
+    onTestFailed(() => saveFailureShot(page, 'w5-cold-start'))
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+    expect(await page.locator('text=Failed to load plugins').count()).toBe(0)
+    const template = await page.locator('[class*="frame"]').evaluate((el) => getComputedStyle(el).gridTemplateColumns)
+    expect(template.split(' ').length).toBe(3)
+    await screen(page, '01-cold-start')
+  })
+
+  it('2+3 empty-state first send completes a real model round', async () => {
+    onTestFailed(() => saveFailureShot(page, 'w5-first-round'))
+    const input = page.locator('textarea').first()
+    await input.waitFor({ timeout: 10_000 })
+    await screen(page, '02-empty-state')
+    await input.fill('请简单介绍事件溯源，两句话即可，最后以「介绍完毕」结尾')
+    await input.press('Enter')
+    // startSession chain: session mounts, composer moves to the bottom.
+    // Regression pin (P0, 585671106): this send used to white-screen the tree
+    // (scope tag lost to a duplicate inlined runtime instance) — body going
+    // near-empty here means that class of bug is back.
+    await page.waitForFunction(() => document.body.innerText.length > 50, undefined, { timeout: 15_000 })
+    expect(pageErrors).toEqual([])
+    await page.waitForFunction(() => document.body.innerText.includes('介绍完毕'), undefined, { timeout: 120_000 })
+    await screen(page, '04-round-complete')
+  }, 150_000)
+
+  it('4 view tabs: Chat / Trajectory / Waterfall all switch', async () => {
+    onTestFailed(() => saveFailureShot(page, 'w5-tabs'))
+    await page.locator('button', { hasText: /Trajectory/i }).first().click()
+    await screen(page, '05-trajectory-tab')
+    await page.locator('button', { hasText: /Waterfall/i }).first().click()
+    await screen(page, '06-waterfall-tab')
+    await page.locator('button', { hasText: /^Chat$/i }).first().click()
+    await screen(page, '07-back-to-chat')
+  })
+
+  it('5 bash differential rendering: tool row click opens the details column', async () => {
+    onTestFailed(() => saveFailureShot(page, 'w5-tool-details'))
+    const input = page.locator('textarea').first()
+    await input.fill('请用 bash 工具运行命令 echo w5marker 然后告诉我结果')
+    await input.press('Enter')
+    // Wait for the tool ROW, not response text (the reply echoes any marker).
+    // bash renders through the third-party sample registration (data-sample) —
+    // that IS the differential-rendering acceptance; the generic path renders
+    // data-variant rows with the handler on the data-clickable inner row.
+    const toolRow = page.locator('[data-sample], [data-variant] [data-clickable]').first()
+    await toolRow.waitFor({ timeout: 120_000 })
+    await screen(page, '08-bash-round')
+    expect(await detailsTrack(page)).toBe(0)
+    await toolRow.click()
+    // Selection channel: click writes selection + layout.openDetails.
+    await page.waitForFunction(() => {
+      const frame = document.querySelector('[class*="frame"]')
+      if (frame === null) return false
+      return Number(getComputedStyle(frame).gridTemplateColumns.split(' ').pop()!.replace('px', '')) > 0
+    }, undefined, { timeout: 10_000 })
+    await screen(page, '09-details-open')
+  }, 150_000)
+
+  it('6 sidebar drag widens the column and persists across reload', async () => {
+    onTestFailed(() => saveFailureShot(page, 'w5-drag'))
+    const before = await firstTrack(page)
+    const handle = page.locator('[class*="handle"]').first()
+    const box = await handle.boundingBox()
+    expect(box).not.toBeNull()
+    await page.mouse.move(box!.x + box!.width / 2, box!.y + 300)
+    await page.mouse.down()
+    await page.mouse.move(box!.x + 70, box!.y + 300, { steps: 6 })
+    await page.mouse.up()
+    const after = await firstTrack(page)
+    expect(after).not.toBe(before)
+    await screen(page, '10-sidebar-dragged')
+    await page.reload({ waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+    expect(await firstTrack(page)).toBe(after)
+  })
+
+  it('7 dark mode: the body attribute cascades the token sheets', async () => {
+    onTestFailed(() => saveFailureShot(page, 'w5-dark'))
+    // theme.apply === toggling this attribute (v3 §8); no switcher UI owns it
+    // in P-I, so the acceptance drives the documented mechanism directly.
+    const dark = await page.evaluate(() => {
+      document.body.setAttribute('data-ds-dark-theme', '')
+      return getComputedStyle(document.body).backgroundColor
+    })
+    await screen(page, '11-dark-mode')
+    const light = await page.evaluate(() => {
+      document.body.removeAttribute('data-ds-dark-theme')
+      return getComputedStyle(document.body).backgroundColor
+    })
+    expect(dark).not.toBe(light)
+  })
+
+  it('8 reload recovery: history replays after a fresh boot', async () => {
+    onTestFailed(() => saveFailureShot(page, 'w5-reload'))
+    await page.reload({ waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+    await page.waitForFunction(() => document.body.innerText.includes('介绍完毕'), undefined, { timeout: 30_000 })
+    await screen(page, '12-reload-recovery')
+  })
+
+  it('stayed clean: no page errors across every flow', () => {
+    expect(pageErrors).toEqual([])
+  })
+})
diff --git a/apps/web/tests/support.ts b/apps/web/tests/support.ts
new file mode 100644
index 0000000000..7c56fc05c3
--- /dev/null
+++ b/apps/web/tests/support.ts
@@ -0,0 +1,47 @@
+// Shared plumbing for the web smoke tests (dist location, free port, failure shots).
+import { existsSync, mkdirSync } from 'node:fs'
+import { createServer } from 'node:net'
+import { fileURLToPath } from 'node:url'
+import type { Page } from 'playwright'
+
+/** The built page under test; `pnpm run test:web` rebuilds it before running. */
+export const DIST_INDEX = fileURLToPath(new URL('../dist/index.html', import.meta.url))
+
+export const REPO_ROOT = fileURLToPath(new URL('../../..', import.meta.url))
+
+/** Fail loud on a stale checkout instead of testing yesterday's bundle. */
+export function requireDist(): void {
+  if (!existsSync(DIST_INDEX)) {
+    throw new Error('web app dist not built — run `pnpm --filter @deepseek-ai/dsh-frontend build` (pnpm run test:web does this first)')
+  }
+}
+
+/**
+ * OS-assigned free port, released before use. startWebServer echoes
+ * options.port instead of the bound one, so passing 0 directly is unusable.
+ */
+export function probeFreePort(): Promise<number> {
+  return new Promise((resolvePort, reject) => {
+    const probe = createServer()
+    probe.once('error', reject)
+    probe.listen(0, '127.0.0.1', () => {
+      const address = probe.address()
+      if (address === null || typeof address === 'string') {
+        probe.close(() => reject(new Error('port probe returned no address')))
+        return
+      }
+      probe.close(() => resolvePort(address.port))
+    })
+  })
+}
+
+/** Failure evidence goes to the gitignored .artifacts/ (repo convention). */
+export async function saveFailureShot(page: Page, name: string): Promise<void> {
+  const dir = fileURLToPath(new URL('../../../.artifacts', import.meta.url))
+  mkdirSync(dir, { recursive: true })
+  try {
+    await page.screenshot({ path: `${dir}/${name}.png`, fullPage: true })
+  } catch {
+    // Best-effort evidence: a dead page/browser at failure time must not mask the real assertion error.
+  }
+}
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
new file mode 100644
index 0000000000..8cf0acfd37
--- /dev/null
+++ b/apps/web/tsconfig.json
@@ -0,0 +1,22 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "lib/types",
+    "jsx": "react-jsx",
+    "lib": [
+      "ES2024",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": ["node"]
+  },
+  "include": [
+    "src",
+    "tests"
+  ],
+  "references": [
+    { "path": "../../packages/client/web" },
+    { "path": "../../packages/host/webserver" }
+  ]
+}
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
new file mode 100644
index 0000000000..1622371a8a
--- /dev/null
+++ b/apps/web/vite.config.ts
@@ -0,0 +1,26 @@
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+const src = (rel: string): string => fileURLToPath(new URL(rel, import.meta.url))
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    // Workspace packages resolve to SOURCE: package.json exports point at lib
+    // for Node/type consumers, but the browser bundle must compile src directly
+    // so CSS rides vite's pipeline instead of the CSS-externalized lib bundle.
+    // Only the shell's static surface is aliased — UI plugin packages are NOT
+    // bundled here; they arrive as dynamic bundles through the client loader.
+    // Order matters — subpath aliases must win over bare-name prefixes.
+    alias: [
+      { find: /^@deepseek-ai\/dsh-client-web$/, replacement: src('../../packages/client/web/src/boot.tsx') },
+      { find: /^@deepseek-ai\/dsh-client-web-react\/store$/, replacement: src('../../packages/client/web-react/src/store/index.ts') },
+      { find: /^@deepseek-ai\/dsh-client-web-react$/, replacement: src('../../packages/client/web-react/src/index.ts') },
+      { find: /^@deepseek-ai\/dsh-client-ui-slots$/, replacement: src('../../packages/client/ui-slots/src/index.ts') },
+      { find: /^@deepseek-ai\/dsh-client-ui-primitives$/, replacement: src('../../packages/client/ui-primitives/src/index.ts') },
+      { find: /^@deepseek-ai\/dsh-client-runtime\/loader$/, replacement: src('../../packages/client/runtime/src/client/loader/index.ts') },
+      { find: /^@deepseek-ai\/dsh-client-runtime$/, replacement: src('../../packages/client/runtime/src/index.ts') },
+    ],
+  },
+})
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 496c254ef3..730ef09965 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1572,7 +1572,7 @@ export interface Config {
 export type ApprovalPolicy = 'ask' | 'never'
 ```
 
-Source: [`packages/ui/user-approval/src/index.ts:214`](../packages/ui/user-approval/src/index.ts)
+Source: [`packages/ui/user-approval/src/index.ts:198`](../packages/ui/user-approval/src/index.ts)
 
 ## `@deepseek-ai/dsh-web`
 
@@ -1738,6 +1738,14 @@ Source: [`packages/context/workspace-context/src/config.ts:16`](../packages/cont
 These load from a `cordis.yml` entry with no `config:` block; they declare no config surface.
 
 - `@deepseek-ai/dsh-agent` ([`packages/core/agent/src/index.ts`](../packages/core/agent/src/index.ts))
+- `@deepseek-ai/dsh-client-connection` ([`packages/client/connection/src/index.ts`](../packages/client/connection/src/index.ts))
+- `@deepseek-ai/dsh-client-i18n` ([`packages/client/i18n/src/index.ts`](../packages/client/i18n/src/index.ts))
+- `@deepseek-ai/dsh-client-runtime` ([`packages/client/runtime/src/index.ts`](../packages/client/runtime/src/index.ts))
+- `@deepseek-ai/dsh-client-ui-conversation` ([`packages/client/ui-conversation/src/index.ts`](../packages/client/ui-conversation/src/index.ts))
+- `@deepseek-ai/dsh-client-ui-layout` ([`packages/client/ui-layout/src/index.ts`](../packages/client/ui-layout/src/index.ts))
+- `@deepseek-ai/dsh-client-ui-sidebar` ([`packages/client/ui-sidebar/src/index.ts`](../packages/client/ui-sidebar/src/index.ts))
+- `@deepseek-ai/dsh-client-ui-theme` ([`packages/client/ui-theme/src/index.ts`](../packages/client/ui-theme/src/index.ts))
+- `@deepseek-ai/dsh-client-ui-trajectory` ([`packages/client/ui-trajectory/src/index.ts`](../packages/client/ui-trajectory/src/index.ts))
 - `@deepseek-ai/dsh-command-goal` — requires `commands` · `goals` ([`packages/goal/command-goal/src/index.ts`](../packages/goal/command-goal/src/index.ts))
 - `@deepseek-ai/dsh-commands` ([`packages/ui/commands/src/index.ts`](../packages/ui/commands/src/index.ts))
 - `@deepseek-ai/dsh-fs-policy` ([`packages/fs/fs-policy/src/index.ts`](../packages/fs/fs-policy/src/index.ts))
@@ -1774,8 +1782,15 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 - `@deepseek-ai/dsh-agent-loop-testkit` ([`packages/support/agent-loop-testkit/src/index.ts`](../packages/support/agent-loop-testkit/src/index.ts))
 - `@deepseek-ai/dsh-app-boot` ([`packages/ui/app-boot/src/index.ts`](../packages/ui/app-boot/src/index.ts))
 - `@deepseek-ai/dsh-brand` ([`packages/util/brand/src/index.ts`](../packages/util/brand/src/index.ts))
+- `@deepseek-ai/dsh-client-ui-primitives` ([`packages/client/ui-primitives/src/index.ts`](../packages/client/ui-primitives/src/index.ts))
+- `@deepseek-ai/dsh-client-ui-slots` ([`packages/client/ui-slots/src/index.ts`](../packages/client/ui-slots/src/index.ts))
+- `@deepseek-ai/dsh-client-web` ([`packages/client/web/src/index.ts`](../packages/client/web/src/index.ts))
+- `@deepseek-ai/dsh-client-web-react` ([`packages/client/web-react/src/index.ts`](../packages/client/web-react/src/index.ts))
 - `@deepseek-ai/dsh-helper` ([`packages/sdk/helper/src/index.ts`](../packages/sdk/helper/src/index.ts))
 - `@deepseek-ai/dsh-hook-protocol` ([`packages/hooks/hook-protocol/src/index.ts`](../packages/hooks/hook-protocol/src/index.ts))
+- `@deepseek-ai/dsh-host-apiproxy` ([`packages/host/apiproxy/src/index.ts`](../packages/host/apiproxy/src/index.ts))
+- `@deepseek-ai/dsh-host-runtime` ([`packages/host/runtime/src/index.ts`](../packages/host/runtime/src/index.ts))
+- `@deepseek-ai/dsh-host-webserver` ([`packages/host/webserver/src/index.ts`](../packages/host/webserver/src/index.ts))
 - `@deepseek-ai/dsh-jsonrpc-demo` ([`packages/examples/jsonrpc-demo/src/index.ts`](../packages/examples/jsonrpc-demo/src/index.ts))
 - `@deepseek-ai/dsh-loader-smoke` ([`packages/support/loader-smoke/src/index.ts`](../packages/support/loader-smoke/src/index.ts))
 - `@deepseek-ai/dsh-paths` ([`packages/util/paths/src/index.ts`](../packages/util/paths/src/index.ts))
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 0ce13d60ce..c5ce69f64f 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -417,7 +417,7 @@ Ask composed answerers for one decision. Return an outcome to claim the request
 
 Types: [ApprovalOutcome](../core-data-structures/approval.md) · [ApprovalRequest](../core-data-structures/approval.md) · [ApprovalService](../core-data-structures/approval.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/ui/user-approval/src/index.ts:31`](../../packages/ui/user-approval/src/index.ts)
+Source: [`packages/ui/user-approval/src/index.ts:30`](../../packages/ui/user-approval/src/index.ts)
 
 ## `commands/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 86c0ed5663..6aa44bcf63 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -246,7 +246,7 @@ async request(req: ApprovalRequest): Promise<ApprovalOutcome>
 
 Types: [ApprovalOutcome](../core-data-structures/approval.md) · [ApprovalRequest](../core-data-structures/approval.md)
 
-Source: [`packages/ui/user-approval/src/index.ts:229`](../../packages/ui/user-approval/src/index.ts)
+Source: [`packages/ui/user-approval/src/index.ts:213`](../../packages/ui/user-approval/src/index.ts)
 
 ## `ctx.bash` — `BashExecutor` (abstract seam)
 
@@ -1482,7 +1482,7 @@ async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
 
 Types: [AskUserQuestionAnswer](../core-data-structures/user-interaction.md) · [AskUserQuestionRequest](../core-data-structures/user-interaction.md) · [UserInteractionProvider](../core-data-structures/user-interaction.md)
 
-Source: [`packages/ui/user-interaction/src/index.ts:82`](../../packages/ui/user-interaction/src/index.ts)
+Source: [`packages/ui/user-interaction/src/index.ts:50`](../../packages/ui/user-interaction/src/index.ts)
 
 ## `ctx.web` — `WebService`
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 517c08408d..53f01cdc47 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -11,7 +11,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent/cancel-requested` | `emit` | [`packages/core/agent/src/types.ts:201`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
 | `agent/created` | `emit` | [`packages/core/agent/src/types.ts:163`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) |
 | `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:172`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) |
-| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:346`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) |
+| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:346`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), `runtime`, [`tui`](../packages/ui/tui) |
 | `agent/post-step` | `serial` | [`packages/core/agent/src/types.ts:296`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic) |
 | `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:230`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`time-context`](../packages/context/time-context), [`user-approval`](../packages/ui/user-approval) |
 | `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:243`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`acp`](../packages/ui/acp), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) |
@@ -20,20 +20,20 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:311`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
 | `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:272`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
 | `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:214`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:181`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) |
+| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:181`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), [`goal-session`](../packages/goal/goal-session), `runtime`, [`tui`](../packages/ui/tui) |
 | `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:284`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
 | `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:322`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `agent/turn-stop` | `serial` | [`packages/core/agent/src/types.ts:333`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`tool-goal`](../packages/goal/tool-goal) |
-| `approval/request` | `waterfall` | [`packages/ui/user-approval/src/index.ts:31`](../packages/ui/user-approval/src/index.ts) | [`user-approval`](../packages/ui/user-approval) (`waterfall`) | [`acp`](../packages/ui/acp) |
+| `approval/request` | `waterfall` | [`packages/ui/user-approval/src/index.ts:30`](../packages/ui/user-approval/src/index.ts) | [`user-approval`](../packages/ui/user-approval) (`waterfall`) | [`acp`](../packages/ui/acp) |
 | `commands/change` | `emit` | [`packages/ui/commands/src/index.ts:103`](../packages/ui/commands/src/index.ts) | [`commands`](../packages/ui/commands) (`events.dispatch`) | [`acp`](../packages/ui/acp), [`tui`](../packages/ui/tui) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:62`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:71`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:54`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `goal/changed` | `emit` | [`packages/goal/goal/src/types.ts:167`](../packages/goal/goal/src/types.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:52`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-title`](../packages/session-title/session-title) |
-| `session/created` | `emit` | [`packages/core/session/src/index.ts:68`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`user-approval`](../packages/ui/user-approval) |
-| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:78`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-title`](../packages/session-title/session-title) |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:90`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/ui/acp), [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tui`](../packages/ui/tui), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) |
+| `session/created` | `emit` | [`packages/core/session/src/index.ts:68`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`llm-retry`](../packages/llm/llm-retry), `runtime`, [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`user-approval`](../packages/ui/user-approval) |
+| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:78`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `runtime`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-title`](../packages/session-title/session-title) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:90`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/ui/acp), [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), `runtime`, [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tui`](../packages/ui/tui), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) |
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:100`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence) |
 | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:139`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc), [`subagent`](../packages/subagent/subagent) |
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:113`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
@@ -57,7 +57,9 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 
 | Event string | Dispatchers | Listeners |
 | --- | --- | --- |
-| `internal/dispatch` | - | [`compact`](../packages/compact/compact), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`workflow`](../packages/workflow/workflow) |
+| `internal/dispatch` | - | [`compact`](../packages/compact/compact), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), `runtime`, [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`workflow`](../packages/workflow/workflow) |
+| `internal/plugin` | - | `webserver` |
 | `internal/status` | - | [`agent`](../packages/core/agent) |
+| `slots/changed` | `runtime` (`emit`) | - |
 
 Maintenance mode: generated: Cordis event declarations and producer/listener edges are resolved from the repository TypeScript Program.
diff --git a/docs/module-graph.md b/docs/module-graph.md
index f4cba95c2a..fd0fe09a12 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -126,6 +126,20 @@ flowchart TD
     pkg_user_approval["user-approval"]
     pkg_user_interaction["user-interaction"]
   end
+  subgraph group_client["packages/client"]
+    pkg_client_connection["client-connection"]
+    pkg_client_i18n["client-i18n"]
+    pkg_client_runtime["client-runtime"]
+    pkg_client_ui_conversation["client-ui-conversation"]
+    pkg_client_ui_layout["client-ui-layout"]
+    pkg_client_ui_primitives["client-ui-primitives"]
+    pkg_client_ui_sidebar["client-ui-sidebar"]
+    pkg_client_ui_slots["client-ui-slots"]
+    pkg_client_ui_theme["client-ui-theme"]
+    pkg_client_ui_trajectory["client-ui-trajectory"]
+    pkg_client_web["client-web"]
+    pkg_client_web_react["client-web-react"]
+  end
   subgraph group_code_runtime["packages/code-runtime"]
     pkg_code_runtime["code-runtime"]
     pkg_code_runtime_worker["code-runtime-worker"]
@@ -144,6 +158,11 @@ flowchart TD
   subgraph group_guard["packages/guard"]
     pkg_repeat_tool_guard["repeat-tool-guard"]
   end
+  subgraph group_host["packages/host"]
+    pkg_host_apiproxy["host-apiproxy"]
+    pkg_host_runtime["host-runtime"]
+    pkg_host_webserver["host-webserver"]
+  end
   subgraph group_lsp["packages/lsp"]
     pkg_lsp["lsp"]
     pkg_lsp_local["lsp-local"]
@@ -182,8 +201,23 @@ flowchart TD
   pkg_acp_snapshot --> pkg_invariants
   pkg_loader_smoke --> pkg_invariants
   pkg_app_boot --> pkg_invariants
+  pkg_client_connection --> pkg_invariants
+  pkg_client_i18n --> pkg_invariants
+  pkg_client_runtime --> pkg_invariants
+  pkg_client_ui_conversation --> pkg_invariants
+  pkg_client_ui_layout --> pkg_invariants
+  pkg_client_ui_primitives --> pkg_invariants
+  pkg_client_ui_sidebar --> pkg_invariants
+  pkg_client_ui_slots --> pkg_invariants
+  pkg_client_ui_theme --> pkg_invariants
+  pkg_client_ui_trajectory --> pkg_invariants
+  pkg_client_web --> pkg_invariants
+  pkg_client_web_react --> pkg_invariants
   pkg_code_runtime --> pkg_invariants
   pkg_jsonrpc_demo --> pkg_invariants
+  pkg_host_apiproxy --> pkg_invariants
+  pkg_host_runtime --> pkg_invariants
+  pkg_host_webserver --> pkg_invariants
   pkg_llm --> pkg_brand
   pkg_llm --> pkg_invariants
   pkg_code_runtime_worker --> pkg_code_runtime
@@ -666,8 +700,23 @@ flowchart TD
 | [`acp-snapshot`](../packages/support/acp-snapshot) | `support` | [`invariants`](../packages/support/invariants) |
 | [`loader-smoke`](../packages/support/loader-smoke) | `support` | [`invariants`](../packages/support/invariants) |
 | [`app-boot`](../packages/ui/app-boot) | `ui` | [`invariants`](../packages/support/invariants) |
+| [`client-connection`](../packages/client/connection) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-i18n`](../packages/client/i18n) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-runtime`](../packages/client/runtime) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-ui-primitives`](../packages/client/ui-primitives) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-ui-slots`](../packages/client/ui-slots) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-ui-trajectory`](../packages/client/ui-trajectory) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-web`](../packages/client/web) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-web-react`](../packages/client/web-react) | `client` | [`invariants`](../packages/support/invariants) |
 | [`code-runtime`](../packages/code-runtime/code-runtime) | `code-runtime` | [`invariants`](../packages/support/invariants) |
 | [`jsonrpc-demo`](../packages/examples/jsonrpc-demo) | `examples` | [`invariants`](../packages/support/invariants) |
+| [`host-apiproxy`](../packages/host/apiproxy) | `host` | [`invariants`](../packages/support/invariants) |
+| [`host-runtime`](../packages/host/runtime) | `host` | [`invariants`](../packages/support/invariants) |
+| [`host-webserver`](../packages/host/webserver) | `host` | [`invariants`](../packages/support/invariants) |
 | [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants) |
 | [`helper`](../packages/sdk/helper) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 9793d262f5..1948e01041 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -106,7 +106,7 @@ Sources: [`packages/core/session/src/types.ts:276`](../packages/core/session/src
 
 Types: [CallId](core-data-structures/core.md)
 
-Source: [`packages/ui/user-approval/src/index.ts:45`](../packages/ui/user-approval/src/index.ts)
+Source: [`packages/ui/user-approval/src/index.ts:44`](../packages/ui/user-approval/src/index.ts)
 
 #### `approval/decided` — log-only
 
@@ -122,7 +122,7 @@ Source: [`packages/ui/user-approval/src/index.ts:45`](../packages/ui/user-approv
 }
 ```
 
-Source: [`packages/ui/user-approval/src/index.ts:56`](../packages/ui/user-approval/src/index.ts)
+Source: [`packages/ui/user-approval/src/index.ts:55`](../packages/ui/user-approval/src/index.ts)
 
 #### `approval/policy` — log-only
 
@@ -138,7 +138,7 @@ Source: [`packages/ui/user-approval/src/index.ts:56`](../packages/ui/user-approv
 'approval/policy': { policy: ApprovalPolicy }
 ```
 
-Source: [`packages/ui/user-approval/src/index.ts:68`](../packages/ui/user-approval/src/index.ts)
+Source: [`packages/ui/user-approval/src/index.ts:67`](../packages/ui/user-approval/src/index.ts)
 
 ### `assistant/*`
 
diff --git a/docs/web-styling.md b/docs/web-styling.md
new file mode 100644
index 0000000000..d2b07ea2b5
--- /dev/null
+++ b/docs/web-styling.md
@@ -0,0 +1,107 @@
+# Web GUI 样式规范
+
+> **【token 体系已换代——§1 表格仅历史参考】** 本文的 `--bg-*`/`--text-*`/`--accent` token 族与其宿主包 `packages/client/web-ui` 已随插件化重构退役。现行 token 唯一来源=`packages/client/ui-theme/src/styles/` 的 `--dsw-*` 体系（static 色阶+alias 语义层，暗色=`body[data-ds-dark-theme]` 覆写）；组件对账基准=`missions/tasks/20260721-1520-web-plugin-rfc/style-spec.md`。**仍然有效**：工程约束（CSS Modules + clsx、无组件库、无 tailwind、组件禁 hardcode 色值）、字号成对写行高、间距 4 倍数、代码字体栈末位不放 monospace——这些已收编进 architecture.md §15。
+
+> 状态：原「活文档」（随 `packages/client/web-ui` 演进）。视觉基线源自对 deepseekchat 前端仓的实测调研。框架决策与工程约束由 [web-styling-system RFC](../.agents/notes/implemented/process/2026-07-19-web-styling-system.md) 拍板，本文不重复论证。
+
+## 1. 设计 token 表（权威定义）
+
+所有 token 住 `packages/client/web-ui/src/style/global.css`：`:root` 亮色实值，`[data-theme='dark']` 块覆盖同名变量（未补全前列为占位）。组件 CSS 只引 token，不出现字面量色值。
+
+### 1.1 颜色（两层：注释里是 base 色板出处，变量名即语义别名）
+
+| token | 亮色实值 | 暗色（占位） | 用途 |
+| --- | --- | --- | --- |
+| `--bg-base` | `#ffffff` | `#151517` | 页面底 |
+| `--bg-layer` | `#ffffff` | `#232324` | 浮层/面板 |
+| `--bg-sidebar` | `#f9fafb` | `#1b1b1c` | 侧边栏底 |
+| `--text-primary` | `#0f1115` | `#f9fafb` | 正文 |
+| `--text-secondary` | `#61666b` | `#cfd3d6` | 次要文字 |
+| `--text-tertiary` | `#81858c` | `#adb2b8` | 辅助/说明 |
+| `--border-l1` | `rgba(0,0,0,.04)` | `rgba(255,255,255,.06)` | 弱分隔（侧边栏右缘） |
+| `--border-l2` | `rgba(0,0,0,.1)` | `rgba(255,255,255,.12)` | 常规边框 |
+| `--hover-bg` | `rgba(38,49,72,.06)` | `rgba(255,255,255,.08)` | hover 态底 |
+| `--active-bg` | `rgba(38,49,72,.1)` | `rgba(255,255,255,.14)` | 按压/激活态底 |
+| `--accent` | `#3964fe` | `#5686fe` | 品牌蓝（deepseek-500；暗提亮一档） |
+| `--accent-soft` | `#edf3fe` | `#28313f` | 淡品牌底（强调块） |
+| `--accent-item` | `#e4edfd` | `#35363a` | 侧边栏选中条目底 |
+| `--bubble-bg` | `#edf3fe` | `#2c2c2e` | 用户消息气泡底 |
+| `--ok` / `--error` / `--warn` | `#22c55e` / `#ec1313` / `#f59e0b` | 同值 | 语义状态色 |
+| `--text-on-solid` | `#ffffff` | 同值 | 实色底（accent/error 徽标等）上的文字 |
+| `--ok-soft` / `--error-soft` | `#e6faed` / `#fee2e2` | `#233c2c` / `#570c0c` | 语义状态软底（徽章）；green-100/red-100，暗为 900 档 |
+| `--color-frame-mux` / `--color-frame-host` | `#8250df` / `#0969da` | 同值 | RPC 调试面板方向色（自有，非基线） |
+| `--frame-mux-soft` / `--frame-host-soft` | `rgba(130,80,223,.1)` / `rgba(9,105,218,.1)` | 同色 `.24` | 方向色软底（徽章） |
+| `--scroll-color` / `--scroll-color-hover` | `rgba(0,0,0,.08)` / `.15` | `rgba(255,255,255,.15)` / `.24` | 滚动条（`.scrollable` 专用） |
+
+### 1.2 非颜色
+
+| token | 值 | 说明 |
+| --- | --- | --- |
+| `--font-ui` | `Inter, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif` | 正文栈 |
+| `--font-mono` | `Menlo, Monaco, Consolas, 'JetBrains Mono', 'Courier New', sans-serif` | 代码栈；**末位不放 monospace**（防 Windows 中文回退宋体） |
+| `--fw-strong` | `600` | 粗体统一权重 |
+| `--ease` | `cubic-bezier(.4,0,.2,1)` | 唯一缓动曲线 |
+| `--dur` / `--dur-fast` / `--dur-slow` | `.2s` / `.1s` / `.3s` | 过渡三档 |
+| `--radius-s` / `--radius-m` / `--radius-l` / `--radius-bubble` / `--radius-xl` | `8px` / `12px` / `16px` / `22px` / `24px` | 圆角语义档：小控件 / 列表条目与面板内块 / 浮层 / 气泡 / 输入卡片（基线 inputWrapper 同值）；胶囊直接写 `999px` |
+| `--shadow-panel` | `0 0 1px rgba(0,0,0,.2), 0 0 4px rgba(0,0,0,.02), 0 12px 32px rgba(0,0,0,.08)` | 浮层阴影（基线 lv3） |
+| `--shadow-float` | `0 0 1px rgba(0,0,0,.24), 0 4px 12px rgba(0,0,0,.06), 0 16px 48px rgba(0,0,0,.16)` | 强浮动面板（lv3 加强档，如 RPC 调试浮层） |
+| `--shadow-card` | `0 4px 10px rgba(0,0,0,.02), 0 2px 4px rgba(0,0,0,.04)`；暗色 `none` | 输入卡片微阴影（基线：亮色同底靠边框+微影区分，暗色靠提亮底、阴影关闭） |
+
+字号与间距**不 token 化**（基线仓同款决策）：字号在组件里写 px 且**成对写行高**，常用对 16/24（气泡）、14/22（UI 默认）、12/18（辅助）；间距用 4 的倍数。
+
+## 2. 视觉基线（源自 deepseekchat）
+
+- 侧边栏：宽 `260px + 1px` 右边框（`--border-l1`）；底色 `--bg-sidebar`。
+- 侧边栏条目：高 `40px`、圆角 `--radius-m`、字号 14px；hover 底 `--hover-bg` 或 sidebar 专属灰、**选中底 `--accent-item` 且不改文字色**。
+- 侧边栏分组标题：12px / weight 500 / `--text-tertiary` / sticky 顶部（底色同侧边栏遮滚动内容）。
+- 会话列：`max-width: 840px` 居中，<1024px 降 712px。
+- 消息流：**仅用户侧有气泡**——`--bubble-bg` 底、圆角 `--radius-bubble`、padding `10px 16px`、字号 16px/24px、`max-width: calc(100% - 88px)`；**助手侧纯文档流无底色**。
+- 消息操作条：默认 `opacity: 0`，父块 hover/focus-within 淡入（`--dur` + `--ease`）。
+- 输入卡片：与会话列同宽（840px，<1024px 降 712px)居中悬浮（距底留白带）；圆角 `--radius-xl`、边框 `--border-l2`、底 `--bg-base`、阴影 `--shadow-card`；内部上下两段=textarea（16px/24px，min 2 行 max 14 行=336px，镜像 div 自增高）+ 操作行（右下嵌 34px 主圆钮）；focus 无边框/阴影变化（基线同款）。
+- 输入主按钮（拍板 2026-07-20 三连，视觉参照 Codex App）：32px 实心正圆图标钮（内联 SVG）——空闲=`--accent` 底白↑箭头「发送」，运行中原地变 `--accent-soft` 底 accent ■「停止」（同色系不告警、不用红）。**运行中锁输入**（拍板 3，取代早先 hover 菜单方案）：textarea disabled（灰、草稿内容保留可见）、无任何排队/插话菜单，停止是唯一动作；turn 结束解禁并 refocus。键盘 Enter=发送、Ctrl/Meta+Enter=换行（运行中键盘路径随锁失效）。
+- 滚动条：近隐形、hover 加深、`scrollbar-gutter: stable` 不占布局（统一走 `.scrollable`，见 §3-9）。
+- RPC 四象限方向符（官方视觉词汇，空间隐喻：上=去 server、下=来自 server；单线=unary、双线=SSE）：
+
+| 符号 | 象限 | 徽章配色 |
+| --- | --- | --- |
+| `↑` | client-request（unary 出站） | `--accent` / `--accent-soft` |
+| `↓` | server-response（unary 回包） | ok `--ok`/`--ok-soft`，error `--error`/`--error-soft` |
+| `⇟` | server-request（SSE 帧推送） | mux `--color-frame-mux`/`--frame-mux-soft`，host `--color-frame-host`/`--frame-host-soft` |
+| `⇞` | client-response（SSE 侧回应） | `--accent`/`--accent-soft` 降透明度 |
+
+## 3. 样式编码规范（review 对照打勾）
+
+1. 颜色/圆角/动效/字体栈只引 §1 token；组件 CSS 出现字面量色值即打回（渐变遮罩等特效除外，须注释说明）。
+2. 组件 CSS 禁止出现 `[data-theme]` 选择器；暗色差异只在 global.css token 表做。确需按主题换非 token 值（渐变端点等），组件定义局部 CSS 变量、主题块只覆写变量（变量桥）。
+3. 类名 camelCase；状态类用单形容词（`.active` `.show`），由 clsx 挂载：`clsx(styles.x, cond && styles.active, className)`。
+4. 对外组件必须透传 `className` 并合入根元素。
+5. 禁用 `composes`；复用靠 token 与组件抽取。
+6. `:global` 仅用于穿透第三方/跨包类名；禁止用它定义新全局类。
+7. 交互过渡一律 `var(--dur*) var(--ease)`，只过渡 opacity / transform / 背景色 / 阴影；纯 hover 展示型元素包 `@media (hover: hover)`。
+8. hover/active 底色优先用透明度制 token（叠任意海拔底色都成立），不新造实色灰。
+9. 滚动容器统一挂 global.css 的 `.scrollable` 工具类；组件内禁写 `::-webkit-scrollbar`。
+10. 媒体查询写在组件 css 尾部、贴着被覆盖规则；断点当前仅 1024px 一档（会话列降档），加第二档需先记入本文档。
+11. 动态样式 JS 侧只写 CSS 变量（`style={{'--x': v}}`），规则留在 CSS；禁止在 TSX 里拼接样式对象做主题/状态分支。
+12. 文字灰阶只用 `--text-primary/secondary/tertiary` 三级，不新造灰色。
+
+## 4. 文件组织
+
+- `src/style/global.css` 固定分区顺序：① token 表（`:root` + `[data-theme='dark']`）② 全局基础（box-sizing、body、button reset）③ 全局工具类（`.scrollable` 等，总数保持个位数）。
+- `*.module.css` 与组件同目录同名；一个组件一个 module 文件。
+- 类型声明用现有 `css-modules.d.ts` 通配；组件数超 20 再评估引入 tcm 生成精确 `.css.d.ts`。
+- PostCSS 特性白名单：当前**零插件**（平铺 CSS + 原生嵌套按需）；引入 nested/custom-media 需先记入本文档。
+
+## 5. 演进规则与偏离记录
+
+- **加新 token**：先进 §1 表（含暗色占位列）再在组件使用；review 见到未入表的 `--` 新变量即打回（组件局部变量桥除外）。
+- **偏离基线**：与 §2 任一常数不一致的实现，须在下方偏离表记一行（日期/项/理由）。
+- **暗色表补全验收**：`[data-theme='dark']` 覆盖 §1 全部占位列后，用 RPC 面板 + 侧边栏 + 会话流三个界面人工/截图核对一遍，无组件级主题选择器即达标。
+
+| 日期 | 偏离项 | 理由 |
+| --- | --- | --- |
+| （空） | | |
+
+## 6. 相关文档
+
+- [web-styling-system RFC](../.agents/notes/implemented/process/2026-07-19-web-styling-system.md)（框架五条与工程约束的裁决记录）
+- 客户端消费架构与分层协议：[Web 客户端架构 RFC](../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)、[GUI 分层与 RPC 协议 RFC](../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 03dcf7edac..4961a569b5 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -18,6 +18,8 @@ export default tseslint.config(
       '**/*.js',
       '**/*.mjs',
       '*.config.ts', // root tool configs (vitest, tsdown) — no project service
+      '**/tsdown.config.ts', // package build configs — in no tsconfig program, and TS syntax breaks the parserless fallback
+      'packages/client/tsdown.client.ts', // shared client build preset, same standing
     ],
   },
 
@@ -108,6 +110,20 @@ export default tseslint.config(
     },
   },
 
+  // --- client tests: the root program excludes packages/client (host/client
+  // Context merges collide), so the shared project service cannot resolve
+  // them — parse these through the client aggregate explicitly.
+  {
+    files: ['packages/client/*/tests/**/*.ts', 'scripts/client-bundle-purity.spec.ts'],
+    languageOptions: {
+      parserOptions: {
+        projectService: false,
+        project: ['./tsconfig.client.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+
   // --- file-local duplication (all owned TypeScript) ---------------------
   {
     files: ['packages/**/*.ts', 'examples/**/*.ts', 'scripts/**/*.ts', 'website/**/*.ts'],
diff --git a/knip.json b/knip.json
index a0944233e9..cae9a35aa4 100644
--- a/knip.json
+++ b/knip.json
@@ -1,11 +1,29 @@
 {
   "$schema": "https://unpkg.com/knip@5/schema.json",
-  "exclude": ["duplicates"],
-  "ignoreBinaries": ["bwrap", "python3", "sandbox-exec"],
-  "ignoreWorkspaces": ["vendor/*", "python/sdk-runtime"],
+  "exclude": [
+    "duplicates"
+  ],
+  "ignoreBinaries": [
+    "bwrap",
+    "python3",
+    "sandbox-exec"
+  ],
+  "ignoreWorkspaces": [
+    "vendor/*",
+    "python/sdk-runtime"
+  ],
+  "ignoreDependencies": [
+    "lightningcss"
+  ],
   "workspaces": {
     ".": {
-      "project": ["scripts/**/*.ts"]
+      "entry": [
+        "scripts/**/*.mjs"
+      ],
+      "project": [
+        "scripts/**/*.ts",
+        "scripts/**/*.mjs"
+      ]
     },
     "examples": {
       "entry": [
@@ -20,11 +38,93 @@
         "*/tests/**/*.e2e.ts",
         "*/tests/**/*.snapshot.ts"
       ],
-      "project": ["**/*.ts"],
-      "ignoreDependencies": ["@deepseek-ai/.+", "@cordisjs/.+"]
+      "project": [
+        "**/*.ts"
+      ],
+      "ignoreDependencies": [
+        "@deepseek-ai/.+",
+        "@cordisjs/.+"
+      ]
+    },
+    "packages/util/home": {
+      "entry": [
+        "tests/**/*.spec.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
+    },
+    "packages/host/webserver": {
+      "entry": [
+        "tests/**/*.spec.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
+    },
+    "packages/host/runtime": {
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ],
+      "ignoreDependencies": [
+        "@deepseek-ai/dsh-client-.+"
+      ]
+    },
+    "packages/client/web-ui": {
+      "entry": [
+        "tests/**/*.spec.{ts,tsx}"
+      ],
+      "project": [
+        "src/**/*.{ts,tsx}",
+        "tests/**/*.{ts,tsx}"
+      ]
+    },
+    "packages/client/runtime": {
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
+    },
+    "packages/client/ui-primitives": {
+      "entry": [
+        "tests/**/*.spec.tsx"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "src/**/*.tsx",
+        "tests/**/*.tsx"
+      ]
+    },
+    "packages/client/ui-layout": {
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.spec.tsx"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "src/**/*.tsx",
+        "tests/**/*.ts",
+        "tests/**/*.tsx"
+      ],
+      "ignoreDependencies": [
+        "@deepseek-ai/dsh-client-ui-slots"
+      ]
     },
     "website": {
-      "project": ["**/*.ts"],
+      "project": [
+        "**/*.ts"
+      ],
       "ignoreDependencies": [
         "@braintree/sanitize-url",
         "cytoscape",
@@ -34,162 +134,424 @@
       ]
     },
     "packages/*/*": {
-      "entry": ["tests/**/*.spec.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/bash/bash-sandbox": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/context/time-context": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/lsp/lsp-local": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts", "tests/fixture-server.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"],
-      "ignoreDependencies": ["typescript-language-server"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts",
+        "tests/fixture-server.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ],
+      "ignoreDependencies": [
+        "typescript-language-server"
+      ]
     },
     "packages/sandbox/sandbox-local": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/util/brand": {
-      "project": ["src/**/*.ts"]
+      "project": [
+        "src/**/*.ts"
+      ]
     },
     "packages/util/timeout": {
-      "entry": ["tests/**/*.spec.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/util/retention": {
-      "entry": ["tests/**/*.spec.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/support/acp-snapshot": {
-      "entry": ["tests/**/*.spec.ts", "tests/fixtures/fake-acp-agent.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/fixtures/fake-acp-agent.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/support/loader-smoke": {
-      "entry": ["tests/**/*.spec.ts", "tests/fixtures/*.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/fixtures/*.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/core/agent-loop": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/goal/goal": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/goal/goal-session": {
-      "entry": ["tests/**/*.spec.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/goal/tool-goal": {
-      "entry": ["tests/**/*.spec.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/code-runtime/code-runtime-worker": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/llm/llm-deepseek": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/llm/llm-pi-ai": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/session-title/session-title-first-message-llm": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/context/workspace-context": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/util/paths": {
-      "entry": ["tests/**/*.spec.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/web/web-search-exa": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/web/web-search-perplexity": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/workflow/workflow-workerthread": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/web/web-search-deepseek": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/examples/acp-demo": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/ui/jsonrpc": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/ui/commands": {
-      "entry": ["tests/**/*.spec.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/examples/tui-demo": {
-      "entry": ["tests/**/*.spec.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/examples/cli-demo": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/ui/tui": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.snapshot.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.snapshot.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/examples/jsonrpc-demo": {
-      "project": ["src/**/*.ts"]
+      "project": [
+        "src/**/*.ts"
+      ]
     },
     "packages/sdk/create-sdk": {
-      "entry": ["src/bin.ts", "tests/**/*.spec.ts", "tests/**/*.e2e.ts", "tests/**/*.snapshot.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "src/bin.ts",
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts",
+        "tests/**/*.snapshot.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/sdk/scripts": {
-      "entry": ["src/bin.ts", "tests/**/*.spec.ts", "tests/**/*.snapshot.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"],
-      "ignoreDependencies": ["node-addon-require-builtin"]
+      "entry": [
+        "src/bin.ts",
+        "tests/**/*.spec.ts",
+        "tests/**/*.snapshot.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ],
+      "ignoreDependencies": [
+        "node-addon-require-builtin"
+      ]
     },
     "packages/subagent/subagent-spawn": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/subagent/subagent-acp": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts", "tests/mock-acp-server.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts",
+        "tests/mock-acp-server.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/subagent/subagent-subprocess": {
-      "entry": ["tests/**/*.spec.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/fs/tool-fs": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
     },
     "packages/fs/tool-fs-search": {
-      "entry": ["tests/**/*.spec.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"],
-      "ignoreBinaries": ["rg"]
+      "entry": [
+        "tests/**/*.spec.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ],
+      "ignoreBinaries": [
+        "rg"
+      ]
     },
     "packages/mcp/mcp-client": {
-      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts", "tests/fixture-server.ts"],
-      "project": ["src/**/*.ts", "tests/**/*.ts"],
-      "ignoreDependencies": ["@modelcontextprotocol/server-everything", "@modelcontextprotocol/server-filesystem"]
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts",
+        "tests/fixture-server.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ],
+      "ignoreDependencies": [
+        "@modelcontextprotocol/server-everything",
+        "@modelcontextprotocol/server-filesystem"
+      ]
+    },
+    "packages/client/web": {
+      "project": [
+        "src/**/*.ts",
+        "src/**/*.tsx",
+        "tests/**/*.tsx"
+      ],
+      "ignoreDependencies": [
+        "@deepseek-ai/dsh-client-ui-theme",
+        "@deepseek-ai/dsh-client-connection"
+      ]
+    },
+    "apps/web": {
+      "entry": [
+        "tests/**/*.e2e.ts",
+        "tests/support.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ],
+      "ignoreDependencies": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-primitives",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-web-react",
+        "@types/react",
+        "@types/react-dom",
+        "react",
+        "react-dom"
+      ]
     }
   }
 }
diff --git a/package.json b/package.json
index c3998bad0e..9a197588e9 100644
--- a/package.json
+++ b/package.json
@@ -10,12 +10,14 @@
   "workspaces": [
     "vendor/*",
     "packages/*/*",
+    "apps/*",
     "website"
   ],
   "scripts": {
     "build": "tsc -b tsconfig.build.json && tsdown",
+    "build:web": "pnpm --filter @deepseek-ai/dsh-frontend run build",
     "clean:build": "rm -rf .typecheck packages/*/*/lib vendor/*/lib *.tsbuildinfo",
-    "typecheck": "tsc -b tsconfig.json",
+    "typecheck": "tsc -b tsconfig.json tsconfig.client.json",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "duplication": "jscpd --config .jscpd.json packages scripts",
@@ -25,6 +27,8 @@
     "test:snapshot": "vitest run --config vitest.snapshot.config.ts",
     "test:snapshot:record": "DSH_SNAPSHOT=record vitest run --config vitest.snapshot.config.ts --update",
     "test:snapshot:refresh": "DSH_SNAPSHOT=refresh vitest run --config vitest.snapshot.config.ts",
+    "test:web": "npm run build:web && vitest run --config vitest.web.config.ts",
+    "test:gui": "vitest run packages/client packages/host",
     "check:ci": "tsx scripts/run-gates.ts ci-primary",
     "check:ci:static": "tsx scripts/run-gates.ts ci-static",
     "check:ci:lint": "tsx scripts/run-gates.ts ci-lint",
@@ -60,6 +64,7 @@
     "verify-node-next-types": "tsx scripts/verify-node-next-types.ts",
     "verify-runtime-closure": "tsx scripts/verify-runtime-closure.ts",
     "verify-cordis-config": "tsx scripts/verify-cordis-config.ts",
+    "verify-client-domain-graph": "tsx scripts/verify-client-domain-graph.ts",
     "gen-cordis-catalog": "tsx scripts/gen-cordis-catalog.ts",
     "verify-cordis-catalog": "tsx scripts/gen-cordis-catalog.ts --check",
     "gen-cordis-api": "tsx scripts/gen-cordis-api.ts",
@@ -85,11 +90,14 @@
     "demo:code-mode": "node scripts/demo-code-mode.mjs",
     "demo:cordis": "node --expose-internals --import tsx packages/examples/tui-demo/src/bin.ts examples/cordis-agent/cordis.yml",
     "demo:acp": "node --import tsx packages/examples/acp-demo/src/bin.ts --config examples/acp-agent/cordis.yml",
+    "demo:web": "npm run build:web && node --import tsx apps/cli/src/bin.ts web",
     "postinstall": "node scripts/install-lefthook.mjs"
   },
   "devDependencies": {
     "@agentclientprotocol/sdk": "0.25.1",
     "@stylistic/eslint-plugin": "^5.10.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/js-yaml": "^4.0.9",
     "@types/jsdom": "^28.0.3",
     "@types/mdast": "^4.0.4",
@@ -103,6 +111,7 @@
     "jsdom": "29.1.1",
     "knip": "^6.16.1",
     "lefthook": "^2.1.9",
+    "lightningcss": "^1.32.0",
     "mdast-util-from-markdown": "^2.0.3",
     "mdast-util-gfm": "^3.1.0",
     "mermaid": "11.16.0",
diff --git a/packages/client/AGENTS.md b/packages/client/AGENTS.md
new file mode 100644
index 0000000000..cfe932ed65
--- /dev/null
+++ b/packages/client/AGENTS.md
@@ -0,0 +1,71 @@
+# AGENTS.md — Web client stack
+
+Rules for `packages/client/*` (the browser side of the dsh web GUI) plus its build entry `apps/web`. They supplement the repo-wide [conventions](../../AGENTS.md#conventions) and the [package rules](../README.md); read the two architecture notes linked below before structural changes.
+
+Packages here are named with the directory prefix: `@deepseek-ai/dsh-client-<name>`.
+
+## Layering red lines
+
+The stack is three layers with one-way knowledge, settled in the [web client architecture note](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md):
+
+1. **Data object layer** (`web-runtime`, React-free): `ConnectionController` → `SessionManager` → `Session` own all business state (event windows, streaming accumulation, reconnect machine). Zero React imports — grep-assertable.
+2. **Hooks layer** (`web-ui/src/hooks`, pure data): subscribes to object snapshots via `useSyncExternalStore`, exposes plain-data handles. No JSX, no DOM.
+3. **Presentation components** (`web-ui`, pure props): consumables, expected to be rewritten wholesale. Business logic must not leak into them; they receive data and callbacks through props only.
+
+Non-negotiables across the layers:
+
+- **No business objects in the store.** zustand carries cross-view presentation state only (`rpcLog`, `ui`, `connection` slices). Sessions, frames, and connections live in the object layer. View-local facts (selection, expansion) stay in component state, not the store.
+- **rpcId is strictly bidirectional**: the initiator mints, the responder echoes; business signatures see only `RpcRequest<P>`, minting stays in the carrier layer ([layering and RPC protocol note](../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)).
+- **Notifier dual-channel discipline**: `notifyNow` only as the direct echo of a user gesture; frame-driven updates always go through `markDirty` (microtask-batched). See `web-runtime/src/session/notifier.ts`.
+- **The web layer is pure presentation.** Nothing that is "how to draw" (tool-card views, queue states) enters the session log; the host computes such data per frame or pushes it live, and replay recomputes it — falling back to the generic form when it can't. A new *model-visible* input still requires a session event (repo-wide rule).
+
+## Directory regime (`web-ui/src`)
+
+> Shell restructure in progress: the tree is converging to this layout (today's `components/{conversation,sessions,panels}` migrate into it); the regime below is the target every new feature follows now.
+
+Two-level feature directories, one contributor per directory — physical conflict avoidance:
+
+```
+web-ui/src/
+  shell/                  # AppShell + the three slot registries + builtins
+  leftmenu/<bar>/         # one directory per left-nav bar (sessions, rpclog, …)
+  sessiontabs/<tab>/      # one directory per session tab (conversation, gantt, …)
+  components/             # shared leaves (MessageText, JsonBlock, …)
+  hooks/ utils/ style/    # cross-cutting; not feature-owned
+```
+
+- `leftmenu/<a>` must not import `leftmenu/<b>` or `sessiontabs/*` (and vice versa). Anything two features need sinks into `components/`.
+- Bars, tabs, and detail blocks register through the `shell/` registries (module-level map, `register*()` returns the disposer — same shape as `toolCardRegistry`). v1 registration is static in `shell/builtins.ts`; plugin-driven registration later calls the same functions.
+- **Claiming a placeholder slot**: pick a `placeholder: true` tab (or add a bar) in `shell/builtins.ts`, create your feature directory, and replace the placeholder component with your container. Don't build features outside this regime.
+
+## Styling
+
+[docs/web-styling.md](../../docs/web-styling.md) is authoritative. In short: design tokens live in `web-ui/src/style/global.css` (`:root` light values, `[data-theme='dark']` overrides); component CSS references tokens only — no literal color values. CSS Modules + `clsx`; no component library, no tailwind ([framework ruling](../../.agents/notes/implemented/process/2026-07-19-web-styling-system.md)). Product copy is Chinese; code comments are English.
+
+## Testing and coverage
+
+The GUI test structure (three tiers, lane map) is settled in the [GUI testing system note](../../.agents/notes/implemented/process/2026-07-20-gui-testing-system.md); repo-wide policy in [docs/testing.md](../../docs/testing.md).
+
+- **Both client packages are inside the per-file 100% coverage gate** (`pnpm run test:coverage`). `web-runtime` is covered by node-env object/protocol suites; `web-ui` rides the jsdom lane. Genuinely unreachable defensive arms take a `/* v8 ignore -- <reason> */` comment with a real reason, never a bare ignore.
+- **web-ui specs are end-to-end behavior checks, not unit tests.** A jsdom spec renders the component with realistic props (or a driven fixture runtime) and asserts what the user would see — never class names, hook internals, or render counts. Components are consumables: behavior-shaped specs survive a rewrite, implementation-shaped specs don't.
+- The jsdom environment comes from a per-file `// @vitest-environment jsdom` pragma on the spec's first line — the shared config stays node-env. Start a new spec from an existing one (`web-ui/tests/tool-card.spec.tsx` is a good template).
+- **Each tier asserts its own layer.** Data-layer semantics (state machines, wire shapes, reference stability) belong to the `web-runtime` and `apiproxy` suites — don't re-assert them from component specs.
+
+## Before you push: the local check ladder
+
+Run the narrowest rung that covers what you touched; escalate only when the change surface demands it.
+
+1. **Every GUI code change** — `pnpm run test:gui` (seconds; no browser, no server): the client suites plus the host-side GUI packages. This is the inner loop; run it as freely as a typecheck.
+2. **Changes to the build surface, boot wiring, or static serving** (`apps/web`, vite config, `dsh-host-webserver`) — additionally `pnpm run test:web`: rebuilds the frontend dist, then runs the browser smoke pair (the real-host case self-skips without `DEEPSEEK_API_KEY`).
+3. **Before a PR** — `pnpm run check:pre-push` (the repo-wide gate ladder). Between PR windows this rung is not expected on every commit.
+
+If `test:gui` is red on code you did not touch, neither silently fix nor ignore it: note it in your handoff so it lands in the next PR window's sweep.
+
+## New component checklist
+
+1. Claim the slot (see the directory regime above): one feature, one directory.
+2. Build the container in your feature directory; keep leaves pure-props. Wire data through the hooks layer, not by importing business objects into components.
+3. Copy a neighbouring jsdom spec into `web-ui/tests/`, keep it behavior-shaped: start from the happy path and the edge states, then widen until the component's branches are covered — the coverage gate applies; only the assertion style stays behavior-level.
+4. Tokens only in CSS; Chinese product copy; English comments.
+5. `pnpm run test:gui` green (plus `test:web` if you touched the build surface).
+6. Non-trivial change? It needs an Agent Note in the same PR (repo-wide rule) — the three GUI notes above are the precedents to extend.
diff --git a/packages/client/connection/README.md b/packages/client/connection/README.md
new file mode 100644
index 0000000000..a35c9c3d0c
--- /dev/null
+++ b/packages/client/connection/README.md
@@ -0,0 +1,16 @@
+# @deepseek-ai/dsh-client-connection
+
+Wire consumer layer (moved verbatim from web-runtime): IApiClient family (WebApiClient/FixtureApiClient), ConnectionController (SSE dual-stream + backoff reconnect), WEB_EVENTS. Contract: api-contracts v3 §3, export inventory in §3.2.
+
+## Model Experience
+
+None, as the wire consumer layer moves already-composed messages between browser and host; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **history's implicit resume is arguable** — opening history on an unattached session pulls an agent up host-side; the pure-persistence-read alternative is recorded in the rt-core reconciliation ledger, unchanged in P-I. This package's consumers see it as latency on first open.
+- **`ToolEventView`/`ToolCallView`/`ToolResultView` re-exports are scheduled for removal** — they fall when the toolview migration deletes the host `viewFor` line (presentation belongs to the client); the fixture keeps a local `viewFor` mirror until then.
diff --git a/packages/client/connection/package.json b/packages/client/connection/package.json
new file mode 100644
index 0000000000..778b431b71
--- /dev/null
+++ b/packages/client/connection/package.json
@@ -0,0 +1,53 @@
+{
+  "name": "@deepseek-ai/dsh-client-connection",
+  "description": "Wire consumer layer: IApiClient subclasses, ConnectionController (SSE dual-stream + reconnect), fixture api (no cordis)",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [],
+    "platform": "web",
+    "immediately": true
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/client/connection/src/client/api.ts b/packages/client/connection/src/client/api.ts
new file mode 100644
index 0000000000..704f028925
--- /dev/null
+++ b/packages/client/connection/src/client/api.ts
@@ -0,0 +1,47 @@
+// Central contract re-export point: every contract import inside
+// web-runtime goes through this single file.
+// Types are type-only imports from the apiproxy api/ layer (zero Node deps, browser-safe);
+// the only runtime values are the RpcId constructor and the AbstractApiClient seam.
+// NEVER import the package root: it drags bootHost/cordis into the browser bundle.
+// The ./api and ./client subpath exports are the browser-safe channels added for this.
+
+export type {
+  ApiProxy, SessionsApi, SessionSummary, HostApi, EventsApi, MuxFrame, HostFrame,
+  ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, ToolEventView,
+} from '@deepseek-ai/dsh-host-apiproxy/api'
+export type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools/presentation'
+export type {
+  RpcRequest, RpcResponse, RpcResult, RpcError, RpcErrorCode,
+  ClientRequest, ServerResponse, ServerRequest, ClientResponse, RpcMessage, RpcReceipt,
+} from '@deepseek-ai/dsh-host-apiproxy/api'
+export { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api'
+export { AbstractApiClient } from '@deepseek-ai/dsh-host-apiproxy/client'
+export type { IApiClient } from '@deepseek-ai/dsh-host-apiproxy/client'
+export type { SessionId, SessionEvent } from '@deepseek-ai/dsh-session/types'
+export type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm/types'
+
+import type { RpcResponse, RpcResult } from '@deepseek-ai/dsh-host-apiproxy/api'
+
+/**
+ * Unwrap a unary response: RpcResponse<T> -> RpcResult<T> (business code only
+ * cares about the result slot).
+ * @param response - the unary response.
+ * @returns its result slot.
+ */
+export function resultOf<T>(response: RpcResponse<T>): RpcResult<T> {
+  return response.result
+}
+
+/**
+ * Fold a transport exception into the RpcResult error branch (unified error
+ * surface; 'internal' as the catch-all code).
+ * @param error - the thrown value from the carrier.
+ * @returns the error branch of an RpcResult.
+ */
+export function transportError<T>(error: unknown): RpcResult<T> {
+  return {
+    ok: false,
+    error: { code: 'internal', message: error instanceof Error ? error.message : String(error), details: {} },
+  }
+}
+
diff --git a/packages/client/connection/src/client/connection.ts b/packages/client/connection/src/client/connection.ts
new file mode 100644
index 0000000000..6eb6491e2f
--- /dev/null
+++ b/packages/client/connection/src/client/connection.ts
@@ -0,0 +1,190 @@
+import type { IApiClient, HostFrame, MuxFrame, RpcRequest } from './api.ts'
+
+/** Reconnect/backoff tunables (deployment-varying — no hardcoded tunables; web-cordis §B.1 lists
+ *  these as the future `ctx.connection` plugin Config). All fields optional; defaults below. */
+export interface ConnectionConfig {
+  /** First-retry backoff cap in ms (jittered: actual delay is cap/2..cap). */
+  backoffBaseMs?: number
+  /** Exponential growth factor per consecutive failed attempt. */
+  backoffFactor?: number
+  /** Upper bound for the backoff cap in ms. */
+  backoffMaxMs?: number
+  /** Cap on waiting for both streams' onOpen before onConnected, in ms. The strict handshake
+   *  (audit C2) waits for mux+host stream establishment plus describe; a carrier that never
+   *  fires onOpen (misbehaving proxy) must not wedge the connection forever — on timeout the
+   *  generation proceeds as connected and the live-gap repair path (audit S3) covers stragglers. */
+  streamOpenTimeoutMs?: number
+}
+
+const CONNECTION_DEFAULTS: Required<ConnectionConfig> = {
+  backoffBaseMs: 500,
+  backoffFactor: 2,
+  backoffMaxMs: 10_000,
+  streamOpenTimeoutMs: 3_000,
+}
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const t = setTimeout(done, ms)
+    signal.addEventListener('abort', done, { once: true })
+    function done(): void {
+      clearTimeout(t)
+      signal.removeEventListener('abort', done)
+      resolve()
+    }
+  })
+}
+
+/** Coarse connection state for the UI (audit C1): 'connected' after each generation's handshake,
+ *  'reconnecting' the moment the generation fails (covers the whole backoff+retry span). */
+export type ConnectionState = 'connected' | 'reconnecting'
+
+/** Frame sink callbacks: the Controller owns the physical streams; business dispatch belongs to
+ *  SessionManager. */
+export interface ConnectionSinks {
+  onMuxEnvelope?: (envelope: RpcRequest<MuxFrame>) => void
+  onHostEnvelope?: (envelope: RpcRequest<HostFrame>) => void
+  /** After each connection generation is established (both streams open + describe succeeded), first connect included. */
+  onConnected?: () => void
+  /** Coarse state transitions (deduplicated: fires only on change). The initial pre-connect
+   *  span reports nothing — the UI treats "no state yet" as connecting, not as an outage. */
+  onStateChange?: (state: ConnectionState) => void
+}
+
+/**
+ * Opens both streams and keeps iterating (pull mode: nothing reads the socket and the tap
+ * never fires unless someone for-awaits), reconnecting with exponential backoff on loss.
+ * State (generation/attempt) is instance-private, never in the store.
+ * The pump body feeds each frame to a sink (sink exceptions must
+ * not kill the pump — a broken business layer must not drag down the connection layer).
+ */
+export class ConnectionController {
+  private generation = 0
+  private attempt = 0
+  private current: AbortController | null = null
+  private running = false
+  private lastState: ConnectionState | null = null
+  private readonly config: Required<ConnectionConfig>
+
+  constructor(
+    private readonly api: IApiClient,
+    private readonly sinks: ConnectionSinks = {},
+    config: ConnectionConfig = {},
+  ) {
+    this.config = { ...CONNECTION_DEFAULTS, ...config }
+  }
+
+  /** Idempotent: begin the connect/pump/reconnect loop. */
+  start(): void {
+    if (this.running) return
+    this.running = true
+    void this.loop()
+  }
+
+  /** Stop the loop and abort the current generation's streams. */
+  stop(): void {
+    this.running = false
+    this.current?.abort()
+    this.current = null
+  }
+
+  private backoffDelay(attempt: number): number {
+    const { backoffBaseMs, backoffFactor, backoffMaxMs } = this.config
+    const cap = Math.min(backoffMaxMs, backoffBaseMs * backoffFactor ** Math.max(0, attempt - 1))
+    return cap / 2 + Math.random() * (cap / 2)
+  }
+
+  /** Read through a method: stop() flips the flag across awaits, so narrowing from the loop condition must not stick. */
+  private isRunning(): boolean {
+    return this.running
+  }
+
+  private async loop(): Promise<void> {
+    while (this.running) {
+      const gen = ++this.generation
+      const ac = new AbortController()
+      this.current = ac
+
+      /* v8 ignore next -- initializer placeholder: the Promise executor
+       * below runs synchronously and replaces it before anyone can call it. */
+      let muxOpened = (): void => {}
+      /* v8 ignore next -- same placeholder pattern as muxOpened. */
+      let hostOpened = (): void => {}
+      const streamsOpen = Promise.all([
+        new Promise<void>((resolve) => { muxOpened = resolve }),
+        new Promise<void>((resolve) => { hostOpened = resolve }),
+      ])
+
+      const failed = new Promise<void>((resolve) => {
+        const settle = (): void => {
+          if (gen === this.generation && !ac.signal.aborted) ac.abort()
+          resolve()
+        }
+        void this.pumpStream(this.api.events.mux({}, ac.signal, muxOpened), this.sinks.onMuxEnvelope, settle)
+        void this.pumpStream(this.api.events.host({}, ac.signal, hostOpened), this.sinks.onHostEnvelope, settle)
+      })
+
+      try {
+        // Strict readiness handshake (audit C2): describe proves unary reachability, onOpen
+        // proves each SSE transport is established (response headers in, before any frame) —
+        // only then may onConnected fire, so the resync it triggers cannot outrun the
+        // subscribed baseline. The timeout guards against a carrier that never fires onOpen
+        // (see ConnectionConfig.streamOpenTimeoutMs).
+        const timeout = new AbortController()
+        await Promise.all([
+          this.api.host.describe({}),
+          Promise.race([streamsOpen, sleep(this.config.streamOpenTimeoutMs, timeout.signal)]),
+        ])
+        timeout.abort()
+        if (ac.signal.aborted) throw new Error('generation aborted during readiness handshake')
+        this.attempt = 0
+        this.emitState('connected')
+        this.callSink(this.sinks.onConnected)
+      } catch {
+        // Transport failure: treat as generation failure, fall through to the shared backoff.
+        if (!ac.signal.aborted) ac.abort()
+      }
+
+      await failed
+      if (!this.isRunning()) return
+      this.emitState('reconnecting')
+      this.attempt += 1
+      console.warn(`[web-runtime] connection lost, retry #${this.attempt}`)
+      const idle = new AbortController()
+      await sleep(this.backoffDelay(this.attempt), idle.signal)
+    }
+  }
+
+  /** Deduplicated state emission (sink isolation applies). */
+  private emitState(state: ConnectionState): void {
+    if (this.lastState === state) return
+    this.lastState = state
+    this.callSink(() => this.sinks.onStateChange?.(state))
+  }
+
+  private async pumpStream<F extends { type: string }>(
+    stream: AsyncIterable<RpcRequest<F>>,
+    sink: ((envelope: RpcRequest<F>) => void) | undefined,
+    onEnd: () => void,
+  ): Promise<void> {
+    try {
+      for await (const envelope of stream) {
+        if (envelope.payload.type === 'stream/error') break
+        if (sink !== undefined) this.callSink(() => { sink(envelope) })
+      }
+    } catch {
+      // Stream loss: converge on onEnd, which triggers the shared reconnect.
+    }
+    onEnd()
+  }
+
+  /** Sink exception isolation: a business-layer throw is logged only, never affecting pump or reconnect semantics. */
+  private callSink(fn: (() => void) | undefined): void {
+    if (fn === undefined) return
+    try {
+      fn()
+    } catch (error) {
+      console.error('[web-runtime] connection sink threw:', error)
+    }
+  }
+}
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
new file mode 100644
index 0000000000..4f4cdaa256
--- /dev/null
+++ b/packages/client/connection/src/client/fixture.ts
@@ -0,0 +1,554 @@
+// FixtureApi: standalone UI development without a server. Real contract shape: unary takes
+// RpcRequest<P> and returns RpcResponse<T> (echoing the rpcId); streams yield RpcRequest<frame>
+// (the fixture IS the fake server, so it mints frame rpcIds); root respond takes ClientResponse
+// and returns RpcReceipt. fx-alpha carries a hand-built history script (60 turns, pageable);
+// prompt triggers a chunked streaming replay; cancel stops the replay; one resident pending
+// approval (placeholder-card material, subscribed-baseline-replay semantics: stable rpcId reuse).
+
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
+import type {
+  ApiProxy, ClientRequest, ClientResponse, HistoryEntry, HostFrame, MuxFrame, RpcReceipt,
+  RpcRequest, RpcResponse, RpcResult, ServerRequest, ServerResponse, SessionSummary,
+  ToolCallView, ToolEventView, ToolResultView,
+} from './api.ts'
+import type { RequestPayload, ResponseValue, RpcMethodMap } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { AbstractApiClient, RpcId } from './api.ts'
+
+/** The fake carrier mints like a real one (business code never mints). */
+function rpcRequest<P>(payload: P): RpcRequest<P> {
+  return { rpcId: RpcId(crypto.randomUUID()), payload }
+}
+
+function text(t: string): ContentBlock[] {
+  return [{ type: 'text', text: t }]
+}
+
+function sid(id: string): SessionId {
+  return id as SessionId
+}
+
+/** fx-alpha history script: 60 turns (~130+ messages -> 3 pages at PAGE_MESSAGES=50),
+ *  mixing reasoning blocks / tool call+result / steering / context. */
+function buildAlphaLog(): SessionEvent[] {
+  const events: Record<string, unknown>[] = []
+  let time = Date.now() - 3_600_000
+  const push = (e: Record<string, unknown>): number => {
+    const seq = events.length
+    events.push({ seq, time: (time += 800), ...e })
+    return seq
+  }
+  for (let turn = 0; turn < 60; turn++) {
+    push({ type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } })
+    push({ type: 'user/message', surfaceOp: 'append', data: { content: text(`问题 ${turn}：fixture 历史消息，用于翻页与渲染验收。`), source: { kind: 'user' } } })
+    if (turn % 9 === 4) {
+      push({ type: 'context/message', surfaceOp: 'append', data: { content: text(`[fixture] 上下文注入（turn ${turn}）`), source: { kind: 'plugin', plugin: 'fixture' } } })
+    }
+    push({ type: 'step/start', data: { turn, step: 0 } })
+    const withTool = turn % 5 === 2
+    const withReasoning = turn % 3 === 1
+    const blocks: ContentBlock[] = []
+    if (withReasoning) blocks.push({ type: 'reasoning', text: `思考过程 ${turn}：这是一段可折叠的 reasoning 内容。` })
+    blocks.push({ type: 'text', text: `回答 ${turn}：这是 fixture 生成的历史回复正文。` })
+    if (withTool) {
+      const callId = `fx-call-${turn}`
+      blocks.push({ type: 'tool-call', id: callId, name: 'echo', arguments: `{"text":"turn ${turn}"}` } as ContentBlock)
+      push({ type: 'assistant/message', surfaceOp: 'append', data: { turn, step: 0, content: blocks, provenance: { provider: 'fixture', model: 'fx-1' } } })
+      push({ type: 'tool/call', data: { turn, step: 0, callId, name: 'echo', arguments: `{"text":"turn ${turn}"}` } })
+      push({ type: 'tool/result', surfaceOp: 'append', data: { turn, step: 0, callId, content: text(`ECHO: TURN ${turn}`), isError: turn % 25 === 12 } })
+      push({ type: 'step/end', data: { turn, step: 0 } })
+      push({ type: 'step/start', data: { turn, step: 1 } })
+      push({ type: 'assistant/message', surfaceOp: 'append', data: { turn, step: 1, content: text(`工具结果已消化（turn ${turn}）。`), provenance: { provider: 'fixture', model: 'fx-1' } } })
+      push({ type: 'step/end', data: { turn, step: 1 } })
+    } else {
+      push({ type: 'assistant/message', surfaceOp: 'append', data: { turn, step: 0, content: blocks, provenance: { provider: 'fixture', model: 'fx-1' } } })
+      push({ type: 'step/end', data: { turn, step: 0 } })
+    }
+    if (turn % 13 === 6) {
+      push({ type: 'steering/message', surfaceOp: 'append', data: { turn, content: text(`插话 ${turn}：fixture steering 消息。`), source: { kind: 'user' } } })
+    }
+    push({ type: 'turn/end', data: { turn, reason: { kind: 'completed' } } })
+  }
+  // Three view-sample turns (60-62) for the tool-card wire acceptance: one per built-in card
+  // type. `echo` above stays presenter-less on purpose — it is the no-view fallback sample.
+  const toolTurn = (turn: number, name: string, args: string, resultText: string): void => {
+    const callId = `fx-call-${turn}`
+    push({ type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } })
+    push({ type: 'user/message', surfaceOp: 'append', data: { content: text(`问题 ${turn}：${name} 样本。`), source: { kind: 'user' } } })
+    push({ type: 'step/start', data: { turn, step: 0 } })
+    push({
+      type: 'assistant/message', surfaceOp: 'append',
+      data: { turn, step: 0, content: [{ type: 'tool-call', id: callId, name, arguments: args } as ContentBlock], provenance: { provider: 'fixture', model: 'fx-1' } },
+    })
+    push({ type: 'tool/call', data: { turn, step: 0, callId, name, arguments: args } })
+    push({ type: 'tool/result', surfaceOp: 'append', data: { turn, step: 0, callId, content: text(resultText), isError: false } })
+    push({ type: 'step/end', data: { turn, step: 0 } })
+    push({ type: 'turn/end', data: { turn, reason: { kind: 'completed' } } })
+  }
+  toolTurn(60, 'fx-bash', '{"command":"ls -la","cwd":"/tmp/fixture"}', 'total 2\ndrwxr-xr-x fixture\n-rw-r--r-- demo.txt')
+  toolTurn(61, 'fx-write', '{"path":"notes/demo.txt","content":"hello fixture\\n"}', 'wrote notes/demo.txt')
+  toolTurn(62, 'fx-note', '{"note":"三型卡验收样本"}', '已记录')
+  return events as unknown as SessionEvent[]
+}
+
+/** Narrows a parsed-JSON field to string; fixture args are authored in-file, so non-strings only mean a typo here. */
+/* v8 ignore next -- the fallback arm is the same in-file-typo guard as the JSON.parse catch above. */
+const str = (value: unknown, fallback = ''): string => typeof value === 'string' ? value : fallback
+
+/** Fixture presenter registry (mirrors host viewFor): pure derivation, undefined = no view. */
+function presentCall(name: string, argsRaw: string): ToolCallView | undefined {
+  let args: Record<string, unknown>
+  try {
+    args = JSON.parse(argsRaw) as Record<string, unknown>
+  } catch {
+    /* v8 ignore next 2 -- defensive: fixture args are authored in-file as valid JSON; only an in-file typo could reach the catch. */
+    return undefined
+  }
+  switch (name) {
+    case 'fx-bash':
+      return { card: 'terminal', title: str(args.command), cwd: str(args.cwd, '/tmp/fixture'), description: 'fixture 终端样本' }
+    case 'fx-write':
+      return {
+        card: 'diff', title: `Write ${str(args.path)}`,
+        diffs: [{ path: str(args.path), oldText: null, newText: str(args.content) }],
+      }
+    case 'fx-note':
+      return { card: 'generic', title: '记录笔记', kind: 'edit', rawInput: args }
+    default:
+      return undefined // echo et al: the documented no-view fallback path
+  }
+}
+
+function presentResult(name: string, argsRaw: string, resultText: string): ToolResultView | undefined {
+  const call = presentCall(name, argsRaw)
+  if (call === undefined) return undefined
+  switch (call.card) {
+    case 'terminal':
+      return { card: 'terminal', output: resultText, exitCode: 0 }
+    case 'diff':
+      return { card: 'diff', diffs: call.diffs }
+    case 'generic':
+      return { card: 'generic', content: text(resultText) }
+  }
+}
+
+/** Host-side viewFor mirror: tool/call presents from its own args; tool/result back-scans the log for the paired call. */
+function viewFor(event: SessionEvent, log: readonly SessionEvent[]): ToolEventView | undefined {
+  if (event.type === 'tool/call') {
+    const view = presentCall(event.data.name, event.data.arguments)
+    return view === undefined ? undefined : { for: 'call', view }
+  }
+  if (event.type === 'tool/result') {
+    const callId = String(event.data.callId)
+    for (let i = log.length - 1; i >= 0; i--) {
+      const candidate = log[i]
+      /* v8 ignore next -- dense-array guard: i stays within [0, log.length),
+      so the undefined arm needs a sparse log no code path builds. */
+      if (candidate !== undefined && candidate.type === 'tool/call' && String(candidate.data.callId) === callId) {
+        const resultText = event.data.content.map(b => (b.type === 'text' ? b.text : '')).join('')
+        const view = presentResult(candidate.data.name, candidate.data.arguments, resultText)
+        return view === undefined ? undefined : { for: 'result', view }
+      }
+    }
+    return undefined // cross-page unpaired: documented default
+  }
+  return undefined
+}
+
+/**
+ * Message-boundary paging (mirrors the host's paging contract): count
+ * maxMessages messages
+ *  backwards from end, cut at a turn/start boundary.
+ Entries carry pagination-time views
+ *  (the host analogue computes viewFor per entry at page time). */
+function pageOf(
+  log: readonly SessionEvent[],
+  beforeSeq: number | undefined,
+  maxMessages: number,
+): { events: HistoryEntry[]; hasMore: boolean } {
+  const end = beforeSeq === undefined ? log.length : Math.max(0, Math.min(beforeSeq, log.length))
+  let start = 0
+  let messages = 0
+  for (let i = end - 1; i >= 0; i--) {
+    const event = log[i]
+    /* v8 ignore next -- dense-array guard: log seqs are array indexes, i stays within [0, end). */
+    if (event === undefined) break
+    if (event.type === 'user/message' || event.type === 'assistant/message' || event.type === 'steering/message') messages++
+    if (event.type === 'turn/start' && messages >= maxMessages) {
+      start = i
+      break
+    }
+  }
+  const events = log.slice(start, end).map((event): HistoryEntry => {
+    const view = viewFor(event, log)
+    return view === undefined ? { event } : { event, view }
+  })
+  return { events, hasMore: start > 0 }
+}
+
+interface StreamConn<F> {
+  push(envelope: RpcRequest<F>): void
+}
+
+/** Inbox pump shared by both stream generators (FrameQueue pattern: ONE abort listener hung
+ *  outside the loop — a per-iteration {once:true} listener never fires for non-final rounds and
+ *  piles up for the stream's lifetime, audit C5). breakNow force-ends the stream without the
+ *  client's signal (timing hook: simulated connection loss). */
+class FxInbox<F> implements StreamConn<F> {
+  private readonly inbox: RpcRequest<F>[] = []
+  private wake: (() => void) | null = null
+  private broken = false
+
+  push(envelope: RpcRequest<F>): void {
+    this.inbox.push(envelope)
+    this.wake?.()
+  }
+
+  breakNow(): void {
+    this.broken = true
+    this.wake?.()
+  }
+
+  /** Read through a method: breakNow()/abort flip state across yields, so narrowing from the loop condition must not stick. */
+  private isLive(signal: AbortSignal): boolean {
+    return !signal.aborted && !this.broken
+  }
+
+  async *drain(signal: AbortSignal): AsyncGenerator<RpcRequest<F>> {
+    const onAbort = (): void => this.wake?.()
+    signal.addEventListener('abort', onAbort)
+    try {
+      while (this.isLive(signal)) {
+        while (this.inbox.length > 0) yield this.inbox.shift() as RpcRequest<F>
+        if (!this.isLive(signal)) break
+        await new Promise<void>((resolve) => {
+          this.wake = resolve
+        })
+        this.wake = null
+      }
+    } finally {
+      signal.removeEventListener('abort', onAbort)
+    }
+  }
+}
+
+/**
+ * In-memory fake host: fx-alpha carries history and replay scripts; fx-beta is fx-alpha's child session (lineage indent material).
+ * @returns an ApiProxy backed entirely by in-memory state — no host process, no network.
+ */
+export function createFixtureApi(): ApiProxy {
+  const sessions: SessionSummary[] = [
+    { sessionId: sid('fx-alpha'), updatedAt: Date.now(), running: true, cwd: '/tmp/fixture' },
+    { sessionId: sid('fx-beta'), updatedAt: Date.now() - 60_000, running: false, parentSessionId: sid('fx-alpha'), cwd: '/tmp/fixture' },
+    { sessionId: sid('fx-gamma'), updatedAt: Date.now() - 120_000, running: false, cwd: '/tmp/fixture' },
+  ]
+  const logs = new Map<SessionId, SessionEvent[]>([[sid('fx-alpha'), buildAlphaLog()]])
+  const nextTurn = new Map<SessionId, number>([[sid('fx-alpha'), 60]])
+  let nextSession = 1
+  let nextRpc = 1
+  const mint = (): ReturnType<typeof RpcId> => RpcId(`fx-rpc-${nextRpc++}`)
+  /** Resident pending approval (stable rpcId: every mux open replays the same id, matching host replay semantics). */
+  const pendingApprovalRpcId = mint()
+
+  const muxConns = new Set<StreamConn<MuxFrame>>()
+  const hostConns = new Set<StreamConn<HostFrame>>()
+  const emitMux = (frame: MuxFrame): void => {
+    for (const conn of muxConns) conn.push({ rpcId: mint(), payload: frame })
+  }
+  const emitHost = (frame: HostFrame): void => {
+    for (const conn of hostConns) conn.push({ rpcId: mint(), payload: frame })
+  }
+
+  /** OK response echoing the caller's rpcId (contract: responses always backfill, never mint). */
+  function ok<P, T>(request: RpcRequest<P>, value: T): Promise<RpcResponse<T>> {
+    return Promise.resolve({ rpcId: request.rpcId, result: { ok: true, value } })
+  }
+  function err<P, T>(request: RpcRequest<P>, error: Extract<RpcResult<T>, { ok: false }>['error']): Promise<RpcResponse<T>> {
+    return Promise.resolve({ rpcId: request.rpcId, result: { ok: false, error } })
+  }
+
+  const summaryOf = (id: SessionId): SessionSummary | undefined => sessions.find(s => s.sessionId === id)
+  const setRunning = (id: SessionId, running: boolean): void => {
+    const summary = summaryOf(id)
+    if (summary === undefined || summary.running === running) return
+    summary.running = running
+    emitHost({ type: 'host/session-status', sessionId: id, running })
+  }
+  const logOf = (id: SessionId): SessionEvent[] => {
+    let log = logs.get(id)
+    if (log === undefined) {
+      log = []
+      logs.set(id, log)
+    }
+    return log
+  }
+  const append = (id: SessionId, e: Record<string, unknown>): void => {
+    const log = logOf(id)
+    const event = { seq: log.length, time: Date.now(), ...e } as unknown as SessionEvent
+    log.push(event)
+    // Emission-time view derivation (mirrors the host's live path).
+    const view = viewFor(event, log)
+    /* v8 ignore next 3 -- the view-present arm needs a live tool/call emission,
+    but the fixture replay produces text-only turns; view vocabulary is
+    exercised through the history samples (turns 60-62). */
+    emitMux(view === undefined
+      ? { type: 'session/event', sessionId: id, event }
+      : { type: 'session/event', sessionId: id, event, view })
+  }
+
+  /** At most one in-flight replay per session; cancel clears it. */
+  const replays = new Map<SessionId, { timer: ReturnType<typeof setTimeout>; finish(aborted: boolean): void }>()
+
+  /** history transit delay (timing hooks below); the page snapshot is taken at request time, like a real host. */
+  let historyDelayMs = 0
+  /** One-shot history failure (timing hook: the doomed in-flight request of the S4 reconnect scenario). */
+  let failNextHistory = false
+  /** Force-enders for currently open stream generators (timing hook: simulated connection loss). */
+  const streamBreakers = new Set<() => void>()
+
+  // Timing-acceptance hooks (browser test backdoor): the in-memory fixture is ideally timed, which
+  // is exactly what masked the open-window and reconnect-gap bugs (audit S1/S3). These let
+  // browser acceptance runs create slow-history, lost-frame, and reconnect
+  // windows a real host produces naturally.
+  const timingHooks = {
+    setHistoryDelay(ms: number): void {
+      historyDelayMs = ms
+    },
+    /** Fail the NEXT history call (after its transit delay) with a transport-level throw. */
+    failNextHistory(): void {
+      failNextHistory = true
+    },
+    /** Log append + mux emit (the normal live path). */
+    appendUser(id: string, msg: string): void {
+      append(sid(id), { type: 'user/message', surfaceOp: 'append', data: { content: text(msg), source: { kind: 'user' } } })
+    },
+    /** Log append WITHOUT the mux emit: a frame lost in transit — history still serves it, the client must repull. */
+    appendSilent(id: string, msg: string): void {
+      const log = logOf(sid(id))
+      log.push({ type: 'user/message', surfaceOp: 'append', seq: log.length, time: Date.now(), data: { content: text(msg), source: { kind: 'user' } } } as unknown as SessionEvent)
+    },
+    /** End every open stream generator (client sees both streams close -> reconnect + resync path). */
+    breakStreams(): void {
+      for (const breakNow of [...streamBreakers]) breakNow()
+    },
+  }
+  ;(globalThis as Record<string, unknown>).__fxTiming = timingHooks
+
+  /** Prompt replay: chunk typewriter (80ms/frame) -> assistant/message finalize -> turn/end + running flip. */
+  const startReply = (id: SessionId, turn: number, replyText: string): void => {
+    const step = 0
+    append(id, { type: 'step/start', data: { turn, step } })
+    append(id, { type: 'assistant/chunk', data: { turn, step, chunk: { type: 'block-start', index: 0, blockType: 'text' } } })
+    /* v8 ignore next -- the ?? arm needs a null match, but replyText is never empty (prompt always prefixes 回声). */
+    const pieces = replyText.match(/.{1,6}/gu) ?? [replyText]
+    let i = 0
+    const finish = (aborted: boolean): void => {
+      replays.delete(id)
+      const done = pieces.slice(0, i).join('')
+      append(id, { type: 'assistant/chunk', data: { turn, step, chunk: { type: 'block-end', index: 0, block: { type: 'text', text: done } } } })
+      append(id, { type: 'assistant/message', surfaceOp: 'append', data: { turn, step, content: text(aborted ? `${done}（已中断）` : done), provenance: { provider: 'fixture', model: 'fx-1' } } })
+      append(id, { type: 'step/end', data: { turn, step } })
+      append(id, { type: 'turn/end', data: { turn, reason: { kind: aborted ? 'cancelled' : 'completed' } } })
+      setRunning(id, false)
+    }
+    const tick = (): void => {
+      const piece = pieces[i]
+      if (piece === undefined) {
+        finish(false)
+        return
+      }
+      i++
+      append(id, { type: 'assistant/chunk', data: { turn, step, chunk: { type: 'text-delta', index: 0, text: piece } } })
+      replays.set(id, { timer: setTimeout(tick, 80), finish })
+    }
+    replays.set(id, { timer: setTimeout(tick, 80), finish })
+  }
+
+  return {
+    sessions: {
+      list: request => ok(request, { items: [...sessions].sort((a, b) => b.updatedAt - a.updatedAt) }),
+      create: (request) => {
+        const created: SessionSummary = {
+          sessionId: sid(`fx-${nextSession++}`), updatedAt: Date.now(), running: false, cwd: '/tmp/fixture',
+        }
+        sessions.push(created)
+        emitHost({ type: 'host/session-added', sessionId: created.sessionId })
+        return ok(request, { sessionId: created.sessionId })
+      },
+      history: async (request) => {
+        const log = logs.get(request.payload.sessionId) ?? []
+        // Snapshot at request time, deliver after the transit delay (mirrors a real host under latency).
+        const page = pageOf(log, request.payload.beforeSeq, request.payload.maxMessages ?? 50)
+        const doomed = failNextHistory
+        failNextHistory = false
+        const delay = historyDelayMs
+        if (delay > 0) await new Promise(resolve => setTimeout(resolve, delay))
+        if (doomed) throw new Error('fixture: simulated history transport failure')
+        return ok(request, page)
+      },
+      prompt: (request) => {
+        const { sessionId: id, mode, content } = request.payload
+        const summary = summaryOf(id)
+        if (summary === undefined) {
+          return err(request, { code: 'session-not-found', message: `no session ${id}`, details: { sessionId: id } })
+        }
+        summary.updatedAt = Date.now()
+        const userText = content.map(b => (b.type === 'text' ? b.text : '')).join('')
+        if (mode === 'steer' && replays.has(id)) {
+          // Steering: insert a steering message into the current turn; the replay continues.
+          /* v8 ignore next -- the ?? arm needs a missing counter, but a live replay implies a prior prompt already set it. */
+          const turn = (nextTurn.get(id) ?? 1) - 1
+          append(id, { type: 'steering/message', surfaceOp: 'append', data: { turn, content, source: { kind: 'user' } } })
+          return ok(request, { accepted: true as const })
+        }
+        const turn = nextTurn.get(id) ?? 0
+        nextTurn.set(id, turn + 1)
+        setRunning(id, true)
+        append(id, { type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } })
+        append(id, { type: 'user/message', surfaceOp: 'append', data: { content, source: { kind: 'user' } } })
+        startReply(id, turn, `回声：${userText}。这是 fixture 的流式回复，用于验证打字机增长与定稿切换。`)
+        return ok(request, { accepted: true as const })
+      },
+      cancel: (request) => {
+        const replay = replays.get(request.payload.sessionId)
+        if (replay !== undefined) {
+          clearTimeout(replay.timer)
+          replay.finish(true)
+        } else {
+          setRunning(request.payload.sessionId, false)
+        }
+        return ok(request, { accepted: true as const })
+      },
+    },
+    host: {
+      describe: request => ok(request, { version: '0.0.0-fixture', cwd: '/tmp/fixture', attachedSessions: 1 }),
+    },
+    events: {
+      async *mux(_request, signal) {
+        const conn = new FxInbox<MuxFrame>()
+        muxConns.add(conn)
+        const breakNow = (): void => { conn.breakNow() }
+        streamBreakers.add(breakNow)
+        // Open baseline: subscribed for attached (running) sessions + pending approval replay (stable rpcId).
+        for (const s of sessions) {
+          if (!s.running) continue
+          conn.push({ rpcId: mint(), payload: { type: 'session/subscribed', sessionId: s.sessionId, lastSeq: (logs.get(s.sessionId)?.length ?? 0) - 1 } })
+        }
+        conn.push({
+          rpcId: pendingApprovalRpcId,
+          payload: {
+            type: 'approval/requested', sessionId: sid('fx-alpha'),
+            approvalId: 'fx-approval-1' as MuxFrame extends never ? never : Extract<MuxFrame, { type: 'approval/requested' }>['approvalId'],
+            toolName: 'dangerous_tool', reason: 'fixture 常驻占位审批（可见不可答）',
+          },
+        })
+        try {
+          yield* conn.drain(signal)
+        } finally {
+          streamBreakers.delete(breakNow)
+          muxConns.delete(conn)
+        }
+      },
+      async *host(_request, signal) {
+        const conn = new FxInbox<HostFrame>()
+        hostConns.add(conn)
+        const breakNow = (): void => { conn.breakNow() }
+        streamBreakers.add(breakNow)
+        // Periodic material (the RPC-panel acceptance's clear-then-new-frames step depends on it): flip fx-gamma every 5s.
+        // fx-gamma only: never touch fx-alpha's running semantics (the conversation replay drives that).
+        const timer = setInterval(() => {
+          const gamma = summaryOf(sid('fx-gamma'))
+          /* v8 ignore next -- the undefined arm needs fx-gamma deleted, but the fixture never removes sessions. */
+          if (gamma !== undefined) setRunning(gamma.sessionId, !gamma.running)
+        }, 5000)
+        try {
+          yield* conn.drain(signal)
+        } finally {
+          clearInterval(timer)
+          streamBreakers.delete(breakNow)
+          hostConns.delete(conn)
+        }
+      },
+    },
+    respond(message: ClientResponse): Promise<RpcReceipt> {
+      // The v1 UI never answers (PendingCard is visible but not answerable); implemented for type completeness, always not-pending.
+      void message
+      return Promise.resolve({ accepted: false, reason: 'not-pending' })
+    },
+  }
+}
+
+/**
+ * Fixture platform subclass: there is no HTTP at all, so instead of a doFetch transport it
+ * overrides the protocol-level virtuals (callUnary/openMux/openHost/respond) to dispatch
+ * straight into the in-memory ApiProxy — while still minting rpcIds, fabricating the four
+ * named full forms, and feeding the same tap as a real carrier. Delete when the fixture moves
+ * to the isomorphic pipeline (InProcessApiClient over toFetchHandler(fixtureImpl)).
+ */
+export class FixtureApiClient extends AbstractApiClient {
+  private readonly api = createFixtureApi()
+
+  protected doFetch(): Promise<Response> {
+    throw new Error('FixtureApiClient overrides all protocol paths; doFetch must be unreachable')
+  }
+
+  protected override async callUnary<K extends keyof RpcMethodMap>(
+    method: K,
+    payload: RequestPayload<K>,
+  ): Promise<RpcResponse<ResponseValue<K>>> {
+    const request = rpcRequest(payload)
+    const full: ClientRequest = { type: 'client-request', rpcId: request.rpcId, method, payload }
+    this.onEnvelope(full)
+    const response = await this.dispatch(method, request as RpcRequest<never>) as RpcResponse<ResponseValue<K>>
+    const fullResponse: ServerResponse = { type: 'server-response', rpcId: response.rpcId, result: response.result }
+    this.onEnvelope(fullResponse)
+    return response
+  }
+
+  /** Method-key dispatch into the in-memory contract impl (a real carrier routes by URL path instead). */
+  private dispatch(method: keyof RpcMethodMap, request: RpcRequest<never>): Promise<RpcResponse<unknown>> {
+    switch (method) {
+      case 'session.list': return this.api.sessions.list(request)
+      case 'session.create': return this.api.sessions.create(request)
+      case 'session.history': return this.api.sessions.history(request)
+      case 'session.prompt': return this.api.sessions.prompt(request)
+      case 'session.cancel': return this.api.sessions.cancel(request)
+      case 'host.describe': return this.api.host.describe(request)
+    }
+  }
+
+  protected override openMux(
+    payload: { since?: Record<SessionId, number> },
+    signal: AbortSignal,
+    onOpen?: () => void,
+  ): AsyncIterable<RpcRequest<MuxFrame>> {
+    return this.tapStream(this.api.events.mux(rpcRequest(payload), signal), onOpen)
+  }
+
+  protected override openHost(
+    payload: Record<never, never>,
+    signal: AbortSignal,
+    onOpen?: () => void,
+  ): AsyncIterable<RpcRequest<HostFrame>> {
+    return this.tapStream(this.api.events.host(rpcRequest(payload), signal), onOpen)
+  }
+
+  private async *tapStream<F extends MuxFrame | HostFrame>(
+    stream: AsyncIterable<RpcRequest<F>>,
+    onOpen?: () => void,
+  ): AsyncGenerator<RpcRequest<F>> {
+    // No HTTP here: the in-memory stream is established the moment iteration starts (mirrors
+    // readSse firing onOpen after response headers, before any frame).
+    onOpen?.()
+    for await (const envelope of stream) {
+      const full: ServerRequest = { type: 'server-request', rpcId: envelope.rpcId, method: envelope.payload.type, payload: envelope.payload }
+      this.onEnvelope(full)
+      yield envelope
+    }
+  }
+
+  override async respond(message: ClientResponse): Promise<RpcReceipt> {
+    this.onEnvelope(message)
+    return this.api.respond(message)
+  }
+}
diff --git a/packages/client/connection/src/client/index.ts b/packages/client/connection/src/client/index.ts
new file mode 100644
index 0000000000..026fc1bf5f
--- /dev/null
+++ b/packages/client/connection/src/client/index.ts
@@ -0,0 +1,76 @@
+/**
+ * Browser half of the wire consumer layer (contract: api-contracts v3
+ * section 3; export inventory = v3 §3.2). The wire is this package's client
+ * half in its entirety — apply mounts ctx.connection: the shared api client
+ * plus the connection controller handle. Mode selection (?fixture) happens
+ * here so the rest of the client tree is mode-blind; the controller's sinks
+ * are wired by the runtime plugin (object layer), which injects this service.
+ */
+import type { Context } from 'cordis'
+import type { IApiClient } from './api.ts'
+import { ConnectionController, type ConnectionConfig, type ConnectionSinks, type ConnectionState } from './connection.ts'
+import { FixtureApiClient } from './fixture.ts'
+import { WebApiClient } from './web-api-client.ts'
+
+// ---- Contract re-exports (browser-safe apiproxy channels + core types) ----
+export type {
+  ApiProxy, SessionsApi, SessionSummary, HostApi, EventsApi, MuxFrame, HostFrame,
+  ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, ToolEventView,
+  ToolCallView, ToolResultView,
+  RpcRequest, RpcResponse, RpcResult, RpcError, RpcErrorCode,
+  ClientRequest, ServerResponse, ServerRequest, ClientResponse, RpcMessage, RpcReceipt,
+  IApiClient, SessionId, SessionEvent, ContentBlock, StreamChunk,
+} from './api.ts'
+export { RpcId, AbstractApiClient, resultOf, transportError } from './api.ts'
+
+// ---- Connection loop ----
+export { ConnectionController } from './connection.ts'
+export type { ConnectionConfig, ConnectionSinks, ConnectionState }
+
+// ---- Platform client subclasses ----
+export { WebApiClient } from './web-api-client.ts'
+export { FixtureApiClient, createFixtureApi } from './fixture.ts'
+
+
+/** Required services (none — this is the wire root). */
+export const inject: string[] = []
+
+/**
+ * The ctx.connection service surface: the api client plus a one-shot
+ * controller starter (the runtime plugin supplies sinks when its object layer
+ * is ready — connection stays consumer-agnostic).
+ */
+export interface ConnectionHandle {
+  /** Shared api client (fixture or real, decided at boot from the page URL). */
+  readonly api: IApiClient
+  /**
+   * Start the connect/pump/reconnect loop with the consumer's frame sinks.
+   * One consumer owns the streams (the runtime object layer); a second call
+   * throws.
+   * @param sinks - frame/state callbacks.
+   * @param config - reconnect/backoff tunables.
+   * @returns stop handle for the loop.
+   */
+  start(sinks: ConnectionSinks, config?: ConnectionConfig): { stop(): void }
+}
+
+/**
+ * Client plugin body: pick the api by page mode and provide ctx.connection.
+ * @param ctx - client cordis context.
+ */
+export function apply(ctx: Context): void {
+  const fixture = typeof location !== 'undefined' && new URLSearchParams(location.search).has('fixture')
+  const api: IApiClient = fixture ? new FixtureApiClient() : new WebApiClient()
+  let started = false
+  const handle: ConnectionHandle = {
+    api,
+    start(sinks, config) {
+      if (started) throw new Error('connection: the stream loop is already owned by another consumer')
+      started = true
+      const controller = new ConnectionController(api, sinks, config ?? {})
+      controller.start()
+      return { stop: () => { controller.stop() } }
+    },
+  }
+  ctx.provide('connection', handle)
+}
diff --git a/packages/client/connection/src/client/web-api-client.ts b/packages/client/connection/src/client/web-api-client.ts
new file mode 100644
index 0000000000..9ae6eeae7d
--- /dev/null
+++ b/packages/client/connection/src/client/web-api-client.ts
@@ -0,0 +1,12 @@
+// WebApiClient: the browser platform subclass — transport = global fetch over same-origin
+// /api/* (base resolution handled by AbstractApiClient). Envelope observation comes from the
+// base batching aspect; subscribers attach via subscribeEnvelopes (see boot).
+
+import { AbstractApiClient } from './api.ts'
+
+/** Browser platform subclass: transport = global fetch over same-origin /api/*. */
+export class WebApiClient extends AbstractApiClient {
+  protected doFetch(input: URL, init?: RequestInit): Promise<Response> {
+    return globalThis.fetch(input, init)
+  }
+}
diff --git a/packages/client/connection/src/index.ts b/packages/client/connection/src/index.ts
new file mode 100644
index 0000000000..313db07225
--- /dev/null
+++ b/packages/client/connection/src/index.ts
@@ -0,0 +1,10 @@
+/**
+ * Connection plugin, node half. The package IS a dshClient plugin: the wire
+ * consumer layer lives in its client half in full (src/client/ — contract:
+ * api-contracts v3 section 3, inventory §3.2); consumers import the /client
+ * subpath. The empty apply exists so the plugin appears in the host Loader
+ * (lifecycle governance + dshClient discovery).
+ */
+
+/** Host plugin body — no host-side behavior for the connection plugin. */
+export function apply(_ctx: unknown): void {}
diff --git a/packages/client/connection/src/invariant.ts b/packages/client/connection/src/invariant.ts
new file mode 100644
index 0000000000..df16e00fd4
--- /dev/null
+++ b/packages/client/connection/src/invariant.ts
@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-connection`.
+ * @module @deepseek-ai/dsh-client-connection/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-connection'
+
+/** Cordis companion plugin name. */
+export const name = 'client-connection-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: the pure wire layer emits no cordis events and owns no
+ * mutable cross-plugin relation — stream/reconnect sequencing is exercised
+ * directly by its behavior specs, and rpcId round-trip discipline is owned by
+ * the apiproxy contract layer.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/client/connection/tests/api-helpers.spec.ts b/packages/client/connection/tests/api-helpers.spec.ts
new file mode 100644
index 0000000000..9e97cdab77
--- /dev/null
+++ b/packages/client/connection/tests/api-helpers.spec.ts
@@ -0,0 +1,21 @@
+/**
+ * Contract-layer helpers: transport-error folding and response unwrapping.
+ * (The assistant block classifier half of the legacy spec lives in
+ * runtime/tests — the classifier moved there.)
+ */
+
+import { describe, expect, it } from 'vitest'
+import { RpcId, resultOf, transportError } from '../src/client/api.ts'
+
+describe('transportError', () => {
+  it('folds an Error to internal keeping the message, and stringifies non-Errors', () => {
+    expect(transportError(new Error('线断了'))).toEqual({ ok: false, error: { code: 'internal', message: '线断了', details: {} } })
+    expect(transportError('raw string')).toMatchObject({ ok: false, error: { message: 'raw string' } })
+  })
+})
+
+describe('resultOf', () => {
+  it('unwraps the result slot', () => {
+    expect(resultOf({ rpcId: RpcId('r'), result: { ok: true, value: 7 } })).toEqual({ ok: true, value: 7 })
+  })
+})
diff --git a/packages/client/connection/tests/connection.spec.ts b/packages/client/connection/tests/connection.spec.ts
new file mode 100644
index 0000000000..4de4a31f25
--- /dev/null
+++ b/packages/client/connection/tests/connection.spec.ts
@@ -0,0 +1,238 @@
+/**
+ * ConnectionController: stream pumping into sinks, the strict readiness
+ * handshake (describe + both streams' onOpen, timeout-guarded), generation
+ * abort on loss, backoff reconnection, state transitions, and sink-exception
+ * isolation. Real (short) timers — the timeout and backoff are configurable,
+ * so tests run them at millisecond scale.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionId } from '../src/client/api.ts'
+import type { ConnectionState } from '../src/client/connection.ts'
+import { ConnectionController } from '../src/client/connection.ts'
+import { FakeApiClient, deferred, ok } from './fake-api.ts'
+
+const SID = 'fk-c1' as SessionId
+const FAST = { backoffBaseMs: 10, backoffFactor: 1, backoffMaxMs: 10, streamOpenTimeoutMs: 500 }
+
+function subscribedFrame(lastSeq = 0) {
+  return { type: 'session/subscribed', sessionId: SID, lastSeq } as const
+}
+
+describe('connection lifecycle', () => {
+  it('announces connected after describe + both streams open, then pumps frames to sinks', async () => {
+    const api = new FakeApiClient()
+    const muxSeen: string[] = []
+    let connected = 0
+    const controller = new ConnectionController(api, {
+      onMuxEnvelope: envelope => muxSeen.push(envelope.payload.type),
+      onConnected: () => { connected++ },
+    }, FAST)
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(connected).toBe(1) })
+      api.pushMux(subscribedFrame())
+      await vi.waitFor(() => { expect(muxSeen).toEqual(['session/subscribed']) })
+      expect(api.callsOf('host.describe')).toHaveLength(1)
+    } finally {
+      controller.stop()
+    }
+  })
+
+  it('reconnects with a fresh generation when a stream fails, and stop() ends the loop', async () => {
+    const api = new FakeApiClient()
+    let connected = 0
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const controller = new ConnectionController(api, { onConnected: () => { connected++ } }, FAST)
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(connected).toBe(1) })
+      api.failStreams(new Error('stream torn'))
+      await vi.waitFor(() => { expect(connected).toBe(2) }) // new generation after backoff
+      expect(api.openMuxCount).toBe(1) // the dead generation's stream is gone, exactly one live
+    } finally {
+      controller.stop()
+      warnSpy.mockRestore()
+    }
+    // stop() aborts the live generation (streams tear down) and no reconnect follows.
+    await vi.waitFor(() => { expect(api.openMuxCount).toBe(0) })
+    await new Promise(resolve => setTimeout(resolve, 40))
+    expect(api.openMuxCount).toBe(0)
+  })
+
+  it('treats describe failure as generation failure and retries', async () => {
+    const api = new FakeApiClient()
+    const gate = deferred<Awaited<ReturnType<FakeApiClient['onDescribe']>>>()
+    let describeCalls = 0
+    api.onDescribe = () => {
+      describeCalls++
+      return describeCalls === 1 ? Promise.reject(new Error('host down')) : gate.promise
+    }
+    let connected = 0
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const controller = new ConnectionController(api, { onConnected: () => { connected++ } }, FAST)
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(describeCalls).toBe(2) }) // retried after backoff
+      expect(connected).toBe(0) // never announced during the failed generation
+      gate.resolve(ok({ version: '0', cwd: '/f', attachedSessions: 0 }))
+      await vi.waitFor(() => { expect(connected).toBe(1) })
+    } finally {
+      controller.stop()
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('converges stream/error frames into reconnect instead of dispatching them', async () => {
+    const api = new FakeApiClient()
+    const muxSeen: string[] = []
+    let connected = 0
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const controller = new ConnectionController(api, {
+      onMuxEnvelope: envelope => muxSeen.push(envelope.payload.type),
+      onConnected: () => { connected++ },
+    }, FAST)
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(connected).toBe(1) })
+      api.pushMux({ type: 'stream/error', error: { code: 'internal', message: 'impl broke', details: {} } })
+      await vi.waitFor(() => { expect(connected).toBe(2) }) // treated as loss → reconnect
+      expect(muxSeen).toEqual([]) // never forwarded to the business sink
+    } finally {
+      controller.stop()
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('isolates sink exceptions from the pump', async () => {
+    const api = new FakeApiClient()
+    const seen: string[] = []
+    let connected = 0
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    const controller = new ConnectionController(api, {
+      onMuxEnvelope: (envelope) => {
+        seen.push(envelope.payload.type)
+        throw new Error('business layer bug')
+      },
+      onConnected: () => { connected++ },
+    }, FAST)
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(connected).toBe(1) })
+      api.pushMux(subscribedFrame(1))
+      api.pushMux(subscribedFrame(2))
+      await vi.waitFor(() => { expect(seen).toHaveLength(2) }) // second frame still pumped
+      expect(connected).toBe(1) // no reconnect triggered by the sink throw
+    } finally {
+      controller.stop()
+      errorSpy.mockRestore()
+    }
+  })
+
+  it('holds onConnected until both streams establish even after describe succeeds', async () => {
+    const api = new FakeApiClient()
+    api.holdStreamOpen = true // describe resolves immediately; stream establishment is in the case's hand
+    let connected = 0
+    const controller = new ConnectionController(api, { onConnected: () => { connected++ } }, FAST)
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(api.callsOf('host.describe')).toHaveLength(1) })
+      await new Promise(resolve => setTimeout(resolve, 30))
+      expect(connected).toBe(0) // describe alone must not announce
+      api.releaseStreamOpens()
+      await vi.waitFor(() => { expect(connected).toBe(1) })
+    } finally {
+      controller.stop()
+    }
+  })
+
+  it('proceeds as connected via the timeout guard when a carrier never fires onOpen', async () => {
+    const api = new FakeApiClient()
+    api.suppressStreamOpen = true // misbehaving carrier: streams open but onOpen never fires
+    let connected = 0
+    const controller = new ConnectionController(api, { onConnected: () => { connected++ } }, { ...FAST, streamOpenTimeoutMs: 20 })
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(connected).toBe(1) }) // handshake resolved by the guard, not wedged
+    } finally {
+      controller.stop()
+    }
+  })
+
+  it('emits deduplicated connected/reconnecting state transitions', async () => {
+    const api = new FakeApiClient()
+    const states: ConnectionState[] = []
+    let connected = 0
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const controller = new ConnectionController(api, {
+      onConnected: () => { connected++ },
+      onStateChange: state => states.push(state),
+    }, FAST)
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(connected).toBe(1) })
+      expect(states).toEqual(['connected'])
+      api.failStreams(new Error('torn'))
+      await vi.waitFor(() => { expect(connected).toBe(2) })
+      expect(states).toEqual(['connected', 'reconnecting', 'connected'])
+    } finally {
+      controller.stop()
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('deduplicates consecutive reconnecting emissions across two straight failures', async () => {
+    const api = new FakeApiClient()
+    const gate = deferred<Awaited<ReturnType<FakeApiClient['onDescribe']>>>()
+    let describeCalls = 0
+    api.onDescribe = () => {
+      describeCalls++
+      return describeCalls <= 2 ? Promise.reject(new Error('down')) : gate.promise
+    }
+    const states: ConnectionState[] = []
+    let connected = 0
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const controller = new ConnectionController(api, {
+      onConnected: () => { connected++ },
+      onStateChange: state => states.push(state),
+    }, FAST)
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(describeCalls).toBe(3) })
+      gate.resolve(ok({ version: '0', cwd: '/f', attachedSessions: 0 }))
+      await vi.waitFor(() => { expect(connected).toBe(1) })
+      expect(states).toEqual(['reconnecting', 'connected']) // two failures, one reconnecting emission
+    } finally {
+      controller.stop()
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('runs with no sinks at all (every callback slot optional)', async () => {
+    const api = new FakeApiClient()
+    const controller = new ConnectionController(api, {}, FAST)
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(api.callsOf('host.describe')).toHaveLength(1) })
+      api.pushMux(subscribedFrame()) // pumped with sink undefined: dropped silently
+      await new Promise(resolve => setTimeout(resolve, 20))
+    } finally {
+      controller.stop()
+    }
+  })
+
+  it('start() is idempotent (one loop, one stream set)', async () => {
+    const api = new FakeApiClient()
+    let connected = 0
+    const controller = new ConnectionController(api, { onConnected: () => { connected++ } }, FAST)
+    controller.start()
+    controller.start()
+    try {
+      await vi.waitFor(() => { expect(connected).toBe(1) })
+      expect(api.openMuxCount).toBe(1)
+      expect(api.callsOf('host.describe')).toHaveLength(1)
+    } finally {
+      controller.stop()
+    }
+  })
+})
diff --git a/packages/client/connection/tests/fake-api.ts b/packages/client/connection/tests/fake-api.ts
new file mode 100644
index 0000000000..20cdf291e0
--- /dev/null
+++ b/packages/client/connection/tests/fake-api.ts
@@ -0,0 +1,154 @@
+// Test-local programmable IApiClient fake (NOT the fixture: fixture is a demo
+// data source on a real clock; behavior tests need per-case responses and
+// deferred-controlled timing). Streams are hand pumps: pushMux/pushHost.
+import type {
+  HostFrame, IApiClient, MuxFrame, RpcRequest, RpcResponse, SessionId,
+} from '../src/client/api.ts'
+import { RpcId } from '../src/client/api.ts'
+
+export interface Deferred<T> {
+  promise: Promise<T>
+  resolve(value: T): void
+  reject(error: unknown): void
+}
+
+/** Test-held settlement: the case decides when an RPC lands (history-pending injections etc.). */
+export function deferred<T>(): Deferred<T> {
+  let resolve!: (value: T) => void
+  let reject!: (error: unknown) => void
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return { promise, resolve, reject }
+}
+
+let nextRpc = 0
+
+export function ok<T>(value: T): RpcResponse<T> {
+  return { rpcId: RpcId(`fake-${nextRpc++}`), result: { ok: true, value } }
+}
+
+
+type StreamItem<F> = { kind: 'frame'; envelope: RpcRequest<F> } | { kind: 'end' } | { kind: 'fail'; error: unknown }
+
+interface StreamConn<F> {
+  feed(item: StreamItem<F>): void
+}
+
+export class FakeApiClient implements IApiClient {
+  /** Chronological call record: [method, payload]. */
+  readonly calls: { method: string; payload: unknown }[] = []
+
+  // Programmable slots (defaults answer OK-empty); reassign per case.
+  onList: (payload: unknown) => Promise<RpcResponse<{ items: never[] }>> = () => Promise.resolve(ok({ items: [] }))
+  onCreate: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-new' as SessionId }))
+  onHistory: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number })
+  => Promise<RpcResponse<{ events: never[]; hasMore: boolean }>> =
+    () => Promise.resolve(ok({ events: [], hasMore: false }))
+
+  onPrompt: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
+  onCancel: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
+  onDescribe: (payload: unknown) => Promise<RpcResponse<{ version: string; cwd: string; attachedSessions: number }>> =
+    () => Promise.resolve(ok({ version: '0-fake', cwd: '/f', attachedSessions: 0 }))
+
+  private readonly muxConns: StreamConn<MuxFrame>[] = []
+  private readonly hostConns: StreamConn<HostFrame>[] = []
+
+  readonly sessions: IApiClient['sessions'] = {
+    list: payload => this.record('session.list', payload, this.onList(payload)),
+    create: payload => this.record('session.create', payload, this.onCreate(payload)),
+    history: payload => this.record('session.history', payload, this.onHistory(payload)),
+    prompt: payload => this.record('session.prompt', payload, this.onPrompt(payload)),
+    cancel: payload => this.record('session.cancel', payload, this.onCancel(payload)),
+  }
+
+  readonly host: IApiClient['host'] = {
+    describe: payload => this.record('host.describe', payload, this.onDescribe(payload)),
+  }
+
+  /** When true, streams never fire onOpen (misbehaving-carrier material for the handshake timeout guard). */
+  suppressStreamOpen = false
+
+  /** When true, onOpen callbacks are parked instead of fired; releaseStreamOpens() fires them.
+   *  Lets a case hold the readiness handshake open (describe done, streams not yet "established"). */
+  holdStreamOpen = false
+  private heldOpens: (() => void)[] = []
+
+  releaseStreamOpens(): void {
+    const held = this.heldOpens
+    this.heldOpens = []
+    for (const fire of held) fire()
+  }
+
+  readonly events: IApiClient['events'] = {
+    mux: (_payload, signal, onOpen) => this.openStream(this.muxConns, signal, onOpen),
+    host: (_payload, signal, onOpen) => this.openStream(this.hostConns, signal, onOpen),
+  }
+
+  respond(): Promise<{ accepted: false; reason: 'not-pending' }> {
+    return Promise.resolve({ accepted: false, reason: 'not-pending' })
+  }
+
+  /** Push one mux frame to every open mux stream (rpcId minted unless pinned by the case). */
+  pushMux(frame: MuxFrame, rpcId?: string): void {
+    for (const conn of [...this.muxConns]) conn.feed({ kind: 'frame', envelope: { rpcId: RpcId(rpcId ?? `push-${nextRpc++}`), payload: frame } })
+  }
+
+  pushHost(frame: HostFrame, rpcId?: string): void {
+    for (const conn of [...this.hostConns]) conn.feed({ kind: 'frame', envelope: { rpcId: RpcId(rpcId ?? `push-${nextRpc++}`), payload: frame } })
+  }
+
+  /** End (clean close) or fail (throw) every open stream — reconnect-path material. */
+  endStreams(): void {
+    for (const conn of [...this.muxConns, ...this.hostConns]) conn.feed({ kind: 'end' })
+  }
+
+  failStreams(error: unknown): void {
+    for (const conn of [...this.muxConns, ...this.hostConns]) conn.feed({ kind: 'fail', error })
+  }
+
+  get openMuxCount(): number {
+    return this.muxConns.length
+  }
+
+  callsOf(method: string): unknown[] {
+    return this.calls.filter(c => c.method === method).map(c => c.payload)
+  }
+
+  private record<T>(method: string, payload: unknown, response: Promise<T>): Promise<T> {
+    this.calls.push({ method, payload })
+    return response
+  }
+
+  private async *openStream<F>(registry: StreamConn<F>[], signal: AbortSignal, onOpen?: () => void): AsyncGenerator<RpcRequest<F>> {
+    const inbox: StreamItem<F>[] = []
+    let wake: (() => void) | null = null
+    const conn: StreamConn<F> = {
+      feed: (item) => {
+        inbox.push(item)
+        wake?.()
+      },
+    }
+    registry.push(conn)
+    if (this.holdStreamOpen && onOpen !== undefined) this.heldOpens.push(onOpen)
+    else if (!this.suppressStreamOpen) onOpen?.()
+    try {
+      while (!signal.aborted) {
+        while (inbox.length > 0) {
+          const item = inbox.shift() as StreamItem<F>
+          if (item.kind === 'end') return
+          if (item.kind === 'fail') throw item.error
+          yield item.envelope
+        }
+        await new Promise<void>((resolve) => {
+          wake = resolve
+          signal.addEventListener('abort', () => { resolve() }, { once: true })
+        })
+        wake = null
+      }
+    } finally {
+      registry.splice(registry.indexOf(conn), 1)
+    }
+  }
+}
diff --git a/packages/client/connection/tests/fixture.spec.ts b/packages/client/connection/tests/fixture.spec.ts
new file mode 100644
index 0000000000..f67a8f14f0
--- /dev/null
+++ b/packages/client/connection/tests/fixture.spec.ts
@@ -0,0 +1,338 @@
+/**
+ * Fixture impl semantics: the demo data source must honor the same contract
+ * shapes as the real host (paging boundaries, rpcId echo, replay lifecycle,
+ * baseline replay, timing hooks) — this is the vitest-side drift detector for
+ * the hand-written fixture/host parallel implementations.
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { SessionId } from '../src/client/api.ts'
+import { RpcId } from '../src/client/api.ts'
+import type { HostFrame, MuxFrame, RpcMessage, RpcRequest } from '../src/client/api.ts'
+import { FixtureApiClient, createFixtureApi } from '../src/client/fixture.ts'
+
+const sid = (id: string): SessionId => id as SessionId
+const req = <P>(payload: P): RpcRequest<P> => ({ rpcId: RpcId(`t-${Math.abs(Math.sin(reqCount++)).toString(36).slice(2, 10)}`), payload })
+let reqCount = 0
+
+interface TimingHooks {
+  setHistoryDelay(ms: number): void
+  failNextHistory(): void
+  appendUser(id: string, msg: string): void
+  appendSilent(id: string, msg: string): void
+  breakStreams(): void
+}
+const timing = (): TimingHooks => (globalThis as Record<string, unknown>).__fxTiming as TimingHooks
+
+/** Collect stream frames until the predicate or a soft cap; abort ends the stream. */
+async function collect<F>(stream: AsyncIterable<RpcRequest<F>>, abort: AbortController, done: (frames: F[]) => boolean): Promise<F[]> {
+  const frames: F[] = []
+  for await (const envelope of stream) {
+    frames.push(envelope.payload)
+    if (done(frames) || frames.length > 500) {
+      abort.abort()
+      break
+    }
+  }
+  return frames
+}
+
+describe('createFixtureApi', () => {
+  it('serves the session list sorted by updatedAt desc and echoes rpcIds on every unary', async () => {
+    const api = createFixtureApi()
+    const request = req({})
+    const response = await api.sessions.list(request)
+    expect(response.rpcId).toBe(request.rpcId)
+    if (!response.result.ok) throw new Error('list failed')
+    expect(response.result.value.items.map(s => s.sessionId)).toEqual(['fx-alpha', 'fx-beta', 'fx-gamma'])
+    expect(response.result.value.items[1]?.parentSessionId).toBe('fx-alpha') // lineage material
+  })
+
+  it('pages history backwards on message-boundary cuts with seq-contiguous stitching', async () => {
+    const api = createFixtureApi()
+    const tail = await api.sessions.history(req({ sessionId: sid('fx-alpha'), maxMessages: 10 }))
+    if (!tail.result.ok) throw new Error('history failed')
+    const tailPage = tail.result.value
+    expect(tailPage.hasMore).toBe(true)
+    expect(tailPage.events[0]?.event.type).toBe('turn/start') // cut lands on a turn boundary
+    const boundary = tailPage.events[0]?.event.seq ?? 0
+    expect(boundary).toBeGreaterThan(0)
+    const older = await api.sessions.history(req({ sessionId: sid('fx-alpha'), beforeSeq: boundary, maxMessages: 10 }))
+    if (!older.result.ok) throw new Error('older failed')
+    const olderTail = older.result.value.events.at(-1)?.event
+    expect((olderTail?.seq ?? -1) + 1).toBe(boundary) // pages stitch with no hole/overlap
+    // Out-of-range beforeSeq clamps instead of exploding.
+    const clamped = await api.sessions.history(req({ sessionId: sid('fx-alpha'), beforeSeq: -5, maxMessages: 10 }))
+    if (!clamped.result.ok) throw new Error('clamped failed')
+    expect(clamped.result.value.events).toEqual([])
+    // Unknown session: empty page, not an error (history of a bare id).
+    const empty = await api.sessions.history(req({ sessionId: sid('no-such'), maxMessages: 10 }))
+    if (!empty.result.ok) throw new Error('empty failed')
+    expect(empty.result.value).toEqual({ events: [], hasMore: false })
+  })
+
+  it('create adds a session and pushes host/session-added to open host streams', async () => {
+    const api = createFixtureApi()
+    const abort = new AbortController()
+    const seen: HostFrame[] = []
+    const consuming = (async () => {
+      for await (const envelope of api.events.host(req({}), abort.signal)) {
+        seen.push(envelope.payload)
+        if (seen.length >= 1) abort.abort()
+      }
+    })()
+    await new Promise(resolve => setTimeout(resolve, 10)) // let the stream register
+    const created = await api.sessions.create(req({}))
+    if (!created.result.ok) throw new Error('create failed')
+    await consuming
+    if (!created.result.ok) throw new Error('create failed')
+    const createdId = created.result.value.sessionId
+    expect(seen).toEqual([{ type: 'host/session-added', sessionId: createdId }])
+    const list = await api.sessions.list(req({}))
+    if (!list.result.ok) throw new Error('list failed')
+    expect(list.result.value.items.some(s => s.sessionId === createdId)).toBe(true)
+  })
+
+  it('prompt replays a full streamed turn and cancel mid-replay freezes with (已中断)', async () => {
+    const api = createFixtureApi()
+    const created = await api.sessions.create(req({}))
+    if (!created.result.ok) throw new Error('create failed')
+    const id = created.result.value.sessionId
+    const abort = new AbortController()
+    const frames: MuxFrame[] = []
+    const consuming = (async () => {
+      for await (const envelope of api.events.mux(req({}), abort.signal)) {
+        frames.push(envelope.payload)
+        const last = envelope.payload
+        if (last.type === 'session/event' && last.event.type === 'turn/end') {
+          abort.abort()
+        }
+      }
+    })()
+    await new Promise(resolve => setTimeout(resolve, 10))
+    // Unknown session → session-not-found with the id echoed in details.
+    const missing = await api.sessions.prompt(req({ sessionId: sid('ghost'), mode: 'queue' as const, content: [{ type: 'text' as const, text: 'x' }] }))
+    expect(missing.result).toMatchObject({ ok: false, error: { code: 'session-not-found', details: { sessionId: 'ghost' } } })
+    // Real prompt: replay starts (running flips true), cancel freezes it.
+    const accepted = await api.sessions.prompt(req({ sessionId: id, mode: 'queue' as const, content: [{ type: 'text' as const, text: '取消我' }] }))
+    expect(accepted.result).toMatchObject({ ok: true, value: { accepted: true } })
+    await new Promise(resolve => setTimeout(resolve, 120)) // a couple of typewriter ticks
+    await api.sessions.cancel(req({ sessionId: id }))
+    await consuming
+    const types = frames.filter((f): f is Extract<MuxFrame, { type: 'session/event' }> => f.type === 'session/event').map(f => f.event.type)
+    expect(types).toContain('turn/start')
+    expect(types).toContain('user/message')
+    expect(types).toContain('assistant/chunk')
+    expect(types).toContain('assistant/message')
+    expect(types.at(-1)).toBe('turn/end')
+    const finalize = frames.find((f): f is Extract<MuxFrame, { type: 'session/event' }> => f.type === 'session/event' && f.event.type === 'assistant/message')
+    expect(JSON.stringify(finalize?.event.data)).toContain('（已中断）')
+    // Idle cancel: no replay in flight, must not explode; running flips false.
+    const idleCancel = await api.sessions.cancel(req({ sessionId: id }))
+    expect(idleCancel.result).toMatchObject({ ok: true })
+  })
+
+  it('steer during a replay inserts a steering message and the replay continues to completion', async () => {
+    const api = createFixtureApi()
+    const created = await api.sessions.create(req({}))
+    if (!created.result.ok) throw new Error('create failed')
+    const id = created.result.value.sessionId
+    const abort = new AbortController()
+    const framesPromise = collect<MuxFrame>(api.events.mux(req({}), abort.signal), abort,
+      frames => frames.some(f => f.type === 'session/event' && f.event.type === 'turn/end'))
+    await new Promise(resolve => setTimeout(resolve, 10))
+    await api.sessions.prompt(req({ sessionId: id, mode: 'queue' as const, content: [{ type: 'text' as const, text: '短' }] }))
+    await api.sessions.prompt(req({ sessionId: id, mode: 'steer' as const, content: [{ type: 'text' as const, text: '插话' }] }))
+    const frames = await framesPromise
+    const types = frames.filter((f): f is Extract<MuxFrame, { type: 'session/event' }> => f.type === 'session/event').map(f => f.event.type)
+    expect(types).toContain('steering/message')
+    expect(types.at(-1)).toBe('turn/end') // steer did not restart the turn
+  })
+
+  it('mux open replays the baseline: subscribed for running sessions + the resident approval with a stable rpcId', async () => {
+    const api = createFixtureApi()
+    const openOnce = async (): Promise<RpcRequest<MuxFrame>[]> => {
+      const abort = new AbortController()
+      const envelopes: RpcRequest<MuxFrame>[] = []
+      for await (const envelope of api.events.mux(req({}), abort.signal)) {
+        envelopes.push(envelope)
+        if (envelopes.length >= 2) abort.abort()
+      }
+      return envelopes
+    }
+    const first = await openOnce()
+    const second = await openOnce()
+    expect(first[0]?.payload).toMatchObject({ type: 'session/subscribed', sessionId: 'fx-alpha' })
+    expect((first[0]?.payload as { lastSeq: number }).lastSeq).toBeGreaterThan(0)
+    expect(first[1]?.payload).toMatchObject({ type: 'approval/requested', toolName: 'dangerous_tool' })
+    expect(second[1]?.rpcId).toBe(first[1]?.rpcId) // stable rpcId across replays (host replay semantics)
+  })
+
+  it('steer with no replay in flight falls through to a fresh queued turn; non-text blocks stringify empty', async () => {
+    const api = createFixtureApi()
+    const abort = new AbortController()
+    const framesPromise = collect<MuxFrame>(api.events.mux(req({}), abort.signal), abort,
+      frames => frames.some(f => f.type === 'session/event' && f.event.type === 'turn/end'))
+    await new Promise(resolve => setTimeout(resolve, 10))
+    const created = await api.sessions.create(req({}))
+    if (!created.result.ok) throw new Error('create failed')
+    // steer while idle + a non-text content block (covers the '' arm of the text join).
+    await api.sessions.prompt(req({
+      sessionId: created.result.value.sessionId, mode: 'steer' as const,
+      content: [{ type: 'text' as const, text: '短' }, { type: 'image', data: 'x' } as never],
+    }))
+    const frames = await framesPromise
+    const types = frames.filter((f): f is Extract<MuxFrame, { type: 'session/event' }> => f.type === 'session/event').map(f => f.event.type)
+    expect(types[0]).toBe('turn/start') // idle steer degraded to a queued turn, not a steering insert
+  })
+
+  it('gamma interval flip emits host/session-status and a running log-less session subscribes at lastSeq -1', async () => {
+    vi.useFakeTimers()
+    try {
+      const api = createFixtureApi()
+      const abort = new AbortController()
+      const hostSeen: HostFrame[] = []
+      const consuming = (async () => {
+        for await (const envelope of api.events.host(req({}), abort.signal)) hostSeen.push(envelope.payload)
+      })()
+      await vi.advanceTimersByTimeAsync(5001) // interval fires: fx-gamma flips running=true (no log exists)
+      expect(hostSeen).toContainEqual({ type: 'host/session-status', sessionId: sid('fx-gamma'), running: true })
+      // A mux stream opened now sees gamma in the baseline with lastSeq = -1 (empty log arm).
+      const mabort = new AbortController()
+      const baseline: MuxFrame[] = []
+      const muxConsuming = (async () => {
+        for await (const envelope of api.events.mux(req({}), mabort.signal)) {
+          baseline.push(envelope.payload)
+          if (baseline.length >= 3) mabort.abort()
+        }
+      })()
+      await vi.advanceTimersByTimeAsync(10)
+      mabort.abort()
+      await muxConsuming
+      expect(baseline).toContainEqual({ type: 'session/subscribed', sessionId: sid('fx-gamma'), lastSeq: -1 })
+      abort.abort()
+      await vi.advanceTimersByTimeAsync(10)
+      await consuming
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('respond is a typed stub: always not-pending', async () => {
+    const api = createFixtureApi()
+    expect(await api.respond({ type: 'client-response', rpcId: RpcId('x'), result: { ok: true, value: {} } })).toEqual({ accepted: false, reason: 'not-pending' })
+  })
+
+  it('describe answers the fixture identity', async () => {
+    const api = createFixtureApi()
+    const response = await api.host.describe(req({}))
+    expect(response.result).toMatchObject({ ok: true, value: { version: '0.0.0-fixture', attachedSessions: 1 } })
+  })
+
+  it('timing hooks: history delay + one-shot failure, silent append, and breakStreams end open generators', async () => {
+    const api = createFixtureApi()
+    const hooks = timing()
+    // One-shot transport failure after transit delay.
+    hooks.setHistoryDelay(5)
+    hooks.failNextHistory()
+    await expect(api.sessions.history(req({ sessionId: sid('fx-alpha'), maxMessages: 5 }))).rejects.toThrow(/simulated history transport failure/)
+    hooks.setHistoryDelay(0)
+    // The failure was one-shot: the next call succeeds.
+    const ok = await api.sessions.history(req({ sessionId: sid('fx-alpha'), maxMessages: 5 }))
+    expect(ok.result.ok).toBe(true)
+    // appendUser emits on the mux stream; appendSilent only lands in the log (lost frame).
+    const abort = new AbortController()
+    const seen: MuxFrame[] = []
+    const consuming = (async () => {
+      for await (const envelope of api.events.mux(req({}), abort.signal)) seen.push(envelope.payload)
+    })()
+    await new Promise(resolve => setTimeout(resolve, 10))
+    hooks.appendSilent('fx-alpha', '静默丢帧')
+    hooks.appendUser('fx-alpha', '正常直播')
+    await vi.waitFor(() => {
+      expect(seen.some(f => f.type === 'session/event' && JSON.stringify(f.event.data).includes('正常直播'))).toBe(true)
+    })
+    expect(seen.some(f => f.type === 'session/event' && JSON.stringify(f.event.data).includes('静默丢帧'))).toBe(false)
+    // But history serves the silent event (the client's repull finds it).
+    const repull = await api.sessions.history(req({ sessionId: sid('fx-alpha'), maxMessages: 5 }))
+    if (!repull.result.ok) throw new Error('repull failed')
+    expect(JSON.stringify(repull.result.value.events)).toContain('静默丢帧')
+    // breakStreams force-ends BOTH stream kinds without the client abort.
+    const habort = new AbortController()
+    const hostConsuming = (async () => {
+      for await (const _ of api.events.host(req({}), habort.signal)) { /* drain */ }
+    })()
+    await new Promise(resolve => setTimeout(resolve, 10))
+    hooks.breakStreams()
+    await consuming // returns because the stream broke, not because we aborted
+    await hostConsuming
+    expect(abort.signal.aborted).toBe(false)
+    expect(habort.signal.aborted).toBe(false)
+  })
+})
+
+describe('FixtureApiClient (protocol-level fake carrier)', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('doFetch is an unreachable tripwire (all protocol paths overridden)', () => {
+    const client = new FixtureApiClient()
+    // Protected at compile time only; reach it directly to pin the tripwire message.
+    expect(() => (client as unknown as { doFetch(): Promise<Response> }).doFetch()).toThrow(/doFetch must be unreachable/)
+  })
+
+  it('mints request ids, taps all four full forms, and never touches doFetch', async () => {
+    const client = new FixtureApiClient()
+    const tapped: RpcMessage[] = []
+    client.subscribeEnvelopes(batch => tapped.push(...batch))
+    const response = await client.sessions.list({})
+    expect(response.result.ok).toBe(true)
+    await client.respond({ type: 'client-response', rpcId: RpcId('r-x'), result: { ok: true, value: {} } })
+    await vi.waitFor(() => {
+      const kinds = tapped.map(m => m.type)
+      expect(kinds).toContain('client-request')
+      expect(kinds).toContain('server-response')
+      expect(kinds).toContain('client-response')
+    })
+    const request = tapped.find(m => m.type === 'client-request')
+    const reply = tapped.find(m => m.type === 'server-response')
+    expect(request?.rpcId).toBe(reply?.rpcId) // echo discipline holds through the fake carrier
+  })
+
+  it('covers the whole unary dispatch table', async () => {
+    const client = new FixtureApiClient()
+    const created = await client.sessions.create({})
+    if (!created.result.ok) throw new Error('create failed')
+    const id = created.result.value.sessionId
+    expect((await client.sessions.history({ sessionId: id })).result.ok).toBe(true)
+    expect((await client.sessions.prompt({ sessionId: id, mode: 'queue', content: [{ type: 'text', text: '嗨' }] })).result.ok).toBe(true)
+    expect((await client.sessions.cancel({ sessionId: id })).result.ok).toBe(true)
+    expect((await client.host.describe({})).result.ok).toBe(true)
+  })
+
+  it('fires onOpen at stream-iteration start and taps server-request full forms', async () => {
+    const client = new FixtureApiClient()
+    const tapped: RpcMessage[] = []
+    client.subscribeEnvelopes(batch => tapped.push(...batch))
+    const order: string[] = []
+    const abort = new AbortController()
+    for await (const envelope of client.events.mux({}, abort.signal, () => order.push('open'))) {
+      order.push(envelope.payload.type)
+      abort.abort()
+    }
+    expect(order[0]).toBe('open')
+    expect(order[1]).toBe('session/subscribed')
+    await vi.waitFor(() => {
+      expect(tapped.some(m => m.type === 'server-request')).toBe(true)
+    })
+    // Host stream side of the pair (same tap path).
+    const habort = new AbortController()
+    const hostOrder: string[] = []
+    const hostIterator = client.events.host({}, habort.signal, () => hostOrder.push('open'))[Symbol.asyncIterator]()
+    const raced = await Promise.race([hostIterator.next(), new Promise<'idle'>(resolve => setTimeout(() => { resolve('idle') }, 50))])
+    expect(hostOrder).toEqual(['open']) // established even though the host stream stays silent
+    habort.abort()
+    if (raced === 'idle') await hostIterator.return?.(undefined)
+  })
+})
diff --git a/packages/client/connection/tests/node-half.spec.ts b/packages/client/connection/tests/node-half.spec.ts
new file mode 100644
index 0000000000..efba1b0445
--- /dev/null
+++ b/packages/client/connection/tests/node-half.spec.ts
@@ -0,0 +1,10 @@
+/** Node half: the empty host apply (Loader governance + dshClient discovery placeholder). */
+import { describe, expect, it } from 'vitest'
+import { apply } from '../src/index.ts'
+
+describe('node half', () => {
+  it('apply is a no-op host placeholder', () => {
+    apply(undefined)
+    expect(true).toBe(true) // reaching here without throw is the contract
+  })
+})
diff --git a/packages/client/connection/tsconfig.json b/packages/client/connection/tsconfig.json
new file mode 100644
index 0000000000..3f45ca0231
--- /dev/null
+++ b/packages/client/connection/tsconfig.json
@@ -0,0 +1,42 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "lib": [
+      "ES2024",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": []
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../util/brand"
+    },
+    {
+      "path": "../../host/apiproxy"
+    },
+    {
+      "path": "../../ui/user-approval"
+    },
+    {
+      "path": "../../ui/user-interaction"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ],
+  "exclude": [
+    "**/*.legacy.*"
+  ]
+}
diff --git a/packages/client/connection/tsdown.config.ts b/packages/client/connection/tsdown.config.ts
new file mode 100644
index 0000000000..9be4570fb8
--- /dev/null
+++ b/packages/client/connection/tsdown.config.ts
@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-connection', ['lib/types/index.js', 'lib/types/invariant.js'])
diff --git a/packages/client/i18n/README.md b/packages/client/i18n/README.md
new file mode 100644
index 0000000000..db6be0fe2a
--- /dev/null
+++ b/packages/client/i18n/README.md
@@ -0,0 +1,16 @@
+# @deepseek-ai/dsh-client-i18n
+
+i18n plugin: I18nService (ns×locale dictionaries, bind(ns)→t with a stable function identity, locale store). Contract: api-contracts v3 §8.
+
+## Model Experience
+
+None, as the i18n registry serves browser UI copy; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **zh/en ship as empty structures** — the existing UI copy is inline Chinese; extraction into dictionaries is deferred repo-wide work, so `bind(ns)` consumers today mostly receive key-echo fallbacks.
+- **Locale switching re-renders the whole tree** — accepted as a low-frequency operation; no per-namespace subscription granularity.
diff --git a/packages/client/i18n/package.json b/packages/client/i18n/package.json
new file mode 100644
index 0000000000..1e3d81b275
--- /dev/null
+++ b/packages/client/i18n/package.json
@@ -0,0 +1,54 @@
+{
+  "name": "@deepseek-ai/dsh-client-i18n",
+  "description": "i18n plugin: I18nService (ns x locale dictionaries, bind(ns) -> t, locale store); zh/en skeleton",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [],
+    "platform": "web",
+    "immediately": true
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-client-web-react": "workspace:^"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}
diff --git a/packages/client/i18n/src/client/index.ts b/packages/client/i18n/src/client/index.ts
new file mode 100644
index 0000000000..b994cccace
--- /dev/null
+++ b/packages/client/i18n/src/client/index.ts
@@ -0,0 +1,108 @@
+/**
+ * i18n plugin, browser half: namespace x locale dictionary registry with a
+ * bound translate function whose reference is stable (safe for inject
+ * surfaces). Mounts ctx.i18n and seeds the zh/en base dictionaries.
+ * Contract: api-contracts v3 section 8.
+ */
+import type { Context } from 'cordis'
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import { en } from '../locales/en.ts'
+import { zh } from '../locales/zh.ts'
+
+/** Translate a key with optional params. */
+export type Translate = (key: string, params?: Record<string, unknown>) => string
+
+/** Locale dictionary: flat key to template string ({name} placeholders). */
+export type LocaleDict = Record<string, string>
+
+declare module 'cordis' {
+  interface Context {
+    i18n: I18nService
+  }
+}
+
+/** Fallback locale consulted after the active locale misses. */
+export const FALLBACK_LOCALE = 'zh'
+
+/** Shared namespace for shell-level texts. */
+export const COMMON_NS = 'common'
+
+/**
+ * Dictionary registry plus locale switch. Lookup chain per key: active locale
+ * -> zh fallback -> the key itself (missing text stays visible, fail loud in
+ * the UI rather than blank).
+ */
+export class I18nService {
+  private dicts = new Map<string, Map<string, LocaleDict>>()
+  private bound = new Map<string, Translate>()
+  private localeStore = createSnapshotStore<string>(FALLBACK_LOCALE)
+
+  /**
+   * Register a dictionary for a namespace and locale. Duplicate (ns, locale)
+   * throws (single occupant; a namespace's texts have one owner).
+   * @param ns - namespace.
+   * @param locale - locale tag (zh/en to start).
+   * @param dict - dictionary.
+   * @returns disposer (idempotent).
+   */
+  register(ns: string, locale: string, dict: LocaleDict): () => void {
+    let locales = this.dicts.get(ns)
+    if (!locales) {
+      locales = new Map()
+      this.dicts.set(ns, locales)
+    }
+    if (locales.has(locale)) throw new Error(`i18n namespace "${ns}" already has locale "${locale}"`)
+    locales.set(locale, dict)
+    return () => {
+      const owner = this.dicts.get(ns)
+      if (owner?.get(locale) === dict) owner.delete(locale)
+    }
+  }
+
+  /**
+   * Bind a namespace to a translate function. The returned reference is
+   * stable per namespace (repeat binds return the same function), so it can
+   * ride inject surfaces without breaking memoization.
+   * @param ns - namespace.
+   * @returns the translate function (reads the locale store at call time).
+   */
+  bind(ns: string): Translate {
+    let t = this.bound.get(ns)
+    if (!t) {
+      t = (key, params) => this.translate(ns, key, params)
+      this.bound.set(ns, t)
+      return t
+    }
+    return t
+  }
+
+  /** Active locale store (switching re-renders the tree; low frequency). */
+  get locale(): SnapshotStore<string> {
+    return this.localeStore
+  }
+
+  private translate(ns: string, key: string, params?: Record<string, unknown>): string {
+    const locales = this.dicts.get(ns)
+    const template = locales?.get(this.localeStore.getSnapshot())?.[key]
+      ?? locales?.get(FALLBACK_LOCALE)?.[key]
+      ?? key
+    if (!params) return template
+    return template.replace(/\{(\w+)\}/g, (match, name: string) =>
+      name in params ? String(params[name]) : match)
+  }
+}
+
+/** Required services (none; the loader passes the export surface as an object plugin). */
+export const inject: string[] = []
+
+/**
+ * Client plugin body: provide the i18n service with base dictionaries.
+ * @param ctx - client cordis context.
+ */
+export function apply(ctx: Context): void {
+  const i18n = new I18nService()
+  i18n.register(COMMON_NS, 'zh', zh)
+  i18n.register(COMMON_NS, 'en', en)
+  ctx.provide('i18n', i18n)
+}
diff --git a/packages/client/i18n/src/index.ts b/packages/client/i18n/src/index.ts
new file mode 100644
index 0000000000..1e2de41ace
--- /dev/null
+++ b/packages/client/i18n/src/index.ts
@@ -0,0 +1,11 @@
+/**
+ * i18n plugin, node half. Pure UI plugin: the empty apply exists so the
+ * plugin appears in the host cordis.yml / Loader (load and lifecycle follow
+ * the host; the browser half ships via exports["./client"], discovered
+ * through the package.json dshClient declaration). Everything else —
+ * I18nService, Translate, LocaleDict — lives in the client half; consumers
+ * import the /client subpath. Contract: api-contracts v3 section 8.
+ */
+
+/** Host plugin body — no host-side behavior for the i18n plugin. */
+export function apply(): void {}
diff --git a/packages/client/i18n/src/invariant.ts b/packages/client/i18n/src/invariant.ts
new file mode 100644
index 0000000000..b2c196e93b
--- /dev/null
+++ b/packages/client/i18n/src/invariant.ts
@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-i18n`.
+ * @module @deepseek-ai/dsh-client-i18n/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-i18n'
+
+/** Cordis companion plugin name. */
+export const name = 'client-i18n-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: ns-by-locale dictionary registry with a stable
+ * bind(ns) surface — it emits no cordis events and owns no cross-plugin
+ * mutable relation; fallback-chain resolution and locale-store behavior are
+ * asserted directly by this package's behavior specs.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/client/i18n/src/locales/en.ts b/packages/client/i18n/src/locales/en.ts
new file mode 100644
index 0000000000..f649177ac0
--- /dev/null
+++ b/packages/client/i18n/src/locales/en.ts
@@ -0,0 +1,2 @@
+/** en base dictionary for the common namespace (starter skeleton; texts land with their features). */
+export const en: Record<string, string> = {}
diff --git a/packages/client/i18n/src/locales/zh.ts b/packages/client/i18n/src/locales/zh.ts
new file mode 100644
index 0000000000..f3ff22d2b8
--- /dev/null
+++ b/packages/client/i18n/src/locales/zh.ts
@@ -0,0 +1,2 @@
+/** zh base dictionary for the common namespace (starter skeleton; texts land with their features). */
+export const zh: Record<string, string> = {}
diff --git a/packages/client/i18n/tests/i18n.spec.ts b/packages/client/i18n/tests/i18n.spec.ts
new file mode 100644
index 0000000000..12fef2c716
--- /dev/null
+++ b/packages/client/i18n/tests/i18n.spec.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+import { I18nService } from '@deepseek-ai/dsh-client-i18n/client'
+
+describe('I18nService', () => {
+  it('translates from the active locale with zh fallback then key passthrough', () => {
+    const i18n = new I18nService()
+    i18n.register('ns', 'zh', { hello: '你好', onlyZh: '仅中文' })
+    i18n.register('ns', 'en', { hello: 'Hello' })
+    const t = i18n.bind('ns')
+    expect(i18n.locale.getSnapshot()).toBe('zh')
+    expect(t('hello')).toBe('你好')
+    i18n.locale.set('en')
+    expect(t('hello')).toBe('Hello')
+    expect(t('onlyZh')).toBe('仅中文')
+    expect(t('missing.key')).toBe('missing.key')
+  })
+
+  it('interpolates {name} params and leaves unknown placeholders intact', () => {
+    const i18n = new I18nService()
+    i18n.register('ns', 'zh', { greet: '你好，{name}！第 {n} 次', partial: '{known} 与 {unknown}' })
+    const t = i18n.bind('ns')
+    expect(t('greet', { name: '世界', n: 2 })).toBe('你好，世界！第 2 次')
+    expect(t('partial', { known: 'A' })).toBe('A 与 {unknown}')
+    expect(t('greet')).toBe('你好，{name}！第 {n} 次')
+  })
+
+  it('bind returns a stable reference per namespace', () => {
+    const i18n = new I18nService()
+    expect(i18n.bind('a')).toBe(i18n.bind('a'))
+    expect(i18n.bind('a')).not.toBe(i18n.bind('b'))
+  })
+
+  it('duplicate (ns, locale) throws; disposer unregisters and is idempotent', () => {
+    const i18n = new I18nService()
+    const dispose = i18n.register('ns', 'zh', { k: 'v1' })
+    expect(() => i18n.register('ns', 'zh', { k: 'v2' })).toThrow('already has locale')
+    dispose()
+    dispose()
+    const t = i18n.bind('ns')
+    expect(t('k')).toBe('k')
+    i18n.register('ns', 'zh', { k: 'v2' })
+    expect(t('k')).toBe('v2')
+  })
+
+  it('locale store is subscribable (snapshot store contract)', () => {
+    const i18n = new I18nService()
+    let notified = 0
+    i18n.locale.subscribe(() => { notified += 1 })
+    i18n.locale.set('en')
+    expect(i18n.locale.getSnapshot()).toBe('en')
+    expect(notified).toBe(1)
+  })
+})
diff --git a/packages/client/i18n/tests/invariant.spec.ts b/packages/client/i18n/tests/invariant.spec.ts
new file mode 100644
index 0000000000..b992e50d52
--- /dev/null
+++ b/packages/client/i18n/tests/invariant.spec.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { apply as nodeApply } from '@deepseek-ai/dsh-client-i18n'
+import { apply as clientApply, COMMON_NS, I18nService, inject } from '@deepseek-ai/dsh-client-i18n/client'
+import * as I18nInvariant from '@deepseek-ai/dsh-client-i18n/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+describe('invariant companion', () => {
+  it('registers under the package name with an empty installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    await expect(ctx.plugin(I18nInvariant).await()).resolves.toBeDefined()
+  })
+
+  it('node-half apply is a no-op host placeholder', () => {
+    nodeApply()
+    expect(true).toBe(true) // reaching here without throw is the contract
+  })
+
+  it('client apply provides ctx.i18n seeded with the zh/en common namespace', async () => {
+    expect(inject).toEqual([])
+    const ctx = new Context()
+    await ctx.plugin({ inject, apply: clientApply }).await()
+    const i18n = ctx.get('i18n')
+    expect(i18n).toBeInstanceOf(I18nService)
+    // Seeded dictionaries occupy the (ns, locale) seats even while empty.
+    expect(() => (i18n as I18nService).register(COMMON_NS, 'zh', {})).toThrow('already has locale')
+    expect(() => (i18n as I18nService).register(COMMON_NS, 'en', {})).toThrow('already has locale')
+  })
+})
diff --git a/packages/client/i18n/tsconfig.json b/packages/client/i18n/tsconfig.json
new file mode 100644
index 0000000000..dd593f678d
--- /dev/null
+++ b/packages/client/i18n/tsconfig.json
@@ -0,0 +1,27 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "lib": [
+      "ES2024",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": []
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../web-react"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/client/i18n/tsdown.config.ts b/packages/client/i18n/tsdown.config.ts
new file mode 100644
index 0000000000..1c0802be49
--- /dev/null
+++ b/packages/client/i18n/tsdown.config.ts
@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-i18n', ['lib/types/index.js', 'lib/types/invariant.js'])
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
new file mode 100644
index 0000000000..01c4172902
--- /dev/null
+++ b/packages/client/runtime/README.md
@@ -0,0 +1,18 @@
+# @deepseek-ai/dsh-client-runtime
+
+Client cordis boot + core services: SlotsService (Service wrapper over SlotCore + 'slots/changed' bridge), SessionsService (list store projection, scope tree, bindings, ancestry), Session object layer, ClientLoader (`./loader` subpath, statically held by the shell). Contract: api-contracts v3 §4.
+
+## Model Experience
+
+None, as the client runtime hosts browser-side services and the session object layer; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **`loader.unload` is a stub (throws not-implemented)** — the full chain (fiber dispose → registration cascade → style removal) lands with the HMR project.
+- **Scope teardown is watch-approximated** — the most recently resolved binding stands in for "who is watching"; a removed-while-watched session's scope survives until the watch moves away, not until true observer count reaches zero.
+- **Value imports of this package from plugin bundles must use the `/client` subpath** — the bare package name is not in the loader externals table and inlines a second module instance, whose private scope-tag Symbol never matches (the empty-state P0 postmortem).
+- **`SessionSummary.title` is a display projection** — the wire summary carries no title yet; the cwd basename stands in, then the raw id.
diff --git a/packages/client/runtime/package.json b/packages/client/runtime/package.json
new file mode 100644
index 0000000000..d17ff8e4b4
--- /dev/null
+++ b/packages/client/runtime/package.json
@@ -0,0 +1,63 @@
+{
+  "name": "@deepseek-ai/dsh-client-runtime",
+  "description": "Client cordis boot and core services: SlotsService, SessionsService (scope tree + object layer), ClientLoader",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./loader": {
+      "types": "./lib/types/client/loader/index.d.ts",
+      "default": "./lib/loader.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-client-connection"
+    ],
+    "platform": "web",
+    "immediately": true
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-client-web-react": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "react": "^18.2.0",
+    "@deepseek-ai/dsh-session": "workspace:^"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/loader.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}
diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
new file mode 100644
index 0000000000..6c012fa410
--- /dev/null
+++ b/packages/client/runtime/src/client/index.ts
@@ -0,0 +1,128 @@
+/**
+ * Browser half: the whole runtime contract surface (api-contracts v3 §4) —
+ * SlotsService, SessionsService (list store + scope tree + object layer),
+ * the ClientLoader interface, and the cordis Context/Events merges. apply
+ * mounts ctx.slots + ctx.sessions and wires the connection stream loop into
+ * the object layer. The loader machinery implementation is NOT in the plugin
+ * bundle — it ships via the package's `./loader` subpath, statically held by
+ * the web shell (a loader cannot load itself).
+ */
+import type { Context } from 'cordis'
+import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
+import type { SessionBinding as GenericSessionBinding } from '@deepseek-ai/dsh-client-ui-slots'
+import type { SnapshotStore, UseSession } from '@deepseek-ai/dsh-client-web-react'
+import { SlotsService } from './slots.ts'
+import { SessionsService } from './sessions/service.ts'
+import type { ConversationSnapshot, RunningToolCall, ToolResultNode } from './sessions/conversation.ts'
+
+export { SlotsService } from './slots.ts'
+export { SessionsService, scopeOf } from './sessions/service.ts'
+export type { SessionBinding, SessionListState, SessionSummary } from './sessions/service.ts'
+export { SessionManager } from './sessions/manager.ts'
+export type { SessionListSnapshot } from './sessions/manager.ts'
+export { Session, PAGE_MESSAGES } from './sessions/session.ts'
+export type { SessionListEntry } from './sessions/lineage.ts'
+export type {
+  AssistantBlock, AssistantMessageNode, ContextMessageNode, ConversationNode, ConversationSnapshot,
+  OpenState, PartialAssistant, PendingInteraction, PromptError, RunningToolCall, SteeringMessageNode,
+  ToolResultNode, UnknownSurfaceNode, UserMessageNode,
+} from './sessions/conversation.ts'
+export type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+
+// ---- Narrowed aliases (the single narrowing point of the slot type chain:
+// ui-slots/web-react stay generic and dependency-inverted; the client-tree
+// concrete types live here, where their subjects live) ----
+
+/**
+ * The client cordis context face: the base Context plus the service keys
+ * this package's declaration merge contributes (slots/sessions/loader) and
+ * every later plugin's merge. A plain alias — the merges land on Context
+ * itself inside the client program; the name marks intent at consumer seams.
+ */
+export type ClientContext = Context
+
+/** SessionBinding narrowed to the client context (inject factories dot services directly). */
+export type ClientSessionBinding = GenericSessionBinding<ClientContext>
+
+/** The conversation-snapshot selector hook (ConvViewProps/ToolViewProps take this). */
+export type UseConversationSession = UseSession<ConversationSnapshot>
+
+/**
+ * One tool call as the chat flow renders it: still-running (spinner card) or
+ * settled (result node). The fold produces both shapes; toolview components
+ * narrow on the discriminant fields.
+ */
+export type ToolCallBlock = RunningToolCall | ToolResultNode
+
+declare module 'cordis' {
+  interface Events {
+    /**
+     * A slot's definition or registration set changed.
+     * @mode emit
+     * @param key - the mutated SlotMap key.
+     */
+    'slots/changed'(key: string): void
+  }
+  interface Context {
+    slots: import('./slots.ts').SlotsService
+    sessions: import('./sessions/service.ts').SessionsService
+    loader: ClientLoader
+  }
+}
+
+/** One __DSH_BOOT__ manifest row. */
+export interface BootPluginEntry { id: string; url: string; inject: string[]; immediately?: boolean }
+
+/** Per-plugin load status store shape. */
+export type LoaderStatus = Record<string, 'loading' | 'active' | 'failed'>
+
+/**
+ * Client bundle loader. The immediately group loads first (parallel fetch,
+ * apply in inject topology order); remaining plugins follow in inject
+ * topology. Loaded bundle export surfaces are registered back into the
+ * require module table. Implementation lives in the `./loader` subpath
+ * (shell-held machinery).
+ */
+export interface ClientLoader {
+  /** Start loading from window.__DSH_BOOT__ (non-blocking). */
+  start(): void
+  /**
+   * Load one plugin bundle (script inject, factory handoff, ctx.plugin, style registration).
+   * @param id - plugin id (package name).
+   */
+  load(id: string): Promise<void>
+  /**
+   * Unload a plugin. P-I: not implemented (full chain lands with HMR).
+   * @param id - plugin id.
+   */
+  unload(id: string): Promise<void>
+  /** Resolves when every manifest plugin reached active (AppRoot gates the real UI on this). */
+  settled(): Promise<void>
+  /**
+   * Read a loaded module's export surface from the module table (same
+   * implementation the bundle-facing require uses; unknown spec throws).
+   * @param spec - module specifier (package name or seeded library id).
+   */
+  requireModule(spec: string): unknown
+  /** Per-plugin status store. */
+  readonly status: SnapshotStore<LoaderStatus>
+}
+
+/** Required services: the wire handle mounted by the connection plugin. */
+export const inject = ['connection']
+
+/**
+ * Client plugin body: mount slots + sessions, start the stream loop.
+ * @param ctx - client cordis context.
+ */
+export function apply(ctx: Context): void {
+  ctx.plugin(SlotsService)
+  const connection = ctx.get('connection') as ConnectionHandle
+  const sessions = new SessionsService(ctx, connection.api)
+  const loop = connection.start({
+    onMuxEnvelope: (envelope) => { sessions.manager.handleMuxEnvelope(envelope) },
+    onHostEnvelope: (envelope) => { sessions.manager.handleHostEnvelope(envelope) },
+    onConnected: () => { sessions.manager.handleConnected() },
+  })
+  ctx.effect(() => () => { loop.stop() }, 'runtime: connection stream loop')
+}
diff --git a/packages/client/runtime/src/client/loader/index.ts b/packages/client/runtime/src/client/loader/index.ts
new file mode 100644
index 0000000000..521c597ae4
--- /dev/null
+++ b/packages/client/runtime/src/client/loader/index.ts
@@ -0,0 +1,247 @@
+/**
+ * ClientLoader implementation (shell-held machinery — the loader cannot load
+ * itself, so the web shell imports this subpath statically and mounts the
+ * instance as ctx.loader; the runtime package's own client bundle never
+ * includes it).
+ *
+ * Load chain per plugin: fetch bundle text → execute (script injection) → the
+ * bundle calls window.DSHClientProxy.loadPlugin({id, factory}) (single-slot
+ * handoff, id reconciled) → factory(require) with require bound to the module
+ * table → ctx.plugin(exports.apply) → the export surface is registered into
+ * the module table under the plugin id (inject topology guarantees later
+ * loaders can require earlier ones) → <style data-plugin> ownership recorded.
+ *
+ * start(): the `immediately` group is fetched in parallel and executed in
+ * group-internal inject topology (execution is serial — the handoff slot is
+ * single); a full-group barrier precedes the remaining plugins, which then
+ * load one by one in inject topology.
+ */
+import type { Context } from 'cordis'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import type { BootPluginEntry, ClientLoader, LoaderStatus } from '../index.ts'
+
+export type { BootPluginEntry, ClientLoader, LoaderStatus } from '../index.ts'
+
+/** The shape a client bundle hands to window.DSHClientProxy.loadPlugin. */
+export interface ClientPluginHandoff {
+  /** Plugin id (package name) — must match the manifest row being loaded. */
+  id: string
+  /**
+   * Closure factory: receives the DI require and returns the module's export
+   * surface; an `apply` export is applied as a cordis plugin.
+   */
+  factory: (require: (spec: string) => unknown) => Record<string, unknown>
+}
+
+/** Window surface the loader owns (bundle side of the handoff protocol). */
+interface DshWindow {
+  __DSH_BOOT__?: { plugins: BootPluginEntry[] }
+  DSHClientProxy?: { loadPlugin(handoff: ClientPluginHandoff): void }
+}
+
+/** Options for createClientLoader (assembled by the web shell at boot). */
+export interface ClientLoaderOptions {
+  /** Client root context: plugin applies mount under it. */
+  ctx: Context
+  /**
+   * Seeded module table: pure-library entities (react, react-dom, cordis,
+   * ui-slots, web-react, ui-primitives). The loader takes ownership and
+   * registers loaded bundle export surfaces alongside them.
+   */
+  modules: Record<string, unknown>
+  /**
+   * Boot manifest; defaults to window.__DSH_BOOT__. Fixture pages inject the
+   * same protocol shape.
+   */
+  boot?: { plugins: BootPluginEntry[] }
+  /** Bundle fetch seam (parallelizable half). Defaults to same-origin fetch().text(). */
+  fetchBundle?: (url: string) => Promise<string>
+  /**
+   * Bundle execution seam (serial half; execution synchronously performs the
+   * loadPlugin handoff). Defaults to a <script> element carrying the code.
+   */
+  executeBundle?: (code: string, url: string) => void
+}
+
+/** Per-plugin bookkeeping across the load chain. */
+interface PluginRecord {
+  entry: BootPluginEntry
+  state: 'idle' | 'loading' | 'active' | 'failed'
+  fetch?: Promise<string>
+  load?: Promise<void>
+}
+
+const NOT_LOADED = Symbol('dsh.loader.not-loaded')
+
+/**
+ * Build the client bundle loader.
+ * @param options - ctx, seeded module table, boot manifest, fetch/execute seams.
+ * @returns the ClientLoader the shell mounts as ctx.loader.
+ */
+export function createClientLoader(options: ClientLoaderOptions): ClientLoader {
+  const { ctx } = options
+  const win = globalThis as DshWindow
+  const boot = options.boot ?? win.__DSH_BOOT__
+  if (boot === undefined) throw new Error('client-loader: no boot manifest (window.__DSH_BOOT__ missing)')
+
+  const modules = new Map<string, unknown>(Object.entries(options.modules))
+  const records = new Map<string, PluginRecord>()
+  for (const entry of boot.plugins) {
+    if (records.has(entry.id)) throw new Error(`client-loader: duplicate manifest id "${entry.id}"`)
+    records.set(entry.id, { entry, state: 'idle' })
+  }
+
+  const status = createSnapshotStore<LoaderStatus>({})
+  const publish = (id: string, state: 'loading' | 'active' | 'failed'): void => {
+    status.update((draft) => { draft[id] = state })
+  }
+
+  // Single-slot handoff: bundle execution synchronously calls loadPlugin;
+  // doLoad arms the slot before executing and reconciles the id after.
+  let slot: ClientPluginHandoff | typeof NOT_LOADED = NOT_LOADED
+  if (win.DSHClientProxy !== undefined) throw new Error('client-loader: window.DSHClientProxy already installed (double boot?)')
+  win.DSHClientProxy = {
+    loadPlugin: (handoff: ClientPluginHandoff): void => {
+      if (slot !== NOT_LOADED) {
+        throw new Error(`client-loader: overlapping loadPlugin handoff (got "${handoff.id}" while a previous handoff is unclaimed)`)
+      }
+      slot = handoff
+    },
+  }
+
+  const fetchBundle = options.fetchBundle ?? (async (url: string): Promise<string> => {
+    const res = await fetch(url)
+    if (!res.ok) throw new Error(`client-loader: bundle fetch ${url} answered ${String(res.status)}`)
+    return res.text()
+  })
+
+  const executeBundle = options.executeBundle ?? ((code: string, url: string): void => {
+    const el = document.createElement('script')
+    // Inline execution (not src) so the fetch half stays parallelizable; the
+    // sourceURL comment keeps devtools stack frames attributed to the bundle.
+    el.textContent = `${code}\n//# sourceURL=${url}`
+    document.head.appendChild(el)
+  })
+
+  const requireModule = (spec: string): unknown => {
+    if (!modules.has(spec)) {
+      throw new Error(`client-loader: module "${spec}" is not available — not a seeded library and no loaded plugin registered it (check dshClient.inject ordering)`)
+    }
+    return modules.get(spec)
+  }
+
+  /** Tag styles the bundle injected during execution (unload bookkeeping; plugin CSS lands untagged). */
+  const claimStyles = (id: string): void => {
+    if (typeof document === 'undefined') return
+    for (const el of document.querySelectorAll('style:not([data-plugin])')) {
+      el.setAttribute('data-plugin', id)
+    }
+  }
+
+  /** Start (or reuse) the parallelizable fetch half. */
+  const prefetch = (record: PluginRecord): Promise<string> =>
+    (record.fetch ??= fetchBundle(record.entry.url))
+
+  async function doLoad(record: PluginRecord): Promise<void> {
+    const { id } = record.entry
+    record.state = 'loading'
+    publish(id, 'loading')
+    try {
+      // Dependencies must already be active (start() sequences this; direct
+      // load() callers get the same fail-loud check).
+      for (const dep of record.entry.inject) {
+        const depRecord = records.get(dep)
+        if (depRecord === undefined) throw new Error(`client-loader: "${id}" injects unknown plugin "${dep}"`)
+        if (depRecord.state !== 'active') throw new Error(`client-loader: "${id}" loaded before its dependency "${dep}" is active`)
+      }
+      const code = await prefetch(record)
+      executeBundle(code, record.entry.url)
+      if (slot === NOT_LOADED) throw new Error(`client-loader: bundle ${record.entry.url} executed without calling DSHClientProxy.loadPlugin`)
+      const handoff = slot
+      slot = NOT_LOADED
+      if (handoff.id !== id) throw new Error(`client-loader: bundle id mismatch — manifest "${id}" vs handoff "${handoff.id}"`)
+      const exports = handoff.factory(requireModule)
+      if (typeof exports.apply !== 'function') throw new Error(`client-loader: plugin "${id}" exports no apply function`)
+      // The whole export surface is the plugin: cordis object-plugin form
+      // keeps the bundle's exported `inject`/`name` (an apply-only pass would
+      // silently drop the dependency declaration — postmortem 0001).
+      const fiber = ctx.plugin(exports as { apply: (ctx: Context) => void })
+      await fiber.await()
+      // Register under both specifier forms bundles emit: the bare package
+      // name (deep-import rewrites) and the /client subpath (CLIENT_EXTERNALS
+      // form) — the loaded surface IS the client half either way.
+      modules.set(id, exports)
+      modules.set(`${id}/client`, exports)
+      claimStyles(id)
+      record.state = 'active'
+      publish(id, 'active')
+    } catch (error) {
+      record.state = 'failed'
+      publish(id, 'failed')
+      throw error
+    }
+  }
+
+  const load = (id: string): Promise<void> => {
+    const record = records.get(id)
+    if (record === undefined) return Promise.reject(new Error(`client-loader: unknown plugin "${id}"`))
+    record.load ??= doLoad(record)
+    return record.load
+  }
+
+  /** Topologically order `ids` by inject (edges inside the set only — an early-group member never waits on a later-group one). */
+  const topo = (ids: string[]): string[] => {
+    const pool = new Set(ids)
+    const ordered: string[] = []
+    const done = new Set<string>()
+    const visiting = new Set<string>()
+    const visit = (id: string): void => {
+      if (done.has(id)) return
+      if (visiting.has(id)) throw new Error(`client-loader: inject cycle through "${id}"`)
+      visiting.add(id)
+      const record = records.get(id)
+      /* v8 ignore next -- ids come from records; unknown ids are caught per-dep below. */
+      if (record === undefined) throw new Error(`client-loader: manifest references unknown plugin "${id}"`)
+      for (const dep of record.entry.inject) {
+        if (!records.has(dep)) throw new Error(`client-loader: "${id}" injects unknown plugin "${dep}"`)
+        if (pool.has(dep)) visit(dep)
+      }
+      visiting.delete(id)
+      done.add(id)
+      ordered.push(id)
+    }
+    for (const id of ids) visit(id)
+    return ordered
+  }
+
+  let settledPromise: Promise<void> | undefined
+
+  async function run(): Promise<void> {
+    const all = [...records.values()]
+    const early = all.filter(r => r.entry.immediately === true)
+    const rest = all.filter(r => r.entry.immediately !== true)
+    // Early group: parallel fetch (all requests in flight at once), serial
+    // inject-topology execution, full-group barrier before anything else.
+    const earlyOrder = topo(early.map(r => r.entry.id))
+    for (const record of early) void prefetch(record).catch(() => {}) // surfaced by the awaited load below
+    for (const id of earlyOrder) await load(id)
+    // Remaining plugins: one by one in inject topology.
+    for (const id of topo(rest.map(r => r.entry.id))) await load(id)
+  }
+
+  return {
+    start: () => {
+      settledPromise ??= run()
+      // Failures surface through settled()/status — start() itself is fire-and-forget.
+      settledPromise.catch(() => {})
+    },
+    load,
+    unload: (id: string) => Promise.reject(new Error(`client-loader: unload("${id}") is not implemented (lands with HMR)`)),
+    settled: () => {
+      if (settledPromise === undefined) throw new Error('client-loader: settled() before start()')
+      return settledPromise
+    },
+    requireModule,
+    status,
+  }
+}
diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts
new file mode 100644
index 0000000000..18c5501972
--- /dev/null
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -0,0 +1,165 @@
+// ConversationSnapshot / ConversationNode: the only data shape the logic layer feeds the UI.
+// Immutability contract: every change swaps the top-level object; unchanged
+// substructures keep their references (the React.memo premise). callId/approvalId stay plain
+// string here (narrow to real brands when convenient).
+
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { RpcError, RpcId, SessionId, ToolCallView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
+
+/** Assistant content blocks sorted by what the UI cares about
+ *  (text body / collapsible reasoning / tool-call card head / other fallback). */
+export type AssistantBlock =
+  | { kind: 'text'; text: string }
+  | { kind: 'reasoning'; text: string }
+  | { kind: 'tool-call'; callId: string; name: string; argsRaw: string }
+  | { kind: 'other'; block: unknown }
+
+/**
+ * core ContentBlock[] -> AssistantBlock[] (classifier shared by finalized messages and partial block-end).
+ * @param content - core content blocks verbatim.
+ * @returns UI-classified blocks in source order.
+ */
+export function toAssistantBlocks(content: readonly ContentBlock[]): AssistantBlock[] {
+  return content.map(toAssistantBlock)
+}
+
+/**
+ * Classify one block (ToolCallBlock fields are id/arguments, mapped to callId/argsRaw).
+ * @param block - one core content block.
+ * @returns the UI classification.
+ */
+export function toAssistantBlock(block: ContentBlock): AssistantBlock {
+  switch (block.type) {
+    case 'text': return { kind: 'text', text: block.text }
+    case 'reasoning': return { kind: 'reasoning', text: block.text }
+    case 'tool-call': return { kind: 'tool-call', callId: String(block.id), name: block.name, argsRaw: block.arguments }
+    default: return { kind: 'other', block }
+  }
+}
+
+/** A finalized user message. */
+export interface UserMessageNode {
+  kind: 'user'
+  seq: number
+  content: readonly ContentBlock[]
+  source: unknown
+}
+
+/** A finalized (or interruption-frozen) assistant message. */
+export interface AssistantMessageNode {
+  kind: 'assistant'
+  seq: number
+  turn: number
+  step: number
+  blocks: readonly AssistantBlock[]
+  usage?: unknown
+  /** Frozen partial of an aborted turn (no finalize ever arrives): rendered with a 已停止 marker.
+   *  Synthetic seq (fractional, derived from the turn/end seq) keeps it ordered inside the flow. */
+  interrupted?: true
+}
+
+/** A steering message injected mid-turn. */
+export interface SteeringMessageNode {
+  kind: 'steering'
+  seq: number
+  turn: number
+  content: readonly ContentBlock[]
+  source: unknown
+}
+
+/** A context/system injection surfaced in the flow. */
+export interface ContextMessageNode {
+  kind: 'context'
+  seq: number
+  content: readonly ContentBlock[]
+  source: unknown
+  meta?: unknown
+}
+
+/** A tool result paired (when in-window) with its call head. */
+export interface ToolResultNode {
+  kind: 'tool-result'
+  seq: number
+  callId: string
+  /** Call head backfilled from the in-window tool/call; null when window truncation left the call outside (card head shows callId). */
+  call: { name: string; argsRaw: string } | null
+  content: readonly ContentBlock[]
+  isError: boolean
+  error?: { name: string; code: string }
+  meta?: unknown
+  /** Host-computed render intent from the paired tool/call's wire view; null = generic JSON card (documented default). */
+  callView: ToolCallView | null
+  /** Host-computed render intent from this tool/result's wire view; null = same default. */
+  resultView: ToolResultView | null
+}
+
+/** Fallback for surface events this UI version does not know. */
+export interface UnknownSurfaceNode {
+  kind: 'unknown'
+  seq: number
+  type: string
+  data: unknown
+}
+
+/** Finalized conversation node union (kind discriminates; seq is the React key). */
+export type ConversationNode =
+  | UserMessageNode
+  | AssistantMessageNode
+  | SteeringMessageNode
+  | ContextMessageNode
+  | ToolResultNode
+  | UnknownSurfaceNode
+
+/** In-flight tool card material: tool/call seen, tool/result not yet. */
+export interface RunningToolCall {
+  callId: string
+  name: string
+  argsRaw: string
+  turn: number
+  step: number
+  /** Host-computed render intent riding the tool/call frame; null = generic JSON card. */
+  callView: ToolCallView | null
+}
+
+/** Approval/question placeholder cards (visible, not answerable;
+ *  rpcId = the requested frame's envelope id, the future respond backfill key). */
+export type PendingInteraction =
+  | { kind: 'approval'; rpcId: RpcId; approvalId: string; toolName: string; callId?: string; reason?: string }
+  | { kind: 'question'; rpcId: RpcId; questions: readonly unknown[] }
+
+/** In-progress assistant output (chunk accumulator product). */
+export interface PartialAssistant {
+  turn: number
+  step: number
+  blocks: readonly AssistantBlock[]
+}
+
+/** History-open lifecycle of a Session window. */
+export type OpenState = 'cold' | 'loading' | 'open' | 'error'
+
+/** Send/stop failure surfaced in the input error strip; op picks the user-facing copy (发送失败 vs 停止失败). */
+export interface PromptError {
+  op: 'send' | 'stop'
+  error: RpcError
+}
+
+/** The immutable snapshot contract Session hands to uSES (see the web client architecture RFC). */
+export interface ConversationSnapshot {
+  sessionId: SessionId
+  /** Surface fold product (finalized conversation nodes in surface order). */
+  nodes: readonly ConversationNode[]
+  /** Fold degradation flag (cross-window replace defense): when true, nodes come from the lenient linear scan. */
+  foldDegraded: boolean
+  partial: PartialAssistant | null
+  runningCalls: readonly RunningToolCall[]
+  pending: readonly PendingInteraction[]
+  running: boolean
+  /** Set after host/session-removed; the UI grays out and disables input. */
+  removed: boolean
+  openState: OpenState
+  openError: RpcError | null
+  hasMore: boolean
+  loadingOlder: boolean
+  promptError: PromptError | null
+  lastAgentError: string | null
+}
diff --git a/packages/client/runtime/src/client/sessions/fold-adapter.ts b/packages/client/runtime/src/client/sessions/fold-adapter.ts
new file mode 100644
index 0000000000..ccb48a0161
--- /dev/null
+++ b/packages/client/runtime/src/client/sessions/fold-adapter.ts
@@ -0,0 +1,194 @@
+// FoldAdapter: core SurfaceManager wiring + node materialization cache.
+// Padding sentinels solve the paged-window seq offset (core fold asserts seq === index);
+// a cross-window replace throw degrades to a lenient linear scan (foldDegraded —
+// the degradation lives in one branch function in this file, zero scattered removal points).
+
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+// Subpath export (package.json exports "./surface", alias added for this): all value imports
+// go through it — the package root points at lib/index.js (needs a build) which the vite
+// browser bundle cannot resolve; surface.ts has no Node dependencies.
+import { SurfaceManager, isSurfaceEligibleType } from '@deepseek-ai/dsh-session/surface'
+import type { ToolCallView, ToolEventView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
+import type { ConversationNode } from './conversation.ts'
+import { toAssistantBlocks } from './conversation.ts'
+
+/** In-window tool/call index entry (result-card backfill + runningCalls material). */
+export interface CallIndexEntry {
+  name: string
+  argsRaw: string
+  turn: number
+  step: number
+  /** Wire view riding the tool/call (envelope-level; never inside the event). */
+  callView: ToolCallView | null
+}
+
+/** Non-surface-eligible sentinel event (safely skipped by surfaceOpOf's undefined branch).
+ *  'noop/padding' is not a real event type on purpose: a genuine type with fake data would
+ *  surface as garbage the day anyone adds handling for it (design §D.1; the cast is the one
+ *  place a synthetic event enters the window). */
+function paddingEvent(seq: number): SessionEvent {
+  return { type: 'noop/padding', seq, time: 0, data: {} } as unknown as SessionEvent
+}
+
+/** One event -> UI node (pure function; the six-variant ConversationNode union). */
+function materializeNode(
+  event: SessionEvent,
+  callIndex: ReadonlyMap<string, CallIndexEntry>,
+  resultView: ToolResultView | null,
+): ConversationNode {
+  switch (event.type) {
+    case 'user/message':
+      return { kind: 'user', seq: event.seq, content: event.data.content, source: event.data.source }
+    case 'assistant/message':
+      return {
+        kind: 'assistant', seq: event.seq, turn: event.data.turn, step: event.data.step,
+        blocks: toAssistantBlocks(event.data.content), usage: event.data.usage,
+      }
+    case 'steering/message':
+      return { kind: 'steering', seq: event.seq, turn: event.data.turn, content: event.data.content, source: event.data.source }
+    case 'context/message':
+      return {
+        kind: 'context', seq: event.seq, content: event.data.content, source: event.data.source,
+        meta: event.data.meta,
+      }
+    case 'tool/result': {
+      const call = callIndex.get(String(event.data.callId))
+      return {
+        kind: 'tool-result', seq: event.seq, callId: String(event.data.callId),
+        call: call ? { name: call.name, argsRaw: call.argsRaw } : null,
+        content: event.data.content, isError: event.data.isError,
+        ...(event.data.error !== undefined ? { error: event.data.error } : {}),
+        meta: event.data.meta,
+        callView: call?.callView ?? null,
+        resultView,
+      }
+    }
+    /* v8 ignore next 2 -- defensive arm: fold output only carries the five
+    surface-eligible types, and each has a case above; reachable only if core
+    adds an eligible type. */
+    default:
+      return { kind: 'unknown', seq: event.seq, type: event.type, data: (event as { data?: unknown }).data }
+  }
+}
+
+/** Window fold over the core SurfaceManager (sentinel padding for the seq offset; degrades to a linear scan on cross-window replace). */
+export class FoldAdapter {
+  /** padded = [sentinel x baseSeq, ...window events]; SurfaceManager borrows this reference for lazy incremental folding. */
+  private padded: SessionEvent[] = []
+  private baseSeq = 0
+  private surface = new SurfaceManager(this.padded)
+  private nodeCache = new Map<number, ConversationNode>()
+  private degraded = false
+  private callIdx = new Map<string, CallIndexEntry>()
+  /** Wire result views keyed by the tool/result event's seq (views ride the envelope, not the event). */
+  private resultViews = new Map<number, ToolResultView>()
+  /** Window revision (bumped on reset/append) keying the nodes() result cache: an unchanged
+   *  window returns the previous ARRAY reference, not just cached elements — the snapshot's
+   *  reference-stability contract (§A.9.4) starts here. */
+  private rev = 0
+  private nodesResult: { rev: number; value: { nodes: ConversationNode[]; degraded: boolean } } | null = null
+
+  /** In-window tool/call index (Session uses it for runningCalls and result-card backfill). */
+  get callIndex(): ReadonlyMap<string, CallIndexEntry> {
+    return this.callIdx
+  }
+
+  /**
+   * Window rebuild (after open/resync/page prepend): new padded array, new
+   * SurfaceManager, cleared cache, rebuilt callIndex.
+   * @param events - the new window contents (seq-ascending).
+   * @param baseSeq - seq of the window head (sentinels pad below it).
+   * @param views - per-event wire views aligned with `events` by index (undefined slots for view-less events).
+   */
+  reset(events: readonly SessionEvent[], baseSeq: number, views?: readonly (ToolEventView | undefined)[]): void {
+    this.rev++
+    this.baseSeq = baseSeq
+    this.padded = []
+    for (let i = 0; i < baseSeq; i++) this.padded.push(paddingEvent(i))
+    for (const event of events) this.padded.push(event)
+    this.surface = new SurfaceManager(this.padded)
+    this.nodeCache.clear()
+    this.degraded = false
+    this.callIdx = new Map()
+    this.resultViews.clear()
+    for (let i = 0; i < events.length; i++) {
+      const event = events[i]
+      /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */
+      if (event !== undefined) this.indexCall(event, views?.[i])
+    }
+  }
+
+  /**
+   * Tail append (live session/event): push into the same array (incremental
+   * lazy fold applies) + incremental callIndex upkeep.
+   * @param event - the live event (seq = window tail + 1).
+   * @param view - host-computed tool view paired with the event when it is a tool call/result; indexed for card rendering.
+   */
+  append(event: SessionEvent, view?: ToolEventView): void {
+    this.rev++
+    this.padded.push(event)
+    this.indexCall(event, view)
+  }
+
+  /**
+   * Current node array + degradation flag. Same revision -> same array
+   * reference (memo boundary); node object references always come from the per-seq cache.
+   * @returns the fold projection for the current window revision.
+   */
+  nodes(): { nodes: ConversationNode[]; degraded: boolean } {
+    if (this.nodesResult !== null && this.nodesResult.rev === this.rev) return this.nodesResult.value
+    let seqs: readonly number[]
+    if (this.degraded) {
+      seqs = this.degradedSeqs()
+    } else {
+      try {
+        seqs = this.surface.nodes
+      } catch (error) {
+        console.error('[web-runtime] surface fold failed, degrading to linear scan:', error)
+        this.degraded = true
+        seqs = this.degradedSeqs()
+      }
+    }
+    const out: ConversationNode[] = []
+    for (const seq of seqs) {
+      const cached = this.nodeCache.get(seq)
+      if (cached !== undefined) {
+        out.push(cached)
+        continue
+      }
+      const event = this.padded[seq]
+      /* v8 ignore next -- sparse guard: both seq sources (surface fold and degradedSeqs) only emit indexes present in padded. */
+      if (event === undefined) continue
+      const node = materializeNode(event, this.callIdx, this.resultViews.get(seq) ?? null)
+      this.nodeCache.set(seq, node)
+      out.push(node)
+    }
+    const value = { nodes: out, degraded: this.degraded }
+    this.nodesResult = { rev: this.rev, value }
+    return value
+  }
+
+  /** Degradation branch: lenient linear scan ignoring surfaceOp/replace (all surface-eligible events in append order). */
+  private degradedSeqs(): number[] {
+    const seqs: number[] = []
+    for (let i = this.baseSeq; i < this.padded.length; i++) {
+      const event = this.padded[i]
+      if (event !== undefined && isSurfaceEligibleType(event.type)) seqs.push(event.seq)
+    }
+    return seqs
+  }
+
+  private indexCall(event: SessionEvent, view?: ToolEventView): void {
+    if (event.type === 'tool/result') {
+      if (view?.for === 'result') this.resultViews.set(event.seq, view.view)
+      return
+    }
+    if (event.type !== 'tool/call') return
+    this.callIdx.set(String(event.data.callId), {
+      name: event.data.name, argsRaw: event.data.arguments, turn: event.data.turn, step: event.data.step,
+      callView: view?.for === 'call' ? view.view : null,
+    })
+    // No backfill into already-materialized tool-result nodes for this callId
+    // (window order puts the call before its result; cannot happen on the normal path).
+  }
+}
diff --git a/packages/client/runtime/src/client/sessions/lineage.ts b/packages/client/runtime/src/client/sessions/lineage.ts
new file mode 100644
index 0000000000..4f67f33343
--- /dev/null
+++ b/packages/client/runtime/src/client/sessions/lineage.ts
@@ -0,0 +1,63 @@
+// flattenLineage: summaries -> flat list with lineage indentation (pure function).
+// Roots sort by updatedAt desc, DFS expansion with children in the same order; orphaned lineage
+// degrades to root level; cycles fail soft and emit as roots.
+
+import type { SessionId, SessionSummary } from '@deepseek-ai/dsh-client-connection/client'
+
+/** One flattened session-list row (summary + lineage indent depth). */
+export interface SessionListEntry {
+  sessionId: SessionId
+  updatedAt: number
+  running: boolean
+  parentSessionId?: SessionId
+  cwd?: string
+  /** Lineage indent depth: root = 0; the UI just multiplies by the indent width. */
+  depth: number
+}
+
+/**
+ * summaries -> flat list with lineage indentation (pure; roots by updatedAt
+ * desc, DFS children in the same order, orphans degrade to roots).
+ * @param summaries - the host's session.list items.
+ * @returns display rows in render order.
+ */
+export function flattenLineage(summaries: readonly SessionSummary[]): SessionListEntry[] {
+  const byId = new Map<SessionId, SessionSummary>()
+  for (const s of summaries) byId.set(s.sessionId, s)
+
+  const children = new Map<SessionId, SessionSummary[]>()
+  const roots: SessionSummary[] = []
+  for (const s of summaries) {
+    if (s.parentSessionId !== undefined && byId.has(s.parentSessionId)) {
+      const list = children.get(s.parentSessionId) ?? []
+      list.push(s)
+      children.set(s.parentSessionId, list)
+    } else {
+      roots.push(s) // root, or an orphan whose parent is absent from summaries (degrade to root, never drop)
+    }
+  }
+
+  const byUpdatedDesc = (a: SessionSummary, b: SessionSummary): number => b.updatedAt - a.updatedAt
+  roots.sort(byUpdatedDesc)
+
+  const out: SessionListEntry[] = []
+  const visited = new Set<SessionId>()
+  const walk = (s: SessionSummary, depth: number): void => {
+    if (visited.has(s.sessionId)) {
+      console.warn(`[web-runtime] lineage cycle at ${s.sessionId}; emitting as root`)
+      return
+    }
+    visited.add(s.sessionId)
+    out.push({ ...s, depth })
+    const kids = children.get(s.sessionId)
+    if (kids === undefined) return
+    kids.sort(byUpdatedDesc)
+    for (const kid of kids) walk(kid, depth + 1)
+  }
+  for (const root of roots) walk(root, 0)
+  // Cycle members (unreachable from any root): emit as roots so no entry is lost.
+  for (const s of summaries) {
+    if (!visited.has(s.sessionId)) walk(s, 0)
+  }
+  return out
+}
diff --git a/packages/client/runtime/src/client/sessions/manager.ts b/packages/client/runtime/src/client/sessions/manager.ts
new file mode 100644
index 0000000000..2881fea468
--- /dev/null
+++ b/packages/client/runtime/src/client/sessions/manager.ts
@@ -0,0 +1,250 @@
+// SessionManager: the instance cluster Map<SessionId, Session> (lazy-built, resident) + the frame
+// dispatch entry + list state, constructed and held by SessionsService (one per client runtime).
+// List data never enters zustand; React connects via subscribe/getListSnapshot.
+
+import type { IApiClient, HostFrame, MuxFrame, RpcError, RpcRequest, RpcResult, SessionId, SessionSummary } from '@deepseek-ai/dsh-client-connection/client'
+import { transportError } from '@deepseek-ai/dsh-client-connection/client'
+import type { SessionListEntry } from './lineage.ts'
+import { flattenLineage } from './lineage.ts'
+import { Notifier } from './notifier.ts'
+import { Session } from './session.ts'
+
+/** Immutable session-list snapshot for useSessionList. */
+export interface SessionListSnapshot {
+  items: readonly SessionListEntry[]
+  state: 'idle' | 'loading' | 'error'
+  error: RpcError | null
+}
+
+/** Per-session cap for pre-instantiation approval/question buffering (low-frequency frames; a few dozen covers any real backlog). */
+const PENDING_BUFFER_CAP = 32
+
+/** Instance cluster + frame entry + the session list (see the web client architecture RFC). */
+export class SessionManager {
+  private readonly sessions = new Map<SessionId, Session>()
+  /** Approval/question frame buffer for uninstantiated sessions: pending interactions never hit
+   *  history (cannot be backfilled on open), the one frame class that must not take the
+   *  drop-and-backfill path; replayed and cleared on instantiation. Bounded per session (these
+   *  frames are low-frequency; overflow drops oldest) and dropped on session-removed (audit S7). */
+  private readonly pendingBuffers = new Map<SessionId, RpcRequest<MuxFrame>[]>()
+  private summaries: SessionSummary[] = []
+  private listState: 'idle' | 'loading' | 'error' = 'idle'
+  private listError: RpcError | null = null
+  private listInflight: Promise<void> | null = null
+
+  private listSnapshotCache: SessionListSnapshot
+  /** Entry-identity cache (§C.2 reference stability): list rebuilds reuse the previous entry
+   *  object when every field matches — wire refreshes mint all-new summary objects, so identity
+   *  must be recovered by value or every SessionListItem memo misses on every refresh (audit S5). */
+  private entryCache = new Map<SessionId, SessionListEntry>()
+  private itemsCache: readonly SessionListEntry[] = []
+  private readonly notifier = new Notifier(() => {
+    this.listSnapshotCache = this.buildListSnapshot()
+  })
+
+  constructor(private readonly api: IApiClient) {
+    this.listSnapshotCache = this.buildListSnapshot()
+  }
+
+  // ---- Instance management ----
+
+  /**
+   * Lazy build: return the existing instance or construct one (no auto-open —
+   * open is triggered by the container's select callback).
+   * @param sessionId - the session to get.
+   * @returns the resident instance.
+   */
+  get(sessionId: SessionId): Session {
+    let session = this.sessions.get(sessionId)
+    if (session === undefined) {
+      session = new Session(sessionId, this.api)
+      this.sessions.set(sessionId, session)
+      // Sync the running bit from the list snapshot into the new instance (consistency when the list precedes open).
+      const summary = this.summaries.find(s => s.sessionId === sessionId)
+      if (summary !== undefined) session.handleRunning(summary.running)
+      // Replay approval/question frames buffered before instantiation (rpcId verbatim, same semantics as the subscribed baseline replay).
+      const buffered = this.pendingBuffers.get(sessionId)
+      if (buffered !== undefined) {
+        this.pendingBuffers.delete(sessionId)
+        for (const envelope of buffered) session.handleMuxEnvelope(envelope.rpcId, envelope.payload)
+      }
+    }
+    return session
+  }
+
+  // ---- List surface ----
+
+  /** Full refresh via session.list (single-flight: an in-flight call is reused). */
+  refreshList(): Promise<void> {
+    if (this.listInflight !== null) return this.listInflight
+    this.listState = 'loading'
+    this.listError = null
+    this.notifier.markDirty()
+    this.listInflight = (async () => {
+      try {
+        const { result } = await this.api.sessions.list({})
+        if (result.ok) {
+          this.summaries = result.value.items
+          this.listState = 'idle'
+          // Push running bits down to instantiated Sessions (the list is the authoritative summary source).
+          for (const s of this.summaries) this.sessions.get(s.sessionId)?.handleRunning(s.running)
+        } else {
+          this.listState = 'error'
+          this.listError = result.error
+        }
+      } catch (error) {
+        this.listState = 'error'
+        const folded = transportError<never>(error)
+        /* v8 ignore next -- the `? null` arm is unreachable: transportError always returns ok:false. */
+        this.listError = folded.ok ? null : folded.error
+      } finally {
+        this.listInflight = null
+        this.notifier.markDirty()
+      }
+    })()
+    return this.listInflight
+  }
+
+  /**
+   * Contract session.create; on success merge into summaries immediately (no
+   * wait for the next refresh).
+   * @param cwd - optional working directory for the new session.
+   * @returns the create result.
+   */
+  async create(cwd?: string): Promise<RpcResult<{ sessionId: SessionId }>> {
+    try {
+      const { result } = await this.api.sessions.create(cwd === undefined ? {} : { cwd })
+      if (result.ok && !this.summaries.some(s => s.sessionId === result.value.sessionId)) {
+        this.summaries = [
+          { sessionId: result.value.sessionId, updatedAt: Date.now(), running: false, ...(cwd !== undefined ? { cwd } : {}) },
+          ...this.summaries,
+        ]
+        this.notifier.markDirty()
+      }
+      return result
+    } catch (error) {
+      return transportError(error)
+    }
+  }
+
+  // ---- Subscription surface (for useSessionList) ----
+
+  /**
+   * uSES subscription entry for useSessionList.
+   * @param listener - change callback.
+   * @returns the unsubscribe function.
+   */
+  subscribe(listener: () => void): () => void {
+    return this.notifier.subscribe(listener)
+  }
+
+  /**
+   * Cached list snapshot (rebuilt lazily when dirty with no listeners).
+   * @returns the cached reference (stable until the next flush).
+   */
+  getListSnapshot(): SessionListSnapshot {
+    this.notifier.ensureFresh()
+    return this.listSnapshotCache
+  }
+
+  // ---- ConnectionController sinks (wired by boot) ----
+
+  /**
+   * Mux frame entry: sessionId-bearing frames go only to instantiated sessions
+   * (no lazy build; non-pending frames for uninstantiated sessions drop —
+   * history backfills them on open).
+   * @param envelope - the frame with its wire rpcId.
+   */
+  handleMuxEnvelope(envelope: RpcRequest<MuxFrame>): void {
+    const frame = envelope.payload
+    if (frame.type === 'stream/error') return // Controller already treats this as stream failure
+    const session = this.sessions.get(frame.sessionId)
+    if (session === undefined) {
+      // Approval/question frames never hit history: buffer for replay on instantiation;
+      // everything else drops (not instantiated — history fully backfills on open).
+      switch (frame.type) {
+        case 'approval/requested':
+        case 'approval/resolved':
+        case 'question/requested':
+        case 'question/resolved': {
+          const buffer = this.pendingBuffers.get(frame.sessionId) ?? []
+          buffer.push(envelope)
+          if (buffer.length > PENDING_BUFFER_CAP) buffer.splice(0, buffer.length - PENDING_BUFFER_CAP)
+          this.pendingBuffers.set(frame.sessionId, buffer)
+          return
+        }
+        default:
+          return
+      }
+    }
+    session.handleMuxEnvelope(envelope.rpcId, frame)
+  }
+
+  /**
+   * Host frame entry: list upkeep + per-instance running/removed/agent-error relay.
+   * @param envelope - the frame with its wire rpcId.
+   */
+  handleHostEnvelope(envelope: RpcRequest<HostFrame>): void {
+    const frame = envelope.payload
+    switch (frame.type) {
+      case 'host/session-added': {
+        if (!this.summaries.some(s => s.sessionId === frame.sessionId)) {
+          this.summaries = [
+            {
+              sessionId: frame.sessionId, updatedAt: Date.now(), running: false,
+              ...(frame.parentSessionId !== undefined ? { parentSessionId: frame.parentSessionId } : {}),
+            },
+            ...this.summaries,
+          ]
+          this.notifier.markDirty()
+        }
+        return
+      }
+      case 'host/session-removed': {
+        this.summaries = this.summaries.filter(s => s.sessionId !== frame.sessionId)
+        this.sessions.get(frame.sessionId)?.handleRemoved() // instance survives (resident-instance rule), only flagged in the snapshot
+        this.pendingBuffers.delete(frame.sessionId) // a removed session's buffered frames must not replay on a future instantiation
+        this.notifier.markDirty()
+        return
+      }
+      case 'host/session-status': {
+        this.summaries = this.summaries.map(s =>
+          s.sessionId === frame.sessionId && s.running !== frame.running ? { ...s, running: frame.running } : s)
+        this.sessions.get(frame.sessionId)?.handleRunning(frame.running)
+        this.notifier.markDirty()
+        return
+      }
+      case 'host/agent-error': {
+        this.sessions.get(frame.sessionId)?.handleAgentError(frame.message)
+        return // not reflected in the list
+      }
+      default:
+        return // stream/error ignored; unknown frames ignored (documented default)
+    }
+  }
+
+  /** After each connection generation (first connect included): refresh the list + resync opened instances (reconnect = rebuild). */
+  handleConnected(): void {
+    void this.refreshList()
+    for (const session of this.sessions.values()) void session.resync()
+  }
+
+  private buildListSnapshot(): SessionListSnapshot {
+    const fresh = flattenLineage(this.summaries)
+    const items = fresh.map((entry) => {
+      const prev = this.entryCache.get(entry.sessionId)
+      if (
+        prev !== undefined && prev.updatedAt === entry.updatedAt && prev.running === entry.running
+        && prev.parentSessionId === entry.parentSessionId && prev.cwd === entry.cwd && prev.depth === entry.depth
+      ) return prev
+      this.entryCache.set(entry.sessionId, entry)
+      return entry
+    })
+    for (const id of this.entryCache.keys()) {
+      if (!items.some(e => e.sessionId === id)) this.entryCache.delete(id)
+    }
+    const sameOrder = items.length === this.itemsCache.length && items.every((e, i) => e === this.itemsCache[i])
+    if (!sameOrder) this.itemsCache = items
+    return { items: this.itemsCache, state: this.listState, error: this.listError }
+  }
+}
diff --git a/packages/client/runtime/src/client/sessions/notifier.ts b/packages/client/runtime/src/client/sessions/notifier.ts
new file mode 100644
index 0000000000..b89904d727
--- /dev/null
+++ b/packages/client/runtime/src/client/sessions/notifier.ts
@@ -0,0 +1,61 @@
+// Notifier: subscription + microtask-batched notification primitive shared by Session and
+// SessionManager. Semantics: N markDirty calls collapse into one microtask flush;
+// the flush rebuilds the snapshot cache BEFORE notifying (useSyncExternalStore requires a stable
+// getSnapshot reference). With no listeners the rebuild is skipped and only the dirty bit is set
+// (keeps frame storms cheap); the next getSnapshot rebuilds lazily.
+
+/** Subscription + microtask-batched notification primitive (shared by Session and SessionManager). */
+export class Notifier {
+  private listeners = new Set<() => void>()
+  private dirty = false
+  private scheduled = false
+
+  /** @param rebuild - snapshot rebuild function injected by the owner (writes the owner's snapshotCache). */
+  constructor(private readonly rebuild: () => void) {}
+
+  /**
+   * uSES subscription entry.
+   * @param listener - change callback.
+   * @returns the unsubscribe function.
+   */
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener)
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+
+  /** State-change entry: mark dirty and schedule the batched flush. */
+  markDirty(): void {
+    this.dirty = true
+    if (this.scheduled) return
+    this.scheduled = true
+    queueMicrotask(() => {
+      this.scheduled = false
+      if (!this.dirty) return
+      if (this.listeners.size === 0) return // lazy: no subscribers, keep dirty for the next getSnapshot
+      this.dirty = false
+      this.rebuild()
+      for (const listener of this.listeners) listener()
+    })
+  }
+
+  /**
+   * Synchronous flush: controlled-input writes must notify in the same tick as
+   * onChange, or React rolls the DOM back to the stale value and the caret jumps to the end.
+   */
+  notifyNow(): void {
+    this.dirty = true
+    if (this.listeners.size === 0) return // lazy: same as markDirty, next getSnapshot rebuilds
+    this.dirty = false
+    this.rebuild()
+    for (const listener of this.listeners) listener()
+  }
+
+  /** Pre-getSnapshot check: rebuild synchronously when dirty (read path before first subscribe / while unobserved). */
+  ensureFresh(): void {
+    if (!this.dirty) return
+    this.dirty = false
+    this.rebuild()
+  }
+}
diff --git a/packages/client/runtime/src/client/sessions/partial.ts b/packages/client/runtime/src/client/sessions/partial.ts
new file mode 100644
index 0000000000..189febf253
--- /dev/null
+++ b/packages/client/runtime/src/client/sessions/partial.ts
@@ -0,0 +1,89 @@
+// PartialAccumulator: assistant/chunk accumulator.
+// Folds the six StreamChunk variants into AssistantBlock[] keyed by block index;
+// block-level immutability (a delta only swaps that block's reference).
+
+import type { StreamChunk } from '@deepseek-ai/dsh-llm/types'
+import type { AssistantBlock, PartialAssistant } from './conversation.ts'
+import { toAssistantBlock } from './conversation.ts'
+
+/** assistant/chunk accumulator: folds StreamChunks into AssistantBlock[] with block-level immutability. */
+export class PartialAccumulator {
+  // Sparse on purpose: block-start may arrive out of order, leaving holes until compaction.
+  private blocks: (AssistantBlock | undefined)[] = []
+  private changed = true
+  private snapshot: PartialAssistant
+
+  constructor(readonly turn: number, readonly step: number) {
+    this.snapshot = { turn, step, blocks: [] }
+  }
+
+  /**
+   * Fold one chunk.
+   * @param chunk - the stream chunk.
+   * @returns whether it caused a visible change (usage/finish return false, skipping notification).
+   */
+  push(chunk: StreamChunk): boolean {
+    switch (chunk.type) {
+      case 'block-start': {
+        this.blocks[chunk.index] = emptyBlock(chunk.blockType)
+        this.changed = true
+        return true
+      }
+      case 'text-delta': {
+        const prev = this.blocks[chunk.index]
+        this.blocks[chunk.index] = { kind: 'text', text: (prev?.kind === 'text' ? prev.text : '') + chunk.text }
+        this.changed = true
+        return true
+      }
+      case 'reasoning-delta': {
+        const prev = this.blocks[chunk.index]
+        this.blocks[chunk.index] = { kind: 'reasoning', text: (prev?.kind === 'reasoning' ? prev.text : '') + chunk.text }
+        this.changed = true
+        return true
+      }
+      case 'tool-call-delta': {
+        const prev = this.blocks[chunk.index]
+        const base = prev?.kind === 'tool-call' ? prev : { kind: 'tool-call' as const, callId: '', name: '', argsRaw: '' }
+        this.blocks[chunk.index] = {
+          kind: 'tool-call',
+          callId: base.callId || String(chunk.id),
+          name: chunk.name ?? base.name,
+          argsRaw: base.argsRaw + chunk.argumentsDelta,
+        }
+        this.changed = true
+        return true
+      }
+      case 'block-end': {
+        this.blocks[chunk.index] = toAssistantBlock(chunk.block)
+        this.changed = true
+        return true
+      }
+      default:
+        // usage / finish / merge-extensible unknown variants: no visible block change
+        // (finish is immediately followed by the assistant/message that supersedes the partial).
+        return false
+    }
+  }
+
+  /**
+   * Current partial projection.
+   * @returns the cached snapshot (the blocks array reference only changes after a mutation).
+   */
+  toPartial(): PartialAssistant {
+    if (this.changed) {
+      // Compact sparse indexes (out-of-order block-start) into render order.
+      this.snapshot = { turn: this.turn, step: this.step, blocks: this.blocks.filter((b): b is AssistantBlock => b !== undefined) }
+      this.changed = false
+    }
+    return this.snapshot
+  }
+}
+
+function emptyBlock(blockType: string): AssistantBlock {
+  switch (blockType) {
+    case 'text': return { kind: 'text', text: '' }
+    case 'reasoning': return { kind: 'reasoning', text: '' }
+    case 'tool-call': return { kind: 'tool-call', callId: '', name: '', argsRaw: '' }
+    default: return { kind: 'other', block: null }
+  }
+}
diff --git a/packages/client/runtime/src/client/sessions/service.ts b/packages/client/runtime/src/client/sessions/service.ts
new file mode 100644
index 0000000000..eb3268e10b
--- /dev/null
+++ b/packages/client/runtime/src/client/sessions/service.ts
@@ -0,0 +1,221 @@
+/**
+ * SessionsService: root sessions service — list snapshot store (manager
+ * projection), session scope tree (mintScope pattern: no-op plugin Fiber +
+ * ctx.extend scope tag), stable SessionBinding cache, ancestry walk.
+ *
+ * Scope lifecycle is watch-driven: a scope is minted lazily on first
+ * resolution; a session leaving the list tears its scope down only when
+ * nobody is watching it. "Watched" is approximated as the most recently
+ * resolved binding id — SessionProvider re-resolves on every selection
+ * change (keyed remount), so a switch away always re-evaluates the deferred
+ * teardown; a host-side death without list removal keeps the scope (frozen
+ * read-only view).
+ */
+import type { Context, Fiber } from 'cordis'
+import type { IApiClient, SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import { SessionManager } from './manager.ts'
+import type { Session } from './session.ts'
+
+/** Session list row projected from the host list RPC plus live stream increments. */
+export interface SessionSummary {
+  id: SessionId
+  title: string
+  cwd?: string
+  parentId?: SessionId
+  running: boolean
+  updatedAt: number
+}
+
+/** Session list store shape. */
+export interface SessionListState { ids: SessionId[]; byId: Record<SessionId, SessionSummary> }
+
+/** Session assembly handle for SessionProvider/inject factories (identity-stable per session). */
+export interface SessionBinding {
+  readonly sessionId: SessionId
+  readonly session: Session
+  readonly ctx: Context
+}
+
+/** Scope tag key (client counterpart of the host dsh-scope pattern). */
+const kScope = Symbol('dsh.client.scope')
+
+/**
+ * Read the session scope tag off a context.
+ * @param ctx - any client context.
+ * @returns the session id, or undefined on root contexts.
+ */
+export function scopeOf(ctx: Context): SessionId | undefined {
+  return (ctx as Context & { [kScope]?: SessionId })[kScope]
+}
+
+/** Shared no-op plugin backing each session scope fiber. */
+function sessionScope(): void {}
+
+/**
+ * Display title projection. The wire summary carries no title yet (P-I
+ * ledger): the project directory's basename stands in, then the raw id.
+ */
+function titleOf(cwd: string | undefined, id: SessionId): string {
+  if (cwd !== undefined && cwd !== '') {
+    const base = cwd.replace(/[/\\]+$/, '').split(/[/\\]/).pop()
+    if (base !== undefined && base !== '') return base
+  }
+  return id
+}
+
+interface ScopeRecord {
+  fiber: Fiber
+  ctx: Context
+  binding: SessionBinding
+}
+
+/** Root sessions service: list store, object-layer manager, scope tree, bindings, ancestry. */
+export class SessionsService {
+  /** List snapshot store (list RPC + host stream increments; re-pulled on reconnect). */
+  readonly list: SnapshotStore<SessionListState>
+  /** The object-layer instance cluster and frame dispatch entry (wired to the connection by the runtime apply). */
+  readonly manager: SessionManager
+
+  private readonly scopes = new Map<SessionId, ScopeRecord>()
+  /** Most recently resolved binding id — the watch approximation for deferred teardown. */
+  private watched: SessionId | undefined
+  /** Removed-while-watched sessions whose teardown waits for the watch to move away. */
+  private readonly deferredRemovals = new Set<SessionId>()
+
+  /**
+   * @param ctx - client root context (scope fibers mount under it).
+   * @param api - wire client shared with every Session.
+   */
+  constructor(private readonly rootCtx: Context, api: IApiClient) {
+    this.manager = new SessionManager(api)
+    this.list = createSnapshotStore<SessionListState>({ ids: [], byId: {} })
+    // The manager owns wire truth; the store is its projection. Manager
+    // notifications are already microtask-batched.
+    this.manager.subscribe(() => { this.projectList() })
+    rootCtx.reflect.provide('sessions', this, undefined)
+  }
+
+  /**
+   * Create a session on the host.
+   * @param opts - creation options (project directory).
+   * @returns the new session id.
+   */
+  async create(opts: { cwd?: string } = {}): Promise<SessionId> {
+    const result = await this.manager.create(opts.cwd)
+    if (!result.ok) throw new Error(`session create failed: ${result.error.code}: ${result.error.message}`)
+    return result.value.sessionId
+  }
+
+  /**
+   * Resolve a session-scoped context view (use-and-discard).
+   * @param id - session id.
+   * @returns scoped ctx, or undefined for a session neither listed nor already scoped.
+   */
+  scope(id: SessionId): Context | undefined {
+    return this.resolve(id)?.ctx
+  }
+
+  /**
+   * Resolve the stable session binding (SessionProvider's resolveBinding feed).
+   * @param id - session id.
+   * @returns binding, or undefined for a session neither listed nor already scoped.
+   */
+  binding(id: SessionId): SessionBinding | undefined {
+    const record = this.resolve(id)
+    if (record === undefined) return undefined
+    if (this.watched !== id) {
+      this.watched = id
+      this.sweepDeferred()
+    }
+    return record.binding
+  }
+
+  /**
+   * Breadcrumb feed: walk parentId links inside the list store.
+   * @param id - session id.
+   * @returns summaries from root ancestor to the session itself (empty when unknown; a broken link stops the walk).
+   */
+  ancestry(id: SessionId): SessionSummary[] {
+    const { byId } = this.list.getSnapshot()
+    const chain: SessionSummary[] = []
+    let cursor: SessionId | undefined = id
+    while (cursor !== undefined) {
+      const summary: SessionSummary | undefined = byId[cursor]
+      if (summary === undefined || chain.includes(summary)) break
+      chain.unshift(summary)
+      cursor = summary.parentId
+    }
+    return chain
+  }
+
+  /** Lazily mint the scope + binding for a listed (or already-scoped) session. */
+  private resolve(id: SessionId): ScopeRecord | undefined {
+    const existing = this.scopes.get(id)
+    if (existing !== undefined) return existing
+    // Frozen scopes outlive the list; new scopes are only minted for listed sessions.
+    if (this.list.getSnapshot().byId[id] === undefined) return undefined
+    const fiber = this.rootCtx.plugin(sessionScope)
+    const ctx = fiber.ctx.extend({ [kScope]: id })
+    const record: ScopeRecord = {
+      fiber,
+      ctx,
+      binding: { sessionId: id, session: this.manager.get(id), ctx },
+    }
+    this.scopes.set(id, record)
+    return record
+  }
+
+  /** Project the manager's list snapshot into the store (title derivation is display-only). */
+  private projectList(): void {
+    const items = this.manager.getListSnapshot().items
+    const ids: SessionId[] = []
+    const byId: Record<SessionId, SessionSummary> = {}
+    for (const entry of items) {
+      ids.push(entry.sessionId)
+      byId[entry.sessionId] = {
+        id: entry.sessionId,
+        title: titleOf(entry.cwd, entry.sessionId),
+        running: entry.running,
+        updatedAt: entry.updatedAt,
+        ...(entry.cwd !== undefined ? { cwd: entry.cwd } : {}),
+        ...(entry.parentSessionId !== undefined ? { parentId: entry.parentSessionId } : {}),
+      }
+    }
+    this.list.set({ ids, byId })
+    this.pruneScopes(byId)
+  }
+
+  /** Tear down scopes for removed sessions nobody watches; the watched one defers until the watch moves. */
+  private pruneScopes(byId: Record<SessionId, SessionSummary>): void {
+    for (const [id, record] of this.scopes) {
+      if (byId[id] !== undefined) continue
+      if (id === this.watched) {
+        this.deferredRemovals.add(id)
+        continue
+      }
+      this.scopes.delete(id)
+      this.deferredRemovals.delete(id)
+      void record.fiber.dispose()
+    }
+  }
+
+  /** Run deferred teardowns whose session is no longer watched (called when the watch moves). */
+  private sweepDeferred(): void {
+    for (const id of [...this.deferredRemovals]) {
+      if (id === this.watched) continue
+      // Still absent from the list? (A re-added id cancels the deferred teardown.)
+      if (this.list.getSnapshot().byId[id] !== undefined) {
+        this.deferredRemovals.delete(id)
+        continue
+      }
+      const record = this.scopes.get(id)
+      this.deferredRemovals.delete(id)
+      if (record !== undefined) {
+        this.scopes.delete(id)
+        void record.fiber.dispose()
+      }
+    }
+  }
+}
diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts
new file mode 100644
index 0000000000..0934118bd1
--- /dev/null
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -0,0 +1,527 @@
+// Session: wraps every contract call that needs a sessionId + all conversation state for this
+// session (design §A.2/§A.9/§D.2/§D.3). Instances are resident (ruling 2): never destroyed once
+// created, they keep consuming mux frames in the background; React connects directly via
+// subscribe/getSnapshot.
+
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type { HistoryEntry, IApiClient, MuxFrame, RpcError, RpcId, RpcResult, SessionId, ToolEventView } from '@deepseek-ai/dsh-client-connection/client'
+import { transportError } from '@deepseek-ai/dsh-client-connection/client'
+import type { ObservableSnapshot, SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
+import type {
+  ConversationNode, ConversationSnapshot, OpenState, PendingInteraction, PromptError, RunningToolCall,
+} from './conversation.ts'
+import { FoldAdapter } from './fold-adapter.ts'
+import { Notifier } from './notifier.ts'
+import { PartialAccumulator } from './partial.ts'
+
+/** Messages per page (F.4 ledger: promote to Config at graduation; every call site references this constant). */
+export const PAGE_MESSAGES = 50
+
+/** Per-session state owner: event window + fold + partial, snapshot out via uSES (see the web client architecture RFC). */
+export class Session implements ObservableSnapshot<ConversationSnapshot> {
+  /** Typed selector hook bound to this instance (the SessionBinding `useSession` source). */
+  readonly useSelector: SnapshotSelectorHook<ConversationSnapshot> = bindSnapshotSelector(this)
+
+  // ---- Window and derived state (all private; the snapshot is the only read surface) ----
+  private events: SessionEvent[] = []
+  /** Wire views aligned with `events` by index (envelope-level annotations; undefined = no view).
+   *  Kept parallel rather than merged so `events` stays the raw log slice (model-visible ⟺ logged). */
+  private views: (ToolEventView | undefined)[] = []
+  private baseSeq = 0
+  private hasMore = false
+  private openState: OpenState = 'cold'
+  private openError: RpcError | null = null
+  private openPromise: Promise<void> | null = null
+  /** Bumped by resync to invalidate an in-flight doOpen: a reconnect must rebuild, never adopt
+   *  a pre-disconnect open whose history request is already doomed (audit S4). Stale doOpen
+   *  passes drop all writes once the generation moves on. */
+  private openGeneration = 0
+  private loadingOlder = false
+  private readonly foldAdapter = new FoldAdapter()
+  private partial: PartialAccumulator | null = null
+  private openCalls = new Map<string, RunningToolCall>()
+  /** Interrupted-turn terminal nodes (frozen partial text / aborted tool cards), merged into the flow by seq.
+   *  Derived from window events (turn/end sweep) — rebuilt by rebuildDerivedFromWindow like partial/openCalls. */
+  private frozenNodes: ConversationNode[] = []
+  private pending = new Map<string, PendingInteraction>()
+  // Revision counters + caches backing the snapshot's reference-stability contract (§A.9.4/§C.2,
+  // audit S5): buildSnapshot reuses the previous array when the revision is unchanged, so
+  // React.memo children survive unrelated snapshot swaps (chunk storms must not re-render every
+  // tool card and pending card). Mutation sites bump the matching revision. partial needs no
+  // counter — PartialAccumulator.toPartial already returns a cached reference when unchanged.
+  private callsRev = 0
+  private callsCache: { rev: number; value: RunningToolCall[] } | null = null
+  private pendingRev = 0
+  private pendingCache: { rev: number; value: PendingInteraction[] } | null = null
+  private frozenRev = 0
+  private nodesCache: { folded: readonly ConversationNode[]; frozenRev: number; value: readonly ConversationNode[] } | null = null
+  private running = false
+  private removed = false
+  private promptError: PromptError | null = null
+  private lastAgentError: string | null = null
+  /** Buffer for live events arriving while open/resync is in flight (stitched by seq once history lands, §D.3). */
+  private liveBuffer: { event: SessionEvent; view: ToolEventView | undefined }[] = []
+  /** Gap-repair (resync-lite) in flight: acceptLiveEvent detours to liveBuffer until the tail page lands (audit S3). */
+  private stitching = false
+  /** subscribed.lastSeq baseline (gap detection; null when no subscribed frame arrived — degrade to the liveBuffer dedup path). */
+  private subscribedLastSeq: number | null = null
+
+  private snapshotCache: ConversationSnapshot
+  private readonly notifier = new Notifier(() => {
+    this.snapshotCache = this.buildSnapshot()
+  })
+
+  constructor(readonly sessionId: SessionId, private readonly api: IApiClient) {
+    this.snapshotCache = this.buildSnapshot()
+  }
+
+  // ---- Operations ----
+
+  /**
+   * Send (queue/steer passed through 1:1); failures land in the snapshot's promptError.
+   * @param content - core content blocks verbatim.
+   * @param mode - queue appends after the current turn; steer interrupts it.
+   * @returns the prompt result (also mirrored into promptError on failure).
+   */
+  async prompt(content: ContentBlock[], mode: 'queue' | 'steer'): Promise<RpcResult<{ accepted: true }>> {
+    this.promptError = null
+    this.lastAgentError = null
+    this.notifier.markDirty()
+    let result: RpcResult<{ accepted: true }>
+    try {
+      result = (await this.api.sessions.prompt({ sessionId: this.sessionId, mode, content })).result
+    } catch (error) {
+      result = transportError(error)
+    }
+    if (!result.ok) {
+      this.promptError = { op: 'send', error: result.error }
+      this.notifier.markDirty()
+    }
+    return result
+  }
+
+  /**
+   * Stop: contract session.cancel 1:1; failures land in promptError (same error-strip display slot).
+   * @returns the cancel result.
+   */
+  async cancel(): Promise<RpcResult<{ accepted: true }>> {
+    let result: RpcResult<{ accepted: true }>
+    try {
+      result = (await this.api.sessions.cancel({ sessionId: this.sessionId })).result
+    } catch (error) {
+      result = transportError(error)
+    }
+    if (!result.ok) {
+      this.promptError = { op: 'stop', error: result.error }
+      this.notifier.markDirty()
+    }
+    return result
+  }
+
+  /** First open: pull the tail page (idempotent — in-flight/already-open returns the existing promise). */
+  open(): Promise<void> {
+    if (this.openState === 'open') return Promise.resolve()
+    if (this.openPromise !== null) return this.openPromise
+    const promise = this.doOpen(this.openGeneration).finally(() => {
+      // Identity-guarded: a superseded open must not null out the promise resync just started.
+      if (this.openPromise === promise) this.openPromise = null
+    })
+    this.openPromise = promise
+    return promise
+  }
+
+  /** Page up: pull one earlier page with the window's first seq as beforeSeq and prepend (§D.2). */
+  async loadOlder(): Promise<void> {
+    if (this.openState !== 'open' || !this.hasMore || this.loadingOlder) return
+    this.loadingOlder = true
+    this.notifier.markDirty()
+    try {
+      const { result } = await this.api.sessions.history({
+        sessionId: this.sessionId, beforeSeq: this.baseSeq, maxMessages: PAGE_MESSAGES,
+      })
+      if (!result.ok) return // keep the window as-is; do not overwrite openError (open already succeeded)
+      const older = result.value.events
+      if (older.length === 0) {
+        this.hasMore = result.value.hasMore
+        return
+      }
+      const tail = older[older.length - 1]
+      if (tail === undefined || tail.event.seq + 1 !== this.baseSeq) {
+        // §D.2 continuity assertion: on violation drop the page fail-soft rather than render an out-of-order stream.
+        console.error(`[web-runtime] history page discontinuous: tail seq ${tail?.event.seq} vs baseSeq ${this.baseSeq}`)
+        this.hasMore = false
+        return
+      }
+      this.events = [...older.map(e => e.event), ...this.events]
+      this.views = [...older.map(e => e.view), ...this.views]
+      /* v8 ignore next -- the ?? arm needs older[0] undefined, but the empty-page branch above already returned. */
+      this.baseSeq = older[0]?.event.seq ?? this.baseSeq
+      this.hasMore = result.value.hasMore
+      this.foldAdapter.reset(this.events, this.baseSeq, this.views) // prepend forces a rebuild (sentinel count changed)
+      this.rebuildDerivedFromWindow()
+    } catch (error) {
+      console.error('[web-runtime] loadOlder failed:', error)
+    } finally {
+      this.loadingOlder = false
+      this.notifier.markDirty()
+    }
+  }
+
+  /** Reconnect rebuild (manager calls this on onConnected for instances that were opened):
+   *  reset the window and rerun open; pending waits for the baseline replay. Invalidates any
+   *  in-flight open first — its history request rode the dead connection and must not settle
+   *  the fresh generation into 'error' (audit S4). */
+  async resync(): Promise<void> {
+    if (this.openState === 'cold') return // never opened: no window to rebuild (doOpen flips to 'loading' synchronously, so cold implies no in-flight open)
+    this.openGeneration++
+    this.openPromise = null
+    this.openState = 'cold'
+    this.openError = null
+    this.events = []
+    this.views = []
+    this.baseSeq = 0
+    this.pending.clear() // the subscribed baseline replay re-sends still-pending requested frames verbatim
+    this.pendingRev++
+    this.subscribedLastSeq = null
+    this.liveBuffer = []
+    this.notifier.markDirty()
+    await this.open()
+  }
+
+  // ---- Subscription surface (useSyncExternalStore direct wiring) ----
+
+  /**
+   * uSES subscription entry.
+   * @param listener - change callback.
+   * @returns the unsubscribe function.
+   */
+  subscribe(listener: () => void): () => void {
+    return this.notifier.subscribe(listener)
+  }
+
+  /**
+   * Cached conversation snapshot (rebuilt lazily when dirty with no listeners).
+   * @returns the cached reference (stable until the next flush).
+   */
+  getSnapshot(): ConversationSnapshot {
+    this.notifier.ensureFresh()
+    return this.snapshotCache
+  }
+
+  // ---- Manager-only entry points (@internal; never called by the UI) ----
+
+  /**
+   * Mux frame arrival (the dispatch switch).
+   * @param rpcId - the frame envelope id (the respond backfill key for requested frames).
+   * @param frame - the routed frame.
+   */
+  handleMuxEnvelope(rpcId: RpcId, frame: MuxFrame): void {
+    switch (frame.type) {
+      case 'session/event': {
+        this.acceptLiveEvent(frame.event, frame.view)
+        return
+      }
+      case 'session/subscribed': {
+        this.subscribedLastSeq = frame.lastSeq
+        return // pure baseline bookkeeping, no visible change
+      }
+      case 'approval/requested': {
+        this.pending.set(`a:${rpcId}`, {
+          kind: 'approval', rpcId, approvalId: frame.approvalId, toolName: frame.toolName,
+          ...(frame.callId !== undefined ? { callId: frame.callId } : {}),
+          ...(frame.reason !== undefined ? { reason: frame.reason } : {}),
+        })
+        this.pendingRev++
+        this.notifier.markDirty()
+        return
+      }
+      case 'approval/resolved': {
+        for (const [key, item] of this.pending) {
+          if (item.kind === 'approval' && item.approvalId === frame.approvalId) {
+            this.pending.delete(key)
+            this.pendingRev++
+          }
+        }
+        this.notifier.markDirty()
+        return
+      }
+      case 'question/requested': {
+        this.pending.set(`q:${rpcId}`, { kind: 'question', rpcId, questions: frame.questions })
+        this.pendingRev++
+        this.notifier.markDirty()
+        return
+      }
+      case 'question/resolved': {
+        if (this.pending.delete(`q:${frame.questionRpcId}`)) this.pendingRev++
+        this.notifier.markDirty()
+        return
+      }
+      default:
+        return // stream/error never reaches Session (Controller converges it); unknown frames ignored (documented default)
+    }
+  }
+
+  /**
+   * Running-bit relay from the host stream (list entry and snapshot stay consistent).
+   * @param running - the new running state.
+   */
+  handleRunning(running: boolean): void {
+    if (this.running === running) return
+    this.running = running
+    this.notifier.markDirty()
+  }
+
+  /** host/session-removed relay: flag the snapshot (instance survives — resident-instance rule). */
+  handleRemoved(): void {
+    this.removed = true
+    this.notifier.markDirty()
+  }
+
+  /**
+   * host/agent-error relay: the only outlet for live failures with no turn position.
+   * @param message - the stringified error.
+   */
+  handleAgentError(message: string): void {
+    this.lastAgentError = message
+    this.notifier.markDirty()
+  }
+
+  /** Instance-eviction hook, reserved no-op (design §F.6): resident instances are never destroyed
+   *  in v1; an eviction policy lands here (unsubscribe, drop buffers) without touching call sites. */
+  dispose(): void {}
+
+  // ---- 私有 ----
+
+  /** @param generation - openGeneration at launch; every await re-checks it and a stale pass
+   *  drops all writes (resync superseded this open — its outcome belongs to a dead connection). */
+  private async doOpen(generation: number): Promise<void> {
+    this.openState = 'loading'
+    this.openError = null
+    this.notifier.markDirty()
+    try {
+      let { result } = await this.api.sessions.history({ sessionId: this.sessionId, maxMessages: PAGE_MESSAGES })
+      if (generation !== this.openGeneration) return
+      if (!result.ok) {
+        this.openState = 'error'
+        this.openError = result.error
+        return
+      }
+      this.installWindow(result.value.events, result.value.hasMore)
+      // Gap detection (§D.3-4): baseline past the window tail and liveBuffer did not cover it -> pull the tail page once more.
+      const tailSeq = this.windowTailSeq()
+      if (this.subscribedLastSeq !== null && tailSeq !== null && this.subscribedLastSeq > tailSeq) {
+        result = (await this.api.sessions.history({ sessionId: this.sessionId, maxMessages: PAGE_MESSAGES })).result
+        if (generation !== this.openGeneration) return
+        if (result.ok) this.installWindow(result.value.events, result.value.hasMore)
+      }
+      this.openState = 'open'
+    } catch (error) {
+      if (generation !== this.openGeneration) return
+      this.openState = 'error'
+      const folded = transportError<never>(error)
+      /* v8 ignore next -- the `? null` arm is unreachable: transportError always returns ok:false. */
+      this.openError = folded.ok ? null : folded.error
+    } finally {
+      if (generation === this.openGeneration) this.notifier.markDirty()
+    }
+  }
+
+  /** Install the history window + stitch the liveBuffer (seq is the sole dedup key).
+   *  Stitching MUST NOT route through acceptLiveEvent: openState is still 'loading' here
+   *  (doOpen flips it after install), so recursing would push every buffered event straight
+   *  back into liveBuffer where nothing ever drains it — a silent drop loop (audit S1). */
+  private installWindow(entries: HistoryEntry[], hasMore: boolean): void {
+    this.events = entries.map(e => e.event)
+    this.views = entries.map(e => e.view)
+    this.baseSeq = this.events[0]?.seq ?? 0
+    this.hasMore = hasMore
+    this.foldAdapter.reset(this.events, this.baseSeq, this.views)
+    this.rebuildDerivedFromWindow()
+    const buffered = this.liveBuffer
+    this.liveBuffer = []
+    for (const item of buffered) this.appendLive(item.event, item.view)
+    this.notifier.markDirty()
+  }
+
+  /** Seq-guarded append shared by stitching and the open-state live path. */
+  private appendLive(event: SessionEvent, view?: ToolEventView): void {
+    const tailSeq = this.windowTailSeq()
+    if (tailSeq !== null && event.seq <= tailSeq) return // replay overlap, drop
+    this.events.push(event)
+    this.views.push(view)
+    this.foldAdapter.append(event, view)
+    this.applyEventSideEffects(event, view)
+  }
+
+  /** Land a live session/event (open/repair in flight -> buffer; overlapping seq -> drop;
+   *  a seq gap -> buffer + tail-page repull instead of appending a hole (audit S3: a gap is an
+   *  expected reconnect-window artifact, repaired by refetch — never fed to the fold to trip
+   *  its continuity assertion into the degraded view). */
+  private acceptLiveEvent(event: SessionEvent, view?: ToolEventView): void {
+    if (this.openState === 'loading' || this.stitching) {
+      this.liveBuffer.push({ event, view })
+      return
+    }
+    if (this.openState !== 'open') return // cold/error: no window upkeep (history fully backfills on open)
+    const tailSeq = this.windowTailSeq()
+    if (tailSeq !== null && event.seq > tailSeq + 1) {
+      this.liveBuffer.push({ event, view })
+      void this.repairGap()
+      return
+    }
+    this.appendLive(event, view)
+    this.notifier.markDirty()
+  }
+
+  /** Resync-lite (audit S3): repull the tail page and stitch the liveBuffer through the shared
+   *  installWindow path. No openState transition — the UI keeps the current window (no loading
+   *  flash); events arriving meanwhile detour to liveBuffer via the stitching flag. */
+  private async repairGap(): Promise<void> {
+    /* v8 ignore next -- re-entry guard: acceptLiveEvent already detours to liveBuffer while stitching, so no second call reaches here. */
+    if (this.stitching) return
+    this.stitching = true
+    const generation = this.openGeneration
+    try {
+      const { result } = await this.api.sessions.history({ sessionId: this.sessionId, maxMessages: PAGE_MESSAGES })
+      // Failure or superseded by a full resync: drop — the resync path rebuilds and clears the buffer itself.
+      if (result.ok && generation === this.openGeneration && this.openState === 'open') {
+        this.installWindow(result.value.events, result.value.hasMore)
+      }
+    } catch (error) {
+      console.error('[web-runtime] gap repair failed:', error)
+    } finally {
+      this.stitching = false
+    }
+  }
+
+  /** Per-event side effects (right column of the §A.9 dispatch table):
+   *  chunk accumulation / partial clear on finalize / openCalls add-remove. */
+  private applyEventSideEffects(event: SessionEvent, view?: ToolEventView): void {
+    switch (event.type) {
+      case 'assistant/chunk': {
+        const { turn, step, chunk } = event.data
+        if (this.partial === null || this.partial.turn !== turn || this.partial.step !== step) {
+          this.partial = new PartialAccumulator(turn, step)
+        }
+        this.partial.push(chunk)
+        return
+      }
+      case 'assistant/message': {
+        if (this.partial !== null && this.partial.turn === event.data.turn && this.partial.step === event.data.step) {
+          this.partial = null // finalize swaps in place (same notification batch, no flicker)
+        }
+        return
+      }
+      case 'tool/call': {
+        this.openCalls.set(String(event.data.callId), {
+          callId: String(event.data.callId), name: event.data.name, argsRaw: event.data.arguments,
+          turn: event.data.turn, step: event.data.step,
+          callView: view?.for === 'call' ? view.view : null,
+        })
+        this.callsRev++
+        return
+      }
+      case 'tool/result': {
+        if (this.openCalls.delete(String(event.data.callId))) this.callsRev++
+        return
+      }
+      case 'turn/end': {
+        // Aborted turns never finalize. The accumulated partial is VALUE, not residue: freeze it
+        // into an interrupted terminal node (pulse stops, text survives) instead of deleting it.
+        // Shared by live and window-replay paths, so a refresh reconstructs the same frozen node
+        // from the logged chunks. Content-free partials are dropped outright.
+        if (this.partial !== null && this.partial.turn === event.data.turn) {
+          const { blocks } = this.partial.toPartial()
+          const visible = blocks.some(b => (b.kind === 'text' || b.kind === 'reasoning' ? b.text !== '' : true))
+          if (visible) {
+            // Fractional seq: strictly after every event of this turn (all < turn/end seq), before the next turn.
+            this.frozenNodes.push({
+              kind: 'assistant', seq: event.seq - 0.9, turn: this.partial.turn, step: this.partial.step,
+              blocks, interrupted: true,
+            })
+            this.frozenRev++
+          }
+          this.partial = null
+        }
+        let callOffset = 0
+        for (const [callId, call] of this.openCalls) {
+          if (call.turn !== event.data.turn) continue
+          this.openCalls.delete(callId)
+          this.callsRev++
+          // The spinner card becomes an interrupted terminal card (never vanishes mid-flow).
+          this.frozenNodes.push({
+            kind: 'tool-result', seq: event.seq - 0.8 + callOffset++ * 0.01, callId,
+            call: { name: call.name, argsRaw: call.argsRaw },
+            content: [], isError: true, error: { name: 'Interrupted', code: 'interrupted' },
+            callView: call.callView, resultView: null,
+          })
+          this.frozenRev++
+        }
+        return
+      }
+      default:
+        return
+    }
+  }
+
+  /** Re-derive state (partial/openCalls/frozenNodes) from raw window events after a rebuild — keeps
+   *  paging/stitching consistent, and makes the live freeze and the history replay converge on the
+   *  same interrupted nodes (chunks are logged, so the replayed sweep re-freezes identical text). */
+  private rebuildDerivedFromWindow(): void {
+    this.partial = null
+    this.openCalls.clear()
+    this.callsRev++
+    this.frozenNodes = []
+    this.frozenRev++
+    for (let i = 0; i < this.events.length; i++) {
+      const event = this.events[i]
+      /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */
+      if (event !== undefined) this.applyEventSideEffects(event, this.views[i])
+    }
+  }
+
+  private windowTailSeq(): number | null {
+    const tail = this.events[this.events.length - 1]
+    return tail === undefined ? null : tail.seq
+  }
+
+  private buildSnapshot(): ConversationSnapshot {
+    const { nodes: folded, degraded } = this.foldAdapter.nodes()
+    // Frozen interrupted nodes ride fractional seqs: a stable merge keeps them in flow order.
+    // The merged array is cached on (folded reference, frozenRev) so an unchanged flow keeps its
+    // reference across snapshot swaps (§A.9.4).
+    let nodes: readonly ConversationNode[]
+    if (this.nodesCache !== null && this.nodesCache.folded === folded && this.nodesCache.frozenRev === this.frozenRev) {
+      nodes = this.nodesCache.value
+    } else {
+      nodes = this.frozenNodes.length === 0
+        ? folded
+        : [...folded, ...this.frozenNodes].sort((a, b) => a.seq - b.seq)
+      this.nodesCache = { folded, frozenRev: this.frozenRev, value: nodes }
+    }
+    if (this.callsCache === null || this.callsCache.rev !== this.callsRev) {
+      this.callsCache = { rev: this.callsRev, value: [...this.openCalls.values()] }
+    }
+    if (this.pendingCache === null || this.pendingCache.rev !== this.pendingRev) {
+      this.pendingCache = { rev: this.pendingRev, value: [...this.pending.values()] }
+    }
+    return {
+      sessionId: this.sessionId,
+      nodes,
+      foldDegraded: degraded,
+      partial: this.partial?.toPartial() ?? null,
+      runningCalls: this.callsCache.value,
+      pending: this.pendingCache.value,
+      running: this.running,
+      removed: this.removed,
+      openState: this.openState,
+      openError: this.openError,
+      hasMore: this.hasMore,
+      loadingOlder: this.loadingOlder,
+      promptError: this.promptError,
+      lastAgentError: this.lastAgentError,
+    }
+  }
+}
diff --git a/packages/client/runtime/src/client/slots.ts b/packages/client/runtime/src/client/slots.ts
new file mode 100644
index 0000000000..5b58670bd4
--- /dev/null
+++ b/packages/client/runtime/src/client/slots.ts
@@ -0,0 +1,107 @@
+/**
+ * SlotsService: cordis Service wrapper over the pure SlotCore (ui-slots).
+ * Every mutation re-emits as the 'slots/changed' cordis event; define/register
+ * run through the caller's ctx.effect so a plugin's registrations are
+ * collected when its fiber unloads (cordis-native cascade).
+ */
+/* eslint-disable @typescript-eslint/no-redundant-type-constituents --
+ * `keyof SlotMap & string` is the declare-merge key pattern: SlotMap is empty
+ * in this compilation unit (intersection reads `never`) but consumers merge
+ * keys in; the rule fires on the empty-map view, not on real redundancy. */
+import { Service } from 'cordis'
+import type { Context } from 'cordis'
+import { SlotCore } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ComposedProps, RegisterArgs, SlotComponent, SlotEntry, SlotEntryDef, SlotMap, SlotSpec } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ClientContext } from './index.ts'
+
+/** cordis Service wrapper over the pure SlotCore; mutations re-emit as 'slots/changed'. */
+export class SlotsService extends Service {
+  private readonly _core = new SlotCore()
+
+  /**
+   * @param ctx - owning root context.
+   */
+  constructor(ctx: Context) {
+    super(ctx, 'slots')
+    this._core.onMutate((key) => { ctx.emit('slots/changed', key) })
+  }
+
+  /**
+   * Record a slot spec (delegates to SlotCore.define; disposal follows the caller's fiber).
+   * @param key - SlotMap key.
+   * @param spec - kind/scope spec.
+   * @returns disposer.
+   */
+  define<K extends keyof SlotMap & string>(key: K, spec: SlotSpec<SlotMap[K]>): () => void {
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises -- synchronous cleanup; direct return preserves disposer identity
+    return this.ctx.effect(() => this._core.define(key, spec), 'slots.define()')
+  }
+
+  /**
+   * Contribute a component (delegates to SlotCore.register; disposal follows the caller's fiber).
+   * @param key - SlotMap key.
+   * @param component - contributed component.
+   * @param args - kind-shaped options (mandatory for keyed/list kinds); the
+   * inject factory's binding is pinned to ClientContext.
+   * @returns disposer.
+   */
+  register<K extends keyof SlotMap & string, I extends object = Record<string, unknown>>(
+    // Client-context registrations have exactly one ctx shape: pin Ctx to
+    // ClientContext so inject factories dot services without a cast.
+    key: K, component: SlotComponent<ComposedProps<K, NoInfer<I>>>,
+    ...args: RegisterArgs<SlotMap[K], I, ClientContext>): () => void {
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises -- synchronous cleanup; direct return preserves disposer identity
+    return this.ctx.effect(() => this._core.register<K, I, ClientContext>(key, component, ...args), 'slots.register()')
+  }
+
+  /**
+   * Snapshot entries for a key.
+   * @param key - SlotMap key.
+   * @returns registered entries (stable reference between mutations).
+   */
+  entries<K extends keyof SlotMap & string>(key: K): readonly SlotEntry<SlotMap[K]>[] {
+    return this._core.entries(key)
+  }
+
+  /**
+   * Look up a defined spec.
+   * @param key - SlotMap key.
+   * @returns spec or undefined.
+   */
+  spec<K extends keyof SlotMap & string>(key: K): SlotSpec<SlotMap[K]> | undefined {
+    return this._core.spec(key)
+  }
+
+  /**
+   * Dynamic-key escape hatch for spec lookup (renderer-side string keys).
+   * @param key - candidate slot key.
+   * @returns wide-typed spec or undefined.
+   */
+  specDynamic(key: string): SlotSpec<SlotEntryDef> | undefined {
+    return this._core.specDynamic(key)
+  }
+
+  /**
+   * Subscribe to a key's registration changes (microtask-batched).
+   * @param key - SlotMap key.
+   * @param fn - change callback.
+   * @returns unsubscribe.
+   */
+  subscribe(key: keyof SlotMap & string, fn: () => void): () => void {
+    return this._core.subscribe(key, fn)
+  }
+
+  /**
+   * Version counter for uSES pairing.
+   * @param key - SlotMap key.
+   * @returns current version.
+   */
+  getVersion(key: keyof SlotMap & string): number {
+    return this._core.getVersion(key)
+  }
+
+  /** The wrapped pure core (web-react's scopedSlots outlet reads through this). */
+  get core(): SlotCore {
+    return this._core
+  }
+}
diff --git a/packages/client/runtime/src/index.ts b/packages/client/runtime/src/index.ts
new file mode 100644
index 0000000000..b0d0f0a7c8
--- /dev/null
+++ b/packages/client/runtime/src/index.ts
@@ -0,0 +1,11 @@
+/**
+ * Runtime plugin, node half. The implementation lives entirely in the client
+ * half (src/client/ — SlotsService, SessionsService + object layer, and the
+ * shell-held ClientLoader under ./loader); consumers import the /client or
+ * /loader subpaths. The empty apply exists so the plugin appears in the host
+ * Loader (lifecycle governance + dshClient discovery). Contract:
+ * api-contracts v3 section 4.
+ */
+
+/** Host plugin body — no host-side behavior for the runtime plugin. */
+export function apply(_ctx: unknown): void {}
diff --git a/packages/client/runtime/src/invariant.ts b/packages/client/runtime/src/invariant.ts
new file mode 100644
index 0000000000..8c0ac292ab
--- /dev/null
+++ b/packages/client/runtime/src/invariant.ts
@@ -0,0 +1,52 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-runtime`.
+ * @module @deepseek-ai/dsh-client-runtime/invariant
+ */
+
+/* jscpd:ignore-start */
+/* eslint-disable @typescript-eslint/no-redundant-type-constituents --
+ * `keyof SlotMap & string` is the declare-merge key pattern: SlotMap is empty
+ * in this compilation unit (intersection reads `never`) but consumers merge
+ * keys in; the rule fires on the empty-map view, not on real redundancy. */
+import type { Context } from 'cordis'
+import type { SlotMap } from '@deepseek-ai/dsh-client-ui-slots'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-runtime'
+
+/** Cordis companion plugin name. */
+export const name = 'client-runtime-invariant'
+/** Service required before the companion can register. */
+export const inject = ['invariants']
+
+/**
+ * Owned relation: every 'slots/changed'(key) emission must observe the
+ * mutation already applied — SlotCore bumps the key's version synchronously
+ * before the service re-emits, so a zero version at dispatch time means the
+ * event fired without (or ahead of) its mutation.
+ */
+const install: InvariantInstaller = (ctx, fail) => {
+  ctx.on('internal/dispatch', (_mode, eventName, args) => {
+    if (eventName !== 'slots/changed') return
+    const key: unknown = args[0]
+    if (typeof key !== 'string' || key === '') {
+      fail("'slots/changed' dispatched without a slot key argument")
+      return
+    }
+    const slots = ctx.get('slots')
+    // Event payloads carry keys as plain strings; getVersion is statically
+    // keyed, so restore the SlotMap-key type after the runtime string check.
+    if (slots !== undefined && slots.getVersion(key as keyof SlotMap & string) === 0) {
+      fail(`'slots/changed' fired for "${key}" before any mutation bumped its version — emission must follow the applied mutation`)
+    }
+  }, { global: true })
+}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/client/runtime/tests/client-loader-bundle.e2e.ts b/packages/client/runtime/tests/client-loader-bundle.e2e.ts
new file mode 100644
index 0000000000..ebb0f143b9
--- /dev/null
+++ b/packages/client/runtime/tests/client-loader-bundle.e2e.ts
@@ -0,0 +1,77 @@
+/**
+ * Real-bundle smoke: the actual tsdown client bundle of ui-layout runs
+ * through the loader chain (execute → handoff → factory(require) → apply →
+ * export re-registration). Skips when the bundle is not built (dist/ is a
+ * build product; `pnpm --filter @deepseek-ai/dsh-client-ui-layout build`).
+ */
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { Context } from 'cordis'
+import { afterEach, describe, expect, it } from 'vitest'
+import * as uiSlots from '@deepseek-ai/dsh-client-ui-slots'
+import * as webReact from '@deepseek-ai/dsh-client-web-react'
+import { createClientLoader } from '../src/client/loader/index.ts'
+import type { ClientPluginHandoff } from '../src/client/loader/index.ts'
+import { SessionsService } from '../src/client/sessions/service.ts'
+import { SlotsService } from '../src/client/slots.ts'
+import { FakeApiClient } from './fake-api.ts'
+
+const LAYOUT_ID = '@deepseek-ai/dsh-client-ui-layout'
+
+type Win = { DSHClientProxy?: { loadPlugin(h: ClientPluginHandoff): void }; window?: unknown }
+
+afterEach(() => {
+  delete (globalThis as Win).DSHClientProxy
+  delete (globalThis as Win).window
+})
+
+function readLayoutBundle(): string | undefined {
+  try {
+    const require = createRequire(import.meta.url)
+    return readFileSync(require.resolve(`${LAYOUT_ID}/client`), 'utf8')
+  } catch {
+    return undefined
+  }
+}
+
+describe('real tsdown bundle through the loader', () => {
+  const code = readLayoutBundle()
+
+  it.skipIf(code === undefined)('loads ui-layout lib/client.js: handoff, DI require, apply, export surface', async () => {
+    // The bundle banner addresses window.DSHClientProxy; node has no window —
+    // alias it to globalThis so the loader-installed proxy is reachable.
+    ;(globalThis as Win).window = globalThis
+    const ctx = new Context()
+    // The layout apply consumes the slots + sessions services; the real chain
+    // loads the runtime bundle first — stand both up directly here.
+    ctx.plugin(SlotsService)
+    await ctx.fiber.await()
+    new SessionsService(ctx, new FakeApiClient())
+    const loader = createClientLoader({
+      ctx,
+      // The real bundle externals resolved from the seeded table. React is a
+      // type-only import in the layout bundle today, but jsx-runtime is real.
+      modules: {
+        'react': await import('react'),
+        'react/jsx-runtime': await import('react/jsx-runtime'),
+        '@deepseek-ai/dsh-client-ui-slots': uiSlots,
+        '@deepseek-ai/dsh-client-web-react': webReact,
+      },
+      boot: { plugins: [{ id: LAYOUT_ID, url: `/plugins/${LAYOUT_ID}/client.js`, inject: [] }] },
+      fetchBundle: () => Promise.resolve(code as string),
+      // node has no DOM: evaluate the bundle body directly (same synchronous
+      // handoff contract as the <script> path).
+      executeBundle: (bundleCode) => {
+        // Node has no <script>: Function-evaluating the built bundle IS the
+        // system under test (same synchronous handoff as the browser path).
+        // eslint-disable-next-line @typescript-eslint/no-implied-eval, @typescript-eslint/no-unsafe-call
+        new Function(bundleCode)()
+      },
+    })
+    loader.start()
+    await loader.settled()
+    expect(loader.status.getSnapshot()[LAYOUT_ID]).toBe('active')
+    const surface = loader.requireModule(LAYOUT_ID) as Record<string, unknown>
+    expect(typeof surface.apply).toBe('function')
+  })
+})
diff --git a/packages/client/runtime/tests/client-loader.spec.ts b/packages/client/runtime/tests/client-loader.spec.ts
new file mode 100644
index 0000000000..b94d69f8bf
--- /dev/null
+++ b/packages/client/runtime/tests/client-loader.spec.ts
@@ -0,0 +1,192 @@
+/**
+ * ClientLoader: handoff protocol (single slot, id reconciliation), DI require
+ * with export-surface re-registration, immediately-group barrier (parallel
+ * fetch / topology execution / full-group barrier), status store, settled,
+ * failure modes (missing handoff, unknown dep, cycle, unload stub).
+ */
+import { Context } from 'cordis'
+import { afterEach, describe, expect, it } from 'vitest'
+import { createClientLoader } from '../src/client/loader/index.ts'
+import type { BootPluginEntry, ClientPluginHandoff } from '../src/client/loader/index.ts'
+
+type Win = { DSHClientProxy?: { loadPlugin(h: ClientPluginHandoff): void }; __DSH_BOOT__?: { plugins: BootPluginEntry[] } }
+const win = globalThis as Win
+
+afterEach(() => {
+  delete win.DSHClientProxy
+  delete win.__DSH_BOOT__
+})
+
+interface FakeBundle {
+  handoff: ClientPluginHandoff | null | ((require: (spec: string) => unknown) => Record<string, unknown>)
+}
+
+interface Bench {
+  loader: ReturnType<typeof createClientLoader>
+  fetched: string[]
+  executed: string[]
+  fetchGate: Map<string, () => void>
+}
+
+/** Build a loader over scripted fake bundles keyed by url; fetches resolve when released (or immediately). */
+function bench(
+  plugins: BootPluginEntry[],
+  bundles: Record<string, FakeBundle>,
+  opts: { modules?: Record<string, unknown>; gated?: string[] } = {},
+): Bench {
+  const ctx = new Context()
+  const fetched: string[] = []
+  const executed: string[] = []
+  const fetchGate = new Map<string, () => void>()
+  const loader = createClientLoader({
+    ctx,
+    modules: opts.modules ?? { react: { marker: 'react' } },
+    boot: { plugins },
+    fetchBundle: (url) => {
+      fetched.push(url)
+      if (opts.gated?.includes(url) === true) {
+        return new Promise<string>((resolve) => { fetchGate.set(url, () => { resolve(url) }) })
+      }
+      return Promise.resolve(url)
+    },
+    executeBundle: (code) => {
+      executed.push(code)
+      const bundle = bundles[code]
+      if (bundle === undefined) throw new Error(`no fake bundle for ${code}`)
+      if (bundle.handoff === null) return // simulates a bundle that never calls loadPlugin
+      if (typeof bundle.handoff === 'function') {
+        win.DSHClientProxy?.loadPlugin({ id: code.replace('/client.js', '').replace('/plugins/', ''), factory: bundle.handoff })
+        return
+      }
+      win.DSHClientProxy?.loadPlugin(bundle.handoff)
+    },
+  })
+  return { loader, fetched, executed, fetchGate }
+}
+
+const entry = (id: string, inject: string[] = [], immediately?: boolean): BootPluginEntry =>
+  ({ id, url: `/plugins/${id}/client.js`, inject, ...(immediately === true ? { immediately: true } : {}) })
+
+const okBundle = (applied?: string[], exports: Record<string, unknown> = {}): FakeBundle => ({
+  handoff: require => ({
+    apply: (pluginCtx: Context) => { void pluginCtx; applied?.push('applied') },
+    require,
+    ...exports,
+  }),
+})
+
+describe('load chain', () => {
+  it('runs fetch→execute→handoff→factory(require)→apply→export re-registration→status active', async () => {
+    const applied: string[] = []
+    const b = bench(
+      [entry('fake-base', [], true), entry('feature', ['fake-base'])],
+      {
+        '/plugins/fake-base/client.js': { handoff: () => ({ apply: () => { applied.push('fake-base') }, helper: 'base-helper' }) },
+        '/plugins/feature/client.js': {
+          handoff: (require) => {
+            // Later loader requires the earlier one's export surface (inject topology guarantee).
+            const fakeBase = ['fake','base'].join('-') // assembled so knip's static require() scan skips the fake id
+            const base = require(fakeBase) as { helper: string }
+            expect(base.helper).toBe('base-helper')
+            expect((require('react') as { marker: string }).marker).toBe('react')
+            return { apply: () => { applied.push('feature') } }
+          },
+        },
+      },
+    )
+    b.loader.start()
+    await b.loader.settled()
+    expect(applied).toEqual(['fake-base', 'feature'])
+    expect(b.loader.status.getSnapshot()).toEqual({ 'fake-base': 'active', feature: 'active' })
+    expect((b.loader.requireModule('fake-base') as { helper: string }).helper).toBe('base-helper')
+    expect(() => b.loader.requireModule('ghost')).toThrow(/not available/)
+  })
+
+  it('fetches the immediately group in parallel and holds the barrier before the rest', async () => {
+    const b = bench(
+      [entry('a', [], true), entry('b', ['a'], true), entry('later')],
+      {
+        '/plugins/a/client.js': okBundle(),
+        '/plugins/b/client.js': okBundle(),
+        '/plugins/later/client.js': okBundle(),
+      },
+      { gated: ['/plugins/a/client.js'] },
+    )
+    b.loader.start()
+    await Promise.resolve()
+    // Both early fetches are in flight before any execution; the late plugin is not fetched yet.
+    expect(b.fetched).toEqual(['/plugins/a/client.js', '/plugins/b/client.js'])
+    expect(b.executed).toEqual([])
+    b.fetchGate.get('/plugins/a/client.js')?.()
+    await b.loader.settled()
+    expect(b.executed).toEqual(['/plugins/a/client.js', '/plugins/b/client.js', '/plugins/later/client.js'])
+  })
+
+  it('orders execution by inject topology within each group', async () => {
+    const b = bench(
+      [entry('z-ui', ['a-base']), entry('a-base')],
+      { '/plugins/a-base/client.js': okBundle(), '/plugins/z-ui/client.js': okBundle() },
+    )
+    b.loader.start()
+    await b.loader.settled()
+    expect(b.executed).toEqual(['/plugins/a-base/client.js', '/plugins/z-ui/client.js'])
+  })
+})
+
+describe('failure modes (fail loud)', () => {
+  it('rejects settled and marks failed when a bundle never calls loadPlugin', async () => {
+    const b = bench([entry('silent')], { '/plugins/silent/client.js': { handoff: null } })
+    b.loader.start()
+    await expect(b.loader.settled()).rejects.toThrow(/without calling DSHClientProxy.loadPlugin/)
+    expect(b.loader.status.getSnapshot().silent).toBe('failed')
+  })
+
+  it('rejects on manifest/handoff id mismatch', async () => {
+    const b = bench([entry('expected')], {
+      '/plugins/expected/client.js': { handoff: { id: 'imposter', factory: () => ({ apply: () => {} }) } },
+    })
+    b.loader.start()
+    await expect(b.loader.settled()).rejects.toThrow(/id mismatch/)
+  })
+
+  it('rejects unknown inject targets, cycles, missing apply, unknown load ids, duplicate manifest ids', async () => {
+    // Sequential benches: each loader owns the window proxy, so release it between them.
+    const fresh = <T>(build: () => T): T => {
+      delete win.DSHClientProxy
+      return build()
+    }
+
+    const missing = fresh(() => bench([entry('x', ['nope'])], { '/plugins/x/client.js': okBundle() }))
+    missing.loader.start()
+    await expect(missing.loader.settled()).rejects.toThrow(/injects unknown plugin "nope"/)
+
+    const cyclic = fresh(() => bench(
+      [entry('p', ['q']), entry('q', ['p'])],
+      { '/plugins/p/client.js': okBundle(), '/plugins/q/client.js': okBundle() },
+    ))
+    cyclic.loader.start()
+    await expect(cyclic.loader.settled()).rejects.toThrow(/inject cycle/)
+
+    const applyless = fresh(() => bench([entry('noap')], { '/plugins/noap/client.js': { handoff: { id: 'noap', factory: () => ({}) } } }))
+    applyless.loader.start()
+    await expect(applyless.loader.settled()).rejects.toThrow(/exports no apply/)
+
+    const b = fresh(() => bench([entry('a')], { '/plugins/a/client.js': okBundle() }))
+    await expect(b.loader.load('ghost')).rejects.toThrow(/unknown plugin "ghost"/)
+
+    expect(() => fresh(() => bench([entry('dup'), entry('dup')], {}))).toThrow(/duplicate manifest id/)
+  })
+
+  it('throws on missing boot manifest, double proxy install, and pre-start settled', () => {
+    expect(() => createClientLoader({ ctx: new Context(), modules: {} })).toThrow(/no boot manifest/)
+    const b = bench([], {})
+    expect(() => b.loader.settled()).toThrow(/settled\(\) before start\(\)/)
+    // First bench installed the proxy; a second loader must refuse.
+    expect(() => createClientLoader({ ctx: new Context(), modules: {}, boot: { plugins: [] } })).toThrow(/already installed/)
+  })
+
+  it('unload is the P-I stub', async () => {
+    const b = bench([], {})
+    await expect(b.loader.unload('x')).rejects.toThrow(/not implemented/)
+  })
+})
diff --git a/packages/client/runtime/tests/conversation.spec.ts b/packages/client/runtime/tests/conversation.spec.ts
new file mode 100644
index 0000000000..7da20bc6f3
--- /dev/null
+++ b/packages/client/runtime/tests/conversation.spec.ts
@@ -0,0 +1,23 @@
+/** Assistant block classifier (moved here with sessions/conversation.ts). */
+
+import { describe, expect, it } from 'vitest'
+import type { ContentBlock } from '@deepseek-ai/dsh-client-connection/client'
+import { toAssistantBlock, toAssistantBlocks } from '../src/client/sessions/conversation.ts'
+
+describe('toAssistantBlock', () => {
+  it('classifies the four block shapes', () => {
+    const blocks: ContentBlock[] = [
+      { type: 'text', text: '正文' },
+      { type: 'reasoning', text: '思考' },
+      { type: 'tool-call', id: 'c1', name: 'echo', arguments: '{}' } as ContentBlock,
+      { type: 'image', data: 'x' } as unknown as ContentBlock,
+    ]
+    expect(toAssistantBlocks(blocks)).toEqual([
+      { kind: 'text', text: '正文' },
+      { kind: 'reasoning', text: '思考' },
+      { kind: 'tool-call', callId: 'c1', name: 'echo', argsRaw: '{}' },
+      { kind: 'other', block: blocks[3] },
+    ])
+    expect(toAssistantBlock(blocks[0] as ContentBlock)).toEqual({ kind: 'text', text: '正文' })
+  })
+})
diff --git a/packages/client/runtime/tests/event-script.ts b/packages/client/runtime/tests/event-script.ts
new file mode 100644
index 0000000000..b567800c9b
--- /dev/null
+++ b/packages/client/runtime/tests/event-script.ts
@@ -0,0 +1,50 @@
+// Minimal SessionEvent builders for orchestration tests (shape mirrors what the
+// host emits; only the fields the object layer reads).
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+
+/** One text content block (local helper). */
+const text = (t: string): ContentBlock[] => [{ type: 'text', text: t }]
+
+const at = (seq: number, e: Record<string, unknown>): SessionEvent =>
+  ({ seq, time: 1_700_000_000_000 + seq, ...e }) as unknown as SessionEvent
+
+export const ev = {
+  turnStart: (seq: number, turn: number): SessionEvent =>
+    at(seq, { type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } }),
+  user: (seq: number, body: string): SessionEvent =>
+    at(seq, { type: 'user/message', surfaceOp: 'append', data: { content: text(body), source: { kind: 'user' } } }),
+  stepStart: (seq: number, turn: number, step = 0): SessionEvent =>
+    at(seq, { type: 'step/start', data: { turn, step } }),
+  chunkStart: (seq: number, turn: number, step = 0, index = 0): SessionEvent =>
+    at(seq, { type: 'assistant/chunk', data: { turn, step, chunk: { type: 'block-start', index, blockType: 'text' } } }),
+  chunkText: (seq: number, turn: number, piece: string, step = 0, index = 0): SessionEvent =>
+    at(seq, { type: 'assistant/chunk', data: { turn, step, chunk: { type: 'text-delta', index, text: piece } } }),
+  assistant: (seq: number, turn: number, body: string, step = 0): SessionEvent =>
+    at(seq, { type: 'assistant/message', surfaceOp: 'append', data: { turn, step, content: text(body), provenance: { provider: 'fake', model: 'fk-1' } } }),
+  toolCall: (seq: number, turn: number, callId: string, name: string, args: string, step = 0): SessionEvent =>
+    at(seq, { type: 'tool/call', data: { turn, step, callId, name, arguments: args } }),
+  toolResult: (seq: number, turn: number, callId: string, body: string, step = 0): SessionEvent =>
+    at(seq, { type: 'tool/result', surfaceOp: 'append', data: { turn, step, callId, content: text(body), isError: false } }),
+  stepEnd: (seq: number, turn: number, step = 0): SessionEvent =>
+    at(seq, { type: 'step/end', data: { turn, step } }),
+  turnEnd: (seq: number, turn: number, reason: 'completed' | 'cancelled' = 'completed'): SessionEvent =>
+    at(seq, { type: 'turn/end', data: { turn, reason: { kind: reason } } }),
+}
+
+/** One complete plain turn (turn/start → user → step → assistant → turn/end), 6 events from startSeq. */
+export function plainTurn(startSeq: number, turn: number, ask: string, answer: string): SessionEvent[] {
+  return [
+    ev.turnStart(startSeq, turn),
+    ev.user(startSeq + 1, ask),
+    ev.stepStart(startSeq + 2, turn),
+    ev.assistant(startSeq + 3, turn, answer),
+    ev.stepEnd(startSeq + 4, turn),
+    ev.turnEnd(startSeq + 5, turn),
+  ]
+}
+
+/** Wrap raw events as view-less history entries (the wire shape history now returns). */
+export function entries(events: readonly SessionEvent[]): { event: SessionEvent }[] {
+  return events.map(event => ({ event }))
+}
diff --git a/packages/client/runtime/tests/fake-api.ts b/packages/client/runtime/tests/fake-api.ts
new file mode 100644
index 0000000000..cf6645391a
--- /dev/null
+++ b/packages/client/runtime/tests/fake-api.ts
@@ -0,0 +1,157 @@
+// Test-local programmable IApiClient fake (NOT the fixture: fixture is a demo
+// data source on a real clock; behavior tests need per-case responses and
+// deferred-controlled timing). Streams are hand pumps: pushMux/pushHost.
+import type {
+  HostFrame, IApiClient, MuxFrame, RpcError, RpcRequest, RpcResponse, SessionId,
+} from '@deepseek-ai/dsh-client-connection/client'
+import { RpcId } from '@deepseek-ai/dsh-client-connection/client'
+
+export interface Deferred<T> {
+  promise: Promise<T>
+  resolve(value: T): void
+  reject(error: unknown): void
+}
+
+/** Test-held settlement: the case decides when an RPC lands (history-pending injections etc.). */
+export function deferred<T>(): Deferred<T> {
+  let resolve!: (value: T) => void
+  let reject!: (error: unknown) => void
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return { promise, resolve, reject }
+}
+
+let nextRpc = 0
+
+export function ok<T>(value: T): RpcResponse<T> {
+  return { rpcId: RpcId(`fake-${nextRpc++}`), result: { ok: true, value } }
+}
+
+export function err<T>(error: RpcError): RpcResponse<T> {
+  return { rpcId: RpcId(`fake-${nextRpc++}`), result: { ok: false, error } }
+}
+
+type StreamItem<F> = { kind: 'frame'; envelope: RpcRequest<F> } | { kind: 'end' } | { kind: 'fail'; error: unknown }
+
+interface StreamConn<F> {
+  feed(item: StreamItem<F>): void
+}
+
+export class FakeApiClient implements IApiClient {
+  /** Chronological call record: [method, payload]. */
+  readonly calls: { method: string; payload: unknown }[] = []
+
+  // Programmable slots (defaults answer OK-empty); reassign per case.
+  onList: (payload: unknown) => Promise<RpcResponse<{ items: never[] }>> = () => Promise.resolve(ok({ items: [] }))
+  onCreate: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-new' as SessionId }))
+  onHistory: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number })
+  => Promise<RpcResponse<{ events: never[]; hasMore: boolean }>> =
+    () => Promise.resolve(ok({ events: [], hasMore: false }))
+
+  onPrompt: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
+  onCancel: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
+  onDescribe: (payload: unknown) => Promise<RpcResponse<{ version: string; cwd: string; attachedSessions: number }>> =
+    () => Promise.resolve(ok({ version: '0-fake', cwd: '/f', attachedSessions: 0 }))
+
+  private readonly muxConns: StreamConn<MuxFrame>[] = []
+  private readonly hostConns: StreamConn<HostFrame>[] = []
+
+  readonly sessions: IApiClient['sessions'] = {
+    list: payload => this.record('session.list', payload, this.onList(payload)),
+    create: payload => this.record('session.create', payload, this.onCreate(payload)),
+    history: payload => this.record('session.history', payload, this.onHistory(payload)),
+    prompt: payload => this.record('session.prompt', payload, this.onPrompt(payload)),
+    cancel: payload => this.record('session.cancel', payload, this.onCancel(payload)),
+  }
+
+  readonly host: IApiClient['host'] = {
+    describe: payload => this.record('host.describe', payload, this.onDescribe(payload)),
+  }
+
+  /** When true, streams never fire onOpen (misbehaving-carrier material for the handshake timeout guard). */
+  suppressStreamOpen = false
+
+  /** When true, onOpen callbacks are parked instead of fired; releaseStreamOpens() fires them.
+   *  Lets a case hold the readiness handshake open (describe done, streams not yet "established"). */
+  holdStreamOpen = false
+  private heldOpens: (() => void)[] = []
+
+  releaseStreamOpens(): void {
+    const held = this.heldOpens
+    this.heldOpens = []
+    for (const fire of held) fire()
+  }
+
+  readonly events: IApiClient['events'] = {
+    mux: (_payload, signal, onOpen) => this.openStream(this.muxConns, signal, onOpen),
+    host: (_payload, signal, onOpen) => this.openStream(this.hostConns, signal, onOpen),
+  }
+
+  respond(): Promise<{ accepted: false; reason: 'not-pending' }> {
+    return Promise.resolve({ accepted: false, reason: 'not-pending' })
+  }
+
+  /** Push one mux frame to every open mux stream (rpcId minted unless pinned by the case). */
+  pushMux(frame: MuxFrame, rpcId?: string): void {
+    for (const conn of [...this.muxConns]) conn.feed({ kind: 'frame', envelope: { rpcId: RpcId(rpcId ?? `push-${nextRpc++}`), payload: frame } })
+  }
+
+  pushHost(frame: HostFrame, rpcId?: string): void {
+    for (const conn of [...this.hostConns]) conn.feed({ kind: 'frame', envelope: { rpcId: RpcId(rpcId ?? `push-${nextRpc++}`), payload: frame } })
+  }
+
+  /** End (clean close) or fail (throw) every open stream — reconnect-path material. */
+  endStreams(): void {
+    for (const conn of [...this.muxConns, ...this.hostConns]) conn.feed({ kind: 'end' })
+  }
+
+  failStreams(error: unknown): void {
+    for (const conn of [...this.muxConns, ...this.hostConns]) conn.feed({ kind: 'fail', error })
+  }
+
+  get openMuxCount(): number {
+    return this.muxConns.length
+  }
+
+  callsOf(method: string): unknown[] {
+    return this.calls.filter(c => c.method === method).map(c => c.payload)
+  }
+
+  private record<T>(method: string, payload: unknown, response: Promise<T>): Promise<T> {
+    this.calls.push({ method, payload })
+    return response
+  }
+
+  private async *openStream<F>(registry: StreamConn<F>[], signal: AbortSignal, onOpen?: () => void): AsyncGenerator<RpcRequest<F>> {
+    const inbox: StreamItem<F>[] = []
+    let wake: (() => void) | null = null
+    const conn: StreamConn<F> = {
+      feed: (item) => {
+        inbox.push(item)
+        wake?.()
+      },
+    }
+    registry.push(conn)
+    if (this.holdStreamOpen && onOpen !== undefined) this.heldOpens.push(onOpen)
+    else if (!this.suppressStreamOpen) onOpen?.()
+    try {
+      while (!signal.aborted) {
+        while (inbox.length > 0) {
+          const item = inbox.shift() as StreamItem<F>
+          if (item.kind === 'end') return
+          if (item.kind === 'fail') throw item.error
+          yield item.envelope
+        }
+        await new Promise<void>((resolve) => {
+          wake = resolve
+          signal.addEventListener('abort', () => { resolve() }, { once: true })
+        })
+        wake = null
+      }
+    } finally {
+      registry.splice(registry.indexOf(conn), 1)
+    }
+  }
+}
diff --git a/packages/client/runtime/tests/fold-adapter.spec.ts b/packages/client/runtime/tests/fold-adapter.spec.ts
new file mode 100644
index 0000000000..3214c44ee9
--- /dev/null
+++ b/packages/client/runtime/tests/fold-adapter.spec.ts
@@ -0,0 +1,145 @@
+/**
+ * FoldAdapter over the real core SurfaceManager: padding sentinels for paged
+ * windows, incremental append with node-cache identity, six-variant
+ * materialization, call-index backfill, and the degraded linear-scan branch.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import { FoldAdapter } from '../src/client/sessions/fold-adapter.ts'
+import { ev, plainTurn } from './event-script.ts'
+
+const at = (seq: number, e: Record<string, unknown>): SessionEvent =>
+  ({ seq, time: 1_700_000_000_000 + seq, ...e }) as unknown as SessionEvent
+
+describe('FoldAdapter', () => {
+  it('folds a baseSeq>0 window through padding sentinels with correct seqs', () => {
+    const adapter = new FoldAdapter()
+    const window = plainTurn(100, 5, '偏移问', '偏移答')
+    adapter.reset(window, 100)
+    const { nodes, degraded } = adapter.nodes()
+    expect(degraded).toBe(false)
+    expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 101], ['assistant', 103]])
+  })
+
+  it('appends incrementally keeping old node references (cache identity)', () => {
+    const adapter = new FoldAdapter()
+    adapter.reset(plainTurn(0, 0, 'a', 'b'), 0)
+    const first = adapter.nodes()
+    adapter.append(ev.user(6, '追加'))
+    const second = adapter.nodes()
+    expect(second.nodes).toHaveLength(3)
+    expect(second.nodes[0]).toBe(first.nodes[0])
+    expect(second.nodes[1]).toBe(first.nodes[1])
+    expect(second.nodes).not.toBe(first.nodes) // array itself fresh per call
+  })
+
+  it('materializes all six node variants with field mapping', () => {
+    const adapter = new FoldAdapter()
+    const events = [
+      ev.user(0, '用户'),
+      ev.assistant(1, 0, '助手'),
+      at(2, { type: 'steering/message', surfaceOp: 'append', data: { turn: 0, content: [{ type: 'text', text: '插话' }], source: { kind: 'user' } } }),
+      at(3, { type: 'context/message', surfaceOp: 'append', data: { content: [{ type: 'text', text: '上下文' }], source: { kind: 'plugin', plugin: 'p' } } }),
+      ev.toolCall(4, 0, 'c1', 'echo', '{"x":1}'),
+      ev.toolResult(5, 0, 'c1', '结果'),
+    ]
+    adapter.reset(events, 0)
+    const { nodes } = adapter.nodes()
+    const kinds = nodes.map(n => n.kind)
+    expect(kinds).toContain('user')
+    expect(kinds).toContain('assistant')
+    expect(kinds).toContain('steering')
+    expect(kinds).toContain('context')
+    const result = nodes.find(n => n.kind === 'tool-result')
+    expect(result).toMatchObject({ callId: 'c1', call: { name: 'echo', argsRaw: '{"x":1}' }, isError: false })
+  })
+
+  it('returns call:null for a tool-result whose call fell outside the window', () => {
+    const adapter = new FoldAdapter()
+    adapter.reset([ev.toolResult(50, 3, 'outside-call', '孤儿结果')], 50)
+    const { nodes } = adapter.nodes()
+    expect(nodes[0]).toMatchObject({ kind: 'tool-result', callId: 'outside-call', call: null })
+  })
+
+  it('materializes surface-eligible types it does not know as unknown nodes', () => {
+    const adapter = new FoldAdapter()
+    adapter.reset([at(0, { type: 'notice/message', surfaceOp: 'append', data: { note: 1 } })], 0)
+    const { nodes } = adapter.nodes()
+    // Either the fold surfaces it (unknown node) or skips it as non-eligible — both are valid
+    // shapes; what matters is no throw and no misclassification into a known kind.
+    for (const node of nodes) expect(node.kind).toBe('unknown')
+  })
+
+  it('degrades to the lenient linear scan when the fold throws, and stays degraded', () => {
+    const adapter = new FoldAdapter()
+    // An invalid surfaceOp on a surface-eligible event deterministically throws in the core fold.
+    const window = [
+      ev.user(10, '正常'),
+      at(11, { type: 'assistant/message', surfaceOp: 'bogus-op', data: { turn: 0, step: 0, content: [{ type: 'text', text: '坏 op' }], provenance: { provider: 'x', model: 'y' } } }),
+    ]
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    try {
+      adapter.reset(window, 10)
+      const first = adapter.nodes()
+      expect(first.degraded).toBe(true)
+      expect(errorSpy).toHaveBeenCalled()
+      expect(first.nodes.map(n => n.seq)).toEqual([10, 11]) // linear scan: append order, bad op ignored
+      adapter.append(ev.user(12, '降级后追加')) // bump rev so the cached result is not reused
+      const second = adapter.nodes()
+      expect(second.degraded).toBe(true) // sticky: no re-throw loop, straight to the linear scan
+      expect(second.nodes[0]).toBe(first.nodes[0]) // cache still serves node identity
+      expect(second.nodes.map(n => n.seq)).toEqual([10, 11, 12])
+    } finally {
+      errorSpy.mockRestore()
+    }
+  })
+
+  it('materializes a tool-result error field when present', () => {
+    const adapter = new FoldAdapter()
+    adapter.reset([
+      at(0, { type: 'tool/result', surfaceOp: 'append', data: { turn: 0, step: 0, callId: 'c1', content: [], isError: true, error: { name: 'Boom', code: 'boom' } } }),
+    ], 0)
+    expect(adapter.nodes().nodes[0]).toMatchObject({ kind: 'tool-result', isError: true, error: { code: 'boom' } })
+  })
+
+  it('exposes the in-window call index for runningCalls material', () => {
+    const adapter = new FoldAdapter()
+    adapter.reset([ev.toolCall(0, 1, 'c9', 'slow', '{}')], 0)
+    expect(adapter.callIndex.get('c9')).toMatchObject({ name: 'slow', turn: 1 })
+    adapter.append(ev.toolCall(1, 1, 'c10', 'fast', '{}'))
+    expect(adapter.callIndex.size).toBe(2)
+  })
+
+  it('attaches wire views: callView into the call index, resultView onto the node by seq', () => {
+    const adapter = new FoldAdapter()
+    const events = [
+      ev.toolCall(0, 1, 'c1', 'bash', '{"cmd":"ls"}'),
+      ev.toolResult(1, 1, 'c1', 'listing'),
+    ]
+    const callView = { for: 'call' as const, view: { card: 'terminal' as const, command: 'ls' } }
+    const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '完成' } }
+    adapter.reset(events, 0, [callView, resultView] as never)
+    expect(adapter.callIndex.get('c1')).toMatchObject({ callView: { card: 'terminal' } })
+    const node = adapter.nodes().nodes.find(n => n.kind === 'tool-result')
+    expect(node).toMatchObject({ callView: { card: 'terminal' }, resultView: { card: 'generic', title: '完成' } })
+  })
+
+  it('attaches views on the live append path and defaults to null without views', () => {
+    const adapter = new FoldAdapter()
+    adapter.reset(plainTurn(0, 0, 'a', 'b'), 0) // no views argument: legacy-shaped call
+    adapter.append(ev.toolCall(6, 1, 'c2', 'echo', '{}'), { for: 'call', view: { card: 'generic', title: '回声' } } as never)
+    adapter.append(ev.toolResult(7, 1, 'c2', 'ok')) // no view on the result
+    expect(adapter.callIndex.get('c2')).toMatchObject({ callView: { title: '回声' } })
+    const node = adapter.nodes().nodes.find(n => n.kind === 'tool-result')
+    expect(node).toMatchObject({ callView: { title: '回声' }, resultView: null })
+  })
+
+  it('leaves callView null when the paired call fell outside the window (cross-page break)', () => {
+    const adapter = new FoldAdapter()
+    const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '孤儿' } }
+    adapter.reset([ev.toolResult(50, 3, 'outside', '窗外配对')], 50, [resultView] as never)
+    const node = adapter.nodes().nodes[0]
+    expect(node).toMatchObject({ kind: 'tool-result', call: null, callView: null, resultView: { title: '孤儿' } })
+  })
+})
diff --git a/packages/client/runtime/tests/lineage.spec.ts b/packages/client/runtime/tests/lineage.spec.ts
new file mode 100644
index 0000000000..9ef959c4b9
--- /dev/null
+++ b/packages/client/runtime/tests/lineage.spec.ts
@@ -0,0 +1,55 @@
+/**
+ * flattenLineage: root ordering, DFS child expansion, orphan degradation, and
+ * cycle fail-soft (every entry always emitted, no infinite walk).
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionId, SessionSummary } from '@deepseek-ai/dsh-client-connection/client'
+import { flattenLineage } from '../src/client/sessions/lineage.ts'
+
+const s = (id: string, updatedAt: number, parent?: string): SessionSummary => ({
+  sessionId: id as SessionId, updatedAt, running: false,
+  ...(parent !== undefined ? { parentSessionId: parent as SessionId } : {}),
+})
+
+describe('flattenLineage', () => {
+  it('sorts roots by updatedAt desc and expands children DFS with depth, children sorted too', () => {
+    const out = flattenLineage([
+      s('old-root', 10),
+      s('new-root', 30),
+      s('kid-old', 11, 'new-root'),
+      s('kid-new', 12, 'new-root'),
+      s('grandkid', 5, 'kid-new'),
+    ])
+    expect(out.map(e => [e.sessionId, e.depth])).toEqual([
+      ['new-root', 0], ['kid-new', 1], ['grandkid', 2], ['kid-old', 1], ['old-root', 0],
+    ])
+  })
+
+  it('degrades an orphan (absent parent) to root level without dropping it', () => {
+    const out = flattenLineage([s('orphan', 20, 'ghost-parent'), s('root', 10)])
+    expect(out.map(e => [e.sessionId, e.depth])).toEqual([['orphan', 0], ['root', 0]])
+  })
+
+  it('fails soft on a two-node cycle: all entries emitted, warn fired, no hang', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    try {
+      const out = flattenLineage([s('a', 20, 'b'), s('b', 10, 'a'), s('root', 30)])
+      expect(out.map(e => e.sessionId).sort()).toEqual(['a', 'b', 'root'])
+      expect(warnSpy).toHaveBeenCalled()
+    } finally {
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('handles a self-referencing entry as a cycle member', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    try {
+      const out = flattenLineage([s('self', 10, 'self')])
+      expect(out.map(e => e.sessionId)).toEqual(['self'])
+      expect(out[0]?.depth).toBe(0)
+    } finally {
+      warnSpy.mockRestore()
+    }
+  })
+})
diff --git a/packages/client/runtime/tests/manager.spec.ts b/packages/client/runtime/tests/manager.spec.ts
new file mode 100644
index 0000000000..af7bc60fd2
--- /dev/null
+++ b/packages/client/runtime/tests/manager.spec.ts
@@ -0,0 +1,223 @@
+/**
+ * SessionManager orchestration: lazy resident instances, list lifecycle, host
+ * frame routing, and the pending-frame buffer for uninstantiated sessions.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import { SessionManager } from '../src/client/sessions/manager.ts'
+import { FakeApiClient, deferred, err, ok } from './fake-api.ts'
+import { entries, plainTurn } from './event-script.ts'
+
+const S1 = 'fk-m1' as SessionId
+const S2 = 'fk-m2' as SessionId
+
+function summary(sessionId: SessionId, over: Partial<{ updatedAt: number; running: boolean; parentSessionId: SessionId }> = {}) {
+  return { sessionId, updatedAt: 100, running: false, ...over }
+}
+
+describe('instances', () => {
+  it('lazily builds one resident instance per id and syncs the running bit from the list', async () => {
+    const api = new FakeApiClient()
+    api.onList = () => Promise.resolve(ok({ items: [summary(S1, { running: true })] as never[] }))
+    const manager = new SessionManager(api)
+    await manager.refreshList()
+    const session = manager.get(S1)
+    expect(manager.get(S1)).toBe(session) // resident: same instance forever
+    expect(session.getSnapshot().running).toBe(true) // list preceded instantiation
+  })
+
+  it('replays buffered approval frames on instantiation and drops ordinary frames for uninstantiated sessions', () => {
+    const api = new FakeApiClient()
+    const manager = new SessionManager(api)
+    // Uninstantiated: approval buffers, plain session/event drops.
+    manager.handleMuxEnvelope({ rpcId: 'ra' as never, payload: { type: 'approval/requested', sessionId: S1, approvalId: 'ap1' as never, toolName: 'rm' } })
+    manager.handleMuxEnvelope({ rpcId: 're' as never, payload: { type: 'session/event', sessionId: S1, event: plainTurn(0, 0, 'x', 'y')[0] as never } })
+    const session = manager.get(S1)
+    expect(session.getSnapshot().pending).toMatchObject([{ kind: 'approval', approvalId: 'ap1' }])
+    // Buffer cleared: a second instantiation of another id gets nothing.
+    expect(manager.get(S2).getSnapshot().pending).toEqual([])
+  })
+
+  it('caps the pending buffer at 32 keeping the newest, and drops it on session-removed', () => {
+    const api = new FakeApiClient()
+    const manager = new SessionManager(api)
+    // 40 distinct question frames for an uninstantiated session: only the newest 32 survive.
+    for (let i = 0; i < 40; i++) {
+      manager.handleMuxEnvelope({ rpcId: `q${i}` as never, payload: { type: 'question/requested', sessionId: S1, questions: [] } })
+    }
+    const pending = manager.get(S1).getSnapshot().pending
+    expect(pending).toHaveLength(32)
+    expect(pending.map(p => p.rpcId)).toEqual(Array.from({ length: 32 }, (_, i) => `q${i + 8}`)) // oldest 8 dropped
+    // Removed session: buffered frames must not replay on a future instantiation.
+    manager.handleMuxEnvelope({ rpcId: 'qz' as never, payload: { type: 'question/requested', sessionId: S2, questions: [] } })
+    manager.handleHostEnvelope({ rpcId: 'hz' as never, payload: { type: 'host/session-removed', sessionId: S2 } })
+    expect(manager.get(S2).getSnapshot().pending).toEqual([])
+  })
+})
+
+describe('list lifecycle', () => {
+  it('single-flights refreshList and lands items sorted through lineage flattening', async () => {
+    const api = new FakeApiClient()
+    const gate = deferred<Awaited<ReturnType<FakeApiClient['onList']>>>()
+    api.onList = () => gate.promise
+    const manager = new SessionManager(api)
+    const first = manager.refreshList()
+    const second = manager.refreshList()
+    expect(manager.getListSnapshot().state).toBe('loading')
+    gate.resolve(ok({ items: [summary(S1), summary(S2, { updatedAt: 200 })] as never[] }))
+    await Promise.all([first, second])
+    expect(api.callsOf('session.list')).toHaveLength(1)
+    const snapshot = manager.getListSnapshot()
+    expect(snapshot.state).toBe('idle')
+    expect(snapshot.items.map(i => i.sessionId)).toEqual([S2, S1]) // updatedAt desc
+  })
+
+  it('keeps the error in the list snapshot on failure', async () => {
+    const api = new FakeApiClient()
+    api.onList = () => Promise.resolve(err({ code: 'internal', message: 'boom', details: {} }))
+    const manager = new SessionManager(api)
+    await manager.refreshList()
+    expect(manager.getListSnapshot()).toMatchObject({ state: 'error', error: { code: 'internal' } })
+  })
+
+  it('merges create into the list immediately without waiting for a refresh', async () => {
+    const api = new FakeApiClient()
+    api.onCreate = () => Promise.resolve(ok({ sessionId: S2 }))
+    const manager = new SessionManager(api)
+    const result = await manager.create()
+    expect(result).toMatchObject({ ok: true, value: { sessionId: S2 } })
+    expect(manager.getListSnapshot().items.map(i => i.sessionId)).toEqual([S2])
+  })
+})
+
+describe('host frame routing', () => {
+  it('adds/removes/flips sessions from host frames and keeps removed instances resident', async () => {
+    const api = new FakeApiClient()
+    const manager = new SessionManager(api)
+    manager.handleHostEnvelope({ rpcId: 'h1' as never, payload: { type: 'host/session-added', sessionId: S1 } })
+    manager.handleHostEnvelope({ rpcId: 'h2' as never, payload: { type: 'host/session-added', sessionId: S1 } }) // dup: ignored
+    expect(manager.getListSnapshot().items).toHaveLength(1)
+
+    const session = manager.get(S1)
+    manager.handleHostEnvelope({ rpcId: 'h3' as never, payload: { type: 'host/session-status', sessionId: S1, running: true } })
+    expect(session.getSnapshot().running).toBe(true)
+    expect(manager.getListSnapshot().items[0]?.running).toBe(true)
+
+    manager.handleHostEnvelope({ rpcId: 'h4' as never, payload: { type: 'host/agent-error', sessionId: S1, message: '炸了' } })
+    expect(session.getSnapshot().lastAgentError).toBe('炸了')
+
+    manager.handleHostEnvelope({ rpcId: 'h5' as never, payload: { type: 'host/session-removed', sessionId: S1 } })
+    expect(manager.getListSnapshot().items).toHaveLength(0)
+    expect(session.getSnapshot().removed).toBe(true)
+    expect(manager.get(S1)).toBe(session) // resident-instance rule survives removal
+  })
+})
+
+describe('remaining branches', () => {
+  it('refreshList folds a transport throw into the error state', async () => {
+    const api = new FakeApiClient()
+    api.onList = () => Promise.reject(new Error('list wire down'))
+    const manager = new SessionManager(api)
+    await manager.refreshList()
+    expect(manager.getListSnapshot()).toMatchObject({ state: 'error', error: { code: 'internal', message: 'list wire down' } })
+  })
+
+  it('refreshList pushes running bits down to already-instantiated sessions', async () => {
+    const api = new FakeApiClient()
+    const manager = new SessionManager(api)
+    const session = manager.get(S1)
+    api.onList = () => Promise.resolve(ok({ items: [summary(S1, { running: true })] as never[] }))
+    await manager.refreshList()
+    expect(session.getSnapshot().running).toBe(true)
+  })
+
+  it('create passes cwd through, folds transport throws, and skips the merge when already listed', async () => {
+    const api = new FakeApiClient()
+    api.onCreate = () => Promise.resolve(ok({ sessionId: S1 }))
+    const manager = new SessionManager(api)
+    await manager.create('/tmp/w')
+    expect(api.callsOf('session.create')).toEqual([{ cwd: '/tmp/w' }])
+    expect(manager.getListSnapshot().items[0]).toMatchObject({ sessionId: S1, cwd: '/tmp/w' })
+    await manager.create('/tmp/w') // same id returned: no duplicate row
+    expect(manager.getListSnapshot().items).toHaveLength(1)
+    api.onCreate = () => Promise.reject(new Error('create wire down'))
+    expect(await manager.create()).toMatchObject({ ok: false, error: { code: 'internal' } })
+    // Business error passes through untouched.
+    api.onCreate = () => Promise.resolve(err({ code: 'internal', message: 'no', details: {} }))
+    expect(await manager.create()).toMatchObject({ ok: false })
+  })
+
+  it('subscribe notifies on list changes and stops after unsubscribe', async () => {
+    const api = new FakeApiClient()
+    const manager = new SessionManager(api)
+    let notified = 0
+    const unsubscribe = manager.subscribe(() => { notified++ })
+    await manager.refreshList()
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(notified).toBeGreaterThan(0)
+    const seen = notified
+    unsubscribe()
+    manager.handleHostEnvelope({ rpcId: 'h' as never, payload: { type: 'host/session-added', sessionId: S1 } })
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(notified).toBe(seen)
+  })
+
+  it('routes stream/error and unknown frames to the documented drops, and dispatches to instantiated sessions', () => {
+    const api = new FakeApiClient()
+    const manager = new SessionManager(api)
+    manager.handleMuxEnvelope({ rpcId: 'e' as never, payload: { type: 'stream/error', error: { code: 'internal', message: 'x', details: {} } } })
+    manager.handleHostEnvelope({ rpcId: 'e2' as never, payload: { type: 'stream/error', error: { code: 'internal', message: 'x', details: {} } } })
+    manager.handleHostEnvelope({ rpcId: 'e3' as never, payload: { type: 'future/host-frame' } as never })
+    const session = manager.get(S1)
+    manager.handleMuxEnvelope({ rpcId: 'q1' as never, payload: { type: 'question/requested', sessionId: S1, questions: [] } })
+    expect(session.getSnapshot().pending).toMatchObject([{ kind: 'question' }])
+    // status flip for an unknown session only touches summaries (no crash).
+    manager.handleHostEnvelope({ rpcId: 'h9' as never, payload: { type: 'host/session-status', sessionId: S2, running: true } })
+    manager.handleHostEnvelope({ rpcId: 'ha' as never, payload: { type: 'host/agent-error', sessionId: S2, message: '无实例' } })
+  })
+
+  it('keeps list-entry identity for unchanged rows across an unrelated list change', async () => {
+    const api = new FakeApiClient()
+    api.onList = () => Promise.resolve(ok({ items: [summary(S1), summary(S2, { updatedAt: 200 })] as never[] }))
+    const manager = new SessionManager(api)
+    await manager.refreshList()
+    const before = manager.getListSnapshot()
+    manager.handleHostEnvelope({ rpcId: 'h' as never, payload: { type: 'host/session-status', sessionId: S2, running: true } })
+    const after = manager.getListSnapshot()
+    expect(after.items).not.toBe(before.items)
+    const beforeS1 = before.items.find(e => e.sessionId === S1)
+    const afterS1 = after.items.find(e => e.sessionId === S1)
+    expect(afterS1).toBe(beforeS1) // untouched entry keeps identity (entryCache)
+    // Same-order same-entries snapshot reuses the items array.
+    manager.handleHostEnvelope({ rpcId: 'h2' as never, payload: { type: 'host/agent-error', sessionId: S1, message: 'x' } })
+    expect(manager.getListSnapshot().items).toBe(after.items)
+  })
+
+  it('carries parentSessionId from host/session-added into the lineage row', () => {
+    const api = new FakeApiClient()
+    const manager = new SessionManager(api)
+    manager.handleHostEnvelope({ rpcId: 'h1' as never, payload: { type: 'host/session-added', sessionId: S1 } })
+    manager.handleHostEnvelope({ rpcId: 'h2' as never, payload: { type: 'host/session-added', sessionId: S2, parentSessionId: S1 } })
+    const items = manager.getListSnapshot().items
+    expect(items.find(e => e.sessionId === S2)).toMatchObject({ parentSessionId: S1, depth: 1 })
+  })
+})
+
+describe('connected generation', () => {
+  it('refreshes the list and resyncs only opened instances', async () => {
+    const api = new FakeApiClient()
+    api.onHistory = () => Promise.resolve(ok({ events: entries(plainTurn(0, 0, 'a', 'b')) as never[], hasMore: false }))
+    const manager = new SessionManager(api)
+    const openedSession = manager.get(S1)
+    await openedSession.open()
+    manager.get(S2) // instantiated but never opened
+    const historyCallsBefore = api.callsOf('session.history').length
+    manager.handleConnected()
+    await vi.waitFor(() => {
+      expect(api.callsOf('session.list').length).toBe(1)
+      // Only the opened instance repulls history; the cold one stays silent.
+      expect(api.callsOf('session.history').length).toBe(historyCallsBefore + 1)
+    })
+  })
+})
diff --git a/packages/client/runtime/tests/node-half.spec.ts b/packages/client/runtime/tests/node-half.spec.ts
new file mode 100644
index 0000000000..efba1b0445
--- /dev/null
+++ b/packages/client/runtime/tests/node-half.spec.ts
@@ -0,0 +1,10 @@
+/** Node half: the empty host apply (Loader governance + dshClient discovery placeholder). */
+import { describe, expect, it } from 'vitest'
+import { apply } from '../src/index.ts'
+
+describe('node half', () => {
+  it('apply is a no-op host placeholder', () => {
+    apply(undefined)
+    expect(true).toBe(true) // reaching here without throw is the contract
+  })
+})
diff --git a/packages/client/runtime/tests/notifier.spec.ts b/packages/client/runtime/tests/notifier.spec.ts
new file mode 100644
index 0000000000..df467e6aac
--- /dev/null
+++ b/packages/client/runtime/tests/notifier.spec.ts
@@ -0,0 +1,75 @@
+/**
+ * Notifier: microtask batching, rebuild-before-notify ordering, no-listener
+ * laziness, synchronous notifyNow, and unsubscribe.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Notifier } from '../src/client/sessions/notifier.ts'
+
+const microtask = (): Promise<void> => new Promise((resolve) => { queueMicrotask(resolve) })
+
+describe('Notifier', () => {
+  it('collapses N markDirty calls into one flush, rebuilding before notifying', async () => {
+    const order: string[] = []
+    const notifier = new Notifier(() => order.push('rebuild'))
+    notifier.subscribe(() => order.push('notify'))
+    notifier.markDirty()
+    notifier.markDirty()
+    notifier.markDirty()
+    expect(order).toEqual([]) // nothing until the microtask boundary
+    await microtask()
+    expect(order).toEqual(['rebuild', 'notify'])
+  })
+
+  it('skips rebuild with zero listeners and ensureFresh rebuilds lazily exactly once', async () => {
+    let rebuilds = 0
+    const notifier = new Notifier(() => { rebuilds++ })
+    notifier.markDirty()
+    await microtask()
+    expect(rebuilds).toBe(0) // lazy: kept dirty
+    notifier.ensureFresh()
+    expect(rebuilds).toBe(1)
+    notifier.ensureFresh()
+    expect(rebuilds).toBe(1) // clean: no second rebuild
+  })
+
+  it('notifyNow runs listeners synchronously (controlled-input contract)', () => {
+    const order: string[] = []
+    const notifier = new Notifier(() => order.push('rebuild'))
+    notifier.subscribe(() => order.push('notify'))
+    notifier.notifyNow()
+    expect(order).toEqual(['rebuild', 'notify']) // before returning, no microtask needed
+  })
+
+  it('notifyNow with zero listeners stays lazy like markDirty', () => {
+    let rebuilds = 0
+    const notifier = new Notifier(() => { rebuilds++ })
+    notifier.notifyNow()
+    expect(rebuilds).toBe(0)
+    notifier.ensureFresh()
+    expect(rebuilds).toBe(1)
+  })
+
+  it('a scheduled flush after notifyNow already flushed is a no-op', async () => {
+    let rebuilds = 0
+    const notifier = new Notifier(() => { rebuilds++ })
+    notifier.subscribe(() => undefined)
+    notifier.markDirty() // schedules the microtask flush
+    notifier.notifyNow() // flushes synchronously, clears dirty
+    await microtask() // the scheduled flush finds dirty=false
+    expect(rebuilds).toBe(1)
+  })
+
+  it('unsubscribed listeners stop receiving notifications', async () => {
+    let calls = 0
+    const notifier = new Notifier(() => undefined)
+    const unsubscribe = notifier.subscribe(() => { calls++ })
+    notifier.notifyNow()
+    expect(calls).toBe(1)
+    unsubscribe()
+    notifier.markDirty()
+    await microtask()
+    notifier.notifyNow()
+    expect(calls).toBe(1)
+  })
+})
diff --git a/packages/client/runtime/tests/partial.spec.ts b/packages/client/runtime/tests/partial.spec.ts
new file mode 100644
index 0000000000..25681ea4cc
--- /dev/null
+++ b/packages/client/runtime/tests/partial.spec.ts
@@ -0,0 +1,91 @@
+/**
+ * PartialAccumulator: six-variant chunk folding, sparse-index compaction, and
+ * the block/snapshot reference discipline (a delta swaps only that block).
+ */
+
+import { describe, expect, it } from 'vitest'
+import type { StreamChunk } from '@deepseek-ai/dsh-client-connection/client'
+import { PartialAccumulator } from '../src/client/sessions/partial.ts'
+
+const chunk = (c: Record<string, unknown>): StreamChunk => c as unknown as StreamChunk
+
+describe('PartialAccumulator', () => {
+  it('builds empty blocks per block-start type, unknown type falls to other', () => {
+    const acc = new PartialAccumulator(1, 0)
+    acc.push(chunk({ type: 'block-start', index: 0, blockType: 'text' }))
+    acc.push(chunk({ type: 'block-start', index: 1, blockType: 'reasoning' }))
+    acc.push(chunk({ type: 'block-start', index: 2, blockType: 'tool-call' }))
+    acc.push(chunk({ type: 'block-start', index: 3, blockType: 'no-such' }))
+    expect(acc.toPartial().blocks).toEqual([
+      { kind: 'text', text: '' },
+      { kind: 'reasoning', text: '' },
+      { kind: 'tool-call', callId: '', name: '', argsRaw: '' },
+      { kind: 'other', block: null },
+    ])
+  })
+
+  it('accumulates text deltas, starting from empty when prev is missing or another kind', () => {
+    const acc = new PartialAccumulator(1, 0)
+    acc.push(chunk({ type: 'text-delta', index: 0, text: '无 start ' })) // prev missing
+    acc.push(chunk({ type: 'text-delta', index: 0, text: '也累积' }))
+    expect(acc.toPartial().blocks).toEqual([{ kind: 'text', text: '无 start 也累积' }])
+    acc.push(chunk({ type: 'reasoning-delta', index: 0, text: '换型重起' })) // prev is text → restart
+    expect(acc.toPartial().blocks).toEqual([{ kind: 'reasoning', text: '换型重起' }])
+  })
+
+  it('accumulates reasoning deltas on the reasoning lane', () => {
+    const acc = new PartialAccumulator(1, 0)
+    acc.push(chunk({ type: 'block-start', index: 0, blockType: 'reasoning' }))
+    acc.push(chunk({ type: 'reasoning-delta', index: 0, text: '思' }))
+    acc.push(chunk({ type: 'reasoning-delta', index: 0, text: '考' }))
+    expect(acc.toPartial().blocks).toEqual([{ kind: 'reasoning', text: '思考' }])
+  })
+
+  it('folds tool-call deltas: first id pins callId, late name overrides, argsRaw concatenates', () => {
+    const acc = new PartialAccumulator(1, 0)
+    acc.push(chunk({ type: 'tool-call-delta', index: 0, id: 'c1', argumentsDelta: '{"a"' }))
+    acc.push(chunk({ type: 'tool-call-delta', index: 0, id: 'c2-late', name: 'echo', argumentsDelta: ':1}' }))
+    expect(acc.toPartial().blocks).toEqual([
+      { kind: 'tool-call', callId: 'c1', name: 'echo', argsRaw: '{"a":1}' },
+    ])
+  })
+
+  it('replaces the accumulated block wholesale on block-end', () => {
+    const acc = new PartialAccumulator(1, 0)
+    acc.push(chunk({ type: 'text-delta', index: 0, text: '中间态' }))
+    acc.push(chunk({ type: 'block-end', index: 0, block: { type: 'text', text: '定稿全文' } }))
+    expect(acc.toPartial().blocks).toEqual([{ kind: 'text', text: '定稿全文' }])
+  })
+
+  it('returns false (no notification) for usage/finish/unknown variants and keeps blocks', () => {
+    const acc = new PartialAccumulator(1, 0)
+    acc.push(chunk({ type: 'text-delta', index: 0, text: 'x' }))
+    const before = acc.toPartial()
+    expect(acc.push(chunk({ type: 'usage', usage: {} }))).toBe(false)
+    expect(acc.push(chunk({ type: 'finish', reason: 'stop' }))).toBe(false)
+    expect(acc.push(chunk({ type: 'future-variant' }))).toBe(false)
+    expect(acc.toPartial()).toBe(before) // unchanged: same snapshot reference
+  })
+
+  it('compacts sparse indexes into a dense render-order array', () => {
+    const acc = new PartialAccumulator(1, 0)
+    acc.push(chunk({ type: 'block-start', index: 2, blockType: 'text' }))
+    acc.push(chunk({ type: 'text-delta', index: 2, text: '先到的高位' }))
+    acc.push(chunk({ type: 'block-start', index: 0, blockType: 'reasoning' }))
+    const { blocks } = acc.toPartial()
+    expect(blocks).toHaveLength(2) // no undefined holes
+    expect(blocks[0]).toEqual({ kind: 'reasoning', text: '' })
+    expect(blocks[1]).toEqual({ kind: 'text', text: '先到的高位' })
+  })
+
+  it('keeps the snapshot reference stable without changes and swaps it once per mutation', () => {
+    const acc = new PartialAccumulator(3, 1)
+    const first = acc.toPartial()
+    expect(first).toMatchObject({ turn: 3, step: 1, blocks: [] })
+    expect(acc.toPartial()).toBe(first)
+    acc.push(chunk({ type: 'text-delta', index: 0, text: 'a' }))
+    const second = acc.toPartial()
+    expect(second).not.toBe(first)
+    expect(acc.toPartial()).toBe(second)
+  })
+})
diff --git a/packages/client/runtime/tests/session.spec.ts b/packages/client/runtime/tests/session.spec.ts
new file mode 100644
index 0000000000..149f73c1fc
--- /dev/null
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -0,0 +1,625 @@
+/**
+ * Session orchestration: drive the object through contract calls and injected
+ * frames (open → prompt → stream → finalize → cancel → resync) and assert the
+ * ConversationSnapshot it settles into. Reference stability is asserted with
+ * toBe/not.toBe — it is the React.memo/uSES contract, equal-value output is not
+ * enough.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import { Session } from '../src/client/sessions/session.ts'
+import { FakeApiClient, deferred, err, ok } from './fake-api.ts'
+import { entries, ev, plainTurn } from './event-script.ts'
+
+const at = (seq: number, e: Record<string, unknown>): SessionEvent =>
+  ({ seq, time: 1_700_000_000_000 + seq, ...e }) as unknown as SessionEvent
+
+const SID = 'fk-s1' as SessionId
+
+function makeSession(api = new FakeApiClient()): { api: FakeApiClient; session: Session } {
+  return { api, session: new Session(SID, api) }
+}
+
+function histResponse(events: SessionEvent[], hasMore = false) {
+  // history now returns HistoryEntry[] ({event, view?}); these tests are view-less.
+  return Promise.resolve(ok({ events: entries(events) as never[], hasMore }))
+}
+
+describe('open', () => {
+  it('installs the tail page: cold → loading → open with window and nodes in place', async () => {
+    const { api, session } = makeSession()
+    const page = plainTurn(10, 3, '问', '答')
+    api.onHistory = () => histResponse(page, true)
+    expect(session.getSnapshot().openState).toBe('cold')
+    const opening = session.open()
+    expect(session.getSnapshot().openState).toBe('loading')
+    await opening
+    const snapshot = session.getSnapshot()
+    expect(snapshot.openState).toBe('open')
+    expect(snapshot.hasMore).toBe(true)
+    expect(snapshot.nodes.map(n => n.kind)).toEqual(['user', 'assistant'])
+  })
+
+  it('is idempotent: concurrent opens share one history call, reopening when open is a no-op', async () => {
+    const { api, session } = makeSession()
+    await Promise.all([session.open(), session.open()])
+    await session.open()
+    expect(api.callsOf('session.history')).toHaveLength(1)
+  })
+
+  it('lands an error result in openState=error with the RpcError kept', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => Promise.resolve(err({ code: 'session-not-found', message: 'gone', details: { sessionId: SID } }))
+    await session.open()
+    const snapshot = session.getSnapshot()
+    expect(snapshot.openState).toBe('error')
+    expect(snapshot.openError?.code).toBe('session-not-found')
+  })
+
+  it('folds a transport throw into openState=error / internal', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => Promise.reject(new Error('socket died'))
+    await session.open()
+    expect(session.getSnapshot().openState).toBe('error')
+    expect(session.getSnapshot().openError).toMatchObject({ code: 'internal', message: 'socket died' })
+  })
+
+  it('stitches live frames arriving while history is pending, dropping the page overlap', async () => {
+    const { api, session } = makeSession()
+    const gate = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
+    api.onHistory = () => gate.promise
+    const opening = session.open()
+    // Three live frames land mid-open; seq 15 overlaps the page tail (page covers 10..15).
+    const page = plainTurn(10, 0, '早', '安')
+    session.handleMuxEnvelope('r1' as never, { type: 'session/event', sessionId: SID, event: ev.turnStart(15, 1) })
+    session.handleMuxEnvelope('r2' as never, { type: 'session/event', sessionId: SID, event: ev.user(16, '插进来的') })
+    gate.resolve(ok({ events: entries(page) as never[], hasMore: false }))
+    await opening
+    const seqs = session.getSnapshot().nodes.map(n => n.seq)
+    // Overlapping seq-15 frame (== page tail turn/end) was dropped; 16 appended once.
+    expect(seqs).toEqual([11, 13, 16])
+  })
+})
+
+describe('live event path', () => {
+  async function opened(events: SessionEvent[] = plainTurn(0, 0, 'a', 'b')) {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(events)
+    await session.open()
+    return { api, session }
+  }
+
+  it('drops replayed frames at or below the window tail', async () => {
+    const { session } = await opened()
+    const before = session.getSnapshot()
+    session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.user(3, '重放') })
+    await Promise.resolve()
+    expect(session.getSnapshot().nodes).toEqual(before.nodes)
+  })
+
+  it('accumulates chunks into partial, then finalize swaps partial out as the node lands', async () => {
+    const { session } = await opened()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(ev.user(7, '流式问'))
+    feed(ev.chunkStart(8, 1))
+    feed(ev.chunkText(9, 1, '半截'))
+    let snapshot = session.getSnapshot()
+    expect(snapshot.partial).toMatchObject({ turn: 1, blocks: [{ kind: 'text', text: '半截' }] })
+    feed(ev.chunkText(10, 1, '回复'))
+    expect(session.getSnapshot().partial?.blocks).toEqual([{ kind: 'text', text: '半截回复' }])
+    feed(ev.assistant(11, 1, '半截回复'))
+    feed(ev.turnEnd(12, 1))
+    snapshot = session.getSnapshot()
+    expect(snapshot.partial).toBeNull()
+    const last = snapshot.nodes.at(-1)
+    expect(last).toMatchObject({ kind: 'assistant', blocks: [{ kind: 'text', text: '半截回复' }] })
+    expect((last as { interrupted?: true }).interrupted).toBeUndefined()
+  })
+
+  it('freezes an unfinalized partial into an interrupted node on turn/end (cancel path)', async () => {
+    const { session } = await opened()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(ev.user(7, '要被打断的'))
+    feed(ev.chunkStart(8, 1))
+    feed(ev.chunkText(9, 1, '说到一半'))
+    feed(ev.turnEnd(10, 1, 'cancelled')) // no assistant/message ever arrives
+    const snapshot = session.getSnapshot()
+    expect(snapshot.partial).toBeNull()
+    const frozen = snapshot.nodes.at(-1)
+    expect(frozen).toMatchObject({ kind: 'assistant', interrupted: true, blocks: [{ kind: 'text', text: '说到一半' }] })
+    // Ordered inside the flow: after the user message (seq 7), before any later turn.
+    expect((frozen as { seq: number }).seq).toBeGreaterThan(7)
+  })
+
+  it('tracks tool calls in runningCalls and converts orphans to interrupted tool-result cards on turn/end', async () => {
+    const { session } = await opened()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(ev.toolCall(7, 1, 'c1', 'echo', '{"a":1}'))
+    expect(session.getSnapshot().runningCalls).toMatchObject([{ callId: 'c1', name: 'echo' }])
+    feed(ev.toolResult(8, 1, 'c1', 'ECHO'))
+    expect(session.getSnapshot().runningCalls).toEqual([])
+    // Second call never resolves: turn/end freezes it as an error card.
+    feed(ev.toolCall(9, 1, 'c2', 'slow_tool', '{}'))
+    feed(ev.turnEnd(10, 1, 'cancelled'))
+    const snapshot = session.getSnapshot()
+    expect(snapshot.runningCalls).toEqual([])
+    expect(snapshot.nodes.at(-1)).toMatchObject({
+      kind: 'tool-result', callId: 'c2', isError: true, error: { code: 'interrupted' },
+    })
+  })
+
+  it('repairs a seq gap by repulling the tail page instead of appending a hole', async () => {
+    const { api, session } = await opened(plainTurn(0, 0, 'a', 'b')) // tail seq = 5
+    const repaired = [...plainTurn(0, 0, 'a', 'b'), ...plainTurn(6, 1, 'c', 'd')]
+    api.onHistory = () => histResponse(repaired)
+    // seq 9 with tail 5 → gap; the event detours to the buffer and one history refetch fires.
+    session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.assistant(9, 1, 'd') })
+    await vi.waitFor(() => {
+      expect(api.callsOf('session.history').length).toBe(2)
+    })
+    await Promise.resolve()
+    const seqs = session.getSnapshot().nodes.map(n => n.seq)
+    expect(seqs).toEqual([1, 3, 7, 9]) // both turns' user/assistant, no hole, no duplicate 9
+  })
+})
+
+describe('paging', () => {
+  it('prepends an older page and keeps seq continuity', async () => {
+    const older = plainTurn(0, 0, '旧问', '旧答')
+    const newer = plainTurn(6, 1, '新问', '新答')
+    const { api, session } = makeSession()
+    api.onHistory = payload => payload.beforeSeq === undefined
+      ? histResponse(newer, true)
+      : histResponse(older, false)
+    await session.open()
+    await session.loadOlder()
+    const snapshot = session.getSnapshot()
+    expect(api.callsOf('session.history')).toMatchObject([{}, { beforeSeq: 6 }].map(p => ({ sessionId: SID, ...p })))
+    expect(snapshot.hasMore).toBe(false)
+    expect(snapshot.nodes.map(n => n.seq)).toEqual([1, 3, 7, 9])
+  })
+
+  it('drops a discontinuous older page fail-soft (window unchanged, hasMore cleared)', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = payload => payload.beforeSeq === undefined
+      ? histResponse(plainTurn(10, 1, '新', '页'), true)
+      : histResponse(plainTurn(0, 0, '断', '层'), true) // tail seq 5, but baseSeq is 10 → hole
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    try {
+      await session.open()
+      const nodesBefore = session.getSnapshot().nodes
+      await session.loadOlder()
+      const snapshot = session.getSnapshot()
+      expect(snapshot.nodes).toEqual(nodesBefore)
+      expect(snapshot.hasMore).toBe(false)
+    } finally {
+      errorSpy.mockRestore()
+    }
+  })
+
+  it('ignores loadOlder while one is in flight (single request)', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(6, 1, 'x', 'y'), true)
+    await session.open()
+    const gate = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
+    api.onHistory = () => gate.promise
+    const first = session.loadOlder()
+    const second = session.loadOlder()
+    gate.resolve(ok({ events: entries(plainTurn(0, 0, 'a', 'b')) as never[], hasMore: false }))
+    await Promise.all([first, second])
+    expect(api.callsOf('session.history')).toHaveLength(2) // open + one page, not two
+  })
+})
+
+describe('prompt and cancel errors', () => {
+  it('sends content through session.prompt with the mode passed through', async () => {
+    const { api, session } = makeSession()
+    const result = await session.prompt([{ type: 'text', text: '要发的' }], 'queue')
+    expect(result.ok).toBe(true)
+    expect(api.callsOf('session.prompt')).toMatchObject([{ sessionId: SID, mode: 'queue', content: [{ type: 'text', text: '要发的' }] }])
+  })
+
+  it('business failure lands in promptError with op=send', async () => {
+    const { api, session } = makeSession()
+    api.onPrompt = () => Promise.resolve(err({ code: 'agent-busy', message: 'busy', details: { reason: 'x' } }))
+    const result = await session.prompt([{ type: 'text', text: '失败的' }], 'queue')
+    expect(result.ok).toBe(false)
+    expect(session.getSnapshot().promptError).toMatchObject({ op: 'send', error: { code: 'agent-busy' } })
+  })
+
+  it('lands cancel failures in promptError with op=stop', async () => {
+    const { api, session } = makeSession()
+    api.onCancel = () => Promise.reject(new Error('cancel transport down'))
+    const result = await session.cancel()
+    expect(result.ok).toBe(false)
+    expect(session.getSnapshot().promptError).toMatchObject({ op: 'stop', error: { code: 'internal' } })
+  })
+})
+
+describe('pending interactions', () => {
+  it('adds approval/question on requested and removes them on resolved', async () => {
+    const { session } = makeSession()
+    session.handleMuxEnvelope('ra' as never, { type: 'approval/requested', sessionId: SID, approvalId: 'ap1' as never, toolName: 'rm' })
+    session.handleMuxEnvelope('rq' as never, { type: 'question/requested', sessionId: SID, questions: [] })
+    expect(session.getSnapshot().pending.map(p => p.kind).sort()).toEqual(['approval', 'question'])
+    session.handleMuxEnvelope('rx' as never, { type: 'approval/resolved', sessionId: SID, approvalId: 'ap1' as never, outcome: 'approved' as never })
+    session.handleMuxEnvelope('ry' as never, { type: 'question/resolved', sessionId: SID, questionRpcId: 'rq' as never, outcome: 'answered' })
+    expect(session.getSnapshot().pending).toEqual([])
+  })
+})
+
+describe('remaining branches', () => {
+  it('prompt transport throw folds to internal promptError', async () => {
+    const { api, session } = makeSession()
+    api.onPrompt = () => Promise.reject(new Error('prompt wire down'))
+    const result = await session.prompt([{ type: 'text', text: 'x' }], 'queue')
+    expect(result.ok).toBe(false)
+    expect(session.getSnapshot().promptError).toMatchObject({ op: 'send', error: { code: 'internal', message: 'prompt wire down' } })
+  })
+
+  it('cancel business error also lands op=stop promptError', async () => {
+    const { api, session } = makeSession()
+    api.onCancel = () => Promise.resolve(err({ code: 'agent-busy', message: 'nope', details: { reason: 'r' } }))
+    await session.cancel()
+    expect(session.getSnapshot().promptError).toMatchObject({ op: 'stop', error: { code: 'agent-busy' } })
+  })
+
+  it('loadOlder guards: not-open/no-hasMore no-op, err result kept window, empty page updates hasMore, throw fail-soft', async () => {
+    const { api, session } = makeSession()
+    await session.loadOlder() // cold: no-op, zero calls
+    expect(api.calls).toEqual([])
+    api.onHistory = () => histResponse(plainTurn(6, 1, 'x', 'y'), true)
+    await session.open()
+    // err result: window unchanged
+    api.onHistory = () => Promise.resolve(err({ code: 'internal', message: 'x', details: {} }))
+    await session.loadOlder()
+    expect(session.getSnapshot().nodes).toHaveLength(2)
+    expect(session.getSnapshot().hasMore).toBe(true)
+    // empty page: hasMore adopts the response
+    api.onHistory = () => histResponse([], false)
+    await session.loadOlder()
+    expect(session.getSnapshot().hasMore).toBe(false)
+    // hasMore false now: further loadOlder is a guard no-op
+    const calls = api.calls.length
+    await session.loadOlder()
+    expect(api.calls.length).toBe(calls)
+    // throw path: fail-soft with console.error
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    try {
+      await session.resync()
+      api.onHistory = () => histResponse(plainTurn(6, 1, 'x', 'y'), true)
+      await session.resync()
+      api.onHistory = () => Promise.reject(new Error('page wire down'))
+      await session.loadOlder()
+      expect(errorSpy).toHaveBeenCalled()
+      expect(session.getSnapshot().loadingOlder).toBe(false)
+    } finally {
+      errorSpy.mockRestore()
+    }
+  })
+
+  it('subscribe delivers snapshot-change notifications and unsubscribes', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    let notified = 0
+    const unsubscribe = session.subscribe(() => { notified++ })
+    await session.open()
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(notified).toBeGreaterThan(0)
+    const seen = notified
+    unsubscribe()
+    session.handleRunning(true) // any snapshot mutation; the listener must stay silent
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(notified).toBe(seen)
+  })
+
+  it('subscribed baseline past the window tail triggers the second stitch pull in doOpen', async () => {
+    const { api, session } = makeSession()
+    const full = [...plainTurn(0, 0, 'a', 'b'), ...plainTurn(6, 1, 'c', 'd')]
+    let call = 0
+    api.onHistory = () => {
+      call++
+      return histResponse(call === 1 ? plainTurn(0, 0, 'a', 'b') : full)
+    }
+    // Baseline arrives before open: lastSeq 11 > first page tail 5 → doOpen repulls once.
+    session.handleMuxEnvelope('rs' as never, { type: 'session/subscribed', sessionId: SID, lastSeq: 11 })
+    await session.open()
+    expect(call).toBe(2)
+    expect(session.getSnapshot().nodes.map(n => n.seq)).toEqual([1, 3, 7, 9])
+  })
+
+  it('a failed second stitch pull keeps the first window and still opens', async () => {
+    const { api, session } = makeSession()
+    let call = 0
+    api.onHistory = () => {
+      call++
+      return call === 1
+        ? histResponse(plainTurn(0, 0, 'a', 'b'))
+        : Promise.resolve(err({ code: 'internal', message: 'stitch pull down', details: {} }))
+    }
+    session.handleMuxEnvelope('rs' as never, { type: 'session/subscribed', sessionId: SID, lastSeq: 11 })
+    await session.open()
+    expect(call).toBe(2)
+    const snapshot = session.getSnapshot()
+    expect(snapshot.openState).toBe('open') // stitch-pull failure is not an open failure
+    expect(snapshot.nodes.map(n => n.seq)).toEqual([1, 3]) // first window kept
+  })
+
+  it('approval frame with callId/reason keeps the optional fields; duplicate resolved is a no-op', () => {
+    const { session } = makeSession()
+    session.handleMuxEnvelope('ra' as never, {
+      type: 'approval/requested', sessionId: SID, approvalId: 'ap2' as never, toolName: 'rm', callId: 'c1' as never, reason: '危险',
+    })
+    expect(session.getSnapshot().pending[0]).toMatchObject({ kind: 'approval', callId: 'c1', reason: '危险' })
+    session.handleMuxEnvelope('rx' as never, { type: 'approval/resolved', sessionId: SID, approvalId: 'ap2' as never, outcome: 'approved' as never })
+    session.handleMuxEnvelope('rx2' as never, { type: 'approval/resolved', sessionId: SID, approvalId: 'ap2' as never, outcome: 'approved' as never })
+    session.handleMuxEnvelope('ry2' as never, { type: 'question/resolved', sessionId: SID, questionRpcId: 'never-was' as never, outcome: 'cancelled' })
+    expect(session.getSnapshot().pending).toEqual([])
+  })
+
+  it('ignores unknown mux frame types and repeated running flips (documented defaults)', () => {
+    const { session } = makeSession()
+    const before = session.getSnapshot()
+    session.handleMuxEnvelope('rz' as never, { type: 'future/frame' } as never)
+    session.handleRunning(false) // already false: dedup branch
+    expect(session.getSnapshot()).toBe(before)
+    session.handleRemoved()
+    expect(session.getSnapshot().removed).toBe(true)
+  })
+
+  it('drops live events while cold/error (no window upkeep)', async () => {
+    const { api, session } = makeSession()
+    session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.user(0, '冷态帧') })
+    expect(session.getSnapshot().nodes).toEqual([])
+    api.onHistory = () => Promise.resolve(err({ code: 'internal', message: 'x', details: {} }))
+    await session.open()
+    session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.user(0, '错态帧') })
+    expect(session.getSnapshot().nodes).toEqual([])
+  })
+
+  it('repairGap failure logs and clears stitching; concurrent gaps coalesce into one repair', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    await session.open()
+    const gate = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
+    let repairs = 0
+    api.onHistory = () => {
+      repairs++
+      return gate.promise
+    }
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    try {
+      session.handleMuxEnvelope('r1' as never, { type: 'session/event', sessionId: SID, event: ev.user(9, '洞一') })
+      session.handleMuxEnvelope('r2' as never, { type: 'session/event', sessionId: SID, event: ev.user(10, '洞二') }) // stitching: detours, no second repair
+      expect(repairs).toBe(1)
+      gate.reject(new Error('repair wire down'))
+      await vi.waitFor(() => { expect(errorSpy).toHaveBeenCalled() })
+      // Window unchanged; a later successful repull still lands the buffered frames.
+      expect(session.getSnapshot().nodes).toHaveLength(2)
+    } finally {
+      errorSpy.mockRestore()
+    }
+  })
+
+  it('freezes only content-bearing partials; a content-free partial is dropped outright', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    await session.open()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(ev.chunkStart(7, 1)) // empty text block only, no delta
+    feed(ev.turnEnd(8, 1, 'cancelled'))
+    const snapshot = session.getSnapshot()
+    expect(snapshot.partial).toBeNull()
+    expect(snapshot.nodes.filter(n => n.kind === 'assistant' && (n as { interrupted?: true }).interrupted)).toEqual([])
+  })
+
+  it('turn/end sweeps only same-turn open calls; other turns keep running', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    await session.open()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(ev.toolCall(7, 1, 'turn1-call', 'echo', '{}'))
+    feed(ev.toolCall(8, 2, 'turn2-call', 'echo', '{}')) // stray call attributed to a later turn
+    feed(ev.turnEnd(9, 1, 'cancelled'))
+    const snapshot = session.getSnapshot()
+    expect(snapshot.runningCalls.map(c => c.callId)).toEqual(['turn2-call'])
+    expect(snapshot.nodes.at(-1)).toMatchObject({ kind: 'tool-result', callId: 'turn1-call', isError: true })
+  })
+
+  it('doOpen transport throw of a stale generation is swallowed (generation guard in catch)', async () => {
+    const { api, session } = makeSession()
+    const stale = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
+    api.onHistory = () => stale.promise
+    const opening = session.open()
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    const resynced = session.resync()
+    stale.reject(new Error('stale wire'))
+    await Promise.all([opening, resynced])
+    expect(session.getSnapshot().openState).toBe('open') // stale catch did not write error
+  })
+
+  it('drops a stale doOpen whose history resolved successfully after resync superseded it', async () => {
+    const { api, session } = makeSession()
+    const stale = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
+    api.onHistory = () => stale.promise
+    const opening = session.open()
+    api.onHistory = () => histResponse(plainTurn(6, 1, '新', '代'))
+    const resynced = session.resync()
+    stale.resolve(ok({ events: entries(plainTurn(0, 0, '旧', '代')) as never[], hasMore: false })) // success, but its generation is gone
+    await Promise.all([opening, resynced])
+    expect(session.getSnapshot().nodes.map(n => n.seq)).toEqual([7, 9]) // only the fresh generation's window
+  })
+
+  it('drops a stale stitch pull (second doOpen fetch) superseded mid-flight by resync', async () => {
+    const { api, session } = makeSession()
+    const secondPull = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
+    let call = 0
+    api.onHistory = () => {
+      call++
+      if (call === 1) return histResponse(plainTurn(0, 0, 'a', 'b')) // first page: tail 5
+      if (call === 2) return secondPull.promise // gap-stitch pull: held
+      return histResponse(plainTurn(6, 1, 'c', 'd'))
+    }
+    session.handleMuxEnvelope('rs' as never, { type: 'session/subscribed', sessionId: SID, lastSeq: 11 })
+    const opening = session.open() // triggers the second pull, which parks
+    await vi.waitFor(() => { expect(call).toBe(2) })
+    const resynced = session.resync()
+    secondPull.resolve(ok({ events: entries([...plainTurn(0, 0, 'a', 'b'), ...plainTurn(6, 1, 'c', 'd')]) as never[], hasMore: false }))
+    await Promise.all([opening, resynced])
+    expect(session.getSnapshot().openState).toBe('open')
+  })
+
+  it('drops a gap repair superseded by a full resync while its pull was in flight', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    await session.open()
+    const repairPull = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
+    api.onHistory = () => repairPull.promise
+    session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.user(9, '洞') }) // starts repairGap
+    api.onHistory = () => histResponse(plainTurn(6, 1, 'c', 'd'))
+    const resynced = session.resync() // bumps the generation
+    repairPull.resolve(ok({ events: entries(plainTurn(0, 0, '旧', '页')) as never[], hasMore: false })) // repair result: stale, dropped
+    await resynced
+    expect(session.getSnapshot().nodes.map(n => n.seq)).toEqual([7, 9])
+  })
+
+  it('successful cancel leaves no promptError; tool/result for an unknown callId is a no-op', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    await session.open()
+    const result = await session.cancel()
+    expect(result.ok).toBe(true)
+    expect(session.getSnapshot().promptError).toBeNull()
+    const callsBefore = session.getSnapshot().runningCalls
+    session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.toolResult(6, 0, 'never-called', 'x') })
+    expect(session.getSnapshot().runningCalls).toBe(callsBefore) // callsRev untouched: same reference
+  })
+
+  it('freezes a tool-call-only partial (visible through the non-text arm)', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    await session.open()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(at(7, { type: 'assistant/chunk', data: { turn: 1, step: 0, chunk: { type: 'tool-call-delta', index: 0, id: 'c1', name: 'echo', argumentsDelta: '{' } } }))
+    feed(ev.turnEnd(8, 1, 'cancelled'))
+    const frozen = session.getSnapshot().nodes.at(-1)
+    expect(frozen).toMatchObject({ kind: 'assistant', interrupted: true, blocks: [{ kind: 'tool-call', callId: 'c1' }] })
+  })
+
+  it('dispose is a reserved no-op on resident instances', () => {
+    const { session } = makeSession()
+    expect(() => { session.dispose() }).not.toThrow()
+  })
+
+  it('carries mux-frame views into runningCalls and tool-result nodes, and history-entry views through open', async () => {
+    const { api, session } = makeSession()
+    const callView = { for: 'call', view: { card: 'generic', title: '历史卡' } }
+    api.onHistory = () => Promise.resolve(ok({
+      events: [
+        ...entries(plainTurn(0, 0, 'a', 'b')),
+        { event: ev.toolCall(6, 1, 'h1', 'bash', '{}'), view: callView },
+        { event: ev.toolResult(7, 1, 'h1', 'done'), view: { for: 'result', view: { card: 'generic', title: '历史果' } } },
+      ] as never[],
+      hasMore: false,
+    }))
+    await session.open()
+    expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
+      kind: 'tool-result', callView: { title: '历史卡' }, resultView: { title: '历史果' },
+    })
+    // Live path: the frame's view slot reaches runningCalls, then the result node.
+    session.handleMuxEnvelope('rv1' as never, {
+      type: 'session/event', sessionId: SID, event: ev.toolCall(8, 2, 'l1', 'write', '{}'),
+      view: { for: 'call', view: { card: 'generic', title: '直播卡' } },
+    } as never)
+    expect(session.getSnapshot().runningCalls).toMatchObject([{ callId: 'l1', callView: { title: '直播卡' } }])
+    session.handleMuxEnvelope('rv2' as never, {
+      type: 'session/event', sessionId: SID, event: ev.toolResult(9, 2, 'l1', 'ok'),
+      view: { for: 'result', view: { card: 'generic', title: '直播果' } },
+    } as never)
+    expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
+      kind: 'tool-result', callView: { title: '直播卡' }, resultView: { title: '直播果' },
+    })
+  })
+})
+
+describe('resync', () => {
+  it('rebuilds the window and clears pending; cold instances no-op', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    await session.open()
+    session.handleMuxEnvelope('ra' as never, { type: 'approval/requested', sessionId: SID, approvalId: 'ap1' as never, toolName: 'rm' })
+    api.onHistory = () => histResponse([...plainTurn(0, 0, 'a', 'b'), ...plainTurn(6, 1, 'c', 'd')])
+    await session.resync()
+    const snapshot = session.getSnapshot()
+    expect(snapshot.openState).toBe('open')
+    expect(snapshot.pending).toEqual([]) // baseline replay re-sends still-pending frames
+    expect(snapshot.nodes).toHaveLength(4)
+
+    const cold = makeSession()
+    await cold.session.resync()
+    expect(cold.api.calls).toEqual([]) // never opened: no traffic
+  })
+
+  it('drops a stale in-flight open superseded by resync (generation guard)', async () => {
+    const { api, session } = makeSession()
+    const stale = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
+    api.onHistory = () => stale.promise
+    const firstOpen = session.open()
+    api.onHistory = () => histResponse(plainTurn(6, 1, '新', '代'))
+    const resynced = session.resync()
+    stale.reject(new Error('dead connection')) // the doomed pre-disconnect request fails late
+    await firstOpen
+    await resynced
+    const snapshot = session.getSnapshot()
+    expect(snapshot.openState).toBe('open') // stale failure did not settle the fresh generation into error
+    expect(snapshot.nodes.map(n => n.seq)).toEqual([7, 9])
+  })
+})
+
+describe('reference stability (the memo contract)', () => {
+  it('keeps unchanged node references across an append and swaps the snapshot object', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, '稳', '定'))
+    await session.open()
+    const before = session.getSnapshot()
+    session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.user(6, '追加') })
+    const after = session.getSnapshot()
+    expect(after).not.toBe(before) // top-level swap on change
+    expect(after.nodes[0]).toBe(before.nodes[0]) // untouched nodes keep identity
+    expect(after.nodes[1]).toBe(before.nodes[1])
+    expect(after.nodes).toHaveLength(3)
+    // No change → same snapshot reference.
+    expect(session.getSnapshot()).toBe(after)
+  })
+
+  it('keeps untouched substructure arrays identical across unrelated changes (revision counters)', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, '底', '座'))
+    await session.open()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(ev.toolCall(7, 1, 'c1', 'echo', '{}'))
+    session.handleMuxEnvelope('ra' as never, { type: 'approval/requested', sessionId: SID, approvalId: 'ap1' as never, toolName: 'rm' })
+    const before = session.getSnapshot()
+    // A chunk storm touches partial/nodes only: runningCalls and pending must keep identity.
+    feed(ev.chunkStart(8, 1))
+    feed(ev.chunkText(9, 1, '与工具无关的流式'))
+    const after = session.getSnapshot()
+    expect(after).not.toBe(before)
+    expect(after.runningCalls).toBe(before.runningCalls)
+    expect(after.pending).toBe(before.pending)
+    // And a mutation on the tracked domain swaps that array.
+    feed(ev.toolResult(10, 1, 'c1', 'ECHO'))
+    const resolved = session.getSnapshot()
+    expect(resolved.runningCalls).not.toBe(after.runningCalls)
+    expect(resolved.pending).toBe(after.pending)
+  })
+})
diff --git a/packages/client/runtime/tests/sessions-service.spec.ts b/packages/client/runtime/tests/sessions-service.spec.ts
new file mode 100644
index 0000000000..1f908cca9c
--- /dev/null
+++ b/packages/client/runtime/tests/sessions-service.spec.ts
@@ -0,0 +1,141 @@
+/**
+ * SessionsService: list store projection (manager → {ids, byId} with derived
+ * titles), scope-tree lifecycle (lazy mint / frozen survival / removed
+ * teardown with watch deferral), binding identity, ancestry walk, create.
+ */
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import { SessionsService, scopeOf } from '../src/client/sessions/service.ts'
+import { FakeApiClient, ok } from './fake-api.ts'
+
+const sid = (s: string): SessionId => s as SessionId
+
+interface Bench {
+  ctx: Context
+  api: FakeApiClient
+  svc: SessionsService
+}
+
+function bench(): Bench {
+  const ctx = new Context()
+  const api = new FakeApiClient()
+  const svc = new SessionsService(ctx, api)
+  return { ctx, api, svc }
+}
+
+/** Refresh the manager list from programmable rows and flush the microtask batch. */
+async function feedList(b: Bench, rows: { id: string; cwd?: string; parentId?: string; running?: boolean }[]): Promise<void> {
+  b.api.onList = () => Promise.resolve(ok({
+    items: rows.map(r => ({
+      sessionId: sid(r.id), updatedAt: 1, running: r.running ?? false,
+      ...(r.cwd !== undefined ? { cwd: r.cwd } : {}),
+      ...(r.parentId !== undefined ? { parentSessionId: sid(r.parentId) } : {}),
+    })),
+  }) as never)
+  await b.svc.manager.refreshList()
+  await Promise.resolve() // manager notifier flush
+}
+
+describe('list store projection', () => {
+  it('projects ids/byId with cwd-basename titles (id fallback) and parent links', async () => {
+    const b = bench()
+    await feedList(b, [
+      { id: 's1', cwd: '/home/u/proj-a/' },
+      { id: 's2', parentId: 's1', running: true },
+    ])
+    const state = b.svc.list.getSnapshot()
+    expect(state.ids).toEqual(['s1', 's2'])
+    expect(state.byId[sid('s1')]).toMatchObject({ title: 'proj-a', cwd: '/home/u/proj-a/' })
+    expect(state.byId[sid('s2')]).toMatchObject({ title: 's2', parentId: 's1', running: true })
+  })
+
+  it('reflects live increments (host stream via manager) into the store', async () => {
+    const b = bench()
+    await feedList(b, [{ id: 's1' }])
+    b.svc.manager.handleHostEnvelope({ rpcId: 'r1' as never, payload: { type: 'host/session-added', sessionId: sid('s2') } as never })
+    await Promise.resolve()
+    expect(b.svc.list.getSnapshot().ids).toContain('s2')
+  })
+})
+
+describe('scope tree', () => {
+  it('mints lazily on first resolution, tags the ctx, and keeps binding identity stable', async () => {
+    const b = bench()
+    await feedList(b, [{ id: 's1' }])
+    expect(b.svc.scope(sid('unknown'))).toBeUndefined()
+    const scoped = b.svc.scope(sid('s1'))
+    expect(scoped).toBeDefined()
+    expect(scopeOf(scoped as Context)).toBe('s1')
+    expect(scopeOf(b.ctx)).toBeUndefined()
+    const binding = b.svc.binding(sid('s1'))
+    expect(binding?.session).toBe(b.svc.manager.get(sid('s1')))
+    expect(b.svc.binding(sid('s1'))).toBe(binding)
+    expect(binding?.ctx).toBe(scoped)
+  })
+
+  it('tears down an unwatched removed session but defers the watched one until the watch moves', async () => {
+    const b = bench()
+    await feedList(b, [{ id: 's1' }, { id: 's2' }])
+    const ctx1 = b.svc.scope(sid('s1'))
+    b.svc.binding(sid('s1')) // s1 is watched
+    b.svc.scope(sid('s2')) // s2 scoped but not watched
+
+    await feedList(b, [{ id: 's1' }]) // s2 removed, unwatched: torn down
+    expect(b.svc.scope(sid('s2'))).toBeUndefined()
+
+    await feedList(b, []) // s1 removed while watched: deferred, scope survives
+    expect(b.svc.scope(sid('s1'))).toBe(ctx1)
+
+    await feedList(b, [{ id: 's3' }])
+    b.svc.binding(sid('s3')) // watch moves: deferred teardown sweeps s1
+    expect(b.svc.scope(sid('s1'))).toBeUndefined()
+  })
+
+  it('keeps the scope when the session merely stops running (frozen ≠ removed)', async () => {
+    const b = bench()
+    await feedList(b, [{ id: 's1', running: true }])
+    const scoped = b.svc.scope(sid('s1'))
+    await feedList(b, [{ id: 's1', running: false }])
+    expect(b.svc.scope(sid('s1'))).toBe(scoped)
+  })
+
+  it('cancels a deferred teardown when the id reappears in the list', async () => {
+    const b = bench()
+    await feedList(b, [{ id: 's1' }])
+    const scoped = b.svc.scope(sid('s1'))
+    b.svc.binding(sid('s1'))
+    await feedList(b, []) // removed while watched → deferred
+    await feedList(b, [{ id: 's1' }, { id: 's2' }]) // reappears
+    b.svc.binding(sid('s2')) // watch moves; sweep must NOT tear down the re-listed s1
+    expect(b.svc.scope(sid('s1'))).toBe(scoped)
+  })
+})
+
+describe('ancestry', () => {
+  it('walks parentId links root-first including self; broken links stop the walk', async () => {
+    const b = bench()
+    await feedList(b, [
+      { id: 'root', cwd: '/w/app' },
+      { id: 'mid', parentId: 'root' },
+      { id: 'leaf', parentId: 'mid' },
+      { id: 'orphan', parentId: 'ghost' },
+    ])
+    expect(b.svc.ancestry(sid('leaf')).map(s => s.id)).toEqual(['root', 'mid', 'leaf'])
+    expect(b.svc.ancestry(sid('orphan')).map(s => s.id)).toEqual(['orphan'])
+    expect(b.svc.ancestry(sid('ghost'))).toEqual([])
+  })
+})
+
+describe('create', () => {
+  it('returns the new id on ok and throws a coded error on failure', async () => {
+    const b = bench()
+    b.api.onCreate = () => Promise.resolve(ok({ sessionId: sid('fresh') }))
+    await expect(b.svc.create({ cwd: '/w' })).resolves.toBe('fresh')
+    b.api.onCreate = () => Promise.resolve({
+      rpcId: 'e' as never,
+      result: { ok: false as const, error: { code: 'internal' as const, message: '爆了', details: {} } },
+    } as never)
+    await expect(b.svc.create()).rejects.toThrow(/internal: 爆了/)
+  })
+})
diff --git a/packages/client/runtime/tests/slots-service.spec.ts b/packages/client/runtime/tests/slots-service.spec.ts
new file mode 100644
index 0000000000..54b8abd658
--- /dev/null
+++ b/packages/client/runtime/tests/slots-service.spec.ts
@@ -0,0 +1,65 @@
+/**
+ * SlotsService: cordis Service wrapper semantics — core delegation, the
+ * 'slots/changed' event bridge, and fiber-scoped registration disposal.
+ */
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import type { FC } from 'react'
+import { SlotsService } from '../src/client/slots.ts'
+
+// Test-only slot keys (SlotMap is empty in this package; the service is generic over it).
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    't-single': { kind: 'single'; scope: 'root'; props: object }
+    't-list': { kind: 'list'; scope: 'root'; props: object }
+  }
+}
+
+const C: FC<object> = () => null
+
+async function boot(): Promise<Context> {
+  const ctx = new Context()
+  ctx.plugin(SlotsService)
+  await ctx.fiber.await()
+  return ctx
+}
+
+describe('SlotsService', () => {
+  it('proxies define/register/entries/spec/getVersion to the core', async () => {
+    const ctx = await boot()
+    ctx.slots.define('t-single', { kind: 'single', scope: 'root' })
+    expect(ctx.slots.spec('t-single')).toEqual({ kind: 'single', scope: 'root' })
+    const v0 = ctx.slots.getVersion('t-single')
+    ctx.slots.register('t-single', C)
+    expect(ctx.slots.entries('t-single')).toHaveLength(1)
+    expect(ctx.slots.getVersion('t-single')).toBeGreaterThan(v0)
+    expect(ctx.slots.core.spec('t-single')).toBeDefined()
+  })
+
+  it("re-emits every mutation as 'slots/changed' with the key", async () => {
+    const ctx = await boot()
+    const seen: string[] = []
+    ctx.on('slots/changed', (key) => { seen.push(key) })
+    ctx.slots.define('t-list', { kind: 'list', scope: 'root' })
+    ctx.slots.register('t-list', C, { id: 'a' })
+    expect(seen).toEqual(['t-list', 't-list'])
+  })
+
+  it('collects a plugin fiber\'s registrations when the fiber unloads (cascade)', async () => {
+    const ctx = await boot()
+    ctx.slots.define('t-single', { kind: 'single', scope: 'root' })
+    const fiber = ctx.plugin({
+      name: 'occupant',
+      inject: ['slots'],
+      apply: (pluginCtx: Context) => {
+        pluginCtx.slots.register('t-single', C)
+      },
+    })
+    await fiber.await()
+    expect(ctx.slots.entries('t-single')).toHaveLength(1)
+    await fiber.dispose()
+    expect(ctx.slots.entries('t-single')).toHaveLength(0)
+    // The slot definition (registered from root) survives; a new occupant may register.
+    expect(() => ctx.slots.register('t-single', C)).not.toThrow()
+  })
+})
diff --git a/packages/client/runtime/tsconfig.json b/packages/client/runtime/tsconfig.json
new file mode 100644
index 0000000000..82ebf4f989
--- /dev/null
+++ b/packages/client/runtime/tsconfig.json
@@ -0,0 +1,39 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "lib": [
+      "ES2024",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": []
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../web-react"
+    },
+    {
+      "path": "../connection"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ],
+  "exclude": [
+    "**/*.legacy.*"
+  ]
+}
diff --git a/packages/client/runtime/tsdown.config.ts b/packages/client/runtime/tsdown.config.ts
new file mode 100644
index 0000000000..a1bb544eb0
--- /dev/null
+++ b/packages/client/runtime/tsdown.config.ts
@@ -0,0 +1,23 @@
+import type { UserConfig } from 'tsdown'
+import { clientBundle } from '../tsdown.client.ts'
+
+/**
+ * Standard dual-entry shape plus the loader lib half: exports["./loader"]
+ * promises lib/loader.js (the web shell statically imports the machinery —
+ * a loader cannot load itself), and the shared preset only emits
+ * lib/{index,invariant}.js, so the extra config supplies it.
+ */
+const configs = clientBundle('@deepseek-ai/dsh-client-runtime', ['lib/types/index.js', 'lib/types/invariant.js'])
+
+const loaderLib: UserConfig = {
+  entry: { loader: 'lib/types/client/loader/index.js' },
+  outDir: 'lib',
+  format: ['esm'],
+  platform: 'neutral',
+  target: 'es2024',
+  fixedExtension: false,
+  dts: false,
+  clean: false,
+}
+
+export default [...configs, loaderLib]
diff --git a/packages/client/tsdown.client.ts b/packages/client/tsdown.client.ts
new file mode 100644
index 0000000000..860c9cc908
--- /dev/null
+++ b/packages/client/tsdown.client.ts
@@ -0,0 +1,152 @@
+/**
+ * Shared tsdown preset for UI plugin client bundles. Emits a closure-factory
+ * artifact: the bundle calls window.DSHClientProxy.loadPlugin({id, factory})
+ * and resolves externals through the injected require (loader module table —
+ * cordis DI entities, no globals, no import map). CSS Modules are compiled by
+ * lightningcss inside the bundle: importing `x.module.css` yields the
+ * hashed class map, and the css text auto-injects a <style data-plugin="<id>">
+ * tag at factory execution (the loader removes plugin-owned tags on unload).
+ */
+import { readFile } from 'node:fs/promises'
+import { basename, dirname, resolve as resolvePath } from 'node:path'
+import type { UserConfig } from 'tsdown'
+import { transform } from 'lightningcss'
+
+/**
+ * Virtual-id wrapper keeping module CSS away from tsdown's own css pipeline
+ * (which requires @tsdown/css). The suffix matters: tsdown's guard matches ids
+ * ending in `.css`, so the virtual id must not.
+ */
+const CSS_VIRTUAL_PREFIX = '\0dsh-css:'
+const CSS_VIRTUAL_SUFFIX = '.mjs'
+
+/**
+ * Wire/type layers a client bundle may inline: browser-safe contract surfaces
+ * with no runtime identity to share (no Symbol/instanceof/singleton state).
+ * Everything else under @deepseek-ai/* is either a module-table entry
+ * (external) or a leak the purity gate rejects.
+ */
+export const INLINE_SAFE = /^@deepseek-ai\/dsh-(host-apiproxy|session|llm|tools|brand)(\/|$)/
+
+/** Externals resolved from the loader module table (keep in sync with the shell's seeding list). */
+export const CLIENT_EXTERNALS = [
+  'react',
+  'react-dom',
+  'react/jsx-runtime',
+  'cordis',
+  '@deepseek-ai/dsh-client-ui-slots',
+  '@deepseek-ai/dsh-client-web-react',
+  '@deepseek-ai/dsh-client-web-react/store',
+  '@deepseek-ai/dsh-client-ui-primitives',
+  '@deepseek-ai/dsh-client-connection/client',
+  '@deepseek-ai/dsh-client-runtime/client',
+  '@deepseek-ai/dsh-client-ui-layout/client',
+  '@deepseek-ai/dsh-client-ui-conversation/client',
+  '@deepseek-ai/dsh-client-ui-theme/client',
+  '@deepseek-ai/dsh-client-i18n/client',
+]
+
+/**
+ * Build the tsdown config for one UI plugin package: the node-half lib build
+ * plus the browser client bundle. A package-level tsdown.config.ts REPLACES
+ * the root workspace shape, so the lib half must be restated here — dropping
+ * it leaves the package without lib/index.js and the host Loader cannot
+ * import its node half.
+ * @param id - plugin id (package name), stamped into the loadPlugin handoff
+ * and onto the injected style tags.
+ * @param libEntry - node-half entries, spelled at the call site so the
+ * package-invariants gate can see `lib/types/invariant.js` in each package's
+ * own tsdown.config.ts (a preset-side glob hides it from the mechanical check).
+ * @returns tsdown user configs emitting lib/*.js and lib/client.js.
+ */
+export function clientBundle(id: string, libEntry: readonly string[]): UserConfig[] {
+  return [{
+    entry: [...libEntry],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  }, {
+    entry: { client: 'src/client/index.ts' },
+    // Browser bundle lands next to the node half (single lib/ artifact dir;
+    // the entryFileNames pin keeps it exactly lib/client.js). clean must stay
+    // off — a default clean would wipe the node-half output emitted above.
+    outDir: 'lib',
+    format: 'cjs',
+    platform: 'browser',
+    // Types ship from lib/types (tsc); dts here would wrap the banner/footer into .d.cts and break parsing.
+    dts: false,
+    clean: false,
+    external: CLIENT_EXTERNALS,
+    // tsdown auto-externalizes package dependencies; anything NOT in the
+    // loader module table must inline instead (wire/type layers, zod, clsx —
+    // every non-shared dep). A require() the table cannot answer is a
+    // guaranteed runtime throw, so the rule is the table list itself: no
+    // opinion for table entries (external above wins), bundle everything else.
+    noExternal: (id: string) => (CLIENT_EXTERNALS.includes(id) ? undefined : true),
+    plugins: [{
+      // Bundle purity gate: a bare-name import of a module-table package would
+      // slip past CLIENT_EXTERNALS (which lists the /client form) and INLINE a
+      // second copy of that package — duplicate runtime identity (a second
+      // scope Symbol was tonight's white-screen root cause). Resolve-time is
+      // the earliest, most precise interception: rewrite bare table names to
+      // their /client form (the loader registers both specifiers), and reject
+      // any other @deepseek-ai/* leak that is not an inline-safe wire layer.
+      name: 'dsh-client-bundle-purity',
+      resolveId(source: string) {
+        if (!source.startsWith('@deepseek-ai/')) return null
+        if (CLIENT_EXTERNALS.includes(source)) return null // external wins
+        if (CLIENT_EXTERNALS.includes(`${source}/client`)) {
+          return { id: `${source}/client`, external: true }
+        }
+        if (INLINE_SAFE.test(source)) return null // wire/type layer: inline is the point
+        throw new Error(
+          `client bundle purity: "${source}" is not in CLIENT_EXTERNALS and not an inline-safe wire layer — `
+          + 'import the /client form, add it to the module table, or it inlines a duplicate runtime instance',
+        )
+      },
+    }, {
+      name: 'dsh-css-modules-inline',
+      resolveId(source: string, importer: string | undefined) {
+        if (!source.endsWith('.module.css')) return null
+        const abs = importer !== undefined ? resolvePath(dirname(importer), source) : source
+        return CSS_VIRTUAL_PREFIX + abs + CSS_VIRTUAL_SUFFIX
+      },
+      async load(virtualId: string) {
+        if (!virtualId.startsWith(CSS_VIRTUAL_PREFIX)) return null
+        const fileId = virtualId.slice(CSS_VIRTUAL_PREFIX.length, -CSS_VIRTUAL_SUFFIX.length)
+        const source = await readFile(fileId)
+        const { code, exports: cssExports } = transform({
+          filename: fileId,
+          code: source,
+          cssModules: { pattern: `[hash]_[local]` },
+          minify: true,
+        })
+        const classMap: Record<string, string> = {}
+        for (const [local, exp] of Object.entries(cssExports ?? {})) classMap[local] = exp.name
+        // One <style data-plugin> per module file; idempotent under re-evaluation.
+        return [
+          `const css = ${JSON.stringify(code.toString())};`,
+          `const tagId = ${JSON.stringify(`${id}/${basename(fileId)}`)};`,
+          `if (typeof document !== 'undefined' && document.querySelector('style[data-plugin-css=' + JSON.stringify(tagId) + ']') === null) {`,
+          `  const tag = document.createElement('style');`,
+          `  tag.dataset.plugin = ${JSON.stringify(id)};`,
+          `  tag.dataset.pluginCss = tagId;`,
+          `  tag.textContent = css;`,
+          `  document.head.appendChild(tag);`,
+          `}`,
+          `export default ${JSON.stringify(classMap)};`,
+        ].join('\n')
+      },
+    }],
+    outputOptions: {
+      entryFileNames: 'client.js',
+      banner: `window.DSHClientProxy.loadPlugin({ id: ${JSON.stringify(id)}, factory: (require) => {`,
+      footer: `return module.exports; } });`,
+      intro: 'var module = { exports: {} }; var exports = module.exports;',
+    },
+  }]
+}
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
new file mode 100644
index 0000000000..c75077d11d
--- /dev/null
+++ b/packages/client/ui-conversation/README.md
@@ -0,0 +1,22 @@
+# @deepseek-ai/dsh-client-ui-conversation
+
+Conversation domain: skeleton (header/tabs/composer/empty state), chat view (grouped step-summary flow, streaming tail isolation), ctx.toolviews named registry with bash samples, minimal details panel, scope-addressed ConversationService. Contract: api-contracts v3 §7.
+
+`src/client/` is organized for the future package split: `contract/` is the sole inter-domain shared face (`slots.ts` composed slot props, `views.ts` view ring, `toolview.ts` tool ring, `tool-call-model.ts`); the `skeleton/`, `chat/`, and `toolviews/` domain directories import contract files and never each other; `apply.ts` is the only assembly point allowed to import all three domains.
+
+## Model Experience
+
+None, as the conversation UI renders session history and streams in the browser; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **The stats line has no duration segment** — assistant `usage` carries token accounting only; elapsed-time needs a host data source.
+- **Details panel is the minimal form** — selected call args/result raw display; the Input/Output/Metadata switch, Prev/Next stepping, and See-in-trajectory deep link are deferred.
+- **Assistant footer extensions (IconActions row, per-message paging) are reserved slots** — drawn in the design, not implemented.
+- **The sparkle icon for the others tool row is a hand-drawn approximation** — the design glyph's vector geometry is not exportable locally; promotion into ui-primitives waits on an exact export.
+- **Approval/question cards are display-only placeholders** — web-side answering (composer takeover panel) is the P-II approvals project.
+- **Module-level toolview caches are single-bundle state** — the inject cache and registry maps must reach cross-bundle consumers through the package export surface and loader module table, never by a second bundle copy.
diff --git a/packages/client/ui-conversation/package.json b/packages/client/ui-conversation/package.json
new file mode 100644
index 0000000000..e9a3aed8ce
--- /dev/null
+++ b/packages/client/ui-conversation/package.json
@@ -0,0 +1,63 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-conversation",
+  "description": "Conversation domain: skeleton (header/tabs/composer), chat view, ctx.toolviews registry, minimal details panel",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-client-ui-layout"
+    ],
+    "platform": "web"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-client-i18n": "workspace:^",
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-client-web-react": "workspace:^",
+    "clsx": "^2.0.0",
+    "react": "^18.2.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
new file mode 100644
index 0000000000..a600789a20
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -0,0 +1,185 @@
+/**
+ * Client plugin body: provide the conversation service and toolview registry,
+ * register the conversation/details slot occupants and the no-session empty
+ * state, and mount the chat view with its samples. Assembly only — components
+ * receive everything through inject factories; nothing here renders directly.
+ */
+import { createElement, Fragment, type ReactNode } from 'react'
+import type { Context } from 'cordis'
+import type { SessionBinding } from '@deepseek-ai/dsh-client-ui-slots'
+import { scopedSlots, shallowEqual } from '@deepseek-ai/dsh-client-web-react'
+import type { SnapshotSelectorHook, UseSession } from '@deepseek-ai/dsh-client-web-react'
+import type {
+  SessionId, SessionListState, SessionsService, SlotsService,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { LayoutService } from '@deepseek-ai/dsh-client-ui-layout/client'
+import type { I18nService } from '@deepseek-ai/dsh-client-i18n/client'
+import type { ConvViewProps, SelectionTarget, ViewEntry, ViewId } from './contract/views.ts'
+import type { ConversationInjected, DetailsInjected, EmptyStateInjected } from './contract/slots.ts'
+import { ConversationService } from './service.ts'
+import { ToolViewRegistry } from './toolviews/registry.ts'
+import { childSessionScope, registerChat } from './chat/register.ts'
+import { registerBashSamples } from './toolviews/bash-sample.tsx'
+import { ConversationRoot } from './skeleton/ConversationRoot.tsx'
+import { DetailsPanel } from './skeleton/DetailsPanel.tsx'
+import { EmptyState } from './skeleton/EmptyState.tsx'
+
+/** Required services (cordis fiber inject — the loader passes the whole export surface as an object plugin). */
+export const inject = ['slots', 'layout', 'sessions', 'i18n']
+
+/** Resolve a service via ctx.get, failing loud. Property access is reserved
+ *  for contexts whose fiber declares the inject (scope fibers do not). */
+// T is the caller-named cast target; inlining `as T` per call site would scatter the budgeted cast.
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+function need<T>(ctx: Context, name: string): T {
+  const value = ctx.get(name) as T | undefined
+  if (value === undefined) throw new Error(`ui-conversation: ${name} service unavailable`)
+  return value
+}
+
+/** Per-list-state cwd set (deduped, list order) for the empty-state picker. */
+const cwdsCache = new WeakMap<SessionListState, readonly string[]>()
+function cwdsOf(state: SessionListState): readonly string[] {
+  let cached = cwdsCache.get(state)
+  if (cached === undefined) {
+    const seen = new Set<string>()
+    for (const id of state.ids) {
+      const cwd = state.byId[id]?.cwd
+      if (cwd !== undefined && cwd !== '') seen.add(cwd)
+    }
+    cached = [...seen]
+    cwdsCache.set(state, cached)
+  }
+  return cached
+}
+
+/**
+ * Client plugin body.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: Context): void {
+  const sessions = need<SessionsService>(ctx, 'sessions')
+  const layout = need<LayoutService>(ctx, 'layout')
+  const i18n = need<I18nService>(ctx, 'i18n')
+  const slots = need<SlotsService>(ctx, 'slots')
+
+  const conversation = new ConversationService(ctx)
+  const toolviews = new ToolViewRegistry()
+  ctx.provide('toolviews', toolviews)
+
+  const t = i18n.bind('conversation')
+  // Chat view + StatsLine footer; bash samples assembled here (apply is the
+  // only cross-domain point — chat consumes the resolver face, samples come
+  // from the toolviews domain). registerView inside registerChat is already
+  // effect-scoped; the raw sample registrations need the effect wrapper to
+  // ride the fiber cascade.
+  ctx.effect(
+    () => registerChat({ conversation, toolviews, t }),
+    'ui-conversation: chat view')
+  ctx.effect(
+    () => registerBashSamples(toolviews, childSessionScope(sessions.list)),
+    'ui-conversation: bash toolview samples')
+
+  // ConvViewProps.slots is ScopedSlots<never>: a real outlet with an empty
+  // whitelist (uncallable by type, correct runtime shape for future grants).
+  const emptySlots = scopedSlots<never>(slots.core)
+
+  /** conversation slot: skeleton surface assembled once per (entry x session). */
+  const conversationInject = (b: SessionBinding): ConversationInjected => {
+    const bctx = b.ctx as Context
+    const scoped = need<ConversationService>(bctx, 'conversation')
+    const id = b.sessionId as SessionId
+    const useSession = b.session.useSelector as UseSession
+    const selectionStore = scoped.selection
+    const draftsStore = scoped.drafts
+    const session = sessions.manager.get(id)
+    // Watch-driven history pull: assembling the surface IS the watch signal
+    // (once per entry x session; open() is idempotent and self-recovers).
+    void session.open()
+
+    const viewProps: Omit<ConvViewProps, 'slots'> = {
+      sessionId: id,
+      useSession,
+      useSelection: selectionStore.useSelector,
+      actions: {
+        openDetails: (target: SelectionTarget) => { scoped.openDetails(target) },
+        loadOlder: () => { void session.loadOlder() },
+      },
+    }
+
+    const injected: ConversationInjected = {
+      useAncestry: () => sessions.list.useSelector(
+        () => sessions.ancestry(id),
+        (a, b) => shallowEqual(a, b)),
+      views: {
+        list: () => conversation.views(),
+        subscribe: fn => conversation.subscribeViews(fn),
+        version: () => conversation.viewsVersion(),
+      },
+      // layout's viewFor value type is its own looser ViewId; the registry is
+      // the runtime validator (unknown ids fall back to the first view).
+      useActiveView: () => layout.current.useSelector(s => s.viewFor[id]) as ViewId | undefined,
+      composer: {
+        useDraft: () => draftsStore.useSelector(s => s),
+        setDraft: (text) => { draftsStore.set(text) },
+        send: (mode) => {
+          const text = draftsStore.getSnapshot().trim()
+          if (text === '') return
+          // Optimistic clear with failure restore (choreography lives with the
+          // sender; the business failure also lands in snapshot.promptError).
+          draftsStore.set('')
+          void scoped.send(text, mode).catch(() => {
+            if (draftsStore.getSnapshot() === '') draftsStore.set(text)
+          })
+        },
+        stop: () => {
+          scoped.cancel().catch(() => {
+            // Stop failure surfaces via snapshot.promptError; nothing to restore.
+          })
+        },
+      },
+      actions: {
+        openView: (view: ViewId) => { layout.openView(id, view) },
+        open: (target: SessionId) => { layout.open(target) },
+      },
+      renderView: (entry: ViewEntry): ReactNode => {
+        const children: ReactNode[] = []
+        if (entry.chrome?.header !== undefined) {
+          children.push(createElement(entry.chrome.header, { key: 'header', sessionId: id, useSession }))
+        }
+        children.push(createElement(entry.component, { key: 'view', ...viewProps, slots: emptySlots }))
+        if (entry.chrome?.footer !== undefined) {
+          children.push(createElement(entry.chrome.footer, { key: 'footer', sessionId: id, useSession }))
+        }
+        return createElement(Fragment, null, ...children)
+      },
+    }
+    return injected
+  }
+
+  /** details slot: minimal selection-driven panel. */
+  const detailsInject = (b: SessionBinding): DetailsInjected => {
+    const bctx = b.ctx as Context
+    const scoped = need<ConversationService>(bctx, 'conversation')
+    const injected: DetailsInjected = {
+      useSelection: scoped.selection.useSelector,
+      actions: { closeDetails: () => { layout.closeDetails() } },
+    }
+    return injected
+  }
+
+  /** conversation.empty root slot: the NEW SESSION hero. */
+  const emptyInject = (): EmptyStateInjected => {
+    const useCwds: SnapshotSelectorHook<readonly string[]> = (sel, eq) =>
+      sessions.list.useSelector(s => sel(cwdsOf(s)), eq)
+    const injected: EmptyStateInjected = {
+      useCwds,
+      actions: { startSession: opts => conversation.startSession(opts) },
+    }
+    return injected
+  }
+
+  slots.register('conversation', ConversationRoot, { inject: conversationInject })
+  slots.register('details', DetailsPanel, { inject: detailsInject })
+  slots.register('conversation.empty', EmptyState, { inject: emptyInject })
+}
diff --git a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.module.css b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.module.css
new file mode 100644
index 0000000000..b4570af921
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.module.css
@@ -0,0 +1,33 @@
+/* Assistant flow body: full-width narration (figma 16/28), block gap 16. */
+
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  font-size: 16px;
+  line-height: 28px;
+  color: var(--dsw-alias-label-primary);
+}
+
+.pulse {
+  display: inline-block;
+  width: 8px;
+  height: 14px;
+  background: var(--dsw-alias-state-business-primary);
+  animation: pulse 1s infinite ease-in-out;
+}
+
+@keyframes pulse {
+  50% { opacity: 0.2; }
+}
+
+/* Interrupted-turn terminal marker: quiet inline tag, no animation. */
+.stopped {
+  align-self: flex-start;
+  padding: 0 6px;
+  border-radius: 6px;
+  background: var(--dsw-alias-interactive-bg-hover);
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 11px;
+  line-height: 18px;
+}
diff --git a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
new file mode 100644
index 0000000000..61ac069b1c
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
@@ -0,0 +1,56 @@
+// AssistantMarkdown: renders assistant blocks in order — markdown text body,
+// reasoning as the figma Think summary row (expand = indented gray text),
+// other-block JSON fallback. Tool-call heads are NOT rendered here: the chat
+// view groups them into tool rows via the toolview outlet (figma step-summary
+// flow). Shared by finalized nodes and the streaming partial (pulse marker).
+
+import { memo } from 'react'
+import type { AssistantBlock } from '@deepseek-ai/dsh-client-runtime/client'
+import { IconThinkOutline14, JsonBlock, MessageText } from '@deepseek-ai/dsh-client-ui-primitives'
+import { ToolRow } from './ToolRow.tsx'
+import css from './AssistantMarkdown.module.css'
+
+export interface AssistantMarkdownProps {
+  blocks: readonly AssistantBlock[]
+  streaming: boolean
+  /** Frozen partial of an aborted turn: rendered with a 已停止 marker, no pulse. */
+  interrupted?: boolean | undefined
+}
+
+function firstLine(text: string): string {
+  const nl = text.indexOf('\n')
+  return nl === -1 ? text : text.slice(0, nl)
+}
+
+/** Reasoning block as the Think variant summary row (figma 39:28304). */
+function ThinkRow({ text, running }: { text: string; running: boolean }) {
+  return (
+    <ToolRow
+      variant="think"
+      icon={<IconThinkOutline14 />}
+      title="Think"
+      summary={firstLine(text)}
+      body={text}
+      state={running ? 'running' : 'ok'}
+    />
+  )
+}
+
+export const AssistantMarkdown = memo(function AssistantMarkdown({ blocks, streaming, interrupted }: AssistantMarkdownProps) {
+  const last = blocks.length - 1
+  return (
+    <div className={css.root} data-streaming={streaming || undefined}>
+      {blocks.map((block, i) => {
+        switch (block.kind) {
+          case 'text': return <MessageText key={i} text={block.text} />
+          case 'reasoning': return <ThinkRow key={i} text={block.text} running={streaming && i === last} />
+          // Tool-call heads render as tool rows in the chat view's grouping pass.
+          case 'tool-call': return null
+          default: return <JsonBlock key={i} label="未知内容块" payload={block.block} />
+        }
+      })}
+      {streaming && <span className={css.pulse} />}
+      {interrupted && <span className={css.stopped}>已停止</span>}
+    </div>
+  )
+})
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.module.css b/packages/client/ui-conversation/src/client/chat/ChatView.module.css
new file mode 100644
index 0000000000..2c3d700501
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.module.css
@@ -0,0 +1,101 @@
+/* Chat flow: block gap 16 between narration/bubbles/tool groups (figma);
+   tool rows inside a group gap 10. Input padding cap rides the skeleton. */
+
+.root {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  flex: 1 1 auto;
+}
+
+.scroll {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+  padding: 16px 24px;
+}
+
+/* Message column: 736px fixed width, centered on the same axis as the
+   input box; the scroller itself stays full-bleed. */
+.column {
+  max-width: 736px;
+  width: 100%;
+  margin: 0 auto;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.toolGroup {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.callRow {
+  border-radius: 6px;
+}
+
+/* Selection linkage: the selected call row wears the blue outline.
+   button-info-fill flips 500→400 with the theme, hitting the darker-blue
+   dark-mode spec exactly (business-primary stays 500 on both). */
+.callRow[data-selected] {
+  outline: 1.5px solid var(--dsw-alias-button-info-fill);
+  outline-offset: 1px;
+}
+
+.hint {
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 12px;
+  line-height: 18px;
+}
+
+.openError {
+  color: var(--dsw-alias-state-error-primary);
+  font-size: 12px;
+  line-height: 18px;
+}
+
+.older {
+  display: flex;
+  justify-content: center;
+}
+
+.older button {
+  border: none;
+  border-radius: 14px;
+  padding: 4px 12px;
+  font-size: 12px;
+  color: var(--dsw-alias-label-secondary);
+  background: var(--dsw-alias-interactive-bg-hover-solid);
+  cursor: pointer;
+}
+
+.older button:disabled {
+  cursor: default;
+  opacity: 0.6;
+}
+
+/* Back-to-bottom: 34px circular icon button at the column's right edge. */
+.toBottom {
+  position: absolute;
+  right: max(24px, calc((100% - 736px) / 2));
+  bottom: 16px;
+  width: 34px;
+  height: 34px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 100px;
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-alias-button-floating-fill);
+  box-shadow: var(--dsw-shadow-lv2);
+  cursor: pointer;
+}
+
+.toBottom:hover {
+  background: var(--dsw-alias-button-floating-hover);
+}
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
new file mode 100644
index 0000000000..b8ea969829
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -0,0 +1,293 @@
+// ChatView: the default conversation view — message flow with user bubbles,
+// assistant narration, tool summary rows grouped into step runs, pending
+// cards, paging and bottom-follow. Created via factory so plugin deps
+// (toolviews registry, i18n) arrive by closure, never by import.
+//
+// Render economics (architecture RFC performance model): the list parent
+// subscribes to snapshot segments that do NOT change per streaming chunk
+// (nodes/runningCalls/pending keep their references across chunk batches), so
+// during a token storm only StreamingTail re-renders; history rows hold via
+// memo on cache-stable node slices. Selection changes re-render the parent
+// map but only rows whose own selected bit flipped.
+
+import {
+  memo, useLayoutEffect, useMemo, useRef, useState, type FC, type ReactNode,
+} from 'react'
+import type {
+  ConversationNode, ConversationSnapshot, RunningToolCall, SessionId, ToolResultNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
+import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ConvViewProps, SelectionTarget, Translate } from '../contract/views.ts'
+import type { ToolViewProps } from '../contract/toolview.ts'
+import type { ToolViewResolver } from '../contract/toolview.ts'
+import { deriveChatFlow, type ChatFlowItem } from './chat-flow.ts'
+import { AssistantMarkdown } from './AssistantMarkdown.tsx'
+import { MessageItem } from './MessageItem.tsx'
+import { PendingCard } from './PendingCard.tsx'
+import { ToolViewOutlet } from './ToolViewOutlet.tsx'
+import css from './ChatView.module.css'
+
+/** Plugin-supplied closure deps (assembled in registerChat, apply world). */
+export interface ChatViewDeps {
+  toolviews: ToolViewResolver
+  t: Translate
+}
+
+const FOLLOW_THRESHOLD = 24
+
+type OpenDetails = (target: SelectionTarget) => void
+
+/** web-react's UseSession is deliberately wide (dependency direction); the
+ *  chat view narrows once to the runtime snapshot the binding actually feeds. */
+type UseConversation = SnapshotSelectorHook<ConversationSnapshot>
+
+/** One tool call row (result or running): builds the bound ToolViewProps. */
+const CallRow = memo(function CallRow({ registry, sessionId, useSession, t, callId, toolName, block, seq, onOpenDetails, selected }: {
+  registry: ToolViewResolver
+  sessionId: SessionId
+  useSession: ConvViewProps['useSession']
+  t: Translate
+  callId: string
+  toolName: string
+  block: ToolResultNode | RunningToolCall
+  /** Surface seq for finalized results; the call's turn for running calls. */
+  seq: number
+  onOpenDetails: OpenDetails
+  selected: boolean
+}) {
+  const viewProps = useMemo<ToolViewProps>(() => ({
+    callId, toolName, block, useSession,
+    actions: { openDetails: () => onOpenDetails({ turnSeq: seq, callId, toolName }) },
+    t,
+  }), [callId, toolName, block, useSession, seq, onOpenDetails, t])
+  return (
+    <div className={css.callRow} data-selected={selected || undefined}>
+      <ToolViewOutlet registry={registry} sessionId={sessionId} toolName={toolName} viewProps={viewProps} />
+    </div>
+  )
+})
+
+/** Consecutive tool results as one step-run group (figma VERTICAL gap10). */
+const ToolGroup = memo(function ToolGroup({ registry, sessionId, useSession, t, results, onOpenDetails, selectedCallId }: {
+  registry: ToolViewResolver
+  sessionId: SessionId
+  useSession: ConvViewProps['useSession']
+  t: Translate
+  results: readonly ToolResultNode[]
+  onOpenDetails: OpenDetails
+  /** Only set when the selected call lives in THIS group (memo economy). */
+  selectedCallId: string | undefined
+}) {
+  return (
+    <div className={css.toolGroup}>
+      {results.map((node) => (
+        <CallRow
+          key={node.callId}
+          registry={registry}
+          sessionId={sessionId}
+          useSession={useSession}
+          t={t}
+          callId={node.callId}
+          toolName={node.call?.name ?? ''}
+          block={node}
+          seq={node.seq}
+          onOpenDetails={onOpenDetails}
+          selected={node.callId === selectedCallId}
+        />
+      ))}
+    </div>
+  )
+})
+
+/** The streaming partial, isolated so chunk batches re-render only this tail.
+ *  onGrow lets the scroll owner follow content the parent never re-renders for. */
+function StreamingTail({ useSession, onGrow }: {
+  useSession: UseConversation
+  onGrow: () => void
+}) {
+  const partial = useSession((s) => s.partial)
+  useLayoutEffect(() => {
+    onGrow()
+  })
+  if (partial === null) return null
+  return <AssistantMarkdown blocks={partial.blocks} streaming />
+}
+
+/**
+ * Build the chat view component over plugin deps.
+ * @param deps - toolview registry and bound translator.
+ * @returns the ConvViewProps component registered as the chat view.
+ */
+export function createChatView(deps: ChatViewDeps): FC<ConvViewProps> {
+  const { toolviews, t } = deps
+
+  return function ChatView({ sessionId, useSession: useSessionWide, useSelection, actions }: ConvViewProps) {
+    const useSession = useSessionWide as UseConversation
+    const nodes = useSession((s) => s.nodes)
+    const runningCalls = useSession((s) => s.runningCalls)
+    const pending = useSession((s) => s.pending)
+    const openState = useSession((s) => s.openState)
+    const openErrorMessage = useSession((s) => s.openError === null ? null : `${s.openError.message}（${s.openError.code}）`)
+    const hasMore = useSession((s) => s.hasMore)
+    const loadingOlder = useSession((s) => s.loadingOlder)
+    const selectedCallId = useSelection((sel) => sel?.callId)
+
+    const items = useMemo(() => deriveChatFlow(nodes), [nodes])
+
+    const listRef = useRef<HTMLDivElement | null>(null)
+    const atBottomRef = useRef(true)
+    const [atBottom, setAtBottom] = useState(true)
+    /** Paging anchor: height/position at click, compensated after the prepend lands. */
+    const anchorRef = useRef<{ h: number; t: number } | null>(null)
+    const firstSeqRef = useRef<number | null>(null)
+    const openedRef = useRef(false)
+    const lastKeyRef = useRef<string | null>(null)
+
+    const firstSeq = nodes[0]?.seq ?? null
+    const lastItem = items[items.length - 1]
+
+    const toBottom = (el: HTMLDivElement): void => {
+      el.scrollTop = el.scrollHeight
+      atBottomRef.current = true
+      setAtBottom(true)
+    }
+
+    useLayoutEffect(() => {
+      const el = listRef.current
+      /* v8 ignore next -- ref-null guard: React attaches the ref before layout effects run. */
+      if (el === null) return
+      // Open completed: jump to the bottom once.
+      if (openState === 'open' && !openedRef.current) {
+        openedRef.current = true
+        toBottom(el)
+        firstSeqRef.current = firstSeq
+        lastKeyRef.current = lastItem?.key ?? null
+        return
+      }
+      // Prepend (head seq decreased): compensate by the height delta.
+      if (anchorRef.current !== null && firstSeq !== null && firstSeqRef.current !== null && firstSeq < firstSeqRef.current) {
+        el.scrollTop = anchorRef.current.t + (el.scrollHeight - anchorRef.current.h)
+        anchorRef.current = null
+        firstSeqRef.current = firstSeq
+        /* v8 ignore next -- ?? arm: a prepend adds nodes, so the flow list here is never empty. */
+        lastKeyRef.current = lastItem?.key ?? null
+        return
+      }
+      firstSeqRef.current = firstSeq
+      // Own words must be visible: a new trailing user node force-scrolls
+      // (send lives in the composer, so arrival is detected here, not armed there).
+      const lastKey = lastItem?.key ?? null
+      const appendedUser = lastKey !== lastKeyRef.current
+        && lastItem !== undefined && lastItem.kind === 'node' && lastItem.node.kind === 'user'
+      lastKeyRef.current = lastKey
+      if (appendedUser || atBottomRef.current) toBottom(el)
+    })
+
+    const onScroll = (): void => {
+      const el = listRef.current
+      /* v8 ignore next -- ref-null guard: the handler only fires on the mounted element. */
+      if (el === null) return
+      const isAtBottom = el.scrollHeight - el.scrollTop - el.clientHeight <= FOLLOW_THRESHOLD + 1
+      atBottomRef.current = isAtBottom
+      setAtBottom(isAtBottom)
+    }
+
+    // Follow streaming growth the parent never re-renders for (stable ref).
+    // The ref starts null and is assigned every render, so the placeholder
+    // initializer a function initial value would need never exists.
+    const followRef = useRef<(() => void) | null>(null)
+    followRef.current = () => {
+      const el = listRef.current
+      if (el !== null && atBottomRef.current) el.scrollTop = el.scrollHeight
+    }
+    const onGrow = useRef(() => followRef.current?.()).current
+
+    const loadOlder = (): void => {
+      const el = listRef.current
+      /* v8 ignore next -- ref-null guard: the paging button renders inside the list tree. */
+      if (el !== null) anchorRef.current = { h: el.scrollHeight, t: el.scrollTop }
+      actions.loadOlder()
+    }
+
+    const renderItem = (item: ChatFlowItem): ReactNode => {
+      if (item.kind === 'tool-group') {
+        const inGroup = selectedCallId !== undefined
+          && item.results.some((r) => r.callId === selectedCallId)
+        return (
+          <ToolGroup
+            key={item.key}
+            registry={toolviews}
+            sessionId={sessionId}
+            useSession={useSession}
+            t={t}
+            results={item.results}
+            onOpenDetails={actions.openDetails}
+            selectedCallId={inGroup ? selectedCallId : undefined}
+          />
+        )
+      }
+      const node: ConversationNode = item.node
+      if (node.kind === 'assistant') {
+        return <AssistantMarkdown key={item.key} blocks={node.blocks} streaming={false} interrupted={node.interrupted} />
+      }
+      /* v8 ignore next -- tool-result never reaches here: deriveChatFlow folds them into groups. */
+      if (node.kind === 'tool-result') return null
+      return <MessageItem key={item.key} node={node} />
+    }
+
+    return (
+      <div className={css.root}>
+        <div ref={listRef} className={css.scroll} onScroll={onScroll}>
+          <div className={css.column}>
+          {openState === 'loading' && <div className={css.hint}>载入历史…</div>}
+          {openState === 'error' && <div className={css.openError}>历史加载失败：{openErrorMessage}</div>}
+          {hasMore && (
+            <div className={css.older}>
+              <button type="button" disabled={loadingOlder} onClick={loadOlder}>
+                {loadingOlder ? '加载中…' : '加载更早'}
+              </button>
+            </div>
+          )}
+          {items.map(renderItem)}
+          <StreamingTail useSession={useSession} onGrow={onGrow} />
+          {runningCalls.length > 0 && (
+            <div className={css.toolGroup}>
+              {runningCalls.map((call) => (
+                <CallRow
+                  key={call.callId}
+                  registry={toolviews}
+                  sessionId={sessionId}
+                  useSession={useSession}
+                  t={t}
+                  callId={call.callId}
+                  toolName={call.name}
+                  block={call}
+                  seq={call.turn}
+                  onOpenDetails={actions.openDetails}
+                  selected={call.callId === selectedCallId}
+                />
+              ))}
+            </div>
+          )}
+          {pending.map((item) => <PendingCard key={item.rpcId} item={item} />)}
+          </div>
+        </div>
+        {!atBottom && (
+          <button
+            type="button"
+            className={css.toBottom}
+            aria-label="回到底部"
+            onClick={() => {
+              const el = listRef.current
+              /* v8 ignore next -- ref-null guard: the button only renders alongside the mounted list. */
+              if (el !== null) toBottom(el)
+            }}
+          >
+            <IconChevronDownOutline14 />
+          </button>
+        )}
+      </div>
+    )
+  }
+}
diff --git a/packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx b/packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx
new file mode 100644
index 0000000000..32793fb804
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx
@@ -0,0 +1,36 @@
+// GenericToolCard: the registry-miss fallback toolview — classifies the tool
+// into one of the five figma row variants and renders the summary row. Also
+// the shared base the bash sample builds on: any ToolViewProps consumer.
+
+import type { ReactNode } from 'react'
+import {
+  IconApiOutline14, IconBrowseOutline16, IconSearchOutline16, IconThinkOutline14,
+} from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ToolViewProps } from '../contract/toolview.ts'
+import { toolRowModel, type ToolCallBlock, type ToolRowVariant } from '../contract/tool-call-model.ts'
+import { ToolRow } from './ToolRow.tsx'
+import { IconSparkle16 } from './IconSparkle16.tsx'
+
+/** Variant leading icons (figma table). */
+const VARIANT_ICONS: Record<ToolRowVariant, ReactNode> = {
+  think: <IconThinkOutline14 />,
+  search: <IconSearchOutline16 />,
+  read: <IconBrowseOutline16 />,
+  bash: <IconApiOutline14 size={16} />,
+  others: <IconSparkle16 />,
+}
+
+export function GenericToolCard({ toolName, block, actions }: ToolViewProps) {
+  const model = toolRowModel(toolName, block as ToolCallBlock)
+  return (
+    <ToolRow
+      variant={model.variant}
+      icon={VARIANT_ICONS[model.variant]}
+      title={model.title}
+      summary={model.summary}
+      body={model.body}
+      state={model.state}
+      onOpenDetails={actions.openDetails}
+    />
+  )
+}
diff --git a/packages/client/ui-conversation/src/client/chat/IconSparkle16.tsx b/packages/client/ui-conversation/src/client/chat/IconSparkle16.tsx
new file mode 100644
index 0000000000..61331ba616
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/IconSparkle16.tsx
@@ -0,0 +1,15 @@
+// Local sparkle icon for the Others tool-row variant (figma 43:31850 leading
+// glyph is an SF Symbols "sparkles" text glyph — not extractable as vector
+// data, so this is a hand-authored three-star approximation). Lives here
+// rather than ui-primitives until the exact glyph is exported and adopted
+// into the ic_ds_* family.
+
+export function IconSparkle16({ size = 16, className }: { size?: number; className?: string }) {
+  return (
+    <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+      <path d="M6.1 3.1Q6.6 7.8 11.3 8.3Q6.6 8.8 6.1 13.5Q5.6 8.8 0.9 8.3Q5.6 7.8 6.1 3.1Z" fill="currentColor" />
+      <path d="M11.9 1Q12.2 3.7 14.9 4Q12.2 4.3 11.9 7Q11.6 4.3 8.9 4Q11.6 3.7 11.9 1Z" fill="currentColor" />
+      <path d="M12.5 9.4Q12.7 11.4 14.7 11.6Q12.7 11.8 12.5 13.8Q12.3 11.8 10.3 11.6Q12.3 11.4 12.5 9.4Z" fill="currentColor" />
+    </svg>
+  )
+}
diff --git a/packages/client/ui-conversation/src/client/chat/MessageItem.module.css b/packages/client/ui-conversation/src/client/chat/MessageItem.module.css
new file mode 100644
index 0000000000..50e560278d
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/MessageItem.module.css
@@ -0,0 +1,34 @@
+/* User bubble: right-aligned, figma r22 fill = the bubble specific token
+   (#EDF3FE light / dark pair rides the token sheet). */
+
+/* Block spacing is the flow column's gap alone — no extra padding here. */
+.userRow {
+  display: flex;
+  justify-content: flex-end;
+}
+
+.bubble {
+  /* 525px cap inside the 736 column; percentage keeps narrow windows sane. */
+  max-width: min(525px, 82%);
+  background: var(--dsw-specific-bubble);
+  border-radius: 22px;
+  /* 44px single-line bubble: 24 line + 10 vertical padding each side. */
+  padding: 10px 16px;
+  font-size: 16px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-primary);
+}
+
+.badge {
+  display: inline-block;
+  margin-bottom: 4px;
+  padding: 1px 6px;
+  border-radius: 6px;
+  background: var(--dsw-alias-state-warn-primary);
+  color: var(--dsw-alias-label-primary-foreground);
+  font-size: 11px;
+}
+
+.contextRow {
+  padding: 2px 0;
+}
diff --git a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
new file mode 100644
index 0000000000..4bfe07d687
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
@@ -0,0 +1,56 @@
+// MessageItem: the four simple node kinds — user bubble (right-aligned),
+// steering (badged bubble), context injection and unknown-surface JSON rows.
+// Props are frozen node slices off the snapshot cache; memo holds across
+// streaming because unchanged nodes keep their references.
+
+import { memo } from 'react'
+import type {
+  ContextMessageNode, SteeringMessageNode, UnknownSurfaceNode, UserMessageNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { JsonBlock, MessageText } from '@deepseek-ai/dsh-client-ui-primitives'
+import css from './MessageItem.module.css'
+
+export interface MessageItemProps {
+  node: UserMessageNode | SteeringMessageNode | ContextMessageNode | UnknownSurfaceNode
+}
+
+function contentText(content: readonly unknown[]): { text: string; rest: unknown[] } {
+  const texts: string[] = []
+  const rest: unknown[] = []
+  for (const block of content) {
+    const b = block as { type?: string; text?: string }
+    if (b.type === 'text' && typeof b.text === 'string') texts.push(b.text)
+    else rest.push(block)
+  }
+  return { text: texts.join(''), rest }
+}
+
+export const MessageItem = memo(function MessageItem({ node }: MessageItemProps) {
+  switch (node.kind) {
+    case 'user':
+    case 'steering': {
+      const { text, rest } = contentText(node.content)
+      return (
+        <div className={css.userRow}>
+          <div className={css.bubble}>
+            {node.kind === 'steering' && <span className={css.badge}>插话</span>}
+            <MessageText text={text} />
+            {rest.map((block, i) => <JsonBlock key={i} label="附加内容块" payload={block} />)}
+          </div>
+        </div>
+      )
+    }
+    case 'context':
+      return (
+        <div className={css.contextRow}>
+          <JsonBlock label="上下文注入" payload={{ content: node.content, meta: node.meta }} />
+        </div>
+      )
+    default:
+      return (
+        <div className={css.contextRow}>
+          <JsonBlock label={`未知 surface 事件：${node.type}`} payload={node.data} />
+        </div>
+      )
+  }
+})
diff --git a/packages/client/ui-conversation/src/client/chat/PendingCard.module.css b/packages/client/ui-conversation/src/client/chat/PendingCard.module.css
new file mode 100644
index 0000000000..2318c88c94
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/PendingCard.module.css
@@ -0,0 +1,31 @@
+/* Amber pending strip (approval waiting = warn semantic, figma state colors). */
+
+.card {
+  margin: 6px 0;
+  padding: 8px 12px;
+  border: 1px solid var(--dsw-alias-state-warn-secondary);
+  border-radius: 10px;
+  background: var(--dsw-alias-state-warn-tertiary);
+}
+
+.title {
+  font-size: 12px;
+  font-weight: 500;
+  color: var(--dsw-alias-label-primary);
+}
+
+.mono {
+  font-family: var(--ds-font-family-code);
+}
+
+.reason {
+  margin-top: 4px;
+  font-size: 12px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.hint {
+  margin-top: 6px;
+  font-size: 11px;
+  color: var(--dsw-alias-label-tertiary);
+}
diff --git a/packages/client/ui-conversation/src/client/chat/PendingCard.tsx b/packages/client/ui-conversation/src/client/chat/PendingCard.tsx
new file mode 100644
index 0000000000..56b886c9ad
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/PendingCard.tsx
@@ -0,0 +1,31 @@
+// PendingCard: approval/question placeholder card (visible, not answerable —
+// the composer-takeover approval panel is a P-II item; wire pending semantics
+// already exist so the flow must show them).
+
+import { memo } from 'react'
+import type { PendingInteraction } from '@deepseek-ai/dsh-client-runtime/client'
+import { JsonBlock } from '@deepseek-ai/dsh-client-ui-primitives'
+import css from './PendingCard.module.css'
+
+export interface PendingCardProps {
+  item: PendingInteraction
+}
+
+export const PendingCard = memo(function PendingCard({ item }: PendingCardProps) {
+  return (
+    <div className={css.card}>
+      {item.kind === 'approval' ? (
+        <>
+          <div className={css.title}>等待审批：<span className={css.mono}>{item.toolName}</span></div>
+          {item.reason !== undefined && <div className={css.reason}>{item.reason}</div>}
+        </>
+      ) : (
+        <>
+          <div className={css.title}>等待回答（{item.questions.length} 题）</div>
+          <JsonBlock label="问题内容" payload={item.questions} />
+        </>
+      )}
+      <div className={css.hint}>请在原客户端处理（web 端作答后续里程碑提供）</div>
+    </div>
+  )
+})
diff --git a/packages/client/ui-conversation/src/client/chat/StatsLine.module.css b/packages/client/ui-conversation/src/client/chat/StatsLine.module.css
new file mode 100644
index 0000000000..d8ea74bbf3
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/StatsLine.module.css
@@ -0,0 +1,13 @@
+/* Session stats row: 12/20 tertiary text under the flow, aligned to the
+   736px message column axis. */
+
+.root {
+  max-width: 736px;
+  width: 100%;
+  margin: 0 auto;
+  box-sizing: border-box;
+  padding: 4px 24px 8px;
+  font-size: 12px;
+  line-height: 20px;
+  color: var(--dsw-alias-label-tertiary);
+}
diff --git a/packages/client/ui-conversation/src/client/chat/StatsLine.tsx b/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
new file mode 100644
index 0000000000..78f036aecf
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
@@ -0,0 +1,68 @@
+// StatsLine: the session stats row (figma 122:11212 "cache hit 92% · 1,284
+// tokens · 45.2s · 5 turns · 32 steps"), mounted as the chat view's
+// chrome.footer — the first chrome-attachment consumer. Duration has no data
+// source in P-I (ledger). Subscribes to `nodes` only: chunk batches never swap
+// that reference, so the row renders zero times during streaming (the RFC
+// performance model's acceptance row).
+
+import { memo, useMemo } from 'react'
+import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
+import type { ChromeProps } from '../contract/views.ts'
+import css from './StatsLine.module.css'
+
+interface UsageTotals {
+  turns: number
+  steps: number
+  tokens: number
+  cacheHitPct: number | null
+}
+
+/** Token accounting slice of assistant `usage` (typed upstream as unknown). */
+interface UsageLike {
+  inputTokens?: number
+  outputTokens?: number
+  cacheReadTokens?: number
+}
+
+/**
+ * Fold assistant nodes into display totals.
+ * @param nodes - snapshot nodes.
+ * @returns totals; cacheHitPct null until any cache accounting arrives.
+ */
+export function deriveStats(nodes: ConversationSnapshot['nodes']): UsageTotals {
+  const turns = new Set<number>()
+  let steps = 0
+  let tokens = 0
+  let input = 0
+  let cacheRead = 0
+  for (const node of nodes) {
+    if (node.kind !== 'assistant') continue
+    turns.add(node.turn)
+    steps += 1
+    const usage = node.usage as UsageLike | undefined
+    if (usage === undefined) continue
+    input += usage.inputTokens ?? 0
+    cacheRead += usage.cacheReadTokens ?? 0
+    tokens += (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0) + (usage.cacheReadTokens ?? 0)
+  }
+  const denom = input + cacheRead
+  return {
+    turns: turns.size,
+    steps,
+    tokens,
+    cacheHitPct: denom === 0 ? null : Math.round((cacheRead / denom) * 100),
+  }
+}
+
+export const StatsLine = memo(function StatsLine({ useSession }: ChromeProps) {
+  const nodes = (useSession as SnapshotSelectorHook<ConversationSnapshot>)((s) => s.nodes)
+  const stats = useMemo(() => deriveStats(nodes), [nodes])
+  if (stats.steps === 0) return null
+  const parts: string[] = []
+  if (stats.cacheHitPct !== null) parts.push(`cache hit ${stats.cacheHitPct}%`)
+  parts.push(`${stats.tokens.toLocaleString('en-US')} tokens`)
+  parts.push(`${stats.turns} turns`)
+  parts.push(`${stats.steps} steps`)
+  return <div className={css.root}>{parts.join(' · ')}</div>
+})
diff --git a/packages/client/ui-conversation/src/client/chat/ToolRow.module.css b/packages/client/ui-conversation/src/client/chat/ToolRow.module.css
new file mode 100644
index 0000000000..c82c9cce20
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/ToolRow.module.css
@@ -0,0 +1,88 @@
+/* Tool summary row (figma 122:9479): 24px single line —
+   [16 leading] gap6 [title 14/24] gap8 [2x2 dot] gap8 [summary FILL truncate]. */
+
+.root {
+  display: flex;
+  flex-direction: column;
+}
+
+.row {
+  display: flex;
+  align-items: center;
+  height: 24px;
+  min-width: 0;
+}
+
+.row[data-clickable] {
+  cursor: pointer;
+  border-radius: 6px;
+}
+
+.row[data-clickable]:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.leading {
+  flex: none;
+  width: 16px;
+  height: 16px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  margin-right: 6px;
+  padding: 0;
+  border: none;
+  background: none;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+/* The others-variant sparkle glyph is one gray step darker than the icon
+   family in the source design. */
+.root[data-variant='others'] .leading {
+  color: var(--dsw-alias-label-secondary);
+}
+
+button.leading {
+  cursor: pointer;
+}
+
+.chevron {
+  color: var(--dsw-alias-label-secondary);
+}
+
+.title {
+  flex: none;
+  font-size: 14px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-primary-dimmed);
+}
+
+.sep {
+  flex: none;
+  width: 2px;
+  height: 2px;
+  border-radius: 1px;
+  margin: 0 8px;
+  background: var(--dsw-alias-label-caption);
+}
+
+.summary {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 14px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+/* Expanded body: pad-left 22 indented gray text, no border, no fill. */
+.body {
+  padding: 4px 0 4px 22px;
+  font-size: 14px;
+  line-height: 24px;
+  white-space: pre-wrap;
+  word-break: break-word;
+  color: var(--dsw-alias-label-tertiary);
+}
diff --git a/packages/client/ui-conversation/src/client/chat/ToolRow.tsx b/packages/client/ui-conversation/src/client/chat/ToolRow.tsx
new file mode 100644
index 0000000000..0bb92e9f66
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/ToolRow.tsx
@@ -0,0 +1,75 @@
+// ToolRow: the single-line tool summary row (figma component set 122:9479) —
+// 16px leading slot (state dot / tool icon, chevron when expanded) + title +
+// separator dot + FILL-truncated summary. Expanded body is indented gray text;
+// no inline output (full results live in the details panel). Expand state is
+// component-local view state; row click hands the selection off to the owner.
+
+import { useState, type ReactNode } from 'react'
+import clsx from 'clsx'
+import { StateDot } from '@deepseek-ai/dsh-client-ui-primitives'
+import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ToolRowState, ToolRowVariant } from '../contract/tool-call-model.ts'
+import css from './ToolRow.module.css'
+
+export interface ToolRowProps {
+  variant: ToolRowVariant
+  /** Leading 16px tool icon, shown while collapsed and not running/failed. */
+  icon: ReactNode
+  title: string
+  summary: string
+  /** Expanded-body text; null = not expandable (leading slot never toggles). */
+  body: string | null
+  state: ToolRowState
+  /** Selection handoff (row click), already bound to this call by the owner. */
+  onOpenDetails?: (() => void) | undefined
+}
+
+/** Leading-slot state substitution: the tool icon yields to the state semantic
+ *  (running = blue ring, error = red, interrupted = amber halo; ok = icon). */
+function leadingFor(state: ToolRowState, icon: ReactNode): ReactNode {
+  switch (state) {
+    case 'running': return <StateDot state="ongoing" />
+    case 'error': return <StateDot state="error" />
+    case 'stopped': return <StateDot state="warning" />
+    default: return icon
+  }
+}
+
+export function ToolRow({ variant, icon, title, summary, body, state, onOpenDetails }: ToolRowProps) {
+  const [expanded, setExpanded] = useState(false)
+  const expandable = body !== null
+  const open = expanded && expandable
+  return (
+    <div className={css.root} data-variant={variant} data-state={state}>
+      <div
+        className={css.row}
+        data-clickable={onOpenDetails !== undefined || undefined}
+        onClick={onOpenDetails}
+      >
+        {expandable ? (
+          <button
+            type="button"
+            className={css.leading}
+            aria-expanded={open}
+            onClick={(e) => {
+              e.stopPropagation()
+              setExpanded((v) => !v)
+            }}
+          >
+            {open ? <IconChevronDownOutline14 className={clsx(css.chevron)} /> : leadingFor(state, icon)}
+          </button>
+        ) : (
+          <span className={css.leading}>{leadingFor(state, icon)}</span>
+        )}
+        <span className={css.title}>{title}</span>
+        {!open && (
+          <>
+            <span className={css.sep} aria-hidden />
+            <span className={css.summary}>{summary}</span>
+          </>
+        )}
+      </div>
+      {open && <div className={css.body}>{body}</div>}
+    </div>
+  )
+}
diff --git a/packages/client/ui-conversation/src/client/chat/ToolViewOutlet.tsx b/packages/client/ui-conversation/src/client/chat/ToolViewOutlet.tsx
new file mode 100644
index 0000000000..7fa8b5702e
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/ToolViewOutlet.tsx
@@ -0,0 +1,89 @@
+// ToolViewOutlet: resolves the toolview for one call through ctx.toolviews
+// (uSES over the registry version so unload falls back live) and renders it
+// behind a per-row error boundary. GenericToolCard is the render-side
+// fallback for both a registry miss and a crashed custom row. A registrant
+// inject factory is called once per (registration x binding) and cached,
+// mirroring the scoped-slots injection discipline.
+
+import { Component, useSyncExternalStore, type FC, type ReactNode } from 'react'
+import { useSessionBinding } from '@deepseek-ai/dsh-client-web-react'
+import type { SessionBinding } from '@deepseek-ai/dsh-client-ui-slots'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ToolViewInject, ToolViewProps, ToolViewResolver } from '../contract/toolview.ts'
+import { GenericToolCard } from './GenericToolCard.tsx'
+
+export interface ToolViewOutletProps {
+  registry: ToolViewResolver
+  sessionId: SessionId
+  toolName: string
+  viewProps: ToolViewProps
+}
+
+/** Inject cache: per inject-factory (stable per registration) x binding object. */
+const injectCache = new WeakMap<ToolViewInject<object>, WeakMap<object, object>>()
+
+function cachedInject(inject: ToolViewInject<object>, binding: SessionBinding): object {
+  let perBinding = injectCache.get(inject)
+  if (!perBinding) {
+    perBinding = new WeakMap()
+    injectCache.set(inject, perBinding)
+  }
+  let props = perBinding.get(binding)
+  if (!props) {
+    props = inject(binding)
+    perBinding.set(binding, props)
+  }
+  return props
+}
+
+class RowErrorBoundary extends Component<
+  { resetKey: unknown; fallback: ReactNode; children: ReactNode }, { failed: boolean }
+> {
+  override state = { failed: false }
+  // Fallback state MUST flip here (render phase): a boundary whose derived
+  // state does not change re-renders the crashing children and React gives
+  // up after the second throw, escalating past the boundary.
+  static getDerivedStateFromError(): { failed: boolean } {
+    return { failed: true }
+  }
+  override componentDidCatch(error: unknown): void {
+    console.error('toolview row crashed:', error)
+  }
+  // A re-registration (resetKey bump) retries the custom row.
+  override componentDidUpdate(prev: { resetKey: unknown }): void {
+    if (this.state.failed && prev.resetKey !== this.props.resetKey) {
+      this.setState({ failed: false })
+    }
+  }
+  override render(): ReactNode {
+    if (this.state.failed) return this.props.fallback
+    return this.props.children
+  }
+}
+
+/** Split component: only inject-carrying registrations need the session
+ *  binding hook (keeps injectless rendering free of the Provider requirement). */
+function InjectedRow({ Row, inject, viewProps }: {
+  Row: FC<ToolViewProps & object>; inject: ToolViewInject<object>; viewProps: ToolViewProps
+}) {
+  const binding = useSessionBinding()
+  const injected = cachedInject(inject, binding)
+  return <Row {...{ ...injected, ...viewProps }} />
+}
+
+export function ToolViewOutlet({ registry, sessionId, toolName, viewProps }: ToolViewOutletProps) {
+  const version = useSyncExternalStore(
+    (fn) => registry.subscribe(fn),
+    () => registry.getVersion(),
+  )
+  const resolved = registry.resolve(toolName, sessionId)
+  if (resolved === undefined) return <GenericToolCard {...viewProps} />
+  const Row = resolved.component
+  return (
+    <RowErrorBoundary resetKey={version} fallback={<GenericToolCard {...viewProps} />}>
+      {resolved.inject === undefined
+        ? <Row {...viewProps} />
+        : <InjectedRow Row={Row} inject={resolved.inject} viewProps={viewProps} />}
+    </RowErrorBoundary>
+  )
+}
diff --git a/packages/client/ui-conversation/src/client/chat/chat-flow.ts b/packages/client/ui-conversation/src/client/chat/chat-flow.ts
new file mode 100644
index 0000000000..8f47e334c5
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/chat-flow.ts
@@ -0,0 +1,46 @@
+/**
+ * Chat flow derivation: ConversationSnapshot nodes -> render items. Tool
+ * results group into consecutive-run tool groups (figma step-summary flow,
+ * VERTICAL gap10) alternating with narration; everything else passes through.
+ * Item identity keys are stable across snapshots so the list parent can
+ * subscribe to keys only while rows subscribe to content.
+ */
+import type { ConversationNode, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+
+/** One renderable flow item; key is the React key and the parent's identity unit. */
+export type ChatFlowItem =
+  | { kind: 'node'; key: string; node: ConversationNode }
+  | { kind: 'tool-group'; key: string; results: readonly ToolResultNode[] }
+
+/**
+ * Group finalized nodes into the step-summary flow.
+ * @param nodes - snapshot nodes (surface order).
+ * @returns flow items; consecutive tool-results merged into one group keyed by the first seq.
+ */
+export function deriveChatFlow(nodes: readonly ConversationNode[]): ChatFlowItem[] {
+  const items: ChatFlowItem[] = []
+  let group: ToolResultNode[] | null = null
+  for (const node of nodes) {
+    if (node.kind === 'tool-result') {
+      if (group === null) {
+        group = [node]
+        items.push({ kind: 'tool-group', key: `g${node.seq}`, results: group })
+      } else {
+        group.push(node)
+      }
+    } else {
+      group = null
+      items.push({ kind: 'node', key: `n${node.seq}`, node })
+    }
+  }
+  return items
+}
+
+/**
+ * Key projection for the list parent's selector (content-blind identity).
+ * @param items - derived flow items.
+ * @returns joined key string usable with Object.is short-circuiting.
+ */
+export function flowKeys(items: readonly ChatFlowItem[]): string {
+  return items.map(i => i.key).join('|')
+}
diff --git a/packages/client/ui-conversation/src/client/chat/register.ts b/packages/client/ui-conversation/src/client/chat/register.ts
new file mode 100644
index 0000000000..b417ab4c0b
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/register.ts
@@ -0,0 +1,52 @@
+/**
+ * Chat-side registration entry, called from the plugin apply (the assembly
+ * point): registers the chat view with the stats-line footer chrome. The
+ * chat domain touches the tool ring only through the contract resolver face;
+ * bash sample registration moved to apply (cross-domain assembly).
+ */
+import type { SessionId, SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ConversationService } from '../service.ts'
+import type { Translate } from '../contract/views.ts'
+import type { ToolViewResolver } from '../contract/toolview.ts'
+import { createChatView } from './ChatView.tsx'
+import { StatsLine } from './StatsLine.tsx'
+
+/** Read face of the sessions list store (subscription not needed: the filter
+ *  reads the latest snapshot at each resolve). */
+export interface SessionListReader { getSnapshot(): SessionListState }
+
+/**
+ * Default scoped-sample filter: the sub-session family. Sub-agent rows
+ * rendering differently is the registry's canonical product scenario, and
+ * forking gives W5 acceptance a real entry point to observe the differential.
+ * @param list - injected sessions list read face.
+ * @returns filter matching sessions with a parent.
+ */
+export function childSessionScope(list: SessionListReader): (sessionId: SessionId) => boolean {
+  return sessionId => list.getSnapshot().byId[sessionId]?.parentId !== undefined
+}
+
+/** Assembly inputs for {@link registerChat} (resolved by apply, not here). */
+export interface RegisterChatDeps {
+  conversation: ConversationService
+  /** Toolview read face consumed by the chat rows' outlet. */
+  toolviews: ToolViewResolver
+  /** Translator bound to the conversation namespace. */
+  t: Translate
+}
+
+/**
+ * Register the chat view (footer chrome included).
+ * @param deps - assembled service instances.
+ * @returns disposer removing the registration.
+ */
+export function registerChat(deps: RegisterChatDeps): () => void {
+  const { conversation, toolviews, t } = deps
+  return conversation.registerView({
+    id: 'chat',
+    label: 'Chat',
+    order: 0,
+    component: createChatView({ toolviews, t }),
+    chrome: { footer: StatsLine },
+  })
+}
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
new file mode 100644
index 0000000000..276ae1ec30
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -0,0 +1,63 @@
+/**
+ * Slot-ring contract for the conversation package: the composed props shapes
+ * its registrants mount into the layout-owned slots (conversation / details /
+ * conversation.empty — the SlotMap declarations live with ui-layout, the
+ * slot owner). Per the share-ownership rule, the owner share is REFERENCED
+ * from ui-layout and each registrant's injected share is declared here, next
+ * to the component that receives it; full component props = owner share &
+ * standard share & own injected share.
+ */
+import type { ReactNode } from 'react'
+import type { SessionId, SessionSummary } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SnapshotSelectorHook, UseSession } from '@deepseek-ai/dsh-client-web-react'
+import type { ConvOwnerProps, DetailsOwnerProps, EmptyOwnerProps } from '@deepseek-ai/dsh-client-ui-layout/client'
+import type { SelectionTarget, ViewEntry, ViewId } from './views.ts'
+
+/** Injected share of the conversation slot (assembled by apply's inject factory). */
+export interface ConversationInjected {
+  /** Breadcrumb chain (root ancestor first, self last; ancestry(list) feed). */
+  useAncestry: () => readonly SessionSummary[]
+  /** View registry read face (uSES triple from the conversation service). */
+  views: {
+    list(): readonly ViewEntry[]
+    subscribe(fn: () => void): () => void
+    version(): number
+  }
+  /** Active view accessor (layout.viewFor backed; undefined falls to 'chat'). */
+  useActiveView: () => ViewId | undefined
+  /** Composer surface: draft store hook pair + send/stop choreography. */
+  composer: {
+    useDraft: () => string
+    setDraft(text: string): void
+    send(mode: 'queue' | 'steer'): void
+    stop(): void
+  }
+  actions: {
+    openView(view: ViewId): void
+    open(id: SessionId): void
+  }
+  /** Renders the active view's body (the owner closes over ConvViewProps assembly). */
+  renderView: (entry: ViewEntry) => ReactNode
+}
+
+/** Full conversation-slot component props: owner share & standard share & injected share. */
+export type ConversationSlotProps = ConvOwnerProps & { useSession: UseSession } & ConversationInjected
+
+/** Injected share of the details slot. */
+export interface DetailsInjected {
+  useSelection: SnapshotSelectorHook<SelectionTarget | null>
+  actions: { closeDetails(): void }
+}
+
+/** Full details-slot component props. */
+export type DetailsSlotProps = DetailsOwnerProps & { useSession: UseSession } & DetailsInjected
+
+/** Injected share of the no-session empty-state slot (root slot: no standard share). */
+export interface EmptyStateInjected {
+  /** cwd options derived from sessions.list (deduped; assembled by the inject factory). */
+  useCwds: SnapshotSelectorHook<readonly string[]>
+  actions: { startSession(opts: { cwd?: string; text: string; mode: 'queue' | 'steer' }): Promise<void> }
+}
+
+/** Full empty-state component props. */
+export type EmptyStateSlotProps = EmptyOwnerProps & EmptyStateInjected
diff --git a/packages/client/ui-conversation/src/client/contract/tool-call-model.ts b/packages/client/ui-conversation/src/client/contract/tool-call-model.ts
new file mode 100644
index 0000000000..0c3e100ec8
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/contract/tool-call-model.ts
@@ -0,0 +1,126 @@
+/**
+ * Pure row-model derivation for tool summary rows: variant classification,
+ * one-line summary and expanded-body text from the frozen call slice. No
+ * inline output ever — full results live in the details panel.
+ */
+import type { ToolCallBlock } from './toolview.ts'
+
+export type { ToolCallBlock } from './toolview.ts'
+
+/** The frozen slice the chat view hands to toolview components as `block`
+ *  (both members are cache-stable references off ConversationSnapshot). */
+
+/** The five figma row variants (think is fed by reasoning blocks, not tool calls). */
+export type ToolRowVariant = 'think' | 'search' | 'read' | 'bash' | 'others'
+
+/** Row state semantic; colors self-supplied via StateDot (design gives none). */
+export type ToolRowState = 'running' | 'ok' | 'error' | 'stopped'
+
+/** Figma row titles per variant (design literals, not translatable copy). */
+export const VARIANT_TITLES: Record<ToolRowVariant, string> = {
+  think: 'Think', search: 'Search', read: 'Read', bash: 'Bash', others: 'Tool call',
+}
+
+/** Known tool name -> variant; fs write/edit intentionally fall to others (no figma form). */
+const TOOL_VARIANTS: Record<string, ToolRowVariant> = {
+  bash: 'bash',
+  read: 'read',
+  web_fetch: 'read',
+  web_search: 'search',
+  grep: 'search',
+  glob: 'search',
+}
+
+/**
+ * Classify a tool name into its row variant.
+ * @param toolName - wire tool name.
+ * @returns matching variant, others when unknown.
+ */
+export function classifyTool(toolName: string): ToolRowVariant {
+  return TOOL_VARIANTS[toolName] ?? 'others'
+}
+
+/** Everything ToolRow needs, derived once from the frozen slice. */
+export interface ToolRowModel {
+  variant: ToolRowVariant
+  title: string
+  summary: string
+  /** Expanded-body text (pretty args); null = row not expandable. */
+  body: string | null
+  state: ToolRowState
+}
+
+function parseArgs(argsRaw: string): unknown {
+  try {
+    return JSON.parse(argsRaw)
+  } catch {
+    // Non-JSON args (mid-stream truncation): summary/body fall back to the raw string.
+    return undefined
+  }
+}
+
+function firstLine(text: string): string {
+  const nl = text.indexOf('\n')
+  return nl === -1 ? text : text.slice(0, nl)
+}
+
+function pickString(args: Record<string, unknown>, keys: readonly string[]): string | undefined {
+  for (const key of keys) {
+    const v = args[key]
+    if (typeof v === 'string' && v !== '') return v
+  }
+  return undefined
+}
+
+/** Summary key preference per variant (args-derived; result-derived summaries are a ledger item). */
+const SUMMARY_KEYS: Record<ToolRowVariant, readonly string[]> = {
+  bash: ['description', 'command'],
+  read: ['path', 'file_path', 'url'],
+  search: ['query', 'pattern', 'url'],
+  think: [],
+  others: [],
+}
+
+function deriveSummary(variant: ToolRowVariant, argsRaw: string): string {
+  const parsed = parseArgs(argsRaw)
+  if (typeof parsed !== 'object' || parsed === null) return firstLine(argsRaw)
+  const args = parsed as Record<string, unknown>
+  const picked = pickString(args, SUMMARY_KEYS[variant])
+  if (picked !== undefined) return firstLine(picked)
+  for (const v of Object.values(args)) {
+    if (typeof v === 'string' && v !== '') return firstLine(v)
+  }
+  return firstLine(argsRaw)
+}
+
+function deriveBody(argsRaw: string): string | null {
+  if (argsRaw === '') return null
+  const parsed = parseArgs(argsRaw)
+  return parsed === undefined ? argsRaw : JSON.stringify(parsed, null, 2)
+}
+
+/**
+ * Derive the full row model from a frozen call slice.
+ * @param toolName - wire tool name (dispatch-supplied; survives windowless results).
+ * @param block - RunningToolCall or ToolResultNode off the snapshot caches.
+ * @returns the row model.
+ */
+export function toolRowModel(toolName: string, block: ToolCallBlock): ToolRowModel {
+  const variant = classifyTool(toolName)
+  const done = 'kind' in block
+  const argsRaw = (done ? block.call?.argsRaw : block.argsRaw) ?? ''
+  const state: ToolRowState = !done ? 'running'
+    : block.error?.code === 'interrupted' ? 'stopped'
+      : block.isError ? 'error' : 'ok'
+  const base = argsRaw === '' ? block.callId : deriveSummary(variant, argsRaw)
+  // Others keeps the static "Tool call" title (figma literal); the real tool
+  // name rides the mutable summary slot so no information is lost.
+  const summary = variant === 'others' && toolName !== '' ? `${toolName} · ${base}` : base
+  return {
+    variant,
+    title: VARIANT_TITLES[variant],
+    summary,
+    body: deriveBody(argsRaw),
+    state,
+  }
+}
diff --git a/packages/client/ui-conversation/src/client/contract/toolview.ts b/packages/client/ui-conversation/src/client/contract/toolview.ts
new file mode 100644
index 0000000000..5271b7658c
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/contract/toolview.ts
@@ -0,0 +1,77 @@
+/**
+ * Tool-ring contract: the props surface handed to toolview components, the
+ * registry's resolve/registration shapes, and the tool-call block union.
+ * Shared face between the chat domain (ToolViewOutlet consumes resolve) and
+ * the toolviews domain (registry implementation + sample rows); domain
+ * implementation files import this, never each other.
+ */
+import type { FC } from 'react'
+import type { SessionBinding } from '@deepseek-ai/dsh-client-ui-slots'
+import type { UseSession } from '@deepseek-ai/dsh-client-web-react'
+import type { SessionId, ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client'
+import type { CallId, Translate } from './views.ts'
+
+// The block union's defining home is runtime (fold-product types); the
+// contract only forwards it (type-definition authority stays with the layer
+// that produces the values).
+export type { ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client'
+
+/** Props handed to registered toolview components. */
+export interface ToolViewProps {
+  callId: CallId
+  toolName: string
+  block: ToolCallBlock
+  useSession: UseSession
+  actions: { openDetails(): void }
+  t: Translate
+}
+
+/**
+ * Toolview inject factory: produces the registrant's private injected share
+ * `I`, called once per (registration x session binding) and cached by the
+ * render outlet. Session-bound by nature — tool rows always render inside a
+ * session subtree.
+ */
+export type ToolViewInject<I extends object> = (b: SessionBinding) => I
+
+/** Options accepted by the toolview registry's register; `I` is inferred from the inject factory. */
+export interface ToolViewOptions<I extends object = object> {
+  /** Session filter; absent = global registration. */
+  scope?: (sessionId: SessionId) => boolean
+  /** Private inject factory merged into the row's props by the render outlet. */
+  inject?: ToolViewInject<I>
+}
+
+/**
+ * A resolved toolview registration. `I` is erased to `object` on the resolve
+ * read face (storage erases the per-registration parameter; the outlet merges
+ * injected props untyped — the register site already proved component ⊇ I).
+ */
+export interface ResolvedToolView<I extends object = object> {
+  component: FC<ToolViewProps & I>
+  inject?: ToolViewInject<I>
+}
+
+/** The registry's read face consumed by render outlets (implementation lives in the toolviews domain). */
+export interface ToolViewResolver {
+  /**
+   * Resolve the renderer for a tool in a session. Order: scope match (later
+   * registration wins) > global > undefined (caller falls back to the
+   * generic card).
+   * @param tool - tool name.
+   * @param sessionId - session the row renders in.
+   * @returns resolved view, or undefined when nothing matches.
+   */
+  resolve(tool: string, sessionId: SessionId): ResolvedToolView | undefined
+  /**
+   * Subscribe to registration changes (synchronous).
+   * @param fn - change callback.
+   * @returns unsubscribe.
+   */
+  subscribe(fn: () => void): () => void
+  /**
+   * Monotonic version for uSES pairing.
+   * @returns current version.
+   */
+  getVersion(): number
+}
diff --git a/packages/client/ui-conversation/src/client/contract/views.ts b/packages/client/ui-conversation/src/client/contract/views.ts
new file mode 100644
index 0000000000..611cc40341
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/contract/views.ts
@@ -0,0 +1,68 @@
+/**
+ * View-ring contract: the typed conversation view table and the props
+ * surfaces handed to registered views. Shared face between the skeleton
+ * domain (ConversationRoot renders views) and the chat domain (registers the
+ * chat view); domain implementation files import this, never each other.
+ */
+import type { FC } from 'react'
+import type { ScopedSlots } from '@deepseek-ai/dsh-client-ui-slots'
+import type { SnapshotSelectorHook, UseSession } from '@deepseek-ai/dsh-client-web-react'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+
+/**
+ * One ConversationViewMap entry: per-view props extension shapes (design
+ * ledger, view ring). `chromeProps` extends {@link ChromeProps} for the
+ * view's chrome attachments; `extraProps` extends {@link ConvViewProps} for
+ * the view component itself. Both optional — the common bases stay the floor.
+ */
+export interface ViewEntryDef { chromeProps?: object; extraProps?: object }
+
+/**
+ * Typed conversation view table; ui-trajectory merges {trajectory, waterfall}.
+ * The chat entry is declared inline here (self-merge from a sibling module
+ * trips TS6305 under tsc -b).
+ */
+export interface ConversationViewMap { chat: ViewEntryDef }
+
+/** View id constrained to registered ConversationViewMap keys (all string literals; chat is declared inline). */
+export type ViewId = keyof ConversationViewMap
+
+/** Per-view chrome props: the common base plus the entry's declared extension. */
+export type ChromePropsOf<Id extends ViewId> =
+  ChromeProps & (ConversationViewMap[Id] extends { chromeProps: infer C extends object } ? C : object)
+
+/** Per-view component props: the common base plus the entry's declared extension. */
+export type ConvViewPropsOf<Id extends ViewId> =
+  ConvViewProps & (ConversationViewMap[Id] extends { extraProps: infer E extends object } ? E : object)
+
+/** Tool call identity as carried on the wire (branded upstream in connection). */
+export type CallId = string
+
+/** Translate function bound to a namespace via i18n. */
+export type Translate = (key: string, params?: Record<string, unknown>) => string
+
+/** One registered conversation view (props positions keyed by the entry's declared shapes). */
+export interface ViewEntry<Id extends ViewId = ViewId> {
+  id: Id
+  label: string
+  order?: number
+  component: FC<ConvViewPropsOf<Id>>
+  /** Per-view chrome attachments (chat mounts the stats line as footer). */
+  chrome?: { header?: FC<ChromePropsOf<Id>>; footer?: FC<ChromePropsOf<Id>> }
+}
+
+/** Props for view chrome attachments. */
+export interface ChromeProps { sessionId: SessionId; useSession: UseSession }
+
+/** Selection target for the details linkage channel (toolcall is the step special case). */
+export interface SelectionTarget { turnSeq: number; stepSeq?: number; callId?: CallId; toolName?: string }
+
+/** Props handed to registered conversation views. */
+export interface ConvViewProps {
+  sessionId: SessionId
+  useSession: UseSession
+  useSelection: SnapshotSelectorHook<SelectionTarget | null>
+  actions: { openDetails(t: SelectionTarget): void; loadOlder(): void }
+  /** Chat has no delegated sub-slots in P-I (toolviews go through the named registry). */
+  slots: ScopedSlots<never>
+}
diff --git a/packages/client/ui-conversation/src/client/index.ts b/packages/client/ui-conversation/src/client/index.ts
new file mode 100644
index 0000000000..17e9ed88a8
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/index.ts
@@ -0,0 +1,42 @@
+/**
+ * Conversation domain plugin, browser half: skeleton (header/tabs/composer),
+ * typed view registry, scope-addressed ConversationService, named toolview
+ * registry, minimal details panel. Contract: api-contracts v3 section 7.
+ * Thin shell: type surfaces live in contract/, assembly in apply.ts; the
+ * three implementation domains (skeleton/chat/toolviews) never import each
+ * other — contract/ is their only shared face.
+ */
+import type { ConversationService } from './service.ts'
+import type { ToolViewRegistry } from './toolviews/registry.ts'
+
+export { apply, inject } from './apply.ts'
+export { ConversationService } from './service.ts'
+export { ToolViewRegistry } from './toolviews/registry.ts'
+
+export type {
+  CallId, ChromeProps, ChromePropsOf, ConversationViewMap, ConvViewProps, ConvViewPropsOf,
+  SelectionTarget, Translate, ViewEntry, ViewEntryDef, ViewId,
+} from './contract/views.ts'
+export type {
+  ResolvedToolView, ToolCallBlock, ToolViewOptions, ToolViewProps, ToolViewResolver,
+} from './contract/toolview.ts'
+export type {
+  ConversationInjected, ConversationSlotProps, DetailsInjected, DetailsSlotProps,
+  EmptyStateInjected, EmptyStateSlotProps,
+} from './contract/slots.ts'
+
+export { ConversationRoot } from './skeleton/ConversationRoot.tsx'
+export type { ConversationRootProps } from './skeleton/ConversationRoot.tsx'
+export { InputBar } from './skeleton/InputBar.tsx'
+export type { InputBarError, InputBarProps } from './skeleton/InputBar.tsx'
+export { EmptyState } from './skeleton/EmptyState.tsx'
+export type { EmptyStateProps } from './skeleton/EmptyState.tsx'
+export { DetailsPanel } from './skeleton/DetailsPanel.tsx'
+export type { DetailsPanelProps } from './skeleton/DetailsPanel.tsx'
+
+declare module 'cordis' {
+  interface Context {
+    conversation: ConversationService
+    toolviews: ToolViewRegistry
+  }
+}
diff --git a/packages/client/ui-conversation/src/client/service.ts b/packages/client/ui-conversation/src/client/service.ts
new file mode 100644
index 0000000000..40aa1b93cc
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/service.ts
@@ -0,0 +1,251 @@
+/**
+ * ConversationService implementation: scope-addressed send/cancel, per-scope
+ * selection/draft stores booked on the session scope fiber, view registry
+ * with a uSES read face, openDetails orchestration, and the empty-state
+ * startSession chain. Contract: api-contracts v3 section 7.
+ *
+ * Scope addressing rides the cordis Service tracker: property access through
+ * `ctx.conversation` rebinds `this.ctx` to the caller's context, so methods
+ * read the session tag with scopeOf (same mechanism as the host tool
+ * registry). Mutable state lives in plain objects reached by one property
+ * read — field assignment through the tracker's shadow proxy is off-limits,
+ * as are `#` hard-private fields.
+ */
+import { Service } from 'cordis'
+import type { Context } from 'cordis'
+// Value import MUST use the /client subpath: only that specifier is in the
+// bundle externals (CLIENT_EXTERNALS), so it resolves to the shared runtime
+// module at load time. A bare-specifier value import gets INLINED as a second
+// module instance whose private scope-tag Symbol never matches the one
+// SessionsService tags contexts with — scopeOf then always returns undefined
+// in the browser while unit tests (single-instance path resolution) stay green.
+import { scopeOf } from '@deepseek-ai/dsh-client-runtime/client'
+import type { Session, SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import type { LayoutService } from '@deepseek-ai/dsh-client-ui-layout/client'
+import type { SelectionTarget, ViewEntry, ViewId } from './index.ts'
+
+/** Mutable view-registry cell (plain object: mutation never crosses the tracker proxy). */
+interface ViewsState {
+  entries: Map<string, ViewEntry>
+  /** Sorted projection cache; null = rebuild on next read. */
+  cache: readonly ViewEntry[] | null
+  tick: number
+  listeners: Set<() => void>
+}
+
+/** Scope-addressed conversation service (root singleton, provided as `conversation`). */
+export class ConversationService extends Service {
+  private readonly selections = new Map<SessionId, SnapshotStore<SelectionTarget | null>>()
+  private readonly draftStores = new Map<SessionId, SnapshotStore<string>>()
+  private readonly viewsState: ViewsState = {
+    entries: new Map(), cache: null, tick: 0, listeners: new Set(),
+  }
+
+  /**
+   * @param ctx - owning root context (the plugin apply context; the service
+   * registers itself and follows that fiber's lifetime).
+   */
+  constructor(ctx: Context) {
+    super(ctx, 'conversation')
+  }
+
+  /**
+   * Send a prompt into the scoped session. Business failures also land in the
+   * session snapshot's promptError (object-layer surface); the rejection here
+   * exists for caller choreography (the composer restores the draft on it).
+   * @param text - prompt text, sent verbatim as one text block.
+   * @param mode - queue after the current turn, or steer into it.
+   */
+  async send(text: string, mode: 'queue' | 'steer'): Promise<void> {
+    const session = this.scopedSession('send')
+    const result = await session.prompt([{ type: 'text', text }], mode)
+    if (!result.ok) throw new Error(`conversation.send failed: ${result.error.code}: ${result.error.message}`)
+  }
+
+  /** Cancel the scoped session's in-flight turn (failures land in promptError and reject, as in send). */
+  async cancel(): Promise<void> {
+    const session = this.scopedSession('cancel')
+    const result = await session.cancel()
+    if (!result.ok) throw new Error(`conversation.cancel failed: ${result.error.code}: ${result.error.message}`)
+  }
+
+  /** Per-scope selection channel (details linkage); root access throws. */
+  get selection(): SnapshotStore<SelectionTarget | null> {
+    return this.scopeStore(this.selections, 'selection',
+      () => createSnapshotStore<SelectionTarget | null>(null))
+  }
+
+  /**
+   * Per-scope draft store, persisted per session id; root access throws.
+   * Persistence is hand-rolled (raw string per key): the snapshot-store
+   * engine's persist middleware object-spreads state on save, corrupting
+   * primitive-state stores.
+   */
+  get drafts(): SnapshotStore<string> {
+    return this.scopeStore(this.draftStores, 'drafts', (id) => {
+      const key = `dsh.conversation.draft.${id}`
+      const store = createSnapshotStore<string>(loadDraft(key))
+      store.subscribe(() => { saveDraft(key, store.getSnapshot()) })
+      return store
+    })
+  }
+
+  /**
+   * Write the scoped selection and open the details panel. Orchestration
+   * only — panel geometry stays with ctx.layout.
+   * @param target - selection target.
+   */
+  openDetails(target: SelectionTarget): void {
+    this.selection.set(target)
+    this.requireLayout().openDetails()
+  }
+
+  /**
+   * Register a conversation view. Duplicate ids throw; the registration is an
+   * effect on the caller's fiber (plugin unload collects it).
+   * @param entry - the view entry.
+   * @returns disposer removing the view.
+   */
+  registerView<Id extends ViewId>(entry: ViewEntry<Id>): () => void {
+    const views = this.viewsState
+    const dispose = this.ctx.effect(() => {
+      if (views.entries.has(entry.id)) {
+        throw new Error(`conversation view "${entry.id}" is already registered`)
+      }
+      views.entries.set(entry.id, entry)
+      bumpViews(views)
+      return () => {
+        views.entries.delete(entry.id)
+        bumpViews(views)
+      }
+    }, 'conversation.registerView()')
+    // The effect disposer settles asynchronously; the registry face stays a
+    // synchronous fire-and-forget disposer.
+    return () => { void dispose() }
+  }
+
+  /**
+   * Registered views ordered by `order` (ties keep registration sequence).
+   * Stable array reference between mutations (uSES getSnapshot source).
+   * @returns the view entries.
+   */
+  views(): readonly ViewEntry[] {
+    const state = this.viewsState
+    state.cache ??= [...state.entries.values()].sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
+    return state.cache
+  }
+
+  /**
+   * Subscribe to view registry changes (synchronous, like the toolview registry).
+   * @param fn - change callback.
+   * @returns unsubscribe.
+   */
+  subscribeViews(fn: () => void): () => void {
+    const { listeners } = this.viewsState
+    listeners.add(fn)
+    return () => { listeners.delete(fn) }
+  }
+
+  /**
+   * Monotonic view registry version for uSES pairing.
+   * @returns current version.
+   */
+  viewsVersion(): number {
+    return this.viewsState.tick
+  }
+
+  /**
+   * Empty-state first-send chain (root-context method; does not read scope):
+   * create the session, navigate to it, then send through the new scope.
+   * The create → open ordering is safe: the manager merges the new summary
+   * synchronously before create() resolves, so the list store is projected by
+   * the time open() validates against it (manager notification batching is
+   * microtask-based; SessionsService projects on the same flush that create
+   * awaited through the RPC round trip).
+   * @param opts - project directory, prompt text, and send mode.
+   */
+  async startSession(opts: { cwd?: string; text: string; mode: 'queue' | 'steer' }): Promise<void> {
+    const sessions = this.requireSessions()
+    const id = await sessions.create(opts.cwd === undefined ? {} : { cwd: opts.cwd })
+    // The manager notifier flushes per microtask; one await guarantees the
+    // list-store projection landed before layout.open validates against it.
+    await Promise.resolve()
+    this.requireLayout().open(id)
+    const scoped = sessions.scope(id)
+    if (scoped === undefined) throw new Error(`conversation.startSession: created session "${id}" resolved no scope`)
+    // ctx.get, not scoped.conversation: property access walks the fiber
+    // topology (a scope fiber never injects services), while get reads the
+    // global store and still binds this service to the scoped ctx.
+    const scopedConversation = scoped.get('conversation')
+    if (scopedConversation === undefined) throw new Error('conversation.startSession: conversation service unavailable through the new scope')
+    await scopedConversation.send(opts.text, opts.mode)
+  }
+
+  /** Resolve the caller scope's Session or throw on root contexts. */
+  private scopedSession(op: string): Session {
+    const id = this.scopeId(op)
+    return this.requireSessions().manager.get(id)
+  }
+
+  /** Read the caller's session scope tag; root contexts fail loud. */
+  private scopeId(op: string): SessionId {
+    const id = scopeOf(this.ctx)
+    if (id === undefined) {
+      throw new Error(`conversation.${op} requires a session scope — address one via ctx.sessions.scope(id).conversation`)
+    }
+    return id
+  }
+
+  /**
+   * Per-scope store account: lazily created, booked on the scope fiber so the
+   * scope teardown (SessionsService prune) collects the entry.
+   */
+  private scopeStore<T>(
+    map: Map<SessionId, SnapshotStore<T>>, op: string,
+    make: (id: SessionId) => SnapshotStore<T>): SnapshotStore<T> {
+    const id = this.scopeId(op)
+    let store = map.get(id)
+    if (store === undefined) {
+      store = make(id)
+      map.set(id, store)
+      this.ctx.effect(() => () => { map.delete(id) }, `conversation.${op} scope account`)
+    }
+    return store
+  }
+
+  private requireSessions(): SessionsService {
+    // ctx.get instead of ctx.sessions: the typed Context merge is suspended
+    // while the client/host `sessions` declaration collision awaits
+    // arbitration (see the runtime package's Context merge note).
+    const sessions = this.ctx.get('sessions')
+    if (sessions === undefined) throw new Error('conversation: sessions service unavailable')
+    return sessions
+  }
+
+  private requireLayout(): LayoutService {
+    const layout = this.ctx.get('layout')
+    if (layout === undefined) throw new Error('conversation: layout service unavailable')
+    return layout
+  }
+}
+
+function bumpViews(state: ViewsState): void {
+  state.cache = null
+  state.tick += 1
+  for (const fn of [...state.listeners]) fn()
+}
+
+function loadDraft(key: string): string {
+  /* v8 ignore next -- storage-less environment guard (workers/tests without DOM); jsdom always provides localStorage. */
+  if (typeof localStorage === 'undefined') return ''
+  return localStorage.getItem(key) ?? ''
+}
+
+function saveDraft(key: string, text: string): void {
+  /* v8 ignore next -- storage-less environment guard (workers/tests without DOM); jsdom always provides localStorage. */
+  if (typeof localStorage === 'undefined') return
+  if (text === '') localStorage.removeItem(key)
+  else localStorage.setItem(key, text)
+}
diff --git a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css
new file mode 100644
index 0000000000..3523919f51
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css
@@ -0,0 +1,129 @@
+/* Conversation column skeleton: header (breadcrumb row + tabs) over the view
+   area, composer InputBar at the bottom. Column width/squeeze is layout's;
+   this fills its cell. Figma: Header 39:27730 (83px two-row), tabs 13px with
+   a 3px active bar. */
+
+.root {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-width: 0;
+  background: var(--dsw-alias-bg-base);
+}
+
+.header {
+  flex: none;
+  padding: 12px 28px 0 20px;
+  border-bottom: 1px solid var(--dsw-alias-border-l2);
+}
+
+.crumbRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  min-height: 32px;
+}
+
+.crumbs {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+}
+
+.crumbSeg {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  min-width: 0;
+}
+
+.crumbSep {
+  /* figma: "/" separators are 14px caption gray (75:7903), one tint lighter than crumb text. */
+  color: var(--dsw-alias-label-caption);
+  font-size: 14px;
+  line-height: 20px;
+}
+
+.crumb {
+  max-width: 220px;
+  overflow: hidden;
+  padding: 4px 8px;
+  border: none;
+  border-radius: 12px;
+  background: transparent;
+  font-size: 13px;
+  line-height: 16px;
+  color: var(--dsw-alias-label-tertiary);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  cursor: pointer;
+}
+
+.crumb:hover:not(:disabled) {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.crumbCurrent {
+  font-weight: 500;
+  color: var(--dsw-alias-label-primary);
+  cursor: default;
+}
+
+.meta {
+  margin-left: 4px;
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+/* figma Tab_Group 34:11441: 35px strip, gap 36, pad-left 8, tabs bottom-aligned. */
+.tabs {
+  display: flex;
+  gap: 36px;
+  margin-top: 4px;
+  padding-left: 8px;
+}
+
+/* figma .Tab 34:11442: 13/16 wt510 text, gap 8 to the 3px bar (no bottom rounding). */
+.tab {
+  position: relative;
+  padding: 0 0 11px;
+  border: none;
+  background: transparent;
+  font-size: 13px;
+  line-height: 16px;
+  font-weight: 510;
+  color: var(--dsw-alias-label-tertiary);
+  cursor: pointer;
+}
+
+.tab::after {
+  content: '';
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  height: 3px;
+  background: transparent;
+}
+
+/* Selected tab is blue, not ink: brand-primary resolves to neutral black in
+   this token sheet, so the selected state rides the business blue — the
+   nearest semantic token that stays blue in both themes. */
+.tabActive {
+  color: var(--dsw-alias-state-business-primary);
+}
+
+.tabActive::after {
+  background: var(--dsw-alias-state-business-primary);
+}
+
+.viewArea {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  min-height: 0;
+}
diff --git a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
new file mode 100644
index 0000000000..540b76bda7
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
@@ -0,0 +1,109 @@
+// ConversationRoot: the conversation slot's skeleton (figma Header 39:27730 +
+// Tab_Group + view area + composer). Zero framework imports — everything
+// arrives via props from the inject factory: breadcrumb feed, view registry
+// read face, per-view render, and the composer's draft/send choreography.
+// The active view id lives in layout.viewFor (shell viewing state), read and
+// written through injected accessors.
+
+import { useSyncExternalStore } from 'react'
+import clsx from 'clsx'
+import type { ConversationSlotProps } from '../contract/slots.ts'
+import { InputBar } from './InputBar.tsx'
+import type { InputBarError } from './InputBar.tsx'
+import css from './ConversationRoot.module.css'
+
+/**
+ * Full props = owner share (sessionId) & standard share (useSession) &
+ * injected share — composed by reference from the contract, never re-typed
+ * here (share-ownership rule).
+ */
+export type ConversationRootProps = ConversationSlotProps
+
+export function ConversationRoot({
+  sessionId, useSession, useAncestry, views, useActiveView, composer, actions, renderView,
+}: ConversationRootProps) {
+  useSyncExternalStore(views.subscribe, views.version)
+  const list = views.list()
+  const activeId = useActiveView() ?? 'chat'
+  const active = list.find(v => v.id === activeId) ?? list[0]
+
+  const ancestry = useAncestry()
+  const draft = composer.useDraft()
+  const running = useSession(s => (s as { running: boolean }).running)
+  const removed = useSession(s => (s as { removed: boolean }).removed)
+  const promptError = useSession(s => (s as { promptError: { op: 'send' | 'stop'; error: { message: string; code: string } } | null }).promptError)
+  const turns = useSession(s => countTurns(s as { nodes: readonly { kind: string }[] }))
+
+  const error: InputBarError | null = promptError === null
+    ? null
+    : { op: promptError.op, message: `${promptError.error.message}（${promptError.error.code}）` }
+
+  return (
+    <div className={css.root}>
+      <header className={css.header}>
+        <div className={css.crumbRow}>
+          <nav className={css.crumbs} aria-label="会话层级">
+            {ancestry.map((s, i) => {
+              const last = i === ancestry.length - 1
+              return (
+                <span key={s.id} className={css.crumbSeg}>
+                  {i > 0 && <span className={css.crumbSep}>/</span>}
+                  <button
+                    type="button"
+                    className={clsx(css.crumb, last && css.crumbCurrent)}
+                    disabled={last}
+                    onClick={() => { actions.open(s.id) }}
+                  >
+                    {s.title}
+                  </button>
+                </span>
+              )
+            })}
+            {ancestry.length === 0 && <span className={css.crumbCurrent}>{sessionId}</span>}
+            <span className={css.meta}>· {turns} turns</span>
+          </nav>
+          {/* Header button row (Fork / Session log / I/O Details): a P-I visual
+              placeholder registry slot is deferred — buttons land with their features. */}
+        </div>
+        {list.length > 1 && (
+          <div className={css.tabs} role="tablist">
+            {list.map(v => (
+              <button
+                key={v.id}
+                type="button"
+                role="tab"
+                aria-selected={v.id === active?.id}
+                className={clsx(css.tab, v.id === active?.id && css.tabActive)}
+                onClick={() => { actions.openView(v.id) }}
+              >
+                {v.label}
+              </button>
+            ))}
+          </div>
+        )}
+      </header>
+
+      <div className={css.viewArea}>
+        {active !== undefined && renderView(active)}
+      </div>
+
+      <InputBar
+        draft={draft}
+        running={running}
+        disabled={removed}
+        error={error}
+        variant="composer"
+        onDraftChange={composer.setDraft}
+        onSend={composer.send}
+        onStop={composer.stop}
+      />
+    </div>
+  )
+}
+
+/** Turn count = user message nodes in the window (display meta; exact host count deferred). */
+function countTurns(s: { nodes: readonly { kind: string }[] }): number {
+  let n = 0
+  for (const node of s.nodes) if (node.kind === 'user') n += 1
+  return n
+}
diff --git a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css
new file mode 100644
index 0000000000..abdece3e25
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css
@@ -0,0 +1,94 @@
+/* Details third column, minimal P-I fill: header (name + close) over a
+   scrolling body of Input/Output code sections. Panel width/squeeze belongs
+   to layout; this fills whatever the column gives. */
+
+.root {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-width: 0;
+  border-left: 1px solid var(--dsw-alias-border-l2);
+  background: var(--dsw-alias-bg-base);
+}
+
+/* figma RightSidebar header frame (I54:42735;43:36451): pad 14/12/12/12, gap 8. */
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 14px 12px 12px;
+  border-bottom: 1px solid var(--dsw-alias-border-l2);
+}
+
+/* figma I54:42735;43:41479: 14/20 wt500. */
+.title {
+  overflow: hidden;
+  font-size: 14px;
+  line-height: 20px;
+  font-weight: 500;
+  color: var(--dsw-alias-label-primary);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.close {
+  display: grid;
+  flex: none;
+  place-items: center;
+  width: 28px;
+  height: 28px;
+  border: none;
+  border-radius: 999px;
+  background: transparent;
+  color: var(--dsw-alias-label-secondary);
+  cursor: pointer;
+}
+
+.close:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.body {
+  flex: 1;
+  min-height: 0;
+  padding: 12px 16px;
+  overflow-y: auto;
+}
+
+.empty {
+  padding: 8px 0;
+  font-size: 13px;
+  line-height: 20px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.section {
+  margin-bottom: 16px;
+}
+
+.sectionLabel {
+  margin-bottom: 6px;
+  font-size: 12px;
+  line-height: 18px;
+  font-weight: 500;
+  color: var(--dsw-alias-label-secondary);
+}
+
+/* figma Code-block (I54:42735;43:41429): r12, pad 16, mono 13/22. */
+.code {
+  margin: 0;
+  padding: 16px;
+  border-radius: 12px;
+  background: var(--dsw-alias-markdown-code-block);
+  font-family: var(--ds-font-family-code);
+  font-size: 13px;
+  line-height: 22px;
+  color: var(--dsw-alias-label-primary);
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.code[data-error] {
+  color: var(--dsw-alias-state-error-primary);
+}
diff --git a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
new file mode 100644
index 0000000000..c59ddf80c3
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
@@ -0,0 +1,111 @@
+// DetailsPanel, P-I minimal form: close button + the selected call's args and
+// result rendered raw. The three-段 Switch / Prev-Next stepping / See-in-
+// trajectory are deferred (ledger). Subscribes to the per-scope selection and
+// derives the call material from the session snapshot — no data of its own.
+
+import type { ConversationSnapshot, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import { shallowEqual } from '@deepseek-ai/dsh-client-web-react'
+import type { DetailsSlotProps } from '../contract/slots.ts'
+import css from './DetailsPanel.module.css'
+
+/** Full props composed by reference from the contract (owner & standard & injected shares). */
+export type DetailsPanelProps = DetailsSlotProps
+
+/** Selected call material: resolved result node, or the in-flight running call's args. */
+interface CallMaterial {
+  name: string
+  argsRaw: string | null
+  result: ToolResultNode | null
+  running: boolean
+}
+
+function materialFor(s: ConversationSnapshot, callId: string): CallMaterial | null {
+  for (const node of s.nodes) {
+    if (node.kind === 'tool-result' && node.callId === callId) {
+      return { name: node.call?.name ?? callId, argsRaw: node.call?.argsRaw ?? null, result: node, running: false }
+    }
+  }
+  const open = s.runningCalls.find(c => c.callId === callId)
+  if (open !== undefined) {
+    return { name: open.name, argsRaw: open.argsRaw, result: null, running: true }
+  }
+  return null
+}
+
+function pretty(raw: string): string {
+  try {
+    return JSON.stringify(JSON.parse(raw), null, 2)
+  } catch {
+    // Not JSON (streaming fragment or plain text): show verbatim.
+    return raw
+  }
+}
+
+export function DetailsPanel({ useSession, useSelection, actions }: DetailsPanelProps) {
+  const selection = useSelection(s => s)
+  const callId = selection?.callId
+  // materialFor builds a fresh wrapper; shallowEqual short-circuits on its
+  // stable members (result node reference rides the snapshot's structural sharing).
+  const material = useSession(
+    s => (callId === undefined ? null : materialFor(s as ConversationSnapshot, callId)),
+    (a, b) => shallowEqual(a, b))
+
+  return (
+    <div className={css.root}>
+      <div className={css.header}>
+        <div className={css.title}>
+          {selection === null ? '详情' : material?.name ?? selection.toolName ?? '详情'}
+        </div>
+        <button
+          type="button" className={css.close} aria-label="关闭详情"
+          onClick={() => { actions.closeDetails() }}
+        >
+          <svg viewBox="0 0 16 16" width="14" height="14" aria-hidden>
+            <path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+          </svg>
+        </button>
+      </div>
+      <div className={css.body}>
+        {selection === null || callId === undefined
+          ? <div className={css.empty}>点击消息流中的工具行查看详情</div>
+          : material === null
+            ? <div className={css.empty}>该调用不在当前窗口内</div>
+            : (
+                <>
+                  {material.argsRaw !== null && (
+                    <section className={css.section}>
+                      <div className={css.sectionLabel}>Input</div>
+                      <pre className={css.code}>{pretty(material.argsRaw)}</pre>
+                    </section>
+                  )}
+                  <section className={css.section}>
+                    <div className={css.sectionLabel}>Output</div>
+                    {/* materialFor invariant: result===null ⇔ running (a settled
+                        material always carries its result node). */}
+                    {material.result === null
+                      ? <div className={css.empty}>运行中…</div>
+                      : (
+                          <pre className={css.code} data-error={material.result.isError || undefined}>
+                            {renderResult(material.result)}
+                          </pre>
+                        )}
+                  </section>
+                </>
+              )}
+      </div>
+    </div>
+  )
+}
+
+/** Flatten result content blocks to display text (text blocks verbatim, others as JSON). */
+function renderResult(node: ToolResultNode): string {
+  const parts: string[] = []
+  for (const block of node.content) {
+    if (block.type === 'text') parts.push(block.text)
+    else parts.push(JSON.stringify(block, null, 2))
+  }
+  if (parts.length === 0 && node.error !== undefined) {
+    parts.push(`${node.error.name}: ${node.error.code}`)
+  }
+  return parts.join('\n')
+}
diff --git a/packages/client/ui-conversation/src/client/skeleton/EmptyState.module.css b/packages/client/ui-conversation/src/client/skeleton/EmptyState.module.css
new file mode 100644
index 0000000000..fbe2f25c09
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/skeleton/EmptyState.module.css
@@ -0,0 +1,68 @@
+/* NEW SESSION hero: headline over the shared InputBar card, centered in the
+   conversation column. The card is the same component as the composer —
+   only positioning lives here. */
+
+.root {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  min-width: 0;
+  padding: 24px;
+}
+
+/* figma hero group 34:10409: headline block sits 36px above the input card. */
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: 36px;
+  width: 100%;
+  max-width: 776px;
+}
+
+/* figma 34:10411: fish + title row, gap 10, centered; title 26/32 wt600 (34:10414). */
+.headline {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 10px;
+  font-size: 26px;
+  line-height: 32px;
+  font-weight: 600;
+  color: var(--dsw-alias-label-primary);
+}
+
+/* figma 34:10412/10413: brand-blue vector. */
+.fish {
+  flex: none;
+  color: var(--dsw-alias-state-business-primary);
+}
+
+.picker {
+  display: flex;
+  align-items: center;
+  min-width: 0;
+}
+
+.select,
+.customInput {
+  max-width: 320px;
+  padding: 4px 10px;
+  border: 1px solid var(--dsw-alias-border-l2-darkmode-thin);
+  border-radius: 12px;
+  background: var(--dsw-alias-bg-base);
+  font-size: 13px;
+  line-height: 20px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.customInput {
+  width: 320px;
+  outline: none;
+}
+
+.customInput:focus {
+  /* Business blue, not brand-primary: that token resolves to ink in this sheet. */
+  border-color: var(--dsw-alias-state-business-primary);
+  color: var(--dsw-alias-label-primary);
+}
diff --git a/packages/client/ui-conversation/src/client/skeleton/EmptyState.tsx b/packages/client/ui-conversation/src/client/skeleton/EmptyState.tsx
new file mode 100644
index 0000000000..775d82ec16
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/skeleton/EmptyState.tsx
@@ -0,0 +1,106 @@
+// EmptyState (figma NEW SESSION screen): centered hero card built around the
+// SAME InputBar component the resident composer uses (the empty→content
+// transition is one component changing position, never a swap). Project
+// picker: cwd set derived from sessions.list plus a free-form new-directory
+// input; submit runs the startSession chain (create → open → send) in one
+// service call.
+
+import { useState } from 'react'
+import { FishLogo } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { EmptyStateSlotProps } from '../contract/slots.ts'
+import { InputBar } from './InputBar.tsx'
+import type { InputBarError } from './InputBar.tsx'
+import css from './EmptyState.module.css'
+
+/** Select sentinel for the free-form directory entry (impossible as a real path: not absolute). */
+const NEW_DIR = '::new-directory'
+
+/** Full props composed by reference from the contract (owner & injected shares; root slot has no standard share). */
+export type EmptyStateProps = EmptyStateSlotProps
+
+export function EmptyState({ useCwds, actions }: EmptyStateProps) {
+  const cwds = useCwds(s => s)
+  // Local viewing state: the empty state owns no session, so its draft is
+  // ephemeral by design (drafts are keyed by session id; there is none yet).
+  const [draft, setDraft] = useState('')
+  const [cwd, setCwd] = useState<string>('')
+  const [custom, setCustom] = useState(false)
+  const [sending, setSending] = useState(false)
+  const [error, setError] = useState<InputBarError | null>(null)
+
+  const submit = (mode: 'queue' | 'steer'): void => {
+    const text = draft.trim()
+    /* v8 ignore next -- defensive: InputBar disables send while empty. */
+    if (text === '' || sending) return
+    setSending(true)
+    setError(null)
+    const chosen = cwd.trim()
+    actions.startSession({ text, mode, ...(chosen === '' ? {} : { cwd: chosen }) })
+      .catch((reason: unknown) => {
+        // The empty state survives failure with the draft intact (no session
+        // exists to carry promptError; this is the only local error surface).
+        setError({ op: 'send', message: reason instanceof Error ? reason.message : String(reason) })
+        setSending(false)
+      })
+    // Success needs no cleanup: layout.open swaps this slot out for the session body.
+  }
+
+  const picker = (
+    <div className={css.picker}>
+      {custom
+        ? (
+            <input
+              className={css.customInput}
+              value={cwd}
+              autoFocus
+              placeholder="目录路径，如 /home/me/proj"
+              onChange={(e) => { setCwd(e.target.value) }}
+            />
+          )
+        : (
+            <select
+              className={css.select}
+              value={cwd}
+              aria-label="项目目录"
+              onChange={(e) => {
+                if (e.target.value === NEW_DIR) {
+                  setCustom(true)
+                  setCwd('')
+                } else {
+                  setCwd(e.target.value)
+                }
+              }}
+            >
+              <option value="">默认目录</option>
+              {cwds.map(c => <option key={c} value={c}>{c}</option>)}
+              <option value={NEW_DIR}>新目录…</option>
+            </select>
+          )}
+    </div>
+  )
+
+  return (
+    <div className={css.root}>
+      <div className={css.card}>
+        <div className={css.headline}>
+          {/* figma 34:10412: fish 34x25 leading the headline, gap 10. */}
+          <FishLogo size={34} className={css.fish} />
+          Let&apos;s start building
+        </div>
+        <InputBar
+          draft={draft}
+          running={false}
+          disabled={sending}
+          error={error}
+          variant="hero"
+          placeholder="Message to run task, plan and build"
+          accessory={picker}
+          onDraftChange={setDraft}
+          onSend={submit}
+          /* v8 ignore next -- structural noop: hero never passes running=true, so stop is unreachable. */
+          onStop={() => {}}
+        />
+      </div>
+    </div>
+  )
+}
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
new file mode 100644
index 0000000000..1139c3c9c1
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
@@ -0,0 +1,160 @@
+/* Floating capsule input (figma Input_Bottom 34:11445): card floats above the
+   viewport bottom inside the centered message column; textarea on top, action
+   row below, one primary circle button bottom-right. Input width rides the
+   column (776 is a cap, not a fixed size — layout rule: the box shrinks with
+   the center column keeping its padding). Hero variant = the same card
+   centered in the empty state; the transition between the two is a position
+   move of one component. */
+
+.root {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  /* figma Input_Bottom 34:11445: pad L32/R32/B12; the bottom gradient mask is
+     owned by the chat scroller. Top 8 hosts the error strip's breathing room. */
+  padding: 8px 32px 12px;
+}
+
+.hero {
+  padding: 0;
+}
+
+.error {
+  width: 100%;
+  max-width: 776px;
+  margin-bottom: 6px;
+  padding: 4px 8px;
+  border-radius: 8px;
+  background: var(--dsw-alias-interactive-bg-hover-danger);
+  color: var(--dsw-alias-state-error-primary);
+  font-size: 12px;
+  line-height: 18px;
+}
+
+.card {
+  display: flex;
+  flex-direction: column;
+  /* figma Input 34:11458: 12px between the text area and the button row. */
+  gap: 12px;
+  width: 100%;
+  max-width: 776px;
+  /* Input stroke: black/0.10 light, white/0.06 dark (figma darkmode note says
+     the input border is one notch weaker than buttons) — exactly the
+     l2-darkmode-thin pair. Fill: the input surface token (elevated in dark). */
+  border: 1px solid var(--dsw-alias-border-l2-darkmode-thin);
+  border-radius: 20px;
+  background: var(--dsw-specific-input-major);
+  box-shadow: var(--dsw-shadow-lv2);
+  font-size: 16px;
+  line-height: 24px;
+}
+
+/* New-session state rounds up (figma: r24 and a taller box). */
+.hero .card {
+  border-radius: 24px;
+}
+
+.accessory {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 10px 12px 0;
+}
+
+/* Mirror-div auto-grow wrapper: the hidden mirror is in normal flow and sets the height
+   (min 2 lines / max 14 lines); the textarea rides it absolutely. Mirror and textarea
+   MUST share font, line-height, padding and wrapping rules or heights diverge. */
+.grow {
+  position: relative;
+}
+
+.input {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  resize: none;
+  overflow-y: auto;
+  border: none;
+  outline: none;
+  background: transparent;
+  color: var(--dsw-alias-label-primary);
+  /* Business blue, not brand-primary: that token resolves to ink in this sheet. */
+  caret-color: var(--dsw-alias-state-business-primary);
+}
+
+.input,
+.mirror {
+  padding: 12px 16px 0;
+  font-size: inherit;
+  line-height: inherit;
+  white-space: pre-wrap;
+  word-break: break-word;
+  overflow-wrap: anywhere;
+}
+
+/* figma 34:10434: #ADB2B8 light / #81858C dark — the caption pair exactly. */
+.input::placeholder {
+  color: var(--dsw-alias-label-caption);
+  user-select: none;
+}
+
+/* Running lock: grayed but the draft stays visible; the turn ending re-enables. */
+.input:disabled {
+  color: var(--dsw-alias-label-tertiary);
+  cursor: not-allowed;
+}
+
+.mirror {
+  visibility: hidden;
+  pointer-events: none;
+  /* 2-line floor: 2 × 24px line + 12px top padding; 14-line cap (336px). */
+  min-height: 60px;
+  max-height: 336px;
+  overflow: hidden;
+}
+
+.hero .mirror {
+  /* New-session box is taller at rest (figma 118px input area). */
+  min-height: 84px;
+}
+
+/* figma Frame 1123 (34:11463): pad 12/0/10/10, buttons vertically centered. */
+.row {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  padding: 0 10px 10px 12px;
+}
+
+/* Primary send (figma IconButton 34:10465): 34px circle, #3964FE light /
+   #679EFE dark — the info-fill pair (500→400), NOT button-primary (ink);
+   white glyph; empty text = 0.4 opacity. */
+.primary {
+  display: grid;
+  place-items: center;
+  width: 34px;
+  height: 34px;
+  border: none;
+  border-radius: 999px;
+  background: var(--dsw-alias-button-info-fill);
+  color: var(--dsw-alias-label-primary-foreground);
+  cursor: pointer;
+}
+
+.primary:hover {
+  background: var(--dsw-alias-button-info-hover);
+}
+
+.primary:disabled {
+  opacity: 0.4;
+  cursor: default;
+}
+
+/* Stop state: same slot, dimmed brand fill — the running-state send-key
+   replacement is a design gap filled by us (figma gives no stop form). */
+.stopping,
+.stopping:hover {
+  background: var(--dsw-alias-button-primary-dimmed);
+  color: var(--dsw-alias-brand-text);
+}
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
new file mode 100644
index 0000000000..c5c8307ffc
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
@@ -0,0 +1,142 @@
+// InputBar: the one composer input (figma Input_Bottom). The same component
+// serves the empty state (variant='hero': centered launch card) and the
+// resident composer (variant='composer') — the empty→content transition is a
+// position move of this component, never a swap (layout ruling). Running
+// LOCKS the input: textarea disabled with the draft visible, stop is the only
+// action; the turn ending re-enables and refocuses.
+
+import { useEffect, useRef } from 'react'
+import type { KeyboardEvent, MouseEvent, ReactNode } from 'react'
+import clsx from 'clsx'
+import css from './InputBar.module.css'
+
+/** Prompt failure surface (mirrors the session snapshot's promptError shape). */
+export interface InputBarError {
+  op: 'send' | 'stop'
+  message: string
+}
+
+export interface InputBarProps {
+  draft: string
+  running: boolean
+  disabled: boolean
+  error: InputBarError | null
+  /** Hero = empty-state centered card; composer = resident bottom bar. */
+  variant: 'hero' | 'composer'
+  placeholder?: string
+  /** Optional leading accessory row content (the empty state mounts its cwd picker here). */
+  accessory?: ReactNode
+  onDraftChange: (text: string) => void
+  onSend: (mode: 'queue' | 'steer') => void
+  onStop: () => void
+}
+
+export function InputBar({
+  draft, running, disabled, error, variant, placeholder, accessory, onDraftChange, onSend, onStop,
+}: InputBarProps) {
+  const empty = draft.trim() === ''
+  const inputRef = useRef<HTMLTextAreaElement | null>(null)
+  // IME guard: composition Enter picks a candidate, it must not send. The ref outlives renders;
+  // clearing is deferred one tick because Safari delivers the closing keydown AFTER compositionend.
+  const composingRef = useRef(false)
+  const onCompositionStart = (): void => {
+    composingRef.current = true
+  }
+  const onCompositionEnd = (): void => {
+    setTimeout(() => {
+      composingRef.current = false
+    }, 10)
+  }
+
+  // Locked while running: the browser drops keystrokes AND focus on a disabled
+  // textarea — no sending mid-turn, stop or wait.
+  const locked = disabled || running
+
+  // Unlock (mount / session switch / turn end) returns focus to the box.
+  useEffect(() => {
+    if (!locked) inputRef.current?.focus()
+  }, [locked])
+
+  const onKeyDown = (e: KeyboardEvent<HTMLTextAreaElement>): void => {
+    if (e.key !== 'Enter') return
+    if (composingRef.current || e.nativeEvent.isComposing || e.nativeEvent.keyCode === 229) return
+    if (e.shiftKey) return // native newline
+    if (e.ctrlKey || e.metaKey) {
+      // execCommand keeps the browser undo stack intact, unlike a setState splice.
+      e.preventDefault()
+      document.execCommand('insertText', false, '\n')
+      return
+    }
+    e.preventDefault()
+    if (e.repeat) return // held-down Enter must not machine-gun sends
+    if (!empty && !locked) onSend('queue')
+  }
+
+  // Button presses steal focus from the textarea; suppress at mousedown so typing continues seamlessly.
+  const keepFocus = (e: MouseEvent<HTMLButtonElement>): void => {
+    e.preventDefault()
+    inputRef.current?.focus()
+  }
+
+  const primaryLabel = running ? '停止' : '发送'
+  const onPrimary = (): void => {
+    if (running) {
+      onStop()
+      return
+    }
+    /* v8 ignore next -- defensive: the primary button is disabled while empty||disabled, so a click cannot reach the false arm. */
+    if (!empty && !disabled) onSend('queue')
+  }
+
+  return (
+    <div className={clsx(css.root, variant === 'hero' && css.hero)}>
+      {error !== null && (
+        <div className={css.error}>
+          {error.op === 'stop' ? '停止失败' : '发送失败'}：{error.message}
+        </div>
+      )}
+      <div className={css.card}>
+        {accessory !== undefined && <div className={css.accessory}>{accessory}</div>}
+        {/* Mirror-div auto-grow: the hidden mirror renders draft+'\n' and stretches the wrapper
+            (min/max capped in CSS); the absolutely-positioned textarea rides its height. Counting
+            rows by '\n' cannot see soft wraps. */}
+        <div className={css.grow}>
+          <textarea
+            ref={inputRef}
+            className={css.input}
+            value={draft}
+            disabled={locked}
+            placeholder={placeholder ?? (disabled ? '会话不可用' : running ? '回复生成中，可停止后再输入' : '输入消息，Enter 发送，Shift+Enter 换行')}
+            rows={2}
+            onChange={(e) => onDraftChange(e.target.value)}
+            onKeyDown={onKeyDown}
+            onCompositionStart={onCompositionStart}
+            onCompositionEnd={onCompositionEnd}
+          />
+          <div aria-hidden className={css.mirror}>{`${draft}\n`}</div>
+        </div>
+        <div className={css.row}>
+          <button
+            type="button"
+            className={clsx(css.primary, running && css.stopping)}
+            aria-label={primaryLabel}
+            title={running ? '停止本轮' : '发送（Enter）'}
+            disabled={!running && (empty || disabled)}
+            onMouseDown={keepFocus}
+            onClick={onPrimary}
+          >
+            {running ? (
+              <svg viewBox="0 0 16 16" width="14" height="14" aria-hidden>
+                <rect x="4" y="4" width="8" height="8" rx="1.5" fill="currentColor" />
+              </svg>
+            ) : (
+              <svg viewBox="0 0 16 16" width="14" height="14" aria-hidden>
+                <path d="M8 13V3.8M8 3.8L3.8 8M8 3.8L12.2 8" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" fill="none" />
+              </svg>
+            )}
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/packages/client/ui-conversation/src/client/toolviews/bash-sample.module.css b/packages/client/ui-conversation/src/client/toolviews/bash-sample.module.css
new file mode 100644
index 0000000000..83c2329fc5
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/toolviews/bash-sample.module.css
@@ -0,0 +1,48 @@
+/* Sample bash rows: deliberately distinct from ToolRow so the differential
+   registry hit is visible at a glance. */
+
+.row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  height: 24px;
+  min-width: 0;
+  cursor: pointer;
+  border-radius: 6px;
+  font-family: var(--ds-font-family-code);
+  font-size: 13px;
+}
+
+.row:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.prompt {
+  flex: none;
+  color: var(--dsw-alias-state-success-primary);
+}
+
+.scopeBadge {
+  flex: none;
+  padding: 0 6px;
+  border-radius: 6px;
+  font-size: 11px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-primary-foreground);
+  background: var(--dsw-alias-state-business-primary);
+}
+
+.command {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.err {
+  flex: none;
+  color: var(--dsw-alias-state-error-primary);
+  font-size: 11px;
+}
diff --git a/packages/client/ui-conversation/src/client/toolviews/bash-sample.tsx b/packages/client/ui-conversation/src/client/toolviews/bash-sample.tsx
new file mode 100644
index 0000000000..eda731f586
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/toolviews/bash-sample.tsx
@@ -0,0 +1,52 @@
+// Bash toolview sample, written in third-party posture: everything below uses
+// only the public registration surface (ctx.toolviews.register + ToolViewProps)
+// — the differential-rendering acceptance proof for the registry chain.
+// Two registrations: a global bash row, and a scope-filtered variant that
+// takes over for matching sessions only (later registration wins its tier).
+
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ToolViewProps } from '../contract/toolview.ts'
+import type { ToolViewRegistry } from './registry.ts'
+import { toolRowModel, type ToolCallBlock } from '../contract/tool-call-model.ts'
+import css from './bash-sample.module.css'
+
+/** Global bash row: command-first monospace summary (replaces the generic row). */
+export function BashRow({ toolName, block, actions }: ToolViewProps) {
+  const model = toolRowModel(toolName, block as ToolCallBlock)
+  return (
+    <div className={css.row} data-sample="bash-global" onClick={actions.openDetails}>
+      <span className={css.prompt} aria-hidden>$</span>
+      <span className={css.command}>{model.summary}</span>
+      {model.state === 'error' && <span className={css.err}>failed</span>}
+    </div>
+  )
+}
+
+/** Scoped variant: visually distinct so the differential hit is observable. */
+export function ScopedBashRow({ toolName, block, actions }: ToolViewProps) {
+  const model = toolRowModel(toolName, block as ToolCallBlock)
+  return (
+    <div className={css.row} data-sample="bash-scoped" onClick={actions.openDetails}>
+      <span className={css.scopeBadge}>scoped</span>
+      <span className={css.command}>{model.summary}</span>
+    </div>
+  )
+}
+
+/**
+ * Register both sample rows.
+ * @param toolviews - the conversation plugin's registry service.
+ * @param scope - session filter for the scoped variant.
+ * @returns disposer removing both registrations.
+ */
+export function registerBashSamples(
+  toolviews: ToolViewRegistry,
+  scope: (sessionId: SessionId) => boolean,
+): () => void {
+  const offGlobal = toolviews.register('bash', BashRow)
+  const offScoped = toolviews.register('bash', ScopedBashRow, { scope })
+  return () => {
+    offGlobal()
+    offScoped()
+  }
+}
diff --git a/packages/client/ui-conversation/src/client/toolviews/registry.ts b/packages/client/ui-conversation/src/client/toolviews/registry.ts
new file mode 100644
index 0000000000..9fe9226b5b
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/toolviews/registry.ts
@@ -0,0 +1,102 @@
+/**
+ * ToolViewRegistry: named per-tool component registry, session-scope aware
+ * (api-contracts v3 section 7). Consumed by chat now, trajectory/waterfall
+ * later — deliberately a named service, not a SlotMap key. The tool key set
+ * is deliberately open (model-side tools arrive at runtime): the strong
+ * typing lives inside the Entry — `I` is inferred from the inject factory at
+ * the register site and proves component props ⊇ ToolViewProps & I.
+ */
+import type { FC } from 'react'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ResolvedToolView, ToolViewOptions, ToolViewProps } from '../contract/toolview.ts'
+
+/** Stored registration: the per-registration inject parameter is erased
+ *  (storage-erase/read-restore is the typed-Map boundary, one cast budgeted). */
+interface Registration extends ToolViewOptions {
+  component: FC<ToolViewProps & object>
+}
+
+/**
+ * Per-tool renderer registry. Resolution order: scope match (later
+ * registration wins) > global (same tie-break) > undefined, where the caller
+ * falls back to GenericToolCard.
+ */
+export class ToolViewRegistry {
+  private byTool = new Map<string, Registration[]>()
+  private version = 0
+  private listeners = new Set<() => void>()
+
+  /**
+   * Register a tool row renderer. The component must accept the shared
+   * ToolViewProps plus its own injected share `I` — mismatches (missing keys,
+   * wrong types, an inject factory that does not produce what the component
+   * declares) are register-site compile errors.
+   * @param tool - tool name the renderer takes over.
+   * @param component - row component over ToolViewProps & I.
+   * @param opts - optional session-scope filter and private inject factory.
+   * @returns disposer removing this registration.
+   */
+  register<I extends object = object>(
+    tool: string, component: FC<ToolViewProps & I>, opts?: ToolViewOptions<I>): () => void {
+    const list = this.byTool.get(tool) ?? []
+    if (list.length === 0) this.byTool.set(tool, list)
+    // Storage erases I (heterogeneous registrations share one list); resolve
+    // restores the erased shape on the read face.
+    const entry: Registration = { component: component as FC<ToolViewProps & object>, ...opts }
+    list.push(entry)
+    this.bump()
+    let disposed = false
+    return () => {
+      if (disposed) return
+      disposed = true
+      const at = list.indexOf(entry)
+      /* v8 ignore next -- negative arm: an entry lives in one list and only its own once-guarded disposer removes it, so a live disposer always finds it. */
+      if (at >= 0) list.splice(at, 1)
+      if (list.length === 0) this.byTool.delete(tool)
+      this.bump()
+    }
+  }
+
+  /**
+   * Resolve the renderer for a tool in a session.
+   * @param tool - tool name.
+   * @param sessionId - session the row renders in (fed to scope filters).
+   * @returns resolved view, or undefined when nothing matches.
+   */
+  resolve(tool: string, sessionId: SessionId): ResolvedToolView | undefined {
+    const list = this.byTool.get(tool)
+    if (list === undefined) return undefined
+    let global: Registration | undefined
+    let scoped: Registration | undefined
+    for (const entry of list) {
+      if (entry.scope === undefined) global = entry
+      else if (entry.scope(sessionId)) scoped = entry
+    }
+    const hit = scoped ?? global
+    if (hit === undefined) return undefined
+    return hit.inject === undefined ? { component: hit.component } : { component: hit.component, inject: hit.inject }
+  }
+
+  /**
+   * Subscribe to registration changes (render outlets re-resolve on notify).
+   * @param fn - change listener.
+   * @returns disposer.
+   */
+  subscribe(fn: () => void): () => void {
+    this.listeners.add(fn)
+    return () => this.listeners.delete(fn)
+  }
+
+  /**
+   * Monotonic registration version for uSES getSnapshot.
+   * @returns current version.
+   */
+  getVersion(): number {
+    return this.version
+  }
+
+  private bump(): void {
+    this.version += 1
+    for (const fn of this.listeners) fn()
+  }
+}
diff --git a/packages/client/ui-conversation/src/css-modules.d.ts b/packages/client/ui-conversation/src/css-modules.d.ts
new file mode 100644
index 0000000000..bc5e482353
--- /dev/null
+++ b/packages/client/ui-conversation/src/css-modules.d.ts
@@ -0,0 +1,6 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css'
diff --git a/packages/client/ui-conversation/src/index.ts b/packages/client/ui-conversation/src/index.ts
new file mode 100644
index 0000000000..ccb2f11242
--- /dev/null
+++ b/packages/client/ui-conversation/src/index.ts
@@ -0,0 +1,10 @@
+/**
+ * Conversation plugin, node half. Pure UI plugin: the empty apply exists so
+ * the plugin appears in the host cordis.yml / Loader (load and lifecycle
+ * follow the host; the browser half ships via exports["./client"], discovered
+ * through the package.json dshClient declaration). Contract: api-contracts
+ * v3 sections 0.3 and 7.
+ */
+
+/** Host plugin body — no host-side behavior for the conversation plugin. */
+export function apply(): void {}
diff --git a/packages/client/ui-conversation/src/invariant.ts b/packages/client/ui-conversation/src/invariant.ts
new file mode 100644
index 0000000000..3100170938
--- /dev/null
+++ b/packages/client/ui-conversation/src/invariant.ts
@@ -0,0 +1,33 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-conversation`.
+ * @module @deepseek-ai/dsh-client-ui-conversation/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-conversation'
+
+/** Cordis companion plugin name. */
+export const name = 'client-ui-conversation-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: the conversation service emits no cordis events — its
+ * view and toolview registries notify through package-local subscribe faces
+ * whose ordering (synchronous version bump before notification) is exercised
+ * directly by the behavior specs, and the per-scope store accounts are owned
+ * mutable state with no cross-plugin observer to contradict.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/client/ui-conversation/tests/apply-inject.spec.tsx b/packages/client/ui-conversation/tests/apply-inject.spec.tsx
new file mode 100644
index 0000000000..2c0166c7de
--- /dev/null
+++ b/packages/client/ui-conversation/tests/apply-inject.spec.tsx
@@ -0,0 +1,276 @@
+// @vitest-environment jsdom
+// apply inject factories exercised end to end: the conversation slot surface
+// (ancestry feed, views triple, active view, composer choreography incl.
+// optimistic clear + failure restore, renderView chrome assembly, watch-driven
+// open), the details surface, and the empty-state surface (cwd derivation
+// cache). Complements chat-apply.spec.tsx, which stops at registration.
+
+import { Context } from 'cordis'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, render } from '@testing-library/react'
+import { createElement } from 'react'
+import { createSnapshotStore, bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
+import { SlotsService, scopeOf } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ConversationSnapshot, SessionId, SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
+import { apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ConversationService, ViewEntry } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { SessionBinding } from '@deepseek-ai/dsh-client-ui-slots'
+import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
+
+afterEach(cleanup)
+
+const ROOT = 'root-1' as SessionId
+
+const SCOPE_TAG: symbol = (() => {
+  const recorded: (string | symbol)[] = []
+  const spy = new Proxy(new Context(), {
+    get(target, prop, receiver) {
+      recorded.push(prop)
+      return Reflect.get(target, prop, receiver)
+    },
+  })
+  void scopeOf(spy as Context)
+  const symbol = recorded.find((p): p is symbol => typeof p === 'symbol')
+  if (symbol === undefined) throw new Error('scopeOf probe recorded no symbol read')
+  return symbol
+})()
+
+function snapshotBase(): ConversationSnapshot {
+  return {
+    sessionId: ROOT, nodes: [], foldDegraded: false, partial: null, runningCalls: [],
+    pending: [], running: false, removed: false, openState: 'open', openError: null,
+    hasMore: false, loadingOlder: false, promptError: null, lastAgentError: null,
+  } as ConversationSnapshot
+}
+
+async function bench() {
+  const ctx = new Context()
+  const slotsFiber = ctx.plugin(SlotsService)
+  await slotsFiber.await()
+
+  const listStore = createSnapshotStore<SessionListState>({
+    ids: [ROOT],
+    byId: { [ROOT]: { id: ROOT, title: 'R', cwd: '/proj', running: false, updatedAt: 1 } },
+  })
+  const snap = snapshotBase()
+  const sessionFake = {
+    getSnapshot: () => snap,
+    subscribe: () => () => {},
+    useSelector: undefined as unknown,
+    open: vi.fn(() => Promise.resolve()),
+    loadOlder: vi.fn(() => Promise.resolve()),
+    prompt: vi.fn<() => Promise<{ ok: boolean; value?: object; error?: { code: string; message: string } }>>(
+      () => Promise.resolve({ ok: true, value: { accepted: true } })),
+    cancel: vi.fn<() => Promise<{ ok: boolean; value?: object; error?: { code: string; message: string } }>>(
+      () => Promise.resolve({ ok: true, value: { accepted: true } })),
+  }
+  sessionFake.useSelector = bindSnapshotSelector(sessionFake as never)
+  const scopes = new Map<SessionId, Context>()
+  const mint = (id: SessionId): Context => {
+    let scoped = scopes.get(id)
+    if (scoped === undefined) {
+      scoped = ctx.plugin(() => {}).ctx.extend({ [SCOPE_TAG]: id }) as Context
+      scopes.set(id, scoped)
+    }
+    return scoped
+  }
+  const sessionsFake = {
+    list: listStore,
+    manager: { get: () => sessionFake },
+    ancestry: (id: SessionId) => {
+      const s = listStore.getSnapshot().byId[id]
+      return s === undefined ? [] : [s]
+    },
+    scope: (id: SessionId) => mint(id),
+    create: vi.fn(() => Promise.resolve(ROOT)),
+  }
+  ctx.provide('sessions', sessionsFake)
+  const layoutFake = {
+    current: createSnapshotStore<{ sessionId?: SessionId; viewFor: Record<string, string> }>({ viewFor: {} }),
+    open: vi.fn(), openView: vi.fn(), openDetails: vi.fn(), closeDetails: vi.fn(),
+  }
+  ctx.provide('layout', layoutFake)
+  ctx.provide('i18n', { bind: () => (key: string) => key })
+
+  const slots = ctx.get('slots') as SlotsService
+  slots.define('conversation', { kind: 'single', scope: 'session' })
+  slots.define('details', { kind: 'single', scope: 'session' })
+  slots.define('conversation.empty', { kind: 'single', scope: 'root' })
+
+  const fiber = ctx.plugin({ inject: [...inject], apply })
+  await fiber.await()
+
+  const binding: SessionBinding = {
+    sessionId: ROOT as never,
+    session: { useSelector: sessionFake.useSelector } as never,
+    ctx: mint(ROOT) as never,
+  }
+  const entryOf = (key: 'conversation' | 'details' | 'conversation.empty') => {
+    const entries = slots.entries(key)
+    return entries[0]! as { options: { inject: (b: unknown) => Record<string, unknown> } }
+  }
+  return { ctx, slots, binding, sessionFake, sessionsFake, layoutFake, mint, entryOf }
+}
+
+describe('conversation slot inject surface', () => {
+  it('assembles the full surface and pulls history through the watch signal', async () => {
+    const b = await bench()
+    const injected = b.entryOf('conversation').options.inject(b.binding) as {
+      useAncestry: () => readonly { id: SessionId }[]
+      views: { list(): readonly ViewEntry[]; version(): number; subscribe(fn: () => void): () => void }
+      useActiveView: () => string | undefined
+      composer: { useDraft: () => string; setDraft(t: string): void; send(m: string): void; stop(): void }
+      actions: { openView(v: string): void; open(id: SessionId): void }
+      renderView: (entry: ViewEntry) => unknown
+    }
+    expect(b.sessionFake.open).toHaveBeenCalledTimes(1)
+    expect(injected.views.list().map(v => v.id)).toEqual(['chat'])
+    injected.actions.openView('chat')
+    expect(b.layoutFake.openView).toHaveBeenCalledWith(ROOT, 'chat')
+    injected.actions.open(ROOT)
+    expect(b.layoutFake.open).toHaveBeenCalledWith(ROOT)
+  })
+
+  it('composer send trims, optimistically clears, and restores on failure; stop swallows rejection', async () => {
+    const b = await bench()
+    const injected = b.entryOf('conversation').options.inject(b.binding) as {
+      composer: { setDraft(t: string): void; send(m: 'queue'): void; stop(): void }
+    }
+    const scoped = b.mint(ROOT).get('conversation') as ConversationService
+    // Whitespace-only draft: no send.
+    scoped.drafts.set('   ')
+    injected.composer.send('queue')
+    expect(b.sessionFake.prompt).not.toHaveBeenCalled()
+    // Success: cleared and stays cleared.
+    injected.composer.setDraft('hello')
+    injected.composer.send('queue')
+    expect(scoped.drafts.getSnapshot()).toBe('')
+    await Promise.resolve()
+    expect(b.sessionFake.prompt).toHaveBeenCalledWith([{ type: 'text', text: 'hello' }], 'queue')
+    // Failure: restored (draft still empty when the rejection lands).
+    b.sessionFake.prompt.mockResolvedValueOnce({ ok: false, error: { code: 'agent-busy', message: 'b' } })
+    injected.composer.setDraft('retry me')
+    injected.composer.send('queue')
+    await vi.waitFor(() => {
+      expect(scoped.drafts.getSnapshot()).toBe('retry me')
+    })
+    // Failure with new typing: no clobber.
+    b.sessionFake.prompt.mockResolvedValueOnce({ ok: false, error: { code: 'agent-busy', message: 'b' } })
+    injected.composer.send('queue')
+    injected.composer.setDraft('typed during flight')
+    await new Promise(r => setTimeout(r, 0))
+    expect(scoped.drafts.getSnapshot()).toBe('typed during flight')
+    // Stop failure is swallowed (promptError owns the surface).
+    b.sessionFake.cancel.mockResolvedValueOnce({ ok: false, error: { code: 'internal', message: 'x' } })
+    injected.composer.stop()
+    await new Promise(r => setTimeout(r, 0))
+  })
+
+  it('view actions forward: openDetails writes selection through the scoped service, loadOlder hits the session', async () => {
+    const b = await bench()
+    const injected = b.entryOf('conversation').options.inject(b.binding) as {
+      // viewProps rides renderView's closure; reach the actions through a rendered entry.
+      renderView: (entry: ViewEntry) => React.ReactNode
+    }
+    let captured: { openDetails(t: { turnSeq: number; callId?: string }): void; loadOlder(): void } | undefined
+    const Probe = (p: { actions: typeof captured }) => {
+      captured = p.actions
+      return null
+    }
+    render(createElement('div', null, injected.renderView({
+      id: 'chat', label: 'Chat', component: Probe,
+    } as unknown as ViewEntry)))
+    captured!.openDetails({ turnSeq: 2, callId: 'c1' })
+    expect(b.layoutFake.openDetails).toHaveBeenCalledTimes(1)
+    const scoped = b.mint(ROOT).get('conversation') as import('@deepseek-ai/dsh-client-ui-conversation/client').ConversationService
+    expect(scoped.selection.getSnapshot()).toEqual({ turnSeq: 2, callId: 'c1' })
+    captured!.loadOlder()
+    expect(b.sessionFake.loadOlder).toHaveBeenCalledTimes(1)
+  })
+
+  it('renderView mounts chrome header/footer around the view body', async () => {
+    const b = await bench()
+    const injected = b.entryOf('conversation').options.inject(b.binding) as {
+      renderView: (entry: ViewEntry) => React.ReactNode
+    }
+    const entry = {
+      id: 'chat', label: 'Chat',
+      component: () => createElement('div', { 'data-testid': 'body' }),
+      chrome: {
+        header: () => createElement('div', { 'data-testid': 'hd' }),
+        footer: () => createElement('div', { 'data-testid': 'ft' }),
+      },
+    } as unknown as ViewEntry
+    const view = render(createElement('div', null, injected.renderView(entry)))
+    expect(view.getByTestId('hd')).toBeTruthy()
+    expect(view.getByTestId('body')).toBeTruthy()
+    expect(view.getByTestId('ft')).toBeTruthy()
+    // Ancestry and draft/active-view hooks execute inside a component tree.
+    const HookProbe = () => {
+      const injected2 = b.entryOf('conversation').options.inject(b.binding) as {
+        useAncestry: () => readonly { title: string }[]
+        useActiveView: () => string | undefined
+        composer: { useDraft: () => string }
+      }
+      const chain = injected2.useAncestry()
+      const active = injected2.useActiveView()
+      const draft = injected2.composer.useDraft()
+      return createElement('i', { 'data-testid': 'probe' }, `${chain.length}|${active ?? 'none'}|${draft}`)
+    }
+    const probe = render(createElement(HookProbe))
+    // Draft content carries over from the composer case (per-scope store is
+    // process-resident); the probe asserts hook wiring, not draft value.
+    expect(probe.getByTestId('probe').textContent).toMatch(/^1\|none\|/)
+    // A list-store update while mounted drives the ancestry selector's
+    // shallowEqual arm (same derived chain → short-circuit, no re-render churn).
+    await act(async () => {
+      b.sessionsFake.list.update((d: { byId: Record<string, { updatedAt: number }> }) => {
+        d.byId[ROOT]!.updatedAt = 2
+      })
+    })
+    expect(probe.getByTestId('probe').textContent).toMatch(/^1\|none\|/)
+    // The views read-face triple forwards to the service registry.
+    const injected3 = b.entryOf('conversation').options.inject(b.binding) as {
+      views: { list(): readonly { id: string }[]; subscribe(fn: () => void): () => void; version(): number }
+    }
+    expect(injected3.views.list().map(v => v.id)).toEqual(['chat'])
+    const beforeVersion = injected3.views.version()
+    const listener = vi.fn()
+    const unsub = injected3.views.subscribe(listener)
+    const conversation = b.ctx.get('conversation') as import('@deepseek-ai/dsh-client-ui-conversation/client').ConversationService
+    const offExtra = conversation.registerView({ id: 'chat2', label: 'X', component: () => null } as never)
+    expect(listener).toHaveBeenCalled()
+    expect(injected3.views.version()).toBeGreaterThan(beforeVersion)
+    offExtra()
+    unsub()
+  })
+})
+
+describe('details and empty inject surfaces', () => {
+  it('details surface wires selection and closeDetails', async () => {
+    const b = await bench()
+    const injected = b.entryOf('details').options.inject(b.binding) as {
+      useSelection: unknown
+      actions: { closeDetails(): void }
+    }
+    expect(injected.useSelection).toBeTypeOf('function')
+    injected.actions.closeDetails()
+    expect(b.layoutFake.closeDetails).toHaveBeenCalledTimes(1)
+  })
+
+  it('empty surface derives the deduped cwd set with a per-state cache and starts sessions', async () => {
+    const b = await bench()
+    const injected = b.entryOf('conversation.empty').options.inject({ ctx: b.ctx }) as {
+      useCwds: (sel: (s: readonly string[]) => unknown, eq?: unknown) => unknown
+      actions: { startSession(opts: { text: string; mode: 'queue' }): Promise<void> }
+    }
+    const CwdsProbe = () => {
+      const cwds = injected.useCwds(s => s) as readonly string[]
+      return createElement('i', { 'data-testid': 'cwds' }, cwds.join(','))
+    }
+    const view = render(createElement(CwdsProbe))
+    expect(view.getByTestId('cwds').textContent).toBe('/proj')
+    await injected.actions.startSession({ text: 'go', mode: 'queue' })
+    expect(b.sessionsFake.create).toHaveBeenCalled()
+  })
+})
diff --git a/packages/client/ui-conversation/tests/chat-apply.spec.tsx b/packages/client/ui-conversation/tests/chat-apply.spec.tsx
new file mode 100644
index 0000000000..e6ce83edc5
--- /dev/null
+++ b/packages/client/ui-conversation/tests/chat-apply.spec.tsx
@@ -0,0 +1,105 @@
+// @vitest-environment jsdom
+// apply wiring: services provided, chat view + footer chrome registered, the
+// three slot registrations land against ui-layout-shaped specs, and the bash
+// samples resolve differentially (sub-session default scope). Full-chain
+// rendering belongs to the shell e2e; this spec stops at the assembly surface.
+
+import { Context } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SessionId, SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
+import { apply, inject, ToolViewRegistry } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ConversationService } from '@deepseek-ai/dsh-client-ui-conversation/client'
+// Type-only: pulls ui-layout's SlotMap declaration merge into this spec's
+// program so the slot keys below typecheck in the client lane.
+import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
+
+const ROOT = 'root-1' as SessionId
+const CHILD = 'child-1' as SessionId
+
+async function bench() {
+  const ctx = new Context()
+  const slotsFiber = ctx.plugin(SlotsService)
+  await slotsFiber.await()
+
+  const listStore = createSnapshotStore<SessionListState>({
+    ids: [ROOT, CHILD],
+    byId: {
+      [ROOT]: { id: ROOT, title: 'R', running: false, updatedAt: 1 },
+      [CHILD]: { id: CHILD, title: 'C', parentId: ROOT, running: false, updatedAt: 2 },
+    },
+  })
+  const sessionsFake = {
+    list: listStore,
+    manager: { get: vi.fn() },
+    ancestry: () => [],
+    scope: () => undefined,
+    create: vi.fn(),
+  }
+  ctx.provide('sessions', sessionsFake)
+  ctx.provide('layout', {
+    current: createSnapshotStore<{ viewFor: Record<string, string> }>({ viewFor: {} }),
+    open: vi.fn(), openView: vi.fn(), openDetails: vi.fn(), closeDetails: vi.fn(),
+  })
+  ctx.provide('i18n', { bind: () => (key: string) => key })
+
+  // Specs owned by ui-layout in production; declared here so registrations land.
+  const slots = ctx.get('slots') as SlotsService
+  slots.define('conversation', { kind: 'single', scope: 'session' })
+  slots.define('details', { kind: 'single', scope: 'session' })
+  slots.define('conversation.empty', { kind: 'single', scope: 'root' })
+
+  const fiber = ctx.plugin({ inject: [...inject], apply })
+  return { ctx, fiber, slots }
+}
+
+describe('apply wiring', () => {
+  it('provides conversation and toolviews services', async () => {
+    const b = await bench()
+    await b.fiber.await()
+    expect(b.ctx.get('conversation')).toBeDefined()
+    expect(b.ctx.get('toolviews')).toBeInstanceOf(ToolViewRegistry)
+  })
+
+  it('registers the chat view with the stats footer', async () => {
+    const b = await bench()
+    await b.fiber.await()
+    const conversation = b.ctx.get('conversation') as ConversationService
+    const views = conversation.views()
+    expect(views.map((v) => v.id)).toEqual(['chat'])
+    expect(views[0]?.chrome?.footer).toBeDefined()
+  })
+
+  it('occupies conversation/details/conversation.empty with inject factories', async () => {
+    const b = await bench()
+    await b.fiber.await()
+    for (const key of ['conversation', 'details', 'conversation.empty'] as const) {
+      const entries = b.slots.entries(key)
+      expect(entries, key).toHaveLength(1)
+      expect((entries[0]!.options as { inject?: unknown }).inject, key).toBeTypeOf('function')
+    }
+  })
+
+  it('bash samples resolve differentially: scoped row for sub-sessions, global for roots', async () => {
+    const b = await bench()
+    await b.fiber.await()
+    const toolviews = b.ctx.get('toolviews') as ToolViewRegistry
+    const forChild = toolviews.resolve('bash', CHILD)
+    const forRoot = toolviews.resolve('bash', ROOT)
+    expect(forChild).toBeDefined()
+    expect(forRoot).toBeDefined()
+    expect(forChild!.component).not.toBe(forRoot!.component)
+  })
+
+  it('plugin fiber disposal collects every registration (unload cascade)', async () => {
+    const b = await bench()
+    await b.fiber.await()
+    await b.fiber.dispose()
+    expect(b.slots.entries('conversation')).toHaveLength(0)
+    expect(b.slots.entries('details')).toHaveLength(0)
+    expect(b.slots.entries('conversation.empty')).toHaveLength(0)
+    expect(b.ctx.get('conversation')).toBeUndefined()
+    expect(b.ctx.get('toolviews')).toBeUndefined()
+  })
+})
diff --git a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
new file mode 100644
index 0000000000..23854b643b
--- /dev/null
+++ b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
@@ -0,0 +1,156 @@
+// @vitest-environment jsdom
+// Remaining chat branch tails: MessageItem context/unknown/steering arms,
+// ToolViewOutlet inject cache + crash fallback + retry, StatsLine no-cache
+// join, PendingCard reason strip, AssistantMarkdown single-line reasoning,
+// ChatView view-body fallbacks, and apply's action lambdas.
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render } from '@testing-library/react'
+import { act } from '@testing-library/react'
+import type { SessionId, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import type { RpcId } from '@deepseek-ai/dsh-client-connection/client'
+import { bindSnapshotSelector, createSessionProvider } from '@deepseek-ai/dsh-client-web-react'
+import type { SessionBinding as ReactSessionBinding, UseSession } from '@deepseek-ai/dsh-client-web-react'
+import { ToolViewRegistry } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ToolViewProps, Translate } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { MessageItem } from '../src/client/chat/MessageItem.tsx'
+import { PendingCard } from '../src/client/chat/PendingCard.tsx'
+import { AssistantMarkdown } from '../src/client/chat/AssistantMarkdown.tsx'
+import { StatsLine } from '../src/client/chat/StatsLine.tsx'
+import { ToolViewOutlet } from '../src/client/chat/ToolViewOutlet.tsx'
+
+afterEach(cleanup)
+
+const SID = 's1' as SessionId
+
+const result = (callId: string): ToolResultNode => ({
+  kind: 'tool-result', seq: 3, callId,
+  call: { name: 'bash', argsRaw: '{"command":"x"}' },
+  content: [], isError: false, callView: null, resultView: null,
+})
+
+const viewProps = (): ToolViewProps => ({
+  callId: 'c1', toolName: 'bash', block: result('c1'),
+  useSession: (() => { throw new Error('unused') }) as unknown as UseSession,
+  actions: { openDetails: vi.fn() },
+  t: ((k: string) => k) as Translate,
+})
+
+describe('MessageItem arms', () => {
+  it('steering bubbles carry the interjection badge and non-text rest blocks', () => {
+    const view = render(
+      <MessageItem node={{
+        kind: 'steering', seq: 2, turn: 1, source: null,
+        content: [{ type: 'text', text: 'steer!' }, { type: 'image', data: 'x' }] as never,
+      } as never}
+      />,
+    )
+    expect(view.getByText('插话')).toBeTruthy()
+    expect(view.getByText('steer!')).toBeTruthy()
+    expect(view.getByText(/附加内容块/)).toBeTruthy()
+  })
+
+  it('context and unknown nodes render their JSON rows', () => {
+    const ctxView = render(
+      <MessageItem node={{ kind: 'context', seq: 3, content: [], source: null, meta: { k: 1 } } as never} />,
+    )
+    expect(ctxView.getByText(/上下文注入/)).toBeTruthy()
+    const unknownView = render(
+      <MessageItem node={{ kind: 'unknown', seq: 4, type: 'surface/next', data: { x: 1 } } as never} />,
+    )
+    expect(unknownView.getByText(/未知 surface 事件：surface\/next/)).toBeTruthy()
+  })
+})
+
+describe('small branch tails', () => {
+  it('PendingCard approval reason renders when present', () => {
+    const view = render(
+      <PendingCard item={{ kind: 'approval', rpcId: 'r1' as RpcId, approvalId: 'a1', toolName: 'rm', reason: 'careful' }} />,
+    )
+    expect(view.getByText('careful')).toBeTruthy()
+  })
+
+  it('AssistantMarkdown single-line reasoning summary skips the newline cut', () => {
+    const view = render(
+      <AssistantMarkdown blocks={[{ kind: 'reasoning', text: 'one-liner' }]} streaming={false} />,
+    )
+    expect(view.getByText('one-liner')).toBeTruthy()
+  })
+
+  it('StatsLine omits the cache-hit segment when no input accounting exists at all', () => {
+    // cacheHitPct is null only when input+cacheRead are both zero (pure
+    // output accounting) — any input makes it a real 0%.
+    const snap = {
+      nodes: [{ kind: 'assistant', seq: 1, turn: 1, step: 1, blocks: [], usage: { outputTokens: 10 } }],
+    }
+    const source = { getSnapshot: () => snap, subscribe: () => () => {} }
+    const view = render(
+      <StatsLine sessionId={SID} useSession={bindSnapshotSelector(source) as unknown as UseSession} />,
+    )
+    expect(view.getByText('10 tokens · 1 turns · 1 steps')).toBeTruthy()
+  })
+})
+
+describe('ToolViewOutlet dispatch', () => {
+  it('caches the inject factory per (registration x binding) and merges its props', () => {
+    const registry = new ToolViewRegistry()
+    const inject = vi.fn(() => ({ extra: 'injected' }))
+    registry.register('bash',
+      (p: ToolViewProps & { extra: string }) => <div data-testid="row">{p.extra}</div>,
+      { inject })
+    // InjectedRow reads the session binding from context: mount through the
+    // real SessionProvider so the (factory x binding) cache path executes.
+    const binding: ReactSessionBinding = {
+      sessionId: SID,
+      session: { useSelector: (() => { throw new Error('unused') }) as never },
+      ctx: {},
+    }
+    const Provider = createSessionProvider({
+      useCurrent: () => SID,
+      resolveBinding: () => binding,
+      renderBody: () => (
+        <ToolViewOutlet registry={registry} sessionId={SID} toolName="bash" viewProps={viewProps()} />
+      ),
+    })
+    const view = render(<Provider />)
+    expect(view.getByTestId('row').textContent).toBe('injected')
+    expect(inject).toHaveBeenCalledTimes(1)
+    // Remount against the SAME binding: cache hit, factory not re-run.
+    view.unmount()
+    const second = render(<Provider />)
+    expect(second.getByTestId('row').textContent).toBe('injected')
+    expect(inject).toHaveBeenCalledTimes(1)
+  })
+
+  it('a crashing custom row falls back to GenericToolCard and retries on re-registration', () => {
+    const registry = new ToolViewRegistry()
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {})
+    // React dev builds re-dispatch boundary-caught errors as window 'error'
+    // events (invokeGuardedCallback); swallow them so vitest sees the caught path.
+    const swallow = (e: Event): void => { e.preventDefault() }
+    window.addEventListener('error', swallow)
+    try {
+      const Bomb = () => { throw new Error('row bomb') }
+      registry.register('bash', Bomb as never)
+      const view = render(
+        <ToolViewOutlet registry={registry} sessionId={SID} toolName="bash" viewProps={viewProps()} />,
+      )
+      // Crash caught: generic row rendered instead.
+      expect(view.getByText('Bash')).toBeTruthy()
+      // A new registration bumps the version; the boundary retries the custom row.
+      act(() => { registry.register('bash', (() => <div data-testid="fixed" />) as never) })
+      expect(view.getByTestId('fixed')).toBeTruthy()
+    } finally {
+      window.removeEventListener('error', swallow)
+      consoleError.mockRestore()
+    }
+  })
+
+  it('registry miss renders the generic row directly', () => {
+    const registry = new ToolViewRegistry()
+    const view = render(
+      <ToolViewOutlet registry={registry} sessionId={SID} toolName="bash" viewProps={viewProps()} />,
+    )
+    expect(view.getByText('Bash')).toBeTruthy()
+  })
+})
diff --git a/packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx b/packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx
new file mode 100644
index 0000000000..63b76c86df
--- /dev/null
+++ b/packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx
@@ -0,0 +1,178 @@
+// @vitest-environment jsdom
+// StatsLine (chrome.footer first consumer): totals derivation + the RFC hard
+// acceptance — zero renders during streaming. Bash sample: differential
+// registry hits per session, teardown reverts to the generic row.
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render } from '@testing-library/react'
+import type {
+  AssistantMessageNode, ConversationSnapshot, SessionId, ToolResultNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
+import type { UseSession } from '@deepseek-ai/dsh-client-web-react'
+import type { ChromeProps, ToolViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { ToolViewRegistry } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { StatsLine, deriveStats } from '../src/client/chat/StatsLine.tsx'
+import { BashRow, ScopedBashRow, registerBashSamples } from '../src/client/toolviews/bash-sample.tsx'
+import { ToolViewOutlet } from '../src/client/chat/ToolViewOutlet.tsx'
+import { childSessionScope } from '../src/client/chat/register.ts'
+
+afterEach(cleanup)
+
+const SID = 's1' as SessionId
+
+const assistant = (seq: number, turn: number, usage?: unknown): AssistantMessageNode => ({
+  kind: 'assistant', seq, turn, step: seq, blocks: [{ kind: 'text', text: `t${seq}` }],
+  ...(usage === undefined ? {} : { usage }),
+})
+
+function snapshotBase(): ConversationSnapshot {
+  return {
+    sessionId: SID, nodes: [], foldDegraded: false, partial: null, runningCalls: [],
+    pending: [], running: false, removed: false, openState: 'open', openError: null,
+    hasMore: false, loadingOlder: false, promptError: null, lastAgentError: null,
+  }
+}
+
+function makeSource(init?: Partial<ConversationSnapshot>) {
+  let snap: ConversationSnapshot = { ...snapshotBase(), ...init }
+  const subs = new Set<() => void>()
+  return {
+    set(next: Partial<ConversationSnapshot>) {
+      snap = { ...snap, ...next }
+      for (const fn of [...subs]) fn()
+    },
+    source: {
+      getSnapshot: () => snap,
+      subscribe: (fn: () => void) => {
+        subs.add(fn)
+        return () => subs.delete(fn)
+      },
+    },
+  }
+}
+
+describe('deriveStats', () => {
+  it('folds turns/steps/tokens and cache hit percentage', () => {
+    const stats = deriveStats([
+      assistant(1, 1, { inputTokens: 100, outputTokens: 50, cacheReadTokens: 900 }),
+      assistant(2, 1, { inputTokens: 100, outputTokens: 50 }),
+      assistant(3, 2),
+    ])
+    expect(stats.turns).toBe(2)
+    expect(stats.steps).toBe(3)
+    expect(stats.tokens).toBe(1200)
+    expect(stats.cacheHitPct).toBe(82)
+  })
+
+  it('cache hit stays null with no cache accounting; non-assistant nodes ignored', () => {
+    const tool: ToolResultNode = {
+      kind: 'tool-result', seq: 5, callId: 'c', call: null, content: [],
+      isError: false, callView: null, resultView: null,
+    }
+    const stats = deriveStats([tool, assistant(1, 1)])
+    expect(stats.steps).toBe(1)
+    expect(stats.cacheHitPct).toBeNull()
+  })
+})
+
+describe('StatsLine', () => {
+  function props(source: { getSnapshot(): ConversationSnapshot; subscribe(fn: () => void): () => void }): ChromeProps {
+    return { sessionId: SID, useSession: bindSnapshotSelector(source) as unknown as UseSession }
+  }
+
+  it('renders the joined stats row and hides with zero steps', () => {
+    const { source } = makeSource({
+      nodes: [assistant(1, 1, { inputTokens: 10, outputTokens: 5, cacheReadTokens: 90 })],
+    })
+    const view = render(<StatsLine {...props(source)} />)
+    expect(view.getByText('cache hit 90% · 105 tokens · 1 turns · 1 steps')).toBeTruthy()
+    const empty = makeSource()
+    const emptyView = render(<StatsLine {...props(empty.source)} />)
+    expect(emptyView.container.textContent).toBe('')
+  })
+
+  it('renders ZERO times during streaming chunk frames (RFC hard acceptance)', () => {
+    const { set, source } = makeSource({ nodes: [assistant(1, 1)] })
+    let renders = 0
+    function Counting(p: ChromeProps) {
+      renders += 1
+      return <StatsLine {...p} />
+    }
+    render(<Counting {...props(source)} />)
+    const before = renders
+    // Chunk frames swap partial only; nodes keeps its reference (object-layer contract).
+    act(() => set({ partial: { turn: 1, step: 2, blocks: [{ kind: 'text', text: 'a' }] } }))
+    act(() => set({ partial: { turn: 1, step: 2, blocks: [{ kind: 'text', text: 'ab' }] } }))
+    act(() => set({ running: true }))
+    expect(renders).toBe(before)
+  })
+})
+
+describe('bash toolview samples', () => {
+  const result = (callId: string): ToolResultNode => ({
+    kind: 'tool-result', seq: 3, callId,
+    call: { name: 'bash', argsRaw: '{"command":"make build","description":"Build"}' },
+    content: [], isError: false, callView: null, resultView: null,
+  })
+
+  const viewProps = (openDetails = vi.fn()): ToolViewProps => ({
+    callId: 'c1', toolName: 'bash', block: result('c1'),
+    useSession: (() => { throw new Error('unused') }) as unknown as UseSession,
+    actions: { openDetails },
+    t: (k) => k,
+  })
+
+  function outlet(registry: ToolViewRegistry, sessionId: SessionId, p = viewProps()) {
+    return render(
+      <ToolViewOutlet registry={registry} sessionId={sessionId} toolName="bash" viewProps={p} />,
+    )
+  }
+
+  it('differential rendering: scoped row for the matching session, global elsewhere', () => {
+    const registry = new ToolViewRegistry()
+    registerBashSamples(registry, (id) => id === ('swarm' as SessionId))
+    const scoped = outlet(registry, 'swarm' as SessionId)
+    expect(scoped.container.querySelector('[data-sample="bash-scoped"]')).not.toBeNull()
+    const plain = outlet(registry, SID)
+    expect(plain.container.querySelector('[data-sample="bash-global"]')).not.toBeNull()
+  })
+
+  it('teardown removes both registrations and falls back to the generic row', () => {
+    const registry = new ToolViewRegistry()
+    const off = registerBashSamples(registry, () => true)
+    const view = outlet(registry, SID)
+    expect(view.container.querySelector('[data-sample="bash-scoped"]')).not.toBeNull()
+    act(() => off())
+    expect(view.container.querySelector('[data-sample]')).toBeNull()
+    expect(view.getByText('Bash')).toBeTruthy()
+  })
+
+  it('childSessionScope matches sub-sessions via the injected list read face', () => {
+    const child = 'child' as SessionId
+    const root = 'root' as SessionId
+    const scope = childSessionScope({
+      getSnapshot: () => ({
+        ids: [root, child],
+        byId: {
+          [root]: { id: root, title: 'r', running: false, updatedAt: 0 },
+          [child]: { id: child, title: 'c', parentId: root, running: false, updatedAt: 0 },
+        },
+      }),
+    })
+    expect(scope(child)).toBe(true)
+    expect(scope(root)).toBe(false)
+    expect(scope('gone' as SessionId)).toBe(false)
+  })
+
+  it('sample rows summarize the command and hand clicks to openDetails', () => {
+    const open = vi.fn()
+    const p = viewProps(open)
+    const global = render(<BashRow {...p} />)
+    expect(global.getByText('Build')).toBeTruthy()
+    fireEvent.click(global.getByText('Build'))
+    expect(open).toHaveBeenCalledTimes(1)
+    const scoped = render(<ScopedBashRow {...p} />)
+    expect(scoped.getByText('scoped')).toBeTruthy()
+  })
+})
diff --git a/packages/client/ui-conversation/tests/chat-tool-row.spec.tsx b/packages/client/ui-conversation/tests/chat-tool-row.spec.tsx
new file mode 100644
index 0000000000..d1858787a5
--- /dev/null
+++ b/packages/client/ui-conversation/tests/chat-tool-row.spec.tsx
@@ -0,0 +1,147 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render } from '@testing-library/react'
+
+afterEach(cleanup)
+import type { RunningToolCall, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import type { UseSession } from '@deepseek-ai/dsh-client-web-react'
+import { classifyTool, toolRowModel } from '../src/client/contract/tool-call-model.ts'
+import { ToolRow } from '../src/client/chat/ToolRow.tsx'
+import { GenericToolCard } from '../src/client/chat/GenericToolCard.tsx'
+import type { ToolViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+
+const running = (over?: Partial<RunningToolCall>): RunningToolCall => ({
+  callId: 'c1', name: 'bash', argsRaw: '{"command":"ls -la","description":"List files"}',
+  turn: 1, step: 1, callView: null, ...over,
+})
+
+const result = (over?: Partial<ToolResultNode>): ToolResultNode => ({
+  kind: 'tool-result', seq: 10, callId: 'c1',
+  call: { name: 'bash', argsRaw: '{"command":"ls -la","description":"List files"}' },
+  content: [], isError: false, callView: null, resultView: null, ...over,
+})
+
+describe('tool-call-model', () => {
+  it('classifies known tools and falls back to others', () => {
+    expect(classifyTool('bash')).toBe('bash')
+    expect(classifyTool('read')).toBe('read')
+    expect(classifyTool('web_fetch')).toBe('read')
+    expect(classifyTool('web_search')).toBe('search')
+    expect(classifyTool('grep')).toBe('search')
+    expect(classifyTool('todo_write')).toBe('others')
+  })
+
+  it('derives state across running/ok/error/interrupted', () => {
+    expect(toolRowModel('bash', running()).state).toBe('running')
+    expect(toolRowModel('bash', result()).state).toBe('ok')
+    expect(toolRowModel('bash', result({ isError: true })).state).toBe('error')
+    expect(toolRowModel('bash', result({ isError: true, error: { name: 'E', code: 'interrupted' } })).state).toBe('stopped')
+  })
+
+  it('derives the bash summary from description over command', () => {
+    const m = toolRowModel('bash', running())
+    expect(m.title).toBe('Bash')
+    expect(m.summary).toBe('List files')
+    expect(toolRowModel('bash', running({ argsRaw: '{"command":"pwd"}' })).summary).toBe('pwd')
+  })
+
+  it('keeps summaries single-line and falls back for opaque args', () => {
+    expect(toolRowModel('bash', running({ argsRaw: '{"command":"a\\nb"}' })).summary).toBe('a')
+    expect(toolRowModel('read', running({ name: 'read', argsRaw: '{"path":"/tmp/x.ts"}' })).summary).toBe('/tmp/x.ts')
+    // Others rows prefix the real tool name into the summary slot (figma-flows
+    // ruling: static "Tool call" title, name rides the mutable summary).
+    expect(toolRowModel('x', running({ argsRaw: '{"n":1}' })).summary).toBe('x · {"n":1}')
+    expect(toolRowModel('x', running({ argsRaw: 'not json' })).summary).toBe('x · not json')
+    expect(toolRowModel('x', running({ argsRaw: '' })).summary).toBe('x · c1')
+    expect(toolRowModel('', running({ argsRaw: '' })).summary).toBe('c1')
+  })
+
+  it('body pretty-prints JSON args, keeps raw non-JSON, null when empty', () => {
+    expect(toolRowModel('bash', running({ argsRaw: '{"a":1}' })).body).toBe('{\n  "a": 1\n}')
+    expect(toolRowModel('bash', running({ argsRaw: 'raw' })).body).toBe('raw')
+    expect(toolRowModel('bash', running({ argsRaw: '' })).body).toBeNull()
+    expect(toolRowModel('bash', result({ call: null })).body).toBeNull()
+  })
+})
+
+describe('ToolRow', () => {
+  const rowProps = {
+    variant: 'bash' as const, icon: <i data-testid="tool-icon" />, title: 'Bash',
+    summary: 'List files', body: '{\n  "a": 1\n}', state: 'ok' as const,
+  }
+
+  it('renders leading icon, title and summary while collapsed', () => {
+    const view = render(<ToolRow {...rowProps} />)
+    expect(view.queryByTestId('tool-icon')).not.toBeNull()
+    expect(view.getByText('Bash')).toBeTruthy()
+    expect(view.getByText('List files')).toBeTruthy()
+    expect(view.container.querySelector('[aria-expanded]')?.getAttribute('aria-expanded')).toBe('false')
+  })
+
+  it('expanding swaps the leading slot to a chevron, hides summary, shows body', () => {
+    const view = render(<ToolRow {...rowProps} />)
+    fireEvent.click(view.container.querySelector('button')!)
+    expect(view.queryByTestId('tool-icon')).toBeNull()
+    expect(view.container.querySelector('svg')).not.toBeNull()
+    expect(view.queryByText('List files')).toBeNull()
+    expect(view.getByText(/"a": 1/)).toBeTruthy()
+    fireEvent.click(view.container.querySelector('button')!)
+    expect(view.queryByTestId('tool-icon')).not.toBeNull()
+    expect(view.getByText('List files')).toBeTruthy()
+  })
+
+  it('running and error states replace the icon with a StateDot', () => {
+    const runningView = render(<ToolRow {...rowProps} state="running" />)
+    expect(runningView.queryByTestId('tool-icon')).toBeNull()
+    expect(runningView.container.querySelector('[data-state="running"]')).not.toBeNull()
+    const errorView = render(<ToolRow {...rowProps} state="error" />)
+    expect(errorView.queryByTestId('tool-icon')).toBeNull()
+  })
+
+  it('non-expandable rows render a passive leading slot', () => {
+    const view = render(<ToolRow {...rowProps} body={null} />)
+    expect(view.container.querySelector('button')).toBeNull()
+    expect(view.queryByTestId('tool-icon')).not.toBeNull()
+  })
+
+  it('row click hands off to onOpenDetails; the expand toggle does not', () => {
+    const open = vi.fn()
+    const view = render(<ToolRow {...rowProps} onOpenDetails={open} />)
+    fireEvent.click(view.getByText('List files'))
+    expect(open).toHaveBeenCalledTimes(1)
+    fireEvent.click(view.container.querySelector('button')!)
+    expect(open).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('GenericToolCard', () => {
+  const props = (toolName: string, block: RunningToolCall | ToolResultNode): ToolViewProps => ({
+    callId: 'c1', toolName, block,
+    useSession: (() => { throw new Error('unused') }) as unknown as UseSession,
+    actions: { openDetails: vi.fn() },
+    t: (k) => k,
+  })
+
+  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('List files')).toBeTruthy()
+    expect(view.container.querySelector('[data-variant="bash"]')).not.toBeNull()
+  })
+
+  it('unknown tools land on the others variant titled Tool call', () => {
+    const view = render(
+      <GenericToolCard {...props('todo_write', running({ name: 'todo_write', argsRaw: '{"note":"x"}' }))} />,
+    )
+    expect(view.getByText('Tool call')).toBeTruthy()
+    expect(view.container.querySelector('[data-variant="others"]')).not.toBeNull()
+    expect(view.container.querySelector('[data-state="running"]')).not.toBeNull()
+  })
+
+  it('row click reaches actions.openDetails', () => {
+    const p = props('bash', result())
+    const view = render(<GenericToolCard {...p} />)
+    fireEvent.click(view.getByText('List files'))
+    expect(p.actions.openDetails).toHaveBeenCalledTimes(1)
+  })
+})
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
new file mode 100644
index 0000000000..af4f80c0b4
--- /dev/null
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -0,0 +1,305 @@
+// @vitest-environment jsdom
+// ChatView behavior: flow derivation, streaming isolation (Profiler counts),
+// toolview dispatch and selection handoff — driven through a scripted
+// ObservableSnapshot fake, no wire.
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Profiler } from 'react'
+import { act, cleanup, fireEvent, render } from '@testing-library/react'
+import type {
+  AssistantMessageNode, ConversationNode, ConversationSnapshot, RunningToolCall, SessionId, ToolResultNode, UserMessageNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
+import type { UseSession } from '@deepseek-ai/dsh-client-web-react'
+import type { ConvViewProps, SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { ToolViewRegistry } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { createChatView } from '../src/client/chat/ChatView.tsx'
+import { deriveChatFlow, flowKeys } from '../src/client/chat/chat-flow.ts'
+
+afterEach(cleanup)
+
+const SID = 's1' as SessionId
+
+function snapshotBase(): ConversationSnapshot {
+  return {
+    sessionId: SID, nodes: [], foldDegraded: false, partial: null, runningCalls: [],
+    pending: [], running: false, removed: false, openState: 'open', openError: null,
+    hasMore: false, loadingOlder: false, promptError: null, lastAgentError: null,
+  }
+}
+
+/** Scripted snapshot source: set() swaps the top-level object like the real Session. */
+function makeSource(init?: Partial<ConversationSnapshot>) {
+  let snap: ConversationSnapshot = { ...snapshotBase(), ...init }
+  const subs = new Set<() => void>()
+  return {
+    set(next: Partial<ConversationSnapshot>) {
+      snap = { ...snap, ...next }
+      for (const fn of [...subs]) fn()
+    },
+    source: {
+      getSnapshot: () => snap,
+      subscribe: (fn: () => void) => {
+        subs.add(fn)
+        return () => subs.delete(fn)
+      },
+    },
+  }
+}
+
+const user = (seq: number, text: string): UserMessageNode => ({
+  kind: 'user', seq, content: [{ type: 'text', text }] as never, source: null,
+})
+const assistant = (seq: number, text: string): AssistantMessageNode => ({
+  kind: 'assistant', seq, turn: 1, step: 1, blocks: [{ kind: 'text', text }],
+})
+const toolResult = (seq: number, callId: string, name = 'bash'): ToolResultNode => ({
+  kind: 'tool-result', seq, callId,
+  call: { name, argsRaw: `{"command":"cmd-${callId}","description":"run ${callId}"}` },
+  content: [], isError: false, callView: null, resultView: null,
+})
+const runningCall = (callId: string, name = 'bash'): RunningToolCall => ({
+  callId, name, argsRaw: `{"command":"cmd-${callId}"}`, turn: 2, step: 1, callView: null,
+})
+
+function makeHarness(init?: Partial<ConversationSnapshot>) {
+  const { set, source } = makeSource(init)
+  const registry = new ToolViewRegistry()
+  const ChatView = createChatView({ toolviews: registry, t: (k) => k })
+  const openDetails = vi.fn<(t: SelectionTarget) => void>()
+  const loadOlder = vi.fn()
+  const selection = makeSelection()
+  const props: ConvViewProps = {
+    sessionId: SID,
+    useSession: bindSnapshotSelector(source) as unknown as UseSession,
+    useSelection: bindSnapshotSelector(selection.source),
+    actions: { openDetails, loadOlder },
+    slots: { renderSlot: () => null } as never,
+  }
+  return { set, registry, ChatView, props, openDetails, loadOlder, setSelection: selection.set }
+}
+
+function makeSelection() {
+  let sel: SelectionTarget | null = null
+  const subs = new Set<() => void>()
+  return {
+    set(next: SelectionTarget | null) {
+      sel = next
+      for (const fn of [...subs]) fn()
+    },
+    source: {
+      getSnapshot: () => sel,
+      subscribe: (fn: () => void) => {
+        subs.add(fn)
+        return () => subs.delete(fn)
+      },
+    },
+  }
+}
+
+describe('chat-flow derivation', () => {
+  it('groups consecutive tool results and keeps stable keys', () => {
+    const nodes: ConversationNode[] = [
+      user(1, 'hi'), assistant(2, 'let me look'), toolResult(3, 'a'), toolResult(4, 'b'),
+      assistant(5, 'found'), toolResult(6, 'c'),
+    ]
+    const items = deriveChatFlow(nodes)
+    expect(items.map((i) => i.kind)).toEqual(['node', 'node', 'tool-group', 'node', 'tool-group'])
+    const group = items[2]!
+    expect(group.kind === 'tool-group' && group.results.map((r) => r.callId)).toEqual(['a', 'b'])
+    expect(flowKeys(items)).toBe('n1|n2|g3|n5|g6')
+    expect(flowKeys(deriveChatFlow([...nodes, toolResult(7, 'd')]))).toBe('n1|n2|g3|n5|g6')
+  })
+})
+
+describe('ChatView', () => {
+  it('a windowless tool result (call head truncated) renders with an empty tool name', () => {
+    const h = makeHarness({
+      nodes: [{ ...toolResult(3, 'w1'), call: null }],
+    })
+    const view = render(<h.ChatView {...h.props} />)
+    // classifyTool('') → others; the summary slot falls back to the callId.
+    expect(view.container.querySelector('[data-variant="others"]')).not.toBeNull()
+    expect(view.getByText('w1')).toBeTruthy()
+  })
+
+  it('prepend keeps the viewport anchored when the reader is NOT at the bottom (no lastKey force)', () => {
+    // Covers the prepend early-return arm where lastItem exists but the key
+    // path is not taken (anchor branch wins before the appended-user check).
+    const h = makeHarness({ nodes: [user(9, 'late')], hasMore: true })
+    const view = render(<h.ChatView {...h.props} />)
+    const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement
+    Object.defineProperty(scroller, 'scrollHeight', { value: 800, writable: true })
+    Object.defineProperty(scroller, 'clientHeight', { value: 200, writable: true })
+    scroller.scrollTop = 50
+    fireEvent.scroll(scroller)
+    fireEvent.click(view.getByText('加载更早'))
+    Object.defineProperty(scroller, 'scrollHeight', { value: 1300, writable: true })
+    act(() => h.set({ nodes: [assistant(2, 'older'), user(9, 'late')] }))
+    expect(scroller.scrollTop).toBe(550) // 50 + (1300 - 800)
+  })
+
+  it('renders the fixture main line: bubble, narration, grouped tool rows', () => {
+    const h = makeHarness({
+      nodes: [user(1, 'do the thing'), assistant(2, 'running tools'), toolResult(3, 'a'), toolResult(4, 'b')],
+    })
+    const view = render(<h.ChatView {...h.props} />)
+    expect(view.getByText('do the thing')).toBeTruthy()
+    expect(view.getByText('running tools')).toBeTruthy()
+    expect(view.getAllByText('Bash')).toHaveLength(2)
+    expect(view.getByText('run a')).toBeTruthy()
+  })
+
+  it('streaming partial frames re-render only the tail (Profiler count)', () => {
+    const h = makeHarness({
+      nodes: [user(1, 'q'), assistant(2, 'old answer'), toolResult(3, 'a')],
+    })
+    let renders = 0
+    const counting = (
+      <Profiler id="chat" onRender={() => { renders += 1 }}>
+        <h.ChatView {...h.props} />
+      </Profiler>
+    )
+    const view = render(counting)
+    const before = renders
+    const beforeHtml = view.container.querySelector('[class*="toolGroup"]')!.innerHTML
+    act(() => {
+      h.set({ partial: { turn: 2, step: 1, blocks: [{ kind: 'text', text: 'streaming…' }] } })
+    })
+    act(() => {
+      h.set({ partial: { turn: 2, step: 1, blocks: [{ kind: 'text', text: 'streaming… more' }] } })
+    })
+    expect(view.getByText('streaming… more')).toBeTruthy()
+    // Each chunk commits exactly one profiler pass (the tail), never a full-tree storm.
+    expect(renders - before).toBe(2)
+    expect(view.container.querySelector('[class*="toolGroup"]')!.innerHTML).toBe(beforeHtml)
+  })
+
+  it('streaming leaves neighbor tool rows and history items at zero re-renders', () => {
+    const h = makeHarness({
+      nodes: [user(1, 'q'), assistant(2, 'old'), toolResult(3, 'a')],
+    })
+    let rowRenders = 0
+    h.registry.register('bash', () => {
+      rowRenders += 1
+      return <div data-testid="counting-row" />
+    })
+    const view = render(<h.ChatView {...h.props} />)
+    expect(view.getByTestId('counting-row')).toBeTruthy()
+    const afterMount = rowRenders
+    act(() => {
+      h.set({ partial: { turn: 2, step: 1, blocks: [{ kind: 'text', text: 'chunk1' }] } })
+    })
+    act(() => {
+      h.set({ partial: { turn: 2, step: 1, blocks: [{ kind: 'text', text: 'chunk1 chunk2' }] } })
+    })
+    expect(rowRenders).toBe(afterMount)
+  })
+
+  it('tool row expands to the args body via the leading slot toggle', () => {
+    const h = makeHarness({ nodes: [toolResult(3, 'a')] })
+    const view = render(<h.ChatView {...h.props} />)
+    expect(view.queryByText(/"command": "cmd-a"/)).toBeNull()
+    fireEvent.click(view.container.querySelector('button[aria-expanded]')!)
+    expect(view.getByText(/"command": "cmd-a"/)).toBeTruthy()
+  })
+
+  it('clicking a tool row opens details with callId and toolName; selection paints the outline', () => {
+    const h = makeHarness({ nodes: [toolResult(3, 'a')] })
+    const view = render(<h.ChatView {...h.props} />)
+    fireEvent.click(view.getByText('run a'))
+    expect(h.openDetails).toHaveBeenCalledWith({ turnSeq: 3, callId: 'a', toolName: 'bash' })
+    expect(view.container.querySelector('[data-selected]')).toBeNull()
+    act(() => h.setSelection({ turnSeq: 3, callId: 'a', toolName: 'bash' }))
+    expect(view.container.querySelector('[data-selected]')).not.toBeNull()
+  })
+
+  it('running calls render as a live tool group with the running state', () => {
+    const h = makeHarness({ runningCalls: [runningCall('r1')], running: true })
+    const view = render(<h.ChatView {...h.props} />)
+    expect(view.container.querySelector('[data-state="running"]')).not.toBeNull()
+    expect(view.getByText('cmd-r1')).toBeTruthy()
+  })
+
+  it('a scoped toolview registration takes over rendering for its session only', () => {
+    const h = makeHarness({ nodes: [toolResult(3, 'a')] })
+    h.registry.register('bash', () => <div data-testid="custom-bash" />, { scope: (id) => id === SID })
+    const view = render(<h.ChatView {...h.props} />)
+    expect(view.getByTestId('custom-bash')).toBeTruthy()
+  })
+
+  it('unregistering a toolview falls back to the generic row live', () => {
+    const h = makeHarness({ nodes: [toolResult(3, 'a')] })
+    const off = h.registry.register('bash', () => <div data-testid="custom-bash" />)
+    const view = render(<h.ChatView {...h.props} />)
+    expect(view.getByTestId('custom-bash')).toBeTruthy()
+    act(() => off())
+    expect(view.queryByTestId('custom-bash')).toBeNull()
+    expect(view.getByText('Bash')).toBeTruthy()
+  })
+
+  it('prepend compensates scrollTop by the height delta; a trailing user node force-scrolls', () => {
+    const h = makeHarness({ nodes: [user(5, 'later'), assistant(6, 'a')], hasMore: true })
+    const view = render(<h.ChatView {...h.props} />)
+    const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement
+    // jsdom has no layout: fake the metrics the anchor math reads.
+    Object.defineProperty(scroller, 'scrollHeight', { value: 1000, writable: true })
+    Object.defineProperty(scroller, 'clientHeight', { value: 400, writable: true })
+    // Arm the paging anchor, then deliver an older page (head seq decreases).
+    fireEvent.click(view.getByText('加载更早'))
+    Object.defineProperty(scroller, 'scrollHeight', { value: 1600, writable: true })
+    act(() => h.set({ nodes: [user(1, 'old'), assistant(2, 'b'), user(5, 'later'), assistant(6, 'a')] }))
+    expect(scroller.scrollTop).toBe(600) // 0 + (1600 - 1000)
+    // A new trailing user bubble (own words) force-scrolls to the bottom.
+    act(() => h.set({ nodes: [user(1, 'old'), assistant(2, 'b'), user(5, 'later'), assistant(6, 'a'), user(9, 'mine')] }))
+    expect(scroller.scrollTop).toBe(1600)
+  })
+
+  it('scrolling away disables follow and shows the back-to-bottom button; clicking returns', () => {
+    const h = makeHarness({ nodes: [user(1, 'q'), assistant(2, 'a')] })
+    const view = render(<h.ChatView {...h.props} />)
+    const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement
+    Object.defineProperty(scroller, 'scrollHeight', { value: 1000, writable: true })
+    Object.defineProperty(scroller, 'clientHeight', { value: 300, writable: true })
+    scroller.scrollTop = 100 // far from bottom
+    fireEvent.scroll(scroller)
+    const backButton = view.getByLabelText('回到底部')
+    expect(backButton).toBeTruthy()
+    // Streaming growth must NOT drag a scrolled-away reader down.
+    act(() => h.set({ partial: { turn: 1, step: 1, blocks: [{ kind: 'text', text: 'grow' }] } }))
+    expect(scroller.scrollTop).toBe(100)
+    fireEvent.click(backButton)
+    expect(scroller.scrollTop).toBe(1000)
+    // At the bottom again: follow re-arms and the button unmounts.
+    expect(view.queryByLabelText('回到底部')).toBeNull()
+  })
+
+  it('paging button loads older and shows its busy label', () => {
+    const h = makeHarness({ nodes: [user(5, 'later')], hasMore: true })
+    const view = render(<h.ChatView {...h.props} />)
+    fireEvent.click(view.getByText('加载更早'))
+    expect(h.loadOlder).toHaveBeenCalledTimes(1)
+    act(() => h.set({ loadingOlder: true }))
+    expect(view.getByText('加载中…')).toBeTruthy()
+  })
+
+  it('shows open error and loading states', () => {
+    const h = makeHarness({
+      openState: 'error',
+      openError: { code: 'internal', message: 'boom' } as never,
+    })
+    const view = render(<h.ChatView {...h.props} />)
+    expect(view.getByText(/历史加载失败：boom/)).toBeTruthy()
+    const loading = makeHarness({ openState: 'loading' })
+    const lv = render(<loading.ChatView {...loading.props} />)
+    expect(lv.getByText('载入历史…')).toBeTruthy()
+  })
+
+  it('pending interactions render placeholder cards', () => {
+    const h = makeHarness({
+      pending: [{ kind: 'approval', rpcId: 'r1' as never, approvalId: 'ap1', toolName: 'bash' }],
+    })
+    const view = render(<h.ChatView {...h.props} />)
+    expect(view.getByText(/等待审批/)).toBeTruthy()
+  })
+})
diff --git a/packages/client/ui-conversation/tests/coverage-tails.spec.tsx b/packages/client/ui-conversation/tests/coverage-tails.spec.tsx
new file mode 100644
index 0000000000..2bdcb52902
--- /dev/null
+++ b/packages/client/ui-conversation/tests/coverage-tails.spec.tsx
@@ -0,0 +1,127 @@
+// @vitest-environment jsdom
+// Branch tails the acceptance specs do not reach: ToolRow stopped-state dot,
+// PendingCard question arm, bash sample error pill, registry disposer
+// idempotence re-entry, register.ts explicit bashSampleScope override, the
+// node-half empty apply, and AssistantMarkdown reasoning/unknown block arms.
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render } from '@testing-library/react'
+import type { ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import type { RpcId } from '@deepseek-ai/dsh-client-connection/client'
+import type { UseSession } from '@deepseek-ai/dsh-client-web-react'
+import { ToolViewRegistry } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ConversationService, Translate, ToolViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { apply as nodeApply } from '../src/index.ts'
+import { GenericToolCard } from '../src/client/chat/GenericToolCard.tsx'
+import { ToolRow } from '../src/client/chat/ToolRow.tsx'
+import { PendingCard } from '../src/client/chat/PendingCard.tsx'
+import { AssistantMarkdown } from '../src/client/chat/AssistantMarkdown.tsx'
+import { BashRow } from '../src/client/toolviews/bash-sample.tsx'
+import { registerChat } from '../src/client/chat/register.ts'
+
+afterEach(cleanup)
+
+describe('tails', () => {
+  it('node-half apply is an intentional no-op', () => {
+    expect(nodeApply()).toBeUndefined()
+  })
+
+  it('ToolRow stopped state renders the warning dot in the leading slot', () => {
+    const view = render(
+      <ToolRow variant="bash" icon={<i data-testid="icon" />} title="Bash" summary="s" body={null} state="stopped" />,
+    )
+    expect(view.queryByTestId('icon')).toBeNull()
+    expect(view.container.querySelector('[data-state="stopped"]')).not.toBeNull()
+  })
+
+  it('PendingCard renders the question arm with its count', () => {
+    const view = render(
+      <PendingCard item={{ kind: 'question', rpcId: 'r1' as RpcId, questions: [{}, {}] }} />,
+    )
+    expect(view.getByText(/等待回答（2 题）/)).toBeTruthy()
+  })
+
+  it('AssistantMarkdown renders reasoning as a Think row and unknown blocks as JSON fallback', () => {
+    const view = render(
+      <AssistantMarkdown
+        blocks={[
+          { kind: 'reasoning', text: 'thinking hard\nsecond line' },
+          { kind: 'tool-call', callId: 'c', name: 'bash', argsRaw: '{}' },
+          { kind: 'other', block: { type: 'mystery' } },
+        ]}
+        streaming
+      />,
+    )
+    expect(view.getByText('Think')).toBeTruthy()
+    expect(view.getByText('thinking hard')).toBeTruthy()
+    expect(view.getByText(/未知内容块/)).toBeTruthy()
+    const stopped = render(
+      <AssistantMarkdown blocks={[{ kind: 'text', text: 'partial words' }]} streaming={false} interrupted />,
+    )
+    expect(stopped.getByText('已停止')).toBeTruthy()
+  })
+
+  it('a settled others-variant row renders the sparkle icon in the leading slot', () => {
+    const settled: ToolResultNode = {
+      kind: 'tool-result', seq: 2, callId: 'c5',
+      call: { name: 'todo_write', argsRaw: '{"note":"x"}' },
+      content: [], isError: false, callView: null, resultView: null,
+    }
+    const props: ToolViewProps = {
+      callId: 'c5', toolName: 'todo_write', block: settled,
+      useSession: (() => { throw new Error('unused') }) as unknown as UseSession,
+      actions: { openDetails: vi.fn() },
+      t: ((k: string) => k) as Translate,
+    }
+    const view = render(<GenericToolCard {...props} />)
+    // Settled ok state keeps the variant icon (sparkle) instead of a StateDot.
+    expect(view.container.querySelector('[data-variant="others"] svg')).not.toBeNull()
+    expect(view.container.querySelector('[data-state="ok"]')).not.toBeNull()
+  })
+
+  it('BashRow shows the failed pill on error results', () => {
+    const errorResult: ToolResultNode = {
+      kind: 'tool-result', seq: 1, callId: 'c1',
+      call: { name: 'bash', argsRaw: '{"command":"boom"}' },
+      content: [], isError: true, callView: null, resultView: null,
+    }
+    const props: ToolViewProps = {
+      callId: 'c1', toolName: 'bash', block: errorResult,
+      useSession: (() => { throw new Error('unused') }) as unknown as UseSession,
+      actions: { openDetails: vi.fn() },
+      t: ((k: string) => k) as Translate,
+    }
+    const view = render(<BashRow {...props} />)
+    expect(view.getByText('failed')).toBeTruthy()
+  })
+
+  it('registry disposer re-entry is a no-op after the entry was already removed', () => {
+    const registry = new ToolViewRegistry()
+    const off = registry.register('bash', (() => null) as never)
+    const v1 = registry.getVersion()
+    off()
+    const v2 = registry.getVersion()
+    off()
+    expect(registry.getVersion()).toBe(v2)
+    expect(v2).toBeGreaterThan(v1)
+  })
+
+  it('registerChat registers the chat view with the stats footer and disposes cleanly', () => {
+    const disposer = vi.fn()
+    const calls: unknown[] = []
+    const conversation = {
+      registerView: (entry: unknown) => {
+        calls.push(entry)
+        return disposer
+      },
+    } as unknown as ConversationService
+    const toolviews = new ToolViewRegistry()
+    const off = registerChat({ conversation, toolviews, t: ((k: string) => k) as Translate })
+    const entry = calls[0] as { id: string; chrome?: { footer?: unknown } }
+    expect(entry.id).toBe('chat')
+    // footer is a memo exotic component (object, not plain function).
+    expect(entry.chrome?.footer).toBeDefined()
+    off()
+    expect(disposer).toHaveBeenCalledTimes(1)
+  })
+})
diff --git a/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
new file mode 100644
index 0000000000..3ff148f5d6
--- /dev/null
+++ b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
@@ -0,0 +1,140 @@
+// @vitest-environment jsdom
+// Final branch tails for the coverage gate, post slot-phase-2: apply's need()
+// throw + cwd cache hit/empty-cwd skip, AssistantMarkdown non-final reasoning,
+// StatsLine usage-less node, ChatView tool-group selected passthrough +
+// running-empty guard, DetailsPanel titleless selection, registry disposer
+// after a foreign removal emptied the list.
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render } from '@testing-library/react'
+import { Context } from 'cordis'
+import { createSnapshotStore, bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
+import type { UseSession } from '@deepseek-ai/dsh-client-web-react'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ConversationSnapshot, SessionId, SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
+import { apply, inject, ToolViewRegistry } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { AssistantMarkdown } from '../src/client/chat/AssistantMarkdown.tsx'
+import { StatsLine } from '../src/client/chat/StatsLine.tsx'
+import { DetailsPanel } from '../src/client/skeleton/DetailsPanel.tsx'
+import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
+
+afterEach(cleanup)
+
+const SID = 's1' as SessionId
+
+function snapshotBase(): ConversationSnapshot {
+  return {
+    sessionId: SID, nodes: [], foldDegraded: false, partial: null, runningCalls: [],
+    pending: [], running: false, removed: false, openState: 'open', openError: null,
+    hasMore: false, loadingOlder: false, promptError: null, lastAgentError: null,
+  } as ConversationSnapshot
+}
+
+describe('apply need() and cwd cache', () => {
+  it('apply fails loud when a required service is absent', () => {
+    // Call apply directly (no fiber machinery): need('sessions') on a bare
+    // context throws synchronously — the loud-failure branch without the
+    // fiber runner's internal rejection surface. Mount semantics (inject
+    // gating) are covered by the full bench in apply-inject.spec.
+    void inject
+    const ctx = new Context()
+    expect(() => { (apply as (c: Context) => void)(ctx) }).toThrow(/sessions service unavailable/)
+  })
+
+  it('cwd derivation caches per list state and skips empty cwd values', async () => {
+    const ctx = new Context()
+    const slotsFiber = ctx.plugin(SlotsService)
+    await slotsFiber.await()
+    const listStore = createSnapshotStore<SessionListState>({
+      ids: [SID, 'x2' as SessionId, 'x3' as SessionId],
+      byId: {
+        [SID]: { id: SID, title: 'a', cwd: '/proj', running: false, updatedAt: 1 },
+        ['x2' as SessionId]: { id: 'x2' as SessionId, title: 'b', cwd: '', running: false, updatedAt: 1 },
+        ['x3' as SessionId]: { id: 'x3' as SessionId, title: 'c', running: false, updatedAt: 1 },
+      },
+    })
+    ctx.provide('sessions', { list: listStore, manager: { get: vi.fn() }, ancestry: () => [], scope: () => undefined, create: vi.fn() })
+    ctx.provide('layout', { current: createSnapshotStore<{ viewFor: Record<string, string> }>({ viewFor: {} }), open: vi.fn(), openView: vi.fn(), openDetails: vi.fn(), closeDetails: vi.fn() })
+    ctx.provide('i18n', { bind: () => (k: string) => k })
+    const slots = ctx.get('slots') as SlotsService
+    slots.define('conversation', { kind: 'single', scope: 'session' })
+    slots.define('details', { kind: 'single', scope: 'session' })
+    slots.define('conversation.empty', { kind: 'single', scope: 'root' })
+    const fiber = ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    const entry = slots.entries('conversation.empty')[0]! as unknown as {
+      options: { inject: (b: unknown) => { useCwds: (sel: (s: readonly string[]) => readonly string[]) => readonly string[] } }
+    }
+    const injected = entry.options.inject({ ctx })
+    const Probe = () => {
+      const cwds = injected.useCwds(s => s)
+      const again = injected.useCwds(s => s)
+      // Cache hit: same state object yields the same derived array reference.
+      return <i data-testid="cwds">{`${cwds.join(',')}|${String(cwds === again)}`}</i>
+    }
+    const view = render(<Probe />)
+    expect(view.getByTestId('cwds').textContent).toBe('/proj|true')
+  })
+})
+
+describe('render branch tails', () => {
+  it('AssistantMarkdown reasoning row is ok-state when not the streaming tail', () => {
+    const view = render(
+      <AssistantMarkdown
+        blocks={[{ kind: 'reasoning', text: 'done thinking' }, { kind: 'text', text: 'answer' }]}
+        streaming
+      />,
+    )
+    // reasoning at index 0 with a later block: running is false → ok state.
+    expect(view.container.querySelector('[data-state="ok"]')).not.toBeNull()
+  })
+
+  it('StatsLine skips usage-less nodes and defaults each absent counter to zero', () => {
+    const snap = {
+      nodes: [
+        { kind: 'assistant', seq: 1, turn: 1, step: 1, blocks: [] },
+        { kind: 'assistant', seq: 2, turn: 1, step: 2, blocks: [], usage: { inputTokens: 4, outputTokens: 6 } },
+        // outputTokens absent: the tokens sum's ?? 0 arm for output.
+        { kind: 'assistant', seq: 3, turn: 2, step: 1, blocks: [], usage: { inputTokens: 5 } },
+      ],
+    }
+    const source = { getSnapshot: () => snap, subscribe: () => () => {} }
+    const view = render(
+      <StatsLine sessionId={SID} useSession={bindSnapshotSelector(source) as unknown as UseSession} />,
+    )
+    expect(view.getByText('cache hit 0% · 15 tokens · 2 turns · 3 steps')).toBeTruthy()
+  })
+
+  it('AssistantMarkdown reasoning as the streaming tail renders the running ring', () => {
+    const view = render(
+      <AssistantMarkdown blocks={[{ kind: 'reasoning', text: 'still thinking' }]} streaming />,
+    )
+    expect(view.container.querySelector('[data-state="running"]')).not.toBeNull()
+  })
+
+  it('DetailsPanel title falls to 详情 when the selection has no toolName and no material', () => {
+    const SEL: SelectionTarget = { turnSeq: 1, callId: 'ghost' }
+    const view = render(
+      <DetailsPanel
+        sessionId={SID}
+        useSession={bindSnapshotSelector({ getSnapshot: () => snapshotBase(), subscribe: () => () => {} }) as unknown as UseSession}
+        useSelection={bindSnapshotSelector({ getSnapshot: () => SEL, subscribe: () => () => {} })}
+        actions={{ closeDetails: vi.fn() }}
+      />,
+    )
+    expect(view.getByText('详情')).toBeTruthy()
+    expect(view.getByText('该调用不在当前窗口内')).toBeTruthy()
+  })
+
+  it('registry disposer tolerates the list already emptied by a sibling disposer', () => {
+    const registry = new ToolViewRegistry()
+    const offA = registry.register('bash', () => null)
+    const offB = registry.register('bash', () => null)
+    offA()
+    offB()
+    // Both entries gone; a re-register works from a fresh list.
+    registry.register('bash', () => null)
+    expect(registry.resolve('bash', SID)).toBeDefined()
+  })
+})
diff --git a/packages/client/ui-conversation/tests/input-bar.spec.tsx b/packages/client/ui-conversation/tests/input-bar.spec.tsx
new file mode 100644
index 0000000000..660127946b
--- /dev/null
+++ b/packages/client/ui-conversation/tests/input-bar.spec.tsx
@@ -0,0 +1,131 @@
+// @vitest-environment jsdom
+// InputBar behavior: Enter-send semantics (IME guard, shift newline,
+// ctrl/meta insert, repeat suppression), the running lock with stop-only
+// action, unlock refocus, error strip copy, and the focus-keeping mousedown.
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render } from '@testing-library/react'
+import { InputBar } from '../src/client/skeleton/InputBar.tsx'
+import type { InputBarProps } from '../src/client/skeleton/InputBar.tsx'
+
+afterEach(cleanup)
+
+function setup(over?: Partial<InputBarProps>) {
+  const props: InputBarProps = {
+    draft: 'hello', running: false, disabled: false, error: null,
+    variant: 'composer',
+    onDraftChange: vi.fn(), onSend: vi.fn(), onStop: vi.fn(),
+    ...over,
+  }
+  const view = render(<InputBar {...props} />)
+  const textarea = view.container.querySelector('textarea')!
+  const button = view.container.querySelector('button')!
+  return { view, textarea, button, props }
+}
+
+describe('Enter semantics', () => {
+  it('plain Enter sends queue mode; repeat and empty are suppressed', () => {
+    const { textarea, props } = setup()
+    fireEvent.keyDown(textarea, { key: 'Enter' })
+    expect(props.onSend).toHaveBeenCalledWith('queue')
+    fireEvent.keyDown(textarea, { key: 'Enter', repeat: true })
+    expect(props.onSend).toHaveBeenCalledTimes(1)
+    const empty = setup({ draft: '   ' })
+    fireEvent.keyDown(empty.textarea, { key: 'Enter' })
+    expect(empty.props.onSend).not.toHaveBeenCalled()
+  })
+
+  it('non-Enter keys and Shift+Enter fall through to native behavior', () => {
+    const { textarea, props } = setup()
+    fireEvent.keyDown(textarea, { key: 'a' })
+    fireEvent.keyDown(textarea, { key: 'Enter', shiftKey: true })
+    expect(props.onSend).not.toHaveBeenCalled()
+  })
+
+  it('Ctrl/Meta+Enter inserts a newline through execCommand instead of sending', () => {
+    const exec = vi.fn()
+    ;(document as unknown as { execCommand: typeof exec }).execCommand = exec
+    const { textarea, props } = setup()
+    fireEvent.keyDown(textarea, { key: 'Enter', ctrlKey: true })
+    expect(exec).toHaveBeenCalledWith('insertText', false, '\n')
+    expect(props.onSend).not.toHaveBeenCalled()
+  })
+
+  it('composition Enter never sends: ref guard, isComposing, and keyCode 229 paths', async () => {
+    vi.useFakeTimers()
+    try {
+      const { textarea, props } = setup()
+      fireEvent.compositionStart(textarea)
+      fireEvent.keyDown(textarea, { key: 'Enter' })
+      expect(props.onSend).not.toHaveBeenCalled()
+      fireEvent.compositionEnd(textarea)
+      // Safari delivers the closing keydown before the deferred clear.
+      fireEvent.keyDown(textarea, { key: 'Enter' })
+      expect(props.onSend).not.toHaveBeenCalled()
+      vi.advanceTimersByTime(20)
+      fireEvent.keyDown(textarea, { key: 'Enter', keyCode: 229 })
+      expect(props.onSend).not.toHaveBeenCalled()
+      fireEvent.keyDown(textarea, { key: 'Enter' })
+      expect(props.onSend).toHaveBeenCalledTimes(1)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+})
+
+describe('running lock and primary button', () => {
+  it('running locks the textarea and turns the primary into stop', () => {
+    const { textarea, button, props } = setup({ running: true })
+    expect(textarea.disabled).toBe(true)
+    expect(button.getAttribute('aria-label')).toBe('停止')
+    fireEvent.click(button)
+    expect(props.onStop).toHaveBeenCalledTimes(1)
+    expect(props.onSend).not.toHaveBeenCalled()
+  })
+
+  it('idle primary sends and disables on empty draft', () => {
+    const { button, props } = setup()
+    fireEvent.click(button)
+    expect(props.onSend).toHaveBeenCalledWith('queue')
+    const empty = setup({ draft: '' })
+    expect(empty.button.disabled).toBe(true)
+  })
+
+  it('unlock refocuses the textarea; mousedown on the button keeps focus', () => {
+    const { view, props } = setup({ running: true })
+    view.rerender(<InputBar {...props} running={false} />)
+    const textarea = view.container.querySelector('textarea')!
+    expect(document.activeElement).toBe(textarea)
+    textarea.blur()
+    fireEvent.mouseDown(view.container.querySelector('button')!)
+    expect(document.activeElement).toBe(textarea)
+  })
+
+  it('disabled state shows the unavailable placeholder; typing forwards drafts', () => {
+    const { textarea } = setup({ disabled: true, draft: '' })
+    expect(textarea.placeholder).toBe('会话不可用')
+    const live = setup({ draft: '' })
+    expect(live.textarea.placeholder).toContain('Enter 发送')
+    fireEvent.change(live.textarea, { target: { value: 'typed' } })
+    expect(live.props.onDraftChange).toHaveBeenCalledWith('typed')
+    const runningPh = setup({ running: true, draft: '' })
+    expect(runningPh.textarea.placeholder).toContain('停止')
+    const custom = setup({ placeholder: '自定义' })
+    expect(custom.textarea.placeholder).toBe('自定义')
+  })
+})
+
+describe('error strip and variants', () => {
+  it('renders send and stop failure copy', () => {
+    const send = setup({ error: { op: 'send', message: 'boom' } })
+    expect(send.view.getByText(/发送失败：boom/)).toBeTruthy()
+    const stop = setup({ error: { op: 'stop', message: 'halt' } })
+    expect(stop.view.getByText(/停止失败：halt/)).toBeTruthy()
+  })
+
+  it('hero variant adds the hero class and accessory row renders', () => {
+    const { view } = setup({ variant: 'hero', accessory: <i data-testid="acc" /> })
+    expect(view.getByTestId('acc')).toBeTruthy()
+    expect(view.container.querySelector('[class*="hero"]')).not.toBeNull()
+  })
+})
diff --git a/packages/client/ui-conversation/tests/selection-survival.spec.ts b/packages/client/ui-conversation/tests/selection-survival.spec.ts
new file mode 100644
index 0000000000..f12cb63617
--- /dev/null
+++ b/packages/client/ui-conversation/tests/selection-survival.spec.ts
@@ -0,0 +1,121 @@
+// @vitest-environment jsdom
+/**
+ * M1a regression pin: the per-scope selection must survive list refreshes.
+ * Drives the REAL SessionsService + ConversationService chain over the
+ * programmable wire fake — a late list refresh that upgrades the display
+ * title (bare id → cwd basename) and a reconnect-driven refreshList+resync
+ * must neither recreate the session scope nor clear the selection account.
+ */
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import { SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { ConversationService } from '@deepseek-ai/dsh-client-ui-conversation/client'
+
+// The runtime package's programmable fake lives in its tests; import through
+// the src path (same pattern the runtime specs use — test-support material).
+import { FakeApiClient, ok } from '../../runtime/tests/fake-api.ts'
+
+const sid = (s: string): SessionId => s as SessionId
+
+interface Bench {
+  ctx: Context
+  api: FakeApiClient
+  sessions: SessionsService
+  conversation: ConversationService
+}
+
+function bench(): Bench {
+  const ctx = new Context()
+  const api = new FakeApiClient()
+  const sessions = new SessionsService(ctx, api)
+  const conversation = new ConversationService(ctx)
+  return { ctx, api, sessions, conversation }
+}
+
+async function flush(): Promise<void> {
+  // Manager notifier + store batching are microtask-based.
+  await Promise.resolve()
+  await Promise.resolve()
+}
+
+function feed(b: Bench, rows: { id: string; cwd?: string; running?: boolean }[]): void {
+  b.api.onList = () => Promise.resolve(ok({
+    items: rows.map(r => ({
+      sessionId: sid(r.id), updatedAt: 1, running: r.running ?? false,
+      ...(r.cwd !== undefined ? { cwd: r.cwd } : {}),
+    })),
+  }) as never)
+}
+
+describe('selection survives list refreshes (M1a)', () => {
+  it('create → select → title-upgrading refresh keeps scope, binding, store and value', async () => {
+    const b = bench()
+    // First-send shape: client-side create inserts the row without cwd (title = bare id).
+    b.api.onCreate = () => Promise.resolve(ok({ sessionId: sid('s1') }))
+    const id = await b.sessions.create({})
+    await flush()
+    expect(b.sessions.list.getSnapshot().byId[id]?.title).toBe('s1')
+
+    const binding = b.sessions.binding(id)
+    expect(binding).toBeDefined()
+    const scoped = b.sessions.scope(id)!
+    const store = (scoped.get('conversation') as ConversationService).selection
+    store.set({ turnSeq: 3, callId: 'c1' })
+
+    // The late list refresh lands (host knows the cwd → formal title).
+    feed(b, [{ id: 's1', cwd: '/w/proj-a' }])
+    await b.sessions.manager.refreshList()
+    await flush()
+    expect(b.sessions.list.getSnapshot().byId[id]?.title).toBe('proj-a')
+
+    // Scope, binding and the selection account must all be identity-stable.
+    expect(b.sessions.scope(id)).toBe(scoped)
+    expect(b.sessions.binding(id)).toBe(binding)
+    const after = (b.sessions.scope(id)!.get('conversation') as ConversationService).selection
+    expect(after).toBe(store)
+    expect(after.getSnapshot()).toEqual({ turnSeq: 3, callId: 'c1' })
+  })
+
+  it('reconnect (handleConnected: refreshList + resync) keeps the selection account', async () => {
+    const b = bench()
+    feed(b, [{ id: 's1' }])
+    await b.sessions.manager.refreshList()
+    await flush()
+
+    const scoped = b.sessions.scope(sid('s1'))!
+    const store = (scoped.get('conversation') as ConversationService).selection
+    store.set({ turnSeq: 1, callId: 'c9' })
+
+    // Reconnect generation: title upgrade arrives with the re-pull.
+    feed(b, [{ id: 's1', cwd: '/w/proj-a', running: true }])
+    b.sessions.manager.handleConnected()
+    await flush()
+    await flush()
+
+    expect(b.sessions.scope(sid('s1'))).toBe(scoped)
+    const after = (b.sessions.scope(sid('s1'))!.get('conversation') as ConversationService).selection
+    expect(after).toBe(store)
+    expect(after.getSnapshot()).toEqual({ turnSeq: 1, callId: 'c9' })
+  })
+
+  it('a transiently failing list refresh does not prune live scopes', async () => {
+    const b = bench()
+    feed(b, [{ id: 's1' }])
+    await b.sessions.manager.refreshList()
+    await flush()
+    const scoped = b.sessions.scope(sid('s1'))!
+    const store = (scoped.get('conversation') as ConversationService).selection
+    store.set({ turnSeq: 2, callId: 'c2' })
+
+    // Wire hiccup: the reconnect-time list RPC throws (transport error).
+    b.api.onList = () => Promise.reject(new Error('boom'))
+    b.sessions.manager.handleConnected()
+    await flush()
+    await flush()
+
+    expect(b.sessions.scope(sid('s1'))).toBe(scoped)
+    expect((b.sessions.scope(sid('s1'))!.get('conversation') as ConversationService).selection.getSnapshot())
+      .toEqual({ turnSeq: 2, callId: 'c2' })
+  })
+})
diff --git a/packages/client/ui-conversation/tests/service-orchestration.spec.ts b/packages/client/ui-conversation/tests/service-orchestration.spec.ts
new file mode 100644
index 0000000000..9c8e84e55b
--- /dev/null
+++ b/packages/client/ui-conversation/tests/service-orchestration.spec.ts
@@ -0,0 +1,190 @@
+// @vitest-environment jsdom
+/**
+ * ConversationService orchestration half: scope-addressed send/cancel (result
+ * folding, root throw), openDetails choreography, the startSession chain, and
+ * the service-unavailable loud failures. Store semantics live in
+ * service-stores.spec.ts.
+ */
+import { Context } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import { scopeOf } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { ConversationService } from '@deepseek-ai/dsh-client-ui-conversation/client'
+
+const sid = (s: string): SessionId => s as SessionId
+
+/** Recover the module-private scope tag through the public seam (same probe as service-stores.spec). */
+const SCOPE_TAG: symbol = (() => {
+  const recorded: (string | symbol)[] = []
+  const spy = new Proxy(new Context(), {
+    get(target, prop, receiver) {
+      recorded.push(prop)
+      return Reflect.get(target, prop, receiver)
+    },
+  })
+  void scopeOf(spy)
+  const symbol = recorded.find((p): p is symbol => typeof p === 'symbol')
+  if (symbol === undefined) throw new Error('scopeOf probe recorded no symbol read')
+  return symbol
+})()
+
+interface SessionDouble {
+  prompt: ReturnType<typeof vi.fn>
+  cancel: ReturnType<typeof vi.fn>
+}
+
+async function bench(opts?: { layout?: boolean; sessions?: boolean }) {
+  const ctx = new Context()
+  const sessionDoubles = new Map<SessionId, SessionDouble>()
+  const scopes = new Map<SessionId, Context>()
+  const mint = (id: SessionId): Context => {
+    let scoped = scopes.get(id)
+    if (scoped === undefined) {
+      const fiber = ctx.plugin(() => {})
+      scoped = fiber.ctx.extend({ [SCOPE_TAG]: id })
+      scopes.set(id, scoped)
+    }
+    return scoped
+  }
+  const sessionsFake = {
+    manager: {
+      get: (id: SessionId) => {
+        let s = sessionDoubles.get(id)
+        if (s === undefined) {
+          s = {
+            prompt: vi.fn(() => Promise.resolve({ ok: true, value: { accepted: true } })),
+            cancel: vi.fn(() => Promise.resolve({ ok: true, value: { accepted: true } })),
+          }
+          sessionDoubles.set(id, s)
+        }
+        return s
+      },
+    },
+    create: vi.fn(() => Promise.resolve(sid('new-1'))),
+    scope: (id: SessionId) => (id === sid('new-1') ? mint(id) : scopes.get(id)),
+  } as unknown as SessionsService
+  if (opts?.sessions !== false) ctx.provide('sessions', sessionsFake)
+  const layoutFake = { open: vi.fn(), openDetails: vi.fn() }
+  if (opts?.layout !== false) ctx.provide('layout', layoutFake)
+  const fiber = ctx.plugin((pluginCtx) => { void new ConversationService(pluginCtx) })
+  await fiber.await()
+  const svc = ctx.get('conversation') as ConversationService
+  const scopedSvc = (id: SessionId) => mint(id).get('conversation') as ConversationService
+  return { ctx, svc, scopedSvc, mint, sessionDoubles, sessionsFake, layoutFake }
+}
+
+describe('send / cancel', () => {
+  it('sends one text block through the scoped session with the mode', async () => {
+    const b = await bench()
+    await b.scopedSvc(sid('s1')).send('hello', 'steer')
+    expect(b.sessionDoubles.get(sid('s1'))!.prompt).toHaveBeenCalledWith(
+      [{ type: 'text', text: 'hello' }], 'steer')
+  })
+
+  it('folds business failure into a thrown error carrying code and message', async () => {
+    const b = await bench()
+    const s = b.scopedSvc(sid('s1'))
+    // Materialize the double first (manager.get is the lazy mint point).
+    b.sessionsFake.manager.get(sid('s1'))
+    const double = b.sessionDoubles.get(sid('s1'))!
+    double.prompt.mockResolvedValue({ ok: false, error: { code: 'agent-busy', message: 'busy' } })
+    await expect(s.send('x', 'queue')).rejects.toThrow(/send failed: agent-busy: busy/)
+  })
+
+  it('cancel resolves on ok and throws the folded business error', async () => {
+    const b = await bench()
+    const s = b.scopedSvc(sid('s1'))
+    await s.cancel()
+    const double = b.sessionDoubles.get(sid('s1'))!
+    expect(double.cancel).toHaveBeenCalledTimes(1)
+    double.cancel.mockResolvedValue({ ok: false, error: { code: 'internal', message: 'nope' } })
+    await expect(s.cancel()).rejects.toThrow(/cancel failed: internal: nope/)
+  })
+
+  it('root-context send and cancel throw the addressing hint', async () => {
+    const b = await bench()
+    await expect(b.svc.send('x', 'queue')).rejects.toThrow(/requires a session scope/)
+    await expect(b.svc.cancel()).rejects.toThrow(/requires a session scope/)
+  })
+})
+
+describe('openDetails', () => {
+  it('writes the scoped selection then opens the layout panel', async () => {
+    const b = await bench()
+    const s = b.scopedSvc(sid('s1'))
+    s.openDetails({ turnSeq: 3, callId: 'c1', toolName: 'bash' })
+    expect(s.selection.getSnapshot()).toEqual({ turnSeq: 3, callId: 'c1', toolName: 'bash' })
+    expect(b.layoutFake.openDetails).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('startSession chain', () => {
+  it('creates, navigates, then sends through the new scope', async () => {
+    const b = await bench()
+    await b.svc.startSession({ cwd: '/proj', text: 'first', mode: 'queue' })
+    expect(b.sessionsFake.create).toHaveBeenCalledWith({ cwd: '/proj' })
+    expect(b.layoutFake.open).toHaveBeenCalledWith(sid('new-1'))
+    expect(b.sessionDoubles.get(sid('new-1'))!.prompt).toHaveBeenCalledWith(
+      [{ type: 'text', text: 'first' }], 'queue')
+  })
+
+  it('omits cwd from create when not chosen', async () => {
+    const b = await bench()
+    await b.svc.startSession({ text: 't', mode: 'steer' })
+    expect(b.sessionsFake.create).toHaveBeenCalledWith({})
+  })
+
+  it('fails loud when the created session resolves no scope', async () => {
+    const b = await bench()
+    ;(b.sessionsFake.create as ReturnType<typeof vi.fn>).mockResolvedValue(sid('ghost'))
+    await expect(b.svc.startSession({ text: 't', mode: 'queue' })).rejects.toThrow(/resolved no scope/)
+  })
+})
+
+describe('service-unavailable loud failures', () => {
+  it('throws when sessions is missing', async () => {
+    const b = await bench({ sessions: false })
+    await expect(b.svc.startSession({ text: 't', mode: 'queue' })).rejects.toThrow(/sessions service unavailable/)
+  })
+
+  it('throws when layout is missing', async () => {
+    const b = await bench({ layout: false })
+    const s = b.scopedSvc(sid('s1'))
+    expect(() => { s.openDetails({ turnSeq: 1 }) }).toThrow(/layout service unavailable/)
+  })
+
+  it('startSession fails loud when the new scope cannot resolve conversation', async () => {
+    const b = await bench()
+    // A scope minted outside the service tree: scoped.get('conversation') finds nothing.
+    const foreign = new Context()
+    const foreignScope = foreign.plugin(() => {}).ctx.extend({})
+    ;(b.sessionsFake.scope as unknown) = () => foreignScope
+    await expect(b.svc.startSession({ text: 't', mode: 'queue' }))
+      .rejects.toThrow(/conversation service unavailable through the new scope/)
+  })
+})
+
+describe('views ordering and draft persistence branches', () => {
+  it('orders by explicit order with undefined treated as zero (both comparator arms)', async () => {
+    const b = await bench()
+    const entry = (id: string, order?: number) => ({
+      id, label: id, component: () => null,
+      ...(order !== undefined ? { order } : {}),
+    })
+    b.svc.registerView(entry('z-late', 5) as never)
+    b.svc.registerView(entry('default-zero') as never)
+    b.svc.registerView(entry('first', -1) as never)
+    expect(b.svc.views().map(v => v.id)).toEqual(['first', 'default-zero', 'z-late'])
+  })
+
+  it('draft store round-trips through localStorage and removes the key when emptied', async () => {
+    const b = await bench()
+    localStorage.setItem('dsh.conversation.draft.s9', 'restored')
+    const s = b.scopedSvc(sid('s9'))
+    expect(s.drafts.getSnapshot()).toBe('restored')
+    s.drafts.set('typed')
+    expect(localStorage.getItem('dsh.conversation.draft.s9')).toBe('typed')
+    s.drafts.set('')
+    expect(localStorage.getItem('dsh.conversation.draft.s9')).toBeNull()
+  })
+})
diff --git a/packages/client/ui-conversation/tests/service-stores.spec.ts b/packages/client/ui-conversation/tests/service-stores.spec.ts
new file mode 100644
index 0000000000..e7c77bc182
--- /dev/null
+++ b/packages/client/ui-conversation/tests/service-stores.spec.ts
@@ -0,0 +1,176 @@
+// @vitest-environment jsdom
+/**
+ * ConversationService store half: scope-addressed selection/drafts accounts
+ * (lazy mint, per-scope isolation, root access throws, scope teardown
+ * collects), view registry (order, duplicate throw, effect-scoped disposal,
+ * uSES read face). Send/cancel/startSession orchestration live in
+ * service-orchestration.spec.ts.
+ */
+import { Context } from 'cordis'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { FC } from 'react'
+import { scopeOf } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { ConversationService } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ConvViewProps, ViewEntry } from '@deepseek-ai/dsh-client-ui-conversation/client'
+
+const sid = (s: string): SessionId => s as SessionId
+
+/**
+ * The scope tag symbol is module-private to the runtime package; recover it
+ * through the public seam by recording which symbol scopeOf reads off a
+ * spying proxy (keeps this bench honest against the real tagging shape
+ * without dragging the full SessionsService + wire fake in here).
+ */
+const SCOPE_TAG: symbol = (() => {
+  const recorded: (string | symbol)[] = []
+  const spy = new Proxy(new Context(), {
+    get(target, prop, receiver) {
+      recorded.push(prop)
+      return Reflect.get(target, prop, receiver)
+    },
+  })
+  void scopeOf(spy)
+  const symbol = recorded.find((p): p is symbol => typeof p === 'symbol')
+  if (symbol === undefined) throw new Error('scopeOf probe recorded no symbol read')
+  return symbol
+})()
+
+/** Scope bench: real cordis scope fibers tagged like SessionsService.resolve mints them. */
+interface Bench {
+  ctx: Context
+  svc: ConversationService
+  mint: (id: SessionId) => Context
+  dispose: (id: SessionId) => Promise<void>
+}
+
+function bench(): Bench {
+  const ctx = new Context()
+  const fibers = new Map<SessionId, { fiber: ReturnType<Context['plugin']>; ctx: Context }>()
+  const mint = (id: SessionId): Context => {
+    let rec = fibers.get(id)
+    if (rec === undefined) {
+      const fiber = ctx.plugin(() => {})
+      const scoped = fiber.ctx.extend({ [SCOPE_TAG]: id })
+      rec = { fiber, ctx: scoped }
+      fibers.set(id, rec)
+    }
+    return rec.ctx
+  }
+  const dispose = async (id: SessionId): Promise<void> => {
+    const rec = fibers.get(id)
+    if (rec !== undefined) {
+      await rec.fiber.dispose()
+      fibers.delete(id)
+    }
+  }
+  const sessions = { scope: (id: SessionId) => fibers.get(id)?.ctx } as unknown as SessionsService
+  ctx.provide('sessions', sessions)
+  const svc = new ConversationService(ctx)
+  return { ctx, svc, mint, dispose }
+}
+
+/** Scoped service view: ctx.get binds the root singleton to the scoped ctx (scope addressing seam). */
+function convo(scoped: Context): ConversationService {
+  const service = scoped.get('conversation')
+  if (service === undefined) throw new Error('bench: conversation unavailable')
+  return service
+}
+
+const viewComp = (() => null) as unknown as FC<ConvViewProps>
+const entry = (id: string, order?: number): ViewEntry =>
+  ({ id, label: id, component: viewComp, ...(order !== undefined ? { order } : {}) }) as unknown as ViewEntry
+
+beforeEach(() => { localStorage.clear() })
+
+describe('scope addressing of stores', () => {
+  it('root-context selection/drafts access throws with the addressing hint', () => {
+    const b = bench()
+    expect(() => b.svc.selection).toThrow(/requires a session scope/)
+    expect(() => b.svc.drafts).toThrow(/requires a session scope/)
+  })
+
+  it('mints one store per scope and keeps identity per session', () => {
+    const b = bench()
+    const c1 = b.mint(sid('s1'))
+    const c2 = b.mint(sid('s2'))
+    const sel1 = convo(c1).selection
+    const sel2 = convo(c2).selection
+    expect(sel1).not.toBe(sel2)
+    expect(convo(c1).selection).toBe(sel1)
+    sel1.set({ turnSeq: 3 })
+    expect(sel1.getSnapshot()).toEqual({ turnSeq: 3 })
+    expect(sel2.getSnapshot()).toBeNull()
+  })
+
+  it('persists drafts keyed by session id and evolves independently', async () => {
+    const b = bench()
+    const c1 = b.mint(sid('s1'))
+    convo(c1).drafts.set('hello')
+    expect(localStorage.getItem('dsh.conversation.draft.s1')).toBe('hello')
+    const c2 = b.mint(sid('s2'))
+    expect(convo(c2).drafts.getSnapshot()).toBe('')
+    // Re-minting after teardown rehydrates from storage; clearing removes the key.
+    await b.dispose(sid('s1'))
+    expect(convo(b.mint(sid('s1'))).drafts.getSnapshot()).toBe('hello')
+    convo(b.mint(sid('s1'))).drafts.set('')
+    expect(localStorage.getItem('dsh.conversation.draft.s1')).toBeNull()
+  })
+
+  it('scope fiber disposal collects the store account (fresh store on re-mint)', async () => {
+    const b = bench()
+    const c1 = b.mint(sid('s1'))
+    const sel = convo(c1).selection
+    sel.set({ turnSeq: 1 })
+    await b.dispose(sid('s1'))
+    const again = b.mint(sid('s1'))
+    const sel2 = convo(again).selection
+    expect(sel2).not.toBe(sel)
+    expect(sel2.getSnapshot()).toBeNull()
+  })
+})
+
+describe('view registry', () => {
+  it('orders by order (ties keep registration sequence) with a stable cache reference', () => {
+    const b = bench()
+    b.svc.registerView(entry('chat', 0))
+    b.svc.registerView(entry('waterfall', 2))
+    b.svc.registerView(entry('trajectory', 1))
+    const views = b.svc.views()
+    expect(views.map(v => v.id)).toEqual(['chat', 'trajectory', 'waterfall'])
+    expect(b.svc.views()).toBe(views)
+  })
+
+  it('duplicate id throws; disposer removes and bumps the version', () => {
+    const b = bench()
+    const fn = vi.fn()
+    b.svc.subscribeViews(fn)
+    const off = b.svc.registerView(entry('chat'))
+    expect(() => b.svc.registerView(entry('chat'))).toThrow(/already registered/)
+    const v1 = b.svc.viewsVersion()
+    off()
+    expect(b.svc.viewsVersion()).toBeGreaterThan(v1)
+    expect(b.svc.views()).toEqual([])
+    expect(fn).toHaveBeenCalled()
+  })
+
+  it('unsubscribe stops notifications', () => {
+    const b = bench()
+    const fn = vi.fn()
+    const unsub = b.svc.subscribeViews(fn)
+    unsub()
+    b.svc.registerView(entry('chat'))
+    expect(fn).not.toHaveBeenCalled()
+  })
+
+  it('a registering plugin fiber unloading collects its views (effect cascade)', async () => {
+    const b = bench()
+    const fiber = b.ctx.plugin((pluginCtx: Context) => {
+      convo(pluginCtx).registerView(entry('chat'))
+    })
+    await fiber.await()
+    expect(b.svc.views().map(v => v.id)).toEqual(['chat'])
+    await fiber.dispose()
+    expect(b.svc.views()).toEqual([])
+  })
+})
diff --git a/packages/client/ui-conversation/tests/skeleton-branches.spec.tsx b/packages/client/ui-conversation/tests/skeleton-branches.spec.tsx
new file mode 100644
index 0000000000..25808e17c5
--- /dev/null
+++ b/packages/client/ui-conversation/tests/skeleton-branches.spec.tsx
@@ -0,0 +1,245 @@
+// @vitest-environment jsdom
+// Skeleton branch tails for the coverage gate (complements skeleton.spec.tsx
+// acceptance flows): breadcrumb ancestry rendering + error strip in
+// ConversationRoot, DetailsPanel non-JSON args / non-text result blocks /
+// error-only results, EmptyState failure surface and custom-directory swap.
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render, waitFor } from '@testing-library/react'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
+import type { UseSession } from '@deepseek-ai/dsh-client-web-react'
+import type { ConversationSnapshot, SessionId, SessionSummary } from '@deepseek-ai/dsh-client-runtime/client'
+import { ConversationRoot, DetailsPanel, EmptyState } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { SelectionTarget, ViewEntry } from '@deepseek-ai/dsh-client-ui-conversation/client'
+
+afterEach(cleanup)
+
+const SID = 's1' as SessionId
+
+function snapshotBase(): ConversationSnapshot {
+  return {
+    sessionId: SID, nodes: [], foldDegraded: false, partial: null, runningCalls: [],
+    pending: [], running: false, removed: false, openState: 'open', openError: null,
+    hasMore: false, loadingOlder: false, promptError: null, lastAgentError: null,
+  } as ConversationSnapshot
+}
+
+function sessionSource(over?: Partial<ConversationSnapshot>) {
+  const snap = { ...snapshotBase(), ...over }
+  return {
+    getSnapshot: () => snap,
+    subscribe: () => () => {},
+  }
+}
+
+const summary = (id: string, title: string): SessionSummary =>
+  ({ id: id as SessionId, title, running: false, updatedAt: 1 })
+
+describe('ConversationRoot branches', () => {
+  const chatEntry: ViewEntry = {
+    id: 'chat', label: 'Chat', component: () => null,
+  } as unknown as ViewEntry
+
+  function rootProps(over?: {
+    ancestry?: readonly SessionSummary[]
+    snapshot?: Partial<ConversationSnapshot>
+  }) {
+    const open = vi.fn()
+    const view = render(
+      <ConversationRoot
+        sessionId={SID}
+        useSession={bindSnapshotSelector(sessionSource(over?.snapshot)) as unknown as UseSession}
+        useAncestry={() => over?.ancestry ?? []}
+        views={{ list: () => [chatEntry], subscribe: () => () => {}, version: () => 1 }}
+        useActiveView={() => undefined}
+        composer={{ useDraft: () => '', setDraft: vi.fn(), send: vi.fn(), stop: vi.fn() }}
+        actions={{ openView: vi.fn(), open }}
+        renderView={() => <div data-testid="view-body" />}
+      />,
+    )
+    return { view, open }
+  }
+
+  it('renders the ancestry breadcrumb with separators and navigates on ancestor click', () => {
+    const { view, open } = rootProps({
+      ancestry: [summary('root-1', 'Workspace'), summary('s1', 'Current')],
+    })
+    expect(view.getByText('Workspace')).toBeTruthy()
+    expect(view.getByText('/')).toBeTruthy()
+    fireEvent.click(view.getByText('Workspace'))
+    expect(open).toHaveBeenCalledWith('root-1' as SessionId)
+    // The last crumb is the current session: disabled, no navigation.
+    fireEvent.click(view.getByText('Current'))
+    expect(open).toHaveBeenCalledTimes(1)
+  })
+
+  it('falls back to the raw session id without ancestry and counts user turns', () => {
+    const { view } = rootProps({
+      snapshot: { nodes: [{ kind: 'user', seq: 1 } as never, { kind: 'assistant', seq: 2 } as never] },
+    })
+    expect(view.getByText(SID)).toBeTruthy()
+    expect(view.getByText(/1 turns/)).toBeTruthy()
+  })
+
+  it('surfaces promptError through the composer error strip', () => {
+    const { view } = rootProps({
+      snapshot: { promptError: { op: 'stop', error: { message: 'halt', code: 'internal' } } as never },
+    })
+    expect(view.getByText(/停止失败：halt（internal）/)).toBeTruthy()
+  })
+
+  it('an unknown active view id falls back to the first registered view', () => {
+    const view = render(
+      <ConversationRoot
+        sessionId={SID}
+        useSession={bindSnapshotSelector(sessionSource()) as unknown as UseSession}
+        useAncestry={() => []}
+        views={{ list: () => [chatEntry], subscribe: () => () => {}, version: () => 1 }}
+        useActiveView={() => 'gone' as never}
+        composer={{ useDraft: () => '', setDraft: vi.fn(), send: vi.fn(), stop: vi.fn() }}
+        actions={{ openView: vi.fn(), open: vi.fn() }}
+        renderView={(entry) => <div data-testid={`body-${entry.id}`} />}
+      />,
+    )
+    expect(view.getByTestId('body-chat')).toBeTruthy()
+  })
+})
+
+describe('DetailsPanel branches', () => {
+  function panel(selection: SelectionTarget | null, snapshot?: Partial<ConversationSnapshot>) {
+    return render(
+      <DetailsPanel
+        sessionId={SID}
+        useSession={bindSnapshotSelector(sessionSource(snapshot)) as unknown as UseSession}
+        useSelection={bindSnapshotSelector({ getSnapshot: () => selection, subscribe: () => () => {} })}
+        actions={{ closeDetails: vi.fn() }}
+      />,
+    )
+  }
+
+  it('shows non-JSON args verbatim (streaming fragment path)', () => {
+    const view = panel({ turnSeq: 1, callId: 'c1', toolName: 'bash' }, {
+      runningCalls: [{ callId: 'c1', name: 'bash', argsRaw: '{"cmd": tru', turn: 1, step: 1, callView: null }],
+    })
+    expect(view.getByText('{"cmd": tru')).toBeTruthy()
+  })
+
+  it('a selection without callId renders the empty hint (selector null arm)', () => {
+    const view = panel({ turnSeq: 2 })
+    expect(view.getByText(/点击消息流中的工具行查看详情/)).toBeTruthy()
+  })
+
+  it('snapshot updates re-run the material selector through the shallow equality arm', () => {
+    let snap = { ...snapshotBase(), runningCalls: [{ callId: 'c9', name: 'bash', argsRaw: '{"a":1}', turn: 1, step: 1, callView: null }] } as ConversationSnapshot
+    const subs = new Set<() => void>()
+    const source = {
+      getSnapshot: () => snap,
+      subscribe: (fn: () => void) => {
+        subs.add(fn)
+        return () => subs.delete(fn)
+      },
+    }
+    const SEL: SelectionTarget = { turnSeq: 1, callId: 'c9' }
+    const view = render(
+      <DetailsPanel
+        sessionId={SID}
+        useSession={bindSnapshotSelector(source) as unknown as UseSession}
+        useSelection={bindSnapshotSelector({ getSnapshot: () => SEL, subscribe: () => () => {} })}
+        actions={{ closeDetails: vi.fn() }}
+      />,
+    )
+    expect(view.getByText(/"a": 1/)).toBeTruthy()
+    // Top-level swap with identical material members: the eq arm short-circuits.
+    snap = { ...snap }
+    for (const fn of [...subs]) fn()
+    expect(view.getByText(/"a": 1/)).toBeTruthy()
+  })
+
+  it('windowless call material: no name/args fallback to callId, mixed node walk skips non-matches', () => {
+    // A tool-result whose call head fell outside the window (call === null),
+    // preceded by non-matching nodes so the walk exercises both filter arms.
+    const view = panel({ turnSeq: 1, callId: 'c8' }, {
+      nodes: [
+        { kind: 'user', seq: 1, content: [], source: null } as never,
+        { kind: 'tool-result', seq: 2, callId: 'other', call: { name: 'x', argsRaw: '{}' }, content: [], isError: false, callView: null, resultView: null } as never,
+        { kind: 'tool-result', seq: 3, callId: 'c8', call: null, content: [], isError: false, callView: null, resultView: null } as never,
+      ],
+    })
+    expect(view.getByText('c8')).toBeTruthy()
+  })
+
+  it('stringifies non-text result blocks and renders error-only results', () => {
+    const withBlocks = panel({ turnSeq: 1, callId: 'c2' }, {
+      nodes: [{
+        kind: 'tool-result', seq: 3, callId: 'c2', call: { name: 'read', argsRaw: '{}' },
+        content: [{ type: 'image', data: 'x' } as never],
+        isError: false, callView: null, resultView: null,
+      } as never],
+    })
+    expect(withBlocks.getByText(/"type": "image"/)).toBeTruthy()
+    const errorOnly = panel({ turnSeq: 1, callId: 'c3' }, {
+      nodes: [{
+        kind: 'tool-result', seq: 4, callId: 'c3', call: { name: 'bash', argsRaw: '{}' },
+        content: [], isError: true, error: { name: 'ToolError', code: 'timeout' },
+        callView: null, resultView: null,
+      } as never],
+    })
+    expect(errorOnly.getByText(/ToolError: timeout/)).toBeTruthy()
+  })
+})
+
+describe('EmptyState branches', () => {
+  // getSnapshot must return a stable reference (uSES contract) — a fresh
+  // array per call loops the selector forever.
+  const CWDS: readonly string[] = ['/proj']
+  const NO_CWDS: readonly string[] = []
+
+  it('keeps the draft and surfaces a local error strip when startSession rejects', async () => {
+    const startSession = vi.fn(() => Promise.reject(new Error('create down')))
+    const view = render(
+      <EmptyState
+        useCwds={bindSnapshotSelector({ getSnapshot: () => CWDS, subscribe: () => () => {} })}
+        actions={{ startSession }}
+      />,
+    )
+    const textarea = view.container.querySelector('textarea')!
+    fireEvent.change(textarea, { target: { value: 'first task' } })
+    fireEvent.keyDown(textarea, { key: 'Enter' })
+    await waitFor(() => expect(view.getByText(/发送失败：create down/)).toBeTruthy())
+    expect((textarea as HTMLTextAreaElement).value).toBe('first task')
+  })
+
+  it('non-Error rejection reasons stringify into the error strip', async () => {
+    const startSession = vi.fn(() => Promise.reject('plain-string'))
+    const view = render(
+      <EmptyState
+        useCwds={bindSnapshotSelector({ getSnapshot: () => NO_CWDS, subscribe: () => () => {} })}
+        actions={{ startSession }}
+      />,
+    )
+    const textarea = view.container.querySelector('textarea')!
+    fireEvent.change(textarea, { target: { value: 'go' } })
+    fireEvent.keyDown(textarea, { key: 'Enter' })
+    await waitFor(() => expect(view.getByText(/发送失败：plain-string/)).toBeTruthy())
+  })
+
+  it('cwd select picks an option, swaps to free-form on 新目录, and submits the typed path', async () => {
+    const startSession = vi.fn(() => Promise.resolve())
+    const view = render(
+      <EmptyState
+        useCwds={bindSnapshotSelector({ getSnapshot: () => CWDS, subscribe: () => () => {} })}
+        actions={{ startSession }}
+      />,
+    )
+    const select = view.container.querySelector('select')!
+    fireEvent.change(select, { target: { value: '/proj' } })
+    expect((select as HTMLSelectElement).value).toBe('/proj')
+    fireEvent.change(select, { target: { value: '::new-directory' } })
+    const custom = view.container.querySelector('input')!
+    fireEvent.change(custom, { target: { value: '/typed/dir' } })
+    const textarea = view.container.querySelector('textarea')!
+    fireEvent.change(textarea, { target: { value: 'task' } })
+    fireEvent.keyDown(textarea, { key: 'Enter' })
+    await waitFor(() => expect(startSession).toHaveBeenCalledWith({ text: 'task', mode: 'queue', cwd: '/typed/dir' }))
+  })
+})
diff --git a/packages/client/ui-conversation/tests/skeleton.spec.tsx b/packages/client/ui-conversation/tests/skeleton.spec.tsx
new file mode 100644
index 0000000000..ab23a64389
--- /dev/null
+++ b/packages/client/ui-conversation/tests/skeleton.spec.tsx
@@ -0,0 +1,181 @@
+// @vitest-environment jsdom
+/**
+ * Skeleton acceptance: empty-state transition (same InputBar component in
+ * hero position, startSession submit), ConversationRoot view switching over
+ * the registry face, DetailsPanel open/close linkage against a layout-shaped
+ * fake. Components stay framework-free — everything arrives via props here,
+ * exactly as the inject factories will assemble them.
+ */
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { FC } from 'react'
+import { bindSnapshotSelector, createSnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import type { UseSession } from '@deepseek-ai/dsh-client-web-react'
+import type { SessionId, SessionSummary } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  ConversationRoot, DetailsPanel, EmptyState,
+} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { SelectionTarget, ViewEntry, ViewId } from '@deepseek-ai/dsh-client-ui-conversation/client'
+
+const sid = (s: string): SessionId => s as SessionId
+
+afterEach(cleanup)
+
+/** Minimal conversation snapshot slice the skeleton reads. */
+interface FakeSnapshot {
+  nodes: readonly { kind: string; callId?: string; call?: { name: string; argsRaw: string } | null; content?: readonly { type: string; text?: string }[]; isError?: boolean }[]
+  runningCalls: readonly { callId: string; name: string; argsRaw: string }[]
+  running: boolean
+  removed: boolean
+  promptError: { op: 'send' | 'stop'; error: { message: string; code: string } } | null
+}
+
+function fakeSession(init: Partial<FakeSnapshot> = {}) {
+  const store = createSnapshotStore<FakeSnapshot>({
+    nodes: [], runningCalls: [], running: false, removed: false, promptError: null, ...init,
+  })
+  return { store, useSession: bindSnapshotSelector(store) as unknown as UseSession }
+}
+
+describe('EmptyState', () => {
+  it('submits startSession with the typed text and picked cwd; failure surfaces locally', async () => {
+    const cwds = createSnapshotStore<readonly string[]>(['/w/app', '/w/lib'])
+    let reject!: (e: Error) => void
+    const startSession = vi.fn(() => new Promise<void>((_res, rej) => { reject = rej }))
+    render(<EmptyState useCwds={cwds.useSelector} actions={{ startSession }} />)
+
+    fireEvent.change(screen.getByRole('combobox', { name: '项目目录' }), { target: { value: '/w/app' } })
+    const box = screen.getByPlaceholderText('Message to run task, plan and build')
+    fireEvent.change(box, { target: { value: '造一个轮子' } })
+    fireEvent.keyDown(box, { key: 'Enter' })
+    expect(startSession).toHaveBeenCalledWith({ text: '造一个轮子', mode: 'queue', cwd: '/w/app' })
+
+    reject(new Error('后端拒收'))
+    expect(await screen.findByText(/后端拒收/)).toBeTruthy()
+    // Draft survives the failure for retry.
+    expect((box as HTMLTextAreaElement).value).toBe('造一个轮子')
+  })
+
+  it('new-directory option swaps the select for a free-form input', () => {
+    const cwds = createSnapshotStore<readonly string[]>([])
+    render(<EmptyState useCwds={cwds.useSelector} actions={{ startSession: () => Promise.resolve() }} />)
+    fireEvent.change(screen.getByRole('combobox'), { target: { value: '::new-directory' } })
+    const custom = screen.getByPlaceholderText(/目录路径/)
+    fireEvent.change(custom, { target: { value: '/tmp/fresh' } })
+    expect((custom as HTMLInputElement).value).toBe('/tmp/fresh')
+  })
+})
+
+describe('ConversationRoot', () => {
+  function bench(views: ViewEntry[], active?: string) {
+    const { useSession } = fakeSession({ nodes: [{ kind: 'user' }, { kind: 'user' }] })
+    const activeStore = createSnapshotStore<string | undefined>(active)
+    const openView = vi.fn((v: string) => { activeStore.set(v) })
+    const open = vi.fn()
+    const drafts = createSnapshotStore<string>('')
+    const send = vi.fn()
+    const stop = vi.fn()
+    const ancestry: SessionSummary[] = [
+      { id: sid('root'), title: 'proj', running: false, updatedAt: 1 },
+      { id: sid('s1'), title: 'child', running: false, updatedAt: 1, parentId: sid('root') },
+    ]
+    const rendered: string[] = []
+    const ui = render(
+      <ConversationRoot
+        sessionId={sid('s1')}
+        useSession={useSession}
+        useAncestry={() => ancestry}
+        views={{
+          list: () => views,
+          subscribe: () => () => {},
+          version: () => 1,
+        }}
+        useActiveView={() => activeStore.useSelector(s => s) as ViewId | undefined}
+        composer={{
+          useDraft: () => drafts.useSelector(s => s),
+          setDraft: (t) => { drafts.set(t) },
+          send, stop,
+        }}
+        actions={{ openView: openView as (v: never) => void, open }}
+        renderView={(entry) => { rendered.push(entry.id); return <div data-testid={`view-${entry.id}`} /> }}
+      />)
+    return { ui, openView, open, rendered, send, drafts }
+  }
+
+  const comp = (() => null) as unknown as FC<never>
+  const view = (id: string, label: string): ViewEntry =>
+    ({ id, label, component: comp }) as unknown as ViewEntry
+
+  it('renders breadcrumb chain, meta turns, and the active view (default chat)', () => {
+    const { rendered, open } = bench([view('chat', 'Chat'), view('trajectory', 'Trajectory')])
+    expect(screen.getByText('proj')).toBeTruthy()
+    expect(screen.getByText('child')).toBeTruthy()
+    expect(screen.getByText(/2 turns/)).toBeTruthy()
+    expect(rendered).toEqual(['chat'])
+    // Ancestor crumb navigates; current crumb is disabled.
+    fireEvent.click(screen.getByRole('button', { name: 'proj' }))
+    expect(open).toHaveBeenCalledWith('root')
+    expect((screen.getByRole('button', { name: 'child' }) as HTMLButtonElement).disabled).toBe(true)
+  })
+
+  it('switches views through actions.openView and re-renders the new body', () => {
+    const { openView } = bench([view('chat', 'Chat'), view('trajectory', 'Trajectory')])
+    fireEvent.click(screen.getByRole('tab', { name: 'Trajectory' }))
+    expect(openView).toHaveBeenCalledWith('trajectory')
+    expect(screen.getByTestId('view-trajectory')).toBeTruthy()
+  })
+
+  it('hides the tab strip with a single view and wires the composer send', () => {
+    const { send } = bench([view('chat', 'Chat')])
+    expect(screen.queryByRole('tablist')).toBeNull()
+    const box = screen.getByPlaceholderText(/输入消息/)
+    fireEvent.change(box, { target: { value: 'hi' } })
+    fireEvent.keyDown(box, { key: 'Enter' })
+    expect(send).toHaveBeenCalledWith('queue')
+  })
+})
+
+describe('DetailsPanel', () => {
+  function benchDetails(snapshot: Partial<FakeSnapshot>, selection: SelectionTarget | null) {
+    const { useSession } = fakeSession(snapshot)
+    const selectionStore = createSnapshotStore<SelectionTarget | null>(selection)
+    const closeDetails = vi.fn()
+    render(
+      <DetailsPanel
+        sessionId={sid('s1')}
+        useSession={useSession}
+        useSelection={selectionStore.useSelector}
+        actions={{ closeDetails }}
+      />)
+    return { closeDetails, selectionStore }
+  }
+
+  it('renders the selected call args and result; close fires the layout-linked action', () => {
+    const { closeDetails } = benchDetails({
+      nodes: [{
+        kind: 'tool-result', callId: 'c1',
+        call: { name: 'bash', argsRaw: '{"cmd":"ls"}' },
+        content: [{ type: 'text', text: 'file-a\nfile-b' }],
+        isError: false,
+      }],
+    }, { turnSeq: 1, callId: 'c1' })
+    expect(screen.getByText('bash')).toBeTruthy()
+    expect(screen.getByText(/"cmd": "ls"/)).toBeTruthy()
+    expect(screen.getByText(/file-a/)).toBeTruthy()
+    fireEvent.click(screen.getByRole('button', { name: '关闭详情' }))
+    expect(closeDetails).toHaveBeenCalledTimes(1)
+  })
+
+  it('shows the empty hint without a selection and the running state for open calls', () => {
+    benchDetails({ runningCalls: [{ callId: 'c9', name: 'bash', argsRaw: '{}' }] }, null)
+    expect(screen.getByText(/点击消息流中的工具行/)).toBeTruthy()
+    cleanup()
+    benchDetails({ runningCalls: [{ callId: 'c9', name: 'bash', argsRaw: '{}' }] }, { turnSeq: 1, callId: 'c9' })
+    expect(screen.getByText('运行中…')).toBeTruthy()
+  })
+
+  it('reports an out-of-window call distinctly', () => {
+    benchDetails({}, { turnSeq: 1, callId: 'ghost' })
+    expect(screen.getByText(/不在当前窗口内/)).toBeTruthy()
+  })
+})
diff --git a/packages/client/ui-conversation/tests/toolview-entry-types.spec.ts b/packages/client/ui-conversation/tests/toolview-entry-types.spec.ts
new file mode 100644
index 0000000000..62c875687e
--- /dev/null
+++ b/packages/client/ui-conversation/tests/toolview-entry-types.spec.ts
@@ -0,0 +1,62 @@
+/**
+ * Tool-ring Entry typing (design §7): I inferred from the inject factory at
+ * the register site, component must accept ToolViewProps & I, and the resolve
+ * read face carries the erased-but-present inject. Compile-time checks via
+ * @ts-expect-error pairs; the runtime assertions just keep vitest happy.
+ */
+import { describe, expect, it } from 'vitest'
+import type { FC } from 'react'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import { ToolViewRegistry } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ToolViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+
+const sid = (s: string): SessionId => s as SessionId
+
+// Positive control: component's own injected share matches the factory's product.
+interface RowInjected { useMyStore: () => number }
+const InjectedRowComp: FC<ToolViewProps & RowInjected> = () => null
+// Plain rows take the shared props only.
+const PlainRowComp: FC<ToolViewProps> = () => null
+
+describe('tool-ring entry typing', () => {
+  it('register infers I from the inject factory and accepts a matching component', () => {
+    const reg = new ToolViewRegistry()
+    const off = reg.register('bash', InjectedRowComp, {
+      inject: () => ({ useMyStore: () => 1 }),
+    })
+    expect(reg.resolve('bash', sid('s'))?.inject).toBeDefined()
+    off()
+  })
+
+  it('injectless registration needs no options and resolves without inject', () => {
+    const reg = new ToolViewRegistry()
+    reg.register('read', PlainRowComp)
+    expect('inject' in (reg.resolve('read', sid('s')) ?? {})).toBe(false)
+  })
+
+  it('compile-time: factory product must cover the component injected share', () => {
+    const reg = new ToolViewRegistry()
+    reg.register('bash', InjectedRowComp, {
+      // @ts-expect-error the factory misses useMyStore, which the component requires
+      inject: () => ({ somethingElse: 1 }),
+    })
+    expect(true).toBe(true)
+  })
+
+  // Known boundary (not asserted): a component demanding an injected share CAN
+  // register bare — with I defaulting to `object`, FC<ToolViewProps & RowInjected>
+  // is structurally assignable to FC<ToolViewProps & object> (parameter
+  // bivariance over a wider props type). The register-site guarantee holds in
+  // the direction that matters: WITH an inject factory, its product must cover
+  // the component's share (previous case). The bare-register gap is the same
+  // one SlotMap's single-kind register has and is accepted by design §7.
+
+  it('compile-time: scope filter receives the branded SessionId', () => {
+    const reg = new ToolViewRegistry()
+    reg.register('bash', PlainRowComp, {
+      // @ts-expect-error number is not assignable to SessionId
+      scope: (id: number) => id > 0,
+    })
+    expect(true).toBe(true)
+  })
+})
diff --git a/packages/client/ui-conversation/tests/toolview-registry.spec.ts b/packages/client/ui-conversation/tests/toolview-registry.spec.ts
new file mode 100644
index 0000000000..fad1d7f171
--- /dev/null
+++ b/packages/client/ui-conversation/tests/toolview-registry.spec.ts
@@ -0,0 +1,101 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import { ToolViewRegistry } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ToolViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+
+const sid = (s: string) => s as SessionId
+const comp = (name: string) => {
+  const fc = () => null
+  fc.displayName = name
+  return fc as unknown as import('react').FC<ToolViewProps>
+}
+
+describe('ToolViewRegistry', () => {
+  it('resolves a global registration for any session', () => {
+    const reg = new ToolViewRegistry()
+    const bash = comp('Bash')
+    reg.register('bash', bash)
+    expect(reg.resolve('bash', sid('a'))?.component).toBe(bash)
+    expect(reg.resolve('bash', sid('b'))?.component).toBe(bash)
+    expect(reg.resolve('read', sid('a'))).toBeUndefined()
+  })
+
+  it('prefers a matching scope filter over the global registration', () => {
+    const reg = new ToolViewRegistry()
+    const global = comp('Global')
+    const swarm = comp('Swarm')
+    reg.register('bash', global)
+    reg.register('bash', swarm, { scope: id => id === sid('swarm-1') })
+    expect(reg.resolve('bash', sid('swarm-1'))?.component).toBe(swarm)
+    expect(reg.resolve('bash', sid('plain'))?.component).toBe(global)
+  })
+
+  it('later registration wins within the same tier, scoped and global', () => {
+    const reg = new ToolViewRegistry()
+    const s1 = comp('S1')
+    const s2 = comp('S2')
+    const g1 = comp('G1')
+    const g2 = comp('G2')
+    reg.register('bash', g1)
+    reg.register('bash', s1, { scope: () => true })
+    reg.register('bash', s2, { scope: () => true })
+    reg.register('bash', g2)
+    expect(reg.resolve('bash', sid('x'))?.component).toBe(s2)
+    const scopeless = new ToolViewRegistry()
+    scopeless.register('bash', g1)
+    scopeless.register('bash', g2)
+    expect(scopeless.resolve('bash', sid('x'))?.component).toBe(g2)
+  })
+
+  it('a non-matching scope filter falls through to global, then undefined', () => {
+    const reg = new ToolViewRegistry()
+    const scoped = comp('Scoped')
+    reg.register('bash', scoped, { scope: () => false })
+    expect(reg.resolve('bash', sid('x'))).toBeUndefined()
+    const global = comp('Global')
+    reg.register('bash', global)
+    expect(reg.resolve('bash', sid('x'))?.component).toBe(global)
+  })
+
+  it('disposer removes exactly its registration and is idempotent', () => {
+    const reg = new ToolViewRegistry()
+    const g = comp('G')
+    const s = comp('S')
+    const off = reg.register('bash', s, { scope: () => true })
+    reg.register('bash', g)
+    off()
+    off()
+    expect(reg.resolve('bash', sid('x'))?.component).toBe(g)
+  })
+
+  it('unregistering the last entry resolves undefined (GenericToolCard fallback)', () => {
+    const reg = new ToolViewRegistry()
+    const off = reg.register('bash', comp('B'))
+    off()
+    expect(reg.resolve('bash', sid('x'))).toBeUndefined()
+  })
+
+  it('carries the inject factory through resolve', () => {
+    const reg = new ToolViewRegistry()
+    const inject = () => ({})
+    reg.register('bash', comp('B'), { inject })
+    expect(reg.resolve('bash', sid('x'))?.inject).toBe(inject)
+    reg.register('read', comp('R'))
+    expect('inject' in reg.resolve('read', sid('x'))!).toBe(false)
+  })
+
+  it('notifies subscribers and bumps the version on register and dispose', () => {
+    const reg = new ToolViewRegistry()
+    const fn = vi.fn()
+    const unsub = reg.subscribe(fn)
+    const v0 = reg.getVersion()
+    const off = reg.register('bash', comp('B'))
+    expect(fn).toHaveBeenCalledTimes(1)
+    expect(reg.getVersion()).toBeGreaterThan(v0)
+    off()
+    expect(fn).toHaveBeenCalledTimes(2)
+    unsub()
+    reg.register('read', comp('R'))
+    expect(fn).toHaveBeenCalledTimes(2)
+  })
+})
diff --git a/packages/client/ui-conversation/tests/toolviews-type-chain.spec.ts b/packages/client/ui-conversation/tests/toolviews-type-chain.spec.ts
new file mode 100644
index 0000000000..64b9745f51
--- /dev/null
+++ b/packages/client/ui-conversation/tests/toolviews-type-chain.spec.ts
@@ -0,0 +1,96 @@
+// Tool-ring type-chain samples (design §9 item 5, toolviews half): the
+// register→inject→resolve chain where `I` is inferred from the inject
+// factory and proved against the component at the register site, plus
+// expect-error duals. Tool names stay an open set (no per-tool props table —
+// design §7); the strong typing under test is Entry-internal. The known
+// bare-register variance edge (FC<Props & I> assignable to FC<Props & object>
+// without an inject factory) is accepted by design §7 and deliberately not
+// pinned here. Follows the slots-ring exemplar's shape.
+import { describe, expect, it } from 'vitest'
+import type { FC, ReactNode } from 'react'
+import type { SessionBinding } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ToolViewOptions, ToolViewProps } from '../src/client/contract/toolview.ts'
+import { ToolViewRegistry } from '../src/client/toolviews/registry.ts'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+
+const sid = (s: string): SessionId => s as SessionId
+
+/** Registrant's own injected share (locally declared — ownership rule). */
+interface RowInjected { useRuns: () => number; actions2: { rerun: () => void } }
+
+const InjectedRow: FC<ToolViewProps & RowInjected> = () => null
+const PlainRow: FC<ToolViewProps> = () => null
+
+describe('tool-ring type-chain negatives (compile-time; body never runs)', () => {
+  it('holds the negative samples as expect-error sites', () => {
+    const negatives = (registry: ToolViewRegistry) => {
+      // 1. Inject factory under-produces the component's declared share:
+      //    I infers from the factory, and the component position then fails.
+      registry.register(
+        'bash',
+        // @ts-expect-error component wants actions2, which the factory never produces
+        InjectedRow,
+        { inject: () => ({ useRuns: () => 1 }) },
+      )
+      // 2. Inject factory produces a drifted value type for a declared key
+      //    (I infers from the component position here, so TS flags the factory).
+      registry.register(
+        'bash',
+        InjectedRow,
+        // @ts-expect-error useRuns returns string here, component wants number
+        { inject: () => ({ useRuns: () => 'one', actions2: { rerun: () => {} } }) },
+      )
+      // 3. Options object drifts: scope filter with a wrong parameter shape.
+      const badScope: ToolViewOptions<RowInjected> = {
+        // @ts-expect-error scope takes a SessionId, not a numeric index
+        scope: (index: number) => index > 0,
+      }
+      void badScope
+      // 4. Component demanding props outside ToolViewProps & I (a key neither
+      //    standard nor injected) cannot register even with a full factory.
+      const Overreaching: FC<ToolViewProps & RowInjected & { fromNowhere: boolean }> = () => null
+      registry.register(
+        'bash',
+        // @ts-expect-error fromNowhere is neither a standard prop nor produced by the factory
+        Overreaching,
+        { inject: (): RowInjected => ({ useRuns: () => 1, actions2: { rerun: () => {} } }) },
+      )
+      return null as ReactNode
+    }
+    expect(negatives).toBeTypeOf('function')
+  })
+})
+
+describe('tool-ring full chain (positive dual)', () => {
+  it('registers with an inferred inject share, resolves by scope order, and reads the erased face back', () => {
+    const registry = new ToolViewRegistry()
+    // Registration: I inferred from the factory, component proved ⊇ ToolViewProps & I.
+    const disposeGlobal = registry.register('bash', InjectedRow, {
+      inject: (b: SessionBinding): RowInjected => ({
+        useRuns: () => b.sessionId.length,
+        actions2: { rerun: () => {} },
+      }),
+    })
+    const disposeScoped = registry.register('bash', PlainRow, {
+      scope: id => id === sid('swarm-1'),
+    })
+
+    // Resolve: scope match beats global; elsewhere the global row wins.
+    expect(registry.resolve('bash', sid('swarm-1'))?.component).toBe(PlainRow)
+    const global = registry.resolve('bash', sid('other'))
+    expect(global?.component).toBe(InjectedRow)
+    // Read face: I is erased to object, the factory reference survives; the
+    // outlet-side restoration is the budgeted cast (same boundary as slots).
+    const injected = (global?.inject as (b: SessionBinding) => RowInjected)(
+      { sessionId: 'ab', session: { useSelector: undefined }, ctx: undefined },
+    )
+    expect(injected.useRuns()).toBe(2)
+    // Unknown tool → undefined (caller falls back to the generic card).
+    expect(registry.resolve('ghost-tool', sid('other'))).toBeUndefined()
+
+    disposeScoped()
+    expect(registry.resolve('bash', sid('swarm-1'))?.component).toBe(InjectedRow)
+    disposeGlobal()
+    expect(registry.resolve('bash', sid('other'))).toBeUndefined()
+  })
+})
diff --git a/packages/client/ui-conversation/tests/views-type-chain.spec.tsx b/packages/client/ui-conversation/tests/views-type-chain.spec.tsx
new file mode 100644
index 0000000000..31d9ccd4c7
--- /dev/null
+++ b/packages/client/ui-conversation/tests/views-type-chain.spec.tsx
@@ -0,0 +1,100 @@
+// View-ring type-chain samples (design §9 item 5, views half): the
+// register→inject→render chain composed through ConversationViewMap's
+// per-view extension shapes, plus expect-error duals for each stage.
+// Follows the slots-ring exemplar (ui-slots/tests/type-chain.spec.tsx):
+// negatives live in a never-executed function body; the positive dual runs
+// the real ConversationService view registry.
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import type { FC, ReactNode } from 'react'
+import type {
+  ChromePropsOf, ConvViewProps, ConvViewPropsOf, ViewEntry,
+} from '../src/client/contract/views.ts'
+import { ConversationService } from '../src/client/service.ts'
+
+// Test-only view keys with distinct extension shapes (merged like
+// ui-trajectory does; extension fields are optional per ViewEntryDef).
+declare module '../src/client/contract/views.ts' {
+  interface ConversationViewMap {
+    'vt-extended': { chromeProps: { statLabel: string }; extraProps: { density: 'compact' | 'wide' } }
+    'vt-plain': object
+  }
+}
+
+const ExtendedView: FC<ConvViewPropsOf<'vt-extended'>> = ({ density }) => (density === 'compact' ? null : null)
+const ExtendedChrome: FC<ChromePropsOf<'vt-extended'>> = ({ statLabel }) => (statLabel === '' ? null : null)
+const PlainView: FC<ConvViewPropsOf<'vt-plain'>> = () => null
+
+describe('view-ring type-chain negatives (compile-time; body never runs)', () => {
+  it('holds the negative samples as expect-error sites', () => {
+    const negatives = (service: ConversationService) => {
+      // 1. Registration: a component missing the entry's declared extraProps
+      //    cannot register under that id (props flow from the map entry).
+      const NarrowComp: FC<ConvViewProps & { density: number }> = () => null
+      service.registerView({
+        id: 'vt-extended',
+        label: 'x',
+        // @ts-expect-error density has the wrong value type vs the map entry's extraProps
+        component: NarrowComp,
+      })
+      // 2. Registration: chrome typed for another view's chromeProps drifts.
+      service.registerView({
+        id: 'vt-plain',
+        label: 'x',
+        component: PlainView,
+        // @ts-expect-error vt-plain declares no statLabel chromeProps
+        chrome: { footer: ExtendedChrome },
+      })
+      // 3. Registration: id outside the map is rejected at the entry.
+      service.registerView({
+        // @ts-expect-error unregistered view id
+        id: 'vt-ghost',
+        label: 'x',
+        component: PlainView,
+      })
+      // 4. Render side: per-view props narrow — the extended view's density
+      //    is not accessible under another id's props type.
+      const renderPlain = (props: ConvViewPropsOf<'vt-plain'>): ReactNode => {
+        // @ts-expect-error density belongs to vt-extended's extension, not vt-plain
+        return props.density === 'compact' ? null : null
+      }
+      void renderPlain
+      // 5. Entry-shape drift: ViewEntry<Id> ties chrome and component to the
+      //    SAME id — mixing ids inside one entry fails.
+      const mixed: ViewEntry<'vt-extended'> = {
+        id: 'vt-extended',
+        label: 'x',
+        component: ExtendedView,
+        // @ts-expect-error chrome for vt-plain cannot ride a vt-extended entry
+        chrome: { header: (props: ChromePropsOf<'vt-plain'> & { onlyPlain: true }) => null },
+      }
+      void mixed
+      return null as ReactNode
+    }
+    expect(negatives).toBeTypeOf('function')
+  })
+})
+
+describe('view-ring full chain (positive dual)', () => {
+  it('registers, lists, and renders through the per-view extension shapes', () => {
+    const ctx = new Context()
+    const service = new ConversationService(ctx)
+    // Registration: extension-typed component + same-id chrome compose cleanly.
+    const dispose = service.registerView({
+      id: 'vt-extended',
+      label: '扩展视图',
+      order: 7,
+      component: ExtendedView,
+      chrome: { footer: ExtendedChrome },
+    })
+    const entry = service.views().find(v => v.id === 'vt-extended')
+    expect(entry?.label).toBe('扩展视图')
+    // Render surface: the listed entry's component accepts the composed props
+    // (base ConvViewProps + the map extension), spelled here as the same type
+    // the runtime hands over.
+    expect(typeof entry?.component).toBe('function')
+    expect(typeof entry?.chrome?.footer).toBe('function')
+    dispose()
+    expect(service.views().some(v => v.id === 'vt-extended')).toBe(false)
+  })
+})
diff --git a/packages/client/ui-conversation/tsconfig.json b/packages/client/ui-conversation/tsconfig.json
new file mode 100644
index 0000000000..ed0065fa04
--- /dev/null
+++ b/packages/client/ui-conversation/tsconfig.json
@@ -0,0 +1,46 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "jsx": "react-jsx",
+    "lib": [
+      "ES2024",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": []
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../ui-primitives"
+    },
+    {
+      "path": "../web-react"
+    },
+    {
+      "path": "../runtime"
+    },
+    {
+      "path": "../ui-layout"
+    },
+    {
+      "path": "../i18n"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ],
+  "exclude": [
+    "**/*.legacy.*"
+  ]
+}
diff --git a/packages/client/ui-conversation/tsdown.config.ts b/packages/client/ui-conversation/tsdown.config.ts
new file mode 100644
index 0000000000..3a2c2da24d
--- /dev/null
+++ b/packages/client/ui-conversation/tsdown.config.ts
@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-ui-conversation', ['lib/types/index.js', 'lib/types/invariant.js'])
diff --git a/packages/client/ui-layout/README.md b/packages/client/ui-layout/README.md
new file mode 100644
index 0000000000..6c935f4b9d
--- /dev/null
+++ b/packages/client/ui-layout/README.md
@@ -0,0 +1,19 @@
+# @deepseek-ai/dsh-client-ui-layout
+
+Shell plugin: three-column AppFrame (drag handles, concession chain) + ctx.layout viewing-state service (nav, panel widths, persist); defines the sidebar/conversation/details/conversation.empty slots. Contract: api-contracts v3 §5.
+
+Slot declarations use the composed-props entry form (`owner` share, no full `props`): the exported OwnerShare contracts are `SidebarOwnerProps` / `ConvOwnerProps` / `DetailsOwnerProps` / `EmptyOwnerProps` — registrants reference them via `OwnerOf<'sidebar' | ...>` and compose their own injected share locally. The `conversation` entry authorizes `conversation.empty` delegation through `children`.
+
+## Model Experience
+
+None, as the layout shell manages browser viewing state; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Details open/width state is global** — it does not follow the session (arbitrated for P-I); the per-session keyed upgrade slot is reserved.
+- **Concession-chain auto-close derives a zero width without touching the persisted open flag** — the panel restores itself when the window widens; consumers must not read `details.open` as the rendered truth.
+- **Scroll anchoring during squeeze reflow is not implemented** — deferred with the virtualized-list project.
diff --git a/packages/client/ui-layout/package.json b/packages/client/ui-layout/package.json
new file mode 100644
index 0000000000..f9c556c26a
--- /dev/null
+++ b/packages/client/ui-layout/package.json
@@ -0,0 +1,59 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-layout",
+  "description": "Shell plugin: three-column AppFrame with drag handles, ctx.layout viewing-state service (navigation + panels)",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-client-runtime"
+    ],
+    "platform": "web"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-client-web-react": "workspace:^",
+    "react": "^18.2.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}
diff --git a/packages/client/ui-layout/src/client/AppFrame.module.css b/packages/client/ui-layout/src/client/AppFrame.module.css
new file mode 100644
index 0000000000..b7a03c7f2f
--- /dev/null
+++ b/packages/client/ui-layout/src/client/AppFrame.module.css
@@ -0,0 +1,73 @@
+.frame {
+  position: relative; /* anchors the drag handles, which straddle column borders */
+  display: grid;
+  grid-template-rows: 100%;
+  height: 100%;
+  overflow: hidden;
+  background: var(--dsw-alias-bg-base);
+}
+
+.sidebarCol {
+  min-width: 0;
+  overflow: hidden;
+  background: var(--dsw-specific-sidebar-fill);
+  border-right: 1px solid var(--dsw-alias-border-l1);
+}
+
+.centerCol {
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.detailsCol {
+  min-width: 0;
+  overflow: hidden;
+  border-left: 1px solid var(--dsw-alias-border-l2);
+}
+
+/* Collapsed columns keep children mounted; the border must not paint a 1px seam.
+   Flags live on the frame — DetailsColumn renders inside the provider body and
+   does not know its own width. */
+.frame[data-sidebar-collapsed] .sidebarCol {
+  border-right: none;
+}
+
+.frame[data-details-collapsed] .detailsCol {
+  border-left: none;
+}
+
+/* Drag handles are frame children (columns clip overflow): an 8px hit strip
+   centered on the column border via inline left, above column content. The
+   visible pill (12x32 r10, riding the border at vertical center) is the figma
+   Handle component; the hit strip stays wider than the pill. */
+.handle {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 8px;
+  margin-left: -4px;
+  cursor: col-resize;
+  z-index: 2;
+  touch-action: none;
+}
+
+.handle::after {
+  content: '';
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  width: 12px;
+  height: 32px;
+  border-radius: 10px;
+  box-sizing: border-box;
+  background: var(--dsw-alias-bg-layer-2);
+  border: 1px solid var(--dsw-alias-border-l2-darkmode-thin);
+}
+
+.handle:hover::after,
+.handle[data-dragging='true']::after {
+  border-color: var(--dsw-alias-border-l3);
+}
diff --git a/packages/client/ui-layout/src/client/AppFrame.tsx b/packages/client/ui-layout/src/client/AppFrame.tsx
new file mode 100644
index 0000000000..a7efd09311
--- /dev/null
+++ b/packages/client/ui-layout/src/client/AppFrame.tsx
@@ -0,0 +1,149 @@
+/**
+ * Three-column shell frame. Owns the grid tracks (sidebar | center | details),
+ * the two drag handles (pointer capture + rAF throttle), and the concession
+ * chain (columns.ts). Column content arrives via props: `sidebar` is the
+ * sidebar slot render, `children` is the session area (the shell mounts
+ * SessionProvider there; its body renders {@link CenterColumn} and
+ * {@link DetailsColumn}, which land as grid items because neither the provider
+ * nor fragments emit DOM). Zero cordis imports — stores and actions are
+ * injected as props.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { ReactNode } from 'react'
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
+import { computeColumns } from './columns.ts'
+import type { PanelState } from './service.ts'
+import css from './AppFrame.module.css'
+
+/** AppFrame props: injected viewing-state hooks, stable width actions, column content. */
+export interface AppFrameProps {
+  /** Selector hook over the sidebar panel store. */
+  useSidebar: SnapshotSelectorHook<PanelState>
+  /** Selector hook over the details panel store. */
+  useDetails: SnapshotSelectorHook<PanelState>
+  /** Persist a sidebar width preference (service clamps). */
+  setSidebarWidth: (px: number) => void
+  /** Persist a details width preference (service clamps). */
+  setDetailsWidth: (px: number) => void
+  /** Sidebar column content (shell: renderSlot('sidebar')). */
+  sidebar: ReactNode
+  /** Session area (shell: SessionProvider whose body renders CenterColumn + DetailsColumn). */
+  children?: ReactNode
+}
+
+/** Center column grid item; rendered inside the session provider's body. */
+export function CenterColumn(props: { children?: ReactNode }) {
+  return <div className={css.centerCol}>{props.children}</div>
+}
+
+/** Details column grid item; width 0 keeps the subtree mounted (never unmount on close). */
+export function DetailsColumn(props: { children?: ReactNode }) {
+  return <div className={css.detailsCol}>{props.children}</div>
+}
+
+/** One drag handle: pointer capture, rAF-throttled dx reports against the drag-start origin. */
+function DragHandle(props: { left: number; onStart: () => void; onDrag: (dx: number) => void }) {
+  const [dragging, setDragging] = useState(false)
+  const origin = useRef(0)
+  const latest = useRef(0)
+  const frame = useRef<number | null>(null)
+  const callbacks = useRef({ onStart: props.onStart, onDrag: props.onDrag })
+  callbacks.current = { onStart: props.onStart, onDrag: props.onDrag }
+
+  const onPointerDown = useCallback((e: React.PointerEvent<HTMLDivElement>) => {
+    e.preventDefault()
+    e.currentTarget.setPointerCapture(e.pointerId)
+    origin.current = e.clientX
+    latest.current = e.clientX
+    callbacks.current.onStart()
+    setDragging(true)
+  }, [])
+  const onPointerMove = useCallback((e: React.PointerEvent<HTMLDivElement>) => {
+    if (!e.currentTarget.hasPointerCapture(e.pointerId)) return
+    latest.current = e.clientX
+    frame.current ??= requestAnimationFrame(() => {
+      frame.current = null
+      callbacks.current.onDrag(latest.current - origin.current)
+    })
+  }, [])
+  const onPointerUp = useCallback((e: React.PointerEvent<HTMLDivElement>) => {
+    if (!e.currentTarget.hasPointerCapture(e.pointerId)) return
+    e.currentTarget.releasePointerCapture(e.pointerId)
+    if (frame.current !== null) { cancelAnimationFrame(frame.current); frame.current = null }
+    callbacks.current.onDrag(latest.current - origin.current)
+    setDragging(false)
+  }, [])
+
+  return (
+    <div
+      className={css.handle}
+      style={{ left: props.left }}
+      data-dragging={dragging || undefined}
+      onPointerDown={onPointerDown}
+      onPointerMove={onPointerMove}
+      onPointerUp={onPointerUp}
+    />
+  )
+}
+
+/** The three-column frame (see module doc). */
+export function AppFrame(props: AppFrameProps) {
+  const sidebar = props.useSidebar((s) => s)
+  const details = props.useDetails((s) => s)
+  const frameRef = useRef<HTMLDivElement | null>(null)
+  const [viewport, setViewport] = useState(() => window.innerWidth)
+
+  // Track the frame's own box (not the window): rAF-throttled ResizeObserver.
+  useEffect(() => {
+    const el = frameRef.current
+    /* v8 ignore next -- the ref is always attached by effect time: the frame div renders unconditionally. */
+    if (el === null) return
+    let raf: number | null = null
+    const observer = new ResizeObserver(() => {
+      raf ??= requestAnimationFrame(() => {
+        raf = null
+        const width = el.getBoundingClientRect().width
+        if (width > 0) setViewport(width)
+      })
+    })
+    observer.observe(el)
+    return () => {
+      observer.disconnect()
+      if (raf !== null) cancelAnimationFrame(raf)
+    }
+  }, [])
+
+  const cols = computeColumns(viewport, sidebar, details)
+  const colsRef = useRef(cols)
+  colsRef.current = cols
+
+  // The drag base is the rendered width captured at drag start (grabbing a
+  // concession-clamped panel must not jump back to the persisted preference);
+  // it stays frozen for the whole gesture so dx deltas do not compound.
+  const sidebarBase = useRef(0)
+  const detailsBase = useRef(0)
+  const { setSidebarWidth, setDetailsWidth } = props
+  const onSidebarStart = useCallback(() => { sidebarBase.current = colsRef.current.sidebar }, [])
+  const onDetailsStart = useCallback(() => { detailsBase.current = colsRef.current.details }, [])
+  const onSidebarDrag = useCallback((dx: number) => {
+    setSidebarWidth(sidebarBase.current + dx)
+  }, [setSidebarWidth])
+  const onDetailsDrag = useCallback((dx: number) => {
+    setDetailsWidth(detailsBase.current - dx)
+  }, [setDetailsWidth])
+
+  return (
+    <div
+      ref={frameRef}
+      className={css.frame}
+      style={{ gridTemplateColumns: `${cols.sidebar}px minmax(0, 1fr) ${cols.details}px` }}
+      data-sidebar-collapsed={cols.sidebar === 0 || undefined}
+      data-details-collapsed={cols.details === 0 || undefined}
+    >
+      <div className={css.sidebarCol}>{props.sidebar}</div>
+      {props.children}
+      {cols.sidebar > 0 && <DragHandle left={cols.sidebar} onStart={onSidebarStart} onDrag={onSidebarDrag} />}
+      {cols.details > 0 && <DragHandle left={viewport - cols.details} onStart={onDetailsStart} onDrag={onDetailsDrag} />}
+    </div>
+  )
+}
diff --git a/packages/client/ui-layout/src/client/columns.ts b/packages/client/ui-layout/src/client/columns.ts
new file mode 100644
index 0000000000..b6950c19e3
--- /dev/null
+++ b/packages/client/ui-layout/src/client/columns.ts
@@ -0,0 +1,79 @@
+/**
+ * Pure concession-chain column solver for the three-column AppFrame.
+ * Chain order is fixed by contract: keep center >= CENTER_MIN by shrinking
+ * details first, then sidebar, then auto-closing details (derived zero width —
+ * persisted open/width preferences are never rewritten, so widening the window
+ * restores them). Center absorbs any remaining deficit as the last resort.
+ */
+
+/** Panel viewing state consumed by the solver (mirrors LayoutService PanelState). */
+export interface PanelInput { open: boolean; width: number }
+
+/** Resolved widths for one frame; center may drop below CENTER_MIN only at the final fallback. */
+export interface Columns { sidebar: number; center: number; details: number }
+
+// Contract-frozen geometry: the three-column concession chain's fixed points.
+/** Center column floor; only the final fallback may go below it. */
+export const CENTER_MIN = 640
+/** Sidebar drag clamp floor. */
+export const SIDEBAR_MIN = 240
+/** Sidebar drag clamp ceiling. */
+export const SIDEBAR_MAX = 420
+/** Sidebar width before any user drag. */
+export const SIDEBAR_DEFAULT = 300
+/** Details drag clamp floor. */
+export const DETAILS_MIN = 300
+/** Details drag clamp ceiling. */
+export const DETAILS_MAX = 520
+/** Details width before any user drag. */
+export const DETAILS_DEFAULT = 360
+
+/**
+ * Clamp a panel width into its contract range.
+ * @param px - requested width.
+ * @param min - range lower bound.
+ * @param max - range upper bound.
+ * @returns the clamped width.
+ */
+export function clampWidth(px: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, Math.round(px)))
+}
+
+/**
+ * Solve the three column widths for one viewport frame. Pure: no hysteresis —
+ * the output is a function of (viewport, preferences) only, so recovery on
+ * re-widening is automatic. After the auto-close step the details pressure is
+ * gone, so the sidebar returns to its preferred width when it fits.
+ * @param viewport - available frame width in px.
+ * @param sidebar - sidebar preference (open flag + persisted width).
+ * @param details - details preference (open flag + persisted width).
+ * @returns resolved widths; details 0 means visually closed (never unmounted).
+ */
+export function computeColumns(viewport: number, sidebar: PanelInput, details: PanelInput): Columns {
+  const want = (p: PanelInput, min: number, max: number): number =>
+    p.open ? clampWidth(p.width, min, max) : 0
+  const s0 = want(sidebar, SIDEBAR_MIN, SIDEBAR_MAX)
+  const d0 = want(details, DETAILS_MIN, DETAILS_MAX)
+
+  // Step 1: everything fits at preferred widths.
+  if (s0 + d0 + CENTER_MIN <= viewport) return { sidebar: s0, center: viewport - s0 - d0, details: d0 }
+
+  // Step 2: shrink details toward its minimum.
+  const d1 = d0 === 0 ? 0 : Math.max(DETAILS_MIN, viewport - s0 - CENTER_MIN)
+  if (s0 + d1 + CENTER_MIN <= viewport) return { sidebar: s0, center: CENTER_MIN, details: d1 }
+
+  // Step 3: shrink sidebar toward its minimum.
+  const s1 = s0 === 0 ? 0 : Math.max(SIDEBAR_MIN, viewport - d1 - CENTER_MIN)
+  if (s1 + d1 + CENTER_MIN <= viewport) return { sidebar: s1, center: CENTER_MIN, details: d1 }
+
+  // Step 4: auto-close details (derived — preferences untouched). With the
+  // details pressure gone the sidebar concession is re-solved from preference.
+  if (d1 > 0) {
+    if (s0 + CENTER_MIN <= viewport) return { sidebar: s0, center: viewport - s0, details: 0 }
+    const s2 = s0 === 0 ? 0 : Math.max(SIDEBAR_MIN, viewport - CENTER_MIN)
+    return { sidebar: s2, center: Math.max(0, viewport - s2), details: 0 }
+  }
+
+  // Step 5: center absorbs the deficit (may drop below CENTER_MIN).
+  return { sidebar: s1, center: Math.max(0, viewport - s1 - d1), details: d1 }
+}
diff --git a/packages/client/ui-layout/src/client/index.ts b/packages/client/ui-layout/src/client/index.ts
new file mode 100644
index 0000000000..e07c5d9896
--- /dev/null
+++ b/packages/client/ui-layout/src/client/index.ts
@@ -0,0 +1,81 @@
+/**
+ * Layout plugin, browser half: three-column AppFrame plus ctx.layout, the
+ * shell-level viewing-state authority (navigation + panel geometry).
+ * Contract: api-contracts v3 section 5. apply provides the service and
+ * defines the three top-level slots; frame components are exported for the
+ * web shell's assembly (the shell resolves this surface from the loader
+ * module table and closes the slots over its own scopedSlots).
+ */
+import type { Context } from 'cordis'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import { LayoutService } from './service.ts'
+
+export { AppFrame, CenterColumn, DetailsColumn, type AppFrameProps } from './AppFrame.tsx'
+export {
+  clampWidth, computeColumns,
+  CENTER_MIN, DETAILS_DEFAULT, DETAILS_MAX, DETAILS_MIN, SIDEBAR_DEFAULT, SIDEBAR_MAX, SIDEBAR_MIN,
+  type Columns, type PanelInput,
+} from './columns.ts'
+export { LayoutService, type NavState, type PanelState, type ViewId } from './service.ts'
+
+declare module 'cordis' {
+  interface Context {
+    layout: LayoutService
+  }
+}
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    'sidebar': { kind: 'single'; scope: 'root'; owner: SidebarOwnerProps }
+    // children deliberately absent on every entry: the B-a validation layer
+    // gates COMPONENT delegation, and no P-I slot component delegates —
+    // conversation.empty is rendered by the shell's assembly closure, not
+    // handed down by ConversationRoot (its slots face is ScopedSlots<never>).
+    'conversation': { kind: 'single'; scope: 'session'; owner: ConvOwnerProps }
+    'details': { kind: 'single'; scope: 'session'; owner: DetailsOwnerProps }
+    'conversation.empty': { kind: 'single'; scope: 'root'; owner: EmptyOwnerProps }
+  }
+}
+
+// OwnerShare contracts — the render-side share the slot owner supplies at
+// renderSlot. Registrants IMPORT these and compose their full component props
+// as OwnerOf<K> & StandardOf<K> & OwnInjected (reference, never re-typed).
+
+/** Sidebar owner share: the owner supplies nothing — everything arrives via inject. */
+export interface SidebarOwnerProps { slots?: never }
+
+/** Conversation owner share. */
+export interface ConvOwnerProps { sessionId: SessionId }
+
+/** Details owner share. */
+export interface DetailsOwnerProps { sessionId: SessionId }
+
+/** Empty-state owner share (ui-conversation registers EmptyState here). */
+export interface EmptyOwnerProps { slots?: never }
+
+/** Required services (cordis fiber inject — the loader passes the whole export surface as an object plugin). */
+export const inject = ['slots']
+
+/**
+ * Client plugin body: provide ctx.layout and define the three top-level slots.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: Context): void {
+  const layout = new LayoutService(ctx)
+  ctx.effect(() => {
+    const disposeService = ctx.reflect.provide('layout', layout)
+    const disposeSidebar = ctx.slots.define('sidebar', { kind: 'single', scope: 'root' })
+    const disposeConversation = ctx.slots.define('conversation', { kind: 'single', scope: 'session' })
+    const disposeDetails = ctx.slots.define('details', { kind: 'single', scope: 'session' })
+    const disposeEmpty = ctx.slots.define('conversation.empty', { kind: 'single', scope: 'root' })
+    return () => {
+      disposeEmpty()
+      disposeDetails()
+      disposeConversation()
+      disposeSidebar()
+      // provide()'s disposer settles asynchronously; teardown is synchronous fire-and-forget.
+      void disposeService()
+      layout.dispose()
+    }
+  }, 'ui-layout: service + slot definitions')
+}
diff --git a/packages/client/ui-layout/src/client/service.ts b/packages/client/ui-layout/src/client/service.ts
new file mode 100644
index 0000000000..fbf92d9ea4
--- /dev/null
+++ b/packages/client/ui-layout/src/client/service.ts
@@ -0,0 +1,132 @@
+/**
+ * LayoutService implementation: the shell-level viewing-state authority.
+ * Four persisted stores (nav + two panels); actions clamp and validate. The
+ * concession chain lives in columns.ts and never writes back into these
+ * stores — persisted preferences survive window shrinking.
+ */
+import type { Context } from 'cordis'
+import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import type { SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  clampWidth, DETAILS_DEFAULT, DETAILS_MAX, DETAILS_MIN,
+  SIDEBAR_DEFAULT, SIDEBAR_MAX, SIDEBAR_MIN,
+} from './columns.ts'
+
+/** Active conversation view id (keys merged into ConversationViewMap by ui-conversation). */
+export type ViewId = string
+
+/** Navigation state: selected session and per-session active view. */
+export interface NavState { sessionId?: SessionId; viewFor: Record<SessionId, ViewId> }
+
+/** Panel viewing state: open flag plus persisted width. */
+export interface PanelState { open: boolean; width: number }
+
+/** Shell-level viewing-state authority (zustand + persist). */
+export class LayoutService {
+  /** Navigation state store. */
+  readonly current: SnapshotStore<NavState>
+  /** Sidebar panel store (default 300, clamp [240, 420]). */
+  readonly sidebar: SnapshotStore<PanelState>
+  /** Details panel store (default 360, clamp [300, 520]; P-I global, not per-session). */
+  readonly details: SnapshotStore<PanelState>
+
+  #sessions: SessionsService
+  #unprune: () => void
+
+  /**
+   * @param ctx - root context (resolves the sessions service for open validation and list pruning).
+   */
+  constructor(ctx: Context) {
+    // ctx.get instead of ctx.sessions: the typed Context merge is suspended
+    // while the client/host `sessions` declaration collision awaits
+    // arbitration (see the runtime package's Context merge note).
+    const sessions = ctx.get('sessions')
+    if (sessions === undefined) throw new Error('layout: sessions service unavailable')
+    this.#sessions = sessions
+    this.current = createSnapshotStore<NavState>(
+      { viewFor: {} },
+      { persist: { name: 'dsh.layout.nav' } })
+    this.sidebar = createSnapshotStore<PanelState>(
+      { open: true, width: SIDEBAR_DEFAULT },
+      { persist: { name: 'dsh.layout.sidebar' } })
+    this.details = createSnapshotStore<PanelState>(
+      { open: false, width: DETAILS_DEFAULT },
+      { persist: { name: 'dsh.layout.details' } })
+    // Prune is one-directional: list removals clear keyed viewing state, and a
+    // selection pointing at a removed session falls back to the empty state.
+    this.#unprune = sessions.list.subscribe(() => { this.#prune() })
+  }
+
+  /** Drop the sessions.list subscription (plugin teardown). */
+  dispose(): void {
+    this.#unprune()
+  }
+
+  #prune(): void {
+    const byId = this.#sessions.list.getSnapshot().byId
+    const nav = this.current.getSnapshot()
+    // Object.keys erases the branded key type; these entries were written with SessionId keys.
+    const viewKeys = Object.keys(nav.viewFor) as SessionId[]
+    const staleView = viewKeys.some(id => byId[id] === undefined)
+    const staleCurrent = nav.sessionId !== undefined && byId[nav.sessionId] === undefined
+    if (!staleView && !staleCurrent) return
+    this.current.update((draft) => {
+      // Rebuild instead of dynamic delete: viewFor is a plain keyed record and
+      // the survivors are the entries whose session still exists.
+      draft.viewFor = Object.fromEntries(
+        Object.entries(draft.viewFor).filter(([id]) => byId[id as SessionId] !== undefined))
+      if (draft.sessionId !== undefined && byId[draft.sessionId] === undefined) delete draft.sessionId
+    })
+  }
+
+  /**
+   * Select a session. Unknown ids fail loud instead of navigating nowhere.
+   * @param id - session id (must exist in sessions.list).
+   */
+  open(id: SessionId): void {
+    if (this.#sessions.list.getSnapshot().byId[id] === undefined) {
+      throw new Error(`layout.open: unknown session ${id}`)
+    }
+    this.current.update((draft) => { draft.sessionId = id })
+  }
+
+  /**
+   * Activate a view for a session.
+   * @param sessionId - session id.
+   * @param view - view id.
+   */
+  openView(sessionId: SessionId, view: ViewId): void {
+    this.current.update((draft) => { draft.viewFor[sessionId] = view })
+  }
+
+  /** Toggle the sidebar panel. */
+  toggleSidebar(): void {
+    this.sidebar.update((draft) => { draft.open = !draft.open })
+  }
+
+  /**
+   * Set the sidebar width (clamped to [240, 420]).
+   * @param px - width in pixels.
+   */
+  setSidebarWidth(px: number): void {
+    this.sidebar.update((draft) => { draft.width = clampWidth(px, SIDEBAR_MIN, SIDEBAR_MAX) })
+  }
+
+  /** Open the details panel. */
+  openDetails(): void {
+    this.details.update((draft) => { draft.open = true })
+  }
+
+  /** Close the details panel. */
+  closeDetails(): void {
+    this.details.update((draft) => { draft.open = false })
+  }
+
+  /**
+   * Set the details width (clamped to [300, 520]).
+   * @param px - width in pixels.
+   */
+  setDetailsWidth(px: number): void {
+    this.details.update((draft) => { draft.width = clampWidth(px, DETAILS_MIN, DETAILS_MAX) })
+  }
+}
diff --git a/packages/client/ui-layout/src/css-modules.d.ts b/packages/client/ui-layout/src/css-modules.d.ts
new file mode 100644
index 0000000000..bc5e482353
--- /dev/null
+++ b/packages/client/ui-layout/src/css-modules.d.ts
@@ -0,0 +1,6 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css'
diff --git a/packages/client/ui-layout/src/index.ts b/packages/client/ui-layout/src/index.ts
new file mode 100644
index 0000000000..da118e25e2
--- /dev/null
+++ b/packages/client/ui-layout/src/index.ts
@@ -0,0 +1,10 @@
+/**
+ * Layout plugin, node half. Pure UI plugin: the empty apply exists so the
+ * plugin appears in the host cordis.yml / Loader (load and lifecycle follow
+ * the host; the browser half ships via exports["./client"], discovered
+ * through the package.json dshClient declaration). Contract: api-contracts
+ * v3 sections 0.3 and 5.
+ */
+
+/** Host plugin body — no host-side behavior for the layout plugin. */
+export function apply(): void {}
diff --git a/packages/client/ui-layout/src/invariant.ts b/packages/client/ui-layout/src/invariant.ts
new file mode 100644
index 0000000000..fa46392b5d
--- /dev/null
+++ b/packages/client/ui-layout/src/invariant.ts
@@ -0,0 +1,31 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-layout`.
+ * @module @deepseek-ai/dsh-client-ui-layout/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-layout'
+
+/** Cordis companion plugin name. */
+export const name = 'client-ui-layout-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: shell viewing-state stores (zustand+persist) behind
+ * ctx.layout — it emits no cordis events; clamp/prune/concession-chain
+ * sequencing is asserted directly by this package's columns and service specs.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/client/ui-layout/tests/app-frame.spec.tsx b/packages/client/ui-layout/tests/app-frame.spec.tsx
new file mode 100644
index 0000000000..dfc49be327
--- /dev/null
+++ b/packages/client/ui-layout/tests/app-frame.spec.tsx
@@ -0,0 +1,208 @@
+// @vitest-environment jsdom
+/**
+ * AppFrame interaction spec: drag sequences (pointer capture + rAF flush),
+ * concession response to viewport change, details stays mounted at zero
+ * width. jsdom has no layout engine, so the frame width comes from a mocked
+ * getBoundingClientRect and resizes are driven through the ResizeObserver
+ * stub; assertions read the inline grid template.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, render } from '@testing-library/react'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import { AppFrame, CenterColumn, DetailsColumn, type PanelState } from '@deepseek-ai/dsh-client-ui-layout/client'
+import { clampWidth } from '@deepseek-ai/dsh-client-ui-layout/client'
+
+/** Observer stub: captures the callback so tests can fire resizes manually. */
+let fireResize: (() => void) | null = null
+class ResizeObserverStub {
+  #cb: ResizeObserverCallback
+  constructor(cb: ResizeObserverCallback) { this.#cb = cb }
+  observe(): void { fireResize = () => { this.#cb([], this as unknown as ResizeObserver) } }
+  unobserve(): void {}
+  disconnect(): void { fireResize = null }
+}
+
+let frameWidth = 1920
+
+function mountFrame() {
+  window.innerWidth = frameWidth // first-render viewport source before the observer fires
+  const sidebar = createSnapshotStore<PanelState>({ open: true, width: 300 })
+  const details = createSnapshotStore<PanelState>({ open: true, width: 360 })
+  const utils = render(
+    <AppFrame
+      useSidebar={sidebar.useSelector}
+      useDetails={details.useSelector}
+      setSidebarWidth={(px) => { sidebar.update((d) => { d.width = clampWidth(px, 240, 420) }) }}
+      setDetailsWidth={(px) => { details.update((d) => { d.width = clampWidth(px, 300, 520) }) }}
+      sidebar={<div data-testid="sidebar-content" />}
+    >
+      <CenterColumn><div data-testid="center-content" /></CenterColumn>
+      <DetailsColumn><div data-testid="details-content" /></DetailsColumn>
+    </AppFrame>,
+  )
+  const frame = utils.container.firstElementChild as HTMLElement
+  return { sidebar, details, frame, ...utils }
+}
+
+function tracks(frame: HTMLElement): number[] {
+  const m = /^(\d+)px minmax\(0, 1fr\) (\d+)px$/.exec(frame.style.gridTemplateColumns)
+  if (m === null) throw new Error(`unexpected template: ${frame.style.gridTemplateColumns}`)
+  return [Number(m[1]), Number(m[2])]
+}
+
+function drag(handle: Element, fromX: number, toX: number): void {
+  const down = new PointerEvent('pointerdown', { pointerId: 1, clientX: fromX, bubbles: true })
+  const move = new PointerEvent('pointermove', { pointerId: 1, clientX: toX, bubbles: true })
+  const up = new PointerEvent('pointerup', { pointerId: 1, clientX: toX, bubbles: true })
+  act(() => { handle.dispatchEvent(down) })
+  act(() => { handle.dispatchEvent(move); vi.advanceTimersByTime(20) })
+  act(() => { handle.dispatchEvent(up) })
+}
+
+beforeEach(() => {
+  frameWidth = 1920
+  vi.useFakeTimers()
+  vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+  vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => setTimeout(() => { cb(0) }, 16) as unknown as number)
+  vi.stubGlobal('cancelAnimationFrame', (h: number) => { clearTimeout(h) })
+  window.innerWidth = frameWidth
+  Element.prototype.getBoundingClientRect = function () {
+    return { width: frameWidth, height: 1080, top: 0, left: 0, right: frameWidth, bottom: 1080, x: 0, y: 0, toJSON: () => ({}) } as DOMRect
+  }
+  // jsdom lacks pointer capture: emulate per-element so hasPointerCapture gates pass.
+  const captured = new WeakSet<Element>()
+  Element.prototype.setPointerCapture = function () { captured.add(this) }
+  Element.prototype.releasePointerCapture = function () { captured.delete(this) }
+  Element.prototype.hasPointerCapture = function () { return captured.has(this) }
+})
+
+afterEach(() => {
+  cleanup()
+  vi.useRealTimers()
+  vi.unstubAllGlobals()
+})
+
+describe('AppFrame', () => {
+  it('renders three tracks from panel state', () => {
+    const { frame } = mountFrame()
+    expect(tracks(frame)).toEqual([300, 360])
+  })
+
+  it('sidebar drag widens through rAF-batched pointer moves', () => {
+    const { frame } = mountFrame()
+    const handles = frame.querySelectorAll('[class*="handle"]')
+    drag(handles[0]!, 300, 350)
+    expect(tracks(frame)[0]).toBe(350)
+  })
+
+  it('details drag widens leftward (negative dx grows the panel)', () => {
+    const { frame } = mountFrame()
+    const handles = frame.querySelectorAll('[class*="handle"]')
+    drag(handles[1]!, 1560, 1500)
+    expect(tracks(frame)[1]).toBe(420)
+  })
+
+  it('drag base is the rendered (concession-clamped) width, not the preference', () => {
+    frameWidth = 1250 // step-2 squeeze: details renders 310 while preference is 360
+    const { frame, details } = mountFrame()
+    expect(tracks(frame)).toEqual([300, 310])
+    const handles = frame.querySelectorAll('[class*="handle"]')
+    drag(handles[1]!, 940, 950) // shrink by 10 from the rendered width
+    expect(details.getSnapshot().width).toBe(300)
+  })
+
+  it('details column stays mounted at zero width', () => {
+    const { frame, details, getByTestId } = mountFrame()
+    act(() => { details.update((d) => { d.open = false }) })
+    expect(tracks(frame)).toEqual([300, 0])
+    expect(getByTestId('details-content')).toBeTruthy()
+    expect(frame.hasAttribute('data-details-collapsed')).toBe(true)
+  })
+
+  it('viewport shrink triggers the concession chain via ResizeObserver', () => {
+    const { frame } = mountFrame()
+    frameWidth = 1250
+    act(() => { fireResize?.(); vi.advanceTimersByTime(20) })
+    expect(tracks(frame)).toEqual([300, 310])
+    frameWidth = 1920
+    act(() => { fireResize?.(); vi.advanceTimersByTime(20) })
+    expect(tracks(frame)).toEqual([300, 360])
+  })
+
+  it('drag handles disappear for collapsed columns', () => {
+    const { frame, details, sidebar } = mountFrame()
+    expect(frame.querySelectorAll('[class*="handle"]')).toHaveLength(2)
+    act(() => { details.update((d) => { d.open = false }) })
+    expect(frame.querySelectorAll('[class*="handle"]')).toHaveLength(1)
+    act(() => { sidebar.update((d) => { d.open = false }) })
+    expect(frame.querySelectorAll('[class*="handle"]')).toHaveLength(0)
+  })
+})
+
+describe('AppFrame — guard branches', () => {
+  it('pointer moves without capture are ignored (no width write)', () => {
+    const { frame, sidebar } = mountFrame()
+    const handle = frame.querySelectorAll('[class*="handle"]')[0]!
+    const before = sidebar.getSnapshot().width
+    // Move + up without a preceding pointerdown: hasPointerCapture is false.
+    act(() => {
+      handle.dispatchEvent(new PointerEvent('pointermove', { pointerId: 9, clientX: 500, bubbles: true }))
+      vi.advanceTimersByTime(20)
+      handle.dispatchEvent(new PointerEvent('pointerup', { pointerId: 9, clientX: 500, bubbles: true }))
+    })
+    expect(sidebar.getSnapshot().width).toBe(before)
+  })
+
+  it('two moves inside one frame coalesce through the pending rAF', () => {
+    const { frame, sidebar } = mountFrame()
+    const handle = frame.querySelectorAll('[class*="handle"]')[0]!
+    act(() => { handle.dispatchEvent(new PointerEvent('pointerdown', { pointerId: 1, clientX: 300, bubbles: true })) })
+    act(() => {
+      // Two moves before the frame flushes: the second must ride the pending
+      // rAF (frame.current ??= guard), and the flush sees the latest x.
+      handle.dispatchEvent(new PointerEvent('pointermove', { pointerId: 1, clientX: 320, bubbles: true }))
+      handle.dispatchEvent(new PointerEvent('pointermove', { pointerId: 1, clientX: 340, bubbles: true }))
+      vi.advanceTimersByTime(20)
+    })
+    act(() => { handle.dispatchEvent(new PointerEvent('pointerup', { pointerId: 1, clientX: 340, bubbles: true })) })
+    expect(sidebar.getSnapshot().width).toBe(340)
+  })
+
+  it('pointerup with a pending rAF cancels it and commits the final position', () => {
+    const { frame, sidebar } = mountFrame()
+    const handle = frame.querySelectorAll('[class*="handle"]')[0]!
+    act(() => { handle.dispatchEvent(new PointerEvent('pointerdown', { pointerId: 1, clientX: 300, bubbles: true })) })
+    act(() => {
+      handle.dispatchEvent(new PointerEvent('pointermove', { pointerId: 1, clientX: 360, bubbles: true }))
+      // No timer advance: the rAF is still pending when pointerup arrives.
+      handle.dispatchEvent(new PointerEvent('pointerup', { pointerId: 1, clientX: 360, bubbles: true }))
+    })
+    expect(sidebar.getSnapshot().width).toBe(360)
+  })
+
+  it('zero-width resize reports are ignored (display:none window)', () => {
+    const { frame } = mountFrame()
+    frameWidth = 0
+    act(() => { fireResize?.(); vi.advanceTimersByTime(20) })
+    // Track template still reflects the last non-zero viewport.
+    expect(tracks(frame)).toEqual([300, 360])
+  })
+})
+
+describe('AppFrame — unmount with an in-flight resize frame', () => {
+  it('cancels the pending rAF on unmount (no post-unmount setState)', () => {
+    const { unmount } = mountFrame()
+    frameWidth = 800
+    act(() => { fireResize?.() }) // rAF scheduled, NOT flushed
+    unmount()
+    // Flushing after unmount must be a no-op (the frame was cancelled).
+    expect(() => { vi.advanceTimersByTime(20) }).not.toThrow()
+  })
+
+  it('double resize inside one frame rides the pending rAF (?"?= guard)', () => {
+    const { frame } = mountFrame()
+    frameWidth = 1250
+    act(() => { fireResize?.(); fireResize?.(); vi.advanceTimersByTime(20) })
+    expect(tracks(frame)).toEqual([300, 310])
+  })
+})
diff --git a/packages/client/ui-layout/tests/apply.spec.ts b/packages/client/ui-layout/tests/apply.spec.ts
new file mode 100644
index 0000000000..da49028b34
--- /dev/null
+++ b/packages/client/ui-layout/tests/apply.spec.ts
@@ -0,0 +1,71 @@
+// @vitest-environment jsdom
+// Client apply wiring: ctx.layout provided, the four layout-owned slots
+// defined, teardown cascades (service unprovided + slot specs removed + list
+// subscription dropped). Node half and the invariant companion ride along —
+// they are one-line surfaces the aggregate coverage gate still requires
+// exercised.
+
+import { Context } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
+import { apply, inject, LayoutService } from '@deepseek-ai/dsh-client-ui-layout/client'
+import { apply as nodeApply } from '@deepseek-ai/dsh-client-ui-layout'
+import * as invariant from '@deepseek-ai/dsh-client-ui-layout/invariant'
+
+async function bench() {
+  const ctx = new Context()
+  const slotsFiber = ctx.plugin(SlotsService)
+  await slotsFiber.await()
+  const list = createSnapshotStore<SessionListState>({ ids: [], byId: {} })
+  ctx.provide('sessions', { list })
+  return { ctx, slots: ctx.get('slots') as SlotsService }
+}
+
+describe('ui-layout client apply', () => {
+  it('declares its service dependencies', () => {
+    expect(inject).toContain('slots')
+  })
+
+  it('provides ctx.layout and defines the four layout-owned slots', async () => {
+    const { ctx, slots } = await bench()
+    const fiber = ctx.plugin({ inject: ['slots'], apply })
+    await fiber.await()
+    expect(ctx.get('layout')).toBeInstanceOf(LayoutService)
+    expect(slots.spec('sidebar')).toEqual({ kind: 'single', scope: 'root' })
+    expect(slots.spec('conversation')).toEqual({ kind: 'single', scope: 'session' })
+    expect(slots.spec('details')).toEqual({ kind: 'single', scope: 'session' })
+    expect(slots.spec('conversation.empty')).toEqual({ kind: 'single', scope: 'root' })
+  })
+
+  it('teardown unwinds service, slot specs, and the prune subscription', async () => {
+    const { ctx, slots } = await bench()
+    const fiber = ctx.plugin({ inject: ['slots'], apply })
+    await fiber.await()
+    const layout = ctx.get('layout') as LayoutService
+    const disposeSpy = vi.spyOn(layout, 'dispose')
+    await fiber.dispose()
+    expect(ctx.get('layout')).toBeUndefined()
+    expect(slots.spec('sidebar')).toBeUndefined()
+    expect(slots.spec('conversation.empty')).toBeUndefined()
+    expect(disposeSpy).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('node half + invariant companion', () => {
+  it('node apply is an intentional no-op (loader-managed lifecycle only)', () => {
+    nodeApply()
+    expect(true).toBe(true) // reaching here without throw is the contract
+  })
+
+  it('invariant companion registers under the package name', async () => {
+    const register = vi.fn().mockReturnValue(() => {})
+    const ctx = { invariants: { register } } as never
+    const dispose = await invariant.apply(ctx)
+    expect(register).toHaveBeenCalledWith('@deepseek-ai/dsh-client-ui-layout', expect.any(Function))
+    // The installer is the declared no-op — calling it must not throw.
+    expect(() => { (register.mock.calls[0]![1] as (c: never) => void)(undefined as never) }).not.toThrow()
+    expect(dispose).toBeTypeOf('function')
+  })
+})
diff --git a/packages/client/ui-layout/tests/columns.spec.ts b/packages/client/ui-layout/tests/columns.spec.ts
new file mode 100644
index 0000000000..49d351a6d4
--- /dev/null
+++ b/packages/client/ui-layout/tests/columns.spec.ts
@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest'
+import {
+  CENTER_MIN, clampWidth, computeColumns,
+  DETAILS_DEFAULT, DETAILS_MIN, SIDEBAR_DEFAULT, SIDEBAR_MIN,
+} from '@deepseek-ai/dsh-client-ui-layout/client'
+
+const open = (width: number) => ({ open: true, width })
+const closed = (width: number) => ({ open: false, width })
+
+describe('clampWidth', () => {
+  it('clamps into the range and rounds', () => {
+    expect(clampWidth(250.4, 240, 420)).toBe(250)
+    expect(clampWidth(100, 240, 420)).toBe(240)
+    expect(clampWidth(9999, 240, 420)).toBe(420)
+  })
+})
+
+describe('computeColumns', () => {
+  it('step 1: everything fits at preferred widths', () => {
+    const cols = computeColumns(1920, open(SIDEBAR_DEFAULT), open(DETAILS_DEFAULT))
+    expect(cols).toEqual({ sidebar: 300, center: 1920 - 300 - 360, details: 360 })
+  })
+
+  it('closed panels contribute zero width', () => {
+    expect(computeColumns(1920, closed(300), closed(360))).toEqual({ sidebar: 0, center: 1920, details: 0 })
+  })
+
+  it('preferences beyond the clamp range are clamped before solving', () => {
+    const cols = computeColumns(1920, open(9999), open(1))
+    expect(cols.sidebar).toBe(420)
+    expect(cols.details).toBe(300)
+  })
+
+  it('step 2: details shrinks first, center pinned at min', () => {
+    // 300 + 360 + 640 = 1300 > 1250; details concedes to 1250-300-640 = 310.
+    const cols = computeColumns(1250, open(SIDEBAR_DEFAULT), open(DETAILS_DEFAULT))
+    expect(cols).toEqual({ sidebar: 300, center: CENTER_MIN, details: 310 })
+  })
+
+  it('boundary: exactly at the step-1/step-2 seam', () => {
+    const cols = computeColumns(300 + 360 + CENTER_MIN, open(300), open(360))
+    expect(cols).toEqual({ sidebar: 300, center: CENTER_MIN, details: 360 })
+    const one = computeColumns(300 + 360 + CENTER_MIN - 1, open(300), open(360))
+    expect(one).toEqual({ sidebar: 300, center: CENTER_MIN, details: 359 })
+  })
+
+  it('step 3: sidebar concedes after details hits its min', () => {
+    // details floor 300: sidebar = 1220-300-640 = 280.
+    const cols = computeColumns(1220, open(SIDEBAR_DEFAULT), open(DETAILS_DEFAULT))
+    expect(cols).toEqual({ sidebar: 280, center: CENTER_MIN, details: DETAILS_MIN })
+  })
+
+  it('step 4: details auto-closes when both panels are at min and center still starves', () => {
+    // 240 + 300 + 640 = 1180 > 1100 → details 0; sidebar preference (300) fits: 1100-300 = 800 center.
+    const cols = computeColumns(1100, open(SIDEBAR_DEFAULT), open(DETAILS_DEFAULT))
+    expect(cols).toEqual({ sidebar: 300, center: 800, details: 0 })
+  })
+
+  it('step 4 keeps squeezing sidebar when preference no longer fits', () => {
+    // 900 < 300+640: sidebar = max(240, 900-640) = 260.
+    const cols = computeColumns(900, open(SIDEBAR_DEFAULT), open(DETAILS_DEFAULT))
+    expect(cols).toEqual({ sidebar: 260, center: CENTER_MIN, details: 0 })
+  })
+
+  it('step 5: center absorbs the deficit as last resort (details closed)', () => {
+    // 700 < 240+640: sidebar floors at 240, center takes 460 < CENTER_MIN.
+    const cols = computeColumns(700, open(SIDEBAR_DEFAULT), closed(DETAILS_DEFAULT))
+    expect(cols).toEqual({ sidebar: SIDEBAR_MIN, center: 460, details: 0 })
+  })
+
+  it('sidebar-closed narrow window: details concedes then auto-closes', () => {
+    const fits = computeColumns(DETAILS_MIN + CENTER_MIN, closed(300), open(DETAILS_DEFAULT))
+    expect(fits).toEqual({ sidebar: 0, center: CENTER_MIN, details: DETAILS_MIN })
+    const starved = computeColumns(DETAILS_MIN + CENTER_MIN - 1, closed(300), open(DETAILS_DEFAULT))
+    expect(starved).toEqual({ sidebar: 0, center: DETAILS_MIN + CENTER_MIN - 1, details: 0 })
+  })
+
+  it('tiny viewport: both panels yield everything to center', () => {
+    const cols = computeColumns(400, open(SIDEBAR_DEFAULT), open(DETAILS_DEFAULT))
+    expect(cols.details).toBe(0)
+    expect(cols.sidebar).toBe(SIDEBAR_MIN)
+    expect(cols.center).toBe(Math.max(0, 400 - SIDEBAR_MIN))
+  })
+
+  it('recovery is pure: re-widening restores preferred widths untouched', () => {
+    const squeezed = computeColumns(1100, open(SIDEBAR_DEFAULT), open(DETAILS_DEFAULT))
+    expect(squeezed.details).toBe(0)
+    const restored = computeColumns(1920, open(SIDEBAR_DEFAULT), open(DETAILS_DEFAULT))
+    expect(restored.details).toBe(DETAILS_DEFAULT)
+    expect(restored.sidebar).toBe(SIDEBAR_DEFAULT)
+  })
+})
+
+describe('computeColumns — degenerate viewports', () => {
+  it('sidebar closed and viewport below CENTER_MIN: details auto-closes, center takes all', () => {
+    // Reaches step 4's re-solve with s0 = 0 (the closed-sidebar arm).
+    expect(computeColumns(500, closed(300), open(DETAILS_DEFAULT)))
+      .toEqual({ sidebar: 0, center: 500, details: 0 })
+  })
+})
diff --git a/packages/client/ui-layout/tests/service.spec.ts b/packages/client/ui-layout/tests/service.spec.ts
new file mode 100644
index 0000000000..85d458cf7b
--- /dev/null
+++ b/packages/client/ui-layout/tests/service.spec.ts
@@ -0,0 +1,138 @@
+// @vitest-environment jsdom
+/**
+ * LayoutService over the real snapshot-store engine (persist rides jsdom
+ * localStorage). ctx is faked down to the one surface the service reads:
+ * ctx.sessions.list as a real store, so prune subscriptions are exercised
+ * for real.
+ */
+import { beforeEach, describe, expect, it } from 'vitest'
+import type { Context } from 'cordis'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import type { SessionId, SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
+import { LayoutService, DETAILS_DEFAULT, SIDEBAR_DEFAULT } from '@deepseek-ai/dsh-client-ui-layout/client'
+
+function makeCtx() {
+  const list = createSnapshotStore<SessionListState>({ ids: [], byId: {} })
+  // The service resolves sessions via ctx.get (typed merge suspended, see service).
+  const ctx = { get: (name: string) => (name === 'sessions' ? { list } : undefined) } as unknown as Context
+  return { ctx, list }
+}
+
+/** Test-side brand: specs mint ids the wire would normally brand. */
+const sid = (s: string): SessionId => s as SessionId
+const summary = (id: SessionId) => ({ id, title: id as string, running: false, updatedAt: 1 })
+
+beforeEach(() => { localStorage.clear() })
+
+describe('LayoutService', () => {
+  it('defaults: sidebar open 300, details closed 360, empty nav', () => {
+    const svc = new LayoutService(makeCtx().ctx)
+    expect(svc.sidebar.getSnapshot()).toEqual({ open: true, width: SIDEBAR_DEFAULT })
+    expect(svc.details.getSnapshot()).toEqual({ open: false, width: DETAILS_DEFAULT })
+    expect(svc.current.getSnapshot()).toEqual({ viewFor: {} })
+    svc.dispose()
+  })
+
+  it('open validates against sessions.list and selects', () => {
+    const { ctx, list } = makeCtx()
+    const svc = new LayoutService(ctx)
+    expect(() => { svc.open(sid('nope')) }).toThrow(/unknown session/)
+    list.update((d) => { d.ids.push(sid('s1')); d.byId[sid('s1')] = summary(sid('s1')) })
+    svc.open(sid('s1'))
+    expect(svc.current.getSnapshot().sessionId).toBe('s1')
+    svc.dispose()
+  })
+
+  it('width setters clamp into contract ranges', () => {
+    const svc = new LayoutService(makeCtx().ctx)
+    svc.setSidebarWidth(10)
+    expect(svc.sidebar.getSnapshot().width).toBe(240)
+    svc.setSidebarWidth(10_000)
+    expect(svc.sidebar.getSnapshot().width).toBe(420)
+    svc.setDetailsWidth(10)
+    expect(svc.details.getSnapshot().width).toBe(300)
+    svc.setDetailsWidth(10_000)
+    expect(svc.details.getSnapshot().width).toBe(520)
+    svc.dispose()
+  })
+
+  it('toggle and open/close flip flags without touching widths', () => {
+    const svc = new LayoutService(makeCtx().ctx)
+    svc.toggleSidebar()
+    expect(svc.sidebar.getSnapshot()).toEqual({ open: false, width: SIDEBAR_DEFAULT })
+    svc.openDetails()
+    expect(svc.details.getSnapshot().open).toBe(true)
+    svc.closeDetails()
+    expect(svc.details.getSnapshot().open).toBe(false)
+    svc.dispose()
+  })
+
+  it('prune clears viewFor entries and the current selection of removed sessions', () => {
+    const { ctx, list } = makeCtx()
+    const svc = new LayoutService(ctx)
+    list.update((d) => {
+      d.ids.push(sid('s1'), sid('s2'))
+      d.byId[sid('s1')] = summary(sid('s1'))
+      d.byId[sid('s2')] = summary(sid('s2'))
+    })
+    svc.open(sid('s1'))
+    svc.openView(sid('s1'), 'chat')
+    svc.openView(sid('s2'), 'chat')
+    list.update((d) => { d.ids = [sid('s2')]; d.byId = { [sid('s2')]: d.byId[sid('s2')]! } })
+    expect(svc.current.getSnapshot().sessionId).toBeUndefined()
+    expect(svc.current.getSnapshot().viewFor).toEqual({ s2: 'chat' })
+    svc.dispose()
+  })
+
+  it('prune leaves untouched state alone (no gratuitous store writes)', () => {
+    const { ctx, list } = makeCtx()
+    const svc = new LayoutService(ctx)
+    list.update((d) => { d.ids.push(sid('s1')); d.byId[sid('s1')] = summary(sid('s1')) })
+    svc.open(sid('s1'))
+    const before = svc.current.getSnapshot()
+    list.update((d) => { d.byId[sid('s1')] = { ...d.byId[sid('s1')]!, title: 'renamed' } })
+    expect(svc.current.getSnapshot()).toBe(before)
+    svc.dispose()
+  })
+
+  it('persists panel state and nav across instances (fresh service, same storage)', () => {
+    const first = new LayoutService(makeCtx().ctx)
+    first.setSidebarWidth(320)
+    first.openDetails()
+    first.dispose()
+    const second = new LayoutService(makeCtx().ctx)
+    expect(second.sidebar.getSnapshot().width).toBe(320)
+    expect(second.details.getSnapshot().open).toBe(true)
+    second.dispose()
+  })
+
+  it('dispose stops pruning', () => {
+    const { ctx, list } = makeCtx()
+    const svc = new LayoutService(ctx)
+    list.update((d) => { d.ids.push(sid('s1')); d.byId[sid('s1')] = summary(sid('s1')) })
+    svc.open(sid('s1'))
+    svc.dispose()
+    list.update((d) => { d.ids = []; d.byId = {} })
+    expect(svc.current.getSnapshot().sessionId).toBe('s1')
+  })
+})
+
+describe('LayoutService — construction and prune edge branches', () => {
+  it('throws loud when the sessions service is absent', () => {
+    const bare = { get: () => undefined } as unknown as Context
+    expect(() => new LayoutService(bare)).toThrow(/sessions service unavailable/)
+  })
+
+  it('prunes stale viewFor while the current selection stays valid', () => {
+    // Covers the prune branch where staleView holds but staleCurrent does not.
+    const { ctx, list } = makeCtx()
+    const svc = new LayoutService(ctx)
+    list.update((d) => { d.ids.push(sid('s1'), sid('s2')); d.byId[sid('s1')] = summary(sid('s1')); d.byId[sid('s2')] = summary(sid('s2')) })
+    svc.open(sid('s1'))
+    svc.openView(sid('s2'), 'chat')
+    list.update((d) => { d.ids = [sid('s1')]; d.byId = { [sid('s1')]: d.byId[sid('s1')]! } })
+    expect(svc.current.getSnapshot().sessionId).toBe('s1')
+    expect(svc.current.getSnapshot().viewFor).toEqual({})
+    svc.dispose()
+  })
+})
diff --git a/packages/client/ui-layout/tsconfig.json b/packages/client/ui-layout/tsconfig.json
new file mode 100644
index 0000000000..f2c03d8d12
--- /dev/null
+++ b/packages/client/ui-layout/tsconfig.json
@@ -0,0 +1,37 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "jsx": "react-jsx",
+    "lib": [
+      "ES2024",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": []
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../ui-primitives"
+    },
+    {
+      "path": "../web-react"
+    },
+    {
+      "path": "../runtime"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/client/ui-layout/tsdown.config.ts b/packages/client/ui-layout/tsdown.config.ts
new file mode 100644
index 0000000000..2b6bbfee86
--- /dev/null
+++ b/packages/client/ui-layout/tsdown.config.ts
@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-ui-layout', ['lib/types/index.js', 'lib/types/invariant.js'])
diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md
new file mode 100644
index 0000000000..29883df236
--- /dev/null
+++ b/packages/client/ui-primitives/README.md
@@ -0,0 +1,18 @@
+# @deepseek-ai/dsh-client-ui-primitives
+
+Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Input, markdown family (MessageText/JsonBlock). Contract: api-contracts v3 §8.
+
+## Model Experience
+
+None, as the package renders pure React atoms in the browser; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Glyph-level icons are redrawn approximations** — the fish logo (and the sparkle held by ui-conversation) come from font glyphs whose vector geometry is not exportable from the local design data; hand-authored recreations stand in until an exact export path exists.
+- **Pill and Input have no design source** — both atoms are self-defined; the sidebar search field and view-tab strip that resemble them are consumer-owned compositions, not these atoms.
+- **StateDot `Active` variant is a hidden placeholder in the design** — not implemented; the four shipped states (done/warning/ongoing/error) are the complete P-I surface.
+- **MessageText renders plain text** — markdown support swaps this component's internals later; consumers must not assume block structure.
diff --git a/packages/client/ui-primitives/package.json b/packages/client/ui-primitives/package.json
new file mode 100644
index 0000000000..2d23ecd330
--- /dev/null
+++ b/packages/client/ui-primitives/package.json
@@ -0,0 +1,42 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-primitives",
+  "description": "Pure React atoms for the dsh web UI: StateDot, ic_ds_* icon set, Button/Pill/Menu/Input, markdown family (zero cordis)",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "clsx": "^2.0.0",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/client/ui-primitives/src/Button.module.css b/packages/client/ui-primitives/src/Button.module.css
new file mode 100644
index 0000000000..1cb3b18194
--- /dev/null
+++ b/packages/client/ui-primitives/src/Button.module.css
@@ -0,0 +1,73 @@
+/* Capsule geometry from the figma Button component (1:155 instances:
+ * h36, pad 14/7, gap 4, r18; the wide New Session form is r24 at h38 —
+ * owners with the wide form set their own radius/width). */
+.button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 4px;
+  border: none;
+  border-radius: 18px;
+  cursor: pointer;
+  font-size: 14px;
+  line-height: 22px;
+  color: var(--dsw-alias-label-primary);
+  background: transparent;
+  padding: 0 14px;
+}
+
+.button:disabled {
+  cursor: not-allowed;
+  color: var(--dsw-alias-label-dimmed);
+}
+
+.md {
+  height: 36px;
+}
+
+/* Compact height for dense rows; no dedicated figma node (Icon_container
+ * 28x28 is the icon-only form) — geometry is ours. */
+.sm {
+  height: 28px;
+  font-size: 12px;
+  line-height: 18px;
+  padding: 0 10px;
+  border-radius: 14px;
+}
+
+.primary {
+  background: var(--dsw-alias-button-primary-fill);
+  color: var(--dsw-alias-label-primary-foreground);
+}
+
+.primary:hover:not(:disabled) {
+  background: var(--dsw-alias-button-primary-hover);
+}
+
+.primary:disabled {
+  background: var(--dsw-alias-button-primary-dimmed);
+}
+
+.ghost:hover:not(:disabled) {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.ghost:active:not(:disabled) {
+  background: var(--dsw-alias-interactive-bg-active);
+}
+
+.toolbar {
+  background: var(--dsw-alias-button-tool-bar-fill);
+}
+
+.toolbar:hover:not(:disabled) {
+  background: var(--dsw-alias-button-tool-bar-hover);
+}
+
+.icon {
+  display: inline-flex;
+  width: 16px;
+  height: 16px;
+  align-items: center;
+  justify-content: center;
+}
diff --git a/packages/client/ui-primitives/src/Button.tsx b/packages/client/ui-primitives/src/Button.tsx
new file mode 100644
index 0000000000..028c1fc266
--- /dev/null
+++ b/packages/client/ui-primitives/src/Button.tsx
@@ -0,0 +1,31 @@
+// Button: token-styled button atom. Variants map to the --dsw-alias-button-*
+// fill families; no framework imports, all behavior via props.
+
+import type { ButtonHTMLAttributes, ReactNode } from 'react'
+import clsx from 'clsx'
+import css from './Button.module.css'
+
+/** Visual variant, each backed by its --dsw-alias-button-* token family. */
+export type ButtonVariant = 'primary' | 'ghost' | 'toolbar'
+
+/**
+ * Render a button.
+ * @param props.variant - visual family (default 'ghost').
+ * @param props.size - 'md' 36px capsule (figma Button) or 'sm' 28px compact.
+ * @param props.icon - optional leading 16px icon node.
+ * @returns the button element; native button attributes pass through.
+ */
+export function Button({ variant = 'ghost', size = 'md', icon, className, children, ...rest }: {
+  variant?: ButtonVariant
+  size?: 'md' | 'sm'
+  icon?: ReactNode
+  className?: string
+  children?: ReactNode
+} & ButtonHTMLAttributes<HTMLButtonElement>) {
+  return (
+    <button type="button" className={clsx(css.button, css[variant], css[size], className)} {...rest}>
+      {icon != null && <span className={css.icon}>{icon}</span>}
+      {children}
+    </button>
+  )
+}
diff --git a/packages/client/ui-primitives/src/ConnectionBanner.module.css b/packages/client/ui-primitives/src/ConnectionBanner.module.css
new file mode 100644
index 0000000000..16908770bb
--- /dev/null
+++ b/packages/client/ui-primitives/src/ConnectionBanner.module.css
@@ -0,0 +1,13 @@
+.banner {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  z-index: 100;
+  padding: 4px 12px;
+  text-align: center;
+  font-size: 12px;
+  line-height: 18px;
+  background: var(--dsw-alias-state-error-primary);
+  color: var(--dsw-alias-label-primary-foreground);
+}
diff --git a/packages/client/ui-primitives/src/ConnectionBanner.tsx b/packages/client/ui-primitives/src/ConnectionBanner.tsx
new file mode 100644
index 0000000000..b87f329147
--- /dev/null
+++ b/packages/client/ui-primitives/src/ConnectionBanner.tsx
@@ -0,0 +1,16 @@
+// ConnectionBanner: top strip surfacing connection loss. The atom is pure:
+// the owner subscribes to connection state and passes `reconnecting` down.
+// A null/connecting state upstream should stay quiet too — only an actual
+// outage (reconnect backoff in progress) shows the strip.
+
+import css from './ConnectionBanner.module.css'
+
+/**
+ * Render the reconnecting banner.
+ * @param props.reconnecting - true while the connection is in backoff/retry.
+ * @returns the banner, or null when connected.
+ */
+export function ConnectionBanner({ reconnecting }: { reconnecting: boolean }) {
+  if (!reconnecting) return null
+  return <div className={css.banner}>连接已断开，正在重连…</div>
+}
diff --git a/packages/client/ui-primitives/src/FishLogo.tsx b/packages/client/ui-primitives/src/FishLogo.tsx
new file mode 100644
index 0000000000..9b882a850c
--- /dev/null
+++ b/packages/client/ui-primitives/src/FishLogo.tsx
@@ -0,0 +1,27 @@
+// DeepSeek fish logo (figma I39:24057;88:8943 fillGeometry, exact extract;
+// the full-canvas rectangle path from the raw dump is a background plate and
+// is intentionally dropped). Native 23.16x17.04, rendered 24x18 by default;
+// hero usage scales to 34x25. Color rides currentColor (wordmark ink).
+
+import type { IconProps } from './icons/props.ts'
+
+/**
+ * Render the fish logo.
+ * @param props.size - width in px (default 24; height keeps the 23.16:17.04 ratio).
+ * @param props.className - extra class for layout placement.
+ * @returns the logo svg (aria-hidden; pair with the wordmark for accessibility).
+ */
+export function FishLogo({ size = 24, className }: IconProps) {
+  return (
+    <svg
+      width={size}
+      height={(size * 17.04) / 23.16}
+      className={className}
+      viewBox="0 0 23.16 17.04"
+      fill="none"
+      aria-hidden="true"
+    >
+      <path d="M22.9168 1.43018C22.6713 1.31018 22.5658 1.53918 22.4223 1.65519C22.3733 1.69269 22.3318 1.74169 22.2903 1.78669C21.9317 2.1697 21.5127 2.42121 20.9657 2.39121C20.1657 2.34621 19.4827 2.59771 18.8787 3.20973C18.7502 2.45521 18.3236 2.0047 17.6746 1.71569C17.3351 1.56568 16.9916 1.41518 16.7536 1.08867C16.5876 0.856163 16.5421 0.597155 16.4591 0.341647C16.4061 0.187643 16.3536 0.0301382 16.1761 0.00363739C15.9836 -0.0263635 15.9081 0.135141 15.8326 0.270145C15.5306 0.822162 15.4136 1.43018 15.4251 2.0462C15.4516 3.43174 16.0366 4.53527 17.1991 5.3203C17.3311 5.4103 17.3651 5.5003 17.3236 5.63181C17.2441 5.90231 17.1501 6.16482 17.0671 6.43533C17.0141 6.60784 16.9351 6.64584 16.7501 6.57033C16.1121 6.30383 15.5611 5.90931 15.074 5.4328C14.2475 4.63328 13.5 3.75075 12.568 3.05973C12.349 2.89822 12.13 2.74822 11.9034 2.60522C10.9524 1.68169 12.028 0.923165 12.277 0.833162C12.5375 0.739159 12.3675 0.41615 11.5259 0.42015C10.6844 0.42365 9.91439 0.705658 8.93286 1.08117C8.78935 1.13767 8.63835 1.17867 8.48384 1.21267C7.59332 1.04367 6.66829 1.00617 5.70226 1.11517C3.88321 1.31768 2.43016 2.1777 1.36213 3.64575C0.0790928 5.4103 -0.222916 7.41536 0.146595 9.50642C0.535106 11.7105 1.66014 13.535 3.38869 14.9616C5.18125 16.4406 7.24581 17.1657 9.60138 17.0266C11.0319 16.9441 12.6245 16.7526 14.421 15.2321C14.874 15.4576 15.3496 15.5476 16.1381 15.6151C16.7456 15.6716 17.3306 15.5851 17.7836 15.4911C18.4931 15.3411 18.4441 14.6841 18.1876 14.5636C16.1081 13.595 16.5646 13.9891 16.1496 13.67C17.2061 12.42 18.8202 10.1979 19.3182 7.17235C19.3672 6.83834 19.4297 6.36783 19.4222 6.09732C19.4182 5.93231 19.4562 5.86831 19.6447 5.84931C20.1657 5.78931 20.6712 5.64681 21.1357 5.3913C22.4833 4.65528 23.0268 3.44624 23.1548 1.9972C23.1738 1.77569 23.1508 1.54668 22.9168 1.43018ZM11.1749 14.4736C9.15936 12.889 8.18184 12.3675 7.77832 12.39C7.40081 12.4125 7.46881 12.8445 7.55182 13.126C7.63882 13.404 7.75182 13.5955 7.91033 13.8396C8.01983 14.0011 8.09533 14.2411 7.80083 14.4216C7.15181 14.8231 6.02327 14.2866 5.97027 14.2601C4.65673 13.4865 3.5587 12.4655 2.78467 11.069C2.03715 9.72493 1.60314 8.28289 1.53164 6.74384C1.51264 6.37233 1.62214 6.24082 1.99215 6.17332C2.47916 6.08332 2.98118 6.06432 3.46769 6.13582C5.52476 6.43633 7.27581 7.35586 8.74385 8.8129C9.58188 9.64243 10.2159 10.634 10.8689 11.6025C11.5634 12.631 12.3105 13.611 13.262 14.4146C13.598 14.6961 13.866 14.9101 14.1225 15.0681C13.349 15.1546 12.058 15.1731 11.1749 14.4746L11.1749 14.4736ZM12.141 8.25988C12.141 8.09488 12.273 7.96338 12.439 7.96338C12.4765 7.96338 12.5105 7.97088 12.541 7.98188C12.5825 7.99688 12.6205 8.01938 12.6505 8.05338C12.7035 8.10588 12.7335 8.18088 12.7335 8.25988C12.7335 8.42489 12.6015 8.55639 12.4355 8.55639C12.2695 8.55639 12.141 8.42489 12.141 8.25988ZM15.1415 9.79893C14.949 9.87793 14.7565 9.94544 14.5715 9.95294C14.2845 9.96794 13.9715 9.85143 13.8015 9.70893C13.5375 9.48742 13.3485 9.36342 13.2695 8.97691C13.2355 8.8119 13.2545 8.55639 13.2845 8.40989C13.3525 8.09438 13.277 7.89187 13.0545 7.70787C12.8735 7.55786 12.643 7.51636 12.39 7.51636C12.2955 7.51636 12.209 7.47486 12.1445 7.44136C12.039 7.38886 11.9519 7.25735 12.035 7.09585C12.0615 7.04335 12.19 6.91584 12.22 6.89334C12.5635 6.69784 12.9595 6.76184 13.326 6.90834C13.6655 7.04735 13.9225 7.30236 14.292 7.66287C14.6695 8.09838 14.7375 8.21838 14.9525 8.54539C15.1225 8.8009 15.277 9.06341 15.3831 9.36392C15.4471 9.55142 15.3641 9.70493 15.1415 9.79893Z" fill="currentColor"/>
+    </svg>
+  )
+}
diff --git a/packages/client/ui-primitives/src/Input.module.css b/packages/client/ui-primitives/src/Input.module.css
new file mode 100644
index 0000000000..70258a3339
--- /dev/null
+++ b/packages/client/ui-primitives/src/Input.module.css
@@ -0,0 +1,38 @@
+.wrap {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  height: 32px;
+  padding: 0 8px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 8px;
+  background: var(--dsw-alias-bg-layer-1);
+}
+
+.wrap:focus-within {
+  border-color: var(--dsw-alias-brand-primary);
+}
+
+.icon {
+  display: inline-flex;
+  width: 16px;
+  height: 16px;
+  align-items: center;
+  justify-content: center;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.input {
+  flex: 1;
+  min-width: 0;
+  border: none;
+  outline: none;
+  background: transparent;
+  font-size: 14px;
+  line-height: 22px;
+  color: var(--dsw-alias-label-primary);
+}
+
+.input::placeholder {
+  color: var(--dsw-alias-label-dimmed);
+}
diff --git a/packages/client/ui-primitives/src/Input.tsx b/packages/client/ui-primitives/src/Input.tsx
new file mode 100644
index 0000000000..3af60f9d18
--- /dev/null
+++ b/packages/client/ui-primitives/src/Input.tsx
@@ -0,0 +1,23 @@
+// Input: single-line text input atom (search boxes, inline forms). Composer
+// textareas are NOT this atom — they live with the conversation package.
+
+import type { InputHTMLAttributes, ReactNode } from 'react'
+import clsx from 'clsx'
+import css from './Input.module.css'
+
+/**
+ * Render a text input with an optional leading icon.
+ * @param props.icon - optional 16px leading icon node.
+ * @returns wrapper span containing the native input; input attributes pass through.
+ */
+export function Input({ icon, className, ...rest }: {
+  icon?: ReactNode
+  className?: string
+} & InputHTMLAttributes<HTMLInputElement>) {
+  return (
+    <span className={clsx(css.wrap, className)}>
+      {icon != null && <span className={css.icon}>{icon}</span>}
+      <input className={css.input} {...rest} />
+    </span>
+  )
+}
diff --git a/packages/client/ui-primitives/src/Menu.module.css b/packages/client/ui-primitives/src/Menu.module.css
new file mode 100644
index 0000000000..3e3bf85299
--- /dev/null
+++ b/packages/client/ui-primitives/src/Menu.module.css
@@ -0,0 +1,68 @@
+.root {
+  position: relative;
+  display: inline-flex;
+}
+
+/* Dropdown card (figma MenuDropdown 122:10096): white card, r12, no border,
+ * layered drop shadows via the shadow token, 4px inset padding. */
+.list {
+  position: absolute;
+  top: calc(100% + 4px);
+  left: 0;
+  z-index: 100;
+  min-width: 130px;
+  padding: 4px;
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+  border-radius: 12px;
+  background: var(--dsw-alias-bg-layer-1);
+  box-shadow: var(--dsw-shadow-lv2);
+}
+
+.alignEnd {
+  left: auto;
+  right: 0;
+}
+
+/* Menu cell (figma .Menu_cell 27:5169): r10, pad 10/8, 14/22 primary text,
+ * gap 8 between leading icon / label / trailing check. */
+.item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 10px;
+  border: none;
+  border-radius: 10px;
+  background: transparent;
+  cursor: pointer;
+  font-size: 14px;
+  line-height: 22px;
+  color: var(--dsw-alias-label-primary);
+  text-align: left;
+}
+
+.item:hover:not(:disabled) {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.item:disabled {
+  color: var(--dsw-alias-label-dimmed);
+  cursor: not-allowed;
+}
+
+.itemLabel {
+  flex: 1;
+  min-width: 0;
+}
+
+.check {
+  flex: none;
+  color: var(--dsw-alias-label-primary);
+}
+
+/* Selected cell keeps the plain fill (marker is the trailing check); the
+ * class remains as a hook for owner-side emphasis. */
+.selected {
+  background: transparent;
+}
diff --git a/packages/client/ui-primitives/src/Menu.tsx b/packages/client/ui-primitives/src/Menu.tsx
new file mode 100644
index 0000000000..ad45acc221
--- /dev/null
+++ b/packages/client/ui-primitives/src/Menu.tsx
@@ -0,0 +1,81 @@
+// Menu: minimal controlled dropdown (group-by pickers, project selectors).
+// Pure CSS positioning relative to the anchor wrapper — no portal, no popper.
+// The owner controls `open`; outside-click closing uses one document listener
+// active only while open.
+
+import { useEffect, useRef } from 'react'
+import type { ReactNode } from 'react'
+import clsx from 'clsx'
+import { IconCheckOutline16 } from './icons/index.tsx'
+import css from './Menu.module.css'
+
+/** One selectable menu row. */
+export interface MenuItem {
+  id: string
+  label: ReactNode
+  disabled?: boolean
+}
+
+/**
+ * Render an anchored dropdown menu.
+ * @param props.open - whether the list is showing (owner-controlled).
+ * @param props.anchor - the trigger element (rendered in place).
+ * @param props.items - selectable rows.
+ * @param props.selectedId - row shown as selected.
+ * @param props.onSelect - row click callback (not called for disabled rows).
+ * @param props.onClose - invoked on outside click or Escape.
+ * @param props.align - list alignment against the anchor (default 'start').
+ * @returns anchor wrapper with the conditional list.
+ */
+export function Menu({ open, anchor, items, selectedId, onSelect, onClose, align = 'start', className }: {
+  open: boolean
+  anchor: ReactNode
+  items: readonly MenuItem[]
+  selectedId?: string
+  onSelect: (id: string) => void
+  onClose: () => void
+  align?: 'start' | 'end'
+  className?: string
+}) {
+  const rootRef = useRef<HTMLSpanElement>(null)
+
+  useEffect(() => {
+    if (!open) return
+    const onPointerDown = (e: PointerEvent) => {
+      if (rootRef.current && e.target instanceof Node && !rootRef.current.contains(e.target)) onClose()
+    }
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+    }
+    document.addEventListener('pointerdown', onPointerDown)
+    document.addEventListener('keydown', onKeyDown)
+    return () => {
+      document.removeEventListener('pointerdown', onPointerDown)
+      document.removeEventListener('keydown', onKeyDown)
+    }
+  }, [open, onClose])
+
+  return (
+    <span ref={rootRef} className={clsx(css.root, className)}>
+      {anchor}
+      {open && (
+        <div className={clsx(css.list, align === 'end' && css.alignEnd)} role="menu">
+          {items.map(item => (
+            <button
+              key={item.id}
+              type="button"
+              role="menuitem"
+              className={clsx(css.item, item.id === selectedId && css.selected)}
+              disabled={item.disabled}
+              onClick={() => onSelect(item.id)}
+            >
+              <span className={css.itemLabel}>{item.label}</span>
+              {/* Selection marker is a trailing check (figma .Menu_cell), not a fill. */}
+              {item.id === selectedId && <IconCheckOutline16 className={css.check} />}
+            </button>
+          ))}
+        </div>
+      )}
+    </span>
+  )
+}
diff --git a/packages/client/ui-primitives/src/Pill.module.css b/packages/client/ui-primitives/src/Pill.module.css
new file mode 100644
index 0000000000..8fb6cc0bda
--- /dev/null
+++ b/packages/client/ui-primitives/src/Pill.module.css
@@ -0,0 +1,27 @@
+.pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  height: 24px;
+  padding: 0 8px;
+  border: none;
+  border-radius: 12px;
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-secondary);
+  background: var(--dsw-alias-bg-layer-2);
+}
+
+.interactive {
+  cursor: pointer;
+}
+
+.interactive:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.active {
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-alias-button-ghost-active-fill);
+  box-shadow: inset 0 0 0 1px var(--dsw-alias-button-ghost-active-border);
+}
diff --git a/packages/client/ui-primitives/src/Pill.tsx b/packages/client/ui-primitives/src/Pill.tsx
new file mode 100644
index 0000000000..76b9301972
--- /dev/null
+++ b/packages/client/ui-primitives/src/Pill.tsx
@@ -0,0 +1,31 @@
+// Pill: small rounded label chip (view switcher tabs, filters, badges).
+
+import type { ButtonHTMLAttributes, ReactNode } from 'react'
+import clsx from 'clsx'
+import css from './Pill.module.css'
+
+/**
+ * Render a pill chip. Interactive when onClick is supplied (renders a button);
+ * otherwise a static span.
+ * @param props.active - selected/active visual state.
+ * @returns pill element.
+ */
+export function Pill({ active = false, className, children, onClick, ...rest }: {
+  active?: boolean
+  className?: string
+  children?: ReactNode
+} & ButtonHTMLAttributes<HTMLButtonElement>) {
+  if (!onClick) {
+    return <span className={clsx(css.pill, active && css.active, className)}>{children}</span>
+  }
+  return (
+    <button
+      type="button"
+      className={clsx(css.pill, css.interactive, active && css.active, className)}
+      onClick={onClick}
+      {...rest}
+    >
+      {children}
+    </button>
+  )
+}
diff --git a/packages/client/ui-primitives/src/StateDot.module.css b/packages/client/ui-primitives/src/StateDot.module.css
new file mode 100644
index 0000000000..e5a8ebdb50
--- /dev/null
+++ b/packages/client/ui-primitives/src/StateDot.module.css
@@ -0,0 +1,65 @@
+/* Ongoing blue has no alias token (state-business-primary is the 500 step,
+ * not this 450) — component-level var pinned to the static scale instead. */
+.dot,
+.ring {
+  --dsh-state-ongoing: var(--dsw-static-deepseek-450);
+}
+
+/* Solid states: same-color halo via a 0.10-opacity outer layer (::before)
+ * with a 6/10-scale solid core. Layer color rides currentColor set per state. */
+.dot {
+  position: relative;
+  display: inline-block;
+  flex: none;
+}
+
+.dot::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  border-radius: 50%;
+  background: currentColor;
+  opacity: 0.1;
+}
+
+.dot::after {
+  content: '';
+  position: absolute;
+  inset: 20%;
+  border-radius: 50%;
+  background: currentColor;
+}
+
+.dot[data-state='done'] {
+  color: var(--dsw-alias-state-success-primary);
+}
+
+.dot[data-state='warning'] {
+  color: var(--dsw-alias-state-warn-primary);
+}
+
+.dot[data-state='error'] {
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.ring {
+  flex: none;
+  color: var(--dsh-state-ongoing);
+  animation: dsh-state-dot-spin 1s linear infinite;
+}
+
+.stopFrom {
+  stop-color: currentColor;
+  stop-opacity: 1;
+}
+
+.stopTo {
+  stop-color: currentColor;
+  stop-opacity: 0;
+}
+
+@keyframes dsh-state-dot-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
diff --git a/packages/client/ui-primitives/src/StateDot.tsx b/packages/client/ui-primitives/src/StateDot.tsx
new file mode 100644
index 0000000000..c4117673ba
--- /dev/null
+++ b/packages/client/ui-primitives/src/StateDot.tsx
@@ -0,0 +1,55 @@
+// StateDot: session state indicator (figma nodes 14:3303/3305/3312, 122:9182).
+// done/warning/error: 10x10 halo (same color, 10% opacity) around a 6x6 solid
+// core. ongoing: 10x10 ring, 1px inside stroke, color fading out along a
+// linear gradient, spinning. Colors resolve through --dsw-* tokens only.
+
+import { useId } from 'react'
+import clsx from 'clsx'
+import css from './StateDot.module.css'
+
+/** Four-color session state semantic (green done / amber approval-waiting / blue running ring / red error). */
+export type StateDotState = 'done' | 'warning' | 'ongoing' | 'error'
+
+/**
+ * Render a state dot.
+ * @param props.state - which of the four states to show.
+ * @param props.size - outer diameter in px (default 10, the figma size).
+ * @param props.className - extra class for layout placement.
+ * @returns the dot element (aria-hidden; pair with text for accessibility).
+ */
+export function StateDot({ state, size = 10, className }: {
+  state: StateDotState
+  size?: number
+  className?: string
+}) {
+  const gradientId = useId()
+  if (state === 'ongoing') {
+    return (
+      <svg
+        className={clsx(css.ring, className)}
+        data-state="ongoing"
+        width={size}
+        height={size}
+        viewBox="0 0 10 10"
+        aria-hidden="true"
+      >
+        <defs>
+          {/* Gradient handles from the figma node: (0.1,0) -> (0.85,1). */}
+          <linearGradient id={gradientId} x1="1" y1="0" x2="8.5" y2="10" gradientUnits="userSpaceOnUse">
+            <stop className={css.stopFrom} offset="0" />
+            <stop className={css.stopTo} offset="1" />
+          </linearGradient>
+        </defs>
+        <circle cx="5" cy="5" r="4.5" fill="none" strokeWidth="1" stroke={`url(#${gradientId})`} />
+      </svg>
+    )
+  }
+  return (
+    <span
+      className={clsx(css.dot, className)}
+      data-state={state}
+      style={{ width: size, height: size }}
+      aria-hidden="true"
+    />
+  )
+}
diff --git a/packages/client/ui-primitives/src/css-modules.d.ts b/packages/client/ui-primitives/src/css-modules.d.ts
new file mode 100644
index 0000000000..bc5e482353
--- /dev/null
+++ b/packages/client/ui-primitives/src/css-modules.d.ts
@@ -0,0 +1,6 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css'
diff --git a/packages/client/ui-primitives/src/icons/index.tsx b/packages/client/ui-primitives/src/icons/index.tsx
new file mode 100644
index 0000000000..4f35833fb6
--- /dev/null
+++ b/packages/client/ui-primitives/src/icons/index.tsx
@@ -0,0 +1,575 @@
+/**
+ * ic_ds_* icon set for the dsh web UI. All glyphs render fill="currentColor"
+ * and take {size, className}. Batch A mirrors the deepsuite icon library
+ * (same figma source); batch B glyphs are harness-only figma extracts.
+ */
+import type { IconProps } from './props.ts'
+
+export type { IconProps } from './props.ts'
+
+/** ic_ds_new_chat_outline_16 */
+export const IconNewChatOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M8.00003 0.3237C3.76075 0.3237 0.32373 3.76072 0.32373 8C0.32373 9.17603 0.589121 10.2922 1.0632 11.2901L1.35291 11.8989L2.5705 11.3205L2.28079 10.7117C1.89079 9.89074 1.67301 8.97167 1.67301 8C1.67301 4.50546 4.50549 1.67298 8.00003 1.67298C11.4946 1.67298 14.3271 4.50546 14.3271 8C14.3271 11.4945 11.4946 14.327 8.00003 14.327C7.28473 14.327 6.76077 14.277 6.29621 14.1487C5.83857 14.0224 5.40441 13.8109 4.88514 13.4488C4.12569 12.919 3.03778 12.7316 2.141 13.2978L2.12682 13.307L2.11264 13.3171L1.34886 13.854L1.79659 15.188L2.86122 14.4384C3.19068 14.2305 3.68325 14.2542 4.11326 14.5539C4.72789 14.9826 5.30042 15.2724 5.93762 15.4484C6.56803 15.6224 7.22776 15.6763 8.00003 15.6763C12.2393 15.6763 15.6763 12.2393 15.6763 8C15.6763 3.76072 12.2393 0.3237 8.00003 0.3237ZM7.32033 4.82535V7.32536H4.82538V8.67464H7.32033V11.1747H8.6696V8.67464H11.1747V7.32536H8.6696V4.82535H7.32033Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_search_outline_16 */
+export const IconSearchOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M11.894845 6.647401C11.894845 3.725463 9.534486 1.356779 6.623219 1.35657C3.711786 1.35657 1.351635 3.725338 1.351635 6.647401C1.351843 9.569296 3.711911 11.938273 6.623219 11.938273C9.534361 11.938064 11.894637 9.569171 11.894845 6.647401ZM13.245462 6.647401C13.245254 10.317935 10.280401 13.293613 6.623219 13.293821C2.965871 13.293821 0.000204 10.31806 0 6.647401C0 2.976574 2.965746 0 6.623219 0C10.280526 0.000205 13.245462 2.9767 13.245462 6.647401Z"
+      fill="currentColor"
+    />
+    <path
+      d="M16.000417 15.041079L15.044449 16.000433L11.530434 12.473588L12.486298 11.514234L16.000417 15.041079Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_settings_outline_14 */
+export const IconSettingsOutline14 = ({ size = 14, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <g clipPath="url(#clip0_2580_121189)">
+      <path
+        d="M12.1192 4.91016C11.9392 4.52714 11.7007 4.1292 11.4483 3.78809C11.385 3.70258 11.3517 3.68409 11.2462 3.67383C10.7419 3.6248 10.2318 3.69454 9.72662 3.64551C9.29108 3.60318 8.93739 3.40341 8.67682 3.05176C8.38762 2.66127 8.19217 2.20926 7.90338 1.81934C7.83985 1.73359 7.80848 1.71542 7.70221 1.70508C7.24758 1.6609 6.7511 1.66104 6.29791 1.70508C6.19164 1.71542 6.16027 1.73359 6.09674 1.81934C5.80775 2.20954 5.61248 2.66131 5.3233 3.05176C5.06273 3.40341 4.70904 3.60318 4.2735 3.64551C3.76831 3.69454 3.25825 3.6248 2.75397 3.67383C2.6484 3.68409 2.61509 3.70258 2.55182 3.78809C2.30019 4.12814 2.06125 4.52646 1.88092 4.91016C1.83256 5.01309 1.83242 5.04912 1.88092 5.15235C2.07954 5.57482 2.37449 5.94529 2.5733 6.36817C2.76971 6.78606 2.76964 7.21293 2.5733 7.63086C2.37462 8.05374 2.07947 8.42453 1.88092 8.84668C1.83235 8.95004 1.83257 8.98695 1.88092 9.08985C2.06098 9.47285 2.2994 9.87079 2.55182 10.2119C2.61509 10.2974 2.6484 10.3159 2.75397 10.3262C3.25879 10.3753 3.76834 10.3055 4.2735 10.3545C4.70904 10.3968 5.06273 10.5966 5.3233 10.9482C5.6125 11.3387 5.80795 11.7907 6.09674 12.1807C6.16027 12.2664 6.19164 12.2846 6.29791 12.2949C6.7511 12.339 7.24758 12.3391 7.70221 12.2949C7.80848 12.2846 7.83985 12.2664 7.90338 12.1807C8.19237 11.7905 8.38764 11.3387 8.67682 10.9482C8.93739 10.5966 9.29108 10.3968 9.72662 10.3545C10.2318 10.3055 10.7419 10.3752 11.2462 10.3262C11.3517 10.3159 11.385 10.2974 11.4483 10.2119C11.7007 9.87079 11.9391 9.47285 12.1192 9.08985C12.1675 8.98695 12.1678 8.95004 12.1192 8.84668C11.9205 8.42428 11.6255 8.05377 11.4268 7.63086C11.2305 7.21293 11.2304 6.78606 11.4268 6.36817C11.6256 5.94531 11.9207 5.5746 12.1192 5.15235C12.1677 5.04912 12.1676 5.01309 12.1192 4.91016ZM13.2051 5.66309C13.0064 6.08573 12.7114 6.45579 12.5128 6.87793C12.4642 6.98123 12.4645 7.01829 12.5128 7.1211C12.7112 7.54328 13.0064 7.91405 13.2051 8.33692C13.4015 8.75487 13.4015 9.18169 13.2051 9.59961C12.9911 10.0551 12.7109 10.5221 12.4122 10.9258C12.1522 11.277 11.7974 11.4782 11.3624 11.5205C10.8573 11.5696 10.3477 11.4999 9.84283 11.5488C9.73621 11.5592 9.70429 11.5772 9.64069 11.6631C9.35229 12.0526 9.15705 12.5044 8.86823 12.8945C8.60854 13.2452 8.25275 13.447 7.81842 13.4893C7.28749 13.5409 6.71096 13.5407 6.1817 13.4893C5.74737 13.447 5.39158 13.2452 5.1319 12.8945C4.84312 12.5045 4.64808 12.0529 4.35944 11.6631C4.29583 11.5772 4.26392 11.5592 4.15729 11.5488C3.65283 11.5 3.14295 11.5696 2.63776 11.5205C2.20274 11.4782 1.84796 11.277 1.58795 10.9258C1.28834 10.5209 1.00864 10.0543 0.794982 9.59961C0.598644 9.18169 0.598598 8.75487 0.794982 8.33692C0.993688 7.91405 1.28889 7.54328 1.48737 7.1211C1.53567 7.01829 1.53593 6.98123 1.48737 6.87793C1.28887 6.45603 0.993667 6.08569 0.794982 5.66309C0.598535 5.24516 0.59869 4.81829 0.794982 4.40039C1.00898 3.94492 1.28922 3.47791 1.58795 3.07422C1.84796 2.723 2.20274 2.5218 2.63776 2.47949C3.14295 2.43038 3.65283 2.50003 4.15729 2.45117C4.26391 2.44081 4.29583 2.4228 4.35944 2.33692C4.64783 1.94742 4.84308 1.49557 5.1319 1.10547C5.39158 0.754835 5.74737 0.553005 6.1817 0.510744C6.71263 0.459147 7.28917 0.459309 7.81842 0.510744C8.25275 0.553005 8.60854 0.754835 8.86823 1.10547C9.157 1.49551 9.35204 1.94708 9.64069 2.33692C9.70429 2.4228 9.73621 2.44081 9.84283 2.45117C10.3477 2.50007 10.8573 2.43039 11.3624 2.47949C11.7974 2.5218 12.1522 2.723 12.4122 3.07422C12.7118 3.47909 12.9915 3.94567 13.2051 4.40039C13.4014 4.81829 13.4016 5.24516 13.2051 5.66309Z"
+        fill="currentColor"
+      />
+      <path
+        d="M7.9317 7C7.9317 6.48569 7.51438 6.06836 7.00006 6.06836C6.48575 6.06836 6.06842 6.48569 6.06842 7C6.06842 7.51432 6.48575 7.93164 7.00006 7.93164C7.51438 7.93164 7.9317 7.51432 7.9317 7ZM9.13092 7C9.13092 8.17706 8.17712 9.13086 7.00006 9.13086C5.823 9.13086 4.8692 8.17706 4.8692 7C4.8692 5.82294 5.823 4.86914 7.00006 4.86914C8.17712 4.86914 9.13092 5.82294 9.13092 7Z"
+        fill="currentColor"
+      />
+    </g>
+    <defs>
+      <clipPath id="clip0_2580_121189">
+        <rect width={14} height={14} fill="currentColor" />
+      </clipPath>
+    </defs>
+  </svg>
+)
+
+/** ic_ds_settings_outline_16 */
+export const IconSettingsOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <g clipPath="url(#clip0_1450_63327)">
+      <path
+        d="M14.0861 5.51366C13.8717 5.0575 13.588 4.58542 13.2889 4.18108C13.208 4.07172 13.1596 4.04373 13.0243 4.03054C12.4277 3.97255 11.8245 4.05527 11.2269 3.9972C10.7224 3.94816 10.3133 3.71661 10.0115 3.30919C9.66986 2.84777 9.43973 2.31343 9.09824 1.85234C9.01771 1.74365 8.96805 1.71589 8.83354 1.70282C8.29432 1.65044 7.70402 1.65061 7.16656 1.70282C7.03205 1.71589 6.98239 1.74365 6.90186 1.85234C6.56067 2.31303 6.33025 2.84774 5.98855 3.30919C5.68681 3.71661 5.27774 3.94816 4.77317 3.9972C4.17564 4.05527 3.57239 3.97255 2.97585 4.03054C2.84046 4.04373 2.79208 4.07172 2.71115 4.18108C2.41212 4.58542 2.12835 5.0575 1.91403 5.51366C1.85299 5.64359 1.85286 5.7018 1.91403 5.8319C2.14865 6.33077 2.49748 6.76892 2.73237 7.26854C2.9594 7.7515 2.96041 8.24717 2.73338 8.73044C2.49837 9.23061 2.14891 9.66837 1.91403 10.1681C1.85291 10.2982 1.85299 10.3564 1.91403 10.4863C2.12856 10.9429 2.41185 11.4142 2.71115 11.8189C2.79208 11.9283 2.84046 11.9563 2.97585 11.9694C3.57239 12.0274 4.17564 11.9447 4.77317 12.0028C5.27774 12.0518 5.68681 12.2834 5.98855 12.6908C6.33024 13.1522 6.56037 13.6866 6.90186 14.1476C6.98239 14.2563 7.03205 14.2841 7.16656 14.2972C7.70402 14.3494 8.29432 14.3495 8.83354 14.2972C8.96805 14.2841 9.01771 14.2563 9.09824 14.1476C9.43944 13.687 9.66985 13.1522 10.0115 12.6908C10.3133 12.2834 10.7224 12.0518 11.2269 12.0028C11.8244 11.9447 12.4271 12.0275 13.0243 11.9694C13.1596 11.9563 13.208 11.9283 13.2889 11.8189C13.5891 11.4131 13.872 10.942 14.0861 10.4863C14.1471 10.3564 14.1472 10.2982 14.0861 10.1681C13.8513 9.66861 13.5017 9.23061 13.2667 8.73044C13.0397 8.24717 13.0407 7.7515 13.2677 7.26854C13.5026 6.7689 13.8513 6.33106 14.0861 5.8319C14.1472 5.7018 14.1471 5.64359 14.0861 5.51366ZM15.3035 6.40373C15.0685 6.90359 14.7188 7.34119 14.4841 7.84037C14.4231 7.97025 14.423 8.02855 14.4841 8.15861C14.7189 8.65833 15.0685 9.09611 15.3035 9.59626C15.5308 10.0801 15.5308 10.5744 15.3035 11.0582C15.052 11.5933 14.7225 12.1426 14.37 12.6191C14.0685 13.0265 13.6581 13.259 13.1536 13.3081C12.5566 13.366 11.9541 13.2835 11.3573 13.3414C11.2228 13.3545 11.1731 13.3823 11.0926 13.491C10.7511 13.9521 10.521 14.4864 10.1793 14.9478C9.87828 15.3542 9.46719 15.5869 8.96387 15.6358C8.34008 15.6964 7.66194 15.6966 7.03623 15.6358C6.53291 15.5869 6.12182 15.3542 5.82084 14.9478C5.47911 14.4863 5.24878 13.9517 4.90753 13.491C4.82701 13.3823 4.77734 13.3545 4.64284 13.3414C4.04647 13.2835 3.44373 13.366 2.84653 13.3081C2.34201 13.259 1.93164 13.0265 1.63013 12.6191C1.27867 12.144 0.948453 11.5941 0.696621 11.0582C0.469315 10.5744 0.469279 10.0801 0.696621 9.59626C0.931628 9.09613 1.2813 8.65807 1.51597 8.15861C1.57708 8.02855 1.57702 7.97025 1.51597 7.84037C1.28117 7.34095 0.931635 6.9036 0.696621 6.40373C0.469213 5.91992 0.469367 5.42562 0.696621 4.94183C0.948441 4.40587 1.27868 3.85598 1.63013 3.38092C1.93164 2.97349 2.34201 2.74095 2.84653 2.6919C3.44353 2.63397 4.04599 2.71649 4.64284 2.65856C4.77734 2.64549 4.82701 2.61774 4.90753 2.50904C5.24905 2.04792 5.47913 1.51362 5.82084 1.05219C6.12182 0.645806 6.53291 0.413119 7.03623 0.364178C7.66002 0.303556 8.33816 0.303369 8.96387 0.364178C9.46719 0.413119 9.87828 0.645806 10.1793 1.05219C10.521 1.51365 10.7513 2.04828 11.0926 2.50904C11.1731 2.61774 11.2228 2.64549 11.3573 2.65856C11.9541 2.71649 12.5566 2.63397 13.1536 2.6919C13.6581 2.74095 14.0685 2.97349 14.37 3.38092C14.7214 3.85598 15.0517 4.40587 15.3035 4.94183C15.5307 5.42562 15.5309 5.91992 15.3035 6.40373Z"
+        fill="currentColor"
+      />
+      <path
+        d="M9.13764 7.99999C9.13764 7.3715 8.62855 6.8624 8.00005 6.8624C7.37155 6.8624 6.86246 7.3715 6.86246 7.99999C6.86246 8.62849 7.37155 9.13759 8.00005 9.13759C8.62855 9.13759 9.13764 8.62849 9.13764 7.99999ZM10.4834 7.99999C10.4834 9.37126 9.37132 10.4833 8.00005 10.4833C6.62878 10.4833 5.51674 9.37126 5.51674 7.99999C5.51674 6.62873 6.62878 5.51669 8.00005 5.51669C9.37132 5.51669 10.4834 6.62873 10.4834 7.99999Z"
+        fill="currentColor"
+      />
+    </g>
+    <defs>
+      <clipPath id="clip0_1450_63327">
+        <rect width={16} height={16} fill="currentColor" />
+      </clipPath>
+    </defs>
+  </svg>
+)
+
+/** ic_ds_panel_left_outline_16 */
+export const IconPanelLeftOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      fillRule="evenodd"
+      clipRule="evenodd"
+      d="M9.67272 0.522841C10.8339 0.522841 11.76 0.522714 12.4963 0.602493C13.2453 0.683657 13.8789 0.854248 14.4264 1.25197C14.7504 1.48739 15.0355 1.77247 15.2709 2.0965C15.6686 2.64394 15.8392 3.27758 15.9204 4.02655C16.0002 4.7629 16 5.68895 16 6.85014V9.14986C16 10.3111 16.0002 11.2371 15.9204 11.9735C15.8392 12.7224 15.6686 13.3561 15.2709 13.9035C15.0355 14.2275 14.7504 14.5126 14.4264 14.748C13.8789 15.1458 13.2453 15.3163 12.4963 15.3975C11.76 15.4773 10.8339 15.4772 9.67272 15.4772H6.3273C5.16611 15.4772 4.24006 15.4773 3.50371 15.3975C2.75474 15.3163 2.1211 15.1458 1.57366 14.748C1.24963 14.5126 0.964549 14.2275 0.729131 13.9035C0.331407 13.3561 0.160817 12.7224 0.0796529 11.9735C-0.000126137 11.2371 1.25338e-09 10.3111 1.25338e-09 9.14986V6.85014C1.25329e-09 5.68895 -0.000126137 4.7629 0.0796529 4.02655C0.160817 3.27758 0.331407 2.64394 0.729131 2.0965C0.964549 1.77247 1.24963 1.48739 1.57366 1.25197C2.1211 0.854248 2.75474 0.683657 3.50371 0.602493C4.24006 0.522714 5.16611 0.522841 6.3273 0.522841H9.67272ZM5.54303 1.88715V14.1118C5.78636 14.1128 6.04709 14.1169 6.3273 14.1169H9.67272C10.8639 14.1169 11.7032 14.1164 12.3493 14.0465C12.9824 13.9779 13.3497 13.8494 13.6268 13.6482C13.8354 13.4966 14.0195 13.3125 14.1711 13.1039C14.3723 12.8268 14.5007 12.4595 14.5693 11.8264C14.6393 11.1803 14.6398 10.341 14.6398 9.14986V6.85014C14.6398 5.65896 14.6393 4.81967 14.5693 4.1736C14.5007 3.54048 14.3723 3.17318 14.1711 2.89609C14.0195 2.68747 13.8354 2.50337 13.6268 2.35179C13.3497 2.1506 12.9824 2.02212 12.3493 1.95353C11.7032 1.88358 10.8639 1.88307 9.67272 1.88307H6.3273C6.04709 1.88307 5.78636 1.8862 5.54303 1.88715ZM4.1828 1.91166C3.99125 1.9216 3.8148 1.93577 3.65076 1.95353C3.01764 2.02212 2.65034 2.1506 2.37325 2.35179C2.16463 2.50337 1.98052 2.68747 1.82895 2.89609C1.62776 3.17318 1.49928 3.54048 1.43069 4.1736C1.36074 4.81967 1.36023 5.65896 1.36023 6.85014V9.14986C1.36023 10.341 1.36074 11.1803 1.43069 11.8264C1.49928 12.4595 1.62776 12.8268 1.82895 13.1039C1.98052 13.3125 2.16463 13.4966 2.37325 13.6482C2.65034 13.8494 3.01764 13.9779 3.65076 14.0465C3.81478 14.0642 3.99127 14.0774 4.1828 14.0873V1.91166Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_ellipsis_outline_16 */
+export const IconEllipsisOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M4.55146 8.00001C4.55146 8.63513 4.03659 9.15001 3.40146 9.15001C2.76634 9.15001 2.25146 8.63513 2.25146 8.00001C2.25146 7.36488 2.76634 6.85001 3.40146 6.85001C4.03659 6.85001 4.55146 7.36488 4.55146 8.00001Z"
+      fill="currentColor"
+    />
+    <path
+      d="M9.1476 8.00001C9.1476 8.63513 8.63273 9.15001 7.9976 9.15001C7.36248 9.15001 6.8476 8.63513 6.8476 8.00001C6.8476 7.36488 7.36248 6.85001 7.9976 6.85001C8.63273 6.85001 9.1476 7.36488 9.1476 8.00001Z"
+      fill="currentColor"
+    />
+    <path
+      d="M13.7486 8.00001C13.7486 8.63513 13.2338 9.15001 12.5986 9.15001C11.9635 9.15001 11.4486 8.63513 11.4486 8.00001C11.4486 7.36488 11.9635 6.85001 12.5986 6.85001C13.2338 6.85001 13.7486 7.36488 13.7486 8.00001Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_plus_outline_16 */
+export const IconPlusOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M8.64453 1.5V7.34961H14.5V8.65039H8.64453V14.5H7.34473V8.65039H1.5V7.34961H7.34473V1.5H8.64453Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_check_outline_16 */
+export const IconCheckOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M15.0498 3.92579L8.49512 12.3818C8.25774 12.6881 8.04517 12.9645 7.84668 13.1689C7.63957 13.3823 7.38732 13.5841 7.04492 13.6719C6.86373 13.7183 6.6757 13.7346 6.48926 13.7197C6.13666 13.6915 5.8528 13.5355 5.6123 13.3604C5.38201 13.1926 5.12573 12.9567 4.83984 12.6953L1.03125 9.21289L1.96875 8.1875L5.77734 11.6699C6.08684 11.9529 6.27773 12.1249 6.43066 12.2363C6.50183 12.2882 6.54699 12.3135 6.57324 12.3252C6.58525 12.3305 6.59269 12.3322 6.5957 12.333C6.59802 12.3336 6.59961 12.334 6.59961 12.334C6.63317 12.3367 6.66758 12.3335 6.7002 12.3252C6.7002 12.3252 6.70211 12.3251 6.7041 12.3242C6.70698 12.3229 6.71348 12.319 6.72461 12.3115C6.74849 12.2956 6.78843 12.2642 6.84961 12.2012C6.98138 12.0654 7.13957 11.8628 7.39648 11.5313L13.9502 3.07422L15.0498 3.92579Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_branch_outline_16 */
+export const IconBranchOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      fillRule="evenodd"
+      clipRule="evenodd"
+      d="M13.0762 1.37207C14.0846 1.37228 14.9021 2.19077 14.9023 3.19922C14.9022 4.20772 14.0847 5.02518 13.0762 5.02539C12.2967 5.02539 11.6325 4.53691 11.3701 3.84961H4.35547C4.79397 4.26458 5.15861 4.7644 5.41699 5.33496L7.10645 9.06738C7.88526 10.7875 9.55104 11.9228 11.4189 12.0371C11.7085 11.4109 12.3411 10.9756 13.0762 10.9756C14.0843 10.9759 14.9023 11.7936 14.9023 12.8018C14.9023 13.81 14.0843 14.6277 13.0762 14.6279C12.2534 14.6279 11.5574 14.0832 11.3291 13.335C8.9868 13.1879 6.89981 11.7612 5.92285 9.60352L4.23242 5.87109C3.67503 4.64033 2.44878 3.84961 1.09766 3.84961V2.54883C1.10665 2.54883 1.11601 2.54975 1.125 2.5498L11.3701 2.54883C11.6326 1.86151 12.2969 1.37207 13.0762 1.37207ZM13.0762 12.2764C12.7858 12.2764 12.5508 12.5114 12.5508 12.8018C12.5508 13.0921 12.7858 13.3281 13.0762 13.3281C13.3664 13.3279 13.6025 13.092 13.6025 12.8018C13.6025 12.5115 13.3664 12.2766 13.0762 12.2764ZM13.0762 2.67285C12.7855 2.67285 12.55 2.90861 12.5498 3.19922C12.5499 3.48987 12.7855 3.72559 13.0762 3.72559C13.3667 3.72538 13.6024 3.48975 13.6025 3.19922C13.6023 2.90874 13.3666 2.67306 13.0762 2.67285Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_chevron_down_outline_14 */
+export const IconChevronDownOutline14 = ({ size = 14, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M11.8486 5.5L11.4238 5.92383L8.69727 8.65137C8.44157 8.90706 8.21562 9.13382 8.01172 9.29785C7.79912 9.46883 7.55595 9.61756 7.25 9.66602C7.08435 9.69222 6.91565 9.69222 6.75 9.66602C6.44405 9.61756 6.20088 9.46883 5.98828 9.29785C5.78438 9.13382 5.55843 8.90706 5.30273 8.65137L2.57617 5.92383L2.15137 5.5L3 4.65137L3.42383 5.07617L6.15137 7.80273C6.42595 8.07732 6.59876 8.24849 6.74023 8.3623C6.87291 8.46904 6.92272 8.47813 6.9375 8.48047C6.97895 8.48703 7.02105 8.48703 7.0625 8.48047C7.07728 8.47813 7.12709 8.46904 7.25977 8.3623C7.40124 8.24849 7.57405 8.07732 7.84863 7.80273L10.5762 5.07617L11 4.65137L11.8486 5.5Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_chevron_left_outline_14 */
+export const IconChevronLeftOutline14 = ({ size = 14, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M8.5 2.15137L8.07617 2.57617L5.34863 5.30273C5.09294 5.55843 4.86618 5.78438 4.70215 5.98828C4.53117 6.20088 4.38244 6.44405 4.33398 6.75C4.30778 6.91565 4.30778 7.08435 4.33398 7.25C4.38244 7.55595 4.53117 7.79912 4.70215 8.01172C4.86618 8.21561 5.09294 8.44157 5.34863 8.69727L8.07617 11.4238L8.5 11.8486L9.34863 11L8.92383 10.5762L6.19727 7.84863C5.92268 7.57405 5.75151 7.40124 5.6377 7.25977C5.53096 7.12709 5.52187 7.07728 5.51953 7.0625C5.51297 7.02105 5.51297 6.97895 5.51953 6.9375C5.52187 6.92272 5.53096 6.87291 5.6377 6.74023C5.75152 6.59876 5.92268 6.42595 6.19727 6.15137L8.92383 3.42383L9.34863 3L8.5 2.15137Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_chevron_right_outline_14 */
+export const IconChevronRightOutline14 = ({ size = 14, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M5.5 2.15137L5.92383 2.57617L8.65137 5.30273C8.90706 5.55843 9.13382 5.78438 9.29785 5.98828C9.46883 6.20088 9.61756 6.44405 9.66602 6.75C9.69222 6.91565 9.69222 7.08435 9.66602 7.25C9.61756 7.55595 9.46883 7.79912 9.29785 8.01172C9.13382 8.21561 8.90706 8.44157 8.65137 8.69727L5.92383 11.4238L5.5 11.8486L4.65137 11L5.07617 10.5762L7.80273 7.84863C8.07732 7.57405 8.24849 7.40124 8.3623 7.25977C8.46904 7.12709 8.47813 7.07728 8.48047 7.0625C8.48703 7.02105 8.48703 6.97895 8.48047 6.9375C8.47813 6.92272 8.46904 6.87291 8.3623 6.74023C8.24848 6.59876 8.07732 6.42595 7.80273 6.15137L5.07617 3.42383L4.65137 3L5.5 2.15137Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_chevron_up_outline_14 */
+export const IconChevronUpOutline14 = ({ size = 14, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M2.15137 8.5L2.57617 8.07617L5.30273 5.34863C5.55843 5.09294 5.78438 4.86618 5.98828 4.70215C6.20088 4.53117 6.44405 4.38244 6.75 4.33398C6.91565 4.30778 7.08435 4.30778 7.25 4.33398C7.55595 4.38244 7.79912 4.53117 8.01172 4.70215C8.21561 4.86618 8.44157 5.09294 8.69727 5.34863L11.4238 8.07617L11.8486 8.5L11 9.34863L10.5762 8.92383L7.84863 6.19727C7.57405 5.92269 7.40124 5.75152 7.25977 5.6377C7.12709 5.53096 7.07728 5.52187 7.0625 5.51953C7.02105 5.51297 6.97895 5.51297 6.9375 5.51953C6.92272 5.52187 6.87291 5.53096 6.74023 5.6377C6.59876 5.75152 6.42595 5.92268 6.15137 6.19727L3.42383 8.92383L3 9.34863L2.15137 8.5Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_close_outline_16 */
+export const IconCloseOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M14.1168 13.197L13.197 14.1167L1.8833 2.80303L2.80309 1.88324L14.1168 13.197Z"
+      fill="currentColor"
+    />
+    <path
+      d="M13.197 1.88326L14.1168 2.80305L2.80309 14.1168L1.8833 13.197L13.197 1.88326Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_close_fill_14 */
+export const IconCloseFill14 = ({ size = 14, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M10.6074 4.40278L8.00975 6.99973L10.6074 9.59739L9.59736 10.6074L6.9997 8.00978L4.40274 10.6074L3.3927 9.59739L5.98966 6.99973L3.3927 4.40278L4.40274 3.39273L6.9997 5.98969L9.59736 3.39273L10.6074 4.40278Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_copy_outline_16 */
+export const IconCopyOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M6.14929 4.02032C7.11197 4.02032 7.87983 4.02016 8.49597 4.07598C9.12128 4.13269 9.65792 4.25188 10.1415 4.53106C10.7202 4.8653 11.2008 5.3459 11.535 5.92462C11.8142 6.40818 11.9334 6.94481 11.9901 7.57012C12.0459 8.18625 12.0458 8.95419 12.0458 9.9168C12.0458 10.8795 12.0459 11.6473 11.9901 12.2635C11.9334 12.8888 11.8142 13.4254 11.535 13.909C11.2008 14.4877 10.7202 14.9683 10.1415 15.3025C9.65792 15.5817 9.12128 15.7009 8.49597 15.7576C7.87984 15.8134 7.11196 15.8133 6.14929 15.8133C5.18667 15.8133 4.41874 15.8134 3.80261 15.7576C3.1773 15.7009 2.64067 15.5817 2.1571 15.3025C1.5784 14.9683 1.09778 14.4877 0.76355 13.909C0.484366 13.4254 0.365184 12.8888 0.308472 12.2635C0.252649 11.6473 0.252808 10.8795 0.252808 9.9168C0.252808 8.95418 0.252664 8.18625 0.308472 7.57012C0.365184 6.94481 0.484366 6.40818 0.76355 5.92462C1.09777 5.34589 1.57839 4.86529 2.1571 4.53106C2.64067 4.25188 3.1773 4.13269 3.80261 4.07598C4.41874 4.02017 5.18666 4.02032 6.14929 4.02032ZM6.14929 5.37774C5.16181 5.37774 4.46634 5.37761 3.92566 5.42657C3.39434 5.47472 3.07859 5.56574 2.83582 5.70587C2.4632 5.92106 2.15354 6.2307 1.93835 6.60333C1.79823 6.8461 1.70721 7.16185 1.65906 7.69317C1.6101 8.23385 1.61023 8.92933 1.61023 9.9168C1.61023 10.9043 1.61009 11.5998 1.65906 12.1404C1.70721 12.6717 1.79823 12.9875 1.93835 13.2303C2.15356 13.6029 2.46321 13.9126 2.83582 14.1277C3.07859 14.2679 3.39434 14.3589 3.92566 14.407C4.46634 14.456 5.16182 14.4559 6.14929 14.4559C7.13682 14.4559 7.83224 14.456 8.37292 14.407C8.90425 14.3589 9.21999 14.2679 9.46277 14.1277C9.83535 13.9126 10.145 13.6029 10.3602 13.2303C10.5004 12.9875 10.5914 12.6717 10.6395 12.1404C10.6885 11.5998 10.6884 10.9043 10.6884 9.9168C10.6884 8.92934 10.6885 8.23384 10.6395 7.69317C10.5914 7.16185 10.5004 6.8461 10.3602 6.60333C10.1451 6.23071 9.83536 5.92107 9.46277 5.70587C9.21999 5.56574 8.90424 5.47472 8.37292 5.42657C7.83224 5.3776 7.13682 5.37774 6.14929 5.37774ZM9.80164 0.367975C10.7638 0.367975 11.5314 0.36788 12.1473 0.423639C12.7726 0.480307 13.3093 0.598759 13.7928 0.877741C14.3717 1.21192 14.8521 1.69355 15.1864 2.27227C15.4655 2.75574 15.5857 3.29164 15.6425 3.9168C15.6983 4.53301 15.6971 5.3016 15.6971 6.26446V7.82989C15.6971 8.29264 15.6989 8.58993 15.6649 8.84844C15.4668 10.3525 14.401 11.5738 12.9833 11.9988V10.5467C13.6973 10.1903 14.2105 9.49662 14.3192 8.67169C14.3387 8.52347 14.3407 8.3358 14.3407 7.82989V6.26446C14.3407 5.27706 14.3398 4.58149 14.2909 4.04083C14.2428 3.50968 14.1526 3.19372 14.0126 2.95098C13.7974 2.57849 13.4876 2.26869 13.1151 2.05352C12.8724 1.91347 12.5564 1.82237 12.0253 1.77423C11.4847 1.72528 10.7888 1.7254 9.80164 1.7254H7.71472C6.7562 1.72558 5.92665 2.27697 5.52332 3.07891H4.07019C4.54221 1.51132 5.9932 0.368186 7.71472 0.367975H9.80164Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_refresh_outline_16 */
+export const IconRefreshOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M7.92136 0.349152C10.3744 0.349234 12.5564 1.5052 13.9557 3.29894L15.1281 2.12759C15.3303 1.92546 15.6767 2.06943 15.6767 2.35538V5.53923C15.6766 5.71626 15.5329 5.85976 15.3559 5.86002H12.171C11.8854 5.8597 11.7426 5.51465 11.9443 5.31249L12.9641 4.29056C11.8237 2.74305 9.98908 1.74106 7.92136 1.74097C4.46436 1.74097 1.66233 4.543 1.66233 8C1.66233 11.457 4.46436 14.259 7.92136 14.259C11.3782 14.2589 14.1804 11.4569 14.1804 8H15.5722C15.5722 12.2251 12.1465 15.6507 7.92136 15.6508C3.69614 15.6508 0.270508 12.2252 0.270508 8C0.270508 3.77478 3.69614 0.349152 7.92136 0.349152Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_refresh_outline_14 */
+export const IconRefreshOutline14 = ({ size = 14, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M1.272 6.21348C1.70645 3.08888 4.59169 0.908064 7.71634 1.34239C8.95495 1.51469 10.0438 2.07331 10.8814 2.87755L11.9458 1.81407C12.1347 1.6255 12.4572 1.75911 12.4575 2.02598V5.08751C12.4574 5.25303 12.3233 5.38731 12.1577 5.38731H9.0972C8.82993 5.38731 8.69629 5.06361 8.88528 4.87462L10.0327 3.72618C9.3732 3.09994 8.52006 2.66569 7.5513 2.53087C5.08313 2.18779 2.80376 3.91044 2.46048 6.37852C2.11747 8.84665 3.84009 11.1261 6.30814 11.4693C8.77612 11.8121 11.0557 10.0896 11.399 7.62169L11.9937 7.70372L12.5874 7.78673C12.153 10.9112 9.26756 13.0919 6.1431 12.6578C3.01854 12.2234 0.837738 9.33809 1.272 6.21348Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_like_outline_16 */
+export const IconLikeOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M8.27868 0.811572C8.81991 0.142194 9.79022 0.0421835 10.4538 0.557601L10.5823 0.669306L10.6066 0.693544L10.6097 0.695652L10.6392 0.725159C11.355 1.44679 11.6337 2.49468 11.3716 3.47669L11.3706 3.48091L11.3611 3.51674L11.3601 3.51885L10.889 5.22604C10.8796 5.25997 10.8707 5.29157 10.8627 5.32088C10.8934 5.32095 10.927 5.32194 10.9628 5.32194H11.9007C12.4264 5.32194 12.7831 5.319 13.0651 5.36725C14.8182 5.66719 15.9851 7.34568 15.6565 9.09357C15.6036 9.37487 15.477 9.7092 15.294 10.2022L14.3371 12.7798C14.1402 13.3104 13.9774 13.7518 13.8102 14.1024C13.6376 14.4645 13.4386 14.7793 13.1442 15.0424C12.9712 15.197 12.7802 15.3303 12.5751 15.4386C12.226 15.6231 11.8608 15.7 11.4612 15.7358C11.0743 15.7705 10.6035 15.7695 10.0375 15.7695H4.87377C4.08053 15.7695 3.42928 15.7702 2.90734 15.7137C2.37212 15.6557 1.88991 15.5311 1.46676 15.2237C1.22415 15.0474 1.01078 14.8339 0.834466 14.5914C0.527021 14.1682 0.401373 13.686 0.343384 13.1508C0.286822 12.6287 0.287531 11.9769 0.287531 11.1833V9.51405C0.287531 8.84778 0.281347 8.36714 0.399237 7.9565C0.671152 7.00935 1.41115 6.26832 2.35829 5.99638C2.76894 5.87849 3.24958 5.88573 3.91585 5.88573C4.11983 5.88573 4.14548 5.88319 4.16244 5.88046C4.23532 5.86863 4.30409 5.83663 4.35845 5.78667C4.3711 5.77504 4.38761 5.75604 4.51442 5.59488L8.25655 0.838972L8.2576 0.837918L8.27868 0.811572ZM1.69122 11.1833C1.69122 12.0082 1.69217 12.5711 1.73865 13.0001C1.78371 13.4157 1.86473 13.6221 1.96943 13.7662C2.0592 13.8898 2.16733 13.9989 2.29085 14.0887C2.43501 14.1934 2.64216 14.2744 3.05803 14.3195C3.45897 14.3629 3.97637 14.3656 4.7157 14.3659C4.30801 13.8053 4.06453 13.1171 4.06444 12.371V8.59406H5.46813V12.371C5.46838 13.4733 6.36166 14.3669 7.46407 14.3669H10.0375C10.6286 14.3669 11.0269 14.3663 11.3369 14.3385C11.6339 14.3118 11.7956 14.2638 11.9196 14.1983C12.0241 14.1431 12.1213 14.0747 12.2094 13.996C12.314 13.9025 12.4151 13.7678 12.5435 13.4986C12.6774 13.2176 12.8162 12.845 13.0219 12.2909L13.9788 9.71322C14.1848 9.15816 14.2531 8.96731 14.2781 8.83433C14.4618 7.85692 13.8093 6.91895 12.8291 6.75092C12.6957 6.7281 12.4928 6.72458 11.9007 6.72458H10.9628C10.7737 6.72458 10.5693 6.72657 10.4 6.70666C10.2211 6.68562 9.96702 6.63024 9.74771 6.43161C9.64454 6.33811 9.55957 6.2261 9.4969 6.10177C9.3639 5.83784 9.37799 5.57899 9.40521 5.40097C9.431 5.23261 9.48672 5.03616 9.53694 4.85404L10.008 3.14579L10.0175 3.11102C10.1488 2.61338 10.0078 2.08338 9.64654 1.71681L9.6086 1.67887L9.55064 1.64304C9.48795 1.62043 9.41425 1.63814 9.36938 1.69362L9.35779 1.70627L9.35884 1.70732L5.61672 6.46217C5.51822 6.58735 5.42237 6.7133 5.30689 6.81942C5.05075 7.05471 4.73126 7.20939 4.38796 7.26519C4.23315 7.29032 4.07513 7.28837 3.91585 7.28837C3.15356 7.28837 2.91916 7.2957 2.7461 7.34528C2.26364 7.48379 1.88564 7.86081 1.74708 8.34325C1.69738 8.51636 1.69122 8.7511 1.69122 9.51405V11.1833Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_like_fill_16 */
+export const IconLikeFill16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M14.0593 12.922L15.0976 10.1247C15.3087 9.5559 15.4143 9.27138 15.4566 9.04658C15.7349 7.56751 14.7472 6.14737 13.2637 5.89357C13.0382 5.85499 12.7348 5.85499 12.1281 5.85499H11.1099C10.6615 5.85499 10.4372 5.85499 10.3034 5.73376C10.2607 5.69508 10.2255 5.64885 10.1995 5.5974C10.1182 5.43613 10.1778 5.21997 10.297 4.78765L10.8081 2.93419L10.819 2.89456C11.0336 2.09024 10.8051 1.23244 10.2189 0.64139L10.1898 0.612405L10.1692 0.592068C9.77357 0.210076 9.13559 0.249344 8.78983 0.676966L8.77186 0.699678L4.71076 5.86083C4.52965 6.09101 4.38573 6.35138 4.38573 6.64427V12.7431C4.38573 14.3601 5.69654 15.6709 7.31351 15.6709L10.1068 15.6709C11.3628 15.6709 11.9908 15.6709 12.5043 15.3995C12.6723 15.3107 12.8289 15.2018 12.9706 15.0752C13.4037 14.6882 13.6222 14.0995 14.0593 12.922Z"
+      fill="currentColor"
+    />
+    <path
+      d="M2.91388 13.2113C2.91388 14.6907 4.08499 15.5536 4.08499 15.5536H2.65606C1.46328 15.5536 0.496338 14.5866 0.496338 13.3938V8.34439C0.496338 7.15161 1.46328 6.18467 2.65606 6.18467H2.91388V13.2113Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_dislike_outline_16 */
+export const IconDislikeOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M7.72451 15.1086C7.18929 15.7705 6.22975 15.8694 5.57357 15.3597L5.44643 15.2492L5.42247 15.2253L5.41934 15.2232L5.39016 15.194C4.68239 14.4804 4.40679 13.4441 4.66589 12.473L4.66693 12.4689L4.67631 12.4334L4.67735 12.4314L5.14318 10.7431C5.15243 10.7096 5.1613 10.6783 5.16923 10.6493C5.13878 10.6493 5.10558 10.6483 5.07023 10.6483H4.14274C3.62288 10.6483 3.27015 10.6512 2.9912 10.6035C1.25757 10.3069 0.103662 8.64702 0.42863 6.91854C0.480965 6.64037 0.606164 6.30975 0.787119 5.82223L1.73336 3.27321C1.92812 2.74852 2.08912 2.31209 2.25442 1.96535C2.42515 1.60724 2.62191 1.29594 2.91304 1.03578C3.08408 0.882951 3.273 0.751121 3.47579 0.643944C3.82102 0.461504 4.18214 0.38551 4.57731 0.350066C4.95993 0.315784 5.42553 0.316718 5.98521 0.316718H11.0916C11.876 0.316718 12.52 0.31607 13.0362 0.37195C13.5655 0.429293 14.0423 0.552534 14.4608 0.856536C14.7007 1.03085 14.9117 1.24193 15.086 1.48181C15.3901 1.90027 15.5143 2.37709 15.5717 2.90638C15.6276 3.42269 15.6269 4.06721 15.6269 4.85202V6.50274C15.6269 7.1616 15.633 7.6369 15.5164 8.04299C15.2475 8.97962 14.5158 9.71242 13.5791 9.98133C13.173 10.0979 12.6977 10.0908 12.0389 10.0908C11.8372 10.0908 11.8118 10.0933 11.795 10.096C11.723 10.1077 11.6549 10.1393 11.6012 10.1887C11.5887 10.2002 11.5724 10.219 11.447 10.3784L7.74639 15.0815L7.74535 15.0825L7.72451 15.1086ZM14.2388 4.85202C14.2388 4.03628 14.2379 3.47965 14.1919 3.05541C14.1473 2.64443 14.0672 2.4403 13.9637 2.29779C13.8749 2.17562 13.768 2.06769 13.6458 1.9789C13.5033 1.87532 13.2984 1.79523 12.8872 1.75067C12.4907 1.70773 11.979 1.70511 11.2479 1.70482C11.6511 2.25917 11.8918 2.93968 11.8919 3.67755V7.41251H10.5038V3.67755C10.5036 2.58745 9.62023 1.70378 8.53007 1.70378H5.98521C5.40065 1.70378 5.00679 1.70442 4.70028 1.73192C4.40651 1.7583 4.24662 1.80571 4.12399 1.87052C4.02069 1.92511 3.92452 1.99276 3.8374 2.07061C3.73401 2.16306 3.634 2.2962 3.50705 2.56249C3.37462 2.84027 3.23734 3.20873 3.03393 3.75675L2.08768 6.30578C1.88395 6.85467 1.81646 7.0434 1.79172 7.1749C1.61005 8.14146 2.25533 9.06902 3.22464 9.23517C3.35654 9.25774 3.55717 9.26123 4.14274 9.26123H5.07023C5.25717 9.26123 5.4593 9.25926 5.62672 9.27894C5.80364 9.29975 6.05492 9.35452 6.27179 9.55094C6.37381 9.6434 6.45784 9.75417 6.51982 9.87712C6.65133 10.1381 6.6374 10.3941 6.61048 10.5701C6.58498 10.7366 6.52988 10.9309 6.48022 11.111L6.01439 12.8003L6.00501 12.8347C5.87513 13.3268 6.01464 13.8509 6.37184 14.2134L6.40935 14.2509L6.46667 14.2863C6.52866 14.3087 6.60155 14.2912 6.64591 14.2363L6.65738 14.2238L6.65633 14.2228L10.3569 9.52072C10.4543 9.39693 10.5491 9.27238 10.6633 9.16744C10.9166 8.93476 11.2325 8.7818 11.572 8.72662C11.7251 8.70177 11.8814 8.70369 12.0389 8.70369C12.7927 8.70369 13.0245 8.69645 13.1956 8.64742C13.6727 8.51045 14.0465 8.13761 14.1836 7.66053C14.2327 7.48935 14.2388 7.25721 14.2388 6.50274V4.85202Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_dislike_fill_16 */
+export const IconDislikeFill16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M1.92838 3.06811L0.88799 5.87104C0.676449 6.44097 0.570628 6.72606 0.52825 6.95131C0.249414 8.43336 1.2391 9.85637 2.72555 10.1107C2.95149 10.1493 3.25549 10.1493 3.86348 10.1493H4.88371C5.33306 10.1493 5.55774 10.1493 5.69187 10.2708C5.73467 10.3096 5.76994 10.3559 5.79593 10.4074C5.87738 10.569 5.81766 10.7856 5.69821 11.2188L5.18609 13.076L5.17522 13.1157C4.9602 13.9217 5.1891 14.7812 5.7765 15.3735L5.80568 15.4025L5.82635 15.4229C6.22273 15.8056 6.862 15.7663 7.20846 15.3378L7.22647 15.315L11.2958 10.1435C11.4772 9.91284 11.6214 9.65195 11.6214 9.35847V3.24734C11.6214 1.62711 10.308 0.313655 8.68776 0.313655L5.88886 0.313654C4.63032 0.313654 4.00105 0.313654 3.48649 0.585577C3.31815 0.674536 3.16127 0.783647 3.01929 0.910507C2.58531 1.29828 2.36633 1.88824 1.92838 3.06811Z"
+      fill="currentColor"
+    />
+    <path
+      d="M13.0963 2.77815C13.0963 1.29585 11.9228 0.431205 11.9228 0.431205H13.3546C14.5498 0.431205 15.5187 1.4001 15.5187 2.59529V7.65491C15.5187 8.8501 14.5498 9.81899 13.3546 9.81899H13.0963V2.77815Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_share_outline_16 */
+export const IconShareOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M7.95889 1.52285C7.95888 0.826234 8.76055 0.467983 9.27669 0.875208L9.37524 0.967191L15.1317 7.18358C15.5582 7.64419 15.5582 8.35614 15.1317 8.81676L9.37524 15.0331C8.87034 15.578 7.95888 15.2205 7.95889 14.4775V10.8207C7.10614 10.8432 6.31361 10.9316 5.45468 11.2515C4.39484 11.6463 3.18248 12.413 1.64676 13.9425C1.4533 14.135 1.18329 14.1696 0.969086 14.0908C0.74748 14.0091 0.547307 13.7879 0.54859 13.4844L0.55516 13.1315C0.618924 11.3494 1.11153 9.29838 2.27656 7.63787C3.45289 5.96147 5.29554 4.71635 7.95889 4.54797V1.52285ZM9.20911 5.13366C9.20899 5.50567 8.9031 5.77687 8.56523 5.77755C5.99383 5.78282 4.33736 6.8762 3.29964 8.35496C2.54519 9.43014 2.10739 10.7283 1.9152 11.9939C3.04749 11.0323 4.0569 10.4385 5.01917 10.0801C6.29638 9.60449 7.4406 9.56343 8.56429 9.56295C8.9178 9.5628 9.20894 9.84909 9.20911 10.2068L9.20817 13.3737L14.1837 8.00017L9.20817 2.62571L9.20911 5.13366Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_edit_outline_16 */
+export const IconEditOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M9.94076 1.34942C10.7047 0.90231 11.6503 0.902415 12.4143 1.34942C12.7061 1.52015 12.9688 1.79118 13.3104 2.13284C13.6521 2.47448 13.9231 2.73721 14.0939 3.02894C14.5408 3.79294 14.5409 4.73856 14.0939 5.50251C13.9231 5.79415 13.652 6.05704 13.3104 6.39861L6.65932 13.0497C6.28068 13.4284 6.00695 13.7108 5.66543 13.9097C5.32391 14.1085 4.94315 14.2074 4.42705 14.3498L3.24394 14.6761C2.77527 14.8054 2.34538 14.9262 2.00131 14.9684C1.65196 15.0112 1.17964 15.0013 0.810764 14.6325C0.441921 14.2637 0.432107 13.7913 0.47486 13.442C0.517035 13.0979 0.6379 12.668 0.767181 12.1993L1.09352 11.0162C1.23588 10.5001 1.33481 10.1193 1.5336 9.77784C1.7325 9.43632 2.0149 9.1626 2.39355 8.78395L9.04466 2.13284C9.38625 1.79126 9.64911 1.52016 9.94076 1.34942ZM15.5427 14.8398H7.55223L8.96707 13.425H15.5427V14.8398ZM3.39382 9.78422C2.965 10.213 2.84244 10.3436 2.75709 10.49C2.67183 10.6366 2.61862 10.8079 2.45733 11.3925L2.13099 12.5756C2.00183 13.0439 1.92194 13.3419 1.88863 13.5536C2.10041 13.5204 2.39872 13.4416 2.86764 13.3123L4.05075 12.9859C4.63544 12.8246 4.80669 12.7715 4.95323 12.6862C5.09968 12.6008 5.23022 12.4783 5.65905 12.0494L10.721 6.98644L8.45577 4.72121L3.39382 9.78422ZM11.7 2.57079C11.3774 2.38198 10.9777 2.38198 10.6551 2.57079C10.5602 2.62647 10.4487 2.72931 10.0449 3.13311L9.45604 3.72094L11.7213 5.98617L12.3102 5.39833C12.7139 4.99457 12.8168 4.88307 12.8725 4.78818C13.0613 4.46561 13.0612 4.06585 12.8725 3.74326C12.8169 3.64827 12.7146 3.53752 12.3102 3.13311C11.9057 2.72863 11.795 2.6264 11.7 2.57079Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_think_outline_14 */
+export const IconThinkOutline14 = ({ size = 14, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M7.06431 5.93342C7.68763 5.93342 8.19307 6.43904 8.19322 7.06233C8.19322 7.68573 7.68772 8.19123 7.06431 8.19123C6.44099 8.19113 5.9354 7.68567 5.9354 7.06233C5.93555 6.43911 6.44108 5.93353 7.06431 5.93342Z"
+      fill="currentColor"
+    />
+    <path
+      fillRule="evenodd"
+      clipRule="evenodd"
+      d="M8.6815 0.963693C10.1169 0.447019 11.6266 0.374829 12.5633 1.31135C13.5 2.24805 13.4277 3.75776 12.911 5.19319C12.7126 5.74431 12.4386 6.31796 12.0965 6.89729C12.4969 7.54638 12.8141 8.19018 13.036 8.80647C13.5527 10.2419 13.6251 11.7516 12.6883 12.6883C11.7516 13.625 10.242 13.5527 8.8065 13.036C8.19022 12.8141 7.54641 12.4969 6.89732 12.0965C6.31797 12.4386 5.74435 12.7125 5.19322 12.911C3.75777 13.4276 2.2481 13.5 1.31138 12.5633C0.374859 11.6266 0.447049 10.1168 0.963724 8.68147C1.17185 8.10338 1.46321 7.50063 1.82896 6.8924C1.52182 6.35711 1.27235 5.82825 1.08872 5.31819C0.572068 3.88278 0.499714 2.37306 1.43638 1.43635C2.37308 0.499655 3.8828 0.572044 5.31822 1.08869C5.82828 1.27232 6.35715 1.5218 6.89243 1.82893C7.50066 1.46318 8.10341 1.17181 8.6815 0.963693ZM11.3573 8.01154C10.9083 8.62253 10.3901 9.22873 9.80943 9.8094C9.22877 10.3901 8.62255 10.9083 8.01158 11.3572C8.4257 11.5841 8.8287 11.7688 9.21275 11.9071C10.5456 12.3868 11.4246 12.2547 11.8397 11.8397C12.2548 11.4246 12.3869 10.5456 11.9071 9.21272C11.7688 8.82866 11.5841 8.42568 11.3573 8.01154ZM2.56529 8.02912C2.37344 8.39322 2.21495 8.74796 2.09263 9.08772C1.61291 10.4204 1.74512 11.2995 2.16001 11.7147C2.57505 12.1297 3.45415 12.2618 4.78697 11.7821C5.11057 11.6656 5.44786 11.5164 5.7938 11.3367C5.249 10.9223 4.70922 10.4533 4.19029 9.9344C3.57578 9.31987 3.03169 8.67633 2.56529 8.02912ZM6.90708 3.2469C6.24065 3.70479 5.5646 4.26321 4.91392 4.91389C4.26325 5.56456 3.70482 6.24063 3.24693 6.90705C3.72674 7.63325 4.32777 8.37459 5.03892 9.08576C5.64943 9.69627 6.28183 10.2265 6.90806 10.6678C7.59368 10.2025 8.2908 9.63076 8.96079 8.96076C9.6308 8.29075 10.2025 7.59366 10.6678 6.90803C10.2265 6.2818 9.69631 5.6494 9.08579 5.03889C8.37462 4.32773 7.63328 3.72672 6.90708 3.2469ZM11.7147 2.15998C11.2996 1.74509 10.4204 1.61288 9.08775 2.0926C8.74835 2.21479 8.39382 2.37271 8.03013 2.56428C8.67728 3.03065 9.31995 3.5758 9.93443 4.19026C10.4534 4.7092 10.9223 5.24896 11.3368 5.79377C11.5164 5.44785 11.6656 5.11052 11.7821 4.78694C12.2618 3.45416 12.1297 2.57502 11.7147 2.15998ZM4.91197 2.2176C3.57922 1.73788 2.70004 1.86995 2.28501 2.28498C1.87001 2.70003 1.73791 3.5792 2.21763 4.91194C2.31709 5.18822 2.44112 5.47427 2.58677 5.7674C3.01931 5.1887 3.51474 4.6158 4.06529 4.06526C4.61584 3.5147 5.18872 3.01928 5.76743 2.58674C5.47431 2.4411 5.18824 2.31706 4.91197 2.2176Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_think_outline_16 */
+export const IconThinkOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M8.00192 6.64454C8.75026 6.64454 9.35732 7.25169 9.35739 8.00001C9.35739 8.74838 8.7503 9.35548 8.00192 9.35548C7.25367 9.35533 6.64743 8.74829 6.64743 8.00001C6.6475 7.25178 7.25371 6.64468 8.00192 6.64454Z"
+      fill="currentColor"
+    />
+    <path
+      fillRule="evenodd"
+      clipRule="evenodd"
+      d="M9.97165 1.29981C11.5853 0.718916 13.271 0.642197 14.3144 1.68555C15.3577 2.72902 15.2811 4.41466 14.7002 6.02833C14.4707 6.66561 14.1504 7.32937 13.75 8.00001C14.1504 8.67062 14.4707 9.33444 14.7002 9.97169C15.2811 11.5854 15.3578 13.271 14.3144 14.3145C13.271 15.3579 11.5854 15.2811 9.97165 14.7002C9.3344 14.4708 8.67059 14.1505 7.99997 13.75C7.32933 14.1505 6.66558 14.4708 6.02829 14.7002C4.41461 15.2811 2.72899 15.3578 1.68552 14.3145C0.642155 13.271 0.71887 11.5854 1.29977 9.97169C1.52915 9.33454 1.84865 8.67049 2.24899 8.00001C1.84866 7.32953 1.52915 6.66544 1.29977 6.02833C0.718852 4.41459 0.64207 2.729 1.68552 1.68555C2.72897 0.642112 4.41456 0.718887 6.02829 1.29981C6.66541 1.52918 7.32949 1.8487 7.99997 2.24903C8.67045 1.84869 9.33451 1.52919 9.97165 1.29981ZM12.9404 9.2129C12.4391 9.893 11.8616 10.5681 11.2148 11.2149C10.568 11.8616 9.89296 12.4391 9.21286 12.9404C9.62532 13.1579 10.0271 13.338 10.4121 13.4766C11.9146 14.0174 12.9172 13.8738 13.3955 13.3955C13.8737 12.9173 14.0174 11.9146 13.4765 10.4121C13.3379 10.0271 13.1578 9.62535 12.9404 9.2129ZM3.05856 9.2129C2.84121 9.62523 2.66197 10.0272 2.52341 10.4121C1.98252 11.9146 2.12627 12.9172 2.60446 13.3955C3.08278 13.8737 4.08544 14.0174 5.58786 13.4766C5.97264 13.338 6.37389 13.1577 6.7861 12.9404C6.10624 12.4393 5.43168 11.8614 4.78513 11.2149C4.13823 10.5679 3.55992 9.89313 3.05856 9.2129ZM7.99899 3.792C7.23179 4.31419 6.45306 4.95512 5.70407 5.70411C4.95509 6.45309 4.31415 7.23184 3.79196 7.99903C4.3143 8.76666 4.95471 9.54653 5.70407 10.2959C6.45309 11.0449 7.23271 11.6848 7.99997 12.207C8.76725 11.6848 9.54683 11.0449 10.2959 10.2959C11.0449 9.54686 11.6848 8.76729 12.207 8.00001C11.6848 7.23275 11.0449 6.45312 10.2959 5.70411C9.5465 4.95475 8.76662 4.31434 7.99899 3.792ZM5.58786 2.52344C4.08533 1.98255 3.08272 2.12625 2.60446 2.6045C2.12621 3.08275 1.98252 4.08536 2.52341 5.5879C2.66189 5.97253 2.8414 6.37409 3.05856 6.78614C3.55983 6.10611 4.1384 5.43189 4.78513 4.78516C5.43186 4.13843 6.10606 3.55987 6.7861 3.0586C6.37405 2.84144 5.97249 2.66192 5.58786 2.52344ZM13.3955 2.6045C12.9172 2.12631 11.9146 1.98257 10.4121 2.52344C10.0272 2.66201 9.62519 2.84125 9.21286 3.0586C9.8931 3.55996 10.5679 4.13827 11.2148 4.78516C11.8614 5.43172 12.4392 6.10627 12.9404 6.78614C13.1577 6.37393 13.338 5.97267 13.4765 5.5879C14.0174 4.08549 13.8736 3.08281 13.3955 2.6045Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_browse_outline_16 */
+export const IconBrowseOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path d="M11.2426 4.80473V6.10551H4.75819V4.80473H11.2426Z" fill="currentColor" />
+    <path d="M9.40858 7.84478V9.14557H4.75819V7.84478H9.40858Z" fill="currentColor" />
+    <path
+      d="M9.23438 0.546389C10.1941 0.546389 10.9683 0.544914 11.5859 0.611819C12.2161 0.680096 12.7634 0.825745 13.2393 1.17139C13.5172 1.3733 13.7619 1.61812 13.9639 1.896C14.3096 2.37183 14.4551 2.91922 14.5234 3.54932C14.5903 4.16686 14.5889 4.94133 14.5889 5.90088V10.0981C14.5889 11.0576 14.5903 11.8321 14.5234 12.4497C14.4552 13.0798 14.3094 13.6272 13.9639 14.103C13.7619 14.381 13.5172 14.6257 13.2393 14.8276C12.7633 15.1734 12.2163 15.3189 11.5859 15.3872C10.9683 15.4541 10.1942 15.4536 9.23438 15.4536H6.76563C5.80591 15.4536 5.03168 15.4541 4.41407 15.3872C3.78385 15.3189 3.23665 15.1734 2.76074 14.8276C2.48291 14.6257 2.23802 14.3809 2.03614 14.103C1.69066 13.6272 1.54483 13.0798 1.47657 12.4497C1.40973 11.8321 1.41114 11.0576 1.41114 10.0981V5.90088C1.41113 4.94132 1.40966 4.16686 1.47657 3.54932C1.54488 2.91921 1.69042 2.37184 2.03614 1.896C2.2381 1.61807 2.4828 1.37333 2.76074 1.17139C3.23665 0.825682 3.78386 0.680109 4.41407 0.611819C5.03168 0.544905 5.80591 0.546389 6.76563 0.546389H9.23438ZM6.76563 1.896C5.77586 1.896 5.0876 1.89738 4.55957 1.95459C4.0443 2.01043 3.76214 2.11349 3.55469 2.26416C3.39135 2.38284 3.24761 2.52662 3.12891 2.68994C2.97821 2.89736 2.8752 3.17967 2.81934 3.69483C2.76214 4.22279 2.76075 4.91131 2.76074 5.90088V10.0981C2.76074 11.0876 2.76221 11.7762 2.81934 12.3042C2.87516 12.8194 2.97829 13.1026 3.12891 13.3101C3.24754 13.4733 3.39147 13.6172 3.55469 13.7358C3.76213 13.8865 4.04438 13.9896 4.55957 14.0454C5.0876 14.1026 5.77586 14.103 6.76563 14.103H9.23438C10.2242 14.103 10.9124 14.1026 11.4404 14.0454C11.9556 13.9896 12.2379 13.8865 12.4453 13.7358C12.6086 13.6172 12.7525 13.4733 12.8711 13.3101C13.0217 13.1026 13.1248 12.8195 13.1807 12.3042C13.2378 11.7762 13.2393 11.0876 13.2393 10.0981V5.90088C13.2393 4.91131 13.2379 4.22279 13.1807 3.69483C13.1248 3.17969 13.0218 2.89736 12.8711 2.68994C12.7524 2.52667 12.6086 2.38281 12.4453 2.26416C12.2379 2.11355 11.9556 2.01041 11.4404 1.95459C10.9124 1.8974 10.2241 1.896 9.23438 1.896H6.76563Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_link_outline_14 */
+export const IconLinkOutline14 = ({ size = 14, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M8.19727 5.86969C9.2092 6.90067 9.20969 8.55271 8.19727 9.58338L6.88871 10.8919C5.85801 11.9039 4.20584 11.9037 3.17502 10.8919L3.10873 10.8243C2.09622 9.7934 2.09626 8.14148 3.10873 7.11058L4.36757 5.85174C4.28261 6.33758 4.30355 6.84354 4.44077 7.33362L3.89249 7.88053C3.30043 8.48348 3.30108 9.4507 3.89318 10.0536L3.94566 10.1061C4.54861 10.698 5.51521 10.6981 6.11808 10.1061L7.41283 8.81275C8.00484 8.21002 8.00504 7.24267 7.41352 6.63964L7.35966 6.58716C7.21975 6.44976 7.05995 6.34434 6.89009 6.27089L7.70009 5.4609C7.85176 5.55768 7.99607 5.67091 8.1296 5.80202L8.19727 5.86969Z"
+      fill="currentColor"
+    />
+    <path
+      d="M5.80913 8.12648C4.79584 7.09547 4.79591 5.44245 5.80913 4.41141C5.81733 4.40304 5.82707 4.39209 5.8409 4.37826L7.07833 3.14082C7.09224 3.12693 7.10311 3.11729 7.11148 3.10906C8.14253 2.09591 9.79557 2.09579 10.8266 3.10906L10.8908 3.17328C11.9041 4.20425 11.9039 5.85727 10.8908 6.88835L9.63193 8.14581C9.70566 7.66581 9.67564 7.16895 9.53456 6.68948L10.1063 6.11772C10.6989 5.51458 10.6992 4.54691 10.1063 3.94391L10.0552 3.8942C9.45215 3.30157 8.48446 3.30151 7.88142 3.8942L6.59358 5.18204C6.00081 5.78507 6.00092 6.75274 6.59358 7.35584L6.6433 7.40694C6.77998 7.54132 6.93555 7.64528 7.10112 7.71837L6.29251 8.52699C6.14446 8.43127 6.00395 8.31906 5.87335 8.1907L5.80913 8.12648Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_link_outline_16 */
+export const IconLinkOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M9.94133 6.50173C11.3218 7.99603 11.3218 10.3011 9.94128 11.7954C9.88691 11.8542 9.82125 11.9196 9.72099 12.0198L7.75707 13.9838C7.65709 14.0838 7.592 14.1491 7.53334 14.2034C6.03906 15.5843 3.7327 15.5854 2.23827 14.2048C2.17933 14.1503 2.11374 14.0844 2.01315 13.9838C1.91318 13.8839 1.84922 13.8188 1.79495 13.7601C0.413857 12.2657 0.413909 9.95948 1.795 8.46503C1.84923 8.4064 1.91335 8.34115 2.01321 8.24129L3.79275 6.46313C3.71814 7.08101 3.75236 7.71445 3.90115 8.33518L3.00344 9.23151C2.89398 9.34097 2.8535 9.38307 2.82251 9.41658C1.93771 10.3744 1.93704 11.8514 2.82179 12.8092C2.85279 12.8427 2.89383 12.884 3.0034 12.9936C3.11272 13.1029 3.15429 13.1442 3.18777 13.1752C4.14561 14.0603 5.62381 14.0608 6.58178 13.1758C6.61532 13.1448 6.65722 13.1032 6.76685 12.9935L8.73077 11.0296C8.83999 10.9204 8.88142 10.8787 8.91238 10.8452C9.79744 9.88728 9.7969 8.40911 8.91173 7.45124C8.88074 7.41775 8.83944 7.3762 8.73011 7.26687C8.62082 7.15757 8.58061 7.11623 8.54712 7.08526C8.37347 6.92477 8.18243 6.79361 7.98088 6.69165L9.00289 5.66964C9.17506 5.78373 9.34035 5.91265 9.49663 6.05703C9.55538 6.11135 9.62026 6.17652 9.72036 6.27662C9.82094 6.3772 9.88686 6.4428 9.94133 6.50173Z"
+      fill="currentColor"
+    />
+    <path
+      d="M6.06816 9.49196C4.68626 7.99724 4.68667 5.68942 6.06885 4.19487C6.12268 4.13671 6.18789 4.07306 6.28706 3.9739L8.24541 2.01416C8.34478 1.91479 8.41018 1.85055 8.46845 1.79665C9.96301 0.414902 12.2689 0.414922 13.7635 1.79665C13.8217 1.85051 13.8866 1.91559 13.9858 2.01486C14.0849 2.11394 14.1502 2.17769 14.204 2.23583C15.5861 3.7304 15.5866 6.03823 14.2047 7.53291C14.1508 7.59125 14.0854 7.65638 13.9858 7.75595L12.1994 9.54098C12.2614 8.92982 12.2185 8.30587 12.0634 7.69657L12.9956 6.76573C13.1044 6.65692 13.1458 6.61529 13.1765 6.58205C14.0621 5.62404 14.0621 4.1454 13.1765 3.18738C13.1458 3.15419 13.104 3.1135 12.9956 3.00508C12.8877 2.89716 12.8471 2.85551 12.814 2.82485C11.8559 1.9389 10.376 1.93886 9.41794 2.82485C9.38479 2.85554 9.34381 2.89622 9.23564 3.00439L7.27728 4.96413C7.16875 5.07265 7.12708 5.11322 7.09636 5.14643C6.21074 6.10441 6.21153 7.58236 7.09705 8.5404C7.12775 8.57357 7.16826 8.61575 7.27659 8.72408C7.38456 8.83205 7.42647 8.87227 7.45958 8.90293C7.62849 9.0591 7.81309 9.1881 8.00856 9.28894L6.98795 10.3095C6.82111 10.1978 6.66052 10.0715 6.50872 9.93114C6.45057 9.87733 6.38547 9.81341 6.28637 9.71431C6.1871 9.61504 6.12202 9.55018 6.06816 9.49196Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_right_up_outline_14 */
+export const IconRightUpOutline14 = ({ size = 8, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 8 14" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M6.54199 8.62824C6.54199 8.44193 6.54146 8.28829 6.53906 8.15851L1.11719 13.5814L0.728516 13.1927L0.339844 12.803L5.76172 7.38019C5.63201 7.3778 5.47812 7.37824 5.29199 7.37824H1.43555V6.27863H5.29199C5.65471 6.27863 5.97167 6.27814 6.22852 6.30597C6.49541 6.33493 6.76232 6.3998 7.00293 6.57452C7.13452 6.67013 7.25108 6.78571 7.34668 6.9173C7.52157 7.15808 7.5863 7.4256 7.61523 7.69269C7.64305 7.94948 7.64258 8.26562 7.64258 8.62824V12.4857H6.54199V8.62824Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_right_up_outline_16 */
+export const IconRightUpOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M13.588429 5.147807C13.588429 4.739638 13.587271 4.403003 13.582013 4.118684L1.703098 15.99968L0.85155 15.148178L0 14.294485L11.878915 2.413442C11.594721 2.408199 11.257569 2.409154 10.849776 2.409154H2.400594V0.000001H10.849776C11.644471 0.000001 12.338899 -0.001059 12.901622 0.059909C13.486363 0.123352 14.071136 0.265493 14.598303 0.648292C14.886598 0.857751 15.141981 1.110984 15.351433 1.399281C15.734578 1.926807 15.876362 2.512925 15.939743 3.098105C16.000775 3.660718 15.99968 4.353347 15.99968 5.147807V13.599133H13.588429V5.147807Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_enhance_outline_16 */
+export const IconEnhanceOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path d="M14.9943 1.92389V3.32428H1.00598V1.92389H14.9943Z" fill="currentColor" />
+    <path d="M14.9943 5.50784V6.90823H1.00598V5.50784H14.9943Z" fill="currentColor" />
+    <path d="M14.9943 9.09177V10.4922H1.00598V9.09177H14.9943Z" fill="currentColor" />
+    <path d="M8.93274 12.6757V14.0761H1.00598V12.6757H8.93274Z" fill="currentColor" />
+  </svg>
+)
+
+/** ic_ds_trash_outline_16 */
+export const IconTrashOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M14.4782 4.84067L14.2138 10.1152C14.1102 12.1872 14.067 13.0115 13.3866 13.9607C13.1044 14.3546 12.7498 14.6912 12.3424 14.9535C11.8239 15.2872 11.2415 15.4316 10.5585 15.4998C9.88727 15.5668 9.04946 15.5656 7.99998 15.5656C6.95051 15.5656 6.1127 15.5668 5.44142 15.4998C4.75851 15.4316 4.17602 15.2872 3.65753 14.9535C3.25012 14.6912 2.89559 14.3546 2.61332 13.9607C1.93296 13.0115 1.88979 12.1872 1.78619 10.1152L1.52179 4.84067L2.89006 4.77277L3.15343 10.0463C3.26221 12.2218 3.32452 12.6015 3.72646 13.1624C3.90825 13.4161 4.13686 13.6334 4.39927 13.8023C4.66204 13.9714 5.00263 14.0792 5.57825 14.1367C6.16562 14.1953 6.92298 14.1963 7.99998 14.1963C9.07699 14.1963 9.83434 14.1953 10.4217 14.1367C10.9973 14.0792 11.3379 13.9714 11.6007 13.8023C11.8631 13.6334 12.0917 13.4161 12.2735 13.1624C12.6755 12.6015 12.7378 12.2218 12.8465 10.0463L13.1099 4.77277L14.4782 4.84067ZM5.43011 6.22849H6.7994V11.3909H5.43011V6.22849ZM9.20056 6.22849H10.5699V11.3909H9.20056V6.22849ZM8.53597 0.434431C9.17976 0.434431 9.6522 0.426926 10.0966 0.571258C10.2357 0.616451 10.3717 0.672554 10.502 0.738948C10.9182 0.951107 11.2464 1.29099 11.7015 1.74612L12.4978 2.54136H15.3742V3.91169H0.625732V2.54136H3.50218L4.29845 1.74612C4.75358 1.29099 5.08174 0.951107 5.49801 0.738948C5.62831 0.672554 5.76425 0.616451 5.90334 0.571258C6.34776 0.426926 6.82021 0.434431 7.46399 0.434431H8.53597ZM7.46399 1.80476C6.73208 1.80476 6.51641 1.81187 6.32617 1.87369C6.25545 1.89667 6.18668 1.92533 6.12041 1.95907C5.96398 2.03878 5.82348 2.16253 5.44142 2.54136H10.5585C10.1765 2.16253 10.036 2.03878 9.87955 1.95907C9.81329 1.92533 9.74452 1.89667 9.6738 1.87369C9.48356 1.81187 9.26789 1.80476 8.53597 1.80476H7.46399Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_warning_outline_16 */
+export const IconWarningOutline16 = ({ size = 14, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M6.3002 3.32843L7.69986 3.32843L7.69986 7.79657H6.3002L6.3002 3.32843Z"
+      fill="currentColor"
+    />
+    <path d="M6.3002 9.01935H7.69986V10.6711H6.3002V9.01935Z" fill="currentColor" />
+    <path
+      d="M12.6328 6.99976C12.6328 3.88874 10.111 1.36694 7 1.36694C3.88899 1.36695 1.3672 3.88875 1.36719 6.99976C1.36719 10.1108 3.88899 12.6326 7 12.6326C10.111 12.6326 12.6328 10.1108 12.6328 6.99976ZM13.8582 6.99976C13.8582 10.7873 10.7876 13.8579 7 13.8579C3.21244 13.8579 0.141846 10.7873 0.141846 6.99976C0.141857 3.2122 3.21245 0.141612 7 0.141602C10.7876 0.141602 13.8581 3.21219 13.8582 6.99976Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_user_outline_16 */
+export const IconUserOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M11.0307 5.46369C11.0305 3.78995 9.6734 2.43357 7.99961 2.43357C6.32601 2.43379 4.96972 3.79009 4.96949 5.46369C4.96949 7.13748 6.32587 8.49455 7.99961 8.49477C9.67354 8.49477 11.0307 7.13762 11.0307 5.46369ZM12.3163 5.46369C12.3163 7.84777 10.3837 9.78042 7.99961 9.78042C5.61572 9.7802 3.68288 7.84763 3.68288 5.46369C3.6831 3.07993 5.61586 1.14718 7.99961 1.14695C10.3836 1.14695 12.3161 3.0798 12.3163 5.46369Z"
+      fill="currentColor"
+    />
+    <path
+      d="M8.00002 10.3316C11.7343 10.3316 14.1864 11.8997 15.0387 14.4445L14.4292 14.6483L13.8197 14.8531C13.1955 12.9893 11.3673 11.6182 8.00002 11.6182C4.63277 11.6182 2.80455 12.9893 2.18031 14.8531L1.5708 14.6483L0.961304 14.4445C1.81368 11.8997 4.26579 10.3316 8.00002 10.3316Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_send_outline_16 */
+export const IconSendOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M8.3125 0.981587C8.66767 1.0545 8.97902 1.20558 9.2627 1.43374C9.48724 1.61438 9.73029 1.85933 9.97949 2.10854L14.707 6.83608L13.293 8.25014L9 3.95717V15.0431H7V3.95717L2.70703 8.25014L1.29297 6.83608L6.02051 2.10854C6.26971 1.85933 6.51277 1.61438 6.7373 1.43374C6.97662 1.24126 7.28445 1.04542 7.6875 0.981587C7.8973 0.94841 8.1031 0.956564 8.3125 0.981587Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_stop_fill_16 */
+export const IconStopFill16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M2 4.88C2 3.68009 2 3.08013 2.30557 2.65954C2.40426 2.52371 2.52371 2.40426 2.65954 2.30557C3.08013 2 3.68009 2 4.88 2H11.12C12.3199 2 12.9199 2 13.3405 2.30557C13.4763 2.40426 13.5957 2.52371 13.6944 2.65954C14 3.08013 14 3.68009 14 4.88V11.12C14 12.3199 14 12.9199 13.6944 13.3405C13.5957 13.4763 13.4763 13.5957 13.3405 13.6944C12.9199 14 12.3199 14 11.12 14H4.88C3.68009 14 3.08013 14 2.65954 13.6944C2.52371 13.5957 2.40426 13.4763 2.30557 13.3405C2 12.9199 2 12.3199 2 11.12V4.88Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_paperclip_outline_16 */
+export const IconPaperclipOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M5.5498 9.75V5H6.9502V9.75C6.9502 10.3299 7.4201 10.7998 8 10.7998C8.5799 10.7998 9.0498 10.3299 9.0498 9.75V4.5C9.0498 2.9536 7.7964 1.7002 6.25 1.7002C4.7036 1.7002 3.4502 2.9536 3.4502 4.5V9.75C3.4502 12.2629 5.4871 14.2998 8 14.2998C10.5129 14.2998 12.5498 12.2629 12.5498 9.75V4H13.9502V9.75C13.9502 13.0361 11.2861 15.7002 8 15.7002C4.71391 15.7002 2.0498 13.0361 2.0498 9.75V4.5C2.04981 2.1804 3.9304 0.299806 6.25 0.299805C8.5696 0.299805 10.4502 2.1804 10.4502 4.5V9.75C10.4502 11.1031 9.3531 12.2002 8 12.2002C6.6469 12.2002 5.5498 11.1031 5.5498 9.75Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_loading_outline_16 */
+export const IconLoadingOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M2.871 13.1286C0.0387669 10.2962 0.0387669 5.70383 2.871 2.87141C5.70341 0.0390029 10.2957 0.0391154 13.1282 2.87141L12.1387 3.86094C9.85292 1.57538 6.1469 1.57596 3.86123 3.86163C1.57573 6.14732 1.57573 9.85269 3.86123 12.1384C6.1469 14.424 9.85292 14.4246 12.1387 12.1391L13.1282 13.1286C10.2957 15.9609 5.70341 15.961 2.871 13.1286Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_download_outline_16 */
+export const IconDownloadOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M15.3695 11.411L15.1234 12.8866C14.8869 14.3042 13.6603 15.3436 12.223 15.3436H3.77673C2.33958 15.3434 1.1128 14.3042 0.876343 12.8866L0.630249 11.411L2.05408 11.1747L2.29919 12.6493C2.41973 13.3713 3.04475 13.9001 3.77673 13.9003H12.223C12.9551 13.9002 13.58 13.3713 13.7006 12.6493L13.9457 11.1747L15.3695 11.411ZM8.72205 8.994C8.77717 8.93934 8.83792 8.88106 8.90271 8.81627L12.4828 5.23424L13.5043 6.25572L9.92224 9.8358C9.6395 10.1185 9.38763 10.3732 9.15857 10.5575C8.91892 10.7503 8.63953 10.9224 8.2865 10.9784C8.09711 11.0083 7.90363 11.0083 7.71423 10.9784C7.36106 10.9224 7.0809 10.7503 6.84119 10.5575C6.61215 10.3732 6.36022 10.1185 6.07751 9.8358L2.49646 6.25572L3.51697 5.23424L7.09705 8.81627C7.16219 8.88142 7.22331 8.94006 7.27869 8.99498V1.3065H8.72205V8.994Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_play_outline_16 */
+export const IconPlayOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M14.1446 8C14.1446 4.6062 11.3938 1.85539 8 1.85539C4.6062 1.85539 1.85539 4.6062 1.85539 8C1.85539 11.3938 4.6062 14.1446 8 14.1446C11.3938 14.1446 14.1446 11.3938 14.1446 8ZM15.511 8C15.511 12.148 12.148 15.511 8 15.511C3.85202 15.511 0.489014 12.148 0.489014 8C0.489014 3.85202 3.85202 0.489014 8 0.489014C12.148 0.489014 15.511 3.85202 15.511 8Z"
+      fill="currentColor"
+    />
+    <path
+      d="M10.5617 8.42578C10.852 8.21614 10.852 7.78386 10.5617 7.57422L7.25708 5.18751C6.90974 4.93666 6.42436 5.18484 6.42436 5.61329V10.3867C6.42436 10.8152 6.90974 11.0633 7.25708 10.8125L10.5617 8.42578Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_fullscreen_outline_16 */
+export const IconFullscreenOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M2.58875 12.3407L6.59167 8.33777L7.66296 9.40808L3.66003 13.411H7.99988V14.8065H3.05457C2.02633 14.8065 1.19324 13.9734 1.19324 12.9452V7.99988H2.58875V12.3407Z"
+      fill="currentColor"
+    />
+    <path
+      d="M12.9452 1.19324C13.9734 1.19324 14.8065 2.02633 14.8065 3.05457V7.99988H13.411V3.66003L9.40808 7.66296L8.33777 6.59167L12.3407 2.58875H7.99988V1.19324H12.9452Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_code_outline_16 */
+export const IconCodeOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      fillRule="evenodd"
+      clipRule="evenodd"
+      d="M12.3368 1.53569L11.931 4.43172H14.8086V5.79673H11.7404L11.1962 9.67859H14.2839V11.0436H11.0056L10.4994 14.6529L9.14873 14.4643L9.62731 11.0436H5.75876L5.25252 14.6529L3.90186 14.4643L4.38043 11.0436H1.69141V9.67859H4.57104L5.11417 5.79673H2.21609V4.43172H5.30581L5.73724 1.34713L7.08995 1.53569L6.68414 4.43172H10.5527L10.9841 1.34713L12.3368 1.53569ZM5.94937 9.67859H9.81791L10.361 5.79673H6.49353L5.94937 9.67859Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
+/** ic_ds_api_outline (figma extract) */
+export const IconApiOutline14 = ({ size = 14, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 14 14" fill="none">
+    <path transform="translate(0.6689 1.073)" d="M11.4818 5.57813C11.4818 4.45301 11.4807 3.66237 11.4075 3.05908C11.3359 2.46953 11.2024 2.13852 10.9939 1.89441C10.9247 1.81341 10.8493 1.73801 10.7683 1.66882C10.5242 1.46033 10.1932 1.32686 9.60364 1.25525C9.00034 1.18198 8.20974 1.18091 7.0846 1.18091L5.57813 1.18091C4.45301 1.18091 3.66238 1.18198 3.05908 1.25525C2.46953 1.32686 2.13852 1.46033 1.89441 1.66882C1.81341 1.73801 1.73801 1.81341 1.66882 1.89441C1.46033 2.13852 1.32686 2.46953 1.25525 3.05908C1.18198 3.66238 1.18091 4.45301 1.18091 5.57813L1.18091 6.2771C1.18091 7.40218 1.18197 8.19288 1.25525 8.79614C1.32687 9.38553 1.46036 9.71674 1.66882 9.96082C1.73797 10.0417 1.81347 10.1173 1.89441 10.1864C2.13851 10.3948 2.46965 10.5275 3.05908 10.5991C3.66238 10.6724 4.45298 10.6735 5.57813 10.6735L7.0846 10.6735C8.20977 10.6735 9.00033 10.6724 9.60364 10.5991C10.1931 10.5275 10.5242 10.3948 10.7683 10.1864C10.8493 10.1173 10.9247 10.0417 10.9939 9.96082C11.2024 9.71674 11.3358 9.38553 11.4075 8.79614C11.4808 8.19288 11.4818 7.40218 11.4818 6.2771L11.4818 5.57813ZM12.6627 6.2771C12.6627 7.37222 12.6637 8.247 12.5798 8.93799C12.4942 9.64284 12.3133 10.2359 11.8928 10.7282C11.7834 10.8562 11.6637 10.9751 11.5356 11.0845C11.0434 11.5049 10.4511 11.6867 9.74634 11.7723C9.05525 11.8563 8.17999 11.8552 7.0846 11.8552L5.57813 11.8552C4.48273 11.8552 3.60747 11.8563 2.91638 11.7723C2.21157 11.6867 1.61933 11.5049 1.12708 11.0845C0.99901 10.9751 0.879281 10.8562 0.769898 10.7282C0.349454 10.2359 0.168506 9.64284 0.0828864 8.93799C-0.00101964 8.247 4.88512e-07 7.37222 6.47206e-07 6.2771L6.47206e-07 5.57813C6.47206e-07 4.48273 -0.00106163 3.60747 0.0828864 2.91638C0.168502 2.21168 0.349594 1.61928 0.769898 1.12708C0.879302 0.998981 0.998981 0.879302 1.12708 0.769898C1.61928 0.349594 2.21168 0.168502 2.91638 0.0828864C3.60747 -0.00106163 4.48273 6.47206e-07 5.57813 6.47206e-07L7.0846 6.47206e-07C8.17999 6.47206e-07 9.05525 -0.00106163 9.74634 0.0828864C10.451 0.168505 11.0434 0.349587 11.5356 0.769898C11.6637 0.879302 11.7834 0.998981 11.8928 1.12708C12.3131 1.61928 12.4942 2.21169 12.5798 2.91638C12.6638 3.60747 12.6627 4.48273 12.6627 5.57813L12.6627 6.2771Z" fill="currentColor"/>
+    <path transform="translate(0.6689 1.073)" d="M6.02607 5.50955L6.44306 5.9274L3.84284 8.52762L3.425 8.11063L3.00715 7.69278L4.77253 5.9274L3.00715 4.16202L3.84284 3.32633L6.02607 5.50955Z" fill="currentColor"/>
+    <path transform="translate(0.6689 1.073)" d="M9.23789 7.35397L9.23789 8.53488L6.96238 8.53488L6.96238 7.35397L9.23789 7.35397Z" fill="currentColor"/>
+    </svg>
+)
+
+/** ic_ds_personalization_outline_16 (figma extract) */
+export const IconPersonalizationOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none">
+    <path transform="translate(1.292 1.3)" d="M10.3232 9.18164C11.2868 9.18164 12.0985 9.82833 12.3506 10.7109L13.415 10.7109L13.415 11.8711L12.3496 11.8711C12.0971 12.7532 11.2864 13.3994 10.3232 13.3994C9.36031 13.3992 8.55012 12.7531 8.29785 11.8711L0 11.8711L0 10.7109L8.29688 10.7109C8.54876 9.82845 9.35988 9.18186 10.3232 9.18164ZM10.3232 10.3418C9.7999 10.3421 9.37534 10.7667 9.375 11.29C9.375 11.8137 9.79969 12.239 10.3232 12.2393C10.847 12.2393 11.2725 11.8138 11.2725 11.29C11.2721 10.7666 10.8468 10.3418 10.3232 10.3418ZM12.4326 11.291C12.4326 11.3549 12.4284 11.418 12.4229 11.4805C12.4287 11.4181 12.4326 11.355 12.4326 11.291ZM8.21484 11.2832C8.21484 11.2856 8.21484 11.2886 8.21484 11.291L8.21484 11.29C8.21484 11.2878 8.21484 11.2855 8.21484 11.2832ZM3.08301 4.59082C4.04605 4.59095 4.85696 5.23717 5.10938 6.11914L13.415 6.11914L13.415 7.2793L5.11035 7.2793C4.85833 8.16202 4.04648 8.80846 3.08301 8.80859C2.11972 8.80843 1.30963 8.16179 1.05762 7.2793L0 7.2793L0 6.11914L1.05762 6.11914C1.30994 5.23728 2.12006 4.59098 3.08301 4.59082ZM3.08301 5.75098C2.55962 5.75117 2.13512 6.17587 2.13477 6.69922C2.13477 7.22287 2.5594 7.64824 3.08301 7.64844C3.60665 7.64828 4.03223 7.2229 4.03223 6.69922C4.03187 6.17585 3.60643 5.75113 3.08301 5.75098ZM5.19238 6.69922C5.19238 6.763 5.18816 6.82633 5.18262 6.88867C5.18846 6.82629 5.19238 6.76313 5.19238 6.69922C5.19236 6.63495 5.18853 6.57152 5.18262 6.50879C5.18826 6.57154 5.19236 6.635 5.19238 6.69922ZM0.982422 6.52344C0.977382 6.58136 0.97463 6.63999 0.974609 6.69922C0.974609 6.75775 0.977496 6.81579 0.982422 6.87305C0.977758 6.81579 0.974609 6.75767 0.974609 6.69922C0.974628 6.64 0.977618 6.58142 0.982422 6.52344ZM10.3232 0C11.2869 0 12.0986 0.646596 12.3506 1.5293L13.415 1.5293L13.415 2.68945L12.3496 2.68945C12.363 2.64266 12.3754 2.59488 12.3857 2.54688C12.1838 3.50118 11.3376 4.21777 10.3232 4.21777C9.36037 4.21756 8.55018 3.57139 8.29785 2.68945L0 2.68945L0 1.5293L8.29688 1.5293C8.5487 0.646717 9.35981 0.00021854 10.3232 0ZM10.3232 1.16016C9.79984 1.16042 9.37524 1.58499 9.375 2.1084C9.375 2.63201 9.79969 3.05735 10.3232 3.05762C10.847 3.05762 11.2725 2.63217 11.2725 2.1084C11.2722 1.58483 10.8469 1.16016 10.3232 1.16016ZM12.4229 2.29883C12.4287 2.23641 12.4326 2.17331 12.4326 2.10938C12.4326 2.17327 12.4284 2.23638 12.4229 2.29883ZM8.21484 2.10938L8.21484 2.1084L8.21484 2.10938ZM8.22266 1.93359C8.21785 1.98897 8.21506 2.04499 8.21484 2.10156C8.21503 2.04501 8.2181 1.98902 8.22266 1.93359ZM8.22266 11.1162C8.2179 11.1713 8.21507 11.227 8.21484 11.2832C8.21504 11.227 8.21814 11.1713 8.22266 11.1162Z" fill="currentColor"/>
+    </svg>
+)
+
+/** ic_ds_project_add_outline_16 (figma extract) */
+export const IconProjectAddOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none">
+    <path transform="translate(9.52 2.52)" d="M3.55246 0L3.55246 2.44252L6 2.44252L6 3.55748L3.55246 3.55748L3.55246 6L2.43834 6L2.43834 3.55748L0 3.55748L0 2.44252L2.43834 2.44252L2.43834 0L3.55246 0Z" fill="currentColor"/>
+    <path transform="translate(0.3496 2.35)" d="M4.76367 0C5.36861 1.80598e-05 5.93113 0.310294 6.25488 0.821289L6.78027 1.64941C6.79685 1.67558 6.81791 1.69775 6.83887 1.71973C6.72186 2.15521 6.65702 2.61192 6.65137 3.08301C6.25601 2.96045 5.90909 2.70478 5.68164 2.3457L5.15723 1.5166C5.07183 1.38189 4.92318 1.3008 4.76367 1.30078L2.32422 1.30078C1.7589 1.30078 1.30078 1.7589 1.30078 2.32422L1.30078 10.1338C1.30078 10.6991 1.7589 11.1572 2.32422 11.1572L11.9766 11.1572C12.5419 11.1572 13 10.6991 13 10.1338L13 8.58398C13.4545 8.5135 13.8903 8.38748 14.3008 8.21289L14.3008 10.1338C14.3008 11.4171 13.2598 12.458 11.9766 12.458L2.32422 12.458C1.04093 12.458 0 11.4171 0 10.1338L0 2.32422C0 1.04093 1.04093 0 2.32422 0L4.76367 0Z" fill="currentColor"/>
+    </svg>
+)
+
+/** folder_open_16 (figma extract) */
+export const IconFolderOpen16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none">
+    <path transform="translate(0.5996 1.645)" d="M4.69624 0C5.3113 0.000140941 5.88623 0.307626 6.22749 0.819336L6.69917 1.52734C6.78449 1.65523 6.92823 1.7324 7.08198 1.73242L11.6699 1.73242C13.0038 1.73257 14.0859 2.81452 14.0859 4.14844L14.0859 5.05566C14.7693 5.4559 15.1595 6.2791 14.9374 7.11621L13.8837 11.0869C13.6026 12.1454 12.644 12.8818 11.5488 12.8818L2.41596 12.8818C1.01395 12.8816 -0.0511855 11.7074 0.00190073 10.376L0.00190073 2.41602C0.00190073 1.08201 1.08391 0 2.41792 0L4.69624 0ZM3.27827 6.18457C2.80902 6.18474 2.39772 6.50054 2.27729 6.9541L1.41499 10.2012C1.2407 10.8579 1.73653 11.5017 2.41596 11.502L11.5488 11.502C12.0182 11.502 12.4293 11.1861 12.5498 10.7324L13.6035 6.7627C13.681 6.47081 13.4611 6.18474 13.1591 6.18457L3.27827 6.18457ZM2.41792 1.38086C1.8462 1.38086 1.38276 1.8443 1.38276 2.41602L1.38276 5.72266C1.83056 5.15603 2.52166 4.80383 3.27827 4.80371L12.705 4.80371L12.705 4.14844C12.705 3.57681 12.2415 3.11342 11.6699 3.11328L7.08198 3.11328C6.46674 3.11326 5.89205 2.80484 5.55073 2.29297L5.07905 1.58496C4.99378 1.45723 4.84981 1.381 4.69624 1.38086L2.41792 1.38086Z" fill="currentColor"/>
+    <path transform="translate(1.979 3.026)" d="M11.7793 4.80371C12.0811 4.80388 12.3008 5.09009 12.2236 5.38184L11.1699 9.35156C11.0494 9.80525 10.6383 10.1211 10.1689 10.1211L1.03612 10.1211C0.356864 10.1206 -0.139141 9.47695 0.0351403 8.82031L0.897445 5.57324C1.01797 5.12 1.42946 4.80406 1.89842 4.80371L11.7793 4.80371ZM3.31639 0C3.46985 0.000107244 3.61388 0.0765707 3.6992 0.204102L4.17088 0.912109C4.51213 1.42391 5.08701 1.73228 5.70213 1.73242L10.29 1.73242C10.8616 1.73251 11.325 2.19605 11.3252 2.76758L11.3252 3.42285L1.89842 3.42285C1.14203 3.42309 0.450638 3.77535 0.00291371 4.3418L0.00291371 1.03516C0.00307753 0.463694 0.466614 0.000188756 1.03807 0L3.31639 0Z" fill="currentColor"/>
+    </svg>
+)
+
+/** folder_close_16 (figma extract) */
+export const IconFolderClose16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none">
+    <path transform="translate(1.5 2.429)" d="M5.05582 0.518756L4.50669 0.86654L5.05582 0.518756ZM13 9.4837L13.65 9.4837L13.65 3.53962L13 3.53962L12.35 3.53962L12.35 9.4837L13 9.4837ZM11.3264 1.86603L11.3264 1.21603L6.52313 1.21603L6.52313 1.86603L6.52313 2.51603L11.3264 2.51603L11.3264 1.86603ZM5.58054 1.34727L6.12968 0.999489L5.60495 0.170972L5.05582 0.518756L4.50669 0.86654L5.03141 1.69506L5.58054 1.34727ZM4.11323 1.23058e-13L4.11323 -0.65L1.67359 -0.65L1.67359 5.00699e-14L1.67359 0.65L4.11323 0.65L4.11323 1.23058e-13ZM0 1.67359L-0.65 1.67359L-0.65 9.4837L0 9.4837L0.65 9.4837L0.65 1.67359L0 1.67359ZM11.3264 11.1573L11.3264 10.5073L1.67359 10.5073L1.67359 11.1573L1.67359 11.8073L11.3264 11.8073L11.3264 11.1573ZM0 9.4837L-0.65 9.4837C-0.65 10.767 0.390308 11.8073 1.67359 11.8073L1.67359 11.1573L1.67359 10.5073C1.10828 10.5073 0.65 10.049 0.65 9.4837L0 9.4837ZM1.67359 5.00699e-14L1.67359 -0.65C0.390307 -0.65 -0.65 0.390309 -0.65 1.67359L0 1.67359L0.65 1.67359C0.65 1.10828 1.10828 0.65 1.67359 0.65L1.67359 5.00699e-14ZM5.05582 0.518756L5.60495 0.170972C5.28121 -0.340193 4.71829 -0.65 4.11323 -0.65L4.11323 1.23058e-13L4.11323 0.65C4.27282 0.65 4.4213 0.731715 4.50669 0.86654L5.05582 0.518756ZM6.52313 1.86603L6.52313 1.21603C6.36354 1.21603 6.21507 1.13431 6.12968 0.999489L5.58054 1.34727L5.03141 1.69506C5.35515 2.20622 5.91808 2.51603 6.52313 2.51603L6.52313 1.86603ZM13 3.53962L13.65 3.53962C13.65 2.25634 12.6097 1.21603 11.3264 1.21603L11.3264 1.86603L11.3264 2.51603C11.8917 2.51603 12.35 2.97431 12.35 3.53962L13 3.53962ZM13 9.4837L12.35 9.4837C12.35 10.049 11.8917 10.5073 11.3264 10.5073L11.3264 11.1573L11.3264 11.8073C12.6097 11.8073 13.65 10.767 13.65 9.4837L13 9.4837Z" fill="currentColor"/>
+    </svg>
+)
+
+/** tree_corner_8x10 (figma extract; session-tree "L" connector, stroke geometry pre-expanded) */
+export const IconTreeCorner8x10 = ({ size = 10, className }: IconProps) => (
+  <svg width={(size * 8) / 10} height={size} className={className} viewBox="-0.5 0 8.5 10.5" fill="none">
+    <path d="M0 0L-0.5 0L-0.5 7L0 7L0.5 7L0.5 0L0 0ZM3 10L3 10.5L8 10.5L8 10L8 9.5L3 9.5L3 10ZM0 7L-0.5 7C-0.5 8.933 1.067 10.5 3 10.5L3 10L3 9.5C1.61929 9.5 0.5 8.38071 0.5 7L0 7Z" fill="currentColor"/>
+  </svg>
+)
diff --git a/packages/client/ui-primitives/src/icons/props.ts b/packages/client/ui-primitives/src/icons/props.ts
new file mode 100644
index 0000000000..59b10c8492
--- /dev/null
+++ b/packages/client/ui-primitives/src/icons/props.ts
@@ -0,0 +1,8 @@
+/** Shared props for every ic_ds_* icon component. */
+export interface IconProps {
+  /** Square edge in px; defaults to the glyph's native size (14 or 16). */
+  size?: number | undefined
+  /** Extra class for layout placement; color rides currentColor.
+   * (`| undefined` for exactOptionalPropertyTypes: callers forward their own optional prop.) */
+  className?: string | undefined
+}
diff --git a/packages/client/ui-primitives/src/index.ts b/packages/client/ui-primitives/src/index.ts
new file mode 100644
index 0000000000..daea4202b3
--- /dev/null
+++ b/packages/client/ui-primitives/src/index.ts
@@ -0,0 +1,19 @@
+/**
+ * Pure React atoms (zero cordis): StateDot, icons, Button/Pill/Menu/Input,
+ * markdown family, ConnectionBanner. Everything consumes props plus --dsw-*
+ * token vars only. Contract: api-contracts v3 section 8.
+ */
+
+export { StateDot } from './StateDot.tsx'
+export type { StateDotState } from './StateDot.tsx'
+export { Button } from './Button.tsx'
+export type { ButtonVariant } from './Button.tsx'
+export { Pill } from './Pill.tsx'
+export { Input } from './Input.tsx'
+export { Menu } from './Menu.tsx'
+export type { MenuItem } from './Menu.tsx'
+export { ConnectionBanner } from './ConnectionBanner.tsx'
+export { FishLogo } from './FishLogo.tsx'
+export { JsonBlock } from './markdown/JsonBlock.tsx'
+export { MessageText } from './markdown/MessageText.tsx'
+export * from './icons/index.tsx'
diff --git a/packages/client/ui-primitives/src/invariant.ts b/packages/client/ui-primitives/src/invariant.ts
new file mode 100644
index 0000000000..5ce3411aff
--- /dev/null
+++ b/packages/client/ui-primitives/src/invariant.ts
@@ -0,0 +1,31 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-primitives`.
+ * @module @deepseek-ai/dsh-client-ui-primitives/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-primitives'
+
+/** Cordis companion plugin name. */
+export const name = 'client-ui-primitives-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: pure props-in React atoms with zero cordis surface —
+ * no events, no services, no mutable cross-plugin state; rendering contracts
+ * are asserted directly by this package's component specs.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/client/ui-primitives/src/markdown/JsonBlock.module.css b/packages/client/ui-primitives/src/markdown/JsonBlock.module.css
new file mode 100644
index 0000000000..7a967146e6
--- /dev/null
+++ b/packages/client/ui-primitives/src/markdown/JsonBlock.module.css
@@ -0,0 +1,32 @@
+.root {
+  margin: 4px 0;
+}
+
+.toggle {
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-secondary);
+  padding: 2px 6px;
+  border: none;
+  background: transparent;
+  cursor: pointer;
+  border-radius: 6px;
+}
+
+.toggle:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.body {
+  margin: 4px 0 0;
+  padding: 8px;
+  max-height: 200px;
+  overflow: auto;
+  background: var(--dsw-alias-markdown-code-block);
+  border: 1px solid var(--dsw-alias-border-l1);
+  border-radius: 6px;
+  font-family: var(--ds-font-family-code);
+  font-size: 11px;
+  line-height: 16px;
+  color: var(--dsw-alias-label-primary);
+}
diff --git a/packages/client/ui-primitives/src/markdown/JsonBlock.tsx b/packages/client/ui-primitives/src/markdown/JsonBlock.tsx
new file mode 100644
index 0000000000..c916c8303d
--- /dev/null
+++ b/packages/client/ui-primitives/src/markdown/JsonBlock.tsx
@@ -0,0 +1,32 @@
+// JsonBlock: collapsible JSON block (conversation side; independent from the RPC panel's PayloadJson to avoid cross-panel coupling).
+
+import { useMemo, useState } from 'react'
+import css from './JsonBlock.module.css'
+
+const MAX_CHARS = 20_000
+
+export function JsonBlock({ label, payload, defaultOpen = false }: {
+  label: string
+  payload: unknown
+  defaultOpen?: boolean
+}) {
+  const [open, setOpen] = useState(defaultOpen)
+  const body = useMemo(() => {
+    if (!open) return ''
+    let s: string
+    try {
+      s = JSON.stringify(payload, null, 2) ?? String(payload)
+    } catch {
+      s = String(payload)
+    }
+    return s.length > MAX_CHARS ? `${s.slice(0, MAX_CHARS)}\n… 已截断，共 ${s.length} 字符` : s
+  }, [open, payload])
+  return (
+    <div className={css.root}>
+      <button type="button" className={css.toggle} onClick={() => setOpen((v) => !v)}>
+        {open ? '▾' : '▸'} {label}
+      </button>
+      {open && <pre className={css.body}>{body}</pre>}
+    </div>
+  )
+}
diff --git a/packages/client/ui-primitives/src/markdown/MessageText.module.css b/packages/client/ui-primitives/src/markdown/MessageText.module.css
new file mode 100644
index 0000000000..c6a9c9b245
--- /dev/null
+++ b/packages/client/ui-primitives/src/markdown/MessageText.module.css
@@ -0,0 +1,9 @@
+.text {
+  white-space: pre-wrap;
+  word-break: break-word;
+  /* Font metrics inherit from the consumer's container (bubble 16/24,
+     assistant flow 16/28) — a generic text primitive must not pin its own
+     size, or every consumer's line grid breaks (44px bubble spec regression). */
+  font-size: inherit;
+  line-height: inherit;
+}
diff --git a/packages/client/ui-primitives/src/markdown/MessageText.tsx b/packages/client/ui-primitives/src/markdown/MessageText.tsx
new file mode 100644
index 0000000000..e9fa76d823
--- /dev/null
+++ b/packages/client/ui-primitives/src/markdown/MessageText.tsx
@@ -0,0 +1,7 @@
+// MessageText: the single text-block rendering point (Markdown support later = swap this component's internals, zero card-structure changes).
+
+import css from './MessageText.module.css'
+
+export function MessageText({ text }: { text: string }) {
+  return <div className={css.text}>{text}</div>
+}
diff --git a/packages/client/ui-primitives/tests/atoms.spec.tsx b/packages/client/ui-primitives/tests/atoms.spec.tsx
new file mode 100644
index 0000000000..f259cb334a
--- /dev/null
+++ b/packages/client/ui-primitives/tests/atoms.spec.tsx
@@ -0,0 +1,122 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Button, ConnectionBanner, Input, Menu, Pill } from '@deepseek-ai/dsh-client-ui-primitives'
+
+afterEach(cleanup)
+
+describe('Button', () => {
+  it('renders children, icon, and forwards clicks', () => {
+    const onClick = vi.fn()
+    render(<Button variant="primary" icon={<svg data-testid="ic" />} onClick={onClick}>Go</Button>)
+    const button = screen.getByRole('button', { name: 'Go' })
+    expect(screen.getByTestId('ic')).toBeDefined()
+    fireEvent.click(button)
+    expect(onClick).toHaveBeenCalledTimes(1)
+  })
+
+  it('disabled blocks interaction', () => {
+    const onClick = vi.fn()
+    render(<Button disabled onClick={onClick}>No</Button>)
+    fireEvent.click(screen.getByRole('button'))
+    expect(onClick).not.toHaveBeenCalled()
+  })
+})
+
+describe('Pill', () => {
+  it('is a span when static, a button when clickable', () => {
+    const { rerender } = render(<Pill active>tab</Pill>)
+    expect(screen.queryByRole('button')).toBeNull()
+    rerender(<Pill onClick={() => {}}>tab</Pill>)
+    expect(screen.getByRole('button', { name: 'tab' })).toBeDefined()
+  })
+
+  it('active and className land on both static and interactive forms', () => {
+    const { container, rerender } = render(<Pill className="x">tab</Pill>)
+    const asSpan = container.firstElementChild as HTMLElement
+    expect(asSpan.classList.contains('x')).toBe(true)
+    rerender(<Pill active className="x" onClick={() => {}}>tab</Pill>)
+    const asButton = screen.getByRole('button')
+    expect(asButton.classList.contains('x')).toBe(true)
+  })
+})
+
+describe('Input', () => {
+  it('forwards value/onChange and renders the leading icon', () => {
+    const onChange = vi.fn()
+    render(<Input icon={<svg data-testid="ic" />} value="q" onChange={onChange} placeholder="search" />)
+    const input = screen.getByPlaceholderText<HTMLInputElement>('search')
+    expect(input.value).toBe('q')
+    fireEvent.change(input, { target: { value: 'qq' } })
+    expect(onChange).toHaveBeenCalled()
+    expect(screen.getByTestId('ic')).toBeDefined()
+  })
+})
+
+describe('Menu', () => {
+  const items = [
+    { id: 'a', label: 'Alpha' },
+    { id: 'b', label: 'Beta', disabled: true },
+  ]
+
+  it('shows items only while open; select fires onSelect', () => {
+    const onSelect = vi.fn()
+    const { rerender } = render(
+      <Menu open={false} anchor={<span>trigger</span>} items={items} onSelect={onSelect} onClose={() => {}} />)
+    expect(screen.queryByRole('menu')).toBeNull()
+    rerender(
+      <Menu open anchor={<span>trigger</span>} items={items} selectedId="a" onSelect={onSelect} onClose={() => {}} />)
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Alpha' }))
+    expect(onSelect).toHaveBeenCalledWith('a')
+  })
+
+  it('disabled item does not select; Escape and outside pointerdown close', () => {
+    const onSelect = vi.fn()
+    const onClose = vi.fn()
+    render(
+      <Menu open anchor={<span>trigger</span>} items={items} onSelect={onSelect} onClose={onClose} />)
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Beta' }))
+    expect(onSelect).not.toHaveBeenCalled()
+    fireEvent.keyDown(document, { key: 'Escape' })
+    expect(onClose).toHaveBeenCalledTimes(1)
+    fireEvent.pointerDown(document.body)
+    expect(onClose).toHaveBeenCalledTimes(2)
+  })
+
+  it('inside pointerdown does not close', () => {
+    const onClose = vi.fn()
+    render(
+      <Menu open anchor={<span>trigger</span>} items={items} onSelect={() => {}} onClose={onClose} />)
+    fireEvent.pointerDown(screen.getByRole('menuitem', { name: 'Alpha' }))
+    expect(onClose).not.toHaveBeenCalled()
+  })
+
+  it('selected item shows the trailing check; align=end and className apply', () => {
+    const { container } = render(
+      <Menu
+        open
+        align="end"
+        className="x"
+        anchor={<span>trigger</span>}
+        items={items}
+        selectedId="a"
+        onSelect={() => {}}
+        onClose={() => {}}
+      />)
+    expect((container.firstElementChild as HTMLElement).classList.contains('x')).toBe(true)
+    const selected = screen.getByRole('menuitem', { name: 'Alpha' })
+    expect(selected.querySelector('svg')).not.toBeNull()
+    const other = screen.getByRole('menuitem', { name: 'Beta' })
+    expect(other.querySelector('svg')).toBeNull()
+    fireEvent.keyDown(document, { key: 'a' })
+  })
+})
+
+describe('ConnectionBanner', () => {
+  it('renders only while reconnecting', () => {
+    const { container, rerender } = render(<ConnectionBanner reconnecting={false} />)
+    expect(container.firstChild).toBeNull()
+    rerender(<ConnectionBanner reconnecting />)
+    expect(container.textContent).toContain('重连')
+  })
+})
diff --git a/packages/client/ui-primitives/tests/icons.spec.tsx b/packages/client/ui-primitives/tests/icons.spec.tsx
new file mode 100644
index 0000000000..ee396af4f5
--- /dev/null
+++ b/packages/client/ui-primitives/tests/icons.spec.tsx
@@ -0,0 +1,58 @@
+// @vitest-environment jsdom
+import { cleanup, render } from '@testing-library/react'
+import { afterEach, describe, expect, it } from 'vitest'
+import * as primitives from '@deepseek-ai/dsh-client-ui-primitives'
+import { IconApiOutline14, IconFolderClose16, IconSendOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
+
+afterEach(cleanup)
+
+// Icon components all share the IconProps signature; the barrel also exports
+// non-icon atoms (different props shapes), so filter by prefix BEFORE typing.
+const icons = Object.fromEntries(
+  Object.entries(primitives).filter(([name]) => name.startsWith('Icon')),
+) as Record<string, (p: primitives.IconProps) => React.JSX.Element>
+const iconNames = Object.keys(icons)
+
+describe('ic_ds_ icon set', () => {
+  it('exports the full P-I set (43 deepsuite + 6 figma extracts)', () => {
+    expect(iconNames.length).toBe(49)
+  })
+
+  it.each(iconNames)('%s renders an svg with currentColor fills and no hardcoded palette', name => {
+    const Icon = icons[name]!
+    const { container } = render(<Icon />)
+    const svg = container.querySelector('svg')
+    expect(svg).not.toBeNull()
+    const markup = container.innerHTML
+    expect(markup).not.toMatch(/#[0-9a-fA-F]{3,8}"/)
+    expect(markup).toContain('currentColor')
+  })
+
+  it('size and className props land on the root svg', () => {
+    const { container } = render(<IconSendOutline16 size={20} className="x" />)
+    const svg = container.querySelector('svg')!
+    expect(svg.getAttribute('width')).toBe('20')
+    expect(svg.getAttribute('height')).toBe('20')
+    expect(svg.classList.contains('x')).toBe(true)
+  })
+
+  it('native defaults: 14-glyphs default 14, 16-glyphs default 16', () => {
+    const api = render(<IconApiOutline14 />)
+    expect(api.container.querySelector('svg')!.getAttribute('width')).toBe('14')
+    const folder = render(<IconFolderClose16 />)
+    expect(folder.container.querySelector('svg')!.getAttribute('width')).toBe('16')
+  })
+})
+
+describe('FishLogo', () => {
+  it('renders the fish path in currentColor at the native ratio', () => {
+    const { container } = render(<primitives.FishLogo />)
+    const svg = container.querySelector('svg')!
+    expect(svg.getAttribute('width')).toBe('24')
+    expect(Number(svg.getAttribute('height'))).toBeCloseTo(17.66, 1)
+    expect(svg.getAttribute('viewBox')).toBe('0 0 23.16 17.04')
+    expect(container.querySelectorAll('path')).toHaveLength(1)
+    expect(container.innerHTML).toContain('currentColor')
+    expect(container.innerHTML).not.toContain('M0 0L23.16')
+  })
+})
diff --git a/packages/client/ui-primitives/tests/invariant.spec.ts b/packages/client/ui-primitives/tests/invariant.spec.ts
new file mode 100644
index 0000000000..72e5cb2f7c
--- /dev/null
+++ b/packages/client/ui-primitives/tests/invariant.spec.ts
@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import * as PrimitivesInvariant from '@deepseek-ai/dsh-client-ui-primitives/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+describe('invariant companion', () => {
+  it('registers under the package name with an empty installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    await expect(ctx.plugin(PrimitivesInvariant).await()).resolves.toBeDefined()
+  })
+})
diff --git a/packages/client/ui-primitives/tests/markdown.spec.tsx b/packages/client/ui-primitives/tests/markdown.spec.tsx
new file mode 100644
index 0000000000..6cfb5f4e8e
--- /dev/null
+++ b/packages/client/ui-primitives/tests/markdown.spec.tsx
@@ -0,0 +1,49 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it } from 'vitest'
+import { JsonBlock, MessageText } from '@deepseek-ai/dsh-client-ui-primitives'
+
+afterEach(cleanup)
+
+describe('MessageText', () => {
+  it('renders the text verbatim', () => {
+    const { container } = render(<MessageText text={'line1\nline2'} />)
+    expect(container.textContent).toBe('line1\nline2')
+  })
+})
+
+describe('JsonBlock', () => {
+  it('collapsed by default; toggle reveals pretty-printed payload', () => {
+    render(<JsonBlock label="args" payload={{ a: 1 }} />)
+    expect(screen.queryByText(/"a": 1/)).toBeNull()
+    fireEvent.click(screen.getByRole('button', { name: /args/ }))
+    expect(screen.getByText(/"a": 1/)).toBeDefined()
+    fireEvent.click(screen.getByRole('button', { name: /args/ }))
+    expect(screen.queryByText(/"a": 1/)).toBeNull()
+  })
+
+  it('defaultOpen renders the body immediately', () => {
+    const { container } = render(<JsonBlock label="args" payload={[1, 2]} defaultOpen />)
+    expect(container.querySelector('pre')?.textContent).toContain('1')
+  })
+
+  it('stringifies undefined payloads via String()', () => {
+    const { container } = render(<JsonBlock label="x" payload={undefined} defaultOpen />)
+    expect(container.querySelector('pre')?.textContent).toBe('undefined')
+  })
+
+  it('falls back to String() for circular payloads', () => {
+    const circular: { self?: unknown } = {}
+    circular.self = circular
+    const { container } = render(<JsonBlock label="x" payload={circular} defaultOpen />)
+    expect(container.querySelector('pre')?.textContent).toBe('[object Object]')
+  })
+
+  it('truncates beyond the size cap with a suffix note', () => {
+    const big = 'x'.repeat(30_000)
+    const { container } = render(<JsonBlock label="x" payload={big} defaultOpen />)
+    const body = container.querySelector('pre')!.textContent!
+    expect(body.length).toBeLessThan(30_000)
+    expect(body).toContain('截断')
+  })
+})
diff --git a/packages/client/ui-primitives/tests/state-dot.spec.tsx b/packages/client/ui-primitives/tests/state-dot.spec.tsx
new file mode 100644
index 0000000000..0d2cf52ef2
--- /dev/null
+++ b/packages/client/ui-primitives/tests/state-dot.spec.tsx
@@ -0,0 +1,45 @@
+// @vitest-environment jsdom
+import { cleanup, render } from '@testing-library/react'
+import { afterEach, describe, expect, it } from 'vitest'
+import { StateDot } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { StateDotState } from '@deepseek-ai/dsh-client-ui-primitives'
+
+afterEach(cleanup)
+
+describe('StateDot', () => {
+  it.each(['done', 'warning', 'ongoing', 'error'] as const)('renders state %s as data-state', state => {
+    const { container } = render(<StateDot state={state} />)
+    const dot = container.firstElementChild as HTMLElement
+    expect(dot.dataset['state']).toBe(state)
+    expect(dot.getAttribute('aria-hidden')).toBe('true')
+  })
+
+  it('solid states are spans; ongoing is an svg gradient ring', () => {
+    const { container, rerender } = render(<StateDot state="done" />)
+    expect(container.firstElementChild?.tagName).toBe('SPAN')
+    rerender(<StateDot state="ongoing" />)
+    const ring = container.firstElementChild as SVGSVGElement
+    expect(ring.tagName).toBe('svg')
+    const circle = ring.querySelector('circle')
+    expect(circle?.getAttribute('stroke-width')).toBe('1')
+    expect(circle?.getAttribute('stroke')).toMatch(/^url\(#/)
+    expect(ring.querySelector('linearGradient')).not.toBeNull()
+  })
+
+  it('sizes via the size prop in both shapes', () => {
+    const { container, rerender } = render(<StateDot state="done" size={12} />)
+    const dot = container.firstElementChild as HTMLElement
+    expect(dot.style.width).toBe('12px')
+    expect(dot.style.height).toBe('12px')
+    rerender(<StateDot state="ongoing" size={12} />)
+    const ring = container.firstElementChild as SVGSVGElement
+    expect(ring.getAttribute('width')).toBe('12')
+    expect(ring.getAttribute('height')).toBe('12')
+  })
+
+  it('rejects unknown states at the type level', () => {
+    const bad = (state: StateDotState) => state
+    // @ts-expect-error 'paused' is not one of the four states
+    expect(bad('paused')).toBe('paused')
+  })
+})
diff --git a/packages/client/ui-primitives/tsconfig.json b/packages/client/ui-primitives/tsconfig.json
new file mode 100644
index 0000000000..fa9b40f9e6
--- /dev/null
+++ b/packages/client/ui-primitives/tsconfig.json
@@ -0,0 +1,25 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "jsx": "react-jsx",
+    "lib": [
+      "ES2024",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": []
+  },
+  "include": [
+    "src"
+  ],
+  "exclude": [
+    "**/*.legacy.*"
+  ],
+  "references": [
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/client/ui-primitives/tsdown.config.ts b/packages/client/ui-primitives/tsdown.config.ts
new file mode 100644
index 0000000000..1532f5e5f6
--- /dev/null
+++ b/packages/client/ui-primitives/tsdown.config.ts
@@ -0,0 +1,31 @@
+import { defineConfig } from 'tsdown'
+
+/**
+ * ui-primitives is browser-only, but its lib bundle IS imported under plain
+ * Node now that the web shell is a lib (dsh-client-web's lib chain reaches
+ * this package). CSS imports are therefore stubbed to empty modules instead
+ * of externalized — the hashed class maps only matter in bundler contexts
+ * (loader module table / vite source paths), which compile src directly and
+ * never read lib.
+ */
+export default defineConfig({
+  entry: ['lib/types/index.js', 'lib/types/invariant.js'],
+  outDir: 'lib',
+  format: ['esm'],
+  platform: 'neutral',
+  target: 'es2024',
+  fixedExtension: false,
+  dts: false,
+  clean: false,
+  plugins: [{
+    name: 'dsh-css-stub',
+    resolveId(source: string) {
+      if (!source.endsWith('.css')) return null
+      return `\0dsh-css-stub:${source}.mjs`
+    },
+    load(id: string) {
+      if (!id.startsWith('\0dsh-css-stub:')) return null
+      return 'export default {};'
+    },
+  }],
+})
diff --git a/packages/client/ui-sidebar/README.md b/packages/client/ui-sidebar/README.md
new file mode 100644
index 0000000000..25f840ab3d
--- /dev/null
+++ b/packages/client/ui-sidebar/README.md
@@ -0,0 +1,19 @@
+# @deepseek-ai/dsh-client-ui-sidebar
+
+Sidebar plugin: session multi-level tree (cwd grouping + parentId nesting), search, by-workspace grouping, state dots, three creation entries. Contract: api-contracts v3 §6.
+
+`src/client/contract/slots.ts` is the single-domain contract file: `SidebarRootInjected` (the registrant's own injected share — tree hook, current-session hook, actions) and `SidebarRootComponentProps = OwnerOf<'sidebar'> & SidebarRootInjected` (the owner share referenced from ui-layout's slot declaration, never re-stated). `apply` registers SidebarRoot cast-free against that composition; the inject factory binds layout/sessions off `RootBinding<ClientContext>`.
+
+## Model Experience
+
+None, as the sidebar renders the browser session list; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **State dots have two live data states (running/none)** — the done/error/amber sources arrive with P-II approvals and notifications; the four-color primitive is already wired.
+- **Group-by menu ships by-workspace only** — Update/Status grouping strategies are drawn without specs and deferred.
+- **"New task completed" unread marking is local viewing state** — completion-time > last-seen never reaches the host.
diff --git a/packages/client/ui-sidebar/package.json b/packages/client/ui-sidebar/package.json
new file mode 100644
index 0000000000..91432fb79a
--- /dev/null
+++ b/packages/client/ui-sidebar/package.json
@@ -0,0 +1,62 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-sidebar",
+  "description": "Sidebar plugin: session multi-level tree, search, grouping, state dots",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-client-ui-layout"
+    ],
+    "platform": "web"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-client-web-react": "workspace:^",
+    "clsx": "^2.0.0",
+    "react": "^18.2.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}
diff --git a/packages/client/ui-sidebar/src/client/Rows.module.css b/packages/client/ui-sidebar/src/client/Rows.module.css
new file mode 100644
index 0000000000..65b6f0fa5e
--- /dev/null
+++ b/packages/client/ui-sidebar/src/client/Rows.module.css
@@ -0,0 +1,158 @@
+/* Tree rows (figma Cell set 14:3080): project 54px two-line, session 34px
+   single-line, radius 8, indent step 22px (16px slot + 6px gap). Hover swaps
+   are pure CSS: project folder -> chevron + action buttons; session time ->
+   ellipsis button. */
+
+.projectRow,
+.sessionRow {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  border-radius: 8px;
+  padding: 0 8px;
+  cursor: pointer;
+  user-select: none;
+  color: var(--dsw-alias-label-primary);
+}
+
+.projectRow:hover,
+.sessionRow:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.sessionRow.selected {
+  background: var(--dsw-alias-interactive-bg-active);
+}
+
+.projectRow {
+  height: 54px;
+}
+
+.sessionRow {
+  height: 34px;
+}
+
+.slot {
+  flex: none;
+  width: 16px;
+  height: 20px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+
+.folderActive {
+  color: var(--dsw-alias-state-business-primary);
+}
+
+/* Project leading slot: folder by default, chevron on row hover. */
+.projectRow .chevron { display: none; }
+.projectRow:hover .chevron { display: inline-flex; }
+.projectRow:hover .folder { display: none; }
+
+.projectText {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.title {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 14px;
+  line-height: 20px;
+}
+
+.sessionRow .title {
+  flex: 1;
+}
+
+.meta {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 12px;
+  line-height: 20px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.time {
+  flex: none;
+  font-size: 12px;
+  line-height: 20px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.dot {
+  flex: none;
+}
+
+/* Trailing action buttons surface on hover only (figma 27:4668 / 27:4656):
+   bare 16px glyphs, gap 12, tertiary grey. */
+.rowActions {
+  flex: none;
+  display: none;
+  align-items: center;
+  gap: 12px;
+}
+
+.projectRow:hover .rowActions,
+.sessionRow:hover .rowActions {
+  display: inline-flex;
+}
+
+.sessionRow:hover .time {
+  display: none;
+}
+
+.iconButton {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  border: none;
+  border-radius: 4px;
+  padding: 0;
+  background: transparent;
+  cursor: pointer;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.iconButton:hover {
+  color: var(--dsw-alias-label-primary);
+}
+
+/* Session expand twist occupies the leading 16px slot; keep a spacer when absent
+   so titles align across sibling rows. */
+.twist {
+  composes: iconButton;
+  width: 16px;
+  height: 20px;
+}
+
+/* "L" connector slot (figma arrow 14:3071): 16x16, glyph right-aligned. */
+.cornerSlot {
+  flex: none;
+  width: 16px;
+  height: 16px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: flex-end;
+  color: var(--dsw-alias-label-caption);
+}
+
+/* Chevrons and tree twists ride the caption grey (#ADB2B8); the folder glyph
+   stays one step darker (tertiary, #81858C) per the cell spec. Declared last
+   to win over the composed .iconButton color. */
+.chevron,
+.twist {
+  color: var(--dsw-alias-label-caption);
+}
diff --git a/packages/client/ui-sidebar/src/client/Rows.tsx b/packages/client/ui-sidebar/src/client/Rows.tsx
new file mode 100644
index 0000000000..c24f6b9fb5
--- /dev/null
+++ b/packages/client/ui-sidebar/src/client/Rows.tsx
@@ -0,0 +1,122 @@
+/**
+ * Sidebar 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.
+ */
+import clsx from 'clsx'
+import {
+  IconChevronDownOutline14, IconChevronRightOutline14,
+  IconEllipsisOutline16, IconFolderClose16, IconFolderOpen16, IconPlusOutline16,
+  IconTreeCorner8x10, StateDot,
+} from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ProjectRow, SessionRow } from './tree.ts'
+import { formatRelativeTime } from './tree.ts'
+import css from './Rows.module.css'
+
+/** Indent step per tree level: 16px slot + 6px gap (figma). */
+const INDENT_STEP = 22
+
+/**
+ * Project (workspace) row: 54px, folder + title + session count; hover
+ * reveals the chevron and the more/create buttons.
+ * @param props.row - derived project row.
+ * @param props.active - group contains the selected session (blue open folder).
+ * @param props.onToggle - expand/collapse the group.
+ * @param props.onCreate - create a session inside this group.
+ * @returns the row element.
+ */
+export function ProjectRowItem({ row, active, onToggle, onCreate }: {
+  row: ProjectRow
+  active: boolean
+  onToggle: () => void
+  onCreate: () => void
+}) {
+  const count = `${row.sessionCount} ${row.sessionCount === 1 ? 'session' : 'sessions'}`
+  return (
+    <div className={css.projectRow} role="treeitem" aria-expanded={row.expanded} onClick={onToggle}>
+      <span className={clsx(css.slot, css.folder, active && css.folderActive)}>
+        {row.expanded ? <IconFolderOpen16 /> : <IconFolderClose16 />}
+      </span>
+      <span className={clsx(css.slot, css.chevron)}>
+        {row.expanded ? <IconChevronDownOutline14 /> : <IconChevronRightOutline14 />}
+      </span>
+      <span className={css.projectText}>
+        <span className={css.title}>{row.label}</span>
+        <span className={css.meta}>{count}</span>
+      </span>
+      <span className={css.rowActions}>
+        {/* Row menu contents are not designed yet (figma draft notes); the button is the reserved anchor. */}
+        <button type="button" className={css.iconButton} aria-label="More" onClick={(e) => { e.stopPropagation() }}>
+          <IconEllipsisOutline16 />
+        </button>
+        <button
+          type="button"
+          className={css.iconButton}
+          aria-label="New session here"
+          onClick={(e) => { e.stopPropagation(); onCreate() }}
+        >
+          <IconPlusOutline16 />
+        </button>
+      </span>
+    </div>
+  )
+}
+
+/**
+ * Session row: 34px, indent by depth, expand twist when it has children,
+ * running state dot, relative time swapping to the more button on hover.
+ * @param props.row - derived session row.
+ * @param props.selected - row is the current session.
+ * @param props.now - epoch ms for relative-time formatting.
+ * @param props.onOpen - open this session.
+ * @param props.onToggle - unfold/fold the subtree.
+ * @returns the row element.
+ */
+export function SessionRowItem({ row, selected, now, onOpen, onToggle }: {
+  row: SessionRow
+  selected: boolean
+  now: number
+  onOpen: () => void
+  onToggle: () => void
+}) {
+  // Rail (figma sub-cell slot sequence): twist slot, always-reserved state
+  // slot (opacity-0 slots keep their 22px in figma, so titles align whether
+  // or not the dot is lit), then the L connector on child rows. Extra depth
+  // rides the left padding: indent spacers = depth - 1.
+  return (
+    <div
+      className={clsx(css.sessionRow, selected && css.selected)}
+      role="treeitem"
+      aria-selected={selected}
+      {...(row.hasChildren ? { 'aria-expanded': row.expanded } : {})}
+      style={{ paddingLeft: 8 + Math.max(0, row.depth - 1) * INDENT_STEP }}
+      onClick={onOpen}
+    >
+      {row.hasChildren
+        ? (
+            <button
+              type="button"
+              className={css.twist}
+              aria-label={row.expanded ? 'Collapse' : 'Expand'}
+              onClick={(e) => { e.stopPropagation(); onToggle() }}
+            >
+              {row.expanded ? <IconChevronDownOutline14 /> : <IconChevronRightOutline14 />}
+            </button>
+          )
+        : <span className={css.slot} />}
+      <span className={css.slot}>{row.running && <StateDot state="ongoing" />}</span>
+      {row.depth > 0 && (
+        <span className={css.cornerSlot} data-tree-corner="">
+          <IconTreeCorner8x10 />
+        </span>
+      )}
+      <span className={css.title}>{row.title}</span>
+      <span className={css.time}>{formatRelativeTime(row.updatedAt, now)}</span>
+      <span className={css.rowActions}>
+        <button type="button" className={css.iconButton} aria-label="More" onClick={(e) => { e.stopPropagation() }}>
+          <IconEllipsisOutline16 />
+        </button>
+      </span>
+    </div>
+  )
+}
diff --git a/packages/client/ui-sidebar/src/client/SidebarRoot.module.css b/packages/client/ui-sidebar/src/client/SidebarRoot.module.css
new file mode 100644
index 0000000000..5fdcbce74c
--- /dev/null
+++ b/packages/client/ui-sidebar/src/client/SidebarRoot.module.css
@@ -0,0 +1,248 @@
+/* Sidebar column (figma 133:7629): vertical stack, gap 8, padding 16/6,
+   sidebar fill + 1px right border painted by the layout column. Header block
+   (logo + New Session) and list area (section header + search + cells) carry
+   their own inner gaps per the style spec (1.2 / 1.3). */
+
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  height: 100%;
+  padding: 6px 16px;
+  box-sizing: border-box;
+  background: var(--dsw-specific-sidebar-fill);
+  color: var(--dsw-alias-label-primary);
+  font-size: 14px;
+}
+
+/* Header block (figma 133:7630): logo row + New Session, gap 16, padBottom 12. */
+.headerBlock {
+  flex: none;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  padding-bottom: 12px;
+}
+
+/* Logo row: 60px, brand mark left, collapse button right.
+   figma pad is (l,t,r,b)=(4,8,4,8) — horizontal 4, vertical 8. */
+.logoRow {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  height: 60px;
+  padding: 8px 4px;
+  box-sizing: border-box;
+}
+
+/* Brand group (figma I133:7632): fish + wordmark ride the text ink
+   (figma-flows ruling: main-screen instance is black; blue is brand
+   emphasis only). */
+.brand {
+  flex: 1;
+  min-width: 0;
+  display: inline-flex;
+  align-items: center;
+  gap: 7px;
+  overflow: hidden;
+}
+
+.wordmark {
+  font-weight: 600;
+  white-space: nowrap;
+}
+
+/* HARNESS badge (figma 34:10358): 14px tall, mono 11/500 on primary fill. */
+.badge {
+  flex: none;
+  padding: 0 3px;
+  border-radius: 2px;
+  background: var(--dsw-alias-label-primary);
+  color: var(--dsw-alias-label-primary-inverted);
+  font-family: var(--ds-font-family-code);
+  font-size: 11px;
+  font-weight: 500;
+  line-height: 14px;
+}
+
+.iconButton {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  border: none;
+  border-radius: 50%;
+  padding: 0;
+  background: transparent;
+  cursor: pointer;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.iconButton:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+/* New Session: 38px capsule (figma 133:7634). */
+.newSession {
+  flex: none;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  height: 38px;
+  padding: 8px 16px;
+  box-sizing: border-box;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 24px;
+  background: var(--dsw-alias-button-elevated-fill);
+  color: var(--dsw-alias-label-primary);
+  font-size: 14px;
+  font-weight: 510;
+  line-height: 22px;
+  cursor: pointer;
+}
+
+.newSession:hover {
+  background: var(--dsw-alias-button-floating-hover);
+}
+
+/* List area (figma 133:7640): section header + search + cells, gap 4.
+   Relative for the bottom fade overlay. */
+.listArea {
+  position: relative;
+  flex: 1;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+/* Bottom fade (figma 133:7666): 72px overlay pinned to the visible bottom,
+   transparent -> sidebar fill so it tracks the theme. */
+.fade {
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  height: 72px;
+  background: linear-gradient(to bottom, transparent, var(--dsw-specific-sidebar-fill));
+  pointer-events: none;
+}
+
+/* Batch separator (figma 133:7661): 20px spacer after an expanded project's
+   session run, before the next project row. */
+.batchGap {
+  flex: none;
+  height: 20px;
+}
+
+/* Section header: 36px, "WorkSpace" label + group-by / new-workspace buttons. */
+.sectionHeader {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  height: 36px;
+  padding-left: 12px;
+  box-sizing: border-box;
+  border-radius: 12px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.sectionLabel {
+  flex: 1;
+  min-width: 0;
+  line-height: 20px;
+}
+
+/* Search input: 38px capsule (figma 133:7649). Upstream binds a dedicated
+   design-system variable (light #F1F3F5 / dark #1B1B1C) matching no shipped
+   alias — a component token pinned to the static scale mirrors it (ruled
+   compliant: indirect via custom property, upstream-variable equivalent). */
+.search {
+  --dsh-search-input-fill: var(--dsw-static-neutral-bluish-75);
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  height: 38px;
+  margin-bottom: 8px; /* + 4px area gap = 12px to the first cell (spec padB12) */
+  padding: 0 14px;
+  box-sizing: border-box;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 24px;
+  background: var(--dsh-search-input-fill);
+  color: var(--dsw-alias-label-caption);
+}
+
+:global(body[data-ds-dark-theme]) .search {
+  --dsh-search-input-fill: var(--dsw-static-neutral-bluish-900);
+}
+
+.searchInput {
+  flex: 1;
+  min-width: 0;
+  border: none;
+  outline: none;
+  background: transparent;
+  font-size: 14px;
+  line-height: 20px;
+  color: var(--dsw-alias-label-primary);
+}
+
+.searchInput::placeholder {
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.clearButton {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  border: none;
+  border-radius: 50%;
+  padding: 0;
+  background: transparent;
+  cursor: pointer;
+  color: var(--dsw-alias-label-secondary);
+}
+
+/* Tree list: the only scrolling region. */
+.list {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding-bottom: 12px;
+}
+
+.empty {
+  padding: 16px 12px;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 13px;
+}
+
+/* Foot: settings entry (figma 133:7668). */
+.foot {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  height: 29px;
+  margin: 10px 0;
+  padding: 0 2px 0 6px;
+  border-radius: 12px;
+  cursor: pointer;
+  color: var(--dsw-alias-label-primary);
+}
+
+.foot:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
diff --git a/packages/client/ui-sidebar/src/client/SidebarRoot.tsx b/packages/client/ui-sidebar/src/client/SidebarRoot.tsx
new file mode 100644
index 0000000000..01c8fbfcd4
--- /dev/null
+++ b/packages/client/ui-sidebar/src/client/SidebarRoot.tsx
@@ -0,0 +1,164 @@
+/**
+ * SidebarRoot (figma 133:7629): logo row + collapse, New Session, search,
+ * WorkSpace section header with the group-by menu, session tree list,
+ * Settings foot. Pure presentational — data and actions arrive through the
+ * inject surface; the tree store is subscribed via useTree, never derived in
+ * render.
+ */
+import { Fragment, useState } from 'react'
+import clsx from 'clsx'
+import {
+  FishLogo,
+  IconCloseFill14, IconNewChatOutline16, IconPanelLeftOutline16, IconPersonalizationOutline16,
+  IconProjectAddOutline16, IconSearchOutline16, IconSettingsOutline14,
+  Menu,
+} from '@deepseek-ai/dsh-client-ui-primitives'
+import type { SidebarRootComponentProps } from './contract/slots.ts'
+import { ProjectRowItem, SessionRowItem } from './Rows.tsx'
+import css from './SidebarRoot.module.css'
+
+const GROUP_BY_ITEMS = [
+  { id: 'workspace', label: 'WorkSpace' },
+  // Update/Status grouping has no design yet (figma §3) — visible, disabled.
+  { id: 'update', label: 'Update', disabled: true },
+  { id: 'status', label: 'Status', disabled: true },
+]
+
+/**
+ * Render the sidebar column.
+ * @param props - composed slot props (owner share + injected surface, contract/slots.ts).
+ * @returns the sidebar element tree.
+ */
+export function SidebarRoot({ useTree, useCurrent, actions, tree }: SidebarRootComponentProps) {
+  const rows = useTree((s) => s.rows)
+  const query = useTree((s) => s.query)
+  const groupBy = useTree((s) => s.groupBy)
+  const current = useCurrent()
+  const [menuOpen, setMenuOpen] = useState(false)
+  const now = Date.now()
+
+  // Presentational lookup (not tree derivation): the group holding the
+  // selected session gets the active folder; only expanded groups can show it.
+  let activeGroup: string | undefined
+  if (current !== undefined) {
+    for (const row of rows) {
+      if (row.type === 'session' && row.id === current) { activeGroup = row.groupKey; break }
+    }
+  }
+
+  return (
+    <div className={css.root}>
+      <div className={css.headerBlock}>
+        <div className={css.logoRow}>
+          <span className={css.brand}>
+            {/* Wordmark svg not extracted yet (figma 88:8932) — text stands in at the same ink. */}
+            <FishLogo size={23} />
+            <span className={css.wordmark}>deepseek</span>
+            <span className={css.badge}>HARNESS</span>
+          </span>
+          <button
+            type="button"
+            className={css.iconButton}
+            aria-label="Collapse sidebar"
+            onClick={() => { actions.toggleSidebar() }}
+          >
+            <IconPanelLeftOutline16 />
+          </button>
+        </div>
+
+        <button type="button" className={css.newSession} onClick={() => { actions.create() }}>
+          <IconNewChatOutline16 size={14} />
+          New Session
+        </button>
+      </div>
+
+      <div className={css.listArea}>
+      <div className={css.sectionHeader}>
+        <span className={css.sectionLabel}>WorkSpace</span>
+        <Menu
+          open={menuOpen}
+          onClose={() => { setMenuOpen(false) }}
+          items={GROUP_BY_ITEMS}
+          selectedId={groupBy}
+          onSelect={() => { setMenuOpen(false) }}
+          align="end"
+          anchor={(
+            <button
+              type="button"
+              className={css.iconButton}
+              aria-label="Group by"
+              onClick={() => { setMenuOpen((v) => !v) }}
+            >
+              <IconPersonalizationOutline16 />
+            </button>
+          )}
+        />
+        <button
+          type="button"
+          className={css.iconButton}
+          aria-label="New workspace"
+          onClick={() => { actions.create() }}
+        >
+          <IconProjectAddOutline16 />
+        </button>
+      </div>
+
+      <label className={css.search}>
+        <IconSearchOutline16 size={14} />
+        <input
+          className={css.searchInput}
+          type="text"
+          placeholder="Search name, keywords..."
+          value={query}
+          onChange={(e) => { tree.setQuery(e.target.value) }}
+        />
+        {query !== '' && (
+          <button
+            type="button"
+            className={css.clearButton}
+            aria-label="Clear search"
+            onClick={() => { tree.setQuery('') }}
+          >
+            <IconCloseFill14 />
+          </button>
+        )}
+      </label>
+
+      <div className={css.list} role="tree" aria-label="Sessions">
+        {rows.length === 0 && (
+          <div className={css.empty}>{query === '' ? 'No sessions yet' : 'No matches'}</div>
+        )}
+        {rows.map((row, i) => row.type === 'project'
+          ? (
+              <Fragment key={`p:${row.key}`}>
+                {/* Batch separator: a project row closing an expanded session run (figma 133:7661). */}
+                {i > 0 && rows[i - 1]!.type === 'session' && <span className={css.batchGap} />}
+                <ProjectRowItem
+                  row={row}
+                  active={row.key === activeGroup}
+                  onToggle={() => { tree.toggleProject(row.key) }}
+                  onCreate={() => { actions.create(row.cwd) }}
+                />
+              </Fragment>
+            )
+          : (
+              <SessionRowItem
+                key={row.id}
+                row={row}
+                selected={row.id === current}
+                now={now}
+                onOpen={() => { actions.open(row.id) }}
+                onToggle={() => { tree.toggleSession(row.id) }}
+              />
+            ))}
+      </div>
+      <span className={css.fade} />
+      </div>
+
+      <div className={clsx(css.foot)} role="button" tabIndex={0} aria-label="Settings">
+        <IconSettingsOutline14 />
+        Settings
+      </div>
+    </div>
+  )
+}
diff --git a/packages/client/ui-sidebar/src/client/contract/slots.ts b/packages/client/ui-sidebar/src/client/contract/slots.ts
new file mode 100644
index 0000000000..4d1e0dd7f4
--- /dev/null
+++ b/packages/client/ui-sidebar/src/client/contract/slots.ts
@@ -0,0 +1,49 @@
+/**
+ * Sidebar slot contract: the registrant-side props composition for the
+ * layout-owned `sidebar` slot. The own injected share is declared here (a
+ * share's type lives with whoever wires it); the owner share is referenced
+ * off ui-layout's slot declaration through OwnerOf, never re-stated. Single
+ * domain — this is the package's whole contract surface.
+ */
+import type { OwnerOf } from '@deepseek-ai/dsh-client-ui-slots'
+// Type-only: pulls ui-layout's SlotMap merge (the 'sidebar' entry) into every
+// program that sees this contract, so OwnerOf<'sidebar'> resolves.
+import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SidebarTreeState } from '../store.ts'
+
+/** Cross-plugin actions bound in apply (layout / sessions services). */
+export interface SidebarActions {
+  open(id: SessionId): void
+  create(cwd?: string): void
+  toggleSidebar(): void
+}
+
+/** Plugin-owned tree viewing-state actions (tree store mutators). */
+export interface SidebarTreeActions {
+  toggleProject(key: string): void
+  toggleSession(id: SessionId): void
+  setQuery(query: string): void
+}
+
+/**
+ * Registrant-private injected share (arrives via the register inject
+ * factory). A type alias, not an interface: the alias carries an implicit
+ * index signature, so the factory's return crosses the registry's
+ * `Record<string, unknown>` boundary uncast.
+ */
+export type SidebarRootInjected = {
+  useTree: SnapshotSelectorHook<SidebarTreeState>
+  /** Current session selector (row highlight); undefined selects nothing. */
+  useCurrent: () => SessionId | undefined
+  actions: SidebarActions
+  tree: SidebarTreeActions
+}
+
+/**
+ * Full component props: owner share referenced from ui-layout's declaration
+ * plus the own injected share. Root scope has no standard injection
+ * (useSession is session-scope only), so no standard term appears.
+ */
+export type SidebarRootComponentProps = OwnerOf<'sidebar'> & SidebarRootInjected
diff --git a/packages/client/ui-sidebar/src/client/index.ts b/packages/client/ui-sidebar/src/client/index.ts
new file mode 100644
index 0000000000..fab3bc4836
--- /dev/null
+++ b/packages/client/ui-sidebar/src/client/index.ts
@@ -0,0 +1,71 @@
+/**
+ * Sidebar plugin, browser half: SidebarRoot registered into the layout-owned
+ * sidebar slot; tree derivation materialized in a plugin-owned snapshot
+ * store (pure consumer — no ctx service). Contract: api-contracts v3
+ * section 6; props composition in contract/slots.ts.
+ */
+import type { RootBinding } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ClientContext, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SidebarRootInjected } from './contract/slots.ts'
+import { createSidebarTreeStore } from './store.ts'
+import { SidebarRoot } from './SidebarRoot.tsx'
+
+export {
+  deriveRows, formatRelativeTime, projectLabel,
+  UNGROUPED_KEY, UNGROUPED_LABEL,
+  type ProjectRow, type SessionRow, type SidebarRow, type TreeView,
+} from './tree.ts'
+export {
+  createSidebarTreeStore,
+  type GroupBy, type SidebarTreeState, type SidebarTreeStore,
+} from './store.ts'
+export { ProjectRowItem, SessionRowItem } from './Rows.tsx'
+export { SidebarRoot } from './SidebarRoot.tsx'
+export type {
+  SidebarActions, SidebarRootComponentProps, SidebarRootInjected, SidebarTreeActions,
+} from './contract/slots.ts'
+
+/** Required services (cordis fiber inject — the loader passes the whole export surface as an object plugin). */
+export const inject = ['slots', 'layout', 'sessions']
+
+/**
+ * Client plugin body: build the tree store and register SidebarRoot into the
+ * sidebar slot with the inject surface bound off the root binding's ctx.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  const sessions = ctx.sessions
+
+  ctx.effect(() => {
+    const tree = createSidebarTreeStore(sessions)
+    // Called once per registration (root slots cache per entry); services are
+    // bound off the binding ctx per the contract's inject-surface wording.
+    const injectProps = (b: RootBinding<ClientContext>): SidebarRootInjected => {
+      const { sessions: boundSessions, layout } = b.ctx
+      return {
+        useTree: tree.store.useSelector,
+        useCurrent: () => layout.current.useSelector(s => s.sessionId),
+        actions: {
+          open: (id) => { layout.open(id) },
+          create: (cwd) => {
+            // Create-then-open: the sidebar's three creation entries all land
+            // in the new session (empty-state first-send stays with ui-conversation).
+            void boundSessions.create(cwd === undefined ? {} : { cwd })
+              .then((id: SessionId) => { layout.open(id) })
+          },
+          toggleSidebar: () => { layout.toggleSidebar() },
+        },
+        tree: {
+          toggleProject: (key) => { tree.toggleProject(key) },
+          toggleSession: (id) => { tree.toggleSession(id) },
+          setQuery: (query) => { tree.setQuery(query) },
+        },
+      }
+    }
+    const disposeRegistration = ctx.slots.register('sidebar', SidebarRoot, { inject: injectProps })
+    return () => {
+      disposeRegistration()
+      tree.dispose()
+    }
+  }, 'ui-sidebar: tree store + slot registration')
+}
diff --git a/packages/client/ui-sidebar/src/client/store.ts b/packages/client/ui-sidebar/src/client/store.ts
new file mode 100644
index 0000000000..f8bf2c724b
--- /dev/null
+++ b/packages/client/ui-sidebar/src/client/store.ts
@@ -0,0 +1,94 @@
+/**
+ * Sidebar tree store: plugin-owned snapshot store materializing the derived
+ * row list. Subscribes to sessions.list and re-derives on list changes and
+ * on viewing-state actions (expansion, search, group-by) — components
+ * subscribe to `rows` and never derive in render. Contract: api-contracts
+ * v3 section 6.
+ */
+import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import type { SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { deriveRows, type SidebarRow } from './tree.ts'
+
+/** Grouping strategy. Only by-workspace is designed (figma); the menu shows the rest disabled. */
+export type GroupBy = 'workspace'
+
+/** Sidebar tree state: materialized rows plus the viewing state that shaped them. */
+export interface SidebarTreeState {
+  rows: SidebarRow[]
+  /** Expanded project group keys (cwd or the ungrouped key). */
+  expandedProjects: string[]
+  /** Expanded session ids (subtree unfold). */
+  expandedSessions: string[]
+  query: string
+  groupBy: GroupBy
+}
+
+/** Store handle: snapshot store plus mutation actions and the list unsubscribe. */
+export interface SidebarTreeStore {
+  readonly store: SnapshotStore<SidebarTreeState>
+  toggleProject(key: string): void
+  toggleSession(id: SessionId): void
+  setQuery(query: string): void
+  setGroupBy(groupBy: GroupBy): void
+  dispose(): void
+}
+
+/**
+ * Create the sidebar tree store bound to a sessions service.
+ * @param sessions - root sessions service (only the list store is consumed).
+ * @returns store handle; call dispose on plugin teardown.
+ */
+export function createSidebarTreeStore(sessions: Pick<SessionsService, 'list'>): SidebarTreeStore {
+  const store = createSnapshotStore<SidebarTreeState>({
+    rows: [],
+    expandedProjects: [],
+    expandedSessions: [],
+    query: '',
+    groupBy: 'workspace',
+  })
+
+  const rederive = (draft: SidebarTreeState): void => {
+    draft.rows = deriveRows(sessions.list.getSnapshot(), {
+      expandedProjects: new Set(draft.expandedProjects),
+      expandedSessions: new Set(draft.expandedSessions),
+      query: draft.query,
+    })
+  }
+  store.update(rederive)
+  const unsubscribe = sessions.list.subscribe(() => { store.update(rederive) })
+
+  const toggle = (list: string[], key: string): void => {
+    const at = list.indexOf(key)
+    if (at >= 0) list.splice(at, 1)
+    else list.push(key)
+  }
+
+  return {
+    store,
+    toggleProject(key) {
+      store.update((draft) => {
+        toggle(draft.expandedProjects, key)
+        rederive(draft)
+      })
+    },
+    toggleSession(id) {
+      store.update((draft) => {
+        toggle(draft.expandedSessions, id)
+        rederive(draft)
+      })
+    },
+    setQuery(query) {
+      store.update((draft) => {
+        draft.query = query
+        rederive(draft)
+      })
+    },
+    setGroupBy(groupBy) {
+      store.update((draft) => {
+        draft.groupBy = groupBy
+        rederive(draft)
+      })
+    },
+    dispose: unsubscribe,
+  }
+}
diff --git a/packages/client/ui-sidebar/src/client/tree.ts b/packages/client/ui-sidebar/src/client/tree.ts
new file mode 100644
index 0000000000..1858643d43
--- /dev/null
+++ b/packages/client/ui-sidebar/src/client/tree.ts
@@ -0,0 +1,265 @@
+/**
+ * Pure sidebar tree derivation: session list snapshot -> flat render rows.
+ * Groups sessions by project directory (cwd), builds the per-group session
+ * tree from parentId links, sorts by recency, and applies search filtering
+ * with forced ancestor visibility. Components subscribe to the materialized
+ * rows and never derive in render. Contract: api-contracts v3 section 6.
+ */
+import type { SessionId, SessionListState, SessionSummary } from '@deepseek-ai/dsh-client-runtime/client'
+
+/** Group key for sessions without a project directory. */
+export const UNGROUPED_KEY = ''
+
+/** Display label for the ungrouped project row. */
+export const UNGROUPED_LABEL = 'Ungrouped'
+
+/** Project (workspace) row: 54px, two lines (label + session count). */
+export interface ProjectRow {
+  type: 'project'
+  /** Group key: the cwd, or {@link UNGROUPED_KEY}. */
+  key: string
+  cwd: string | undefined
+  label: string
+  /** Total sessions in the group, including hidden ones. */
+  sessionCount: number
+  expanded: boolean
+}
+
+/** Session row: 34px single line; depth drives the 22px indent steps. */
+export interface SessionRow {
+  type: 'session'
+  id: SessionId
+  /** Owning project group key (selection -> active-folder lookup). */
+  groupKey: string
+  title: string
+  /** 0 = directly under the project row. */
+  depth: number
+  hasChildren: boolean
+  expanded: boolean
+  running: boolean
+  updatedAt: number
+}
+
+/** One flat sidebar list row. */
+export type SidebarRow = ProjectRow | SessionRow
+
+/** Viewing state consumed by the derivation. */
+export interface TreeView {
+  expandedProjects: ReadonlySet<string>
+  expandedSessions: ReadonlySet<string>
+  query: string
+}
+
+interface Group {
+  key: string
+  cwd: string | undefined
+  label: string
+  summaries: Map<SessionId, SessionSummary>
+  roots: SessionId[]
+  children: Map<SessionId, SessionId[]>
+  latest: number
+}
+
+/**
+ * Project display label: basename of the group directory.
+ * @param cwd - project directory, or undefined for the ungrouped bucket.
+ * @returns basename, the raw cwd when it has no basename, or the ungrouped label.
+ */
+export function projectLabel(cwd: string | undefined): string {
+  if (cwd === undefined || cwd === '') return UNGROUPED_LABEL
+  const base = cwd.replace(/[/\\]+$/, '').split(/[/\\]/).pop()
+  return base !== undefined && base !== '' ? base : cwd
+}
+
+/** Recency comparator: newest first, id as the deterministic tiebreak (ids are unique per group). */
+function byRecency(a: SessionSummary, b: SessionSummary): number {
+  if (b.updatedAt !== a.updatedAt) return b.updatedAt - a.updatedAt
+  return a.id < b.id ? -1 : 1
+}
+
+function groupByCwd(list: SessionListState): Group[] {
+  const byKey = new Map<string, SessionSummary[]>()
+  for (const id of list.ids) {
+    const s = list.byId[id]
+    if (s === undefined) continue
+    const key = s.cwd ?? UNGROUPED_KEY
+    const members = byKey.get(key)
+    if (members === undefined) byKey.set(key, [s])
+    else members.push(s)
+  }
+  const groups: Group[] = []
+  for (const [key, members] of byKey) {
+    const summaries = new Map(members.map(m => [m.id, m]))
+    const children = new Map<SessionId, SessionId[]>()
+    const roots: SessionSummary[] = []
+    for (const m of members) {
+      // A session is a tree child only when its parent lives in the same
+      // group; cross-group or unknown parents degrade to group roots.
+      if (m.parentId !== undefined && m.parentId !== m.id && summaries.has(m.parentId)) {
+        const kids = children.get(m.parentId)
+        if (kids === undefined) children.set(m.parentId, [m.id])
+        else kids.push(m.id)
+      } else {
+        roots.push(m)
+      }
+    }
+    roots.sort(byRecency)
+    for (const kids of children.values()) {
+      kids.sort((a, b) => {
+        const sa = summaries.get(a)
+        const sb = summaries.get(b)
+        /* v8 ignore next -- unreachable: kid ids are inserted alongside their summaries. */
+        if (sa === undefined || sb === undefined) return 0
+        return byRecency(sa, sb)
+      })
+    }
+    const rootIds = roots.map(r => r.id)
+    // parentId cycles (host bug) leave members unreachable from any root;
+    // surface them as extra roots — the flatten walk's visited set stops
+    // loops. Each node sits in at most one kids list and roots have no
+    // in-group parent, so the scan pushes every reachable node exactly once.
+    const reachable = new Set<SessionId>(rootIds)
+    const stack = [...rootIds]
+    while (stack.length > 0) {
+      const top = stack.pop()
+      /* v8 ignore next -- unreachable: the loop condition guarantees a non-empty stack. */
+      if (top === undefined) break
+      for (const kid of children.get(top) ?? []) {
+        reachable.add(kid)
+        stack.push(kid)
+      }
+    }
+    for (const m of [...members].sort(byRecency)) {
+      if (!reachable.has(m.id)) rootIds.push(m.id)
+    }
+    let latest = 0
+    for (const m of members) latest = Math.max(latest, m.updatedAt)
+    groups.push({
+      key,
+      cwd: key === UNGROUPED_KEY ? undefined : key,
+      label: projectLabel(key === UNGROUPED_KEY ? undefined : key),
+      summaries,
+      roots: rootIds,
+      children,
+      latest,
+    })
+  }
+  groups.sort((a, b) => b.latest - a.latest || (a.label < b.label ? -1 : a.label > b.label ? 1 : 0))
+  return groups
+}
+
+function sessionRow(g: Group, s: SessionSummary, depth: number, hasChildren: boolean, expanded: boolean): SessionRow {
+  return {
+    type: 'session',
+    id: s.id,
+    groupKey: g.key,
+    title: s.title,
+    depth,
+    hasChildren,
+    expanded,
+    running: s.running,
+    updatedAt: s.updatedAt,
+  }
+}
+
+function flattenVisible(g: Group, expandedSessions: ReadonlySet<string>, rows: SidebarRow[]): void {
+  const visited = new Set<SessionId>()
+  const walk = (id: SessionId, depth: number): void => {
+    if (visited.has(id)) return
+    visited.add(id)
+    const s = g.summaries.get(id)
+    /* v8 ignore next -- unreachable: walked ids come from the grouped summaries. */
+    if (s === undefined) return
+    const kids = g.children.get(id) ?? []
+    const expanded = expandedSessions.has(id)
+    rows.push(sessionRow(g, s, depth, kids.length > 0, expanded))
+    if (expanded) for (const kid of kids) walk(kid, depth + 1)
+  }
+  for (const root of g.roots) walk(root, 0)
+}
+
+/** Matched sessions plus their ancestor chains (forced visible under search). */
+function searchVisible(g: Group, q: string): Set<SessionId> {
+  const visible = new Set<SessionId>()
+  for (const m of g.summaries.values()) {
+    if (!m.title.toLowerCase().includes(q)) continue
+    let cur: SessionSummary | undefined = m
+    while (cur !== undefined && !visible.has(cur.id)) {
+      visible.add(cur.id)
+      cur = cur.parentId !== undefined && cur.parentId !== cur.id ? g.summaries.get(cur.parentId) : undefined
+    }
+  }
+  return visible
+}
+
+function flattenSearch(g: Group, visible: ReadonlySet<SessionId>, rows: SidebarRow[]): void {
+  const visited = new Set<SessionId>()
+  const walk = (id: SessionId, depth: number): void => {
+    if (visited.has(id) || !visible.has(id)) return
+    visited.add(id)
+    const s = g.summaries.get(id)
+    /* v8 ignore next -- unreachable: walked ids come from the grouped summaries. */
+    if (s === undefined) return
+    const kids = (g.children.get(id) ?? []).filter(kid => visible.has(kid))
+    rows.push(sessionRow(g, s, depth, kids.length > 0, kids.length > 0))
+    for (const kid of kids) walk(kid, depth + 1)
+  }
+  for (const root of g.roots) walk(root, 0)
+}
+
+/**
+ * Derive the flat sidebar row list.
+ *
+ * Normal mode: every project row shows; sessions show under expanded
+ * projects, descending only into expanded sessions. Search mode (non-blank
+ * query, case-insensitive title substring): expansion state is ignored —
+ * matched sessions and their ancestor chains are forced visible, groups
+ * without a title or label hit are dropped, and a label-only hit keeps the
+ * bare project row.
+ * @param list - sessions list snapshot.
+ * @param view - expansion sets and search query.
+ * @returns rows in render order.
+ */
+export function deriveRows(list: SessionListState, view: TreeView): SidebarRow[] {
+  const q = view.query.trim().toLowerCase()
+  const rows: SidebarRow[] = []
+  for (const g of groupByCwd(list)) {
+    if (q === '') {
+      const expanded = view.expandedProjects.has(g.key)
+      rows.push({ type: 'project', key: g.key, cwd: g.cwd, label: g.label, sessionCount: g.summaries.size, expanded })
+      if (expanded) flattenVisible(g, view.expandedSessions, rows)
+    } else {
+      const visible = searchVisible(g, q)
+      if (visible.size === 0 && !g.label.toLowerCase().includes(q)) continue
+      rows.push({
+        type: 'project',
+        key: g.key,
+        cwd: g.cwd,
+        label: g.label,
+        sessionCount: g.summaries.size,
+        expanded: visible.size > 0,
+      })
+      flattenSearch(g, visible, rows)
+    }
+  }
+  return rows
+}
+
+/**
+ * Relative time label for session rows (figma samples: now / 2min / 1h / 2d / 18d / 2mo).
+ * @param updatedAt - epoch ms of the last update.
+ * @param now - current epoch ms.
+ * @returns compact age label.
+ */
+export function formatRelativeTime(updatedAt: number, now: number): string {
+  const MIN = 60_000
+  const HOUR = 3_600_000
+  const DAY = 86_400_000
+  const diff = Math.max(0, now - updatedAt)
+  if (diff < MIN) return 'now'
+  if (diff < HOUR) return `${Math.floor(diff / MIN)}min`
+  if (diff < DAY) return `${Math.floor(diff / HOUR)}h`
+  if (diff < 30 * DAY) return `${Math.floor(diff / DAY)}d`
+  if (diff < 365 * DAY) return `${Math.floor(diff / (30 * DAY))}mo`
+  return `${Math.floor(diff / (365 * DAY))}y`
+}
diff --git a/packages/client/ui-sidebar/src/css-modules.d.ts b/packages/client/ui-sidebar/src/css-modules.d.ts
new file mode 100644
index 0000000000..bc5e482353
--- /dev/null
+++ b/packages/client/ui-sidebar/src/css-modules.d.ts
@@ -0,0 +1,6 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css'
diff --git a/packages/client/ui-sidebar/src/index.ts b/packages/client/ui-sidebar/src/index.ts
new file mode 100644
index 0000000000..e84498c714
--- /dev/null
+++ b/packages/client/ui-sidebar/src/index.ts
@@ -0,0 +1,10 @@
+/**
+ * Sidebar plugin, node half. Pure UI plugin: the empty apply exists so the
+ * plugin appears in the host cordis.yml / Loader (load and lifecycle follow
+ * the host; the browser half ships via exports["./client"], discovered
+ * through the package.json dshClient declaration). Contract: api-contracts
+ * v3 sections 0.3 and 6.
+ */
+
+/** Host plugin body — no host-side behavior for the sidebar plugin. */
+export function apply(): void {}
diff --git a/packages/client/ui-sidebar/src/invariant.ts b/packages/client/ui-sidebar/src/invariant.ts
new file mode 100644
index 0000000000..1f6d34ba8f
--- /dev/null
+++ b/packages/client/ui-sidebar/src/invariant.ts
@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-sidebar`.
+ * @module @deepseek-ai/dsh-client-ui-sidebar/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-sidebar'
+
+/** Cordis companion plugin name. */
+export const name = 'client-ui-sidebar-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: a pure-consumer plugin deriving its tree store from
+ * sessions.list — it emits no cordis events and owns no cross-plugin mutable
+ * state; derivation and interaction behavior are asserted directly by this
+ * package's tree/store/component specs.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/client/ui-sidebar/tests/apply.spec.tsx b/packages/client/ui-sidebar/tests/apply.spec.tsx
new file mode 100644
index 0000000000..ea029c6709
--- /dev/null
+++ b/packages/client/ui-sidebar/tests/apply.spec.tsx
@@ -0,0 +1,158 @@
+// @vitest-environment jsdom
+/**
+ * apply wiring on a real cordis Context + SlotsService: tree store built and
+ * subscribed, SidebarRoot registered into the layout-owned sidebar slot with
+ * the inject surface bound off the root binding ctx, effect teardown
+ * unregisters and drops the list subscription. Behavior-level assertions
+ * only — the inject factory's cast shape is due to change with the slot
+ * type-chain redesign.
+ */
+import { Context } from 'cordis'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { act } from 'react'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import { scopedSlots, RootBindingProvider } from '@deepseek-ai/dsh-client-web-react'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SessionId, SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
+import { apply, inject } from '@deepseek-ai/dsh-client-ui-sidebar/client'
+// Type-only: ui-layout's SlotMap merge so the sidebar slot key typechecks.
+import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
+
+const sid = (s: string) => s as SessionId
+
+afterEach(cleanup)
+
+async function bench() {
+  const ctx = new Context()
+  await ctx.plugin(SlotsService).await()
+  const list = createSnapshotStore<SessionListState>({
+    ids: [sid('a')],
+    byId: { [sid('a')]: { id: sid('a'), title: 'alpha', cwd: '/proj', running: false, updatedAt: 1 } },
+  })
+  const sessions = { list, create: vi.fn(async () => sid('minted')) }
+  const layout = {
+    current: createSnapshotStore<{ sessionId?: SessionId }>({}),
+    open: vi.fn(),
+    toggleSidebar: vi.fn(),
+  }
+  ctx.provide('sessions', sessions)
+  ctx.provide('layout', layout)
+  const slots = ctx.get('slots') as SlotsService
+  slots.define('sidebar', { kind: 'single', scope: 'root' })
+  return { ctx, slots, sessions, layout }
+}
+
+function mountSlot(ctx: Context, slots: SlotsService) {
+  const surface = scopedSlots(slots.core, 'sidebar')
+  return render(
+    <RootBindingProvider value={{ ctx }}>
+      {surface.renderSlot('sidebar', {})}
+    </RootBindingProvider>,
+  )
+}
+
+describe('apply', () => {
+  it('declares the services it binds', () => {
+    expect(inject).toEqual(['slots', 'layout', 'sessions'])
+  })
+
+  it('fails loud when mounted without the inject declaration', async () => {
+    // ctx.sessions rides the cordis property proxy: reading it from a plugin
+    // that never declared the dependency throws instead of yielding undefined.
+    // Await the fiber thenable itself, not a second .await() chain: the test
+    // invariant host wraps plugin() with an eager readiness promise, and only
+    // the thenable settles it (a parallel .await() leaves it unhandled).
+    const ctx = new Context()
+    await ctx.plugin(SlotsService).await()
+    await expect(ctx.plugin({ apply })).rejects.toThrow(/without inject/)
+  })
+
+  it('registers SidebarRoot which renders from the live list', async () => {
+    const { ctx, slots } = await bench()
+    await ctx.plugin({ inject: [...inject], apply }).await()
+    mountSlot(ctx, slots)
+    expect(screen.getByText('proj')).toBeTruthy()
+    expect(screen.getByText('1 session')).toBeTruthy()
+  })
+
+  it('binds actions to layout/sessions off the root binding', async () => {
+    const { ctx, slots, sessions, layout } = await bench()
+    await ctx.plugin({ inject: [...inject], apply }).await()
+    mountSlot(ctx, slots)
+
+    act(() => { fireEvent.click(screen.getByLabelText('Collapse sidebar')) })
+    expect(layout.toggleSidebar).toHaveBeenCalledOnce()
+
+    act(() => { fireEvent.click(screen.getByText('proj')) })
+    act(() => { fireEvent.click(screen.getByText('alpha')) })
+    expect(layout.open).toHaveBeenCalledWith('a')
+
+    act(() => { fireEvent.click(screen.getByText('New Session')) })
+    expect(sessions.create).toHaveBeenCalledWith({})
+    // create-then-open lands after the create promise resolves.
+    await act(async () => { await Promise.resolve() })
+    expect(layout.open).toHaveBeenCalledWith('minted')
+
+    act(() => { fireEvent.click(screen.getAllByLabelText('New session here')[0]!) })
+    expect(sessions.create).toHaveBeenCalledWith({ cwd: '/proj' })
+  })
+
+  it('throws from the inject factory when binding ctx lacks the services', async () => {
+    const { ctx, slots } = await bench()
+    await ctx.plugin({ inject: [...inject], apply }).await()
+    const bare = new Context()
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    try {
+      const surface = scopedSlots(slots.core, 'sidebar')
+      render(
+        <RootBindingProvider value={{ ctx: bare }}>
+          {surface.renderSlot('sidebar', {})}
+        </RootBindingProvider>,
+      )
+      // The slot error boundary absorbs the throw and logs it.
+      expect(document.querySelector('[data-slot-error="sidebar"]')).toBeTruthy()
+    } finally {
+      spy.mockRestore()
+    }
+  })
+
+  it('search input drives the plugin-owned tree store', async () => {
+    const { ctx, slots } = await bench()
+    await ctx.plugin({ inject: [...inject], apply }).await()
+    mountSlot(ctx, slots)
+    act(() => {
+      fireEvent.change(screen.getByPlaceholderText('Search name, keywords...'), { target: { value: 'zzz' } })
+    })
+    expect(screen.getByText('No matches')).toBeTruthy()
+  })
+
+  it('expansion toggles route through the injected tree actions', async () => {
+    const { ctx, slots, sessions } = await bench()
+    sessions.list.update((draft) => {
+      draft.ids.push(sid('kid'))
+      draft.byId[sid('kid')] = {
+        id: sid('kid'), title: 'child', cwd: '/proj', parentId: sid('a'), running: false, updatedAt: 2,
+      }
+    })
+    await ctx.plugin({ inject: [...inject], apply }).await()
+    mountSlot(ctx, slots)
+    act(() => { fireEvent.click(screen.getByText('proj')) })
+    expect(screen.getByText('alpha')).toBeTruthy()
+    act(() => { fireEvent.click(screen.getByLabelText('Expand')) })
+    expect(screen.getByText('child')).toBeTruthy()
+  })
+
+  it('teardown unregisters the slot and drops the list subscription', async () => {
+    const { ctx, slots, sessions } = await bench()
+    const fiber = ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    expect(slots.entries('sidebar')).toHaveLength(1)
+    await fiber.dispose()
+    expect(slots.entries('sidebar')).toHaveLength(0)
+    // A post-teardown list change must not reach a disposed store.
+    expect(() => {
+      sessions.list.update((draft) => { draft.ids = [] })
+    }).not.toThrow()
+  })
+})
diff --git a/packages/client/ui-sidebar/tests/invariant.spec.ts b/packages/client/ui-sidebar/tests/invariant.spec.ts
new file mode 100644
index 0000000000..c524606dd5
--- /dev/null
+++ b/packages/client/ui-sidebar/tests/invariant.spec.ts
@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import * as SidebarInvariant from '@deepseek-ai/dsh-client-ui-sidebar/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+describe('invariant companion', () => {
+  it('registers under the package name with an empty installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    await expect(ctx.plugin(SidebarInvariant).await()).resolves.toBeDefined()
+  })
+
+  it('node-half apply is a no-op host placeholder', async () => {
+    const { apply } = await import('@deepseek-ai/dsh-client-ui-sidebar')
+    apply()
+    expect(true).toBe(true) // reaching here without throw is the contract
+  })
+})
diff --git a/packages/client/ui-sidebar/tests/sidebar-root.spec.tsx b/packages/client/ui-sidebar/tests/sidebar-root.spec.tsx
new file mode 100644
index 0000000000..db03c672dd
--- /dev/null
+++ b/packages/client/ui-sidebar/tests/sidebar-root.spec.tsx
@@ -0,0 +1,195 @@
+// @vitest-environment jsdom
+/**
+ * SidebarRoot interaction spec on the real framework stack: real tree store
+ * (web-react SnapshotStore) feeding the component through the same selector
+ * hook the inject surface hands out. Covers expand/collapse, subtree unfold,
+ * search filtering, row activation, and the creation entries.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { act } from 'react'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import type { SessionId, SessionListState, SessionSummary } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  createSidebarTreeStore, SidebarRoot,
+  type SidebarActions, type SidebarTreeStore,
+} from '@deepseek-ai/dsh-client-ui-sidebar/client'
+
+const sid = (s: string) => s as SessionId
+
+/** Bare-string init; brands ids and omits absent optional keys (exactOptionalPropertyTypes). */
+interface SummaryInit {
+  id: string
+  title?: string
+  cwd?: string
+  parentId?: string
+  running?: boolean
+  updatedAt?: number
+}
+
+function summary(init: SummaryInit): SessionSummary {
+  const s: SessionSummary = {
+    id: sid(init.id),
+    title: init.title ?? init.id,
+    running: init.running ?? false,
+    updatedAt: init.updatedAt ?? 0,
+  }
+  if (init.cwd !== undefined) s.cwd = init.cwd
+  if (init.parentId !== undefined) s.parentId = sid(init.parentId)
+  return s
+}
+
+function listStateOf(...summaries: SessionSummary[]): SessionListState {
+  const byId: Record<SessionId, SessionSummary> = {}
+  for (const s of summaries) byId[s.id] = s
+  return { ids: summaries.map((s) => s.id), byId }
+}
+
+afterEach(cleanup)
+
+function mount(...summaries: SessionSummary[]) {
+  const list = createSnapshotStore<SessionListState>(listStateOf(...summaries))
+  const tree: SidebarTreeStore = createSidebarTreeStore({ list })
+  const current = createSnapshotStore<{ id: SessionId | undefined }>({ id: undefined })
+  const actions: SidebarActions = {
+    open: vi.fn((id: SessionId) => { current.update((d) => { d.id = id }) }),
+    create: vi.fn(),
+    toggleSidebar: vi.fn(),
+  }
+  const utils = render(
+    <SidebarRoot
+      useTree={tree.store.useSelector}
+      useCurrent={() => current.useSelector((s) => s.id)}
+      actions={actions}
+      tree={tree}
+    />,
+  )
+  return { list, tree, current, actions, ...utils }
+}
+
+const projectData = () => [
+  summary({ id: 'root', title: 'root work', cwd: '/proj', updatedAt: 5 }),
+  summary({ id: 'kid', title: 'forked child', cwd: '/proj', parentId: sid('root'), updatedAt: 4 }),
+  summary({ id: 'lone', title: 'elsewhere', cwd: '/other', updatedAt: 3 }),
+]
+
+describe('SidebarRoot', () => {
+  it('renders chrome and collapsed project rows', () => {
+    mount(...projectData())
+    expect(screen.getByText('HARNESS')).toBeTruthy()
+    expect(screen.getByText('New Session')).toBeTruthy()
+    expect(screen.getByText('proj')).toBeTruthy()
+    expect(screen.getByText('2 sessions')).toBeTruthy()
+    expect(screen.getByText('1 session')).toBeTruthy()
+    expect(screen.queryByText('root work')).toBeNull()
+  })
+
+  it('expands a project on click and unfolds a subtree via the twist', () => {
+    mount(...projectData())
+    act(() => { fireEvent.click(screen.getByText('proj')) })
+    expect(screen.getByText('root work')).toBeTruthy()
+    expect(screen.queryByText('forked child')).toBeNull()
+    act(() => { fireEvent.click(screen.getByLabelText('Expand')) })
+    expect(screen.getByText('forked child')).toBeTruthy()
+    act(() => { fireEvent.click(screen.getByLabelText('Collapse')) })
+    expect(screen.queryByText('forked child')).toBeNull()
+  })
+
+  it('opens a session on row click and marks it selected', () => {
+    const { actions } = mount(...projectData())
+    act(() => { fireEvent.click(screen.getByText('proj')) })
+    act(() => { fireEvent.click(screen.getByText('root work')) })
+    expect(actions.open).toHaveBeenCalledWith('root')
+    expect(screen.getByText('root work').closest('[role="treeitem"]')!.getAttribute('aria-selected')).toBe('true')
+  })
+
+  it('search filters across groups and forces ancestor chains visible', () => {
+    mount(...projectData())
+    const input = screen.getByPlaceholderText('Search name, keywords...')
+    act(() => { fireEvent.change(input, { target: { value: 'forked' } }) })
+    expect(screen.getByText('forked child')).toBeTruthy()
+    expect(screen.getByText('root work')).toBeTruthy()
+    expect(screen.queryByText('elsewhere')).toBeNull()
+    expect(screen.queryByText(/^other$/)).toBeNull()
+    act(() => { fireEvent.click(screen.getByLabelText('Clear search')) })
+    expect(screen.queryByText('root work')).toBeNull()
+    expect(screen.getByText('proj')).toBeTruthy()
+  })
+
+  it('shows the blank-list empty state without a query', () => {
+    mount()
+    expect(screen.getByText('No sessions yet')).toBeTruthy()
+  })
+
+  it('shows the no-match empty state', () => {
+    mount(...projectData())
+    const input = screen.getByPlaceholderText('Search name, keywords...')
+    act(() => { fireEvent.change(input, { target: { value: 'zzz-none' } }) })
+    expect(screen.getByText('No matches')).toBeTruthy()
+  })
+
+  it('routes the three creation entries with the right cwd', () => {
+    const { actions } = mount(...projectData())
+    act(() => { fireEvent.click(screen.getByText('New Session')) })
+    expect(actions.create).toHaveBeenLastCalledWith()
+    act(() => { fireEvent.click(screen.getByLabelText('New workspace')) })
+    expect(actions.create).toHaveBeenLastCalledWith()
+    // Per-project "+" is hover-revealed by CSS; still clickable in jsdom.
+    act(() => { fireEvent.click(screen.getAllByLabelText('New session here')[0]!) })
+    expect(actions.create).toHaveBeenLastCalledWith('/proj')
+  })
+
+  it('collapse button and group-by menu behave', () => {
+    const { actions } = mount(...projectData())
+    act(() => { fireEvent.click(screen.getByLabelText('Collapse sidebar')) })
+    expect(actions.toggleSidebar).toHaveBeenCalledOnce()
+    expect(screen.queryByText('Update')).toBeNull()
+    act(() => { fireEvent.click(screen.getByLabelText('Group by')) })
+    expect(screen.getByText('Update')).toBeTruthy()
+    expect(screen.getByText('Status')).toBeTruthy()
+    // Selecting the active strategy closes the list (only workspace is enabled).
+    act(() => { fireEvent.click(screen.getByText('WorkSpace', { selector: 'button *' })) })
+    expect(screen.queryByText('Update')).toBeNull()
+    // Reopen and dismiss via Escape (Menu onClose channel).
+    act(() => { fireEvent.click(screen.getByLabelText('Group by')) })
+    act(() => { fireEvent.keyDown(document, { key: 'Escape' }) })
+    expect(screen.queryByText('Update')).toBeNull()
+  })
+
+  it('re-renders when the sessions list gains a session', async () => {
+    const { list } = mount(...projectData())
+    act(() => {
+      list.update((draft) => {
+        draft.ids.push(sid('fresh'))
+        draft.byId[sid('fresh')] = summary({ id: 'fresh', title: 'brand new', cwd: '/fresh', updatedAt: 99 })
+      })
+    })
+    // Store notifications are microtask-batched.
+    await act(async () => { await Promise.resolve() })
+    expect(screen.getByText('fresh')).toBeTruthy()
+  })
+
+  it('row "More" anchors swallow the click without opening or toggling', () => {
+    const { actions, tree } = mount(...projectData())
+    act(() => { fireEvent.click(screen.getByText('proj')) })
+    const before = tree.store.getSnapshot().expandedProjects.length
+    // Project-row anchor: must not collapse the project.
+    act(() => { fireEvent.click(screen.getAllByLabelText('More')[0]!) })
+    expect(tree.store.getSnapshot().expandedProjects).toHaveLength(before)
+    // Session-row anchor: must not open the session.
+    act(() => { fireEvent.click(screen.getAllByLabelText('More')[1]!) })
+    expect(actions.open).not.toHaveBeenCalled()
+  })
+
+  it('shows the running state dot only for running sessions', () => {
+    mount(
+      summary({ id: 'busy', title: 'busy one', cwd: '/p', running: true, updatedAt: 2 }),
+      summary({ id: 'idle', title: 'idle one', cwd: '/p', updatedAt: 1 }),
+    )
+    act(() => { fireEvent.click(screen.getByText('p')) })
+    const busyRow = screen.getByText('busy one').closest('[role="treeitem"]')!
+    const idleRow = screen.getByText('idle one').closest('[role="treeitem"]')!
+    expect(busyRow.querySelector('[data-state="ongoing"]')).toBeTruthy()
+    expect(idleRow.querySelector('[data-state="ongoing"]')).toBeNull()
+  })
+})
diff --git a/packages/client/ui-sidebar/tests/store.spec.ts b/packages/client/ui-sidebar/tests/store.spec.ts
new file mode 100644
index 0000000000..d0bb3b386b
--- /dev/null
+++ b/packages/client/ui-sidebar/tests/store.spec.ts
@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import type { SessionId, SessionListState, SessionSummary } from '@deepseek-ai/dsh-client-runtime/client'
+import { createSidebarTreeStore } from '@deepseek-ai/dsh-client-ui-sidebar/client'
+
+const sid = (s: string) => s as SessionId
+
+/** Bare-string init; brands ids and omits absent optional keys (exactOptionalPropertyTypes). */
+interface SummaryInit {
+  id: string
+  title?: string
+  cwd?: string
+  parentId?: string
+  running?: boolean
+  updatedAt?: number
+}
+
+function summary(init: SummaryInit): SessionSummary {
+  const s: SessionSummary = {
+    id: sid(init.id),
+    title: init.title ?? init.id,
+    running: init.running ?? false,
+    updatedAt: init.updatedAt ?? 0,
+  }
+  if (init.cwd !== undefined) s.cwd = init.cwd
+  if (init.parentId !== undefined) s.parentId = sid(init.parentId)
+  return s
+}
+
+function listStateOf(...summaries: SessionSummary[]): SessionListState {
+  const byId: Record<SessionId, SessionSummary> = {}
+  for (const s of summaries) byId[s.id] = s
+  return { ids: summaries.map(s => s.id), byId }
+}
+
+function setup(...summaries: SessionSummary[]) {
+  const list = createSnapshotStore<SessionListState>(listStateOf(...summaries))
+  const tree = createSidebarTreeStore({ list })
+  return { list, tree }
+}
+
+const flushMicrotasks = () => new Promise<void>((resolve) => { queueMicrotask(resolve) })
+
+describe('createSidebarTreeStore', () => {
+  it('materializes rows from the initial list snapshot', () => {
+    const { tree } = setup(summary({ id: 'a', cwd: '/p' }))
+    expect(tree.store.getSnapshot().rows).toEqual([
+      expect.objectContaining({ type: 'project', key: '/p', sessionCount: 1 }),
+    ])
+  })
+
+  it('re-derives when the sessions list changes', async () => {
+    const { list, tree } = setup(summary({ id: 'a', cwd: '/p' }))
+    list.update((draft) => {
+      draft.ids.push(sid('b'))
+      draft.byId[sid('b')] = summary({ id: 'b', cwd: '/q', updatedAt: 99 })
+    })
+    // Snapshot-store notifications are microtask-batched.
+    await flushMicrotasks()
+    expect(tree.store.getSnapshot().rows.map(r => r.type === 'project' && r.key)).toEqual(['/q', '/p'])
+  })
+
+  it('toggleProject expands and collapses synchronously', () => {
+    const { tree } = setup(summary({ id: 'a', cwd: '/p' }))
+    tree.toggleProject('/p')
+    expect(tree.store.getSnapshot().rows).toHaveLength(2)
+    tree.toggleProject('/p')
+    expect(tree.store.getSnapshot().rows).toHaveLength(1)
+  })
+
+  it('toggleSession unfolds a subtree', () => {
+    const { tree } = setup(
+      summary({ id: 'root', cwd: '/p', updatedAt: 2 }),
+      summary({ id: 'kid', cwd: '/p', parentId: sid('root'), updatedAt: 1 }),
+    )
+    tree.toggleProject('/p')
+    expect(tree.store.getSnapshot().rows).toHaveLength(2)
+    tree.toggleSession(sid('root'))
+    expect(tree.store.getSnapshot().rows).toHaveLength(3)
+  })
+
+  it('setQuery switches into search mode and back', () => {
+    const { tree } = setup(
+      summary({ id: 'a', title: 'needle', cwd: '/p' }),
+      summary({ id: 'b', title: 'other', cwd: '/q' }),
+    )
+    tree.setQuery('needle')
+    const rows = tree.store.getSnapshot().rows
+    expect(rows.map(r => r.type)).toEqual(['project', 'session'])
+    tree.setQuery('')
+    expect(tree.store.getSnapshot().rows.every(r => r.type === 'project')).toBe(true)
+  })
+
+  it('setGroupBy records the strategy and re-derives', () => {
+    const { tree } = setup(summary({ id: 'a', cwd: '/p' }))
+    tree.setGroupBy('workspace')
+    expect(tree.store.getSnapshot().groupBy).toBe('workspace')
+    expect(tree.store.getSnapshot().rows).toHaveLength(1)
+  })
+
+  it('dispose stops re-derivation on list changes', async () => {
+    const { list, tree } = setup(summary({ id: 'a', cwd: '/p' }))
+    tree.dispose()
+    list.update((draft) => {
+      draft.ids.push(sid('b'))
+      draft.byId[sid('b')] = summary({ id: 'b', cwd: '/q' })
+    })
+    await flushMicrotasks()
+    expect(tree.store.getSnapshot().rows).toHaveLength(1)
+  })
+})
diff --git a/packages/client/ui-sidebar/tests/tree.spec.ts b/packages/client/ui-sidebar/tests/tree.spec.ts
new file mode 100644
index 0000000000..1b29d460cf
--- /dev/null
+++ b/packages/client/ui-sidebar/tests/tree.spec.ts
@@ -0,0 +1,234 @@
+import { describe, expect, it } from 'vitest'
+import type { SessionId, SessionListState, SessionSummary } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  deriveRows, formatRelativeTime, projectLabel, UNGROUPED_KEY, UNGROUPED_LABEL,
+  type SessionRow, type TreeView,
+} from '@deepseek-ai/dsh-client-ui-sidebar/client'
+
+const sid = (s: string) => s as SessionId
+
+/** Bare-string init; brands ids and omits absent optional keys (exactOptionalPropertyTypes). */
+interface SummaryInit {
+  id: string
+  title?: string
+  cwd?: string
+  parentId?: string
+  running?: boolean
+  updatedAt?: number
+}
+
+function summary(init: SummaryInit): SessionSummary {
+  const s: SessionSummary = {
+    id: sid(init.id),
+    title: init.title ?? init.id,
+    running: init.running ?? false,
+    updatedAt: init.updatedAt ?? 0,
+  }
+  if (init.cwd !== undefined) s.cwd = init.cwd
+  if (init.parentId !== undefined) s.parentId = sid(init.parentId)
+  return s
+}
+
+function listOf(...summaries: SessionSummary[]): SessionListState {
+  const byId: Record<SessionId, SessionSummary> = {}
+  for (const s of summaries) byId[s.id] = s
+  return { ids: summaries.map(s => s.id), byId }
+}
+
+const view = (partial: Partial<TreeView> = {}): TreeView => ({
+  expandedProjects: partial.expandedProjects ?? new Set(),
+  expandedSessions: partial.expandedSessions ?? new Set(),
+  query: partial.query ?? '',
+})
+
+describe('projectLabel', () => {
+  it('takes the basename and survives trailing separators', () => {
+    expect(projectLabel('/home/me/proj')).toBe('proj')
+    expect(projectLabel('/home/me/proj/')).toBe('proj')
+    expect(projectLabel('C:\\work\\thing')).toBe('thing')
+  })
+
+  it('falls back for empty and root-only paths', () => {
+    expect(projectLabel(undefined)).toBe(UNGROUPED_LABEL)
+    expect(projectLabel('')).toBe(UNGROUPED_LABEL)
+    expect(projectLabel('///')).toBe('///')
+  })
+})
+
+describe('deriveRows grouping', () => {
+  it('groups by cwd into project rows with counts, newest group first', () => {
+    const rows = deriveRows(listOf(
+      summary({ id: 'a', cwd: '/x/alpha', updatedAt: 10 }),
+      summary({ id: 'b', cwd: '/x/beta', updatedAt: 30 }),
+      summary({ id: 'c', cwd: '/x/alpha', updatedAt: 20 }),
+    ), view())
+    expect(rows).toEqual([
+      expect.objectContaining({ type: 'project', key: '/x/beta', label: 'beta', sessionCount: 1, expanded: false }),
+      expect.objectContaining({ type: 'project', key: '/x/alpha', label: 'alpha', sessionCount: 2 }),
+    ])
+  })
+
+  it('orders equally-recent groups by label and skips ids missing from byId', () => {
+    const list = listOf(
+      summary({ id: 'b1', cwd: '/x/beta', updatedAt: 5 }),
+      summary({ id: 'a1', cwd: '/x/alpha', updatedAt: 5 }),
+      // Same basename and same recency as beta: label comparator returns 0,
+      // insertion order breaks the tie.
+      summary({ id: 'b2', cwd: '/y/beta', updatedAt: 5 }),
+    )
+    list.ids.push(sid('ghost'))
+    const rows = deriveRows(list, view())
+    expect(rows.map(r => r.type === 'project' && r.key)).toEqual(['/x/alpha', '/x/beta', '/y/beta'])
+  })
+
+  it('buckets cwd-less sessions under the ungrouped project row', () => {
+    const rows = deriveRows(listOf(summary({ id: 'a' })), view())
+    expect(rows).toEqual([
+      expect.objectContaining({ type: 'project', key: UNGROUPED_KEY, cwd: undefined, label: UNGROUPED_LABEL }),
+    ])
+  })
+
+  it('hides sessions under collapsed projects and shows them when expanded', () => {
+    const list = listOf(
+      summary({ id: 'a', cwd: '/p', updatedAt: 1 }),
+      summary({ id: 'b', cwd: '/p', updatedAt: 2 }),
+    )
+    expect(deriveRows(list, view()).filter(r => r.type === 'session')).toHaveLength(0)
+    const rows = deriveRows(list, view({ expandedProjects: new Set(['/p']) }))
+    expect(rows.slice(1)).toEqual([
+      expect.objectContaining({ type: 'session', id: 'b', depth: 0 }),
+      expect.objectContaining({ type: 'session', id: 'a', depth: 0 }),
+    ])
+  })
+})
+
+describe('deriveRows session tree', () => {
+  const treeList = listOf(
+    summary({ id: 'root', cwd: '/p', updatedAt: 5 }),
+    summary({ id: 'kid', cwd: '/p', parentId: sid('root'), updatedAt: 4 }),
+    summary({ id: 'grandkid', cwd: '/p', parentId: sid('kid'), updatedAt: 3 }),
+    summary({ id: 'other', cwd: '/p', updatedAt: 9 }),
+  )
+
+  it('nests children under expanded parents with increasing depth', () => {
+    const rows = deriveRows(treeList, view({
+      expandedProjects: new Set(['/p']),
+      expandedSessions: new Set(['root', 'kid']),
+    }))
+    expect(rows.slice(1)).toEqual([
+      expect.objectContaining({ id: 'other', depth: 0, hasChildren: false }),
+      expect.objectContaining({ id: 'root', depth: 0, hasChildren: true, expanded: true }),
+      expect.objectContaining({ id: 'kid', depth: 1, hasChildren: true, expanded: true }),
+      expect.objectContaining({ id: 'grandkid', depth: 2, hasChildren: false }),
+    ])
+  })
+
+  it('collapses subtrees at unexpanded sessions', () => {
+    const rows = deriveRows(treeList, view({ expandedProjects: new Set(['/p']) }))
+    const ids = rows.filter((r): r is SessionRow => r.type === 'session').map(r => r.id)
+    expect(ids).toEqual(['other', 'root'])
+  })
+
+  it('degrades a cross-group parent link to a group root', () => {
+    const rows = deriveRows(listOf(
+      summary({ id: 'p1', cwd: '/a', updatedAt: 2 }),
+      summary({ id: 'stray', cwd: '/b', parentId: sid('p1'), updatedAt: 1 }),
+    ), view({ expandedProjects: new Set(['/a', '/b']) }))
+    expect(rows).toEqual([
+      expect.objectContaining({ type: 'project', key: '/a' }),
+      expect.objectContaining({ id: 'p1', depth: 0 }),
+      expect.objectContaining({ type: 'project', key: '/b' }),
+      expect.objectContaining({ id: 'stray', depth: 0 }),
+    ])
+  })
+
+  it('keeps cycle members visible as extra roots without looping', () => {
+    const rows = deriveRows(listOf(
+      summary({ id: 'x', cwd: '/p', parentId: sid('y'), updatedAt: 2 }),
+      summary({ id: 'y', cwd: '/p', parentId: sid('x'), updatedAt: 1 }),
+      summary({ id: 'self', cwd: '/p', parentId: sid('self'), updatedAt: 3 }),
+    ), view({ expandedProjects: new Set(['/p']), expandedSessions: new Set(['x', 'y', 'self']) }))
+    const ids = rows.filter((r): r is SessionRow => r.type === 'session').map(r => r.id)
+    expect(ids).toContain('self')
+    expect(ids).toContain('x')
+    expect(ids).toContain('y')
+    expect(ids).toHaveLength(3)
+  })
+
+  it('breaks updatedAt ties deterministically by id', () => {
+    const rows = deriveRows(listOf(
+      summary({ id: 'b', cwd: '/p', updatedAt: 7 }),
+      summary({ id: 'a', cwd: '/p', updatedAt: 7 }),
+      summary({ id: 'c', cwd: '/p', updatedAt: 7 }),
+    ), view({ expandedProjects: new Set(['/p']) }))
+    const ids = rows.filter((r): r is SessionRow => r.type === 'session').map(r => r.id)
+    expect(ids).toEqual(['a', 'b', 'c'])
+  })
+
+  it('collects multiple children under one parent in recency order', () => {
+    const rows = deriveRows(listOf(
+      summary({ id: 'p', cwd: '/p', updatedAt: 9 }),
+      summary({ id: 'old', cwd: '/p', parentId: sid('p'), updatedAt: 1 }),
+      summary({ id: 'new', cwd: '/p', parentId: sid('p'), updatedAt: 5 }),
+    ), view({ expandedProjects: new Set(['/p']), expandedSessions: new Set(['p']) }))
+    const ids = rows.filter((r): r is SessionRow => r.type === 'session').map(r => r.id)
+    expect(ids).toEqual(['p', 'new', 'old'])
+  })
+
+  it('carries the running flag onto rows', () => {
+    const rows = deriveRows(
+      listOf(summary({ id: 'a', cwd: '/p', running: true })),
+      view({ expandedProjects: new Set(['/p']) }))
+    expect(rows[1]).toEqual(expect.objectContaining({ id: 'a', running: true }))
+  })
+})
+
+describe('deriveRows search', () => {
+  const list = listOf(
+    summary({ id: 'root', title: 'alpha work', cwd: '/p', updatedAt: 5 }),
+    summary({ id: 'kid', title: 'deep needle here', cwd: '/p', parentId: sid('root'), updatedAt: 4 }),
+    summary({ id: 'noise', title: 'unrelated', cwd: '/p', updatedAt: 3 }),
+    summary({ id: 'q', title: 'quiet', cwd: '/other', updatedAt: 2 }),
+  )
+
+  it('forces matched sessions and their ancestor chains visible, ignoring expansion', () => {
+    const rows = deriveRows(list, view({ query: 'NEEDLE' }))
+    expect(rows).toEqual([
+      expect.objectContaining({ type: 'project', key: '/p', expanded: true }),
+      expect.objectContaining({ id: 'root', depth: 0, expanded: true }),
+      expect.objectContaining({ id: 'kid', depth: 1 }),
+    ])
+  })
+
+  it('drops groups without a hit and keeps a bare project row on label-only hits', () => {
+    const rows = deriveRows(list, view({ query: 'other' }))
+    expect(rows).toEqual([
+      expect.objectContaining({ type: 'project', key: '/other', expanded: false }),
+    ])
+  })
+
+  it('blank query means normal mode', () => {
+    const rows = deriveRows(list, view({ query: '   ' }))
+    expect(rows.every(r => r.type === 'project')).toBe(true)
+  })
+})
+
+describe('formatRelativeTime', () => {
+  const now = 1_000_000_000_000
+  it.each([
+    [now, 'now'],
+    [now - 30_000, 'now'],
+    [now - 2 * 60_000, '2min'],
+    [now - 3_600_000, '1h'],
+    [now - 2 * 86_400_000, '2d'],
+    [now - 18 * 86_400_000, '18d'],
+    [now - 65 * 86_400_000, '2mo'],
+    [now - 400 * 86_400_000, '1y'],
+  ])('%d -> %s', (at, label) => {
+    expect(formatRelativeTime(at, now)).toBe(label)
+  })
+
+  it('clamps future timestamps to now', () => {
+    expect(formatRelativeTime(now + 5_000, now)).toBe('now')
+  })
+})
diff --git a/packages/client/ui-sidebar/tsconfig.json b/packages/client/ui-sidebar/tsconfig.json
new file mode 100644
index 0000000000..a560748366
--- /dev/null
+++ b/packages/client/ui-sidebar/tsconfig.json
@@ -0,0 +1,40 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "jsx": "react-jsx",
+    "lib": [
+      "ES2024",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": []
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../ui-primitives"
+    },
+    {
+      "path": "../web-react"
+    },
+    {
+      "path": "../runtime"
+    },
+    {
+      "path": "../ui-layout"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/client/ui-sidebar/tsdown.config.ts b/packages/client/ui-sidebar/tsdown.config.ts
new file mode 100644
index 0000000000..2d575677b7
--- /dev/null
+++ b/packages/client/ui-sidebar/tsdown.config.ts
@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-ui-sidebar', ['lib/types/index.js', 'lib/types/invariant.js'])
diff --git a/packages/client/ui-slots/README.md b/packages/client/ui-slots/README.md
new file mode 100644
index 0000000000..dae69c5eae
--- /dev/null
+++ b/packages/client/ui-slots/README.md
@@ -0,0 +1,18 @@
+# @deepseek-ai/dsh-client-ui-slots
+
+Slot registry pure core: SlotMap declaration merging, SlotCore (single/list/keyed), ScopedSlots types. Contract: api-contracts v3 §1 + the slot type-chain design (composed-props registration).
+
+A SlotMap entry declares `{ kind; scope; owner; children? }`. `owner` is the render-side props share the slot-owning package declares; registrants reference it through `OwnerOf<K>` and never re-state it. The registrant's injected share `I` stays a local type at the registration site, inferred from the inject factory (`InjectFactory<E, I, Ctx>`; context-narrowing wrappers pin `Ctx`). `SlotCore.register` constrains the component against `ComposedProps<K, I>` — owner share & bottom-typed standard share (`StandardOf`) & `children`-gated slots face (`SlotsFaceOf`) & `I` — through the bare-call-signature `SlotComponent` position. `children` optionally whitelists delegable sub-slot keys (`ChildrenOf`; constraint-side validation only — delivery stays with the renderer); `narrowSlots` narrows a `ScopedSlots` surface to a subset whitelist.
+
+## Model Experience
+
+None, as the slot registry is browser-side UI plumbing; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **`StandardOf` is a constraint-position bottom type (`useSession: never`), not the arriving hook type** — this zero-dependency layer cannot see the conversation snapshot; components declare the narrowed hook they consume, and what actually arrives is web-react's renderer responsibility.
+- **The legacy `props` entry member (with `OwnerProps`'s Partial owner share) remains for migration** — entries not yet declaring `owner` keep the P-I full-props constraint; both forms disappear with the last legacy declaration.
diff --git a/packages/client/ui-slots/package.json b/packages/client/ui-slots/package.json
new file mode 100644
index 0000000000..82de6483e6
--- /dev/null
+++ b/packages/client/ui-slots/package.json
@@ -0,0 +1,38 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-slots",
+  "description": "Slot registry pure core: SlotMap declaration-merge surface, SlotCore (single/list/keyed), ScopedSlots types",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "license": "BSD-3-Clause",
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/client/ui-slots/src/index.ts b/packages/client/ui-slots/src/index.ts
new file mode 100644
index 0000000000..9c9396a99f
--- /dev/null
+++ b/packages/client/ui-slots/src/index.ts
@@ -0,0 +1,407 @@
+/**
+ * Slot registry pure core. Owners declare slot contracts by merging into
+ * {@link SlotMap}; `define` records the runtime spec, `register` contributes a
+ * component. Zero runtime dependencies (React types only).
+ *
+ * SlotMap and its companion types live directly in this entry module: consumer
+ * `declare module` augmentation merges with declarations lexically in the
+ * augmented module, not with re-exports.
+ */
+/* eslint-disable @typescript-eslint/no-redundant-type-constituents --
+ * `keyof SlotMap & string` is the declare-merge key pattern: SlotMap is empty
+ * in THIS compilation unit (so the intersection reads as `never`), but every
+ * consumer merges keys in and the intersection is what keeps them string-typed.
+ * The rule fires on the empty-map view, not on real redundancy. */
+import type { FC, ReactNode } from 'react'
+
+/** Slot contract table. Owners extend via declaration merging; entries are {@link SlotEntryDef}. */
+export interface SlotMap {}
+
+/** Slot cardinality: single occupant, ordered list, or key-dispatched. */
+export type SlotKind = 'single' | 'list' | 'keyed'
+
+/** Slot data context: root (no session) or session-bound. */
+export type SlotScope = 'root' | 'session'
+
+/**
+ * One SlotMap entry: kind/scope axes, the owner-supplied props share, and an
+ * optional sub-slot whitelist. Ownership rule (a share's type lives with
+ * whoever wires it): `owner` is the render-side share declared by the
+ * slot-owning package and REFERENCED by registrants; the registrant's own
+ * injected share never enters this table — full component props are composed
+ * at the component as `OwnerOf<K> & <injector-narrowed standard> & OwnInjected`.
+ * `props` is the legacy full-props slot kept while consumers migrate to
+ * composed declarations (new entries declare `owner` and omit it).
+ */
+export interface SlotEntryDef {
+  kind: SlotKind
+  scope: SlotScope
+  props?: object
+  owner?: object
+  children?: keyof SlotMap & string
+}
+
+/**
+ * Owner-supplied props share for a slot key: the render-side contract half.
+ * Falls back to the legacy Partial form when the entry declares no `owner`.
+ */
+export type OwnerOf<K extends keyof SlotMap & string> =
+  SlotMap[K] extends { owner: infer O extends object } ? O : OwnerProps<SlotMap[K]>
+
+/**
+ * CONSTRAINT-position standard share for register(): the framework supplies
+ * session slots' bound selector hook, so it is bottom-typed here — any
+ * registrant narrowing (e.g. a runtime-typed conversation hook) is accepted,
+ * and the type responsibility for what actually arrives lives with the
+ * injecting side (web-react's renderer). Do NOT compose component props from
+ * this type; declare the narrowed hook the component actually consumes.
+ */
+export type StandardOf<K extends keyof SlotMap & string> =
+  SlotMap[K]['scope'] extends 'session' ? { useSession: never } : object
+
+/**
+ * Delegable sub-slot whitelist declared by an entry: the `children` key union,
+ * or `never` when the entry declares none (no delegation authorized).
+ */
+export type ChildrenOf<K extends keyof SlotMap & string> =
+  SlotMap[K] extends { children: infer C extends keyof SlotMap & string } ? C : never
+
+/**
+ * B-b optional validation layer over the hand-written whitelist (B-a): the
+ * composed register constraint carries a `slots` face whose key union is the
+ * entry's `children` declaration. Components wanting a SUBSET whitelist
+ * accept it through ScopedSlots covariance; an out-of-union whitelist makes
+ * the component's `slots` parameter unsatisfiable and the register call site
+ * reports it. Entries without `children` add no slots constraint, so any
+ * hand-written whitelist registers freely (the layer is opt-in per entry).
+ * This is constraint-side only: whether slots are actually delivered stays
+ * with the renderer/owner (B-a trust).
+ */
+export type SlotsFaceOf<K extends keyof SlotMap & string> =
+  [ChildrenOf<K>] extends [never]
+    ? object
+    : { slots: ScopedSlots<ChildrenOf<K>> }
+
+/**
+ * The registration-boundary composed props constraint: owner share + standard
+ * share + registrant share, gated by the entry's `children` authorization
+ * (see {@link ChildrenChecked}). Entries without an `owner` declaration
+ * (legacy full-props form) keep the plain props constraint until they migrate.
+ */
+export type ComposedProps<K extends keyof SlotMap & string, I extends object> =
+  SlotMap[K] extends { owner: infer O extends object }
+    ? O & StandardOf<K> & SlotsFaceOf<K> & I
+    : PropsShape<SlotMap[K]>
+
+/**
+ * Registration-position component shape: the bare call signature, so the
+ * ComposedProps constraint checks through clean parameter contravariance
+ * (FC's propTypes/defaultProps statics add covariant noise that rejects
+ * legitimate narrowings of the bottom-typed standard share).
+ */
+export type SlotComponent<P> = (props: P) => ReactNode
+
+/** The stored component's props shape: the legacy full-props slot, or wide for composed entries. */
+export type PropsShape<E extends SlotEntryDef> =
+  E extends { props: infer P extends object } ? P : object
+
+/**
+ * Session-scoped assembly handle passed to inject factories (apply world
+ * only, never into props). `Ctx` defaults to unknown at this zero-dependency
+ * layer; runtime re-exports the ClientContext-narrowed alias.
+ */
+export interface SessionBinding<Ctx = unknown> {
+  readonly sessionId: string
+  readonly session: SessionAccess
+  readonly ctx: Ctx
+}
+
+/** Root-scoped assembly handle passed to inject factories. */
+export interface RootBinding<Ctx = unknown> { readonly ctx: Ctx }
+
+/** Session subscription surface; web-react narrows `useSelector` to the typed hook. */
+export interface SessionAccess { readonly useSelector: unknown }
+
+/**
+ * Factory producing the registrant's private injected props, called once per
+ * (entry x session) for session slots or per entry for root slots. `I` is the
+ * registrant's own injected share, inferred at the registration site. `Ctx`
+ * parameterizes the binding's context (default unknown keeps this layer
+ * dependency-free); runtime's narrowed binding aliases flow through here so
+ * factories written against a narrowed ctx type-check without a cast.
+ */
+export type InjectFactory<E extends SlotEntryDef, I extends object = Record<string, unknown>, Ctx = unknown> =
+  (b: E['scope'] extends 'session' ? SessionBinding<Ctx> : RootBinding<Ctx>) => I
+
+/** Runtime spec recorded at define time; must match the SlotMap declaration. */
+export interface SlotSpec<E extends SlotEntryDef> { kind: E['kind']; scope: E['scope'] }
+
+/**
+ * Registration options, shaped by the slot kind and the registrant's injected
+ * share `I`. `Ctx` flows through to the inject factory's binding parameter
+ * (narrowing wrappers fix it to their client context type).
+ */
+export type SlotOptions<E extends SlotEntryDef, I extends object = Record<string, unknown>, Ctx = unknown> =
+  E['kind'] extends 'keyed' ? { key: string; inject?: InjectFactory<E, I, Ctx> }
+    : E['kind'] extends 'list' ? { id: string; order?: number; label?: string; inject?: InjectFactory<E, I, Ctx> }
+      : { inject?: InjectFactory<E, I, Ctx> }
+
+/** register() trailing args: options are statically mandatory for keyed/list kinds (key/id live there). */
+export type RegisterArgs<E extends SlotEntryDef, I extends object = Record<string, unknown>, Ctx = unknown> =
+  E['kind'] extends 'keyed' | 'list' ? [options: SlotOptions<E, I, Ctx>] : [options?: SlotOptions<E, I, Ctx>]
+
+/** One registered contribution: the component plus its registration options. */
+export interface SlotEntry<E extends SlotEntryDef, I extends object = Record<string, unknown>> {
+  component: FC<PropsShape<E>>
+  options: SlotOptions<E, I>
+}
+
+/** Type-erased stored entry; public typing is restored at the entries() boundary. */
+interface StoredEntry {
+  component: unknown
+  options: { key?: string; id?: string; order?: number; label?: string; inject?: unknown }
+}
+
+/** Per-key registry record. Created on first define/subscribe/version read; never removed (version stays monotonic across redefines). */
+interface SlotRecord {
+  spec: SlotSpec<SlotEntryDef> | undefined
+  entries: readonly StoredEntry[]
+  version: number
+  listeners: Set<() => void>
+}
+
+const NO_ENTRIES: readonly StoredEntry[] = Object.freeze([])
+
+/**
+ * Pure slot registry (no cordis; event emission lives in the runtime Service
+ * wrapper via {@link SlotCore.onMutate}).
+ *
+ * Change propagation contract: versions bump and {@link SlotCore.onMutate}
+ * fires synchronously per mutation (registry state is consistent when they
+ * fire); {@link SlotCore.subscribe} notifications batch per microtask, so N
+ * same-tick mutations produce one notification per touched key.
+ */
+export class SlotCore {
+  private records = new Map<string, SlotRecord>()
+  private mutateListeners = new Set<(key: string) => void>()
+  // Dirty records, not keys: records are never removed, so holding the
+  // reference skips a lookup (and an unreachable missing-record branch) at flush.
+  private dirty = new Set<SlotRecord>()
+  private flushScheduled = false
+
+  /**
+   * Record a slot's runtime spec. Registering into an undefined key throws;
+   * defining an already-defined key throws (one owner per slot).
+   * @param key - SlotMap key.
+   * @param spec - kind/scope spec matching the declaration.
+   * @returns disposer removing the definition and its entries (idempotent; a
+   * stale disposer after redefine is a no-op).
+   */
+  define<K extends keyof SlotMap & string>(key: K, spec: SlotSpec<SlotMap[K]>): () => void {
+    const rec = this.record(key)
+    if (rec.spec) throw new Error(`slot "${String(key)}" is already defined`)
+    const recorded: SlotSpec<SlotEntryDef> = spec
+    rec.spec = recorded
+    this.markDirty(key, rec)
+    return () => {
+      if (rec.spec !== recorded) return
+      rec.spec = undefined
+      rec.entries = NO_ENTRIES
+      this.markDirty(key, rec)
+    }
+  }
+
+  /**
+   * Contribute a component to a defined slot. single: duplicate registration
+   * throws; keyed: missing or duplicate `options.key` throws; list: missing or
+   * duplicate `options.id` throws (duplicates would make `only`/`entryKey`
+   * dispatch ambiguous).
+   * @param key - SlotMap key.
+   * @param component - component honoring the entry's composed props contract (owner & standard & injected shares).
+   * @param args - kind-shaped registration options; statically mandatory for keyed/list (key/id live there).
+   * @returns disposer removing the registration (idempotent; a stale disposer
+   * after the slot's define disposer ran is a no-op).
+   */
+  register<K extends keyof SlotMap & string, I extends object = Record<string, unknown>, Ctx = unknown>(
+    // NoInfer pins I's inference to the inject factory: letting the component
+    // position drive I would absorb any props drift into the constraint.
+    // Ctx flows from the options' inject-factory parameter annotation
+    // (narrowing wrappers fix it; the core stays context-agnostic).
+    key: K, component: SlotComponent<ComposedProps<K, NoInfer<I>>>, ...args: RegisterArgs<SlotMap[K], I, Ctx>): () => void {
+    const rec = this.records.get(key)
+    if (!rec?.spec) throw new Error(`slot "${String(key)}" is not defined`)
+    const opts = (args[0] ?? {}) as StoredEntry['options']
+    // keyed/list options are statically mandatory (RegisterArgs); the runtime
+    // checks below stay for dynamically-composed callers.
+    switch (rec.spec.kind) {
+      case 'single':
+        if (rec.entries.length > 0) throw new Error(`single slot "${String(key)}" already has a registration`)
+        break
+      case 'keyed':
+        if (opts.key === undefined) throw new Error(`keyed slot "${String(key)}" requires options.key`)
+        if (rec.entries.some(e => e.options.key === opts.key)) {
+          throw new Error(`keyed slot "${String(key)}" already has an entry for key "${opts.key}"`)
+        }
+        break
+      case 'list':
+        if (opts.id === undefined) throw new Error(`list slot "${String(key)}" requires options.id`)
+        if (rec.entries.some(e => e.options.id === opts.id)) {
+          throw new Error(`list slot "${String(key)}" already has an entry with id "${opts.id}"`)
+        }
+        break
+    }
+    const entry: StoredEntry = { component, options: opts }
+    const next = [...rec.entries, entry]
+    // Stable sort: order ascending, ties keep registration sequence.
+    if (rec.spec.kind === 'list') next.sort((a, b) => (a.options.order ?? 0) - (b.options.order ?? 0))
+    rec.entries = next
+    this.markDirty(key, rec)
+    return () => {
+      if (!rec.entries.includes(entry)) return
+      rec.entries = rec.entries.filter(e => e !== entry)
+      this.markDirty(key, rec)
+    }
+  }
+
+  /**
+   * Snapshot the registered entries for a key. Returns the cached array
+   * reference (stable between mutations — safe as a uSES getSnapshot source);
+   * empty for keys not (or no longer) defined, so renderers may probe ahead of
+   * plugin load order.
+   * @param key - SlotMap key.
+   * @returns entries in registration (list: order) sequence.
+   */
+  entries<K extends keyof SlotMap & string>(key: K): readonly SlotEntry<SlotMap[K]>[] {
+    return (this.records.get(key)?.entries ?? NO_ENTRIES) as unknown as readonly SlotEntry<SlotMap[K]>[]
+  }
+
+  /**
+   * Look up a slot's defined spec, narrowed by the SlotMap key.
+   * @param key - SlotMap key.
+   * @returns the spec, or undefined before define.
+   */
+  spec<K extends keyof SlotMap & string>(key: K): SlotSpec<SlotMap[K]> | undefined {
+    return this.records.get(key)?.spec as SlotSpec<SlotMap[K]> | undefined
+  }
+
+  /**
+   * Dynamic-key escape hatch for spec lookup — renderers resolving keys they
+   * only hold as strings (generic dispatch) use this wide form; statically
+   * keyed callers use {@link SlotCore.spec}.
+   * @param key - candidate slot key.
+   * @returns the wide-typed spec, or undefined before define.
+   */
+  specDynamic(key: string): SlotSpec<SlotEntryDef> | undefined {
+    return this.records.get(key)?.spec
+  }
+
+  /**
+   * Subscribe to registration changes for a key (microtask-batched).
+   * Subscribing ahead of define is allowed; the define itself notifies.
+   * @param key - SlotMap key.
+   * @param fn - change callback.
+   * @returns unsubscribe.
+   */
+  subscribe(key: keyof SlotMap & string, fn: () => void): () => void {
+    const rec = this.record(key)
+    rec.listeners.add(fn)
+    return () => { rec.listeners.delete(fn) }
+  }
+
+  /**
+   * Monotonic version for a key, bumped synchronously per mutation so a
+   * uSES getSnapshot read is never stale when its batched notification lands.
+   * @param key - SlotMap key.
+   * @returns current version (0 for untouched keys).
+   */
+  getVersion(key: keyof SlotMap & string): number {
+    return this.records.get(key)?.version ?? 0
+  }
+
+  /**
+   * Hook every mutation (the runtime Service wrapper bridges this to ctx.emit).
+   * Fires synchronously per mutation, unbatched — event semantics need one
+   * emission per change.
+   * @param fn - called with the mutated key.
+   * @returns unsubscribe.
+   */
+  onMutate(fn: (key: string) => void): () => void {
+    this.mutateListeners.add(fn)
+    return () => { this.mutateListeners.delete(fn) }
+  }
+
+  private record(key: string): SlotRecord {
+    let rec = this.records.get(key)
+    if (!rec) {
+      rec = { spec: undefined, entries: NO_ENTRIES, version: 0, listeners: new Set() }
+      this.records.set(key, rec)
+    }
+    return rec
+  }
+
+  private markDirty(key: string, rec: SlotRecord): void {
+    rec.version += 1
+    for (const fn of [...this.mutateListeners]) fn(key)
+    this.dirty.add(rec)
+    if (!this.flushScheduled) {
+      this.flushScheduled = true
+      queueMicrotask(() => { this.flush() })
+    }
+  }
+
+  private flush(): void {
+    // Reset before iterating so a mutation from inside a listener re-schedules.
+    this.flushScheduled = false
+    const dirty = [...this.dirty]
+    this.dirty.clear()
+    for (const rec of dirty) {
+      for (const fn of [...rec.listeners]) fn()
+    }
+  }
+}
+
+/**
+ * Whitelist-narrowed render surface handed to owner components via props
+ * (implementation lives in web-react's scopedSlots factory).
+ */
+export interface ScopedSlots<K extends keyof SlotMap & string> {
+  /**
+   * Render a slot's registered entries.
+   * @param key - whitelisted SlotMap key.
+   * @param props - owner-supplied share of the entry's props contract.
+   * @param opts - render options.
+   * @returns rendered node(s).
+   */
+  renderSlot: <Key extends K>(key: Key, props: OwnerOf<Key>, opts?: RenderOpts) => ReactNode
+  /**
+   * Phantom variance anchor (never materialized at runtime): generic method
+   * signatures compare loosely across differing key-union constraints, so
+   * this contravariant marker is what actually enforces "a surface is
+   * assignable only where its whitelist covers the target's keys".
+   */
+  readonly __accepts?: ((key: K) => void) | undefined
+}
+
+/** renderSlot options: keyed dispatch key, list filtering, empty fallback. */
+export interface RenderOpts { entryKey?: string; only?: string; fallback?: ReactNode }
+
+/**
+ * Narrow a slots surface to a subset whitelist for delegation to a child
+ * component (`K2` ⊆ `K1`). Pure type narrowing — ScopedSlots is covariant in
+ * its key union, so the same object is returned.
+ * @param slots - the owner's wider surface.
+ * @returns the same surface, typed to the subset.
+ */
+export function narrowSlots<K2 extends K1, K1 extends keyof SlotMap & string>(
+  slots: ScopedSlots<K1>): ScopedSlots<K2> {
+  return slots
+}
+
+/**
+ * The owner-supplied share of an entry's props. `useSession` is excluded (the
+ * framework injects it on session slots; owners must not shadow the bound
+ * hook). Registrant inject keys are per-registration and unknowable at the
+ * type level, so the remaining share stays Partial rather than exact.
+ */
+export type OwnerProps<E extends SlotEntryDef> =
+  E extends { props: infer P extends object } ? Partial<Omit<P, 'useSession'>> : object
diff --git a/packages/client/ui-slots/src/invariant.ts b/packages/client/ui-slots/src/invariant.ts
new file mode 100644
index 0000000000..de9ea2c511
--- /dev/null
+++ b/packages/client/ui-slots/src/invariant.ts
@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-slots`.
+ * @module @deepseek-ai/dsh-client-ui-slots/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-slots'
+
+/** Cordis companion plugin name. */
+export const name = 'client-ui-slots-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: a zero-dependency pure registry core — it emits no
+ * cordis events itself (the runtime SlotsService wrapper owns the event
+ * bridge and its invariants); define/register/dispose sequencing is asserted
+ * directly by this package's behavior specs.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/client/ui-slots/tests/core.spec.ts b/packages/client/ui-slots/tests/core.spec.ts
new file mode 100644
index 0000000000..690a0e9f08
--- /dev/null
+++ b/packages/client/ui-slots/tests/core.spec.ts
@@ -0,0 +1,209 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { FC } from 'react'
+import type { RootBinding, SessionBinding, SlotOptions } from '@deepseek-ai/dsh-client-ui-slots'
+import { SlotCore } from '@deepseek-ai/dsh-client-ui-slots'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    'test.single': { kind: 'single'; scope: 'root'; props: { label: string } }
+    'test.list': { kind: 'list'; scope: 'root'; props: { label: string } }
+    'test.keyed': { kind: 'keyed'; scope: 'session'; props: { label: string; useSession: unknown } }
+  }
+}
+
+const Comp: FC<{ label: string }> = () => null
+const SessionComp: FC<{ label: string; useSession: unknown }> = () => null
+
+const flushMicrotasks = () => new Promise<void>((resolve) => { queueMicrotask(resolve) })
+
+describe('SlotCore kind semantics', () => {
+  it('throws on register before define', () => {
+    const core = new SlotCore()
+    expect(() => core.register('test.single', Comp)).toThrow('not defined')
+  })
+
+  it('throws on duplicate define', () => {
+    const core = new SlotCore()
+    core.define('test.single', { kind: 'single', scope: 'root' })
+    expect(() => core.define('test.single', { kind: 'single', scope: 'root' })).toThrow('already defined')
+  })
+
+  it('single: second registration throws, disposer frees the seat', () => {
+    const core = new SlotCore()
+    core.define('test.single', { kind: 'single', scope: 'root' })
+    const dispose = core.register('test.single', Comp)
+    expect(() => core.register('test.single', Comp)).toThrow('already has a registration')
+    dispose()
+    expect(core.entries('test.single')).toHaveLength(0)
+    expect(() => core.register('test.single', Comp)).not.toThrow()
+  })
+
+  it('keyed: duplicate key throws, missing key throws', () => {
+    const core = new SlotCore()
+    core.define('test.keyed', { kind: 'keyed', scope: 'session' })
+    core.register('test.keyed', SessionComp, { key: 'a' })
+    expect(() => core.register('test.keyed', SessionComp, { key: 'a' })).toThrow('key "a"')
+    // Statically rejected since RegisterArgs made keyed options mandatory;
+    // the runtime guard stays for dynamically-composed callers.
+    // @ts-expect-error keyed registration requires options
+    expect(() => core.register('test.keyed', SessionComp)).toThrow('requires options.key')
+    expect(() => core.register('test.keyed', SessionComp, { key: 'b' })).not.toThrow()
+  })
+
+  it('list: duplicate id throws, missing id throws, entries sort by order stably', () => {
+    const core = new SlotCore()
+    core.define('test.list', { kind: 'list', scope: 'root' })
+    core.register('test.list', Comp, { id: 'c', order: 10 })
+    core.register('test.list', Comp, { id: 'a' })
+    core.register('test.list', Comp, { id: 'b' })
+    expect(() => core.register('test.list', Comp, { id: 'a' })).toThrow('id "a"')
+    // @ts-expect-error list registration requires options (static since RegisterArgs)
+    expect(() => core.register('test.list', Comp)).toThrow('requires options.id')
+    const ids = core.entries('test.list').map(e => (e.options as { id: string }).id)
+    expect(ids).toEqual(['a', 'b', 'c'])
+  })
+
+  it('spec() exposes the definition; define disposer clears spec and entries', () => {
+    const core = new SlotCore()
+    const dispose = core.define('test.single', { kind: 'single', scope: 'root' })
+    core.register('test.single', Comp)
+    expect(core.spec('test.single')).toEqual({ kind: 'single', scope: 'root' })
+    dispose()
+    expect(core.spec('test.single')).toBeUndefined()
+    expect(core.entries('test.single')).toHaveLength(0)
+    expect(() => core.register('test.single', Comp)).toThrow('not defined')
+  })
+
+  it('disposers are idempotent and stale disposers after redefine are no-ops', () => {
+    const core = new SlotCore()
+    const disposeDef = core.define('test.single', { kind: 'single', scope: 'root' })
+    const disposeReg = core.register('test.single', Comp)
+    disposeReg()
+    disposeReg()
+    disposeDef()
+    disposeDef()
+    core.define('test.single', { kind: 'single', scope: 'root' })
+    core.register('test.single', Comp)
+    disposeDef()
+    disposeReg()
+    expect(core.spec('test.single')).toBeDefined()
+    expect(core.entries('test.single')).toHaveLength(1)
+  })
+})
+
+describe('SlotCore subscription surface', () => {
+  it('entries() returns a stable cached reference between mutations', () => {
+    const core = new SlotCore()
+    core.define('test.list', { kind: 'list', scope: 'root' })
+    core.register('test.list', Comp, { id: 'a' })
+    const first = core.entries('test.list')
+    expect(core.entries('test.list')).toBe(first)
+    core.register('test.list', Comp, { id: 'b' })
+    expect(core.entries('test.list')).not.toBe(first)
+  })
+
+  it('bumps version synchronously but batches notifications per microtask', async () => {
+    const core = new SlotCore()
+    const fn = vi.fn()
+    core.subscribe('test.list', fn)
+    core.define('test.list', { kind: 'list', scope: 'root' })
+    core.register('test.list', Comp, { id: 'a' })
+    core.register('test.list', Comp, { id: 'b' })
+    expect(core.getVersion('test.list')).toBe(3)
+    expect(fn).not.toHaveBeenCalled()
+    await flushMicrotasks()
+    expect(fn).toHaveBeenCalledTimes(1)
+    core.register('test.list', Comp, { id: 'c' })
+    await flushMicrotasks()
+    expect(fn).toHaveBeenCalledTimes(2)
+  })
+
+  it('notifies only subscribers of the touched key; unsubscribe stops delivery', async () => {
+    const core = new SlotCore()
+    const single = vi.fn()
+    const list = vi.fn()
+    core.subscribe('test.single', single)
+    const unsubscribe = core.subscribe('test.list', list)
+    core.define('test.single', { kind: 'single', scope: 'root' })
+    await flushMicrotasks()
+    expect(single).toHaveBeenCalledTimes(1)
+    expect(list).not.toHaveBeenCalled()
+    unsubscribe()
+    core.define('test.list', { kind: 'list', scope: 'root' })
+    await flushMicrotasks()
+    expect(list).not.toHaveBeenCalled()
+  })
+
+  it('a mutation from inside a flush re-schedules instead of being lost', async () => {
+    const core = new SlotCore()
+    core.define('test.list', { kind: 'list', scope: 'root' })
+    const seen: number[] = []
+    let reentered = false
+    core.subscribe('test.list', () => {
+      seen.push(core.getVersion('test.list'))
+      if (!reentered) {
+        reentered = true
+        core.register('test.list', Comp, { id: 'reentrant' })
+      }
+    })
+    core.register('test.list', Comp, { id: 'a' })
+    await flushMicrotasks()
+    await flushMicrotasks()
+    expect(seen).toHaveLength(2)
+    expect(core.entries('test.list')).toHaveLength(2)
+  })
+
+  it('getVersion is 0 for untouched keys and monotonic across redefine', () => {
+    const core = new SlotCore()
+    expect(core.getVersion('test.single')).toBe(0)
+    const dispose = core.define('test.single', { kind: 'single', scope: 'root' })
+    dispose()
+    const after = core.getVersion('test.single')
+    core.define('test.single', { kind: 'single', scope: 'root' })
+    expect(core.getVersion('test.single')).toBeGreaterThan(after)
+  })
+
+  it('onMutate fires synchronously per mutation with the touched key', () => {
+    const core = new SlotCore()
+    const keys: string[] = []
+    const off = core.onMutate(key => keys.push(key))
+    core.define('test.single', { kind: 'single', scope: 'root' })
+    core.define('test.list', { kind: 'list', scope: 'root' })
+    core.register('test.list', Comp, { id: 'a' })
+    expect(keys).toEqual(['test.single', 'test.list', 'test.list'])
+    off()
+    core.register('test.list', Comp, { id: 'b' })
+    expect(keys).toHaveLength(3)
+  })
+})
+
+describe('SlotOptions typing', () => {
+  it('rejects kind-mismatched options and scope-mismatched inject bindings', () => {
+    // Compile-time negatives only: the body never runs (some rejected shapes
+    // would be legal at runtime, which validates kinds, not props).
+    const typeNegatives = (core: SlotCore) => {
+      // @ts-expect-error single options take no key
+      core.register('test.single', Comp, { key: 'x' })
+      // @ts-expect-error list options require id
+      core.register('test.list', Comp, { order: 1 })
+      // @ts-expect-error keyed options require key
+      core.register('test.keyed', SessionComp, { inject: () => ({}) })
+      // @ts-expect-error component props must match the SlotMap contract
+      core.register('test.single', SessionComp)
+      // @ts-expect-error kind must match the SlotMap declaration
+      core.define('test.single', { kind: 'list', scope: 'root' })
+      const rootInject: SlotOptions<{ kind: 'single'; scope: 'root'; props: { label: string } }> = {
+        // @ts-expect-error root slots bind RootBinding, which has no sessionId
+        inject: (b: RootBinding) => ({ sessionId: b.sessionId }),
+      }
+      return rootInject
+    }
+    expect(typeNegatives).toBeTypeOf('function')
+
+    const sessionInject: SlotOptions<{ kind: 'keyed'; scope: 'session'; props: { label: string } }> = {
+      key: 'k',
+      inject: (b: SessionBinding) => ({ sessionId: b.sessionId }),
+    }
+    expect(sessionInject.key).toBe('k')
+  })
+})
diff --git a/packages/client/ui-slots/tests/invariant.spec.ts b/packages/client/ui-slots/tests/invariant.spec.ts
new file mode 100644
index 0000000000..3b5740924f
--- /dev/null
+++ b/packages/client/ui-slots/tests/invariant.spec.ts
@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import * as SlotsInvariant from '@deepseek-ai/dsh-client-ui-slots/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+describe('invariant companion', () => {
+  it('registers under the package name with an empty installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    await expect(ctx.plugin(SlotsInvariant).await()).resolves.toBeDefined()
+  })
+})
diff --git a/packages/client/ui-slots/tests/surface.spec.ts b/packages/client/ui-slots/tests/surface.spec.ts
new file mode 100644
index 0000000000..2c6bd9c4b5
--- /dev/null
+++ b/packages/client/ui-slots/tests/surface.spec.ts
@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest'
+import type { FC } from 'react'
+import type { ScopedSlots } from '@deepseek-ai/dsh-client-ui-slots'
+import { narrowSlots, SlotCore } from '@deepseek-ai/dsh-client-ui-slots'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    'surface.a': { kind: 'single'; scope: 'root'; props: { label: string } }
+    'surface.b': { kind: 'single'; scope: 'root'; props: { label: string } }
+  }
+}
+
+const Comp: FC<{ label: string }> = () => null
+
+describe('dynamic-key escape hatch', () => {
+  it('specDynamic reads wide-typed specs for string keys; undefined before define', () => {
+    const core = new SlotCore()
+    expect(core.specDynamic('surface.a')).toBeUndefined()
+    core.define('surface.a', { kind: 'single', scope: 'root' })
+    expect(core.specDynamic('surface.a')).toEqual({ kind: 'single', scope: 'root' })
+    expect(core.specDynamic('never.defined')).toBeUndefined()
+  })
+
+  it('entries/getVersion on an untouched key return the frozen empty array and 0', () => {
+    const core = new SlotCore()
+    expect(core.entries('surface.b')).toHaveLength(0)
+    expect(core.entries('surface.b')).toBe(core.entries('surface.b'))
+    expect(core.getVersion('surface.b')).toBe(0)
+  })
+})
+
+describe('narrowSlots', () => {
+  it('returns the same surface narrowed to the subset whitelist', () => {
+    const wide: ScopedSlots<'surface.a' | 'surface.b'> = { renderSlot: () => null }
+    const narrow = narrowSlots<'surface.a', 'surface.a' | 'surface.b'>(wide)
+    expect(narrow).toBe(wide)
+    const rejects = (s: ScopedSlots<'surface.a'>) => {
+      // @ts-expect-error 'surface.b' is outside the narrowed whitelist
+      return () => s.renderSlot('surface.b', {})
+    }
+    expect(rejects(narrow)).toBeTypeOf('function')
+  })
+})
+
+describe('registration typing', () => {
+  it('keyed/list registrations statically require options (runtime guard retained)', () => {
+    const core = new SlotCore()
+    core.define('surface.a', { kind: 'single', scope: 'root' })
+    // single: options omissible.
+    expect(() => core.register('surface.a', Comp)).not.toThrow()
+  })
+})
diff --git a/packages/client/ui-slots/tests/type-chain.spec.tsx b/packages/client/ui-slots/tests/type-chain.spec.tsx
new file mode 100644
index 0000000000..ef05d3b46f
--- /dev/null
+++ b/packages/client/ui-slots/tests/type-chain.spec.tsx
@@ -0,0 +1,140 @@
+// Slot type-chain negative samples (design.md §9 item 2) plus the slots-ring
+// full-chain positive: register→inject→render composed under the ownership
+// rule (owner share referenced, injected share locally declared).
+import { describe, expect, it } from 'vitest'
+import type { FC, ReactNode } from 'react'
+import type {
+  OwnerOf, RootBinding, ScopedSlots, SessionBinding, SlotMap, SlotOptions,
+} from '@deepseek-ai/dsh-client-ui-slots'
+import { SlotCore } from '@deepseek-ai/dsh-client-ui-slots'
+
+/** Owner share as the slot-owning package's contract would export it. */
+interface ChainOwnerShare { sessionId: string }
+/** Registrant's own injected share (locally declared — ownership rule). */
+interface ChainInjected { useThing: () => number; actions: { open: () => void } }
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    'chain.session': { kind: 'single'; scope: 'session'; props: ChainSessionProps; owner: ChainOwnerShare }
+    'chain.root': { kind: 'single'; scope: 'root'; props: ChainRootProps; owner: object }
+    'chain.keyed': { kind: 'keyed'; scope: 'root'; props: ChainRootProps; owner: object }
+  }
+}
+
+/** Full props = owner share (referenced) + standard share + own injected. */
+type ChainSessionProps = ChainOwnerShare & { useSession: unknown } & ChainInjected
+type ChainRootProps = ChainInjected
+
+const SessionComp: FC<ChainSessionProps> = () => null
+const RootComp: FC<ChainRootProps> = () => null
+
+describe('type-chain negatives (compile-time; bodies never run)', () => {
+  it('holds the six negative samples as expect-error sites', () => {
+    const negatives = (core: SlotCore, slots: ScopedSlots<'chain.session'>) => {
+      // 1. Owner passing a registrant-injected key through renderSlot.
+      //    OwnerOf<'chain.session'> = ChainOwnerShare — useThing is not in it.
+      slots.renderSlot('chain.session', {
+        sessionId: 's1',
+        // @ts-expect-error injected keys are not owner-suppliable
+        useThing: () => 1,
+      })
+      // 2. Inject factory returning a share that mismatches the registrant's
+      //    declared own-injected slice (missing `actions`). The I-typed
+      //    options form is where the mismatch surfaces (the full composed
+      //    register constraint lands with the phase-2 consumer migration).
+      const mismatched: SlotOptions<SlotMap['chain.session'], ChainInjected> = {
+        // @ts-expect-error inject must supply the full registrant share
+        inject: () => ({ useThing: () => 1 }),
+      }
+      void mismatched
+      // 3. renderSlot on a key outside the whitelist.
+      // @ts-expect-error 'chain.root' is not whitelisted on this surface
+      slots.renderSlot('chain.root', {})
+      // 4. keyed registration without options.
+      // @ts-expect-error keyed kind requires options (RegisterArgs)
+      core.register('chain.keyed', RootComp)
+      // 5. Session-slot inject factory typed against RootBinding's surface.
+      const sessionOpts: SlotOptions<{ kind: 'single'; scope: 'session'; props: ChainSessionProps }, ChainInjected> = {
+        // @ts-expect-error session binding has sessionId; RootBinding-only factories don't type-check
+        inject: (b: RootBinding & { notSession: true }) => ({ useThing: () => 1, actions: { open: () => {} } }),
+      }
+      void sessionOpts
+      // 6. Hand-copied owner share drifting from the contract (wrong value type)
+      //    — the composed-reference version right below compiles instead.
+      interface DriftedProps { sessionId: number }
+      const Drifted: FC<DriftedProps & ChainInjected> = () => null
+      // @ts-expect-error drifted hand-copy of the owner share fails at register
+      core.register('chain.session', Drifted)
+      return null as ReactNode
+    }
+    expect(negatives).toBeTypeOf('function')
+  })
+
+  it('full chain (positive dual): composed props register, inject, and render cleanly', () => {
+    const core = new SlotCore()
+    core.define('chain.session', { kind: 'single', scope: 'session' })
+    const dispose = core.register('chain.session', SessionComp, {
+      inject: (b: SessionBinding): ChainInjected => ({
+        useThing: () => b.sessionId.length,
+        actions: { open: () => {} },
+      }),
+    })
+    const entry = core.entries('chain.session')[0]!
+    // Storage erasure boundary: entries() returns the default-I view; the
+    // registrant share is restored after read-back (the budgeted cast).
+    const injected = (entry.options.inject as unknown as (b: SessionBinding) => ChainInjected)(
+      { sessionId: 's1', session: { useSelector: undefined }, ctx: undefined })
+    expect(injected.useThing()).toBe(2)
+    // Owner share stays reference-typed at the render surface.
+    const ownerShare: OwnerOf<'chain.session'> = { sessionId: 's1' }
+    expect(ownerShare.sessionId).toBe('s1')
+    dispose()
+    expect(core.entries('chain.session')).toHaveLength(0)
+  })
+})
+
+// ── children validation layer (B-b, opt-in per entry) ───────────────────────
+
+/** Delegating owner share: entry declares children, component carries a slots face. */
+interface DelegOwnerShare { sessionId: string }
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    'chain.deleg': { kind: 'single'; scope: 'root'; props: object; owner: DelegOwnerShare; children: 'chain.child-a' | 'chain.child-b' }
+    'chain.child-a': { kind: 'single'; scope: 'root'; props: object; owner: object }
+    'chain.child-b': { kind: 'single'; scope: 'root'; props: object; owner: object }
+    'chain.outside': { kind: 'single'; scope: 'root'; props: object; owner: object }
+  }
+}
+
+describe('children validation layer (compile-time; bodies never run)', () => {
+  it('accepts whitelists inside the authorized union, rejects outside keys', () => {
+    const cases = (core: SlotCore) => {
+      // Positive: slots face ⊆ children union (a strict subset is fine).
+      const InUnion: FC<DelegOwnerShare & { slots: ScopedSlots<'chain.child-a'> }> = () => null
+      core.register('chain.deleg', InUnion)
+      // Positive: the full authorized union.
+      const FullUnion: FC<DelegOwnerShare & { slots: ScopedSlots<'chain.child-a' | 'chain.child-b'> }> = () => null
+      core.register('chain.deleg', FullUnion)
+      // Positive: no slots face at all — delegation is optional.
+      const NoSlots: FC<DelegOwnerShare> = () => null
+      core.register('chain.deleg', NoSlots)
+      // Negative: a key outside the authorized union collapses the slots constraint.
+      const Outside: FC<DelegOwnerShare & { slots: ScopedSlots<'chain.outside'> }> = () => null
+      // @ts-expect-error slots whitelist must stay inside the entry's children union
+      core.register('chain.deleg', Outside)
+      // Negative: smuggling an extra key alongside authorized ones still fails.
+      const Mixed: FC<DelegOwnerShare & { slots: ScopedSlots<'chain.child-a' | 'chain.outside'> }> = () => null
+      // @ts-expect-error a partially-authorized whitelist is still out of union
+      core.register('chain.deleg', Mixed)
+      // Entries WITHOUT children stay unchecked: any slots face registers
+      // freely (I inferred from the inject factory as usual).
+      const FreeFace: FC<ChainOwnerShare & { useSession: unknown } & ChainInjected & { slots: ScopedSlots<'chain.outside'> }> = () => null
+      core.register('chain.session', FreeFace, {
+        inject: (): ChainInjected & { slots: ScopedSlots<'chain.outside'> } =>
+          ({ useThing: () => 1, actions: { open: () => {} }, slots: { renderSlot: () => null } }),
+      })
+    }
+    expect(cases).toBeTypeOf('function')
+  })
+})
diff --git a/packages/client/ui-slots/tsconfig.json b/packages/client/ui-slots/tsconfig.json
new file mode 100644
index 0000000000..fc829c7a83
--- /dev/null
+++ b/packages/client/ui-slots/tsconfig.json
@@ -0,0 +1,21 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "lib": [
+      "ES2024",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": []
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/client/ui-theme/README.md b/packages/client/ui-theme/README.md
new file mode 100644
index 0000000000..2ce5d9b9e6
--- /dev/null
+++ b/packages/client/ui-theme/README.md
@@ -0,0 +1,17 @@
+# @deepseek-ai/dsh-client-ui-theme
+
+Theme plugin: ThemeService over the --dsw-* token base stylesheets (static scale + alias semantic layers); apply(id) toggles the `body[data-ds-dark-theme]` attribute, so theme switches are pure CSS cascade. Contract: api-contracts v3 §8.
+
+## Model Experience
+
+None, as the theme service toggles browser CSS; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **No theme-switch control ships in P-I** — the service surface (register/apply/current) is complete but no UI owner mounts a toggle; switching happens programmatically.
+- **Third-party themes are a surface, not a product** — registering one means overriding same-named alias variables; no validation exists that an override set is complete.
+- **The token sheets are the sole color authority** — values absent from cssdesign (for example the design's #4176E6 tab blue) are deliberately not appended; the nearest semantic token wins (arbitrated 2026-07-22).
diff --git a/packages/client/ui-theme/package.json b/packages/client/ui-theme/package.json
new file mode 100644
index 0000000000..fbad2194c3
--- /dev/null
+++ b/packages/client/ui-theme/package.json
@@ -0,0 +1,52 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-theme",
+  "description": "Theme plugin: ThemeService (apply = toggle body[data-ds-dark-theme]), --dsw-* token base stylesheets",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./styles/*": "./src/styles/*",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [],
+    "platform": "web",
+    "immediately": true
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}
diff --git a/packages/client/ui-theme/src/client/index.ts b/packages/client/ui-theme/src/client/index.ts
new file mode 100644
index 0000000000..5b2fc5be20
--- /dev/null
+++ b/packages/client/ui-theme/src/client/index.ts
@@ -0,0 +1,85 @@
+/**
+ * Theme plugin, browser half: ThemeService over the --dsw-* token base
+ * stylesheets in src/styles/ (the sole token source; components must not
+ * hardcode colors). apply(id) toggles body[data-ds-dark-theme] — theming is
+ * CSS cascade, zero React renders. Contract: api-contracts v3 section 8.
+ * The base stylesheets ship separately (the web shell imports them as base
+ * CSS); this plugin only owns the registry and the body-attribute switch.
+ */
+import type { Context } from 'cordis'
+
+/** Theme token dictionary: --dsw-alias-* overrides keyed by variable name. */
+export type ThemeTokens = Record<string, string>
+
+declare module 'cordis' {
+  interface Context {
+    theme: ThemeService
+  }
+}
+
+/**
+ * Theme registry and switcher. `light`/`dark` are built in (the base
+ * stylesheets carry both palettes; the dark palette activates via the
+ * body[data-ds-dark-theme] attribute). Third-party themes register alias-layer
+ * overrides applied as inline CSS variables on body, cascading over whichever
+ * base palette the attribute selects.
+ */
+export class ThemeService {
+  private themes = new Map<string, ThemeTokens>([['light', {}], ['dark', {}]])
+  private appliedTokens: ThemeTokens = {}
+  private active = 'light'
+
+  /**
+   * Register a theme. Duplicate id throws (single occupant per id; the
+   * built-in pair counts).
+   * @param id - theme id.
+   * @param tokens - alias-layer overrides (variable name to value).
+   * @returns disposer. Disposing the active theme reverts to `light` so the
+   * UI never keeps tokens of an unregistered theme.
+   */
+  register(id: string, tokens: ThemeTokens): () => void {
+    if (this.themes.has(id)) throw new Error(`theme "${id}" is already registered`)
+    this.themes.set(id, tokens)
+    return () => {
+      if (!this.themes.delete(id)) return
+      if (this.active === id) this.apply('light')
+    }
+  }
+
+  /**
+   * Activate a theme: toggle body[data-ds-dark-theme] (set only for `dark`)
+   * and swap the previous theme's inline token overrides for this one's.
+   * Unregistered id throws.
+   * @param id - registered theme id.
+   */
+  apply(id: string): void {
+    const tokens = this.themes.get(id)
+    if (!tokens) throw new Error(`theme "${id}" is not registered`)
+    const body = document.body
+    for (const name of Object.keys(this.appliedTokens)) body.style.removeProperty(name)
+    if (id === 'dark') body.setAttribute('data-ds-dark-theme', '')
+    else body.removeAttribute('data-ds-dark-theme')
+    for (const [name, value] of Object.entries(tokens)) body.style.setProperty(name, value)
+    this.appliedTokens = tokens
+    this.active = id
+  }
+
+  /**
+   * Report the active theme id (initially `light`).
+   * @returns the active theme id.
+   */
+  current(): string {
+    return this.active
+  }
+}
+
+/** Required services (none; the loader passes the export surface as an object plugin). */
+export const inject: string[] = []
+
+/**
+ * Client plugin body: provide the theme service.
+ * @param ctx - client cordis context.
+ */
+export function apply(ctx: Context): void {
+  ctx.provide('theme', new ThemeService())
+}
diff --git a/packages/client/ui-theme/src/index.ts b/packages/client/ui-theme/src/index.ts
new file mode 100644
index 0000000000..396c047cd3
--- /dev/null
+++ b/packages/client/ui-theme/src/index.ts
@@ -0,0 +1,11 @@
+/**
+ * Theme plugin, node half. Pure UI plugin: the empty apply exists so the
+ * plugin appears in the host cordis.yml / Loader (load and lifecycle follow
+ * the host; the browser half ships via exports["./client"], discovered
+ * through the package.json dshClient declaration). ThemeService and its
+ * types live in the client half; consumers import the /client subpath.
+ * Contract: api-contracts v3 section 8.
+ */
+
+/** Host plugin body — no host-side behavior for the theme plugin. */
+export function apply(): void {}
diff --git a/packages/client/ui-theme/src/invariant.ts b/packages/client/ui-theme/src/invariant.ts
new file mode 100644
index 0000000000..292304cbaf
--- /dev/null
+++ b/packages/client/ui-theme/src/invariant.ts
@@ -0,0 +1,31 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-theme`.
+ * @module @deepseek-ai/dsh-client-ui-theme/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-theme'
+
+/** Cordis companion plugin name. */
+export const name = 'client-ui-theme-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: a token-sheet registry whose apply() flips one body
+ * attribute — it emits no cordis events; registration/apply/current behavior
+ * is asserted directly by this package's behavior specs.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/client/ui-theme/src/styles/base.css b/packages/client/ui-theme/src/styles/base.css
new file mode 100644
index 0000000000..7fa58107d2
--- /dev/null
+++ b/packages/client/ui-theme/src/styles/base.css
@@ -0,0 +1,10 @@
+/* Base font-family variables referenced by the token sheets but defined
+ * upstream (deepsuite theme/global.css) — supplied here so the composite
+ * --dsw-font-* variables resolve. Code stack deliberately omits a bare
+ * `monospace` tail (Windows CJK falls back to SimSun otherwise). */
+:root {
+  --dsw-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC',
+    'Hiragino Sans GB', 'Microsoft YaHei', 'Helvetica Neue', Helvetica, Arial, sans-serif;
+  --ds-font-family-code: 'SF Mono', 'JetBrains Mono', 'Fira Code', Consolas,
+    'Liberation Mono', Menlo, Courier, 'PingFang SC', 'Microsoft YaHei';
+}
diff --git a/packages/client/ui-theme/src/styles/design-platform.css b/packages/client/ui-theme/src/styles/design-platform.css
new file mode 100644
index 0000000000..96408ce4b9
--- /dev/null
+++ b/packages/client/ui-theme/src/styles/design-platform.css
@@ -0,0 +1,326 @@
+body {
+  --dsw-static-amber-100: rgb(254, 245, 231);
+  --dsw-static-amber-400: rgb(247, 173, 49);
+  --dsw-static-amber-500: rgb(245, 158, 11);
+  --dsw-static-amber-600: rgb(221, 134, 41);
+  --dsw-static-amber-900: rgb(39, 36, 31);
+  --dsw-static-blue-100: rgb(219, 234, 254);
+  --dsw-static-blue-300: rgb(147, 197, 253);
+  --dsw-static-blue-400: rgb(96, 165, 250);
+  --dsw-static-blue-450: rgb(77, 147, 248);
+  --dsw-static-blue-500: rgb(59, 130, 246);
+  --dsw-static-blue-50: rgb(239, 246, 255);
+  --dsw-static-blue-50p: rgb(234, 243, 255);
+  --dsw-static-blue-600: rgb(37, 99, 235);
+  --dsw-static-blue-75: rgb(229, 240, 255);
+  --dsw-static-blue-800: rgb(30, 64, 175);
+  --dsw-static-blue-950: rgb(23, 37, 84);
+  --dsw-static-deepseek-100: rgb(228, 237, 253);
+  --dsw-static-deepseek-200: rgb(211, 226, 255);
+  --dsw-static-deepseek-300: rgb(183, 200, 254);
+  --dsw-static-deepseek-400: rgb(103, 158, 254);
+  --dsw-static-deepseek-450: rgb(86, 134, 254);
+  --dsw-static-deepseek-500: rgb(57, 100, 254);
+  --dsw-static-deepseek-50: rgb(237, 243, 254);
+  --dsw-static-deepseek-600: rgb(72, 104, 178);
+  --dsw-static-deepseek-700-delete: rgb(47, 76, 143);
+  --dsw-static-deepseek-800: rgb(52, 65, 91);
+  --dsw-static-deepseek-900: rgb(40, 49, 66);
+  --dsw-static-green-100: rgb(230, 250, 237);
+  --dsw-static-green-400: rgb(78, 209, 126);
+  --dsw-static-green-500: rgb(34, 197, 94);
+  --dsw-static-green-900: rgb(35, 60, 44);
+  --dsw-static-neutral-00: rgb(255, 255, 255);
+  --dsw-static-neutral-1000: rgb(0, 0, 0);
+  --dsw-static-neutral-100: rgb(245, 245, 245);
+  --dsw-static-neutral-150: rgb(237, 237, 237);
+  --dsw-static-neutral-200: rgb(229, 229, 229);
+  --dsw-static-neutral-250: rgb(220, 220, 220);
+  --dsw-static-neutral-300: rgb(212, 212, 212);
+  --dsw-static-neutral-400: rgb(162, 164, 166);
+  --dsw-static-neutral-500: rgb(127, 130, 135);
+  --dsw-static-neutral-50: rgb(250, 250, 250);
+  --dsw-static-neutral-550: rgb(101, 103, 107);
+  --dsw-static-neutral-600: rgb(84, 85, 87);
+  --dsw-static-neutral-700: rgb(60, 60, 61);
+  --dsw-static-neutral-800: rgb(41, 41, 41);
+  --dsw-static-neutral-850: rgb(33, 33, 35);
+  --dsw-static-neutral-900: rgb(15, 15, 15);
+  --dsw-static-neutral-bluish-00: rgb(255, 255, 255);
+  --dsw-static-neutral-bluish-1000: rgb(15, 17, 21);
+  --dsw-static-neutral-bluish-100: rgb(235, 238, 242);
+  --dsw-static-neutral-bluish-150: rgb(233, 236, 242);
+  --dsw-static-neutral-bluish-200: rgb(225, 229, 238);
+  --dsw-static-neutral-bluish-300: rgb(207, 211, 214);
+  --dsw-static-neutral-bluish-400: rgb(173, 178, 184);
+  --dsw-static-neutral-bluish-500: rgb(151, 157, 166);
+  --dsw-static-neutral-bluish-50: rgb(249, 250, 251);
+  --dsw-static-neutral-bluish-600: rgb(129, 133, 140);
+  --dsw-static-neutral-bluish-60: rgb(245, 246, 247);
+  --dsw-static-neutral-bluish-700: rgb(97, 102, 107);
+  --dsw-static-neutral-bluish-750: rgb(67, 69, 74);
+  --dsw-static-neutral-bluish-75: rgb(241, 243, 245);
+  --dsw-static-neutral-bluish-800: rgb(53, 54, 56);
+  --dsw-static-neutral-bluish-850: rgb(44, 44, 46);
+  --dsw-static-neutral-bluish-875: rgb(35, 35, 36);
+  --dsw-static-neutral-bluish-900: rgb(27, 27, 28);
+  --dsw-static-neutral-bluish-950: rgb(21, 21, 23);
+  --dsw-static-red-100: rgb(254, 226, 226);
+  --dsw-static-red-400: rgb(242, 90, 90);
+  --dsw-static-red-500: rgb(239, 68, 68);
+  --dsw-static-red-50: rgb(254, 242, 242);
+  --dsw-static-red-600: rgb(236, 19, 19);
+  --dsw-static-red-900: rgb(87, 12, 12);
+}
+
+body[data-ds-dark-theme] {
+  --dsw-static-amber-100: rgb(254, 245, 231);
+  --dsw-static-amber-400: rgb(247, 173, 49);
+  --dsw-static-amber-500: rgb(245, 158, 11);
+  --dsw-static-amber-600: rgb(221, 134, 41);
+  --dsw-static-amber-900: rgb(39, 36, 31);
+  --dsw-static-blue-100: rgb(219, 234, 254);
+  --dsw-static-blue-300: rgb(147, 197, 253);
+  --dsw-static-blue-400: rgb(96, 165, 250);
+  --dsw-static-blue-450: rgb(77, 147, 248);
+  --dsw-static-blue-500: rgb(59, 130, 246);
+  --dsw-static-blue-50: rgb(239, 246, 255);
+  --dsw-static-blue-50p: rgb(234, 243, 255);
+  --dsw-static-blue-600: rgb(37, 99, 235);
+  --dsw-static-blue-75: rgb(229, 240, 255);
+  --dsw-static-blue-800: rgb(30, 64, 175);
+  --dsw-static-blue-950: rgb(23, 37, 84);
+  --dsw-static-deepseek-100: rgb(228, 237, 253);
+  --dsw-static-deepseek-200: rgb(211, 226, 255);
+  --dsw-static-deepseek-300: rgb(183, 200, 254);
+  --dsw-static-deepseek-400: rgb(103, 158, 254);
+  --dsw-static-deepseek-450: rgb(86, 134, 254);
+  --dsw-static-deepseek-500: rgb(57, 100, 254);
+  --dsw-static-deepseek-50: rgb(237, 243, 254);
+  --dsw-static-deepseek-600: rgb(72, 104, 178);
+  --dsw-static-deepseek-700-delete: rgb(47, 76, 143);
+  --dsw-static-deepseek-800: rgb(52, 65, 91);
+  --dsw-static-deepseek-900: rgb(40, 49, 66);
+  --dsw-static-green-100: rgb(230, 250, 237);
+  --dsw-static-green-400: rgb(78, 209, 126);
+  --dsw-static-green-500: rgb(34, 197, 94);
+  --dsw-static-green-900: rgb(35, 60, 44);
+  --dsw-static-neutral-00: rgb(255, 255, 255);
+  --dsw-static-neutral-1000: rgb(0, 0, 0);
+  --dsw-static-neutral-100: rgb(245, 245, 245);
+  --dsw-static-neutral-150: rgb(237, 237, 237);
+  --dsw-static-neutral-200: rgb(229, 229, 229);
+  --dsw-static-neutral-250: rgb(220, 220, 220);
+  --dsw-static-neutral-300: rgb(212, 212, 212);
+  --dsw-static-neutral-400: rgb(162, 164, 166);
+  --dsw-static-neutral-500: rgb(127, 130, 135);
+  --dsw-static-neutral-50: rgb(250, 250, 250);
+  --dsw-static-neutral-550: rgb(101, 103, 107);
+  --dsw-static-neutral-600: rgb(84, 85, 87);
+  --dsw-static-neutral-700: rgb(60, 60, 61);
+  --dsw-static-neutral-800: rgb(41, 41, 41);
+  --dsw-static-neutral-850: rgb(33, 33, 35);
+  --dsw-static-neutral-900: rgb(15, 15, 15);
+  --dsw-static-neutral-bluish-00: rgb(255, 255, 255);
+  --dsw-static-neutral-bluish-1000: rgb(15, 17, 21);
+  --dsw-static-neutral-bluish-100: rgb(235, 238, 242);
+  --dsw-static-neutral-bluish-150: rgb(233, 236, 242);
+  --dsw-static-neutral-bluish-200: rgb(225, 229, 238);
+  --dsw-static-neutral-bluish-300: rgb(207, 211, 214);
+  --dsw-static-neutral-bluish-400: rgb(173, 178, 184);
+  --dsw-static-neutral-bluish-500: rgb(151, 157, 166);
+  --dsw-static-neutral-bluish-50: rgb(249, 250, 251);
+  --dsw-static-neutral-bluish-600: rgb(129, 133, 140);
+  --dsw-static-neutral-bluish-60: rgb(249, 250, 251);
+  --dsw-static-neutral-bluish-700: rgb(97, 102, 107);
+  --dsw-static-neutral-bluish-750: rgb(67, 69, 74);
+  --dsw-static-neutral-bluish-75: rgb(241, 243, 245);
+  --dsw-static-neutral-bluish-800: rgb(53, 54, 56);
+  --dsw-static-neutral-bluish-850: rgb(44, 44, 46);
+  --dsw-static-neutral-bluish-875: rgb(35, 35, 36);
+  --dsw-static-neutral-bluish-900: rgb(27, 27, 28);
+  --dsw-static-neutral-bluish-950: rgb(21, 21, 23);
+  --dsw-static-red-100: rgb(254, 226, 226);
+  --dsw-static-red-400: rgb(242, 90, 90);
+  --dsw-static-red-500: rgb(239, 68, 68);
+  --dsw-static-red-50: rgb(254, 242, 242);
+  --dsw-static-red-600: rgb(236, 19, 19);
+  --dsw-static-red-900: rgb(87, 12, 12);
+}
+
+body {
+  --dsw-alias-bg-base: var(--dsw-static-neutral-bluish-00);
+  --dsw-alias-bg-layer-1: var(--dsw-static-neutral-bluish-00);
+  --dsw-alias-bg-layer-2: var(--dsw-static-neutral-bluish-00);
+  --dsw-alias-bg-layer-3: var(--dsw-static-neutral-bluish-00);
+  --dsw-alias-bg-mask-1: rgba(0, 0, 0, 0.24);
+  --dsw-alias-bg-mask-2: rgba(0, 0, 0, 0.12);
+  --dsw-alias-bg-mask-3: rgba(0, 0, 0, 0.48);
+  --dsw-alias-bg-mask-photo: rgba(0, 0, 0, 0.88);
+  --dsw-alias-bg-module-platform: var(--dsw-static-neutral-bluish-60);
+  --dsw-alias-bg-multi-select: var(--dsw-static-neutral-bluish-60);
+  --dsw-alias-bg-overlay: var(--dsw-static-neutral-bluish-150);
+  --dsw-alias-bg-skeleton: rgba(0, 0, 0, 0.04);
+  --dsw-alias-border-inverted2: rgba(0, 0, 0, 0);
+  --dsw-alias-border-inverted: rgba(0, 0, 0, 0);
+  --dsw-alias-border-l1: rgba(0, 0, 0, 0.04);
+  --dsw-alias-border-l2-darkmode-thin: rgba(0, 0, 0, 0.1);
+  --dsw-alias-border-l2: rgba(0, 0, 0, 0.1);
+  --dsw-alias-border-l3: rgba(0, 0, 0, 0.12);
+  --dsw-alias-border-l4: rgba(0, 0, 0, 0.16);
+  --dsw-alias-brand-primary-invert: var(--dsw-static-neutral-bluish-1000);
+  --dsw-alias-brand-primary: var(--dsw-static-neutral-bluish-1000);
+  --dsw-alias-brand-text: var(--dsw-static-neutral-bluish-1000);
+  --dsw-alias-button-contrast-fill: var(--dsw-static-neutral-bluish-700);
+  --dsw-alias-button-elevated-fill: var(--dsw-static-neutral-bluish-00);
+  --dsw-alias-button-floating-fill: var(--dsw-static-neutral-bluish-00);
+  --dsw-alias-button-floating-hover: var(--dsw-static-neutral-bluish-75);
+  --dsw-alias-button-ghost-active-border: var(--dsw-static-neutral-bluish-500);
+  --dsw-alias-button-ghost-active-fill: var(--dsw-static-neutral-bluish-100);
+  --dsw-alias-button-ghost-active-hover: var(--dsw-static-neutral-bluish-150);
+  --dsw-alias-button-info-fill: var(--dsw-static-deepseek-500);
+  --dsw-alias-button-info-hover: var(--dsw-static-deepseek-400);
+  --dsw-alias-button-primary-dimmed: var(--dsw-static-neutral-bluish-100);
+  --dsw-alias-button-primary-fill: var(--dsw-alias-brand-primary);
+  --dsw-alias-button-primary-hover: var(--dsw-static-neutral-bluish-750);
+  --dsw-alias-button-tool-bar-fill-invisible: rgba(31, 31, 31, 0.36);
+  --dsw-alias-button-tool-bar-fill: rgba(84, 85, 87, 0.5);
+  --dsw-alias-button-tool-bar-hover: rgba(84, 85, 87, 0.6);
+  --dsw-alias-interactive-bg-active: rgba(38, 49, 72, 0.1);
+  --dsw-alias-interactive-bg-hover-accent: rgba(38, 49, 72, 0.14);
+  --dsw-alias-interactive-bg-hover-danger: rgba(236, 19, 19, 0.05);
+  --dsw-alias-interactive-bg-hover-solid: var(--dsw-static-neutral-bluish-75);
+  --dsw-alias-interactive-bg-hover: rgba(38, 49, 72, 0.06);
+  --dsw-alias-label-caption: var(--dsw-static-neutral-bluish-400);
+  --dsw-alias-label-dimmed: var(--dsw-static-neutral-bluish-200);
+  --dsw-alias-label-primary-dimmed: var(--dsw-static-neutral-bluish-950);
+  --dsw-alias-label-primary-foreground: var(--dsw-static-neutral-bluish-00);
+  --dsw-alias-label-primary-inverted: var(--dsw-static-neutral-bluish-00);
+  --dsw-alias-label-primary: var(--dsw-static-neutral-bluish-1000);
+  --dsw-alias-label-secondary: var(--dsw-static-neutral-bluish-700);
+  --dsw-alias-label-tertiary: var(--dsw-static-neutral-bluish-600);
+  --dsw-alias-markdown-citation: var(--dsw-static-neutral-bluish-100);
+  --dsw-alias-markdown-code-block-banner: var(--dsw-static-neutral-bluish-50);
+  --dsw-alias-markdown-code-block: var(--dsw-static-neutral-bluish-50);
+  --dsw-alias-markdown-code-segment-selected: var(--dsw-static-neutral-bluish-00);
+  --dsw-alias-markdown-code-segment-unselected: var(--dsw-static-neutral-bluish-75);
+  --dsw-alias-markdown-inline-code: var(--dsw-static-neutral-bluish-100);
+  --dsw-alias-markdown-placeholder: var(--dsw-static-neutral-bluish-60);
+  --dsw-alias-markdown-tag: var(--dsw-static-neutral-bluish-75);
+  --dsw-alias-scrollbar-bg-l1: var(--dsw-static-neutral-200);
+  --dsw-alias-scrollbar-bg-l2: var(--dsw-static-neutral-200);
+  --dsw-alias-scrollbar-hover-l1: var(--dsw-static-neutral-300);
+  --dsw-alias-scrollbar-hover-l2: var(--dsw-static-neutral-300);
+  --dsw-alias-state-business-primary: var(--dsw-static-deepseek-500);
+  --dsw-alias-state-business-tertiary: var(--dsw-static-deepseek-100);
+  --dsw-alias-state-error-primary: var(--dsw-static-red-600);
+  --dsw-alias-state-error-secondary: var(--dsw-static-red-400);
+  --dsw-alias-state-success-primary: var(--dsw-static-green-500);
+  --dsw-alias-state-success-secondary: var(--dsw-static-green-400);
+  --dsw-alias-state-warn-label: var(--dsw-static-amber-600);
+  --dsw-alias-state-warn-primary: var(--dsw-static-amber-500);
+  --dsw-alias-state-warn-secondary: var(--dsw-static-amber-400);
+  --dsw-alias-state-warn-tertiary: var(--dsw-static-amber-100);
+  --dsw-alias-toast-bg: var(--dsw-static-neutral-bluish-800);
+  --dsw-alias-tooltip-bg: var(--dsw-static-neutral-bluish-850);
+  --dsw-specific-bubble-highlight: var(--dsw-static-deepseek-200);
+  --dsw-specific-bubble: var(--dsw-static-deepseek-50);
+  --dsw-specific-input-major: var(--dsw-static-neutral-bluish-00);
+  --dsw-specific-login-input: var(--dsw-static-neutral-bluish-50);
+  --dsw-specific-menu: var(--dsw-alias-bg-layer-3);
+  --dsw-specific-selector: var(--dsw-static-neutral-bluish-60);
+  --dsw-specific-sidebar-fill: var(--dsw-static-neutral-bluish-50);
+  --dsw-specific-sidebar-nav-item-active-accent: var(--dsw-static-deepseek-100);
+  --dsw-specific-sidebar-nav-item-active: var(--dsw-static-neutral-bluish-100);
+  --dsw-specific-sidebar-nav-item-hover: var(--dsw-static-neutral-bluish-75);
+  --dsw-specific-tip: var(--dsw-static-neutral-bluish-60);
+}
+
+body[data-ds-dark-theme] {
+  --dsw-alias-bg-base: var(--dsw-static-neutral-bluish-950);
+  --dsw-alias-bg-layer-1: var(--dsw-static-neutral-bluish-875);
+  --dsw-alias-bg-layer-2: var(--dsw-static-neutral-bluish-850);
+  --dsw-alias-bg-layer-3: var(--dsw-static-neutral-bluish-800);
+  --dsw-alias-bg-mask-1: rgba(0, 0, 0, 0.5);
+  --dsw-alias-bg-mask-2: rgba(0, 0, 0, 0.2);
+  --dsw-alias-bg-mask-3: rgba(0, 0, 0, 0.48);
+  --dsw-alias-bg-mask-photo: rgba(0, 0, 0, 0.88);
+  --dsw-alias-bg-module-platform: var(--dsw-static-neutral-bluish-800);
+  --dsw-alias-bg-multi-select: var(--dsw-static-neutral-850);
+  --dsw-alias-bg-overlay: var(--dsw-static-neutral-bluish-700);
+  --dsw-alias-bg-skeleton: rgba(255, 255, 255, 0.08);
+  --dsw-alias-border-inverted2: rgba(255, 255, 255, 0.08);
+  --dsw-alias-border-inverted: rgba(255, 255, 255, 0.06);
+  --dsw-alias-border-l1: rgba(255, 255, 255, 0.06);
+  --dsw-alias-border-l2-darkmode-thin: rgba(255, 255, 255, 0.06);
+  --dsw-alias-border-l2: rgba(255, 255, 255, 0.12);
+  --dsw-alias-border-l3: rgba(255, 255, 255, 0.16);
+  --dsw-alias-border-l4: rgba(255, 255, 255, 0.2);
+  --dsw-alias-brand-primary-invert: var(--dsw-static-neutral-bluish-50);
+  --dsw-alias-brand-primary: var(--dsw-static-neutral-bluish-50);
+  --dsw-alias-brand-text: var(--dsw-static-neutral-bluish-50);
+  --dsw-alias-button-contrast-fill: var(--dsw-static-neutral-bluish-50);
+  --dsw-alias-button-elevated-fill: var(--dsw-static-neutral-bluish-750);
+  --dsw-alias-button-floating-fill: var(--dsw-static-neutral-bluish-950);
+  --dsw-alias-button-floating-hover: var(--dsw-static-neutral-bluish-800);
+  --dsw-alias-button-ghost-active-border: var(--dsw-static-neutral-bluish-600);
+  --dsw-alias-button-ghost-active-fill: var(--dsw-static-neutral-bluish-750);
+  --dsw-alias-button-ghost-active-hover: var(--dsw-static-neutral-bluish-700);
+  --dsw-alias-button-info-fill: var(--dsw-static-deepseek-400);
+  --dsw-alias-button-info-hover: var(--dsw-static-deepseek-500);
+  --dsw-alias-button-primary-dimmed: var(--dsw-static-neutral-bluish-750);
+  --dsw-alias-button-primary-fill: var(--dsw-alias-brand-primary);
+  --dsw-alias-button-primary-hover: var(--dsw-static-neutral-bluish-100);
+  --dsw-alias-button-tool-bar-fill-invisible: rgba(31, 31, 31, 0.36);
+  --dsw-alias-button-tool-bar-fill: rgba(84, 85, 87, 0.5);
+  --dsw-alias-button-tool-bar-hover: rgba(84, 85, 87, 0.6);
+  --dsw-alias-interactive-bg-active: rgba(255, 255, 255, 0.14);
+  --dsw-alias-interactive-bg-hover-accent: rgba(255, 255, 255, 0.24);
+  --dsw-alias-interactive-bg-hover-danger: rgba(242, 90, 90, 0.15);
+  --dsw-alias-interactive-bg-hover-solid: var(--dsw-static-neutral-bluish-800);
+  --dsw-alias-interactive-bg-hover: rgba(255, 255, 255, 0.08);
+  --dsw-alias-label-caption: var(--dsw-static-neutral-bluish-600);
+  --dsw-alias-label-dimmed: var(--dsw-static-neutral-bluish-750);
+  --dsw-alias-label-primary-dimmed: var(--dsw-static-neutral-bluish-100);
+  --dsw-alias-label-primary-foreground: var(--dsw-static-neutral-bluish-1000);
+  --dsw-alias-label-primary-inverted: var(--dsw-static-neutral-bluish-800);
+  --dsw-alias-label-primary: var(--dsw-static-neutral-bluish-50);
+  --dsw-alias-label-secondary: var(--dsw-static-neutral-bluish-300);
+  --dsw-alias-label-tertiary: var(--dsw-static-neutral-bluish-400);
+  --dsw-alias-markdown-citation: var(--dsw-static-neutral-bluish-800);
+  --dsw-alias-markdown-code-block-banner: var(--dsw-static-neutral-bluish-850);
+  --dsw-alias-markdown-code-block: var(--dsw-static-neutral-bluish-900);
+  --dsw-alias-markdown-code-segment-selected: var(--dsw-static-neutral-bluish-800);
+  --dsw-alias-markdown-code-segment-unselected: var(--dsw-static-neutral-bluish-900);
+  --dsw-alias-markdown-inline-code: var(--dsw-static-neutral-bluish-850);
+  --dsw-alias-markdown-placeholder: var(--dsw-static-neutral-bluish-850);
+  --dsw-alias-markdown-tag: var(--dsw-static-neutral-bluish-850);
+  --dsw-alias-scrollbar-bg-l1: var(--dsw-static-neutral-700);
+  --dsw-alias-scrollbar-bg-l2: var(--dsw-static-neutral-600);
+  --dsw-alias-scrollbar-hover-l1: var(--dsw-static-neutral-600);
+  --dsw-alias-scrollbar-hover-l2: var(--dsw-static-neutral-550);
+  --dsw-alias-state-business-primary: var(--dsw-static-deepseek-500);
+  --dsw-alias-state-business-tertiary: var(--dsw-static-deepseek-800);
+  --dsw-alias-state-error-primary: var(--dsw-static-red-400);
+  --dsw-alias-state-error-secondary: var(--dsw-static-red-400);
+  --dsw-alias-state-success-primary: var(--dsw-static-green-500);
+  --dsw-alias-state-success-secondary: var(--dsw-static-green-400);
+  --dsw-alias-state-success-tertiary: var(--dsw-static-green-900);
+  --dsw-alias-state-warn-label: var(--dsw-static-amber-600);
+  --dsw-alias-state-warn-primary: var(--dsw-static-amber-500);
+  --dsw-alias-state-warn-secondary: var(--dsw-static-amber-400);
+  --dsw-alias-state-warn-tertiary: var(--dsw-static-amber-900);
+  --dsw-alias-toast-bg: var(--dsw-static-neutral-bluish-750);
+  --dsw-alias-tooltip-bg: var(--dsw-static-neutral-bluish-750);
+  --dsw-specific-bubble-highlight: var(--dsw-static-neutral-bluish-750);
+  --dsw-specific-bubble: var(--dsw-static-neutral-bluish-850);
+  --dsw-specific-input-major: var(--dsw-static-neutral-bluish-850);
+  --dsw-specific-login-input: var(--dsw-static-neutral-bluish-900);
+  --dsw-specific-menu: var(--dsw-alias-bg-layer-3);
+  --dsw-specific-selector: var(--dsw-static-neutral-bluish-800);
+  --dsw-specific-sidebar-fill: var(--dsw-static-neutral-bluish-900);
+  --dsw-specific-sidebar-nav-item-active-accent: var(--dsw-static-neutral-bluish-800);
+  --dsw-specific-sidebar-nav-item-active: var(--dsw-static-neutral-bluish-750);
+  --dsw-specific-sidebar-nav-item-hover: var(--dsw-static-neutral-bluish-850);
+  --dsw-specific-tip: var(--dsw-static-neutral-bluish-800);
+}
diff --git a/packages/client/ui-theme/src/styles/gradient-shadow-text.css b/packages/client/ui-theme/src/styles/gradient-shadow-text.css
new file mode 100644
index 0000000000..aea8d9cb83
--- /dev/null
+++ b/packages/client/ui-theme/src/styles/gradient-shadow-text.css
@@ -0,0 +1,224 @@
+body {
+  --dsw-linear-gradient-think: linear-gradient(180deg, #fff 20.19%, rgba(255, 255, 255, 0) 100%);
+  --dsw-linear-think-select: linear-gradient(180deg, #f5f6f7 20.19%, rgba(245, 246, 247, 0) 100%);
+  /* 阴影 */
+  --dsw-shadow-lv1: 0 2px 4px 0 rgba(0, 0, 0, 0.05);
+  --dsw-shadow-lv1-blur: 0 4px 12px 0 rgba(0, 0, 0, 0.02);
+  --dsw-shadow-lv2: 0 4px 12px 0 rgba(0, 0, 0, 0.02), 0 2px 8px 0 rgba(0, 0, 0, 0.04);
+  --dsw-shadow-lv3:
+    0 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 4px 0 rgba(0, 0, 0, 0.02), 0 12px 32px 0 rgba(0, 0, 0, 0.08);
+  /* blur filter */
+  --dsw-mask-blur: blur(2px);
+}
+
+body[data-ds-dark-theme] {
+  --dsw-linear-gradient-think: linear-gradient(180deg, #151517 20.19%, rgba(21, 21, 23, 0) 100%);
+  --dsw-linear-think-select: linear-gradient(180deg, #232325 20.19%, rgba(35, 35, 37, 0) 100%);
+}
+
+/* ---------- 字体 ---------- */
+/* 由 @deepseek-figma-plugin/custom-variable-name 插件导出 */
+body {
+  --dsw-font-markdown-h1: 700 24px/34px var(--dsw-font-family);
+  --dsw-font-markdown-h1-font-family: var(--dsw-font-family);
+  --dsw-font-markdown-h1-font-weight: 700;
+  --dsw-font-markdown-h1-line-height: 34px;
+  --dsw-font-markdown-h1-font-size: 24px;
+  --dsw-font-markdown-h1-font-style: normal;
+
+  --dsw-font-markdown-h2: 700 22px/32px var(--dsw-font-family);
+  --dsw-font-markdown-h2-font-family: var(--dsw-font-family);
+  --dsw-font-markdown-h2-font-weight: 700;
+  --dsw-font-markdown-h2-line-height: 32px;
+  --dsw-font-markdown-h2-font-size: 22px;
+  --dsw-font-markdown-h2-font-style: normal;
+
+  --dsw-font-markdown-h3: 700 20px/30px var(--dsw-font-family);
+  --dsw-font-markdown-h3-font-family: var(--dsw-font-family);
+  --dsw-font-markdown-h3-font-weight: 700;
+  --dsw-font-markdown-h3-line-height: 30px;
+  --dsw-font-markdown-h3-font-size: 20px;
+  --dsw-font-markdown-h3-font-style: normal;
+
+  --dsw-font-markdown-h4: 600 16px/28px var(--dsw-font-family);
+  --dsw-font-markdown-h4-font-family: var(--dsw-font-family);
+  --dsw-font-markdown-h4-font-weight: 600;
+  --dsw-font-markdown-h4-line-height: 28px;
+  --dsw-font-markdown-h4-font-size: 16px;
+  --dsw-font-markdown-h4-font-style: normal;
+
+  --dsw-font-markdown-base: 16px/28px var(--dsw-font-family);
+  --dsw-font-markdown-base-font-family: var(--dsw-font-family);
+  --dsw-font-markdown-base-font-weight: 400;
+  --dsw-font-markdown-base-line-height: 28px;
+  --dsw-font-markdown-base-font-size: 16px;
+  --dsw-font-markdown-base-font-style: normal;
+
+  --dsw-font-markdown-base-strong: 600 16px/28px var(--dsw-font-family);
+  --dsw-font-markdown-base-strong-font-family: var(--dsw-font-family);
+  --dsw-font-markdown-base-strong-font-weight: 600;
+  --dsw-font-markdown-base-strong-line-height: 28px;
+  --dsw-font-markdown-base-strong-font-size: 16px;
+  --dsw-font-markdown-base-strong-font-style: normal;
+
+  --dsw-font-markdown-base-italic: italic 16px/28px var(--dsw-font-family);
+  --dsw-font-markdown-base-italic-font-family: var(--dsw-font-family);
+  --dsw-font-markdown-base-italic-font-weight: 400;
+  --dsw-font-markdown-base-italic-line-height: 28px;
+  --dsw-font-markdown-base-italic-font-size: 16px;
+  --dsw-font-markdown-base-italic-font-style: italic;
+
+  --dsw-font-markdown-base-strong-italic: italic 600 16px/28px var(--dsw-font-family);
+  --dsw-font-markdown-base-strong-italic-font-family: var(--dsw-font-family);
+  --dsw-font-markdown-base-strong-italic-font-weight: 600;
+  --dsw-font-markdown-base-strong-italic-line-height: 28px;
+  --dsw-font-markdown-base-strong-italic-font-size: 16px;
+  --dsw-font-markdown-base-strong-italic-font-style: italic;
+
+  --dsw-font-markdown-table: 15px/25px var(--dsw-font-family);
+  --dsw-font-markdown-table-font-family: var(--dsw-font-family);
+  --dsw-font-markdown-table-font-weight: 400;
+  --dsw-font-markdown-table-line-height: 25px;
+  --dsw-font-markdown-table-font-size: 15px;
+  --dsw-font-markdown-table-font-style: normal;
+
+  --dsw-font-markdown-table-head: 500 15px/25px var(--dsw-font-family);
+  --dsw-font-markdown-table-head-font-family: var(--dsw-font-family);
+  --dsw-font-markdown-table-head-font-weight: 500;
+  --dsw-font-markdown-table-head-line-height: 25px;
+  --dsw-font-markdown-table-head-font-size: 15px;
+  --dsw-font-markdown-table-head-font-style: normal;
+
+  --dsw-font-markdown-small: 14px/24px var(--dsw-font-family);
+  --dsw-font-markdown-small-font-family: var(--dsw-font-family);
+  --dsw-font-markdown-small-font-weight: 400;
+  --dsw-font-markdown-small-line-height: 24px;
+  --dsw-font-markdown-small-font-size: 14px;
+  --dsw-font-markdown-small-font-style: normal;
+
+  --dsw-font-markdown-small-strong: 600 14px/24px var(--dsw-font-family);
+  --dsw-font-markdown-small-strong-font-family: var(--dsw-font-family);
+  --dsw-font-markdown-small-strong-font-weight: 600;
+  --dsw-font-markdown-small-strong-line-height: 24px;
+  --dsw-font-markdown-small-strong-font-size: 14px;
+  --dsw-font-markdown-small-strong-font-style: normal;
+
+  --dsw-font-markdown-small-italic: italic 14px/24px var(--dsw-font-family);
+  --dsw-font-markdown-small-italic-font-family: var(--dsw-font-family);
+  --dsw-font-markdown-small-italic-font-weight: 400;
+  --dsw-font-markdown-small-italic-line-height: 24px;
+  --dsw-font-markdown-small-italic-font-size: 14px;
+  --dsw-font-markdown-small-italic-font-style: italic;
+
+  --dsw-font-markdown-small-strong-italic: italic 600 14px/24px var(--dsw-font-family);
+  --dsw-font-markdown-small-strong-italic-font-family: var(--dsw-font-family);
+  --dsw-font-markdown-small-strong-italic-font-weight: 600;
+  --dsw-font-markdown-small-strong-italic-line-height: 24px;
+  --dsw-font-markdown-small-strong-italic-font-size: 14px;
+  --dsw-font-markdown-small-strong-italic-font-style: italic;
+
+  --dsw-font-markdown-code: 14px/22px var(--ds-font-family-code);
+  --dsw-font-markdown-code-font-family: var(--ds-font-family-code);
+  --dsw-font-markdown-code-font-weight: 400;
+  --dsw-font-markdown-code-line-height: 22px;
+  --dsw-font-markdown-code-font-size: 14px;
+  --dsw-font-markdown-code-font-style: normal;
+
+  --dsw-font-markdown-code-block: 13px/22px var(--ds-font-family-code);
+  --dsw-font-markdown-code-block-font-family: var(--ds-font-family-code);
+  --dsw-font-markdown-code-block-font-weight: 400;
+  --dsw-font-markdown-code-block-line-height: 22px;
+  --dsw-font-markdown-code-block-font-size: 13px;
+  --dsw-font-markdown-code-block-font-style: normal;
+
+  --dsw-font-xl-24: 600 24px/32px var(--dsw-font-family);
+  --dsw-font-xl-24-font-family: var(--dsw-font-family);
+  --dsw-font-xl-24-font-weight: 600;
+  --dsw-font-xl-24-line-height: 32px;
+  --dsw-font-xl-24-font-size: 24px;
+  --dsw-font-xl-24-font-style: normal;
+
+  --dsw-font-l-20: 500 20px/28px var(--dsw-font-family);
+  --dsw-font-l-20-font-family: var(--dsw-font-family);
+  --dsw-font-l-20-font-weight: 500;
+  --dsw-font-l-20-line-height: 28px;
+  --dsw-font-l-20-font-size: 20px;
+  --dsw-font-l-20-font-style: normal;
+
+  --dsw-font-m-18: 500 16px/28px var(--dsw-font-family);
+  --dsw-font-m-18-font-family: var(--dsw-font-family);
+  --dsw-font-m-18-font-weight: 500;
+  --dsw-font-m-18-line-height: 28px;
+  --dsw-font-m-18-font-size: 16px;
+  --dsw-font-m-18-font-style: normal;
+
+  --dsw-font-base-16: 16px/24px var(--dsw-font-family);
+  --dsw-font-base-16-font-family: var(--dsw-font-family);
+  --dsw-font-base-16-font-weight: 400;
+  --dsw-font-base-16-line-height: 24px;
+  --dsw-font-base-16-font-size: 16px;
+  --dsw-font-base-16-font-style: normal;
+
+  --dsw-font-base-strong-16: 500 16px/24px var(--dsw-font-family);
+  --dsw-font-base-strong-16-font-family: var(--dsw-font-family);
+  --dsw-font-base-strong-16-font-weight: 500;
+  --dsw-font-base-strong-16-line-height: 24px;
+  --dsw-font-base-strong-16-font-size: 16px;
+  --dsw-font-base-strong-16-font-style: normal;
+
+  --dsw-font-s-14: 14px/22px var(--dsw-font-family);
+  --dsw-font-s-14-font-family: var(--dsw-font-family);
+  --dsw-font-s-14-font-weight: 400;
+  --dsw-font-s-14-line-height: 22px;
+  --dsw-font-s-14-font-size: 14px;
+  --dsw-font-s-14-font-style: normal;
+
+  --dsw-font-s-strong-14: 500 14px/22px var(--dsw-font-family);
+  --dsw-font-s-strong-14-font-family: var(--dsw-font-family);
+  --dsw-font-s-strong-14-font-weight: 500;
+  --dsw-font-s-strong-14-line-height: 22px;
+  --dsw-font-s-strong-14-font-size: 14px;
+  --dsw-font-s-strong-14-font-style: normal;
+
+  --dsw-font-xs-13: 13px/20px var(--dsw-font-family);
+  --dsw-font-xs-13-font-family: var(--dsw-font-family);
+  --dsw-font-xs-13-font-weight: 400;
+  --dsw-font-xs-13-line-height: 20px;
+  --dsw-font-xs-13-font-size: 13px;
+  --dsw-font-xs-13-font-style: normal;
+
+  --dsw-font-xs-strong-13: 500 13px/20px var(--dsw-font-family);
+  --dsw-font-xs-strong-13-font-family: var(--dsw-font-family);
+  --dsw-font-xs-strong-13-font-weight: 500;
+  --dsw-font-xs-strong-13-line-height: 20px;
+  --dsw-font-xs-strong-13-font-size: 13px;
+  --dsw-font-xs-strong-13-font-style: normal;
+
+  --dsw-font-xxs-12: 12px/18px var(--dsw-font-family);
+  --dsw-font-xxs-12-font-family: var(--dsw-font-family);
+  --dsw-font-xxs-12-font-weight: 400;
+  --dsw-font-xxs-12-line-height: 18px;
+  --dsw-font-xxs-12-font-size: 12px;
+  --dsw-font-xxs-12-font-style: normal;
+
+  --dsw-font-xxs-strong-12: 500 12px/18px var(--dsw-font-family);
+  --dsw-font-xxs-strong-12-font-family: var(--dsw-font-family);
+  --dsw-font-xxs-strong-12-font-weight: 500;
+  --dsw-font-xxs-strong-12-line-height: 18px;
+  --dsw-font-xxs-strong-12-font-size: 12px;
+  --dsw-font-xxs-strong-12-font-style: normal;
+
+  --dsw-font-xxxs-11: 11px/14px var(--dsw-font-family);
+  --dsw-font-xxxs-11-font-family: var(--dsw-font-family);
+  --dsw-font-xxxs-11-font-weight: 400;
+  --dsw-font-xxxs-11-line-height: 14px;
+  --dsw-font-xxxs-11-font-size: 11px;
+  --dsw-font-xxxs-11-font-style: normal;
+
+  --dsw-font-xxxs-strong-11: 500 11px/14px var(--dsw-font-family);
+  --dsw-font-xxxs-strong-11-font-family: var(--dsw-font-family);
+  --dsw-font-xxxs-strong-11-font-weight: 500;
+  --dsw-font-xxxs-strong-11-line-height: 14px;
+  --dsw-font-xxxs-strong-11-font-size: 11px;
+  --dsw-font-xxxs-strong-11-font-style: normal;
+}
diff --git a/packages/client/ui-theme/tests/invariant.spec.ts b/packages/client/ui-theme/tests/invariant.spec.ts
new file mode 100644
index 0000000000..6f4e867c4d
--- /dev/null
+++ b/packages/client/ui-theme/tests/invariant.spec.ts
@@ -0,0 +1,27 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { apply as nodeApply } from '@deepseek-ai/dsh-client-ui-theme'
+import { apply as clientApply, inject, ThemeService } from '@deepseek-ai/dsh-client-ui-theme/client'
+import * as ThemeInvariant from '@deepseek-ai/dsh-client-ui-theme/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+describe('invariant companion', () => {
+  it('registers under the package name with an empty installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    await expect(ctx.plugin(ThemeInvariant).await()).resolves.toBeDefined()
+  })
+
+  it('node-half apply is a no-op host placeholder', () => {
+    nodeApply()
+    expect(true).toBe(true) // reaching here without throw is the contract
+  })
+
+  it('client apply provides ctx.theme with no service prerequisites', async () => {
+    expect(inject).toEqual([])
+    const ctx = new Context()
+    await ctx.plugin({ inject, apply: clientApply }).await()
+    expect(ctx.get('theme')).toBeInstanceOf(ThemeService)
+  })
+})
diff --git a/packages/client/ui-theme/tests/theme.spec.ts b/packages/client/ui-theme/tests/theme.spec.ts
new file mode 100644
index 0000000000..126957c5eb
--- /dev/null
+++ b/packages/client/ui-theme/tests/theme.spec.ts
@@ -0,0 +1,61 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it } from 'vitest'
+import { ThemeService } from '@deepseek-ai/dsh-client-ui-theme/client'
+
+describe('ThemeService', () => {
+  beforeEach(() => {
+    document.body.removeAttribute('data-ds-dark-theme')
+    document.body.removeAttribute('style')
+  })
+
+  it('starts on light; apply toggles the dark body attribute both ways', () => {
+    const theme = new ThemeService()
+    expect(theme.current()).toBe('light')
+    theme.apply('dark')
+    expect(document.body.hasAttribute('data-ds-dark-theme')).toBe(true)
+    expect(theme.current()).toBe('dark')
+    theme.apply('light')
+    expect(document.body.hasAttribute('data-ds-dark-theme')).toBe(false)
+    expect(theme.current()).toBe('light')
+  })
+
+  it('throws on unregistered apply and duplicate register (built-ins included)', () => {
+    const theme = new ThemeService()
+    expect(() => { theme.apply('sepia') }).toThrow('not registered')
+    expect(() => theme.register('light', {})).toThrow('already registered')
+    theme.register('sepia', {})
+    expect(() => theme.register('sepia', {})).toThrow('already registered')
+  })
+
+  it('applies third-party token overrides as body inline vars and swaps them on switch', () => {
+    const theme = new ThemeService()
+    theme.register('sepia', { '--dsw-alias-bg-base': 'rgb(1, 2, 3)' })
+    theme.apply('sepia')
+    expect(document.body.style.getPropertyValue('--dsw-alias-bg-base')).toBe('rgb(1, 2, 3)')
+    expect(document.body.hasAttribute('data-ds-dark-theme')).toBe(false)
+    theme.apply('dark')
+    expect(document.body.style.getPropertyValue('--dsw-alias-bg-base')).toBe('')
+    expect(document.body.hasAttribute('data-ds-dark-theme')).toBe(true)
+  })
+
+  it('disposing the active theme reverts to light; disposer is idempotent', () => {
+    const theme = new ThemeService()
+    const dispose = theme.register('sepia', { '--dsw-alias-bg-base': 'red' })
+    theme.apply('sepia')
+    dispose()
+    expect(theme.current()).toBe('light')
+    expect(document.body.style.getPropertyValue('--dsw-alias-bg-base')).toBe('')
+    expect(() => { theme.apply('sepia') }).toThrow('not registered')
+    dispose()
+    expect(theme.current()).toBe('light')
+  })
+
+  it('disposing an inactive theme leaves the active selection untouched', () => {
+    const theme = new ThemeService()
+    const dispose = theme.register('sepia', {})
+    theme.apply('dark')
+    dispose()
+    expect(theme.current()).toBe('dark')
+    expect(document.body.hasAttribute('data-ds-dark-theme')).toBe(true)
+  })
+})
diff --git a/packages/client/ui-theme/tsconfig.json b/packages/client/ui-theme/tsconfig.json
new file mode 100644
index 0000000000..076aa22e9f
--- /dev/null
+++ b/packages/client/ui-theme/tsconfig.json
@@ -0,0 +1,24 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "lib": [
+      "ES2024",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": []
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/client/ui-theme/tsdown.config.ts b/packages/client/ui-theme/tsdown.config.ts
new file mode 100644
index 0000000000..1bc83af0e9
--- /dev/null
+++ b/packages/client/ui-theme/tsdown.config.ts
@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-ui-theme', ['lib/types/index.js', 'lib/types/invariant.js'])
diff --git a/packages/client/ui-trajectory/README.md b/packages/client/ui-trajectory/README.md
new file mode 100644
index 0000000000..cd3f74f448
--- /dev/null
+++ b/packages/client/ui-trajectory/README.md
@@ -0,0 +1,15 @@
+# @deepseek-ai/dsh-client-ui-trajectory
+
+Trajectory/Waterfall placeholder views; the pure-consumer minimal plugin exemplar (registers two views, provides no service, declares no Context merge). Contract: api-contracts v3 §8.
+
+## Model Experience
+
+None, as the trajectory views render session data in the browser; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Both views are placeholders by charter** — coarse span derivation with no visual acceptance bar; the real implementations, anchor deep-linking, and span-click selection handoff are the P-III project.
diff --git a/packages/client/ui-trajectory/package.json b/packages/client/ui-trajectory/package.json
new file mode 100644
index 0000000000..0721ab99f0
--- /dev/null
+++ b/packages/client/ui-trajectory/package.json
@@ -0,0 +1,59 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-trajectory",
+  "description": "Trajectory/Waterfall placeholder views: pure-consumer plugin registering into the conversation ViewMap (no service)",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-client-ui-conversation"
+    ],
+    "platform": "web"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-web-react": "workspace:^",
+    "react": "^18.2.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}
diff --git a/packages/client/ui-trajectory/src/client/TrajectoryStatsHeader.module.css b/packages/client/ui-trajectory/src/client/TrajectoryStatsHeader.module.css
new file mode 100644
index 0000000000..9def8790a9
--- /dev/null
+++ b/packages/client/ui-trajectory/src/client/TrajectoryStatsHeader.module.css
@@ -0,0 +1,7 @@
+.root {
+  padding: 4px 16px;
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-secondary);
+  border-bottom: 1px solid var(--dsw-alias-border-l2);
+}
diff --git a/packages/client/ui-trajectory/src/client/TrajectoryStatsHeader.tsx b/packages/client/ui-trajectory/src/client/TrajectoryStatsHeader.tsx
new file mode 100644
index 0000000000..4fb143dce9
--- /dev/null
+++ b/packages/client/ui-trajectory/src/client/TrajectoryStatsHeader.tsx
@@ -0,0 +1,28 @@
+// TrajectoryStatsHeader: span totals row mounted as chrome.header on both
+// placeholder views — the second chrome-attachment consumer (chat's
+// StatsLine footer is the first), proving both mount points render.
+// Subscribes to `nodes` only: chunk batches never swap that reference, so
+// the row is quiet during streaming.
+
+import { memo, useMemo } from 'react'
+import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
+import type { ChromeProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { deriveSpans, deriveSpanStats } from './spans.ts'
+import css from './TrajectoryStatsHeader.module.css'
+
+/** Per-view chrome extension (the view map entry's chromeProps slot). */
+export interface TrajectoryChromeProps {
+  /** Render the tool-calls segment; defaults to true (waterfall lanes already
+   *  visualize calls, so that view may drop the redundant count). */
+  showCalls?: boolean
+}
+
+export const TrajectoryStatsHeader = memo(function TrajectoryStatsHeader({ useSession, showCalls }: ChromeProps & TrajectoryChromeProps) {
+  const nodes = (useSession as SnapshotSelectorHook<ConversationSnapshot>)((s) => s.nodes)
+  const stats = useMemo(() => deriveSpanStats(deriveSpans(nodes)), [nodes])
+  if (stats.turns === 0) return null
+  const parts = [`${stats.turns} turns`, `${stats.steps} steps`]
+  if (showCalls !== false) parts.push(`${stats.calls} tool calls`)
+  return <div className={css.root}>{parts.join(' · ')}</div>
+})
diff --git a/packages/client/ui-trajectory/src/client/TrajectoryView.tsx b/packages/client/ui-trajectory/src/client/TrajectoryView.tsx
new file mode 100644
index 0000000000..a1cda2441d
--- /dev/null
+++ b/packages/client/ui-trajectory/src/client/TrajectoryView.tsx
@@ -0,0 +1,28 @@
+// TrajectoryView: P-I placeholder body for the trajectory tab — per-turn
+// span list with node-count weights (no timing data exists yet; deviation
+// ledger #3 defers real rendering to P-III).
+
+import { useMemo } from 'react'
+import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
+import type { ConvViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { deriveSpans } from './spans.ts'
+import css from './views.module.css'
+
+export function TrajectoryView({ useSession }: ConvViewProps) {
+  const nodes = (useSession as SnapshotSelectorHook<ConversationSnapshot>)((s) => s.nodes)
+  const spans = useMemo(() => deriveSpans(nodes), [nodes])
+  if (spans.length === 0) return <div className={css.root}><p className={css.empty}>暂无轨迹数据</p></div>
+  return (
+    <div className={css.root}>
+      {spans.map((span) => (
+        <div key={span.turn} className={css.row}>
+          <span className={css.turnTag}>turn {span.turn}</span>
+          <span className={css.meta}>
+            {span.steps} steps · {span.calls} calls · {span.nodes} nodes
+          </span>
+        </div>
+      ))}
+    </div>
+  )
+}
diff --git a/packages/client/ui-trajectory/src/client/WaterfallView.tsx b/packages/client/ui-trajectory/src/client/WaterfallView.tsx
new file mode 100644
index 0000000000..c9549dbc73
--- /dev/null
+++ b/packages/client/ui-trajectory/src/client/WaterfallView.tsx
@@ -0,0 +1,49 @@
+// WaterfallView: P-I placeholder body for the waterfall tab — node-count
+// bars per turn stand in for duration lanes (no timing data yet; deviation
+// ledger #3 defers real rendering to P-III).
+
+import { useMemo } from 'react'
+import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
+import type { ConvViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { deriveSpans } from './spans.ts'
+import css from './views.module.css'
+
+/** Bar width scale: px per node, clamped so tiny windows still show a bar. */
+const PX_PER_NODE = 14
+const MIN_BAR_PX = 8
+
+/** Per-view extension merged into the waterfall body's props through the
+ *  conversation view map ({ extraProps? } entry slot). */
+export interface WaterfallExtraProps {
+  /** Bar-lane density in px per node; defaults to 14. */
+  pxPerNode?: number
+}
+
+export function WaterfallView({ useSession, pxPerNode }: ConvViewProps & WaterfallExtraProps) {
+  const scale = pxPerNode ?? PX_PER_NODE
+  const nodes = (useSession as SnapshotSelectorHook<ConversationSnapshot>)((s) => s.nodes)
+  const spans = useMemo(() => deriveSpans(nodes), [nodes])
+  if (spans.length === 0) return <div className={css.root}><p className={css.empty}>暂无瀑布数据</p></div>
+  return (
+    <div className={css.root}>
+      {spans.map((span, i) => (
+        <div key={span.turn} className={css.row} style={{ paddingLeft: i * 12 }}>
+          <span className={css.turnTag}>turn {span.turn}</span>
+          <span
+            className={css.bar}
+            style={{ width: Math.max(span.nodes * scale, MIN_BAR_PX) }}
+            title={`${span.nodes} nodes`}
+          />
+          {span.calls > 0 && (
+            <span
+              className={`${css.bar} ${css.barCalls}`}
+              style={{ width: Math.max(span.calls * scale, MIN_BAR_PX) }}
+              title={`${span.calls} tool calls`}
+            />
+          )}
+        </div>
+      ))}
+    </div>
+  )
+}
diff --git a/packages/client/ui-trajectory/src/client/index.ts b/packages/client/ui-trajectory/src/client/index.ts
new file mode 100644
index 0000000000..b65eb3d3ab
--- /dev/null
+++ b/packages/client/ui-trajectory/src/client/index.ts
@@ -0,0 +1,46 @@
+/**
+ * Trajectory/Waterfall plugin, browser half: merges ConversationViewMap and
+ * registers the two placeholder views. Pure consumer — no ctx service, no
+ * Context declaration merge; the minimal-plugin exemplar. Contract:
+ * api-contracts v3 section 8.
+ */
+import type { Context } from 'cordis'
+import { TrajectoryStatsHeader, type TrajectoryChromeProps } from './TrajectoryStatsHeader.tsx'
+import { TrajectoryView } from './TrajectoryView.tsx'
+import { WaterfallView, type WaterfallExtraProps } from './WaterfallView.tsx'
+
+export { deriveSpans, deriveSpanStats, type SpanStats, type TurnSpan } from './spans.ts'
+export { TrajectoryStatsHeader, type TrajectoryChromeProps } from './TrajectoryStatsHeader.tsx'
+export { TrajectoryView } from './TrajectoryView.tsx'
+export { WaterfallView, type WaterfallExtraProps } from './WaterfallView.tsx'
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ConversationViewMap {
+    // Per-view extension shapes merged through the map (view-ring design):
+    // the stats header's chrome props ride both entries; the waterfall body
+    // additionally takes its lane-density extra. P-III widens these.
+    trajectory: { chromeProps: TrajectoryChromeProps }
+    waterfall: { chromeProps: TrajectoryChromeProps; extraProps: WaterfallExtraProps }
+  }
+}
+
+/** Required services (cordis fiber inject — the loader passes the whole export surface as an object plugin). */
+export const inject = ['conversation']
+
+/**
+ * Client plugin body: register the trajectory and waterfall views. The
+ * registrations are effects on this fiber (plugin unload removes both tabs).
+ * @param ctx - client root context.
+ */
+export function apply(ctx: Context): void {
+  // chrome.header on both views: the second chrome-attachment consumer
+  // (chat's footer StatsLine is the first) — proves both mount points live.
+  ctx.conversation.registerView({
+    id: 'trajectory', label: 'Trajectory', order: 10,
+    component: TrajectoryView, chrome: { header: TrajectoryStatsHeader },
+  })
+  ctx.conversation.registerView({
+    id: 'waterfall', label: 'Waterfall', order: 20,
+    component: WaterfallView, chrome: { header: TrajectoryStatsHeader },
+  })
+}
diff --git a/packages/client/ui-trajectory/src/client/spans.ts b/packages/client/ui-trajectory/src/client/spans.ts
new file mode 100644
index 0000000000..4957f3762c
--- /dev/null
+++ b/packages/client/ui-trajectory/src/client/spans.ts
@@ -0,0 +1,71 @@
+/**
+ * Rough per-turn span derivation shared by the two placeholder views and the
+ * header stats bar. P-I ships no timing data, so a span's weight is its node
+ * count, not wall time (deviation ledger #3 — real spans land in P-III).
+ */
+import type { ConversationNode, ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
+
+/** One turn's worth of activity, folded from the snapshot node window. */
+export interface TurnSpan {
+  turn: number
+  /** Assistant step messages inside the turn. */
+  steps: number
+  /** Tool results inside the turn (running calls are not folded in P-I). */
+  calls: number
+  /** Total nodes attributed to the turn (span weight stand-in). */
+  nodes: number
+}
+
+/** Aggregate totals for the header stats bar. */
+export interface SpanStats {
+  turns: number
+  steps: number
+  calls: number
+}
+
+/**
+ * Fold snapshot nodes into per-turn spans. Only assistant nodes carry a turn
+ * number; user/steering/context/tool nodes attach to the turn last seen in
+ * sequence order (turn 0 collects the pre-assistant prologue).
+ * @param nodes - snapshot nodes in surface order.
+ * @returns spans ordered by first appearance.
+ */
+export function deriveSpans(nodes: ConversationSnapshot['nodes']): readonly TurnSpan[] {
+  const spans = new Map<number, TurnSpan>()
+  let currentTurn = 0
+  const spanFor = (turn: number): TurnSpan => {
+    let span = spans.get(turn)
+    if (span === undefined) {
+      span = { turn, steps: 0, calls: 0, nodes: 0 }
+      spans.set(turn, span)
+    }
+    return span
+  }
+  for (const node of nodes) {
+    if (hasTurn(node)) currentTurn = node.turn
+    const span = spanFor(currentTurn)
+    span.nodes += 1
+    if (node.kind === 'assistant') span.steps += 1
+    if (node.kind === 'tool-result') span.calls += 1
+  }
+  return [...spans.values()]
+}
+
+/**
+ * Aggregate spans into the header totals.
+ * @param spans - deriveSpans product.
+ * @returns turn/step/call totals.
+ */
+export function deriveSpanStats(spans: readonly TurnSpan[]): SpanStats {
+  let steps = 0
+  let calls = 0
+  for (const span of spans) {
+    steps += span.steps
+    calls += span.calls
+  }
+  return { turns: spans.length, steps, calls }
+}
+
+function hasTurn(node: ConversationNode): node is ConversationNode & { turn: number } {
+  return node.kind === 'assistant' || node.kind === 'steering'
+}
diff --git a/packages/client/ui-trajectory/src/client/views.module.css b/packages/client/ui-trajectory/src/client/views.module.css
new file mode 100644
index 0000000000..951a5e2705
--- /dev/null
+++ b/packages/client/ui-trajectory/src/client/views.module.css
@@ -0,0 +1,37 @@
+.root {
+  padding: 16px;
+  overflow-y: auto;
+  color: var(--dsw-alias-label-primary);
+  font-size: 13px;
+}
+
+.empty {
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 4px 0;
+}
+
+.turnTag {
+  flex: none;
+  width: 64px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.bar {
+  height: 12px;
+  border-radius: 4px;
+  background: var(--dsw-alias-bg-skeleton);
+}
+
+.barCalls {
+  background: var(--dsw-alias-brand-primary);
+}
+
+.meta {
+  color: var(--dsw-alias-label-caption);
+}
diff --git a/packages/client/ui-trajectory/src/css-modules.d.ts b/packages/client/ui-trajectory/src/css-modules.d.ts
new file mode 100644
index 0000000000..bc5e482353
--- /dev/null
+++ b/packages/client/ui-trajectory/src/css-modules.d.ts
@@ -0,0 +1,6 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css'
diff --git a/packages/client/ui-trajectory/src/index.ts b/packages/client/ui-trajectory/src/index.ts
new file mode 100644
index 0000000000..1688b36271
--- /dev/null
+++ b/packages/client/ui-trajectory/src/index.ts
@@ -0,0 +1,10 @@
+/**
+ * Trajectory plugin, node half. Pure UI plugin: the empty apply exists so
+ * the plugin appears in the host cordis.yml / Loader (load and lifecycle
+ * follow the host; the browser half ships via exports["./client"], discovered
+ * through the package.json dshClient declaration). Contract: api-contracts
+ * v3 sections 0.3 and 8.
+ */
+
+/** Host plugin body — no host-side behavior for the trajectory plugin. */
+export function apply(): void {}
diff --git a/packages/client/ui-trajectory/src/invariant.ts b/packages/client/ui-trajectory/src/invariant.ts
new file mode 100644
index 0000000000..46efab68a3
--- /dev/null
+++ b/packages/client/ui-trajectory/src/invariant.ts
@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-trajectory`.
+ * @module @deepseek-ai/dsh-client-ui-trajectory/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-trajectory'
+
+/** Cordis companion plugin name. */
+export const name = 'client-ui-trajectory-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: a pure-consumer plugin — it emits no cordis events
+ * and owns no mutable cross-plugin state; both view registrations are plain
+ * effects whose disposal the conversation registry's own specs and this
+ * package's behavior specs observe directly.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/client/ui-trajectory/tests/client-bundle.spec.ts b/packages/client/ui-trajectory/tests/client-bundle.spec.ts
new file mode 100644
index 0000000000..1cf411420c
--- /dev/null
+++ b/packages/client/ui-trajectory/tests/client-bundle.spec.ts
@@ -0,0 +1,81 @@
+// @vitest-environment jsdom
+/**
+ * Real tsdown artifact shape: lib/client.js hands off through
+ * window.DSHClientProxy.loadPlugin, resolves externals through the injected
+ * require, returns the export surface (apply + inject), and a mounted apply
+ * registers both views into a real ConversationService. Skips when dist/ is
+ * not built (`pnpm --filter @deepseek-ai/dsh-client-ui-trajectory bundle`).
+ */
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { Context } from 'cordis'
+import { afterEach, describe, expect, it } from 'vitest'
+import { ConversationService } from '@deepseek-ai/dsh-client-ui-conversation/client'
+
+const PLUGIN_ID = '@deepseek-ai/dsh-client-ui-trajectory'
+
+interface Handoff { id: string; factory: (require: (spec: string) => unknown) => Record<string, unknown> }
+type Win = { DSHClientProxy?: { loadPlugin(h: Handoff): void } }
+
+function readBundle(): string | undefined {
+  try {
+    // import.meta.url is http-scheme in the jsdom pool; vitest runs from the
+    // repo root, so resolve the artifact repo-relatively instead.
+    return readFileSync(resolve('packages/client/ui-trajectory/lib/client.js'), 'utf8')
+  } catch {
+    return undefined
+  }
+}
+
+afterEach(() => {
+  delete (window as Win).DSHClientProxy
+  for (const el of document.querySelectorAll('style')) el.remove()
+})
+
+describe('tsdown client artifact', () => {
+  const code = readBundle()
+
+  async function loadArtifact() {
+    let handoff: Handoff | undefined
+    ;(window as Win).DSHClientProxy = { loadPlugin: (h) => { handoff = h } }
+    // Same execution form the loader uses (inline script eval, window scope) —
+    // the implied-eval ban targets accidental string execution, not this
+    // deliberate bundle-execution fixture.
+    // eslint-disable-next-line @typescript-eslint/no-implied-eval, @typescript-eslint/no-unsafe-call
+    new Function(code!)()
+    expect(handoff).toBeDefined()
+    const modules = new Map<string, unknown>([
+      ['react', await import('react')],
+      ['react/jsx-runtime', await import('react/jsx-runtime')],
+    ])
+    const surface = handoff!.factory((spec) => {
+      if (!modules.has(spec)) throw new Error(`unexpected require: ${spec}`)
+      return modules.get(spec)
+    })
+    return { handoff: handoff!, surface }
+  }
+
+  it.skipIf(code === undefined)('hands off with the manifest id and a DI-require factory', async () => {
+    const { handoff, surface } = await loadArtifact()
+    expect(handoff.id).toBe(PLUGIN_ID)
+    expect(surface.apply).toBeTypeOf('function')
+    expect(surface.inject).toEqual(['conversation'])
+  })
+
+  it.skipIf(code === undefined)('mounted as an object plugin, apply registers both views on the real service', async () => {
+    const { surface } = await loadArtifact()
+    const ctx = new Context()
+    const svc = new ConversationService(ctx)
+    const fiber = ctx.plugin(surface as { apply: (ctx: Context) => void })
+    await fiber.await()
+    expect(svc.views().map(v => v.id)).toEqual(['trajectory', 'waterfall'])
+    await fiber.dispose()
+    expect(svc.views()).toHaveLength(0)
+  })
+
+  it.skipIf(code === undefined)('injects plugin-tagged module CSS during factory execution', async () => {
+    await loadArtifact()
+    const tags = document.querySelectorAll(`style[data-plugin=${JSON.stringify(PLUGIN_ID)}]`)
+    expect(tags.length).toBeGreaterThan(0)
+  })
+})
diff --git a/packages/client/ui-trajectory/tests/views.spec.tsx b/packages/client/ui-trajectory/tests/views.spec.tsx
new file mode 100644
index 0000000000..41a3c0c95b
--- /dev/null
+++ b/packages/client/ui-trajectory/tests/views.spec.tsx
@@ -0,0 +1,197 @@
+// @vitest-environment jsdom
+/**
+ * View registration acceptance on the real framework stack: the plugin fiber
+ * registers trajectory/waterfall into a real ConversationService, tabs switch
+ * inside ConversationRoot without collapsing chat, chrome.header renders the
+ * span stats bar, and fiber disposal removes both tabs. Span derivation edge
+ * cases ride along.
+ */
+import { Context } from 'cordis'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { createElement, Fragment, type FC, type ReactNode } from 'react'
+import { bindSnapshotSelector, createSnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import type { UseSession } from '@deepseek-ai/dsh-client-web-react'
+import type { ConversationSnapshot, SessionId, SessionSummary } from '@deepseek-ai/dsh-client-runtime/client'
+import { ConversationRoot, ConversationService } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ConvViewProps, ViewEntry, ViewId } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import {
+  apply, deriveSpans, deriveSpanStats, inject, TrajectoryStatsHeader, TrajectoryView, WaterfallView,
+} from '@deepseek-ai/dsh-client-ui-trajectory/client'
+import { apply as nodeApply } from '@deepseek-ai/dsh-client-ui-trajectory'
+
+const SID = 's1' as SessionId
+
+afterEach(cleanup)
+
+/** Node fixture: user prologue, two turns, one tool result inside turn 1. */
+const NODES = [
+  { kind: 'user', seq: 1, content: [], source: null },
+  { kind: 'assistant', seq: 2, turn: 1, step: 1, blocks: [] },
+  { kind: 'tool-result', seq: 3, callId: 'c1', call: null, content: [], isError: false, callView: null, resultView: null },
+  { kind: 'assistant', seq: 4, turn: 2, step: 1, blocks: [] },
+] as unknown as ConversationSnapshot['nodes']
+
+function fakeSession(nodes: ConversationSnapshot['nodes']) {
+  const store = createSnapshotStore<{ nodes: ConversationSnapshot['nodes'] }>({ nodes })
+  return { store, useSession: bindSnapshotSelector(store) as unknown as UseSession }
+}
+
+/** Real-stack bench: root Context + real ConversationService + the plugin fiber. */
+async function bench() {
+  const ctx = new Context()
+  const svc = new ConversationService(ctx)
+  const chatBody = vi.fn(() => <div data-testid="chat-body" />)
+  svc.registerView({ id: 'chat' as ViewId, label: 'Chat', order: 0, component: chatBody as unknown as FC<ConvViewProps> })
+  const fiber = ctx.plugin({ inject: [...inject], apply })
+  await fiber.await()
+  return { ctx, svc, fiber }
+}
+
+/** Mount ConversationRoot over the service's registry face, rendering chrome like the conversation apply does. */
+function mount(svc: ConversationService, nodes: ConversationSnapshot['nodes'] = NODES) {
+  const { useSession } = fakeSession(nodes)
+  const activeStore = createSnapshotStore<string | undefined>(undefined)
+  const ancestry: SessionSummary[] = [{ id: SID, title: 'self', running: false, updatedAt: 1 }]
+  const viewProps = {
+    sessionId: SID, useSession,
+    useSelection: () => null,
+    actions: { openDetails: vi.fn(), loadOlder: vi.fn() },
+    slots: undefined,
+  } as unknown as ConvViewProps
+  const renderView = (entry: ViewEntry): ReactNode => {
+    const children: ReactNode[] = []
+    if (entry.chrome?.header !== undefined) {
+      children.push(createElement(entry.chrome.header, { key: 'h', sessionId: SID, useSession }))
+    }
+    children.push(createElement(entry.component, { key: 'b', ...viewProps }))
+    if (entry.chrome?.footer !== undefined) {
+      children.push(createElement(entry.chrome.footer, { key: 'f', sessionId: SID, useSession }))
+    }
+    return createElement(Fragment, null, children)
+  }
+  const sessionSnapshot = createSnapshotStore<{ running: boolean; removed: boolean; promptError: null; nodes: ConversationSnapshot['nodes'] }>({
+    running: false, removed: false, promptError: null, nodes,
+  })
+  return render(
+    <ConversationRoot
+      sessionId={SID}
+      useSession={bindSnapshotSelector(sessionSnapshot) as unknown as UseSession}
+      useAncestry={() => ancestry}
+      views={{
+        list: () => svc.views(),
+        subscribe: (fn) => svc.subscribeViews(fn),
+        version: () => svc.viewsVersion(),
+      }}
+      useActiveView={() => activeStore.useSelector((s) => s) as ViewId | undefined}
+      composer={{ useDraft: () => '', setDraft: vi.fn(), send: vi.fn(), stop: vi.fn() }}
+      actions={{ openView: ((v: string) => { activeStore.set(v) }) as (v: never) => void, open: vi.fn() }}
+      renderView={renderView}
+    />,
+  )
+}
+
+describe('plugin registration', () => {
+  it('registers trajectory and waterfall after chat, both with header chrome', async () => {
+    const b = await bench()
+    const views = b.svc.views()
+    expect(views.map((v) => v.id)).toEqual(['chat', 'trajectory', 'waterfall'])
+    expect(views[1]?.chrome?.header).toBeDefined()
+    expect(views[2]?.chrome?.header).toBeDefined()
+    expect(views[1]?.chrome?.footer).toBeUndefined()
+  })
+
+  it('fiber disposal removes both tabs and leaves chat standing', async () => {
+    const b = await bench()
+    await b.fiber.dispose()
+    expect(b.svc.views().map((v) => v.id)).toEqual(['chat'])
+  })
+})
+
+describe('tab switching in ConversationRoot', () => {
+  it('renders all three tabs, defaults to chat, and switches to trajectory with its header stats', async () => {
+    const b = await bench()
+    mount(b.svc)
+    expect(screen.getByTestId('chat-body')).toBeTruthy()
+    expect(screen.getAllByRole('tab').map((t) => t.textContent)).toEqual(['Chat', 'Trajectory', 'Waterfall'])
+
+    fireEvent.click(screen.getByRole('tab', { name: 'Trajectory' }))
+    // chrome.header stats over NODES: turns 0/1/2, 2 assistant steps, 1 tool call.
+    expect(screen.getByText('3 turns · 2 steps · 1 tool calls')).toBeTruthy()
+    expect(screen.getByText('turn 0')).toBeTruthy()
+    expect(screen.getByText('1 steps · 1 calls · 2 nodes')).toBeTruthy()
+    expect(screen.queryByTestId('chat-body')).toBeNull()
+  })
+
+  it('waterfall renders bars and switching back to chat does not collapse it', async () => {
+    const b = await bench()
+    mount(b.svc)
+    fireEvent.click(screen.getByRole('tab', { name: 'Waterfall' }))
+    expect(screen.getByTitle('2 nodes')).toBeTruthy()
+    expect(screen.getByTitle('1 tool calls')).toBeTruthy()
+
+    fireEvent.click(screen.getByRole('tab', { name: 'Chat' }))
+    expect(screen.getByTestId('chat-body')).toBeTruthy()
+  })
+
+  it('empty window: placeholder copy in the body, header chrome renders nothing', async () => {
+    const b = await bench()
+    mount(b.svc, [] as unknown as ConversationSnapshot['nodes'])
+    fireEvent.click(screen.getByRole('tab', { name: 'Trajectory' }))
+    expect(screen.getByText('暂无轨迹数据')).toBeTruthy()
+    expect(screen.queryByText(/turns ·/)).toBeNull()
+  })
+})
+
+describe('span derivation', () => {
+  it('attributes prologue to turn 0 and follows steering turn tags', () => {
+    const nodes = [
+      { kind: 'user', seq: 1 },
+      { kind: 'steering', seq: 2, turn: 5 },
+      { kind: 'user', seq: 3 },
+    ] as unknown as ConversationSnapshot['nodes']
+    const spans = deriveSpans(nodes)
+    expect(spans).toEqual([
+      { turn: 0, steps: 0, calls: 0, nodes: 1 },
+      { turn: 5, steps: 0, calls: 0, nodes: 2 },
+    ])
+    expect(deriveSpanStats(spans)).toEqual({ turns: 2, steps: 0, calls: 0 })
+  })
+
+  it('empty inputs produce zero stats and standalone components render their empty forms', () => {
+    expect(deriveSpanStats(deriveSpans([] as unknown as ConversationSnapshot['nodes']))).toEqual({ turns: 0, steps: 0, calls: 0 })
+    const { useSession } = fakeSession([] as unknown as ConversationSnapshot['nodes'])
+    const { container } = render(createElement(TrajectoryStatsHeader, { sessionId: SID, useSession }))
+    expect(container.firstChild).toBeNull()
+    render(createElement(TrajectoryView as FC<ConvViewProps>, {
+      sessionId: SID, useSession, useSelection: () => null,
+      actions: { openDetails: vi.fn(), loadOlder: vi.fn() }, slots: undefined,
+    } as unknown as ConvViewProps))
+    expect(screen.getByText('暂无轨迹数据')).toBeTruthy()
+  })
+})
+
+describe('WaterfallView standalone branches', () => {
+  const props = (nodes: ConversationSnapshot['nodes']) => ({
+    sessionId: SID, useSession: fakeSession(nodes).useSession, useSelection: () => null,
+    actions: { openDetails: vi.fn(), loadOlder: vi.fn() }, slots: undefined,
+  } as unknown as ConvViewProps)
+
+  it('empty window renders the placeholder copy', () => {
+    render(createElement(WaterfallView as FC<ConvViewProps>, props([] as unknown as ConversationSnapshot['nodes'])))
+    expect(screen.getByText('暂无瀑布数据')).toBeTruthy()
+  })
+
+  it('a turn without tool calls renders the node bar only', () => {
+    const nodes = [{ kind: 'user', seq: 1 }] as unknown as ConversationSnapshot['nodes']
+    render(createElement(WaterfallView as FC<ConvViewProps>, props(nodes)))
+    expect(screen.getByTitle('1 nodes')).toBeTruthy()
+    expect(screen.queryByTitle(/tool calls/)).toBeNull()
+  })
+})
+
+describe('node half', () => {
+  it('node apply is an intentional no-op (loader-managed lifecycle only)', () => {
+    expect(nodeApply()).toBeUndefined()
+  })
+})
diff --git a/packages/client/ui-trajectory/tsconfig.json b/packages/client/ui-trajectory/tsconfig.json
new file mode 100644
index 0000000000..e3b1abe266
--- /dev/null
+++ b/packages/client/ui-trajectory/tsconfig.json
@@ -0,0 +1,34 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "jsx": "react-jsx",
+    "lib": [
+      "ES2024",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": []
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../ui-conversation"
+    },
+    {
+      "path": "../web-react"
+    },
+    {
+      "path": "../runtime"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/client/ui-trajectory/tsdown.config.ts b/packages/client/ui-trajectory/tsdown.config.ts
new file mode 100644
index 0000000000..5fe169be39
--- /dev/null
+++ b/packages/client/ui-trajectory/tsdown.config.ts
@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-ui-trajectory', ['lib/types/index.js', 'lib/types/invariant.js'])
diff --git a/packages/client/web-react/README.md b/packages/client/web-react/README.md
new file mode 100644
index 0000000000..a4e6e4518e
--- /dev/null
+++ b/packages/client/web-react/README.md
@@ -0,0 +1,17 @@
+# @deepseek-ai/dsh-client-web-react
+
+ctx↔React glue: createSnapshotStore (zustand vanilla + immer + subscribeWithSelector + rafFlush + opt-in persist), bindSnapshotSelector, SessionProvider (dependency-inverted), scopedSlots outlet, RootBindingProvider, useInvoke. Contract: api-contracts v3 §2.
+
+## Model Experience
+
+None, as the ctx↔React glue runs entirely in the browser; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **The persist middleware corrupts primitive-state stores** — it object-spreads state on save, so a `SnapshotStore<string>` round-trips as a character map; consumers with primitive state hand-roll persistence instead (ui-conversation drafts is the precedent).
+- **`UseSession` is deliberately wide (`object` snapshot)** — the dependency direction (runtime → web-react, never the reverse) keeps the real `ConversationSnapshot` type out of reach; session-slot consumers narrow once at their boundary.
+- **renderSlot is the single P-I form** — no Suspense, no per-entry lazy loading; the progressive-rendering surface returns with its own project.
diff --git a/packages/client/web-react/package.json b/packages/client/web-react/package.json
new file mode 100644
index 0000000000..60e48421a5
--- /dev/null
+++ b/packages/client/web-react/package.json
@@ -0,0 +1,50 @@
+{
+  "name": "@deepseek-ai/dsh-client-web-react",
+  "description": "ctx-to-React glue: createSnapshotStore (zustand engine), bindSnapshotSelector, SessionProvider, scopedSlots outlet, useInvoke",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./store": {
+      "types": "./lib/types/store/index.d.ts",
+      "default": "./lib/store/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "immer": "^10.1.1",
+    "react": "^18.2.0",
+    "use-sync-external-store": "1.2.0",
+    "zustand": "~4.4.7"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/store/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}
diff --git a/packages/client/web-react/src/bind.ts b/packages/client/web-react/src/bind.ts
new file mode 100644
index 0000000000..8814c09365
--- /dev/null
+++ b/packages/client/web-react/src/bind.ts
@@ -0,0 +1,22 @@
+/**
+ * uSES bridge: turns any {@link ObservableSnapshot} into a typed selector
+ * hook. Client-side-rendered only, so no server snapshot is wired.
+ */
+import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/shim/with-selector.js'
+import type { ObservableSnapshot, SnapshotSelectorHook } from './store/index.ts'
+
+/**
+ * Bind an observable snapshot source to a typed uSES selector hook.
+ * subscribe/getSnapshot are captured once per source into stable closures
+ * (also re-binds `this` for method-based sources), so components never
+ * resubscribe across renders. Equality defaults to Object.is.
+ * @param w - snapshot source (Session object or snapshot store).
+ * @returns the selector hook.
+ */
+export function bindSnapshotSelector<T>(w: ObservableSnapshot<T>): SnapshotSelectorHook<T> {
+  const subscribe = (fn: () => void) => w.subscribe(fn)
+  const getSnapshot = () => w.getSnapshot()
+  return function useSelector<S>(sel: (s: T) => S, eq?: (a: S, b: S) => boolean): S {
+    return useSyncExternalStoreWithSelector(subscribe, getSnapshot, undefined, sel, eq)
+  }
+}
diff --git a/packages/client/web-react/src/env.d.ts b/packages/client/web-react/src/env.d.ts
new file mode 100644
index 0000000000..54d3d9d8f3
--- /dev/null
+++ b/packages/client/web-react/src/env.d.ts
@@ -0,0 +1,5 @@
+/**
+ * Bundler-replaced NODE_ENV: vite/tsdown substitute the literal, so browsers
+ * never evaluate a bare `process`. tsconfig carries no node types on purpose.
+ */
+declare const process: { env: { NODE_ENV?: string } }
diff --git a/packages/client/web-react/src/index.ts b/packages/client/web-react/src/index.ts
new file mode 100644
index 0000000000..b574781b58
--- /dev/null
+++ b/packages/client/web-react/src/index.ts
@@ -0,0 +1,41 @@
+/**
+ * ctx-to-React glue: uSES bridge, SessionProvider (dependency-inverted),
+ * scopedSlots outlet factory, useInvoke. Contract: api-contracts v3 section 2.
+ */
+import type { ReactNode } from 'react'
+import type { SnapshotSelectorHook } from './store/index.ts'
+
+export type {
+  ObservableSnapshot, SnapshotSelectorHook, SnapshotStore,
+} from './store/index.ts'
+export { createSnapshotStore, shallowEqual } from './store/index.ts'
+export { bindSnapshotSelector } from './bind.ts'
+
+/**
+ * Selector hook over a session's conversation snapshot. Wide (`object`) by
+ * default inside this dependency-inverted package; runtime narrows it once at
+ * its export surface (`UseSession<ConversationSnapshot>`) — the snapshot type
+ * never flows back into web-react.
+ */
+export type UseSession<Snap extends object = object> = SnapshotSelectorHook<Snap>
+
+/** Session assembly handle narrowed from ui-slots' structural form. */
+export interface SessionBinding<Snap extends object = object> {
+  readonly sessionId: string
+  readonly session: { useSelector: UseSession<Snap> }
+  readonly ctx: unknown
+}
+
+/** SessionProvider dependency surface (inverted: web-react never imports runtime). */
+export interface SessionProviderDeps {
+  useCurrent: () => string | undefined
+  resolveBinding: (id: string) => SessionBinding | undefined
+  /** Assembler-owned body: the shell closes over its own scopedSlots to render the session slots. */
+  renderBody: (id: string) => ReactNode
+}
+
+export { createSessionProvider, RootBindingProvider, SlotAssemblyError, useRootBinding, useSessionBinding } from './session-provider.tsx'
+
+export { scopedSlots } from './scoped-slots.tsx'
+
+export { useInvoke } from './use-invoke.ts'
diff --git a/packages/client/web-react/src/invariant.ts b/packages/client/web-react/src/invariant.ts
new file mode 100644
index 0000000000..aff9c09cd3
--- /dev/null
+++ b/packages/client/web-react/src/invariant.ts
@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-web-react`.
+ * @module @deepseek-ai/dsh-client-web-react/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-web-react'
+
+/** Cordis companion plugin name. */
+export const name = 'client-web-react-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: pure ctx-to-React glue — it emits no cordis events
+ * and owns no cross-plugin mutable relation; store batching, selector
+ * equality short-circuits, and inject-cache identity are asserted directly
+ * by this package's behavior specs.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/client/web-react/src/scoped-slots.tsx b/packages/client/web-react/src/scoped-slots.tsx
new file mode 100644
index 0000000000..d71dc0f96f
--- /dev/null
+++ b/packages/client/web-react/src/scoped-slots.tsx
@@ -0,0 +1,191 @@
+/**
+ * ScopedSlots factory: the sole render surface over the slot registry.
+ * renderSlot subscribes through uSES (SlotCore.subscribe/getVersion), renders
+ * per slot kind, wraps every entry in an error boundary, and merges props from
+ * three sources: standard injection (session slots get useSession), the
+ * registrant's cached inject factory, then owner props (owner wins).
+ *
+ * Typing model (slot type-chain design §4): the key stays generic (`K`) from
+ * renderSlot down to the outlet, so `entries<K>()` returns typed entries and
+ * the per-entry render path is monomorphic — no existential casts in loops.
+ */
+import { Component, useSyncExternalStore, type FC, type ReactNode } from 'react'
+import type {
+  RenderOpts, RootBinding, ScopedSlots, SessionBinding as SlotSessionBinding,
+  SlotCore, SlotEntry, SlotMap,
+} from '@deepseek-ai/dsh-client-ui-slots'
+import { SlotAssemblyError, useRootBinding, useSessionBinding } from './session-provider.tsx'
+
+type AnyKey = keyof SlotMap & string
+type EntryOf<K extends AnyKey> = SlotEntry<SlotMap[K]>
+type InjectedProps = Record<string, unknown>
+
+/**
+ * Inject results cache: root slots per entry, session slots per (entry x binding).
+ * WeakMap keys are the entry objects (stable across entries() snapshots per
+ * the SlotCore contract); values are the registrant's injected share. Storage
+ * erases the per-entry `I` — the single budgeted cast per cache restores it.
+ */
+const rootInjectCache = new WeakMap<object, InjectedProps>()
+const sessionInjectCache = new WeakMap<object, WeakMap<object, InjectedProps>>()
+
+function cachedRootInject<K extends AnyKey>(entry: EntryOf<K>, binding: RootBinding): InjectedProps {
+  const inject = entry.options?.inject
+  if (!inject) return {}
+  let props = rootInjectCache.get(entry)
+  if (!props) {
+    // Root-scope factories accept RootBinding; the conditional-type parameter
+    // only fails to dispatch because K is generic here — the outlet's
+    // spec.scope branch guarantees the scope side (budgeted cast, one per cache).
+    props = (inject as (b: RootBinding) => InjectedProps)(binding)
+    rootInjectCache.set(entry, props)
+  }
+  return props
+}
+
+function cachedSessionInject<K extends AnyKey>(entry: EntryOf<K>, binding: SlotSessionBinding): InjectedProps {
+  const inject = entry.options?.inject
+  if (!inject) return {}
+  let perBinding = sessionInjectCache.get(entry)
+  if (!perBinding) {
+    perBinding = new WeakMap()
+    sessionInjectCache.set(entry, perBinding)
+  }
+  let props = perBinding.get(binding)
+  if (!props) {
+    // Same scope-dispatch note as the root cache: the session branch of the
+    // outlet guarantees this factory's binding side (budgeted cast).
+    props = (inject as (b: SlotSessionBinding) => InjectedProps)(binding)
+    perBinding.set(binding, props)
+  }
+  return props
+}
+
+/**
+ * Per-entry isolation: one registrant crashing (component render or inject
+ * factory) must not take down siblings. Assembly errors (missing providers)
+ * rethrow — a miswired shell must fail loud, not degrade into fallbacks.
+ */
+class SlotErrorBoundary extends Component<
+  { slotKey: string; children: ReactNode }, { failed: boolean }
+> {
+  override state = { failed: false }
+  static getDerivedStateFromError(error: unknown): { failed: boolean } {
+    if (error instanceof SlotAssemblyError) throw error
+    return { failed: true }
+  }
+  override componentDidCatch(error: unknown): void {
+    console.error(`slot entry crashed in '${this.props.slotKey}':`, error)
+  }
+  override render(): ReactNode {
+    if (this.state.failed) return <div data-slot-error={this.props.slotKey} />
+    return this.props.children
+  }
+}
+
+interface OutletProps<K extends AnyKey> {
+  core: SlotCore
+  slotKey: K
+  ownerProps: object
+  opts?: RenderOpts | undefined
+}
+
+/**
+ * One rendered entry: standard injection + cached inject + owner props.
+ * Inject factories run inside these component bodies ON PURPOSE — the outlet
+ * wraps every Entry element in the per-entry error boundary, so a throwing
+ * factory blacks out only its own entry. The three-source merge composes the
+ * entry's full props contract; TS cannot prove the composition against
+ * `SlotMap[K]['props']` (the shares are erased at the registry boundary), so
+ * each Entry renders through a props-widened view of the component — the
+ * design-budgeted composition point, one per scope branch.
+ */
+function SessionEntry<K extends AnyKey>({ entry, ownerProps }: {
+  entry: EntryOf<K>; ownerProps: object
+}) {
+  const binding = useSessionBinding()
+  const Comp = entry.component as FC<InjectedProps>
+  const injected = cachedSessionInject(entry, binding)
+  return <Comp useSession={binding.session.useSelector} {...injected} {...ownerProps} />
+}
+
+function RootEntry<K extends AnyKey>({ entry, ownerProps }: {
+  entry: EntryOf<K>; ownerProps: object
+}) {
+  const hasInject = entry.options?.inject !== undefined
+  const Comp = entry.component as FC<InjectedProps>
+  // Only inject-bearing entries need the root binding channel; plain entries
+  // must render fine in shells that never mounted RootBindingProvider.
+  if (!hasInject) return <Comp {...ownerProps} />
+  return <RootInjectEntry entry={entry} ownerProps={ownerProps} />
+}
+
+function RootInjectEntry<K extends AnyKey>({ entry, ownerProps }: {
+  entry: EntryOf<K>; ownerProps: object
+}) {
+  const binding = useRootBinding()
+  const Comp = entry.component as FC<InjectedProps>
+  const injected = cachedRootInject(entry, binding)
+  return <Comp {...injected} {...ownerProps} />
+}
+
+function SlotOutlet<K extends AnyKey>({ core, slotKey, ownerProps, opts }: OutletProps<K>) {
+  // Version tick drives entries() re-read; SlotCore batches per microtask.
+  useSyncExternalStore(
+    (fn) => core.subscribe(slotKey, fn),
+    () => core.getVersion(slotKey),
+  )
+  const spec = core.spec(slotKey)
+  if (!spec) throw new Error(`renderSlot('${slotKey}') before define`)
+  const entries = core.entries(slotKey)
+  const Entry: FC<{ entry: EntryOf<K>; ownerProps: object }> =
+    spec.scope === 'session' ? SessionEntry : RootEntry
+
+  // The boundary must wrap the Entry ELEMENT, not live inside it: inject
+  // factories and binding lookups run in the Entry body and must land in the
+  // per-entry fallback rather than escaping to the tree above.
+  const guarded = (entry: EntryOf<K>, key?: string | number) => (
+    <SlotErrorBoundary slotKey={slotKey} key={key}>
+      <Entry entry={entry} ownerProps={ownerProps} />
+    </SlotErrorBoundary>
+  )
+
+  if (spec.kind === 'single') {
+    const entry = entries[0]
+    if (!entry) return <>{opts?.fallback ?? null}</>
+    return guarded(entry)
+  }
+  if (spec.kind === 'keyed') {
+    const entry = entries.find((e) => e.options && 'key' in e.options && e.options.key === opts?.entryKey)
+    if (!entry) return <>{opts?.fallback ?? null}</>
+    return guarded(entry)
+  }
+  // list: registration order refined by explicit order, optional id filter.
+  const withListOptions = entries.map((entry) => ({
+    entry,
+    id: entry.options && 'id' in entry.options ? entry.options.id : undefined,
+    order: entry.options && 'order' in entry.options ? entry.options.order ?? 0 : 0,
+  }))
+  let list = [...withListOptions].sort((a, b) => a.order - b.order)
+  if (opts?.only !== undefined) list = list.filter((item) => item.id === opts.only)
+  if (list.length === 0) return <>{opts?.fallback ?? null}</>
+  return <>{list.map((item, i) => guarded(item.entry, item.id ?? i))}</>
+}
+
+/**
+ * Build a whitelist-narrowed ScopedSlots render surface over a SlotCore.
+ * The type parameter narrows compile-time access; the runtime whitelist
+ * backstops plain-JS callers.
+ * @param core - the slot registry core.
+ * @param keys - whitelisted slot keys the caller may render.
+ * @returns the ScopedSlots facade.
+ */
+export function scopedSlots<K extends AnyKey>(core: SlotCore, ...keys: K[]): ScopedSlots<K> {
+  const allowed = new Set<string>(keys)
+  return {
+    renderSlot(key, props, opts) {
+      if (!allowed.has(key)) throw new Error(`slot '${key}' is not in this ScopedSlots whitelist`)
+      return <SlotOutlet core={core} slotKey={key} ownerProps={props} opts={opts} />
+    },
+  }
+}
diff --git a/packages/client/web-react/src/session-provider.tsx b/packages/client/web-react/src/session-provider.tsx
new file mode 100644
index 0000000000..8b254ed4a1
--- /dev/null
+++ b/packages/client/web-react/src/session-provider.tsx
@@ -0,0 +1,74 @@
+/**
+ * SessionProvider (dependency-inverted; never imports runtime) plus the two
+ * binding contexts the slot outlet reads: per-session {@link BindingContext}
+ * written here, and the root-binding channel written by the shell through
+ * {@link RootBindingProvider}.
+ */
+import { createContext, useContext, type FC, type ReactNode } from 'react'
+import type { RootBinding } from '@deepseek-ai/dsh-client-ui-slots'
+import type { SessionBinding, SessionProviderDeps } from './index.ts'
+
+/** Session binding for the subtree under SessionProvider (module-private write). */
+const BindingContext = createContext<SessionBinding | null>(null)
+
+/**
+ * A missing-provider assembly error: the shell wired the tree wrong. The slot
+ * error boundary rethrows this class so misassembly stays fail-loud while
+ * registrant errors (inject factories, entry components) are contained
+ * per entry.
+ */
+export class SlotAssemblyError extends Error {}
+
+/**
+ * Read the enclosing session binding; throws outside a SessionProvider
+ * subtree (session slots must not render without a session).
+ * @returns the enclosing binding.
+ */
+export function useSessionBinding(): SessionBinding {
+  const binding = useContext(BindingContext)
+  if (!binding) throw new SlotAssemblyError('session slot rendered outside SessionProvider')
+  return binding
+}
+
+const RootBindingContext = createContext<RootBinding | null>(null)
+
+/**
+ * Root-binding supply channel: the shell mounts this once at the top so root
+ * slot inject factories receive their assembly handle.
+ */
+export const RootBindingProvider: FC<{ value: RootBinding; children?: ReactNode }> =
+  ({ value, children }) => (
+    <RootBindingContext.Provider value={value}>{children}</RootBindingContext.Provider>
+  )
+
+/**
+ * Read the root binding; throws when the shell forgot to mount
+ * {@link RootBindingProvider} (root inject factories need ctx).
+ * @returns the root binding.
+ */
+export function useRootBinding(): RootBinding {
+  const binding = useContext(RootBindingContext)
+  if (!binding) throw new SlotAssemblyError('root slot inject requires RootBindingProvider above')
+  return binding
+}
+
+/**
+ * Build the single SessionProvider component: subscribes to the current
+ * session id, resolves its binding (stable reference), remounts the body
+ * under key={id}, and delegates body rendering to the assembler's renderBody
+ * (slot ownership stays with layout; the provider knows no slot names).
+ * @param deps - inverted dependencies.
+ * @returns the provider component.
+ */
+export function createSessionProvider(deps: SessionProviderDeps): FC<{ renderEmpty?: () => ReactNode }> {
+  return function SessionProvider({ renderEmpty }) {
+    const id = deps.useCurrent()
+    const binding = id === undefined ? undefined : deps.resolveBinding(id)
+    if (id === undefined || !binding) return <>{renderEmpty?.() ?? null}</>
+    return (
+      <BindingContext.Provider value={binding} key={id}>
+        {deps.renderBody(id)}
+      </BindingContext.Provider>
+    )
+  }
+}
diff --git a/packages/client/web-react/src/store/index.ts b/packages/client/web-react/src/store/index.ts
new file mode 100644
index 0000000000..5c20d26150
--- /dev/null
+++ b/packages/client/web-react/src/store/index.ts
@@ -0,0 +1,150 @@
+/**
+ * Snapshot store engine (zustand vanilla + immer + subscribeWithSelector +
+ * rafFlush middleware + opt-in persist + dev freeze). The only data contract
+ * consumed by React is {@link ObservableSnapshot}.
+ */
+import { createStore, type StoreApi } from 'zustand/vanilla'
+import { subscribeWithSelector } from 'zustand/middleware'
+import { shallow } from 'zustand/shallow'
+import { produce } from 'immer'
+import { bindSnapshotSelector } from '../bind.ts'
+
+/** Minimal observable snapshot source: Session objects and snapshot stores both satisfy it. */
+export interface ObservableSnapshot<T> { getSnapshot(): T; subscribe(fn: () => void): () => void }
+
+/** Writable snapshot store with an attached typed selector hook. */
+export interface SnapshotStore<T> extends ObservableSnapshot<T> {
+  /**
+   * Mutate the state through an immer draft.
+   * @param mutator - draft mutator.
+   */
+  update(mutator: (draft: T) => void): void
+  /**
+   * Replace the state wholesale.
+   * @param next - next state.
+   */
+  set(next: T): void
+  readonly useSelector: SnapshotSelectorHook<T>
+}
+
+/** Typed selector hook: equality defaults to Object.is; pass shallowEqual for object slices. */
+export type SnapshotSelectorHook<T> = <S>(sel: (s: T) => S, eq?: (a: S, b: S) => boolean) => S
+
+/**
+ * Shallow equality for selector slices (re-export of zustand/shallow semantics).
+ * @param a - left value.
+ * @param b - right value.
+ * @returns whether the values are shallowly equal.
+ */
+export function shallowEqual(a: unknown, b: unknown): boolean {
+  return shallow(a, b)
+}
+
+/** Batches subscriber notification into one flush per animation frame. */
+function rafBatch(notify: () => void): () => void {
+  // Fall back to microtask batching where rAF is absent (node unit tests);
+  // both preserve the N-changes=1-notification contract within a tick.
+  const schedule: (fn: () => void) => void =
+    typeof requestAnimationFrame === 'function'
+      ? (fn) => { requestAnimationFrame(() => { fn() }) }
+      : (fn) => { queueMicrotask(fn) }
+  let scheduled = false
+  return () => {
+    if (scheduled) return
+    scheduled = true
+    schedule(() => {
+      scheduled = false
+      notify()
+    })
+  }
+}
+
+/**
+ * Create a snapshot store.
+ *
+ * Flush default is 'sync' (controlled inputs need same-tick echo); frame-driven
+ * stores opt into 'raf', where a frame's worth of updates coalesces into one
+ * notification. Known raf-mode tradeoff: a component mounting mid-frame reads
+ * fresh state while existing subscribers hear it next flush — transient
+ * frame-level skew, same nature as the object layer's microtask batching.
+ *
+ * @param init - initial state.
+ * @param opts - flush mode and opt-in persistence (localStorage, keyed by name).
+ * @returns the store.
+ */
+export function createSnapshotStore<T>(
+  init: T, opts?: { flush?: 'raf' | 'sync'; persist?: { name: string } }): SnapshotStore<T> {
+  // Immer enters through produce() in update() below (identical semantics to
+  // the immer middleware without its setState-signature mutator generics).
+  const withSelector = subscribeWithSelector(() => init)
+  const api: StoreApi<T> = createStore<T>()(withSelector)
+  if (opts?.persist) attachPersistence(api, opts.persist.name)
+
+  let subscribe = (fn: () => void) => api.subscribe(fn)
+  if (opts?.flush === 'raf') {
+    const listeners = new Set<() => void>()
+    const flush = rafBatch(() => { for (const fn of [...listeners]) fn() })
+    api.subscribe(flush)
+    subscribe = (fn: () => void) => {
+      listeners.add(fn)
+      return () => { listeners.delete(fn) }
+    }
+  }
+
+  const store: SnapshotStore<T> = {
+    getSnapshot: () => api.getState(),
+    subscribe: fn => subscribe(fn),
+    update: (mutator) => {
+      // Immer's produce (not setState's partial-merge path) so scalar and
+      // array roots replace correctly; produce also freezes in dev.
+      api.setState(produce(api.getState(), (draft) => { mutator(draft as T) }), true)
+    },
+    set: (next) => {
+      api.setState(devFreeze(next), true)
+    },
+    useSelector: undefined as unknown as SnapshotSelectorHook<T>,
+  }
+  ;(store as { useSelector: SnapshotSelectorHook<T> }).useSelector = bindSnapshotSelector(store)
+  return store
+}
+
+/**
+ * Whole-value JSON persistence to localStorage. Hand-rolled instead of the
+ * zustand persist middleware: its write path spreads state into an object
+ * (`partialize({ ...get() })`), exploding primitive state (a persisted string
+ * draft becomes {0:'h',1:'e',...}) — not fixable via merge/deserialize options
+ * because the corruption happens before serialization. Storage failures
+ * (quota, private mode) only disable persistence, never break the store.
+ */
+function attachPersistence<T>(api: StoreApi<T>, name: string): void {
+  try {
+    const raw = localStorage.getItem(name)
+    if (raw !== null) {
+      api.setState(devFreeze(JSON.parse(raw) as T), true)
+    }
+  } catch (error) {
+    console.error(`snapshot store '${name}' rehydration failed:`, error)
+  }
+  api.subscribe((state) => {
+    try {
+      localStorage.setItem(name, JSON.stringify(state))
+    } catch (error) {
+      console.error(`snapshot store '${name}' persistence failed:`, error)
+    }
+  })
+}
+
+/** Deep-freeze wholesale-set state outside production: set() bypasses immer's freeze. */
+function devFreeze<T>(value: T): T {
+  if (process.env.NODE_ENV === 'production') return value
+  deepFreeze(value)
+  return value
+}
+
+function deepFreeze(value: unknown): void {
+  if (typeof value !== 'object' || value === null || Object.isFrozen(value)) return
+  Object.freeze(value)
+  for (const key of Reflect.ownKeys(value)) {
+    deepFreeze((value as Record<PropertyKey, unknown>)[key])
+  }
+}
diff --git a/packages/client/web-react/src/use-invoke.ts b/packages/client/web-react/src/use-invoke.ts
new file mode 100644
index 0000000000..9e36057e27
--- /dev/null
+++ b/packages/client/web-react/src/use-invoke.ts
@@ -0,0 +1,62 @@
+/**
+ * useInvoke: wrap an async action into a stable trigger plus pending flag.
+ * Pending is tracked in a per-hook external store read through uSES instead
+ * of setState, keeping the render body side-effect free and the invoke
+ * reference stable across renders (idempotent-hook rules).
+ */
+import { useRef, useSyncExternalStore } from 'react'
+
+interface InvokeCell {
+  inflight: number
+  listeners: Set<() => void>
+  fn: () => Promise<unknown>
+  invoke: () => void
+  subscribe: (fn: () => void) => () => void
+  getPending: () => boolean
+}
+
+function createCell(fn: () => Promise<unknown>): InvokeCell {
+  const cell: InvokeCell = {
+    inflight: 0,
+    listeners: new Set(),
+    fn,
+    invoke: () => {
+      bump(cell, 1)
+      cell.fn().catch((error: unknown) => {
+        // Domain errors surface through the event echo (session log); the
+        // framework only guarantees pending resets and leaves a trace.
+        console.error('useInvoke action failed:', error)
+      }).finally(() => { bump(cell, -1) })
+    },
+    subscribe: (listener) => {
+      cell.listeners.add(listener)
+      return () => { cell.listeners.delete(listener) }
+    },
+    getPending: () => cell.inflight > 0,
+  }
+  return cell
+}
+
+function bump(cell: InvokeCell, delta: number): void {
+  const wasPending = cell.inflight > 0
+  cell.inflight += delta
+  if (wasPending !== cell.inflight > 0) {
+    for (const listener of [...cell.listeners]) listener()
+  }
+}
+
+/**
+ * Wrap an async action into a stable invoke callback plus pending flag.
+ * Concurrent invocations are counted: pending stays true until the last
+ * in-flight call settles. The latest `fn` is always the one invoked.
+ * @param fn - async action.
+ * @returns invoke trigger and pending state.
+ */
+export function useInvoke(fn: () => Promise<unknown>): [invoke: () => void, pending: boolean] {
+  const ref = useRef<InvokeCell | null>(null)
+  ref.current ??= createCell(fn)
+  const cell = ref.current
+  cell.fn = fn
+  const pending = useSyncExternalStore(cell.subscribe, cell.getPending)
+  return [cell.invoke, pending]
+}
diff --git a/packages/client/web-react/src/use-sync-external-store.d.ts b/packages/client/web-react/src/use-sync-external-store.d.ts
new file mode 100644
index 0000000000..251a9c4530
--- /dev/null
+++ b/packages/client/web-react/src/use-sync-external-store.d.ts
@@ -0,0 +1,14 @@
+/**
+ * Local typings for use-sync-external-store 1.2.0: the package ships no types
+ * and the DefinitelyTyped package is unavailable offline. Mirrors the shim's
+ * with-selector build (the only entry this package consumes).
+ */
+declare module 'use-sync-external-store/shim/with-selector.js' {
+  export function useSyncExternalStoreWithSelector<Snapshot, Selection>(
+    subscribe: (onStoreChange: () => void) => () => void,
+    getSnapshot: () => Snapshot,
+    getServerSnapshot: undefined | null | (() => Snapshot),
+    selector: (snapshot: Snapshot) => Selection,
+    isEqual?: (a: Selection, b: Selection) => boolean,
+  ): Selection
+}
diff --git a/packages/client/web-react/tests/bind.spec.tsx b/packages/client/web-react/tests/bind.spec.tsx
new file mode 100644
index 0000000000..e60b7d1098
--- /dev/null
+++ b/packages/client/web-react/tests/bind.spec.tsx
@@ -0,0 +1,125 @@
+// @vitest-environment jsdom
+import { StrictMode } from 'react'
+import { describe, expect, it, vi } from 'vitest'
+import { act, render } from '@testing-library/react'
+import { bindSnapshotSelector, shallowEqual } from '@deepseek-ai/dsh-client-web-react'
+import type { ObservableSnapshot, SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react/store'
+
+interface Snap { a: number; b: number }
+
+/** Hand-rolled observable source so subscription counting is exact. */
+function makeSource(initial: Snap) {
+  let state = initial
+  const listeners = new Set<() => void>()
+  let subscribeCalls = 0
+  const source: ObservableSnapshot<Snap> = {
+    getSnapshot: () => state,
+    subscribe: (fn) => {
+      subscribeCalls += 1
+      listeners.add(fn)
+      return () => { listeners.delete(fn) }
+    },
+  }
+  return {
+    source,
+    set: (next: Snap) => {
+      state = next
+      for (const fn of [...listeners]) fn()
+    },
+    stats: { get subscribeCalls() { return subscribeCalls }, get active() { return listeners.size } },
+  }
+}
+
+function Harness<S>({ useSelector, sel, eq, probe }: {
+  useSelector: SnapshotSelectorHook<Snap>
+  sel: (s: Snap) => S
+  eq?: (a: S, b: S) => boolean
+  probe: { renders: number; value?: S }
+}) {
+  probe.renders += 1
+  probe.value = useSelector(sel, eq)
+  return null
+}
+
+describe('bindSnapshotSelector', () => {
+  it('re-renders on selected change and bails out when the slice is equal', () => {
+    const { source, set } = makeSource({ a: 1, b: 10 })
+    const useSelector = bindSnapshotSelector(source)
+    const probe = { renders: 0, value: undefined as number | undefined }
+    render(<Harness useSelector={useSelector} sel={(s) => s.a} probe={probe} />)
+    expect(probe.value).toBe(1)
+    const before = probe.renders
+    act(() => { set({ a: 1, b: 11 }) })   // unrelated field: Object.is bail
+    expect(probe.renders).toBe(before)
+    act(() => { set({ a: 2, b: 11 }) })
+    expect(probe.renders).toBe(before + 1)
+    expect(probe.value).toBe(2)
+  })
+
+  it('supports custom equality for object slices', () => {
+    const { source, set } = makeSource({ a: 1, b: 10 })
+    const useSelector = bindSnapshotSelector(source)
+    const probe = { renders: 0, value: undefined as { a: number } | undefined }
+    render(<Harness useSelector={useSelector} sel={(s) => ({ a: s.a })} eq={shallowEqual} probe={probe} />)
+    const before = probe.renders
+    act(() => { set({ a: 1, b: 99 }) })   // fresh object, shallow-equal slice
+    expect(probe.renders).toBe(before)
+    act(() => { set({ a: 5, b: 99 }) })
+    expect(probe.renders).toBe(before + 1)
+    expect(probe.value).toEqual({ a: 5 })
+  })
+
+  it('does not resubscribe across re-renders of the same component', () => {
+    const { source, set, stats } = makeSource({ a: 1, b: 10 })
+    const useSelector = bindSnapshotSelector(source)
+    const probe = { renders: 0, value: undefined as number | undefined }
+    const { rerender } = render(<Harness useSelector={useSelector} sel={(s) => s.a} probe={probe} />)
+    const after = stats.subscribeCalls
+    rerender(<Harness useSelector={useSelector} sel={(s) => s.a} probe={probe} />)
+    act(() => { set({ a: 2, b: 10 }) })
+    rerender(<Harness useSelector={useSelector} sel={(s) => s.a} probe={probe} />)
+    expect(stats.subscribeCalls).toBe(after)
+  })
+
+  it('is StrictMode-safe and cleans up subscriptions on unmount', () => {
+    const { source, stats } = makeSource({ a: 1, b: 10 })
+    const useSelector = bindSnapshotSelector(source)
+    const probe = { renders: 0, value: undefined as number | undefined }
+    const view = render(
+      <StrictMode>
+        <Harness useSelector={useSelector} sel={(s) => s.a} probe={probe} />
+      </StrictMode>,
+    )
+    expect(probe.value).toBe(1)
+    view.unmount()
+    expect(stats.active).toBe(0)
+  })
+
+  it('binds method-style sources without losing this', () => {
+    class MethodSource implements ObservableSnapshot<Snap> {
+      private state: Snap = { a: 7, b: 0 }
+      private listeners = new Set<() => void>()
+      getSnapshot(): Snap { return this.state }
+      subscribe(fn: () => void): () => void {
+        this.listeners.add(fn)
+        return () => { this.listeners.delete(fn) }
+      }
+    }
+    const useSelector = bindSnapshotSelector(new MethodSource())
+    const probe = { renders: 0, value: undefined as number | undefined }
+    render(<Harness useSelector={useSelector} sel={(s) => s.a} probe={probe} />)
+    expect(probe.value).toBe(7)
+  })
+
+  it('memoizes the selector result against getSnapshot spam', () => {
+    const { source } = makeSource({ a: 1, b: 10 })
+    const sel = vi.fn((s: Snap) => s.a)
+    const useSelector = bindSnapshotSelector(source)
+    const probe = { renders: 0, value: undefined as number | undefined }
+    const { rerender } = render(<Harness useSelector={useSelector} sel={sel} probe={probe} />)
+    const calls = sel.mock.calls.length
+    rerender(<Harness useSelector={useSelector} sel={sel} probe={probe} />)
+    // Same snapshot + same selector reference: no recompute beyond bookkeeping.
+    expect(sel.mock.calls.length).toBeLessThanOrEqual(calls + 1)
+  })
+})
diff --git a/packages/client/web-react/tests/scoped-slots-real-core.spec.tsx b/packages/client/web-react/tests/scoped-slots-real-core.spec.tsx
new file mode 100644
index 0000000000..3d7fcc0715
--- /dev/null
+++ b/packages/client/web-react/tests/scoped-slots-real-core.spec.tsx
@@ -0,0 +1,70 @@
+// @vitest-environment jsdom
+/**
+ * Integration against the real ui-slots SlotCore (T1): the outlet's uSES
+ * pairing rides the real subscribe/getVersion/entries surfaces, and the
+ * whitelist narrows at compile time (expect-error negative samples).
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { act, render } from '@testing-library/react'
+import { SlotCore } from '@deepseek-ai/dsh-client-ui-slots'
+import { scopedSlots } from '@deepseek-ai/dsh-client-web-react'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    'spec.single': { kind: 'single'; scope: 'root'; props: { label?: string } }
+    'spec.list': { kind: 'list'; scope: 'root'; props: object }
+    'spec.off-limits': { kind: 'single'; scope: 'root'; props: object }
+  }
+}
+
+describe('scopedSlots over the real SlotCore', () => {
+  it('renders registrations live: define, register, dispose back to fallback', async () => {
+    const core = new SlotCore()
+    core.define('spec.single', { kind: 'single', scope: 'root' })
+    const slots = scopedSlots(core, 'spec.single')
+    const view = render(<>{slots.renderSlot('spec.single', {}, { fallback: <i>none</i> })}</>)
+    expect(view.container.textContent).toBe('none')
+    let dispose = () => {}
+    // The real core batches subscriber notification per microtask: async act.
+    await act(async () => { dispose = core.register('spec.single', ({ label }) => <b>{label ?? 'on'}</b>) })
+    expect(view.container.textContent).toBe('on')
+    await act(async () => { dispose(); dispose() })   // disposer is idempotent in the real core
+    expect(view.container.textContent).toBe('none')
+  })
+
+  it('passes owner props through and orders list entries', () => {
+    const core = new SlotCore()
+    core.define('spec.single', { kind: 'single', scope: 'root' })
+    core.define('spec.list', { kind: 'list', scope: 'root' })
+    core.register('spec.single', ({ label }) => <b>{label}</b>)
+    core.register('spec.list', () => <span>2</span>, { id: 'two', order: 2 })
+    core.register('spec.list', () => <span>1</span>, { id: 'one', order: 1 })
+    const slots = scopedSlots(core, 'spec.single', 'spec.list')
+    const view = render(
+      <>
+        {slots.renderSlot('spec.single', { label: 'owner' })}
+        {slots.renderSlot('spec.list', {})}
+      </>,
+    )
+    expect(view.container.textContent).toBe('owner12')
+  })
+
+  it('fails loud when rendering a key that was never defined', () => {
+    const core = new SlotCore()
+    const slots = scopedSlots(core, 'spec.single')
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    expect(() => render(<>{slots.renderSlot('spec.single', {})}</>)).toThrow(/before define/)
+    spy.mockRestore()
+  })
+
+  it('narrows the whitelist at compile time and backstops at runtime', () => {
+    const core = new SlotCore()
+    core.define('spec.single', { kind: 'single', scope: 'root' })
+    core.define('spec.off-limits', { kind: 'single', scope: 'root' })
+    const slots = scopedSlots(core, 'spec.single')
+    // @ts-expect-error spec.off-limits is outside this ScopedSlots whitelist
+    expect(() => slots.renderSlot('spec.off-limits', {})).toThrow(/whitelist/)
+    // @ts-expect-error unknown keys are rejected even before whitelist narrowing
+    expect(() => slots.renderSlot('spec.nonexistent', {})).toThrow(/whitelist/)
+  })
+})
diff --git a/packages/client/web-react/tests/scoped-slots.spec.tsx b/packages/client/web-react/tests/scoped-slots.spec.tsx
new file mode 100644
index 0000000000..a5875777bf
--- /dev/null
+++ b/packages/client/web-react/tests/scoped-slots.spec.tsx
@@ -0,0 +1,274 @@
+// @vitest-environment jsdom
+import { describe, expect, it, vi } from 'vitest'
+import { act, render } from '@testing-library/react'
+import type {
+  FC } from 'react'
+import type {
+  InjectFactory, RootBinding, SlotCore, SlotEntry, SlotEntryDef, SlotSpec,
+} from '@deepseek-ai/dsh-client-ui-slots'
+import {
+  createSessionProvider, createSnapshotStore, RootBindingProvider, scopedSlots,
+  type SessionBinding, type SessionProviderDeps,
+} from '@deepseek-ai/dsh-client-web-react'
+
+/**
+ * Behavioral SlotCore fake (the real ui-slots is still a T0 stub): registration
+ * mutates entries, bumps the key version, and notifies subscribers synchronously
+ * (batching semantics belong to fw-slots' core, not this package's outlet).
+ */
+function makeFakeCore() {
+  const specs = new Map<string, SlotSpec<SlotEntryDef>>()
+  const entries = new Map<string, SlotEntry<SlotEntryDef>[]>()
+  const versions = new Map<string, number>()
+  const subs = new Map<string, Set<() => void>>()
+  const bump = (key: string) => {
+    versions.set(key, (versions.get(key) ?? 0) + 1)
+    for (const fn of [...(subs.get(key) ?? [])]) fn()
+  }
+  const core = {
+    define: (key: string, spec: SlotSpec<SlotEntryDef>) => {
+      specs.set(key, spec)
+      bump(key)
+      return () => { specs.delete(key); bump(key) }
+    },
+    // Options widened beyond SlotOptions<SlotEntryDef>: fake keys ('fake.list')
+    // are not in SlotMap, so calls resolve against this signature and need the
+    // list/keyed fields the conditional type would otherwise narrow away.
+    register: (
+      key: string, component: FC<object>,
+      options: { key?: string; id?: string; order?: number; label?: string; inject?: InjectFactory<SlotEntryDef> } = {},
+    ) => {
+      const list = entries.get(key) ?? []
+      const entry: SlotEntry<SlotEntryDef> = { component, options }
+      entries.set(key, [...list, entry])
+      bump(key)
+      return () => {
+        entries.set(key, (entries.get(key) ?? []).filter((e) => e !== entry))
+        bump(key)
+      }
+    },
+    entries: (key: string) => entries.get(key) ?? [],
+    spec: (key: string) => specs.get(key),
+    subscribe: (key: string, fn: () => void) => {
+      const set = subs.get(key) ?? new Set()
+      set.add(fn)
+      subs.set(key, set)
+      return () => { set.delete(fn) }
+    },
+    getVersion: (key: string) => versions.get(key) ?? 0,
+    onMutate: () => () => {},
+  }
+  return core as unknown as SlotCore & typeof core
+}
+
+const useSelectorStub = (() => { throw new Error('unused in these specs') }) as never
+
+const makeBinding = (sessionId: string): SessionBinding => ({
+  sessionId, session: { useSelector: useSelectorStub }, ctx: { tag: sessionId },
+})
+
+/** Mount ui under a SessionProvider bound to one switchable session. */
+function sessionHarness(body: (id: string) => React.ReactNode, bindings: Record<string, SessionBinding>) {
+  const current = createSnapshotStore<{ id: string | undefined }>({ id: undefined })
+  const deps: SessionProviderDeps = {
+    useCurrent: () => current.useSelector((s) => s.id),
+    resolveBinding: (id) => bindings[id],
+    renderBody: body,
+  }
+  const Provider = createSessionProvider(deps)
+  return { current, Provider }
+}
+
+describe('scopedSlots basics', () => {
+  it('throws on renderSlot before define and on non-whitelisted keys', () => {
+    const core = makeFakeCore()
+    const slots = scopedSlots(core, 'fake.root' as never)
+    expect(() => slots.renderSlot('fake.session' as never, {})).toThrow(/whitelist/)
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    expect(() => render(<>{slots.renderSlot('fake.root' as never, {})}</>)).toThrow(/before define/)
+    spy.mockRestore()
+  })
+
+  it('renders single-kind root slots, falls back when empty, live-updates on register/dispose', () => {
+    const core = makeFakeCore()
+    core.define('fake.root', { kind: 'single', scope: 'root' })
+    const slots = scopedSlots(core, 'fake.root' as never)
+    const view = render(<>{slots.renderSlot('fake.root' as never, {}, { fallback: <i>none</i> })}</>)
+    expect(view.container.textContent).toBe('none')
+    let dispose = () => {}
+    act(() => { dispose = core.register('fake.root', () => <b>SB</b>) })
+    expect(view.container.textContent).toBe('SB')
+    act(() => { dispose() })
+    expect(view.container.textContent).toBe('none')
+  })
+
+  it('renders list slots in order, honors only-filter, keyed slots dispatch by entryKey', () => {
+    const core = makeFakeCore()
+    core.define('fake.list', { kind: 'list', scope: 'root' })
+    core.define('fake.keyed', { kind: 'keyed', scope: 'root' })
+    core.register('fake.list', () => <span>b</span>, { id: 'b', order: 2 })
+    core.register('fake.list', () => <span>a</span>, { id: 'a', order: 1 })
+    core.register('fake.keyed', () => <span>goal</span>, { key: 'goal' })
+    const slots = scopedSlots(core, 'fake.list' as never, 'fake.keyed' as never)
+    const list = render(<>{slots.renderSlot('fake.list' as never, {})}</>)
+    expect(list.container.textContent).toBe('ab')
+    const only = render(<>{slots.renderSlot('fake.list' as never, {}, { only: 'b' })}</>)
+    expect(only.container.textContent).toBe('b')
+    const hit = render(<>{slots.renderSlot('fake.keyed' as never, {}, { entryKey: 'goal' })}</>)
+    expect(hit.container.textContent).toBe('goal')
+    const miss = render(
+      <>{slots.renderSlot('fake.keyed' as never, {}, { entryKey: 'nope', fallback: <i>fb</i> })}</>)
+    expect(miss.container.textContent).toBe('fb')
+  })
+
+  it('contains a throwing root inject factory to its own entry (P1 whiteout regression)', () => {
+    const core = makeFakeCore()
+    core.define('fake.list', { kind: 'list', scope: 'root' })
+    core.register('fake.list', () => <span>never</span>, {
+      id: 'bad', order: 1,
+      inject: (() => { throw new Error('inject boom') }) as unknown as InjectFactory<SlotEntryDef>,
+    })
+    core.register('fake.list', () => <span>alive</span>, { id: 'ok', order: 2 })
+    const slots = scopedSlots(core, 'fake.list' as never)
+    const root: RootBinding = { ctx: {} }
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const view = render(
+      <RootBindingProvider value={root}>
+        <main>{slots.renderSlot('fake.list' as never, {})}</main>
+      </RootBindingProvider>,
+    )
+    spy.mockRestore()
+    // The failing entry blacks out alone; the sibling and the tree above survive.
+    expect(view.container.querySelector('main')).not.toBeNull()
+    expect(view.container.textContent).toBe('alive')
+    expect(view.container.querySelector('[data-slot-error]')).not.toBeNull()
+  })
+
+  it('contains a throwing session inject factory to its own entry', () => {
+    const core = makeFakeCore()
+    core.define('fake.session', { kind: 'single', scope: 'session' })
+    core.register('fake.session', () => <span>never</span>, {
+      inject: (() => { throw new Error('session inject boom') }) as unknown as InjectFactory<SlotEntryDef>,
+    })
+    const slots = scopedSlots(core, 'fake.session' as never)
+    const bindings = { s1: makeBinding('s1') }
+    const { current, Provider } = sessionHarness(
+      (id) => <main data-shell={id}>{slots.renderSlot('fake.session' as never, {})}</main>, bindings)
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const view = render(<Provider />)
+    act(() => { current.update((d) => { d.id = 's1' }) })
+    spy.mockRestore()
+    expect(view.container.querySelector('[data-shell]')).not.toBeNull()
+    expect(view.container.querySelector('[data-slot-error]')).not.toBeNull()
+  })
+
+  it('isolates a crashing entry without collapsing siblings', () => {
+    const core = makeFakeCore()
+    core.define('fake.list', { kind: 'list', scope: 'root' })
+    core.register('fake.list', () => { throw new Error('entry boom') }, { id: 'bad', order: 1 })
+    core.register('fake.list', () => <span>alive</span>, { id: 'ok', order: 2 })
+    const slots = scopedSlots(core, 'fake.list' as never)
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const view = render(<>{slots.renderSlot('fake.list' as never, {})}</>)
+    spy.mockRestore()
+    expect(view.container.textContent).toBe('alive')
+    expect(view.container.querySelector('[data-slot-error]')).not.toBeNull()
+  })
+})
+
+describe('inject caching and props merge', () => {
+  it('root inject runs once per entry and receives the root binding ctx', () => {
+    const core = makeFakeCore()
+    core.define('fake.root', { kind: 'single', scope: 'root' })
+    const inject = vi.fn((b: RootBinding) => ({ tag: (b.ctx as { tag: string }).tag }))
+    core.register('fake.root', ({ tag }: { tag?: string }) => <b>{tag}</b>,
+      { inject: inject as unknown as InjectFactory<SlotEntryDef> })
+    const slots = scopedSlots(core, 'fake.root' as never)
+    const root: RootBinding = { ctx: { tag: 'ROOT' } }
+    const view = render(
+      <RootBindingProvider value={root}>
+        {slots.renderSlot('fake.root' as never, {})}
+      </RootBindingProvider>,
+    )
+    expect(view.container.textContent).toBe('ROOT')
+    view.rerender(
+      <RootBindingProvider value={root}>
+        {slots.renderSlot('fake.root' as never, {})}
+      </RootBindingProvider>,
+    )
+    expect(inject).toHaveBeenCalledTimes(1)
+  })
+
+  it('root slots with inject throw without RootBindingProvider; plain entries do not need it', () => {
+    const core = makeFakeCore()
+    core.define('fake.root', { kind: 'single', scope: 'root' })
+    core.register('fake.root', () => <b>plain</b>)
+    const slots = scopedSlots(core, 'fake.root' as never)
+    const view = render(<>{slots.renderSlot('fake.root' as never, {})}</>)
+    expect(view.container.textContent).toBe('plain')
+
+    const core2 = makeFakeCore()
+    core2.define('fake.root', { kind: 'single', scope: 'root' })
+    core2.register('fake.root', () => <b>x</b>,
+      { inject: (() => ({})) as unknown as InjectFactory<SlotEntryDef> })
+    const slots2 = scopedSlots(core2, 'fake.root' as never)
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    expect(() => render(<>{slots2.renderSlot('fake.root' as never, {})}</>))
+      .toThrow(/RootBindingProvider/)
+    spy.mockRestore()
+  })
+
+  it('session inject caches per (entry x binding): session switch re-invokes, switch-back reuses', () => {
+    const core = makeFakeCore()
+    core.define('fake.session', { kind: 'single', scope: 'session' })
+    const inject = vi.fn((b: { sessionId: string }) => ({ sid: b.sessionId }))
+    core.register('fake.session', ({ sid }: { sid?: string }) => <b>{sid}</b>,
+      { inject: inject as unknown as InjectFactory<SlotEntryDef> })
+    const slots = scopedSlots(core, 'fake.session' as never)
+    const bindings = { s1: makeBinding('s1'), s2: makeBinding('s2') }
+    const { current, Provider } = sessionHarness(
+      () => slots.renderSlot('fake.session' as never, {}), bindings)
+    const view = render(<Provider />)
+    act(() => { current.update((d) => { d.id = 's1' }) })
+    expect(view.container.textContent).toBe('s1')
+    expect(inject).toHaveBeenCalledTimes(1)
+    act(() => { current.update((d) => { d.id = 's2' }) })
+    expect(view.container.textContent).toBe('s2')
+    expect(inject).toHaveBeenCalledTimes(2)
+    act(() => { current.update((d) => { d.id = 's1' }) })   // back: cache hit
+    expect(view.container.textContent).toBe('s1')
+    expect(inject).toHaveBeenCalledTimes(2)
+  })
+
+  it('session slots receive standard useSession injection and owner props win the merge', () => {
+    const core = makeFakeCore()
+    core.define('fake.session', { kind: 'single', scope: 'session' })
+    const seen: Record<string, unknown>[] = []
+    core.register('fake.session', (props: object) => {
+      seen.push(props as Record<string, unknown>)
+      return null
+    }, { inject: (() => ({ fromInject: 'inject', shared: 'inject' })) as unknown as InjectFactory<SlotEntryDef> })
+    const slots = scopedSlots(core, 'fake.session' as never)
+    const bindings = { s1: makeBinding('s1') }
+    const { current, Provider } = sessionHarness(
+      () => slots.renderSlot('fake.session' as never, { owner: 'owner', shared: 'owner' } as never), bindings)
+    render(<Provider />)
+    act(() => { current.update((d) => { d.id = 's1' }) })
+    const props = seen.at(-1)!
+    expect(props.useSession).toBe(bindings.s1.session.useSelector)
+    expect(props.fromInject).toBe('inject')
+    expect(props.owner).toBe('owner')
+    expect(props.shared).toBe('owner')   // three-source merge: owner overrides inject
+  })
+
+  it('session slots outside a SessionProvider fail loud', () => {
+    const core = makeFakeCore()
+    core.define('fake.session', { kind: 'single', scope: 'session' })
+    core.register('fake.session', () => <b>x</b>)
+    const slots = scopedSlots(core, 'fake.session' as never)
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    expect(() => render(<>{slots.renderSlot('fake.session' as never, {})}</>))
+      .toThrow(/outside SessionProvider/)
+    spy.mockRestore()
+  })
+})
diff --git a/packages/client/web-react/tests/session-provider.spec.tsx b/packages/client/web-react/tests/session-provider.spec.tsx
new file mode 100644
index 0000000000..78b633dc33
--- /dev/null
+++ b/packages/client/web-react/tests/session-provider.spec.tsx
@@ -0,0 +1,106 @@
+// @vitest-environment jsdom
+import { useEffect, useRef } from 'react'
+import { describe, expect, it, vi } from 'vitest'
+import { act, render } from '@testing-library/react'
+import type { RootBinding } from '@deepseek-ai/dsh-client-ui-slots'
+import {
+  createSessionProvider, createSnapshotStore, RootBindingProvider,
+  useRootBinding, useSessionBinding,
+  type SessionBinding, type SessionProviderDeps,
+} from '@deepseek-ai/dsh-client-web-react'
+
+const makeBinding = (sessionId: string): SessionBinding => ({
+  sessionId,
+  session: { useSelector: (() => { throw new Error('unused') }) as never },
+  ctx: { tag: sessionId },
+})
+
+function setup(bindings: Record<string, SessionBinding>) {
+  const current = createSnapshotStore<{ id: string | undefined }>({ id: undefined })
+  const resolveBinding = vi.fn((id: string) => bindings[id])
+  const seen: { id: string; binding: SessionBinding; mountCount: number }[] = []
+  let mounts = 0
+
+  function Body({ id }: { id: string }) {
+    const binding = useSessionBinding()
+    const mountRef = useRef(0)
+    useEffect(() => { mounts += 1; mountRef.current = mounts }, [])
+    seen.push({ id, binding, mountCount: mountRef.current })
+    return <div data-testid="body">{id}</div>
+  }
+
+  const deps: SessionProviderDeps = {
+    useCurrent: () => current.useSelector((s) => s.id),
+    resolveBinding,
+    renderBody: (id) => <Body id={id} />,
+  }
+  const SessionProvider = createSessionProvider(deps)
+  return { current, resolveBinding, SessionProvider, seen, mountCount: () => mounts }
+}
+
+describe('createSessionProvider', () => {
+  it('renders empty without a current session and switches to the body on select', () => {
+    const { current, SessionProvider } = setup({ s1: makeBinding('s1') })
+    const view = render(<SessionProvider renderEmpty={() => <span>empty</span>} />)
+    expect(view.container.textContent).toBe('empty')
+    act(() => { current.update((d) => { d.id = 's1' }) })
+    expect(view.container.textContent).toBe('s1')
+  })
+
+  it('renders null empty state when renderEmpty is omitted', () => {
+    const { SessionProvider } = setup({})
+    const view = render(<SessionProvider />)
+    expect(view.container.textContent).toBe('')
+  })
+
+  it('falls back to empty when the binding does not resolve', () => {
+    const { current, SessionProvider } = setup({})
+    const view = render(<SessionProvider renderEmpty={() => <span>empty</span>} />)
+    act(() => { current.update((d) => { d.id = 'ghost' }) })
+    expect(view.container.textContent).toBe('empty')
+  })
+
+  it('passes the resolved binding through context and remounts on session switch', () => {
+    const bindings = { s1: makeBinding('s1'), s2: makeBinding('s2') }
+    const { current, SessionProvider, seen, mountCount } = setup(bindings)
+    render(<SessionProvider />)
+    act(() => { current.update((d) => { d.id = 's1' }) })
+    expect(seen.at(-1)!.binding).toBe(bindings.s1)
+    const mountsAfterS1 = mountCount()
+    act(() => { current.update((d) => { d.id = 's2' }) })
+    expect(seen.at(-1)!.binding).toBe(bindings.s2)
+    // key={id} semantics: switching sessions remounts the body subtree.
+    expect(mountCount()).toBe(mountsAfterS1 + 1)
+  })
+
+  it('does not remount the body when unrelated renders happen on the same session', () => {
+    const bindings = { s1: makeBinding('s1') }
+    const { current, SessionProvider, mountCount } = setup(bindings)
+    const view = render(<SessionProvider />)
+    act(() => { current.update((d) => { d.id = 's1' }) })
+    const mounts = mountCount()
+    view.rerender(<SessionProvider />)
+    expect(mountCount()).toBe(mounts)
+  })
+})
+
+describe('binding contexts', () => {
+  it('useSessionBinding throws outside a SessionProvider subtree', () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    function Naked() { useSessionBinding(); return null }
+    expect(() => render(<Naked />)).toThrow(/outside SessionProvider/)
+    spy.mockRestore()
+  })
+
+  it('RootBindingProvider supplies the root binding; absence throws', () => {
+    const root: RootBinding = { ctx: { tag: 'root' } }
+    let got: RootBinding | undefined
+    function Probe() { got = useRootBinding(); return null }
+    render(<RootBindingProvider value={root}><Probe /></RootBindingProvider>)
+    expect(got).toBe(root)
+
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    expect(() => render(<Probe />)).toThrow(/RootBindingProvider/)
+    spy.mockRestore()
+  })
+})
diff --git a/packages/client/web-react/tests/store.spec.ts b/packages/client/web-react/tests/store.spec.ts
new file mode 100644
index 0000000000..88fdb8bb3b
--- /dev/null
+++ b/packages/client/web-react/tests/store.spec.ts
@@ -0,0 +1,135 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createSnapshotStore, shallowEqual } from '@deepseek-ai/dsh-client-web-react/store'
+
+interface State {
+  a: { n: number }
+  b: { list: string[] }
+}
+
+const init = (): State => ({ a: { n: 1 }, b: { list: ['x'] } })
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('createSnapshotStore', () => {
+  it('applies update through a draft and preserves untouched branch references', () => {
+    const store = createSnapshotStore(init())
+    const before = store.getSnapshot()
+    store.update((d) => { d.a.n = 2 })
+    const after = store.getSnapshot()
+    expect(after).not.toBe(before)
+    expect(after.a.n).toBe(2)
+    expect(after.b).toBe(before.b)
+  })
+
+  it('notifies synchronously per update by default', () => {
+    const store = createSnapshotStore(init())
+    const seen: number[] = []
+    store.subscribe(() => { seen.push(store.getSnapshot().a.n) })
+    store.update((d) => { d.a.n = 2 })
+    store.update((d) => { d.a.n = 3 })
+    expect(seen).toEqual([2, 3])
+  })
+
+  it('coalesces a frame of updates into one notification in raf mode', () => {
+    const frame: FrameRequestCallback[] = []
+    vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
+      frame.push(cb)
+      return frame.length
+    })
+    const store = createSnapshotStore(init(), { flush: 'raf' })
+    const spy = vi.fn()
+    store.subscribe(spy)
+    store.update((d) => { d.a.n = 2 })
+    store.update((d) => { d.a.n = 3 })
+    store.update((d) => { d.b.list.push('y') })
+    expect(spy).not.toHaveBeenCalled()
+    expect(frame).toHaveLength(1)
+    frame.shift()!(0)
+    expect(spy).toHaveBeenCalledTimes(1)
+    expect(store.getSnapshot().a.n).toBe(3)
+    // Next frame batches independently.
+    store.update((d) => { d.a.n = 4 })
+    expect(frame).toHaveLength(1)
+    frame.shift()!(0)
+    expect(spy).toHaveBeenCalledTimes(2)
+  })
+
+  it('falls back to microtask batching in raf mode without requestAnimationFrame', async () => {
+    const store = createSnapshotStore(init(), { flush: 'raf' })
+    const spy = vi.fn()
+    store.subscribe(spy)
+    store.update((d) => { d.a.n = 2 })
+    store.update((d) => { d.a.n = 3 })
+    expect(spy).not.toHaveBeenCalled()
+    await Promise.resolve()
+    expect(spy).toHaveBeenCalledTimes(1)
+  })
+
+  it('unsubscribes raf-mode listeners', () => {
+    const frame: FrameRequestCallback[] = []
+    vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
+      frame.push(cb)
+      return frame.length
+    })
+    const store = createSnapshotStore(init(), { flush: 'raf' })
+    const spy = vi.fn()
+    const off = store.subscribe(spy)
+    store.update((d) => { d.a.n = 2 })
+    off()
+    frame.shift()!(0)
+    expect(spy).not.toHaveBeenCalled()
+  })
+
+  it('replaces state wholesale via set and freezes it outside production', () => {
+    const store = createSnapshotStore(init())
+    const next = init()
+    store.set(next)
+    expect(store.getSnapshot()).toBe(next)
+    expect(() => { (store.getSnapshot().a).n = 9 }).toThrow()
+  })
+
+  it('freezes update produce output outside production (immer dev freeze)', () => {
+    const store = createSnapshotStore(init())
+    store.update((d) => { d.a.n = 2 })
+    expect(() => { (store.getSnapshot().a).n = 9 }).toThrow()
+  })
+
+  it('rehydrates primitive state whole, not spread into index keys', () => {
+    const backing = new Map<string, string>()
+    vi.stubGlobal('localStorage', {
+      getItem: (k: string) => backing.get(k) ?? null,
+      setItem: (k: string, v: string) => { backing.set(k, v) },
+      removeItem: (k: string) => { backing.delete(k) },
+    })
+    const store = createSnapshotStore<string>('', { persist: { name: 'spec-draft' } })
+    store.set('hello')
+    const revived = createSnapshotStore<string>('', { persist: { name: 'spec-draft' } })
+    expect(revived.getSnapshot()).toBe('hello')
+  })
+
+  it('persists to localStorage under the given name and rehydrates', () => {
+    const backing = new Map<string, string>()
+    vi.stubGlobal('localStorage', {
+      getItem: (k: string) => backing.get(k) ?? null,
+      setItem: (k: string, v: string) => { backing.set(k, v) },
+      removeItem: (k: string) => { backing.delete(k) },
+    })
+    const store = createSnapshotStore(init(), { persist: { name: 'spec-store' } })
+    store.update((d) => { d.a.n = 42 })
+    expect(backing.has('spec-store')).toBe(true)
+    const revived = createSnapshotStore(init(), { persist: { name: 'spec-store' } })
+    expect(revived.getSnapshot().a.n).toBe(42)
+  })
+})
+
+describe('shallowEqual', () => {
+  it('matches one-level-equal objects and rejects deeper drift', () => {
+    const leaf = { deep: 1 }
+    expect(shallowEqual({ x: 1, y: leaf }, { x: 1, y: leaf })).toBe(true)
+    expect(shallowEqual({ x: 1, y: { deep: 1 } }, { x: 1, y: { deep: 1 } })).toBe(false)
+    expect(shallowEqual([1, 2], [1, 2])).toBe(true)
+    expect(shallowEqual([1, 2], [2, 1])).toBe(false)
+  })
+})
diff --git a/packages/client/web-react/tests/use-invoke.spec.tsx b/packages/client/web-react/tests/use-invoke.spec.tsx
new file mode 100644
index 0000000000..8e362ed820
--- /dev/null
+++ b/packages/client/web-react/tests/use-invoke.spec.tsx
@@ -0,0 +1,84 @@
+// @vitest-environment jsdom
+import { describe, expect, it, vi } from 'vitest'
+import { act, render } from '@testing-library/react'
+import { useInvoke } from '@deepseek-ai/dsh-client-web-react'
+
+function deferred<T>() {
+  let resolve!: (v: T) => void
+  let reject!: (e: unknown) => void
+  const promise = new Promise<T>((res, rej) => { resolve = res; reject = rej })
+  return { promise, resolve, reject }
+}
+
+interface Probe {
+  invoke: () => void
+  pending: boolean
+  renders: number
+}
+
+function Harness({ fn, probe }: { fn: () => Promise<unknown>; probe: Probe }) {
+  const [invoke, pending] = useInvoke(fn)
+  probe.invoke = invoke
+  probe.pending = pending
+  probe.renders += 1
+  return null
+}
+
+const newProbe = (): Probe => ({ invoke: () => {}, pending: false, renders: 0 })
+
+describe('useInvoke', () => {
+  it('tracks pending across the action lifecycle', async () => {
+    const d = deferred<void>()
+    const probe = newProbe()
+    render(<Harness fn={() => d.promise} probe={probe} />)
+    expect(probe.pending).toBe(false)
+    act(() => { probe.invoke() })
+    expect(probe.pending).toBe(true)
+    await act(async () => { d.resolve(); await d.promise })
+    expect(probe.pending).toBe(false)
+  })
+
+  it('keeps pending true until the last concurrent call settles', async () => {
+    const d1 = deferred<void>()
+    const d2 = deferred<void>()
+    const queue = [d1, d2]
+    const probe = newProbe()
+    render(<Harness fn={() => queue.shift()!.promise} probe={probe} />)
+    act(() => { probe.invoke() })
+    act(() => { probe.invoke() })
+    expect(probe.pending).toBe(true)
+    await act(async () => { d1.resolve(); await d1.promise })
+    expect(probe.pending).toBe(true)
+    await act(async () => { d2.resolve(); await d2.promise })
+    expect(probe.pending).toBe(false)
+  })
+
+  it('keeps the invoke reference stable while fn changes, and calls the latest fn', async () => {
+    const first = vi.fn(() => Promise.resolve())
+    const second = vi.fn(() => Promise.resolve())
+    const probe = newProbe()
+    const { rerender } = render(<Harness fn={first} probe={probe} />)
+    const invokeBefore = probe.invoke
+    rerender(<Harness fn={second} probe={probe} />)
+    expect(probe.invoke).toBe(invokeBefore)
+    await act(async () => { probe.invoke() })
+    expect(first).not.toHaveBeenCalled()
+    expect(second).toHaveBeenCalledTimes(1)
+  })
+
+  it('resets pending and logs when the action rejects', async () => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const d = deferred<void>()
+    const probe = newProbe()
+    render(<Harness fn={() => d.promise} probe={probe} />)
+    act(() => { probe.invoke() })
+    expect(probe.pending).toBe(true)
+    await act(async () => {
+      d.reject(new Error('boom'))
+      await d.promise.catch(() => {})
+    })
+    expect(probe.pending).toBe(false)
+    expect(consoleError).toHaveBeenCalledWith('useInvoke action failed:', expect.any(Error))
+    consoleError.mockRestore()
+  })
+})
diff --git a/packages/client/web-react/tsconfig.json b/packages/client/web-react/tsconfig.json
new file mode 100644
index 0000000000..57b533b2a6
--- /dev/null
+++ b/packages/client/web-react/tsconfig.json
@@ -0,0 +1,25 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "jsx": "react-jsx",
+    "lib": [
+      "ES2024",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": []
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/client/web-react/tsdown.config.ts b/packages/client/web-react/tsdown.config.ts
new file mode 100644
index 0000000000..51bd9b8660
--- /dev/null
+++ b/packages/client/web-react/tsdown.config.ts
@@ -0,0 +1,42 @@
+import { defineConfig } from 'tsdown'
+
+/**
+ * Root shape plus the store subpath, built as SEPARATE single-entry bundles:
+ * a multi-entry build emits a hash-named shared chunk that the exact `files`
+ * whitelist cannot publish (same shape as code-runtime-worker/user-approval).
+ * Each entry inlines the shared store code instead; the node lib is the
+ * repo-uniform shape (publint/NodeNext), not an identity-sensitive runtime —
+ * browser consumers resolve this package through the loader module table.
+ */
+export default defineConfig([
+  {
+    entry: { index: 'lib/types/index.js' },
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'neutral',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+  {
+    entry: { invariant: 'lib/types/invariant.js' },
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'neutral',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+  {
+    entry: { 'store/index': 'lib/types/store/index.js' },
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'neutral',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+])
diff --git a/packages/client/web/README.md b/packages/client/web/README.md
new file mode 100644
index 0000000000..0501cb0384
--- /dev/null
+++ b/packages/client/web/README.md
@@ -0,0 +1,19 @@
+# @deepseek-ai/dsh-client-web
+
+Web shell library: `bootWebShell(el, seams?)` mounts the whole client — loader machinery (statically held; a loader cannot load itself), pure-library module-table seeding, AppRoot (boot loading page → settled → full UI in one switch), and the SessionProvider/scopedSlots assembly closure. The vite application entry lives in apps/web and only calls `bootWebShell`. Contract: api-contracts v3 §9.3.
+
+The optional `seams` parameter forwards the client loader's `fetchBundle`/`executeBundle` transport overrides (`BootSeams`); production callers omit it — it exists for test environments where `<script>` execution cannot reach the page context (jsdom).
+
+## Model Experience
+
+None, as the entry shell boots the browser plugin tree; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **One-shot rendering by design** — the UI waits for `loader.settled()`; a single plugin failure keeps the loading page with a loud error, no partial availability (progressive rendering returns with its own project).
+- **No HMR** — the dev loop is tsdown watch + manual refresh for plugins; vite serves only the shell.
+- **Narrow-window acceptance is deferred** — the concession chain is implemented in ui-layout but the shell-level narrow-viewport walkthrough is a P-II acceptance item.
diff --git a/packages/client/web/package.json b/packages/client/web/package.json
new file mode 100644
index 0000000000..70826127c1
--- /dev/null
+++ b/packages/client/web/package.json
@@ -0,0 +1,51 @@
+{
+  "name": "@deepseek-ai/dsh-client-web",
+  "description": "Web shell library: bootWebShell (loader holding + module-table seeding + AppRoot gate + plugin assembly), consumed by the apps/web vite entry",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-theme": "workspace:^",
+    "@deepseek-ai/dsh-client-web-react": "workspace:^",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "cordis": "^4.0.0-rc.7",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}
diff --git a/packages/client/web/src/AppRoot.module.css b/packages/client/web/src/AppRoot.module.css
new file mode 100644
index 0000000000..a5bc807d3f
--- /dev/null
+++ b/packages/client/web/src/AppRoot.module.css
@@ -0,0 +1,66 @@
+/* Boot page styles are self-contained: the theme base stylesheets are linked
+   by the shell, but the loading page must render acceptably even before/without
+   them, so this file uses tokens with neutral fallbacks (the one sanctioned
+   fallback site — plugin packages must not do this). */
+
+.boot {
+  height: 100%;
+  display: grid;
+  place-items: center;
+  background: var(--dsw-alias-bg-base, #f9fafb);
+}
+
+.card {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 16px;
+}
+
+.wordmark {
+  font-size: 16px;
+  line-height: 24px;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  color: var(--dsw-alias-label-primary, #0f1115);
+}
+
+.hint {
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-tertiary, #81858c);
+}
+
+.spinner {
+  width: 20px;
+  height: 20px;
+  border-radius: 50%;
+  border: 2px solid var(--dsw-alias-border-l2, rgb(0 0 0 / 10%));
+  border-top-color: var(--dsw-alias-brand-primary, #3964fe);
+  animation: spin 0.8s linear infinite;
+}
+
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+
+.failed {
+  max-width: 480px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.failedTitle {
+  font-size: 14px;
+  line-height: 22px;
+  font-weight: 600;
+  color: var(--dsw-alias-label-primary, #0f1115);
+}
+
+.failedItem {
+  font-family: var(--ds-font-family-code, ui-monospace, 'SF Mono', Menlo, Consolas, 'Courier New');
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-secondary, #61666b);
+}
diff --git a/packages/client/web/src/AppRoot.tsx b/packages/client/web/src/AppRoot.tsx
new file mode 100644
index 0000000000..d8b7e0d49d
--- /dev/null
+++ b/packages/client/web/src/AppRoot.tsx
@@ -0,0 +1,52 @@
+/**
+ * Shell root: boot loading page → (loader settled) → real UI in one switch.
+ * Pure shell component with zero plugin dependencies — before settled it may
+ * only rely on itself; the real UI is produced by the boot assembly closure
+ * (renderApp) once every plugin is active. A failed plugin keeps the loading
+ * page and lists the failures (fail loud, no partial UI).
+ */
+import { useSyncExternalStore } from 'react'
+import type { ReactNode } from 'react'
+import type { ObservableSnapshot, SnapshotStore } from '@deepseek-ai/dsh-client-web-react'
+import type { LoaderStatus } from '@deepseek-ai/dsh-client-runtime/client'
+import css from './AppRoot.module.css'
+
+/** AppRoot props: settled signal, loader status feed, deferred real-UI factory. */
+export interface AppRootProps {
+  /** True once loader.settled() resolved (the boot closure flips it; status-derived guesses race an incrementally filled table). */
+  settled: ObservableSnapshot<boolean>
+  /** Loader per-plugin status store (drives loading/failed rendering). */
+  status: SnapshotStore<LoaderStatus>
+  /** Builds the real UI; called only after settled. */
+  renderApp: () => ReactNode
+}
+
+/** Boot gate: loading page until the loader settles; failures stay here. */
+export function AppRoot(props: AppRootProps) {
+  const settled = useSyncExternalStore(props.settled.subscribe, props.settled.getSnapshot)
+  const status = useSyncExternalStore(props.status.subscribe, props.status.getSnapshot)
+  const failed = Object.entries(status).filter(([, s]) => s === 'failed')
+
+  if (settled) return <>{props.renderApp()}</>
+
+  return (
+    <div className={css.boot}>
+      <div className={css.card}>
+        <div className={css.wordmark}>HARNESS</div>
+        {failed.length === 0
+          ? (
+              <>
+                <div className={css.spinner} />
+                <div className={css.hint}>Loading plugins…</div>
+              </>
+            )
+          : (
+              <div className={css.failed}>
+                <div className={css.failedTitle}>Failed to load plugins</div>
+                {failed.map(([id]) => <div key={id} className={css.failedItem}>{id}</div>)}
+              </div>
+            )}
+      </div>
+    </div>
+  )
+}
diff --git a/packages/client/web/src/app.tsx b/packages/client/web/src/app.tsx
new file mode 100644
index 0000000000..e8c25acc3d
--- /dev/null
+++ b/packages/client/web/src/app.tsx
@@ -0,0 +1,89 @@
+/**
+ * Real-UI assembly closure. Runs only after loader.settled(): resolves the
+ * layout plugin's export surface from the loader module table (type-only
+ * import keeps the plugin out of the shell bundle), closes SessionProvider and
+ * scopedSlots over the shell's whitelist, and mounts RootBindingProvider so
+ * root-slot inject factories can reach ctx.
+ */
+import type { ReactNode } from 'react'
+import type { Context } from 'cordis'
+import {
+  createSessionProvider, RootBindingProvider, scopedSlots,
+} from '@deepseek-ai/dsh-client-web-react'
+import type { SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+
+type LayoutExports = typeof import('@deepseek-ai/dsh-client-ui-layout/client')
+
+/** Assembly inputs: the settled root ctx plus the loader's module-table read surface. */
+export interface AssemblyDeps {
+  /** Client root context (all plugin services provided). */
+  ctx: Context
+  /** Module-table resolver (the loader's require; missing spec = throw). */
+  requireModule: (spec: string) => unknown
+}
+
+/**
+ * Build the renderApp factory handed to AppRoot.
+ * @param deps - assembly inputs.
+ * @returns factory producing the real UI tree (called once per AppRoot render after settled).
+ */
+export function buildRenderApp(deps: AssemblyDeps): () => ReactNode {
+  const { ctx } = deps
+  const layoutExports = deps.requireModule('@deepseek-ai/dsh-client-ui-layout/client') as LayoutExports
+  const { AppFrame, CenterColumn, DetailsColumn } = layoutExports
+  const layout = ctx.layout
+  // ctx.get: the typed `sessions` Context merge is suspended pending the
+  // client/host declaration-collision arbitration (runtime's merge note).
+  const sessions = ctx.get('sessions') as SessionsService | undefined
+  if (sessions === undefined) throw new Error('shell assembly: sessions service unavailable')
+
+  // Whitelist closure: the four layout-owned top slots, granted to the shell assembler.
+  const slots = scopedSlots(ctx.slots.core, 'sidebar', 'conversation', 'details', 'conversation.empty')
+
+  // Stable references — created once per assembly, never per render.
+  const rootBinding = { ctx }
+  const useCurrent = (): SessionId | undefined => layout.current.useSelector((s) => s.sessionId)
+  const useSidebar = layout.sidebar.useSelector
+  const useDetails = layout.details.useSelector
+  const setSidebarWidth = (px: number): void => { layout.setSidebarWidth(px) }
+  const setDetailsWidth = (px: number): void => { layout.setDetailsWidth(px) }
+
+  const renderBody = (id: SessionId): ReactNode => (
+    <>
+      <CenterColumn>{slots.renderSlot('conversation', { sessionId: id })}</CenterColumn>
+      <DetailsColumn>{slots.renderSlot('details', { sessionId: id })}</DetailsColumn>
+    </>
+  )
+  // No selected session: the conversation.empty root slot carries EmptyState
+  // (ui-conversation registers it); the fallback keeps the grid shape until
+  // that owner lands.
+  const renderEmpty = (): ReactNode => (
+    <>
+      <CenterColumn>{slots.renderSlot('conversation.empty', {}, { fallback: null })}</CenterColumn>
+      <DetailsColumn />
+    </>
+  )
+
+  // Provider deps speak plain string (web-react's inversion: it never imports
+  // runtime); the assembler re-brands at this boundary — ids entering the
+  // provider came from layout.current, which only holds validated SessionIds.
+  const SessionProvider = createSessionProvider({
+    useCurrent,
+    resolveBinding: (id) => sessions.binding(id as SessionId),
+    renderBody: (id) => renderBody(id as SessionId),
+  })
+
+  return () => (
+    <RootBindingProvider value={rootBinding}>
+      <AppFrame
+        useSidebar={useSidebar}
+        useDetails={useDetails}
+        setSidebarWidth={setSidebarWidth}
+        setDetailsWidth={setDetailsWidth}
+        sidebar={slots.renderSlot('sidebar', {})}
+      >
+        <SessionProvider renderEmpty={renderEmpty} />
+      </AppFrame>
+    </RootBindingProvider>
+  )
+}
diff --git a/packages/client/web/src/base.css b/packages/client/web/src/base.css
new file mode 100644
index 0000000000..53dbde8db7
--- /dev/null
+++ b/packages/client/web/src/base.css
@@ -0,0 +1,19 @@
+/* Shell-owned global base: full-height mount plus the theme token sheets.
+ * The three ui-theme sheets are the sole token source (--dsw-*); the shell
+ * links them here so tokens exist before any plugin CSS lands. */
+@import '@deepseek-ai/dsh-client-ui-theme/styles/base.css';
+@import '@deepseek-ai/dsh-client-ui-theme/styles/design-platform.css';
+@import '@deepseek-ai/dsh-client-ui-theme/styles/gradient-shadow-text.css';
+
+html,
+body,
+#root {
+  height: 100%;
+  margin: 0;
+}
+
+body {
+  font-family: var(--dsw-font-family);
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-alias-bg-base);
+}
diff --git a/packages/client/web/src/boot.tsx b/packages/client/web/src/boot.tsx
new file mode 100644
index 0000000000..ac4accea45
--- /dev/null
+++ b/packages/client/web/src/boot.tsx
@@ -0,0 +1,66 @@
+/**
+ * Web shell boot — the library face consumed by the apps/web entry (api
+ * contracts v3 §0.3/§9.3): root ctx → hold the loader machinery (statically
+ * imported; the loader cannot load itself) → seed the module table → render
+ * the AppRoot loading page → loader.start() → await settled() → flip the
+ * settled signal so AppRoot switches to the real UI in one pass. Load
+ * failures reject settled(); AppRoot stays on the loading page listing them
+ * (fail loud).
+ */
+import { Context } from 'cordis'
+import { createRoot } from 'react-dom/client'
+import type { ReactNode } from 'react'
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-web-react'
+import { createClientLoader, type ClientLoaderOptions } from '@deepseek-ai/dsh-client-runtime/loader'
+import { AppRoot } from './AppRoot.tsx'
+import { buildRenderApp } from './app.tsx'
+import { seedModules } from './seed.ts'
+import './base.css'
+
+/** Manually flipped settled signal (AppRoot's gate; see AppRootProps.settled). */
+function settledSignal(): ObservableSnapshot<boolean> & { flip: () => void } {
+  let value = false
+  const listeners = new Set<() => void>()
+  return {
+    getSnapshot: () => value,
+    subscribe: (fn) => { listeners.add(fn); return () => { listeners.delete(fn) } },
+    flip: () => {
+      value = true
+      for (const fn of [...listeners]) fn()
+    },
+  }
+}
+
+/** Loader transport seams the shell passes through (jsdom tests replace the <script> path). */
+export type BootSeams = Pick<ClientLoaderOptions, 'fetchBundle' | 'executeBundle'>
+
+/**
+ * Mount the web shell into a DOM element and start the plugin load chain.
+ * @param el - mount point (the app's #root).
+ * @param seams - optional loader transport overrides (test environments).
+ * @returns unmount disposer.
+ */
+export function bootWebShell(el: HTMLElement, seams?: BootSeams): () => void {
+  const ctx = new Context()
+  const loader = createClientLoader({ ctx, modules: seedModules(), ...seams })
+  ctx.reflect.provide('loader', loader)
+
+  const settled = settledSignal()
+  // Assemble once on first post-settled render: SessionProvider and the slot
+  // closures must be identity-stable across re-renders.
+  let renderApp: (() => ReactNode) | undefined
+  const renderAppOnce = (): ReactNode => {
+    renderApp ??= buildRenderApp({ ctx, requireModule: (spec) => loader.requireModule(spec) })
+    return renderApp()
+  }
+
+  const root = createRoot(el)
+  root.render(<AppRoot settled={settled} status={loader.status} renderApp={renderAppOnce} />)
+
+  loader.start()
+  loader.settled().then(
+    () => { settled.flip() },
+    () => { /* stay on the loading page; failures render from loader.status */ },
+  )
+  return () => { root.unmount() }
+}
diff --git a/packages/client/web/src/css-modules.d.ts b/packages/client/web/src/css-modules.d.ts
new file mode 100644
index 0000000000..bc5e482353
--- /dev/null
+++ b/packages/client/web/src/css-modules.d.ts
@@ -0,0 +1,6 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css'
diff --git a/packages/client/web/src/index.ts b/packages/client/web/src/index.ts
new file mode 100644
index 0000000000..4ea9ad46a7
--- /dev/null
+++ b/packages/client/web/src/index.ts
@@ -0,0 +1,11 @@
+/**
+ * Web shell library entry. The shell's product is {@link bootWebShell} —
+ * apps/web's vite entry calls it against #root; everything else (AppRoot
+ * gate, assembly closure, module-table seed) is internal to the boot chain.
+ * @module @deepseek-ai/dsh-client-web
+ */
+
+export { bootWebShell } from './boot.tsx'
+export { AppRoot, type AppRootProps } from './AppRoot.tsx'
+export { buildRenderApp, type AssemblyDeps } from './app.tsx'
+export { seedModules } from './seed.ts'
diff --git a/packages/client/web/src/invariant.ts b/packages/client/web/src/invariant.ts
new file mode 100644
index 0000000000..7b9fa6292c
--- /dev/null
+++ b/packages/client/web/src/invariant.ts
@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-web`.
+ * @module @deepseek-ai/dsh-client-web/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-web'
+
+/** Cordis companion plugin name. */
+export const name = 'client-web-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: the vite entry shell — boot glue and module-table
+ * seeding with no cordis events and no cross-plugin mutable state; the boot
+ * chain (loading page → settled → one-flip UI) is asserted by the web smoke
+ * e2e against the real carrier.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/client/web/src/seed.ts b/packages/client/web/src/seed.ts
new file mode 100644
index 0000000000..d4bfcd81e9
--- /dev/null
+++ b/packages/client/web/src/seed.ts
@@ -0,0 +1,35 @@
+/**
+ * Pure-library module-table seed. These are the ONLY entities statically
+ * built into the shell bundle besides the loader machinery — every plugin
+ * (including the infrastructure four) arrives as a dynamic bundle and
+ * resolves its externals against this table through the loader's require.
+ * Keys must match the tsdown client preset's external specifiers
+ * (packages/client/tsdown.client.ts CLIENT_EXTERNALS ∩ pure libraries).
+ */
+import * as React from 'react'
+import * as ReactJsxRuntime from 'react/jsx-runtime'
+import * as ReactDom from 'react-dom'
+import * as ReactDomClient from 'react-dom/client'
+import * as Cordis from 'cordis'
+import * as UiSlots from '@deepseek-ai/dsh-client-ui-slots'
+import * as WebReact from '@deepseek-ai/dsh-client-web-react'
+import * as WebReactStore from '@deepseek-ai/dsh-client-web-react/store'
+import * as UiPrimitives from '@deepseek-ai/dsh-client-ui-primitives'
+
+/**
+ * Build the seed table handed to the loader machinery at boot.
+ * @returns module specifier → export-surface entity.
+ */
+export function seedModules(): Record<string, unknown> {
+  return {
+    'react': React,
+    'react/jsx-runtime': ReactJsxRuntime,
+    'react-dom': ReactDom,
+    'react-dom/client': ReactDomClient,
+    'cordis': Cordis,
+    '@deepseek-ai/dsh-client-ui-slots': UiSlots,
+    '@deepseek-ai/dsh-client-web-react': WebReact,
+    '@deepseek-ai/dsh-client-web-react/store': WebReactStore,
+    '@deepseek-ai/dsh-client-ui-primitives': UiPrimitives,
+  }
+}
diff --git a/packages/client/web/tests/app-root.spec.tsx b/packages/client/web/tests/app-root.spec.tsx
new file mode 100644
index 0000000000..b5c9ab19fc
--- /dev/null
+++ b/packages/client/web/tests/app-root.spec.tsx
@@ -0,0 +1,73 @@
+// @vitest-environment jsdom
+/**
+ * AppRoot boot-gate smoke: loading page until the settled signal flips (status
+ * alone never opens the gate), fail-loud plugin list, one-pass switch to the
+ * real UI. The full browser chain (real loader + bundles) is the e2e's job;
+ * this pins the shell-owned gate semantics.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { act, cleanup, render } from '@testing-library/react'
+
+afterEach(cleanup)
+import { createSnapshotStore, type ObservableSnapshot } from '@deepseek-ai/dsh-client-web-react'
+import type { LoaderStatus } from '@deepseek-ai/dsh-client-runtime/client'
+import { AppRoot } from '@deepseek-ai/dsh-client-web/src/AppRoot.tsx'
+
+function signal(): ObservableSnapshot<boolean> & { flip: () => void } {
+  let value = false
+  const listeners = new Set<() => void>()
+  return {
+    getSnapshot: () => value,
+    subscribe: (fn) => { listeners.add(fn); return () => { listeners.delete(fn) } },
+    flip: () => { value = true; for (const fn of [...listeners]) fn() },
+  }
+}
+
+function mount() {
+  const settled = signal()
+  const status = createSnapshotStore<LoaderStatus>({})
+  let renders = 0
+  const utils = render(
+    <AppRoot
+      settled={settled}
+      status={status}
+      renderApp={() => { renders += 1; return <div data-testid="real-ui" /> }}
+    />,
+  )
+  return { settled, status, counts: () => renders, ...utils }
+}
+
+describe('AppRoot', () => {
+  it('shows the loading page and never calls renderApp before settled', () => {
+    const { queryByTestId, counts, getByText } = mount()
+    expect(getByText('HARNESS')).toBeTruthy()
+    expect(queryByTestId('real-ui')).toBeNull()
+    expect(counts()).toBe(0)
+  })
+
+  it('all-active status alone does not open the gate (settled signal is the only key)', () => {
+    const { status, queryByTestId } = mount()
+    act(() => {
+      status.update((d) => { d['a'] = 'active'; d['b'] = 'active' })
+    })
+    expect(queryByTestId('real-ui')).toBeNull()
+  })
+
+  it('lists failed plugins and stays on the loading page', () => {
+    const { status, getByText, queryByTestId } = mount()
+    act(() => {
+      status.update((d) => { d['@deepseek-ai/dsh-client-ui-theme'] = 'failed'; d['ok'] = 'active' })
+    })
+    expect(getByText('Failed to load plugins')).toBeTruthy()
+    expect(getByText('@deepseek-ai/dsh-client-ui-theme')).toBeTruthy()
+    expect(queryByTestId('real-ui')).toBeNull()
+  })
+
+  it('flipping settled switches to the real UI in one pass', () => {
+    const { settled, getByTestId, queryByText, counts } = mount()
+    act(() => { settled.flip() })
+    expect(getByTestId('real-ui')).toBeTruthy()
+    expect(queryByText('HARNESS')).toBeNull()
+    expect(counts()).toBe(1)
+  })
+})
diff --git a/packages/client/web/tests/boot.spec.tsx b/packages/client/web/tests/boot.spec.tsx
new file mode 100644
index 0000000000..8c05f0abb2
--- /dev/null
+++ b/packages/client/web/tests/boot.spec.tsx
@@ -0,0 +1,200 @@
+// @vitest-environment jsdom
+/**
+ * bootWebShell over the REAL client loader in jsdom (runScripts:dangerously —
+ * the loader's <script> execute path runs for real): fetch is stubbed to
+ * serve fake bundle text, everything else is production code — seeded module
+ * table, DSHClientProxy handoff, inject topology, settled flip, one-pass
+ * switch to the assembled UI, and the fail-loud path — through the loader's
+ * fetch/execute seams (jsdom's <script> vm context cannot reach the test
+ * window, so execute is indirect eval). The fake plugins pull the REAL
+ * SlotCore from the seeded ui-slots module; full-fidelity plugin content
+ * belongs to the apps/web e2e.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { act } from '@testing-library/react'
+import { bootWebShell } from '@deepseek-ai/dsh-client-web'
+
+interface BootWindow extends Window {
+  __DSH_BOOT__?: { plugins: { id: string; url: string; inject: string[]; immediately?: boolean }[] }
+  DSHClientProxy?: unknown
+  __TEST_NAV__?: { sessionId?: string; viewFor: Record<string, string> }
+}
+const win = window as unknown as BootWindow
+
+/** Fake runtime half: real SlotCore behind a minimal slots service + sessions stub. */
+const RUNTIME_STUB = `
+window.DSHClientProxy.loadPlugin({
+  id: 'fake-runtime',
+  factory: (require) => {
+    const { SlotCore } = require('@deepseek-ai/dsh-client-ui-slots')
+    const { createSnapshotStore } = require('@deepseek-ai/dsh-client-web-react')
+    return {
+      apply: (ctx) => {
+        const core = new SlotCore()
+        ctx.provide('slots', { core, define: (k, s) => core.define(k, s), register: (k, c, o) => core.register(k, c, o) })
+        const binding = {
+          sessionId: 's1',
+          session: { useSelector: (sel) => sel({}) },
+          ctx,
+        }
+        ctx.provide('sessions', {
+          list: createSnapshotStore({ ids: ['s1'], byId: { s1: { id: 's1', title: 'S1', running: false, updatedAt: 1 } } }),
+          binding: (id) => (id === 's1' ? binding : undefined),
+        })
+      },
+    }
+  },
+})`
+
+/** Fake layout half: real slot specs + the export surface the shell assembly consumes. */
+const LAYOUT_STUB = `
+window.DSHClientProxy.loadPlugin({
+  id: 'fake-layout',
+  factory: (require) => {
+    const React = require('react')
+    const { createSnapshotStore } = require('@deepseek-ai/dsh-client-web-react')
+    return {
+      inject: ['slots'],
+      AppFrame: (props) => {
+        const sw = props.useSidebar((st) => st.width)
+        const dw = props.useDetails((st) => st.width)
+        return React.createElement('div', {
+          'data-testid': 'fake-frame',
+          'data-widths': sw + 'x' + dw,
+          onClick: () => { props.setSidebarWidth(311); props.setDetailsWidth(411) },
+        }, props.sidebar, props.children)
+      },
+      CenterColumn: (props) => React.createElement('div', null, props.children),
+      DetailsColumn: (props) => React.createElement('div', null, props.children),
+      apply: (ctx) => {
+        const sidebar = createSnapshotStore({ open: true, width: 300 })
+        const details = createSnapshotStore({ open: false, width: 360 })
+        ctx.reflect.provide('layout', {
+          current: createSnapshotStore(window.__TEST_NAV__ ?? { sessionId: 's1', viewFor: {} }),
+          sidebar, details,
+          setSidebarWidth: (px) => { sidebar.update((d) => { d.width = px }) },
+          setDetailsWidth: (px) => { details.update((d) => { d.width = px }) },
+        })
+        ctx.slots.define('sidebar', { kind: 'single', scope: 'root' })
+        ctx.slots.define('conversation', { kind: 'single', scope: 'session' })
+        ctx.slots.define('details', { kind: 'single', scope: 'session' })
+        ctx.slots.define('conversation.empty', { kind: 'single', scope: 'root' })
+        ctx.slots.core.register('conversation', () => React.createElement('div', { 'data-testid': 'conv-body' }))
+      },
+    }
+  },
+})`
+
+// The shell assembly requires the layout surface under its production id.
+const LAYOUT_ID = '@deepseek-ai/dsh-client-ui-layout'
+
+/** Loader seams: serve fake bundle text and execute it via indirect eval (jsdom's <script> vm context cannot see the test window). */
+function seams(bundles: Record<string, string>) {
+  return {
+    fetchBundle: (url: string): Promise<string> => {
+      const hit = Object.keys(bundles).find((b) => url.endsWith(b))
+      if (hit === undefined) return Promise.reject(new Error(`bundle fetch ${url} answered 404`))
+      return Promise.resolve(bundles[hit]!)
+    },
+    executeBundle: (code: string): void => {
+      (0, eval)(code)
+    },
+  }
+}
+
+function mountPoint(): HTMLElement {
+  const el = document.createElement('div')
+  document.body.appendChild(el)
+  return el
+}
+
+async function flushLoader(): Promise<void> {
+  // fetch + per-plugin apply chain across macrotask turns; a few settle it.
+  for (let i = 0; i < 10; i++) await act(async () => { await new Promise((r) => setTimeout(r, 0)) })
+}
+
+afterEach(() => {
+  delete win.__DSH_BOOT__
+  delete win.DSHClientProxy
+  delete win.__TEST_NAV__
+  document.body.innerHTML = ''
+  document.head.querySelectorAll('script').forEach((s) => { s.remove() })
+})
+
+describe('bootWebShell (real loader + real script execution)', () => {
+  it('loading page → settled → assembled UI in one pass; unmount clears the tree', async () => {
+    win.__DSH_BOOT__ = {
+      plugins: [
+        { id: 'fake-runtime', url: '/plugins/fake-runtime.js', inject: [], immediately: true },
+        { id: LAYOUT_ID, url: '/plugins/fake-layout.js', inject: ['fake-runtime'] },
+      ],
+    }
+    const el = mountPoint()
+    let unmount: (() => void) | undefined
+    const s = seams({
+      '/plugins/fake-runtime.js': RUNTIME_STUB,
+      '/plugins/fake-layout.js': LAYOUT_STUB.replace("id: 'fake-layout'", `id: '${LAYOUT_ID}'`),
+    })
+    act(() => { unmount = bootWebShell(el, s) })
+    expect(el.textContent).toContain('HARNESS')
+    expect(el.querySelector('[data-testid="fake-frame"]')).toBeNull()
+
+    await flushLoader()
+    expect(el.querySelector('[data-testid="fake-frame"]')).not.toBeNull()
+    expect(el.textContent).not.toContain('HARNESS')
+    // Selected session: SessionProvider resolved the binding and renderBody
+    // mounted the conversation slot content into the center column.
+    expect(el.querySelector('[data-testid="conv-body"]')).not.toBeNull()
+
+    act(() => { unmount!() })
+    expect(el.childElementCount).toBe(0)
+  })
+
+  it('no selected session: renderEmpty keeps the grid and forwards width setters', async () => {
+    win.__TEST_NAV__ = { viewFor: {} }
+    win.__DSH_BOOT__ = {
+      plugins: [
+        { id: 'fake-runtime', url: '/plugins/fake-runtime.js', inject: [], immediately: true },
+        { id: LAYOUT_ID, url: '/plugins/fake-layout.js', inject: ['fake-runtime'] },
+      ],
+    }
+    const el = mountPoint()
+    const s = seams({
+      '/plugins/fake-runtime.js': RUNTIME_STUB,
+      '/plugins/fake-layout.js': LAYOUT_STUB.replace("id: 'fake-layout'", `id: '${LAYOUT_ID}'`),
+    })
+    act(() => { bootWebShell(el, s) })
+    await flushLoader()
+    const frame = el.querySelector('[data-testid="fake-frame"]')
+    expect(frame).not.toBeNull()
+    // Empty path: no conversation body (nothing registered into conversation.empty → fallback null).
+    expect(el.querySelector('[data-testid="conv-body"]')).toBeNull()
+    // Width setter/selector pass-through (assembly closures over ctx.layout).
+    expect((frame as HTMLElement).dataset['widths']).toBe('300x360')
+    act(() => { (frame as HTMLElement).click() })
+    expect((frame as HTMLElement).dataset['widths']).toBe('311x411')
+  })
+
+  it('fail loud: a 404 bundle keeps the loading page and lists the plugin id', async () => {
+    win.__DSH_BOOT__ = { plugins: [{ id: 'absent-plugin', url: '/plugins/absent.js', inject: [] }] }
+    const el = mountPoint()
+    act(() => { bootWebShell(el, seams({})) })
+    await flushLoader()
+    expect(el.textContent).toContain('Failed to load plugins')
+    expect(el.textContent).toContain('absent-plugin')
+    expect(el.querySelector('[data-testid="fake-frame"]')).toBeNull()
+  })
+})
+
+describe('buildRenderApp — assembly guards', () => {
+  it('throws loud when the sessions service is absent', async () => {
+    const { buildRenderApp } = await import('@deepseek-ai/dsh-client-web')
+    const { Context } = await import('cordis')
+    const ctx = new Context()
+    ctx.reflect.provide('layout', {})
+    expect(() => buildRenderApp({
+      ctx,
+      requireModule: () => ({ AppFrame: () => null, CenterColumn: () => null, DetailsColumn: () => null }),
+    })).toThrow(/sessions service unavailable/)
+  })
+})
diff --git a/packages/client/web/tsconfig.json b/packages/client/web/tsconfig.json
new file mode 100644
index 0000000000..87a6b0dcab
--- /dev/null
+++ b/packages/client/web/tsconfig.json
@@ -0,0 +1,49 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "jsx": "react-jsx",
+    "lib": [
+      "ES2024",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": []
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../ui-primitives"
+    },
+    {
+      "path": "../web-react"
+    },
+    {
+      "path": "../connection"
+    },
+    {
+      "path": "../runtime"
+    },
+    {
+      "path": "../ui-theme"
+    },
+    {
+      "path": "../ui-layout"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ],
+  "exclude": [
+    "**/*.legacy.*"
+  ]
+}
diff --git a/packages/client/web/tsdown.config.ts b/packages/client/web/tsdown.config.ts
new file mode 100644
index 0000000000..8040221e14
--- /dev/null
+++ b/packages/client/web/tsdown.config.ts
@@ -0,0 +1,31 @@
+import { defineConfig } from 'tsdown'
+
+/**
+ * Root-shape lib build plus a css stub: the shell's components import
+ * .module.css/.css assets that tsc passes through untouched, so the JS under
+ * lib/types references css files that do not exist there. The browser
+ * consumer (apps/web) compiles src directly through vite where css is real;
+ * this node lib build stubs every css import to an empty module — importing
+ * the lib under plain node must not crash on an asset specifier.
+ */
+export default defineConfig({
+  entry: ['lib/types/index.js', 'lib/types/invariant.js'],
+  outDir: 'lib',
+  format: ['esm'],
+  platform: 'neutral',
+  target: 'es2024',
+  fixedExtension: false,
+  dts: false,
+  clean: false,
+  plugins: [{
+    name: 'dsh-css-stub',
+    resolveId(source: string) {
+      if (!source.endsWith('.css')) return null
+      return `\0dsh-css-stub:${source}.mjs`
+    },
+    load(id: string) {
+      if (!id.startsWith('\0dsh-css-stub:')) return null
+      return 'export default {};'
+    },
+  }],
+})
diff --git a/packages/core/session/package.json b/packages/core/session/package.json
index 314eb6e0b5..05075a9bd4 100644
--- a/packages/core/session/package.json
+++ b/packages/core/session/package.json
@@ -15,12 +15,21 @@
       "types": "./lib/types/invariant.d.ts",
       "default": "./lib/invariant.js"
     },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
     "./src/*": "./src/*",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./surface": {
+      "types": "./lib/types/surface.d.ts",
+      "default": "./lib/types/surface.js"
+    }
   },
   "files": [
     "lib/index.js",
     "lib/invariant.js",
+    "lib/types/**/*.js",
     "lib/types/**/*.d.ts",
     "lib/types/**/*.d.ts.map",
     "src"
diff --git a/packages/core/session/src/surface.ts b/packages/core/session/src/surface.ts
index 90a2181d53..9095c8388b 100644
--- a/packages/core/session/src/surface.ts
+++ b/packages/core/session/src/surface.ts
@@ -2,10 +2,12 @@
  * Surface layer on top of the session event log: an ordered view of events
  * that produce LLM messages. The append-only log remains the source of truth.
  *
+ * Browser-safe: web clients consume this subpath export, so it must stay free
+ * of `node:` imports (they break the vite bundle).
+ *
  * @module @deepseek-ai/dsh-session/surface
  */
 
-import { isDeepStrictEqual } from 'node:util'
 import type { SessionEvent, SurfaceEvent, SurfaceEventType, SurfaceOp } from './types.ts'
 
 /** Runtime counterpart of the message-producing event union. */
@@ -188,6 +190,24 @@ function replacementRange(
   }
 }
 
+/**
+ * Deep structural equality over the session-event JSON value domain
+ * (null/boolean/number/string, arrays, plain objects). Replaces
+ * `node:util`'s isDeepStrictEqual to keep this module browser-safe.
+ */
+function isDeepEqualJson(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false
+    return a.every((item, i) => isDeepEqualJson(item, b[i]))
+  }
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false
+  const aKeys = Object.keys(a)
+  const bRecord = b as Record<string, unknown>
+  if (aKeys.length !== Object.keys(b).length) return false
+  return aKeys.every(key => Object.hasOwn(b, key) && isDeepEqualJson((a as Record<string, unknown>)[key], bRecord[key]))
+}
+
 /** Restrict a tool-result replacement to one current result's content. */
 function assertToolResultRewrite(
   event: SessionEvent,
@@ -207,7 +227,7 @@ function assertToolResultRewrite(
     const replacementRest = { ...event.data } as Record<string, unknown>
     delete originalRest['content']
     delete replacementRest['content']
-    if (!isDeepStrictEqual(originalRest, replacementRest)) {
+    if (!isDeepEqualJson(originalRest, replacementRest)) {
       throw new Error('tool/result surface replacement may change only content')
     }
   }
diff --git a/packages/core/session/tests/surface.spec.ts b/packages/core/session/tests/surface.spec.ts
index 5243564b6c..b7cbe11b11 100644
--- a/packages/core/session/tests/surface.spec.ts
+++ b/packages/core/session/tests/surface.spec.ts
@@ -141,6 +141,38 @@ describe('foldSurface tool-result rewrites', () => {
     ]
     expect(() => foldSurface(events)).toThrow(/may change only content/)
   })
+
+  it('compares array-valued rest fields structurally (meta arrays: equal accepted, drifted rejected)', () => {
+    const withMeta = (seq: number, meta: unknown, surfaceOp: SurfaceEvent['surfaceOp'] = 'append', sourceEventSeqs?: number[]): SessionEvent => {
+      const event = toolResultEvent(seq, 'c-meta', surfaceOp, sourceEventSeqs)
+      return { ...event, data: { ...(event.data as object), meta } } as SessionEvent
+    }
+    // Structurally equal arrays (fresh references) pass the rest-field equality.
+    expect(() => foldSurface([
+      withMeta(0, { tags: ['a', { n: 1 }] }),
+      withMeta(1, { tags: ['a', { n: 1 }] }, { op: 'replace', start: 0, end: 0 }, [0]),
+    ])).not.toThrow()
+    // Same length, drifted element: the array branch must reject.
+    expect(() => foldSurface([
+      withMeta(0, { tags: ['a'] }),
+      withMeta(1, { tags: ['b'] }, { op: 'replace', start: 0, end: 0 }, [0]),
+    ])).toThrow(/may change only content/)
+    // Array vs non-array on one side: the mixed-shape guard rejects.
+    expect(() => foldSurface([
+      withMeta(0, { tags: ['a'] }),
+      withMeta(1, { tags: 'a' }, { op: 'replace', start: 0, end: 0 }, [0]),
+    ])).toThrow(/may change only content/)
+    // Same key count, different key names: the hasOwn branch rejects.
+    expect(() => foldSurface([
+      withMeta(0, { left: 1 }),
+      withMeta(1, { right: 1 }, { op: 'replace', start: 0, end: 0 }, [0]),
+    ])).toThrow(/may change only content/)
+    // Different key counts: the key-length branch rejects.
+    expect(() => foldSurface([
+      withMeta(0, { one: 1 }),
+      withMeta(1, { one: 1, two: 2 }, { op: 'replace', start: 0, end: 0 }, [0]),
+    ])).toThrow(/may change only content/)
+  })
 })
 
 describe('SurfaceManager', () => {
diff --git a/packages/core/tools/package.json b/packages/core/tools/package.json
index 535e60f60b..0e719ab255 100644
--- a/packages/core/tools/package.json
+++ b/packages/core/tools/package.json
@@ -15,12 +15,17 @@
       "types": "./lib/types/invariant.d.ts",
       "default": "./lib/invariant.js"
     },
+    "./presentation": {
+      "types": "./lib/types/presentation.d.ts",
+      "default": "./lib/types/presentation.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
     "lib/invariant.js",
+    "lib/types/**/*.js",
     "lib/types/**/*.d.ts",
     "lib/types/**/*.d.ts.map",
     "src"
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
new file mode 100644
index 0000000000..5ca6b9b8ca
--- /dev/null
+++ b/packages/host/apiproxy/README.md
@@ -0,0 +1,27 @@
+# @deepseek-ai/dsh-host-apiproxy
+
+The ApiProxy front layer every client shape shares: the TS contract (`src/api/`, zero Node dependencies, importable from the browser) and the fetch carrier pair (`src/fetch/`: `toFetchHandler` on the host side, `AbstractApiClient` plus platform subclasses on the client side). Host assembly lives in `dsh-host-runtime`.
+
+## Contract layer (`/api`)
+
+Wire messages form a four-quadrant discriminated union — who initiates × request/response — decoupled from the physical channel: `ClientRequest` (POST `/api/<method>` body), `ServerResponse` (that POST's response body), `ServerRequest` (SSE frame), `ClientResponse` (POST `/api/respond` body). Responses always echo the matching request's `rpcId` and never mint a new one. Method parameter/return structures live only in the domain interface signatures (`SessionsApi`, `HostApi`, `EventsApi`); `RpcMethodMap` registers the methods and every other position derives via `RequestPayload<K>`/`ResponseValue<K>`. Zod schemas anchor `satisfies z.ZodType<Wire<T>>` and parse at two levels: envelope first, business payload second, dispatched per method. Business errors ride `RpcResult`'s error branch (`RpcErrorDetailsMap` closes the code set); HTTP status expresses only the carrier.
+
+The layering/protocol decisions are recorded in the [GUI layering and RPC protocol RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md); the browser-side consumption architecture in the [web client architecture RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md).
+
+## Carrier layer (`/client` + root)
+
+`AbstractApiClient` holds every protocol invariant — rpcId minting, envelope wrap/unwrap, zod parsing, SSE frame decoding, unary timeout, microtask-batched envelope observation (`subscribeEnvelopes`) — while platform subclasses supply only the `doFetch` transport aspect. `InProcessApiClient` over `toFetchHandler(api)` is the isomorphic point: the full wire serialization/validation path with no network, used by `dsh -p` headless.
+
+## Model Experience
+
+None, as the package defines the client↔host wire contract and carriers; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **`respond` routing is shipped, but pending-interaction state is host-side work** — the wire shape (POST `/api/respond`, `RpcReceipt`) is final; the pending table that makes late/duplicate answers meaningful lives in `dsh-host-runtime` and is still a stub there.
+- **Reserved seams stay out of `RpcMethodMap`** — `session.fork`, `prompt.mode: 'inject'`, `task.list`, `host.listModels`, and a describe `hostInstanceId` are documented reservations; an unknown method fails loud at envelope parse rather than getting a not-implemented code.
+- **No protocol version field** — client and host ship together; `host.describe` gains a version negotiation field only when an independently released client exists.
diff --git a/packages/host/apiproxy/package.json b/packages/host/apiproxy/package.json
new file mode 100644
index 0000000000..fe50c16a60
--- /dev/null
+++ b/packages/host/apiproxy/package.json
@@ -0,0 +1,59 @@
+{
+  "name": "@deepseek-ai/dsh-host-apiproxy",
+  "description": "ApiProxy front layer: the TS contract (api/) and the fetch carrier pair (fetch/); host assembly lives in dsh-host-runtime",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json",
+    "./api": {
+      "types": "./lib/types/api/index.d.ts",
+      "default": "./lib/types/api/index.js"
+    },
+    "./api/*": {
+      "types": "./lib/types/api/*.d.ts",
+      "default": "./lib/types/api/*.js"
+    },
+    "./client": {
+      "types": "./lib/types/fetch/client.d.ts",
+      "default": "./lib/types/fetch/client.js"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-user-approval": "workspace:^",
+    "@deepseek-ai/dsh-user-interaction": "workspace:^",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "cordis": "^4.0.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "^0.0.1"
+  },
+  "devDependencies": {
+    "cordis": "^4.0.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "workspace:^"
+  }
+}
diff --git a/packages/host/apiproxy/src/api/approvals.schema.ts b/packages/host/apiproxy/src/api/approvals.schema.ts
new file mode 100644
index 0000000000..6c6e90fb17
--- /dev/null
+++ b/packages/host/apiproxy/src/api/approvals.schema.ts
@@ -0,0 +1,21 @@
+/**
+ * approvals domain zod schemas (respond is a client-response; the payload schema serves
+ * the /api/respond endpoint's second parse after routing via the pending table).
+ * ApprovalRequestId brand cast point: one.
+ */
+
+import { z } from 'zod'
+import type { ApprovalRequestId } from '@deepseek-ai/dsh-user-approval/types'
+import type { ApprovalResponsePayload } from './approvals.ts'
+import type { Wire } from './rpc.schema.ts'
+import { sessionIdSchema } from './sessions.schema.ts'
+
+/** ApprovalRequestId: one brand cast after shape validation (the only cast point in this domain). */
+export const approvalRequestIdSchema = z.string().min(1) as unknown as z.ZodType<ApprovalRequestId>
+
+/** Approval answer payload (the result.value slot of a client-response). */
+export const approvalResponsePayloadSchema = z.object({
+  sessionId: sessionIdSchema,
+  approvalId: approvalRequestIdSchema,
+  outcome: z.union([z.literal('allowed-once'), z.literal('rejected')]),
+}) satisfies z.ZodType<Wire<ApprovalResponsePayload>>
diff --git a/packages/host/apiproxy/src/api/approvals.ts b/packages/host/apiproxy/src/api/approvals.ts
new file mode 100644
index 0000000000..780bc47431
--- /dev/null
+++ b/packages/host/apiproxy/src/api/approvals.ts
@@ -0,0 +1,21 @@
+/**
+ * approvals domain contract. The approval requested frame is a
+ * server-request (stable rpcId); the answer is a client-response echoing that rpcId (not a
+ * unary method, not in RpcMethodMap, mints no new id), carried on POST /api/respond with an
+ * RpcReceipt carrier receipt as the HTTP response body; the final outcome arrives in the resolved frame.
+ */
+
+import type { ApprovalRequestId } from '@deepseek-ai/dsh-user-approval/types'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+
+/**
+ * Approval answer payload (the result.value slot of a client-response). outcome accepts only
+ * the two values a client can give (cancelled/unavailable are host-side outcomes). approvalId
+ * is the core audit correlation (used by the impl to reconcile `approval/asked`/`decided`;
+ * passes through core's existing brand); wire correlation is governed by the echoed rpcId.
+ */
+export interface ApprovalResponsePayload {
+  sessionId: SessionId
+  approvalId: ApprovalRequestId
+  outcome: 'allowed-once' | 'rejected'
+}
diff --git a/packages/host/apiproxy/src/api/events.schema.ts b/packages/host/apiproxy/src/api/events.schema.ts
new file mode 100644
index 0000000000..a46cdfe09e
--- /dev/null
+++ b/packages/host/apiproxy/src/api/events.schema.ts
@@ -0,0 +1,42 @@
+/**
+ * events domain zod schemas: MuxFrame / HostFrame unions (discriminatedUnion('type')).
+ * A frame is the payload slot of the ServerRequest full form; the SessionEvent inside
+ * a session/event frame reuses sessions.schema's strict-envelope + wide-data passthrough branch.
+ */
+
+import { z } from 'zod'
+import type { AskUserQuestionItem } from '@deepseek-ai/dsh-user-interaction/types'
+import type { HostFrame, MuxFrame } from './events.ts'
+import type { Wire } from './rpc.schema.ts'
+import { rpcErrorSchema, rpcIdSchema } from './rpc.schema.ts'
+import { approvalRequestIdSchema } from './approvals.schema.ts'
+import { sessionEventSchema, sessionIdSchema, toolEventViewSchema } from './sessions.schema.ts'
+
+/** Question shape validated strictly against core dsh-user-interaction. */
+export const askUserQuestionItemSchema = z.object({
+  id: z.string(),
+  question: z.string(),
+  header: z.string().optional(),
+  options: z.array(z.object({ label: z.string(), description: z.string().optional() })).optional(),
+  multiSelect: z.boolean().optional(),
+}) satisfies z.ZodType<Wire<AskUserQuestionItem>>
+
+/** MuxFrame union (payload slot of a mux-stream ServerRequest). */
+export const muxFrameSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('session/event'), sessionId: sessionIdSchema, event: sessionEventSchema, view: toolEventViewSchema.optional() }),
+  z.object({ type: z.literal('session/subscribed'), sessionId: sessionIdSchema, lastSeq: z.number().int() }),
+  z.object({ type: z.literal('approval/requested'), sessionId: sessionIdSchema, approvalId: approvalRequestIdSchema, toolName: z.string(), callId: z.string().optional(), reason: z.string().optional() }),
+  z.object({ type: z.literal('approval/resolved'), sessionId: sessionIdSchema, approvalId: approvalRequestIdSchema, outcome: z.union([z.literal('allowed-once'), z.literal('rejected'), z.literal('cancelled'), z.literal('unavailable')]) }),
+  z.object({ type: z.literal('question/requested'), sessionId: sessionIdSchema, questions: z.array(askUserQuestionItemSchema) }),
+  z.object({ type: z.literal('question/resolved'), sessionId: sessionIdSchema, questionRpcId: rpcIdSchema, outcome: z.union([z.literal('answered'), z.literal('cancelled')]) }),
+  z.object({ type: z.literal('stream/error'), error: rpcErrorSchema }),
+]) as unknown as z.ZodType<MuxFrame>
+
+/** HostFrame union (payload slot of a host-stream ServerRequest). */
+export const hostFrameSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('host/session-added'), sessionId: sessionIdSchema, parentSessionId: sessionIdSchema.optional() }),
+  z.object({ type: z.literal('host/session-removed'), sessionId: sessionIdSchema }),
+  z.object({ type: z.literal('host/session-status'), sessionId: sessionIdSchema, running: z.boolean() }),
+  z.object({ type: z.literal('host/agent-error'), sessionId: sessionIdSchema, message: z.string() }),
+  z.object({ type: z.literal('stream/error'), error: rpcErrorSchema }),
+]) as unknown as z.ZodType<HostFrame>
diff --git a/packages/host/apiproxy/src/api/events.ts b/packages/host/apiproxy/src/api/events.ts
new file mode 100644
index 0000000000..eac4f0e65c
--- /dev/null
+++ b/packages/host/apiproxy/src/api/events.ts
@@ -0,0 +1,69 @@
+/**
+ * events domain contract: signatures and frame unions for the two SSE
+ * streams. Four-quadrant: streams yield the narrow form `RpcRequest<Frame>` (server-request
+ * view) — rpcId must be exposed to the business layer, because responses to answerable frames
+ * (approval/question requested) echo it; for pure pushes it identifies that one push.
+ * signal is a local stream-control parameter, independent of the request (never on the wire).
+ */
+
+import type { AskUserQuestionItem } from '@deepseek-ai/dsh-user-interaction/types'
+import type { ApprovalOutcome, ApprovalRequestId } from '@deepseek-ai/dsh-user-approval/types'
+import type { CallId } from '@deepseek-ai/dsh-llm/brand'
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
+import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools/presentation'
+import type { RpcError, RpcId, RpcRequest } from './rpc.ts'
+
+// Client-side consumers take the render-intent vocabulary from the contract;
+// dsh-tools remains its owner.
+export type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools/presentation'
+
+/**
+ * Host-computed render intent accompanying a `tool/call` or `tool/result`
+ * event. A pure derivation of args/result through the presenter registered at
+ * emission time — never persisted (the session log carries only the event), so
+ * the same event may carry a different view (or none) on a later delivery.
+ * `for` names which vocabulary applies without re-inspecting the event type.
+ * An absent view means the client's documented default (generic JSON card).
+ */
+export type ToolEventView =
+  | { for: 'call'; view: ToolCallView }
+  | { for: 'result'; view: ToolResultView }
+
+/** Streaming face of the contract: the two SSE stream openers (mux + host). */
+export interface EventsApi {
+  /**
+   * All-session aggregated mux stream. On open, emits a subscribed control frame for every
+   * attached session and replays each session's still-pending approval/question requested
+   * frames (rpcId reused verbatim — the refresh-recovery baseline).
+   * since: resume seam, unimplemented in v1 (ignored if passed); reconnection = reopen the
+   * stream + refetch history.
+   */
+  mux(request: RpcRequest<{ since?: Record<SessionId, number> }>, signal: AbortSignal): AsyncIterable<RpcRequest<MuxFrame>>
+
+  /**
+   * Host-level info stream: session create/destroy, running-status flips, and
+   * agent failures with no turn position. Empty payload uses `{}`.
+   */
+  host(request: RpcRequest<{}>, signal: AbortSignal): AsyncIterable<RpcRequest<HostFrame>>
+}
+
+/**
+ * Mux stream frames: raw session-event passthrough + control frames +
+ * approval/question frames (requested = answerable server-request, the rest are pure pushes).
+ */
+export type MuxFrame =
+  | { type: 'session/event'; sessionId: SessionId; event: SessionEvent; view?: ToolEventView }
+  | { type: 'session/subscribed'; sessionId: SessionId; lastSeq: number }
+  | { type: 'approval/requested'; sessionId: SessionId; approvalId: ApprovalRequestId; toolName: string; callId?: CallId; reason?: string }
+  | { type: 'approval/resolved'; sessionId: SessionId; approvalId: ApprovalRequestId; outcome: ApprovalOutcome }
+  | { type: 'question/requested'; sessionId: SessionId; questions: AskUserQuestionItem[] }
+  | { type: 'question/resolved'; sessionId: SessionId; questionRpcId: RpcId; outcome: 'answered' | 'cancelled' }
+  | { type: 'stream/error'; error: RpcError }
+
+/** Host stream frames. session-added carries the lineage anchor; agent-error is the only outlet for live failures with no turn position. */
+export type HostFrame =
+  | { type: 'host/session-added'; sessionId: SessionId; parentSessionId?: SessionId }
+  | { type: 'host/session-removed'; sessionId: SessionId }
+  | { type: 'host/session-status'; sessionId: SessionId; running: boolean }
+  | { type: 'host/agent-error'; sessionId: SessionId; message: string }
+  | { type: 'stream/error'; error: RpcError }
diff --git a/packages/host/apiproxy/src/api/host.schema.ts b/packages/host/apiproxy/src/api/host.schema.ts
new file mode 100644
index 0000000000..cb8de392f5
--- /dev/null
+++ b/packages/host/apiproxy/src/api/host.schema.ts
@@ -0,0 +1,19 @@
+/**
+ * host domain zod schemas (names derived from map keys).
+ */
+
+import { z } from 'zod'
+import type { RequestPayload, ResponseValue } from './rpc-map.ts'
+import type { Wire } from './rpc.schema.ts'
+
+/** host.describe request payload (empty object literal). */
+export const hostDescribeRequestSchema = z.object({}) satisfies z.ZodType<Wire<RequestPayload<'host.describe'>>>
+
+/** host.describe response value. */
+export const hostDescribeValueSchema = z.object({
+  version: z.string(),
+  cwd: z.string(),
+  provider: z.string().optional(),
+  model: z.string().optional(),
+  attachedSessions: z.number().int().nonnegative(),
+}) satisfies z.ZodType<Wire<ResponseValue<'host.describe'>>>
diff --git a/packages/host/apiproxy/src/api/host.ts b/packages/host/apiproxy/src/api/host.ts
new file mode 100644
index 0000000000..fd07b33ced
--- /dev/null
+++ b/packages/host/apiproxy/src/api/host.ts
@@ -0,0 +1,25 @@
+/**
+ * host domain contract. No protocol version: client and host ship
+ * together; introduce protocolVersion only when an independently released client appears.
+ */
+
+import type { RpcRequest, RpcResponse } from './rpc.ts'
+
+/** Host-level unary methods. */
+export interface HostApi {
+  /**
+   * One-shot host snapshot. Empty payload uses the literal `{}` (extend in place when fields arrive).
+   * version = the host app's (apps/cli) package.json version; cwd = the host process working
+   * directory (root for session persistence and tool execution); provider/model = the defaults
+   * applied when a new agent doesn't specify them explicitly, absent when the host configures
+   * no explicit default (the adapter falls back internally);
+   * attachedSessions = count of currently attached sessions (those with a live agent).
+   */
+  describe(request: RpcRequest<{}>): Promise<RpcResponse<{
+    version: string
+    cwd: string
+    provider?: string
+    model?: string
+    attachedSessions: number
+  }>>
+}
diff --git a/packages/host/apiproxy/src/api/index.ts b/packages/host/apiproxy/src/api/index.ts
new file mode 100644
index 0000000000..c51c785a7c
--- /dev/null
+++ b/packages/host/apiproxy/src/api/index.ts
@@ -0,0 +1,46 @@
+/**
+ * apiproxy contract-layer barrel. api/ has zero Node dependencies and is
+ * importable from the browser; the TS interfaces are the authoritative contract, HTTP/SSE are
+ * merely physical channels (four-quadrant message model).
+ */
+
+import type { SessionsApi } from './sessions.ts'
+import type { HostApi } from './host.ts'
+import type { EventsApi } from './events.ts'
+import type { ClientResponse, RpcReceipt } from './rpc.ts'
+
+/** Root interface of the unified API surface. New client-request domain = one new file pair + one field here + one map row. */
+export interface ApiProxy {
+  sessions: SessionsApi
+  host: HostApi
+  events: EventsApi
+  /** Response entry for server-requests (client-response, echoing their rpcId); not a domain method (four-quadrant model). */
+  respond(message: ClientResponse): Promise<RpcReceipt>
+}
+
+// ---- Domain interfaces and payload entities ----
+export type { HistoryEntry, SessionsApi, SessionSummary } from './sessions.ts'
+export type { HostApi } from './host.ts'
+export type { EventsApi, MuxFrame, HostFrame, ToolCallView, ToolEventView, ToolResultView } from './events.ts'
+export type { ApprovalResponsePayload } from './approvals.ts'
+export type { QuestionResponsePayload } from './questions.ts'
+
+// ---- Message layer: narrow forms (domain-signature view) ----
+export type { RpcRequest, RpcResponse } from './rpc.ts'
+
+// ---- Message layer: the four wire full forms + carrier receipt ----
+export type {
+  ClientRequest,
+  ClientResponse,
+  RpcMessage,
+  RpcReceipt,
+  ServerRequest,
+  ServerResponse,
+} from './rpc.ts'
+
+// ---- Errors and ids ----
+export { RpcId } from './rpc.ts'
+export type { RpcError, RpcErrorCode, RpcErrorDetailsMap, RpcResult } from './rpc.ts'
+
+// ---- Method registry and derived generics ----
+export type { RequestPayload, ResponseValue, RpcMethodMap } from './rpc-map.ts'
diff --git a/packages/host/apiproxy/src/api/questions.schema.ts b/packages/host/apiproxy/src/api/questions.schema.ts
new file mode 100644
index 0000000000..ed311a9c41
--- /dev/null
+++ b/packages/host/apiproxy/src/api/questions.schema.ts
@@ -0,0 +1,26 @@
+/**
+ * questions domain zod schemas (respond is a client-response; the payload schema serves
+ * the /api/respond endpoint's second parse after routing via the pending table). The question
+ * identifier is the echoed rpcId; the payload carries no resource id.
+ */
+
+import { z } from 'zod'
+import type { AskUserQuestionAnswer } from '@deepseek-ai/dsh-user-interaction/types'
+import type { QuestionResponsePayload } from './questions.ts'
+import type { Wire } from './rpc.schema.ts'
+import { sessionIdSchema } from './sessions.schema.ts'
+
+/** AskUserQuestionAnswer validated strictly against core dsh-user-interaction. */
+export const askUserQuestionAnswerSchema = z.object({
+  answers: z.array(z.object({
+    id: z.string(),
+    selected: z.array(z.string()),
+    custom: z.string().optional(),
+  })),
+}) satisfies z.ZodType<Wire<AskUserQuestionAnswer>>
+
+/** Question answer payload (the result.value slot of a client-response). */
+export const questionResponsePayloadSchema = z.object({
+  sessionId: sessionIdSchema,
+  answer: askUserQuestionAnswerSchema,
+}) satisfies z.ZodType<Wire<QuestionResponsePayload>>
diff --git a/packages/host/apiproxy/src/api/questions.ts b/packages/host/apiproxy/src/api/questions.ts
new file mode 100644
index 0000000000..1e1dcc5339
--- /dev/null
+++ b/packages/host/apiproxy/src/api/questions.ts
@@ -0,0 +1,19 @@
+/**
+ * questions domain contract. The question requested frame is a
+ * server-request whose rpcId is the question's stable logical id (minted when the host accepts
+ * ask(); core user-interaction has no request-level id); the answer is a client-response
+ * echoing that rpcId, with no resource id in the payload (rpcId suffices).
+ */
+
+import type { AskUserQuestionAnswer } from '@deepseek-ai/dsh-user-interaction/types'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+
+/**
+ * Question answer payload (the result.value slot of a client-response):
+ * answers one ask() as a whole batch (core: one ask, many questions, one
+ * answer — never split per question).
+ */
+export interface QuestionResponsePayload {
+  sessionId: SessionId
+  answer: AskUserQuestionAnswer
+}
diff --git a/packages/host/apiproxy/src/api/rpc-map.ts b/packages/host/apiproxy/src/api/rpc-map.ts
new file mode 100644
index 0000000000..b37cc062ff
--- /dev/null
+++ b/packages/host/apiproxy/src/api/rpc-map.ts
@@ -0,0 +1,26 @@
+/**
+ * RPC method registry and signature-derived generics. The map
+ * registers only client-request methods (respond is a client-response, so it is absent);
+ * map keys are the wire path segments (POST /api/session.list).
+ */
+
+import type { SessionsApi } from './sessions.ts'
+import type { HostApi } from './host.ts'
+import type { RpcResponse } from './rpc.ts'
+
+/** Method name → method signature. Signatures are the single source of truth; payload/value types are always derived from here. */
+export interface RpcMethodMap {
+  'session.list': SessionsApi['list']
+  'session.create': SessionsApi['create']
+  'session.history': SessionsApi['history']
+  'session.prompt': SessionsApi['prompt']
+  'session.cancel': SessionsApi['cancel']
+  'host.describe': HostApi['describe']
+}
+
+/** Business request payload of method K (reaches through the RpcRequest narrow form to payload). */
+export type RequestPayload<K extends keyof RpcMethodMap> = Parameters<RpcMethodMap[K]>[0]['payload']
+
+/** Business return value of method K (reaches through the RpcResponse narrow form to infer the ok value of result). */
+export type ResponseValue<K extends keyof RpcMethodMap> =
+  Awaited<ReturnType<RpcMethodMap[K]>> extends RpcResponse<infer T> ? T : never
diff --git a/packages/host/apiproxy/src/api/rpc.schema.ts b/packages/host/apiproxy/src/api/rpc.schema.ts
new file mode 100644
index 0000000000..d993e763b7
--- /dev/null
+++ b/packages/host/apiproxy/src/api/rpc.schema.ts
@@ -0,0 +1,97 @@
+/**
+ * Message-layer zod schemas: the four wire full forms + error body +
+ * carrier receipt. The payload slot is unknown in the full-form schemas — business payloads
+ * get a second parse dispatched by method (two-level parse discipline).
+ * Brand cast point: rpcIdSchema, and only there.
+ */
+
+import { z } from 'zod'
+import type { z as zCore } from 'zod'
+type ZodIssue = zCore.core.$ZodIssue
+import type { ClientRequest, ClientResponse, RpcError, RpcId, RpcReceipt, ServerRequest, ServerResponse } from './rpc.ts'
+
+/**
+ * Wire widening of a contract type: widens every property (deeply) to `original | undefined`.
+ * The repo enables exactOptionalPropertyTypes while zod `.optional()` outputs `T | undefined`,
+ * so `satisfies z.ZodType<ContractType>` is unusable across the board; anchoring is always
+ * written `satisfies z.ZodType<Wire<ContractType>>` — the widening only adds undefined, so
+ * missing fields / wrong types still fail to compile. On the JSON wire, "absent" and
+ * "value undefined" serialize identically, so the widening loses no validation semantics.
+ */
+export type Wire<T> = T extends readonly (infer E)[] ? Wire<E>[]
+  : T extends object ? { [K in keyof T]: Wire<T[K]> | undefined }
+    : T
+
+/**
+ * RpcId: one brand cast after shape validation (the only cast point in this
+ * file). No min-length: the id is an opaque echo token, and rejecting shapes
+ * here would only turn a correlatable error report into a client-side parse
+ * failure (the handler substitutes a sentinel when a request's id is unreadable).
+ */
+export const rpcIdSchema = z.string() as unknown as z.ZodType<RpcId>
+
+/** Error body: discriminated by code, per-branch details aligned to RpcErrorDetailsMap; details is required. */
+export const rpcErrorSchema: z.ZodType<RpcError> = z.discriminatedUnion('code', [
+  z.object({ code: z.literal('bad-request'), message: z.string(), details: z.object({ issues: z.array(z.custom<ZodIssue>()) }) }),
+  z.object({ code: z.literal('session-not-found'), message: z.string(), details: z.object({ sessionId: z.string() }) }),
+  z.object({ code: z.literal('agent-busy'), message: z.string(), details: z.object({ reason: z.string() }) }),
+  z.object({ code: z.literal('internal'), message: z.string(), details: z.object({}) }),
+]) as unknown as z.ZodType<RpcError>
+
+/**
+ * Business success/failure result schema (generic, reusable).
+ * @param value - Schema for the business value.
+ * @returns Schema for RpcResult<T>.
+ */
+export function rpcResultSchema<T>(value: z.ZodType<T>): z.ZodUnion<readonly [z.ZodType, z.ZodType]> {
+  return z.union([
+    z.object({ ok: z.literal(true), value }),
+    z.object({ ok: z.literal(false), error: rpcErrorSchema }),
+  ])
+}
+
+// ---- The four wire full-form schemas (payload/result.value slots stay wide — business layer does the second parse) ----
+
+/** ClientRequest full form (payload stays wide — the business layer runs the second parse). */
+export const clientRequestSchema = z.object({
+  type: z.literal('client-request'),
+  rpcId: rpcIdSchema,
+  method: z.string(),
+  payload: z.unknown(),
+}) as unknown as z.ZodType<ClientRequest>
+
+/** ServerResponse full form (result.value stays wide). */
+export const serverResponseSchema = z.object({
+  type: z.literal('server-response'),
+  rpcId: rpcIdSchema,
+  result: rpcResultSchema(z.unknown()),
+}) as unknown as z.ZodType<ServerResponse>
+
+/** ServerRequest full form (payload stays wide). */
+export const serverRequestSchema = z.object({
+  type: z.literal('server-request'),
+  rpcId: rpcIdSchema,
+  method: z.string(),
+  payload: z.unknown(),
+}) as unknown as z.ZodType<ServerRequest>
+
+/** ClientResponse full form (result.value stays wide). */
+export const clientResponseSchema = z.object({
+  type: z.literal('client-response'),
+  rpcId: rpcIdSchema,
+  result: rpcResultSchema(z.unknown()),
+}) as unknown as z.ZodType<ClientResponse>
+
+/** Wire full-form union (discriminated by type). */
+export const rpcMessageSchema = z.discriminatedUnion('type', [
+  clientRequestSchema as unknown as z.ZodObject<z.ZodRawShape>,
+  serverResponseSchema as unknown as z.ZodObject<z.ZodRawShape>,
+  serverRequestSchema as unknown as z.ZodObject<z.ZodRawShape>,
+  clientResponseSchema as unknown as z.ZodObject<z.ZodRawShape>,
+])
+
+/** Carrier receipt schema. */
+export const rpcReceiptSchema = z.union([
+  z.object({ accepted: z.literal(true) }),
+  z.object({ accepted: z.literal(false), reason: z.union([z.literal('not-pending'), z.literal('bad-response')]) }),
+]) satisfies z.ZodType<Wire<RpcReceipt>>
diff --git a/packages/host/apiproxy/src/api/rpc.ts b/packages/host/apiproxy/src/api/rpc.ts
new file mode 100644
index 0000000000..46f737817c
--- /dev/null
+++ b/packages/host/apiproxy/src/api/rpc.ts
@@ -0,0 +1,113 @@
+/**
+ * Four-quadrant RPC message model. Channels and messages are
+ * decoupled: HTTP is the client→server physical channel, SSE the server→client one; logical
+ * messages are channel-independent, and the wire full form is a four-member discriminated union.
+ * api/ contract layer: zero Node dependencies, importable from the browser.
+ */
+
+import type { z as zCore } from 'zod'
+type ZodIssue = zCore.core.$ZodIssue
+import type { Branded } from '@deepseek-ai/dsh-brand'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+
+/**
+ * Message correlation id: the initiator mints it on a request; a response
+ * echoes the matching request's rpcId and never mints a new one.
+ */
+export type RpcId = Branded<'rpc-id'>
+
+/**
+ * Brands a string as RpcId (same precedent as core `SessionId()`). Minted by the initiator:
+ * client-request → client mints; server-request → host mints (answerable frames get a stable
+ * logical id, pure pushes mint a fresh one each time).
+ * @param id - Raw id string (implementations mint UUIDs; tests may pass fixtures).
+ * @returns The same string, branded (compile-time cast, zero runtime cost).
+ */
+export function RpcId(id: string): RpcId {
+  return id as RpcId
+}
+
+/** Error code → details type map (a second table isomorphic to RpcMethodMap). New code = one row here + one branch in the error schema. */
+export interface RpcErrorDetailsMap {
+  'bad-request': { issues: ZodIssue[] }
+  'session-not-found': { sessionId: SessionId }
+  'agent-busy': { reason: string }
+  'internal': {}
+}
+
+/** Closed error-code union (the keys of RpcErrorDetailsMap). */
+export type RpcErrorCode = keyof RpcErrorDetailsMap
+
+/**
+ * Distributive union expanded from the map: code is the discriminant, so
+ * `switch (error.code)` narrows details. details is required (internal uses an explicit {}).
+ */
+export type RpcError = {
+  [C in RpcErrorCode]: { code: C; message: string; details: RpcErrorDetailsMap[C] }
+}[RpcErrorCode]
+
+/** Business success/failure result: the result slot of a unary response; methods never throw business errors. */
+export type RpcResult<T> = { ok: true; value: T } | { ok: false; error: RpcError }
+
+/**
+ * Signature-layer narrow form, request side (domain-interface view, shared by
+ * both directions): rpcId is explicit in the signature, never mixed into the
+ * business payload; the type tag and method are filled in by the carrier layer.
+ */
+export interface RpcRequest<P> {
+  rpcId: RpcId
+  payload: P
+}
+
+/** Signature-layer narrow form, response side: rpcId always echoes the matching request. */
+export interface RpcResponse<T> {
+  rpcId: RpcId
+  result: RpcResult<T>
+}
+
+// ---- Wire full forms: four named members of a discriminated union (discriminant = the four `type` literals) ----
+
+/** Call initiated by the client (wire carrier: POST /api/<method> body). */
+export interface ClientRequest {
+  type: 'client-request'
+  rpcId: RpcId
+  method: string
+  payload: unknown
+}
+
+/** Response to a ClientRequest (wire carrier: the HTTP response body of that POST); rpcId echoed. */
+export interface ServerResponse {
+  type: 'server-response'
+  rpcId: RpcId
+  result: RpcResult<unknown>
+}
+
+/**
+ * Message initiated by the server (wire carrier: SSE frame). Answerable interactions
+ * (approval/question requested — stable rpcId, reused on replay) and pure pushes
+ * (session/event etc. — rpcId identifies that one push) share this shape; whether a
+ * response is expected is determined statically by method (a strict dichotomy, no third kind).
+ */
+export interface ServerRequest {
+  type: 'server-request'
+  rpcId: RpcId
+  method: string
+  payload: unknown
+}
+
+/** Response to a ServerRequest (wire carrier: POST /api/respond body); rpcId echoed, never minted anew. */
+export interface ClientResponse {
+  type: 'client-response'
+  rpcId: RpcId
+  result: RpcResult<unknown>
+}
+
+/** Authoritative wire full-form union; narrow via `switch (message.type)`. */
+export type RpcMessage = ClientRequest | ServerResponse | ServerRequest | ClientResponse
+
+/**
+ * Carrier receipt (not an RpcMessage — it belongs to the carrier layer, same
+ * discipline as "HTTP status describes only the carrier"): the HTTP response
+ * body of the POST carrying a client-response. Late/duplicate responses yield not-pending.
+ */
+export type RpcReceipt = { accepted: true } | { accepted: false; reason: 'not-pending' | 'bad-response' }
diff --git a/packages/host/apiproxy/src/api/sessions.schema.ts b/packages/host/apiproxy/src/api/sessions.schema.ts
new file mode 100644
index 0000000000..3edf0e6014
--- /dev/null
+++ b/packages/host/apiproxy/src/api/sessions.schema.ts
@@ -0,0 +1,110 @@
+/**
+ * sessions domain zod schemas (names derived from map keys: sessionListRequestSchema /
+ * sessionListValueSchema). SessionEvent passthrough = strict envelope (type/seq/time) + wide
+ * data: the merge-extensible event surface keeps an unknown-type branch at the union level,
+ * with no field-level passthrough. SessionId brand cast point: sessionIdSchema, and only there.
+ */
+
+import { z } from 'zod'
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
+import type { RequestPayload, ResponseValue } from './rpc-map.ts'
+import type { Wire } from './rpc.schema.ts'
+import type { HistoryEntry, SessionSummary } from './sessions.ts'
+import type { ToolEventView } from './events.ts'
+
+/** SessionId: one brand cast after shape validation (the only cast point in this domain). */
+export const sessionIdSchema = z.string().min(1) as unknown as z.ZodType<SessionId>
+
+/** SessionEvent passthrough: strict envelope, wide data (the client fold handles unknown types via its documented default). */
+export const sessionEventSchema = z.object({
+  type: z.string(),
+  seq: z.number().int().nonnegative(),
+  time: z.number(),
+  data: z.unknown(),
+  sourceEventSeqs: z.array(z.number()).optional(),
+  surfaceOp: z.unknown().optional(),
+}) as unknown as z.ZodType<SessionEvent>
+
+/** SessionSummary row of session.list. */
+export const sessionSummarySchema = z.object({
+  sessionId: sessionIdSchema,
+  updatedAt: z.number(),
+  running: z.boolean(),
+  parentSessionId: sessionIdSchema.optional(),
+  cwd: z.string().optional(),
+}) satisfies z.ZodType<Wire<SessionSummary>>
+
+/** session.list request payload (cursor is a reserved seat, unimplemented in v1). */
+export const sessionListRequestSchema = z.object({
+  cursor: z.string().optional(),
+}) satisfies z.ZodType<Wire<RequestPayload<'session.list'>>>
+
+/** session.list response value. */
+export const sessionListValueSchema = z.object({
+  items: z.array(sessionSummarySchema),
+}) satisfies z.ZodType<Wire<ResponseValue<'session.list'>>>
+
+/** session.create request payload. */
+export const sessionCreateRequestSchema = z.object({
+  cwd: z.string().optional(),
+}) satisfies z.ZodType<Wire<RequestPayload<'session.create'>>>
+
+/** session.create response value. */
+export const sessionCreateValueSchema = z.object({
+  sessionId: sessionIdSchema,
+}) satisfies z.ZodType<Wire<ResponseValue<'session.create'>>>
+
+/** session.history request payload (beforeSeq/maxMessages page backwards from the window tail). */
+export const sessionHistoryRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+  beforeSeq: z.number().int().nonnegative().optional(),
+  maxMessages: z.number().int().positive().optional(),
+}) satisfies z.ZodType<Wire<RequestPayload<'session.history'>>>
+
+/**
+ * ToolEventView passthrough: lock only the `for` discriminant and the presence
+ * of a card-tagged `view` object. The view interior is a host-computed product
+ * the client reads without echoing back; deep-validating it would hand-copy
+ * the dsh-tools vocabulary into this schema and drift with it.
+ */
+export const toolEventViewSchema = z.discriminatedUnion('for', [
+  z.object({ for: z.literal('call'), view: z.looseObject({ card: z.string() }) }),
+  z.object({ for: z.literal('result'), view: z.looseObject({ card: z.string() }) }),
+]) as unknown as z.ZodType<ToolEventView>
+
+/** One session.history item: the session event plus its optional host-computed tool view. */
+export const historyEntrySchema = z.object({
+  event: sessionEventSchema,
+  view: toolEventViewSchema.optional(),
+}) satisfies z.ZodType<Wire<HistoryEntry>>
+
+/** session.history response value. */
+export const sessionHistoryValueSchema = z.object({
+  events: z.array(historyEntrySchema),
+  hasMore: z.boolean(),
+}) satisfies z.ZodType<Wire<ResponseValue<'session.history'>>>
+
+/** ContentBlock passthrough: core is merge-extensible — the type discriminant envelope is strict, the rest stays wide. */
+export const contentBlockSchema = z.looseObject({ type: z.string() })
+
+/** session.prompt request payload. */
+export const sessionPromptRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+  mode: z.union([z.literal('queue'), z.literal('steer')]),
+  content: z.array(contentBlockSchema),
+}) as unknown as z.ZodType<RequestPayload<'session.prompt'>>
+
+/** session.prompt response value. */
+export const sessionPromptValueSchema = z.object({
+  accepted: z.literal(true),
+}) satisfies z.ZodType<Wire<ResponseValue<'session.prompt'>>>
+
+/** session.cancel request payload. */
+export const sessionCancelRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+}) satisfies z.ZodType<Wire<RequestPayload<'session.cancel'>>>
+
+/** session.cancel response value. */
+export const sessionCancelValueSchema = z.object({
+  accepted: z.literal(true),
+}) satisfies z.ZodType<Wire<ResponseValue<'session.cancel'>>>
diff --git a/packages/host/apiproxy/src/api/sessions.ts b/packages/host/apiproxy/src/api/sessions.ts
new file mode 100644
index 0000000000..393303f817
--- /dev/null
+++ b/packages/host/apiproxy/src/api/sessions.ts
@@ -0,0 +1,73 @@
+/**
+ * sessions domain contract. Method signatures are the source of truth:
+ * unary methods take the RpcRequest<P> narrow form and the impl echoes rpcId; everything
+ * else references RequestPayload<'session.*'> / ResponseValue<'session.*'>.
+ */
+
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
+import type { RpcId, RpcRequest, RpcResponse } from './rpc.ts'
+import type { ToolEventView } from './events.ts'
+
+declare module '@deepseek-ai/dsh-llm' {
+  interface MessageSourceMap {
+    /**
+     * The prompt's rpcId is passed through MessageSource into the `user/message` event
+     * (the client uses it to reconcile the optimistically
+     * echoed provisional message with the event stream). kind stays `'user'` — the model face
+     * carries no transport vocabulary; rpcId is an extra durable-JSON field passed back to the client with the event.
+     */
+    'user-rpc': { kind: 'user'; rpcId: RpcId }
+  }
+}
+
+/**
+ * One history page entry: the raw event plus the optional host-computed render
+ * intent (same semantics as the mux frame's `view` slot — a pagination-time
+ * derivation, never persisted).
+ */
+export interface HistoryEntry {
+  event: SessionEvent
+  view?: ToolEventView
+}
+
+/** Session list entry (v1 builds no index: list does readdir+stat). */
+export interface SessionSummary {
+  sessionId: SessionId
+  /** Persisted file mtime. */
+  updatedAt: number
+  /** Status of the attached agent; always false for cold (unattached) sessions. */
+  running: boolean
+  /** fork/spawn lineage (session.header.parentSession passthrough); absent for root sessions. */
+  parentSessionId?: SessionId
+  /** Session working directory (header.cwd passthrough); absent when unrecorded. */
+  cwd?: string
+}
+
+/** Session-domain unary methods (the map keys session.* of RpcMethodMap). */
+export interface SessionsApi {
+  /** Lists persisted sessions (updatedAt descending). v1 returns everything; cursor is a reserved seat, unimplemented. */
+  list(request: RpcRequest<{ cursor?: string }>): Promise<RpcResponse<{ items: SessionSummary[] }>>
+
+  /** Creates a new session (and its agent, idle and standing by). */
+  create(request: RpcRequest<{ cwd?: string }>): Promise<RpcResponse<{ sessionId: SessionId }>>
+
+  /**
+   * Reads a window of history events; page boundaries align to message boundaries: one page =
+   * all raw events owned by a whole number of messages (including their chunk / tool events),
+   * never cut mid-message. The tail page (beforeSeq absent) additionally carries the in-flight
+   * partial — chunk events already emitted for the last unfinalized message.
+   * Each entry pairs the raw SessionEvent with the host-computed view (tool events whose
+   * presenter produced one, evaluated against the registry at pagination time); the client
+   * rebuilds the surface from the events with the shared fold.
+   */
+  history(request: RpcRequest<{ sessionId: SessionId; beforeSeq?: number; maxMessages?: number }>):
+  Promise<RpcResponse<{ events: HistoryEntry[]; hasMore: boolean }>>
+
+  /** Sends a message. content is core's ContentBlock[] verbatim; mode maps 1:1 — queue→send, steer→steer. */
+  prompt(request: RpcRequest<{ sessionId: SessionId; mode: 'queue' | 'steer'; content: ContentBlock[] }>):
+  Promise<RpcResponse<{ accepted: true }>>
+
+  /** Stops: clears both FIFOs + aborts the current step (1:1 with agent.cancel). */
+  cancel(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<{ accepted: true }>>
+}
diff --git a/packages/host/apiproxy/src/fetch/client.ts b/packages/host/apiproxy/src/fetch/client.ts
new file mode 100644
index 0000000000..901cf7bd2a
--- /dev/null
+++ b/packages/host/apiproxy/src/fetch/client.ts
@@ -0,0 +1,302 @@
+/**
+ * Client side of the fetch carrier. AbstractApiClient holds every protocol invariant: rpcId minting,
+ * four-quadrant envelope wrap/unwrap, zod parsing, SSE frame decoding, and the payload-direct
+ * IApiClient domain methods (business code never mints). Platform differences ride two aspects:
+ * abstract doFetch (transport) + overridable onEnvelope (tap). ApiProxy (the impl face) is untouched.
+ */
+
+import type { z } from 'zod'
+import type { ApiProxy, HostFrame, MuxFrame } from '../api/index.ts'
+import type { RequestPayload, ResponseValue, RpcMethodMap } from '../api/rpc-map.ts'
+import type { ClientRequest, ClientResponse, RpcMessage, RpcReceipt, RpcRequest, RpcResponse, ServerRequest } from '../api/rpc.ts'
+import { RpcId } from '../api/rpc.ts'
+import type { Wire } from '../api/rpc.schema.ts'
+import { rpcReceiptSchema, serverRequestSchema, serverResponseSchema } from '../api/rpc.schema.ts'
+import { hostFrameSchema, muxFrameSchema } from '../api/events.schema.ts'
+import { hostDescribeValueSchema } from '../api/host.schema.ts'
+import {
+  sessionCancelValueSchema,
+  sessionCreateValueSchema,
+  sessionHistoryValueSchema,
+  sessionListValueSchema,
+  sessionPromptValueSchema,
+} from '../api/sessions.schema.ts'
+
+/**
+ * Client consumption face of the contract (shape a): same domain tree as ApiProxy, but unary
+ * methods take the business payload directly — the carrier mints the rpcId and wraps the
+ * envelope. Business code needing the call's rpcId reads it from the RpcResponse echo.
+ * Unary methods and respond accept an optional external AbortSignal as the last parameter
+ * (merged with the instance timeout via AbortSignal.any; same "signal rides beside the
+ * request, never on the wire" discipline as the stream signatures).
+ * Stream methods accept an optional onOpen callback: it fires once the SSE transport is
+ * readable (response headers received, before any frame) — the "stream established" signal
+ * connection controllers need for the readiness handshake. Generators are lazy, so the
+ * underlying fetch (and therefore onOpen) only happens once iteration starts.
+ * Relationship: ApiProxy is the narrow-form signature contract the impl side implements;
+ * IApiClient is the payload-direct view clients consume; AbstractApiClient bridges the two.
+ * Derived per method key from RpcMethodMap so a map row addition updates this mechanically.
+ */
+export interface IApiClient {
+  sessions: {
+    list(payload: RequestPayload<'session.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.list'>>>
+    create(payload: RequestPayload<'session.create'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.create'>>>
+    history(payload: RequestPayload<'session.history'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.history'>>>
+    prompt(payload: RequestPayload<'session.prompt'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.prompt'>>>
+    cancel(payload: RequestPayload<'session.cancel'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.cancel'>>>
+  }
+  host: {
+    describe(payload: RequestPayload<'host.describe'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.describe'>>>
+  }
+  events: {
+    mux(payload: Parameters<ApiProxy['events']['mux']>[0]['payload'], signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<MuxFrame>>
+    host(payload: Parameters<ApiProxy['events']['host']>[0]['payload'], signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<HostFrame>>
+  }
+  /** client-response passthrough (rpcId is a backfill of the server-request's id — never minted here). */
+  respond(message: ClientResponse, signal?: AbortSignal): Promise<RpcReceipt>
+}
+
+/**
+ * S→C second-level parse table: value schema by method (the response-path
+ * mirror of the handler's request table; key coverage compiler-enforced against RpcMethodMap).
+ */
+const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseValue<K>>> } = {
+  'session.list': sessionListValueSchema,
+  'session.create': sessionCreateValueSchema,
+  'session.history': sessionHistoryValueSchema,
+  'session.prompt': sessionPromptValueSchema,
+  'session.cancel': sessionCancelValueSchema,
+  'host.describe': hostDescribeValueSchema,
+}
+
+/** Default unary timeout (rpc-compare 2026-07-19: a hung host must not leave callers pending forever). */
+const DEFAULT_TIMEOUT_MS = 30_000
+
+/** URL base for in-process handler injection (fake authority, opencode precedent). */
+const INTERNAL_BASE = 'http://dsh.internal'
+
+/**
+ * Abstract fetch-carrier client. Subclasses supply the transport (doFetch) and may refine the
+ * per-message tap (onEnvelope) — platform aspects stay in subclasses, protocol invariants stay
+ * here. Envelope observation is a first-class aspect of this data middle layer: the instance
+ * owns a microtask-batched buffer (frame storms must not cost one consumer update per frame),
+ * and observers subscribe via subscribeEnvelopes. The isomorphic point survives: an in-process
+ * subclass whose doFetch is toFetchHandler(api).fetch never touches the network.
+ */
+export abstract class AbstractApiClient implements IApiClient {
+  /** Instance-owned observation buffer (module-level state would leak across instances/tests). */
+  private envelopeBatch: RpcMessage[] = []
+  private flushScheduled = false
+  private readonly envelopeListeners = new Set<(batch: readonly RpcMessage[]) => void>()
+
+  /** @param timeoutMs - unary timeout; streams never time out (long-lived by nature). */
+  constructor(protected readonly timeoutMs: number = DEFAULT_TIMEOUT_MS) {}
+
+  /** Transport aspect: browser fetch, injected handler.fetch, IPC bridge, ... */
+  protected abstract doFetch(input: URL, init?: RequestInit): Promise<Response>
+
+  /**
+   * Subscribe to batched envelope observation (diagnostics/logging consumers).
+   * Batches follow microtask boundaries; a listener throw is isolated (observation
+   * must never break the carrier).
+   * @param listener - receives each flushed batch in arrival order.
+   * @returns unsubscribe function.
+   */
+  subscribeEnvelopes(listener: (batch: readonly RpcMessage[]) => void): () => void {
+    this.envelopeListeners.add(listener)
+    return () => {
+      this.envelopeListeners.delete(listener)
+    }
+  }
+
+  /** Per-message tap: feeds the instance buffer. Subclasses may override to observe unbatched (call super to keep batching). */
+  protected onEnvelope(message: RpcMessage): void {
+    if (this.envelopeListeners.size === 0) return
+    this.envelopeBatch.push(message)
+    if (this.flushScheduled) return
+    this.flushScheduled = true
+    queueMicrotask(() => {
+      this.flushScheduled = false
+      // Never empty here: a flush is only ever scheduled by the push above,
+      // and this callback is the sole drain point.
+      const batch = this.envelopeBatch
+      this.envelopeBatch = []
+      for (const notify of this.envelopeListeners) {
+        try {
+          notify(batch)
+        } catch (error) {
+          console.error('[apiproxy] envelope listener threw:', error)
+        }
+      }
+    })
+  }
+
+  /** Browser = same-origin (a fake authority would fail DNS on real requests); no-location env (Node) = fake authority. */
+  protected resolveBase(): string {
+    const loc = (globalThis as { location?: { origin?: string } }).location
+    return loc?.origin !== undefined && loc.origin !== 'null' ? loc.origin : INTERNAL_BASE
+  }
+
+  protected mintRpcId(): RpcId {
+    // crypto.randomUUID is a Web API (browser + Node ≥19): keeps this base platform-neutral.
+    return RpcId(crypto.randomUUID())
+  }
+
+  /**
+   * Shared POST leg of both C→S carriers (callUnary/respond): JSON body,
+   * timeout merged with the caller's optional external signal, non-2xx → transport throw.
+   */
+  private async postJson(path: string, body: ClientRequest | ClientResponse, signal: AbortSignal | undefined): Promise<Response> {
+    const timeout = AbortSignal.timeout(this.timeoutMs)
+    const response = await this.doFetch(new URL(path, this.resolveBase()), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: signal === undefined ? timeout : AbortSignal.any([timeout, signal]),
+    })
+    if (!response.ok) throw new Error(`transport failure for ${path}: HTTP ${response.status}`)
+    return response
+  }
+
+  /**
+   * Unary protocol path: mint → tap → POST full form → envelope parse → verify
+   * echo → value parse → tap → narrow. Virtual so a fake carrier (fixture) can
+   * override transport at this layer.
+   */
+  protected async callUnary<K extends keyof RpcMethodMap>(
+    method: K,
+    payload: RequestPayload<K>,
+    signal?: AbortSignal,
+  ): Promise<RpcResponse<ResponseValue<K>>> {
+    const message: ClientRequest = { type: 'client-request', rpcId: this.mintRpcId(), method, payload }
+    this.onEnvelope(message)
+    const response = await this.postJson(`/api/${method}`, message, signal)
+    const full = serverResponseSchema.parse(await response.json())
+    this.onEnvelope(full)
+    if (full.rpcId !== message.rpcId) throw new Error(`rpcId mismatch for ${method}: sent ${message.rpcId}, got ${full.rpcId}`)
+    if (!full.result.ok) return { rpcId: full.rpcId, result: full.result }
+    // Second-level S→C parse: the ok value must match the method's Value schema (mirror of the
+    // handler's request-payload parse). The cast collapses the Wire<> widening, same as the handler side.
+    const value = UNARY_VALUE_SCHEMAS[method].parse(full.result.value) as ResponseValue<K>
+    return { rpcId: full.rpcId, result: { ok: true, value } }
+  }
+
+  /** Mux stream opener; virtual for the same override reason as callUnary. */
+  protected openMux(_payload: Parameters<ApiProxy['events']['mux']>[0]['payload'], signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<MuxFrame>> {
+    return this.readSse('/api/events.mux', signal, muxFrameSchema, onOpen)
+  }
+
+  /** Host stream opener; virtual. */
+  protected openHost(_payload: Parameters<ApiProxy['events']['host']>[0]['payload'], signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<HostFrame>> {
+    return this.readSse('/api/events.host', signal, hostFrameSchema, onOpen)
+  }
+
+  /**
+   * SSE protocol path: streaming fetch (not EventSource), '\n\n' framing, ServerRequest envelope +
+   * frame-schema parse, tap, narrow yield. onOpen fires once the response headers are in and the
+   * body is readable — the stream-established signal, before any frame arrives. A frame that fails
+   * either parse level is reported and skipped (one corrupt frame must not kill the stream; the
+   * client's gap detection covers whatever the frame carried).
+   */
+  protected async *readSse<F extends MuxFrame | HostFrame>(
+    path: string,
+    signal: AbortSignal,
+    frameSchema: z.ZodType<F>,
+    onOpen?: () => void,
+  ): AsyncGenerator<RpcRequest<F>> {
+    const response = await this.doFetch(new URL(path, this.resolveBase()), { signal })
+    if (!response.ok || response.body === null) throw new Error(`transport failure for ${path}: HTTP ${response.status}`)
+    onOpen?.()
+    const reader = response.body.getReader()
+    const decoder = new TextDecoder()
+    let buffer = ''
+    try {
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) return
+        buffer += decoder.decode(value, { stream: true })
+        let boundary: number
+        while ((boundary = buffer.indexOf('\n\n')) !== -1) {
+          const chunk = buffer.slice(0, boundary)
+          buffer = buffer.slice(boundary + 2)
+          const data = chunk.split('\n').filter(line => line.startsWith('data: ')).map(line => line.slice(6)).join('')
+          if (data === '') continue
+          let full: ServerRequest
+          let frame: F
+          try {
+            full = serverRequestSchema.parse(JSON.parse(data))
+            frame = frameSchema.parse(full.payload)
+          } catch (error) {
+            console.error(`[apiproxy] dropping malformed SSE frame on ${path}:`, error)
+            continue
+          }
+          this.onEnvelope(full)
+          yield { rpcId: full.rpcId, payload: frame }
+        }
+      }
+    } finally {
+      await reader.cancel().catch(() => undefined)
+    }
+  }
+
+  // ---- IApiClient surface (arrow properties so destructured/passed references stay bound) ----
+
+  readonly sessions: IApiClient['sessions'] = {
+    list: (payload, signal) => this.callUnary('session.list', payload, signal),
+    create: (payload, signal) => this.callUnary('session.create', payload, signal),
+    history: (payload, signal) => this.callUnary('session.history', payload, signal),
+    prompt: (payload, signal) => this.callUnary('session.prompt', payload, signal),
+    cancel: (payload, signal) => this.callUnary('session.cancel', payload, signal),
+  }
+
+  readonly host: IApiClient['host'] = {
+    describe: (payload, signal) => this.callUnary('host.describe', payload, signal),
+  }
+
+  readonly events: IApiClient['events'] = {
+    mux: (payload, signal, onOpen) => this.openMux(payload, signal, onOpen),
+    host: (payload, signal, onOpen) => this.openHost(payload, signal, onOpen),
+  }
+
+  async respond(message: ClientResponse, signal?: AbortSignal): Promise<RpcReceipt> {
+    this.onEnvelope(message)
+    const response = await this.postJson('/api/respond', message, signal)
+    return rpcReceiptSchema.parse(await response.json())
+  }
+}
+
+/**
+ * In-process client over an injected fetch-shaped handler (the isomorphic point:
+ * `new InProcessApiClient(toFetchHandler(api))` never touches the network). Lives here because
+ * in-process injection is this package's own capability (handler and client are both local).
+ */
+export class InProcessApiClient extends AbstractApiClient {
+  constructor(private readonly handler: { fetch: typeof fetch }, timeoutMs?: number) {
+    super(timeoutMs)
+  }
+
+  /**
+   * Faithful to real fetch: reject on signal abort even when the in-process
+   * handler ignores the signal (a hung impl must not defeat timeout/cancel).
+   */
+  protected doFetch(input: URL, init?: RequestInit): Promise<Response> {
+    const signal = init?.signal ?? undefined
+    if (signal === undefined) return this.handler.fetch(input, init)
+    if (signal.aborted) return Promise.reject(abortError(signal))
+    return new Promise((resolve, reject) => {
+      const onAbort = (): void => { reject(abortError(signal)) }
+      signal.addEventListener('abort', onAbort, { once: true })
+      this.handler.fetch(input, init)
+        .then(resolve, reject)
+        .finally(() => { signal.removeEventListener('abort', onAbort) })
+    })
+  }
+}
+
+/** Mirror fetch's abort rejection: the signal's reason when present, else a DOMException-style AbortError. */
+function abortError(signal: AbortSignal): Error {
+  const reason: unknown = signal.reason
+  if (reason instanceof Error) return reason
+  if (typeof reason === 'string') return new Error(reason)
+  return new Error('This operation was aborted')
+}
diff --git a/packages/host/apiproxy/src/fetch/handler.ts b/packages/host/apiproxy/src/fetch/handler.ts
new file mode 100644
index 0000000000..03b9f6500f
--- /dev/null
+++ b/packages/host/apiproxy/src/fetch/handler.ts
@@ -0,0 +1,197 @@
+/**
+ * Server side of the fetch carrier: maps an ApiProxy onto a pure
+ * WHATWG Request->Response function. Two-level parse: full form (type/rpcId/method +
+ * path==method) -> payload dispatched per method. HTTP status expresses only the carrier
+ * (404 unknown path / 400 non-JSON body / 500 handler crash); business errors are always
+ * 200 + ServerResponse.
+ */
+
+import { randomUUID } from 'node:crypto'
+import type { z } from 'zod'
+import type { ApiProxy, MuxFrame, HostFrame } from '../api/index.ts'
+import type { RequestPayload, ResponseValue, RpcMethodMap } from '../api/rpc-map.ts'
+import type { ClientRequest, RpcError, RpcRequest, RpcResponse, ServerRequest, ServerResponse } from '../api/rpc.ts'
+import { RpcId } from '../api/rpc.ts'
+import type { Wire } from '../api/rpc.schema.ts'
+import { clientRequestSchema, clientResponseSchema } from '../api/rpc.schema.ts'
+import {
+  sessionCancelRequestSchema,
+  sessionCreateRequestSchema,
+  sessionHistoryRequestSchema,
+  sessionListRequestSchema,
+  sessionPromptRequestSchema,
+} from '../api/sessions.schema.ts'
+import { hostDescribeRequestSchema } from '../api/host.schema.ts'
+
+/**
+ * Unary dispatch table, keyed by (and compiler-locked to) RpcMethodMap: a map row without a
+ * route row fails to compile, and each row's schema/invoke pair is checked against that row's
+ * payload type — a schema pasted onto the wrong row is a type error, not a runtime surprise.
+ * Schemas anchor to the Wire<> widening (the repo-wide exactOptionalPropertyTypes accommodation
+ * documented on Wire); the dispatch point carries the one Wire→exact cast.
+ */
+type UnaryRoutes = {
+  [K in keyof RpcMethodMap]: {
+    schema: z.ZodType<Wire<RequestPayload<K>>>
+    invoke(api: ApiProxy, request: RpcRequest<RequestPayload<K>>): Promise<RpcResponse<ResponseValue<K>>>
+  }
+}
+
+const UNARY_ROUTES: UnaryRoutes = {
+  'session.list': { schema: sessionListRequestSchema, invoke: (api, r) => api.sessions.list(r) },
+  'session.create': { schema: sessionCreateRequestSchema, invoke: (api, r) => api.sessions.create(r) },
+  'session.history': { schema: sessionHistoryRequestSchema, invoke: (api, r) => api.sessions.history(r) },
+  'session.prompt': { schema: sessionPromptRequestSchema, invoke: (api, r) => api.sessions.prompt(r) },
+  'session.cancel': { schema: sessionCancelRequestSchema, invoke: (api, r) => api.sessions.cancel(r) },
+  'host.describe': { schema: hostDescribeRequestSchema, invoke: (api, r) => api.host.describe(r) },
+}
+
+/** Route lookup that narrows an arbitrary path segment to a map key (single cast point for the string→key refinement). */
+function methodFor(path: string): keyof RpcMethodMap | undefined {
+  return Object.hasOwn(UNARY_ROUTES, path) ? path as keyof RpcMethodMap : undefined
+}
+
+/**
+ * Sentinel rpcId for error responses to envelopes whose own rpcId is unreadable: the response
+ * must still be a valid ServerResponse (a self-violating shape would turn the server's explicit
+ * bad-request report into a client-side parse failure). Fixed value, documented here as wire contract.
+ */
+const INVALID_REQUEST_RPC_ID = RpcId('invalid-request')
+
+/** Wrap a business error as a ServerResponse full form (rpcId backfilled; an unreadable rpcId uses the invalid-request sentinel). */
+function errorResponse(rpcId: RpcId, error: RpcError): Response {
+  const body: ServerResponse = { type: 'server-response', rpcId, result: { ok: false, error } }
+  return Response.json(body)
+}
+
+/** Complete the impl's narrow form into a ServerResponse full form. */
+function fullResponse(narrow: RpcResponse<unknown>): Response {
+  const body: ServerResponse = { type: 'server-response', rpcId: narrow.rpcId, result: narrow.result }
+  return Response.json(body)
+}
+
+/**
+ * Parse the payload and invoke one unary route. Generic over the map key so
+ * the row's schema/invoke pairing typechecks; the only cast collapses the
+ * Wire<> widening back to the exact payload (undefined-valued properties and
+ * absent ones are indistinguishable after JSON transport).
+ */
+// K appears once in the signature but ties the UNARY_ROUTES[K] row lookup to its own
+// schema/invoke pairing; a union parameter degrades the row to an uninvokable intersection.
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+async function handleUnary<K extends keyof RpcMethodMap>(api: ApiProxy, method: K, message: ClientRequest): Promise<Response> {
+  const route = UNARY_ROUTES[method]
+  const payload = route.schema.safeParse(message.payload)
+  if (!payload.success) {
+    return errorResponse(message.rpcId, { code: 'bad-request', message: `invalid payload for ${method}`, details: { issues: payload.error.issues } })
+  }
+  try {
+    return fullResponse(await route.invoke(api, { rpcId: message.rpcId, payload: payload.data }))
+  } catch (error: unknown) {
+    // The impl never throws business errors; reaching here means the implementation itself crashed — 500, carrier layer.
+    return new Response(`handler failure: ${String(error)}`, { status: 500 })
+  }
+}
+
+/** SSE frame: complete the narrow RpcRequest<frame> into a ServerRequest full form (method = frame type). */
+function fullFrame(narrow: RpcRequest<MuxFrame | HostFrame>): ServerRequest {
+  return { type: 'server-request', rpcId: narrow.rpcId, method: narrow.payload.type, payload: narrow.payload }
+}
+
+/**
+ * Wrap a frame stream as an SSE Response; stops when req.signal aborts. An
+ * impl throw mid-stream emits one stream/error frame and then closes.
+ */
+function sseResponse(frames: AsyncIterable<RpcRequest<MuxFrame | HostFrame>>): Response {
+  const encoder = new TextEncoder()
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      try {
+        // Send an SSE comment line on open so clients/proxies see a live channel (the host
+        // stream has no baseline frames and would otherwise emit zero bytes while idle;
+        // a comment line is not a frame, so client frame parsing skips it naturally).
+        controller.enqueue(encoder.encode(': connected\n\n'))
+        for await (const narrow of frames) {
+          controller.enqueue(encoder.encode(`data: ${JSON.stringify(fullFrame(narrow))}\n\n`))
+        }
+      } catch (error: unknown) {
+        // Mid-stream impl failure → one stream/error frame, then close: the client must see
+        // the failure instead of a silent end (which reads as a normal disconnect). A fresh
+        // rpcId is minted — this is a server-initiated push like any other frame.
+        const failure: MuxFrame | HostFrame = { type: 'stream/error', error: { code: 'internal', message: String(error), details: {} } }
+        try {
+          controller.enqueue(encoder.encode(`data: ${JSON.stringify(fullFrame({ rpcId: RpcId(randomUUID()), payload: failure }))}\n\n`))
+        } catch {
+          // Consumer already cancelled the stream: enqueue-after-cancel is the
+          // only reachable error, and there is no one left to tell.
+        }
+      } finally {
+        try {
+          controller.close()
+        } catch { /* already cancelled by the consumer: a double close is the only reachable error */ }
+      }
+    },
+  })
+  return new Response(stream, {
+    headers: { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' },
+  })
+}
+
+/**
+ * Wraps an ApiProxy into a pure fetch function (isomorphic point: feed the returned fetch straight to InProcessApiClient).
+ * @param api - the host-side ApiProxy implementation.
+ * @returns an object holding `fetch(Request)`; paths outside /api/ return 404.
+ */
+export function toFetchHandler(api: ApiProxy): { fetch: typeof fetch } {
+  return {
+    // Signature matches global fetch: the isomorphic point hands this function to InProcessApiClient as its transport aspect,
+    // Clients call in (url, init) form — normalize to Request before handling.
+    async fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+      const req = input instanceof Request ? input : new Request(input, init)
+      const url = new URL(req.url)
+      const path = url.pathname
+
+      if (path === '/api/events.mux' && req.method === 'GET') {
+        return sseResponse(api.events.mux({ rpcId: RpcId(randomUUID()), payload: {} }, req.signal))
+      }
+      if (path === '/api/events.host' && req.method === 'GET') {
+        return sseResponse(api.events.host({ rpcId: RpcId(randomUUID()), payload: {} }, req.signal))
+      }
+
+      if (req.method !== 'POST' || !path.startsWith('/api/')) {
+        return new Response('not found', { status: 404 })
+      }
+
+      let body: unknown
+      try {
+        body = await req.json()
+      } catch {
+        // 400 = carrier layer (body is not even JSON); valid JSON with a bad shape goes 200 + bad-request.
+        return new Response('body is not JSON', { status: 400 })
+      }
+
+      if (path === '/api/respond') {
+        const parsed = clientResponseSchema.safeParse(body)
+        if (!parsed.success) return Response.json({ accepted: false, reason: 'bad-response' })
+        return Response.json(await api.respond(parsed.data))
+      }
+
+      const method = methodFor(path.slice('/api/'.length))
+      if (method === undefined) return new Response('not found', { status: 404 })
+
+      const envelope = clientRequestSchema.safeParse(body)
+      if (!envelope.success) {
+        // Best effort at correlation: salvage a string rpcId from the raw body;
+        // otherwise the fixed sentinel keeps the response a valid ServerResponse.
+        const rawId = (body as { rpcId?: unknown } | null)?.rpcId
+        const rpcId = typeof rawId === 'string' ? RpcId(rawId) : INVALID_REQUEST_RPC_ID
+        return errorResponse(rpcId, { code: 'bad-request', message: 'invalid client-request message', details: { issues: envelope.error.issues } })
+      }
+      const message: ClientRequest = envelope.data
+      if (message.method !== method) {
+        return errorResponse(message.rpcId, { code: 'bad-request', message: `method "${message.method}" does not match path "${method}"`, details: { issues: [] } })
+      }
+      return handleUnary(api, method, message)
+    },
+  }
+}
diff --git a/packages/host/apiproxy/src/index.ts b/packages/host/apiproxy/src/index.ts
new file mode 100644
index 0000000000..2999e48b24
--- /dev/null
+++ b/packages/host/apiproxy/src/index.ts
@@ -0,0 +1,13 @@
+/**
+ * @deepseek-ai/dsh-host-apiproxy — the front layer every client shape shares:
+ * the ApiProxy contract (api/: types + zod schemas, browser-safe) and the
+ * fetch carrier pair (fetch/: toFetchHandler on the host side, AbstractApiClient +
+ * platform subclasses on the client side). Host assembly (bootHost/createApiProxy/startHost)
+ * lives in @deepseek-ai/dsh-host-runtime.
+ */
+
+export type * from './api/index.ts'
+export { RpcId } from './api/rpc.ts'
+export { toFetchHandler } from './fetch/handler.ts'
+export { AbstractApiClient, InProcessApiClient } from './fetch/client.ts'
+export type { IApiClient } from './fetch/client.ts'
diff --git a/packages/host/apiproxy/src/invariant.ts b/packages/host/apiproxy/src/invariant.ts
new file mode 100644
index 0000000000..068cbcaa72
--- /dev/null
+++ b/packages/host/apiproxy/src/invariant.ts
@@ -0,0 +1,33 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-host-apiproxy`.
+ * @module @deepseek-ai/dsh-host-apiproxy/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-host-apiproxy'
+
+/** Cordis companion plugin name. */
+export const name = 'host-apiproxy-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package is the wire contract layer (types,
+ * schemas, fetch carrier glue) — it emits no cordis events and owns no
+ * mutable cross-plugin relation. rpcId round-trip and schema acceptance are
+ * enforced at the carrier boundary and exercised by the protocol-isomorphism
+ * suite; the live implementation relations belong to dsh-host-runtime.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/host/apiproxy/tests/client-handler.spec.ts b/packages/host/apiproxy/tests/client-handler.spec.ts
new file mode 100644
index 0000000000..25af7e2f75
--- /dev/null
+++ b/packages/host/apiproxy/tests/client-handler.spec.ts
@@ -0,0 +1,407 @@
+/**
+ * Wire-protocol coverage over the isomorphic point: InProcessApiClient →
+ * toFetchHandler(scripted impl) runs the real envelope wrap/unwrap, zod
+ * two-level parse, rpcId discipline, and SSE framing with no network and no
+ * browser. Each case scripts its own minimal ApiProxy.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { ApiProxy, HostFrame, MuxFrame, RpcMessage, RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy'
+import { InProcessApiClient, RpcId, toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
+
+const sid = (id: string): SessionId => id as SessionId
+
+function ok<T>(request: RpcRequest<unknown>, value: T): Promise<RpcResponse<T>> {
+  return Promise.resolve({ rpcId: request.rpcId, result: { ok: true, value } })
+}
+
+/** Scripted impl: every method resolves an empty-ish OK unless a case overrides it. */
+function scriptedApi(overrides: {
+  sessions?: Partial<ApiProxy['sessions']>
+  host?: Partial<ApiProxy['host']>
+  events?: Partial<ApiProxy['events']>
+  respond?: ApiProxy['respond']
+} = {}): ApiProxy {
+  async function *empty<F>(): AsyncGenerator<RpcRequest<F>> { /* no frames */ }
+  return {
+    sessions: {
+      list: r => ok(r, { items: [] }),
+      create: r => ok(r, { sessionId: sid('s-new') }),
+      history: r => ok(r, { events: [], hasMore: false }),
+      prompt: r => ok(r, { accepted: true as const }),
+      cancel: r => ok(r, { accepted: true as const }),
+      ...overrides.sessions,
+    },
+    host: { describe: r => ok(r, { version: '0-test', cwd: '/t', attachedSessions: 0 }), ...overrides.host },
+    events: { mux: () => empty<MuxFrame>(), host: () => empty<HostFrame>(), ...overrides.events },
+    respond: overrides.respond ?? (() => Promise.resolve({ accepted: false as const, reason: 'not-pending' as const })),
+  }
+}
+
+function client(api: ApiProxy, timeoutMs?: number): InProcessApiClient {
+  return new InProcessApiClient(toFetchHandler(api), timeoutMs)
+}
+
+describe('unary round trip', () => {
+  it('carries payload out and value back through the full wire form', async () => {
+    let seen: RpcRequest<{ cursor?: string }> | undefined
+    const api = scriptedApi({
+      sessions: {
+        list: (r) => {
+          seen = r
+          return ok(r, { items: [{ sessionId: sid('s1'), updatedAt: 7, running: false }] })
+        },
+      },
+    })
+    const response = await client(api).sessions.list({ cursor: 'c1' })
+    // Impl received the narrow form with a minted id; client returned the same id and value.
+    expect(seen?.payload).toEqual({ cursor: 'c1' })
+    expect(seen?.rpcId).toBeTruthy()
+    expect(response.rpcId).toBe(seen?.rpcId)
+    expect(response.result).toEqual({ ok: true, value: { items: [{ sessionId: 's1', updatedAt: 7, running: false }] } })
+  })
+
+  it('passes business errors through as 200 + err result, not a throw', async () => {
+    const api = scriptedApi({
+      sessions: {
+        cancel: r => Promise.resolve({ rpcId: r.rpcId, result: { ok: false, error: { code: 'session-not-found', message: 'nope', details: { sessionId: sid('sx') } } } }),
+      },
+    })
+    const response = await client(api).sessions.cancel({ sessionId: sid('sx') })
+    expect(response.result).toEqual({ ok: false, error: { code: 'session-not-found', message: 'nope', details: { sessionId: 'sx' } } })
+  })
+
+  it('throws on rpcId echo mismatch', async () => {
+    const api = scriptedApi({
+      sessions: { list: () => Promise.resolve({ rpcId: RpcId('forged'), result: { ok: true, value: { items: [] } } }) },
+    })
+    await expect(client(api).sessions.list({})).rejects.toThrow(/rpcId mismatch/)
+  })
+
+  it('rejects an invalid payload at the handler as 200 + bad-request with issues', async () => {
+    const api = scriptedApi()
+    const response = await client(api).sessions.history({ sessionId: 123 as unknown as SessionId })
+    expect(response.result.ok).toBe(false)
+    if (!response.result.ok) {
+      expect(response.result.error.code).toBe('bad-request')
+      expect((response.result.error.details as { issues: unknown[] }).issues.length).toBeGreaterThan(0)
+    }
+  })
+
+  it('rejects a method/path mismatch as bad-request', async () => {
+    const handler = toFetchHandler(scriptedApi())
+    const body = { type: 'client-request', rpcId: 'r1', method: 'session.create', payload: {} }
+    const response = await handler.fetch('http://dsh.internal/api/session.list', { method: 'POST', body: JSON.stringify(body) })
+    expect(response.status).toBe(200)
+    const parsed = await response.json() as { result: { ok: boolean; error?: { code: string; message: string } } }
+    expect(parsed.result.ok).toBe(false)
+    expect(parsed.result.error?.code).toBe('bad-request')
+    expect(parsed.result.error?.message).toMatch(/does not match path/)
+  })
+
+  it('rejects a malformed envelope as bad-request, salvaging the rpcId or falling back to the sentinel', async () => {
+    const handler = toFetchHandler(scriptedApi())
+    // No salvageable rpcId → the fixed invalid-request sentinel keeps the response a valid ServerResponse.
+    const noId = await handler.fetch('http://dsh.internal/api/session.list', { method: 'POST', body: JSON.stringify({ nonsense: true }) })
+    expect(noId.status).toBe(200)
+    const noIdParsed = await noId.json() as { rpcId: string; result: { ok: boolean } }
+    expect(noIdParsed.result.ok).toBe(false)
+    expect(noIdParsed.rpcId).toBe('invalid-request')
+    // A string rpcId in the otherwise-bad body is salvaged for correlation.
+    const withId = await handler.fetch('http://dsh.internal/api/session.list', { method: 'POST', body: JSON.stringify({ rpcId: 'salvage-me', nonsense: true }) })
+    const withIdParsed = await withId.json() as { rpcId: string; result: { ok: boolean } }
+    expect(withIdParsed.result.ok).toBe(false)
+    expect(withIdParsed.rpcId).toBe('salvage-me')
+  })
+
+  it('maps carrier failures to HTTP statuses and the client throws transport failure', async () => {
+    const handler = toFetchHandler(scriptedApi())
+    // Unknown method → 404.
+    const notFound = await handler.fetch('http://dsh.internal/api/no.such', { method: 'POST', body: '{}' })
+    expect(notFound.status).toBe(404)
+    // Non-JSON body → 400.
+    const badBody = await handler.fetch('http://dsh.internal/api/session.list', { method: 'POST', body: '{oops' })
+    expect(badBody.status).toBe(400)
+    // Impl crash → 500, and through the client that is a throw, not an err result.
+    const crashing = scriptedApi({ sessions: { list: () => { throw new Error('impl exploded') } } })
+    await expect(client(crashing).sessions.list({})).rejects.toThrow(/transport failure .*500/)
+  })
+
+  it('rejects when the transport never resolves within timeoutMs', async () => {
+    // AbortSignal.timeout is immune to fake timers; a short real timeout keeps this fast.
+    const never = new InProcessApiClient({
+      fetch: (_i: RequestInfo | URL, init?: RequestInit) => new Promise<Response>((_resolve, reject) => {
+        init?.signal?.addEventListener('abort', () => { reject(new Error('aborted by timeout')) })
+      }),
+    }, 25)
+    await expect(never.sessions.list({})).rejects.toThrow()
+  })
+
+  it('aborts a unary call through the caller-supplied external signal', async () => {
+    // Real-fetch semantics: on abort the rejection is the signal's reason, and the abort
+    // works even when the transport ignores the signal entirely (hung impl).
+    const gate = new AbortController()
+    const hung = new InProcessApiClient({ fetch: () => new Promise<Response>(() => {}) }, 60_000)
+    const call = hung.sessions.list({}, gate.signal)
+    gate.abort(new Error('externally aborted'))
+    await expect(call).rejects.toThrow(/externally aborted/)
+  })
+
+  it('rejects an already-aborted signal before touching the transport, mapping a string reason to an Error', async () => {
+    let touched = false
+    const c = new InProcessApiClient({
+      fetch: () => {
+        touched = true
+        return Promise.resolve(new Response('{}'))
+      },
+    }, 60_000)
+    const gate = new AbortController()
+    gate.abort('gone before start')
+    await expect(c.sessions.list({}, gate.signal)).rejects.toThrow('gone before start')
+    expect(touched).toBe(false)
+  })
+
+  it('maps a non-Error, non-string abort reason to the default AbortError message', async () => {
+    const gate = new AbortController()
+    const hung = new InProcessApiClient({ fetch: () => new Promise<Response>(() => {}) }, 60_000)
+    const call = hung.sessions.list({}, gate.signal)
+    gate.abort(42)
+    await expect(call).rejects.toThrow('This operation was aborted')
+  })
+
+  it('passes a signal-less doFetch straight through to the handler', async () => {
+    class Probe extends InProcessApiClient {
+      direct(url: URL): Promise<Response> {
+        return this.doFetch(url)
+      }
+    }
+    const probe = new Probe({ fetch: () => Promise.resolve(new Response('raw')) })
+    const response = await probe.direct(new URL('http://dsh.internal/probe'))
+    expect(await response.text()).toBe('raw')
+  })
+
+  it('throws on an S→C ok value that fails the method value schema (second-level parse)', async () => {
+    // Impl echoes rpcId but returns a wrong-shaped value: envelope parse passes, value parse must reject.
+    const api = scriptedApi({
+      sessions: { list: r => Promise.resolve({ rpcId: r.rpcId, result: { ok: true, value: { items: 'not-an-array' } } }) as never },
+    })
+    await expect(client(api).sessions.list({})).rejects.toThrow()
+  })
+})
+
+describe('SSE stream path', () => {
+  it('yields frames in order and skips the comment preamble', async () => {
+    const frames: MuxFrame[] = [
+      { type: 'session/subscribed', sessionId: sid('s1'), lastSeq: 3 },
+      { type: 'stream/error', error: { code: 'internal', message: 'x', details: {} } },
+    ]
+    const api = scriptedApi({
+      events: {
+        async *mux(request) {
+          let n = 0
+          for (const frame of frames) yield { rpcId: RpcId(`push-${n++}-${request.rpcId}`), payload: frame }
+        },
+      },
+    })
+    const seen: MuxFrame[] = []
+    for await (const envelope of client(api).events.mux({}, new AbortController().signal)) {
+      seen.push(envelope.payload)
+    }
+    expect(seen).toEqual(frames)
+  })
+
+  it('reassembles frames across arbitrary chunk boundaries', async () => {
+    // Two SSE frames split so one frame spans chunks and one chunk carries parts of both.
+    const f1 = { type: 'server-request', rpcId: 'a', method: 'session/subscribed', payload: { type: 'session/subscribed', sessionId: 's1', lastSeq: 1 } }
+    const f2 = { type: 'server-request', rpcId: 'b', method: 'session/subscribed', payload: { type: 'session/subscribed', sessionId: 's2', lastSeq: 2 } }
+    const wire = `: connected\n\ndata: ${JSON.stringify(f1)}\n\ndata: ${JSON.stringify(f2)}\n\n`
+    const cuts = [5, 40, wire.indexOf('data: ', 40) + 3]
+    const encoder = new TextEncoder()
+    const doFetch = (): Promise<Response> => Promise.resolve(new Response(new ReadableStream<Uint8Array>({
+      start(controller) {
+        let prev = 0
+        for (const cut of [...cuts, wire.length]) {
+          controller.enqueue(encoder.encode(wire.slice(prev, cut)))
+          prev = cut
+        }
+        controller.close()
+      },
+    }), { status: 200 }))
+    const chopped = new InProcessApiClient({ fetch: doFetch })
+    const seen: string[] = []
+    for await (const envelope of chopped.events.mux({}, new AbortController().signal)) {
+      seen.push((envelope.payload as { sessionId: string }).sessionId)
+      expect(envelope.rpcId).toBe(seen.length === 1 ? 'a' : 'b')
+    }
+    expect(seen).toEqual(['s1', 's2'])
+  })
+
+  it('emits a stream/error frame then closes when the impl throws mid-stream', async () => {
+    const api = scriptedApi({
+      events: {
+        async *host(request): AsyncGenerator<RpcRequest<HostFrame>> {
+          yield { rpcId: RpcId(`p-${request.rpcId}`), payload: { type: 'host/session-added', sessionId: sid('s1') } }
+          throw new Error('impl died mid-stream')
+        },
+      },
+    })
+    const seen: HostFrame[] = []
+    for await (const envelope of client(api).events.host({}, new AbortController().signal)) {
+      seen.push(envelope.payload)
+    }
+    expect(seen.map(f => f.type)).toEqual(['host/session-added', 'stream/error'])
+    const last = seen.at(-1)
+    if (last?.type === 'stream/error') expect(last.error.message).toMatch(/impl died mid-stream/)
+  })
+
+  it('drops a malformed SSE frame and keeps the stream alive (S→C two-level parse)', async () => {
+    const good = { type: 'server-request', rpcId: 'g1', method: 'session/subscribed', payload: { type: 'session/subscribed', sessionId: 's1', lastSeq: 1 } }
+    const badEnvelope = { type: 'server-response', rpcId: 'x' } // wrong quadrant for a stream
+    const badFrame = { type: 'server-request', rpcId: 'b1', method: 'nope', payload: { type: 'no/such-frame' } }
+    const wire = [
+      'data: {oops', // not JSON
+      `data: ${JSON.stringify(badEnvelope)}`,
+      `data: ${JSON.stringify(badFrame)}`,
+      `data: ${JSON.stringify(good)}`,
+    ].map(l => `${l}\n\n`).join('')
+    const doFetch = (): Promise<Response> => Promise.resolve(new Response(new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode(wire))
+        controller.close()
+      },
+    }), { status: 200 }))
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    try {
+      const seen: MuxFrame[] = []
+      for await (const envelope of new InProcessApiClient({ fetch: doFetch }).events.mux({}, new AbortController().signal)) {
+        seen.push(envelope.payload)
+      }
+      // The three corrupt frames are reported and skipped; the good one still arrives.
+      expect(seen).toEqual([{ type: 'session/subscribed', sessionId: 's1', lastSeq: 1 }])
+      expect(errorSpy.mock.calls.length).toBe(3)
+    } finally {
+      errorSpy.mockRestore()
+    }
+  })
+
+  it('fires onOpen once headers are in, before the first frame, and not on transport failure', async () => {
+    const api = scriptedApi({
+      events: {
+        async *mux(request): AsyncGenerator<RpcRequest<MuxFrame>> {
+          yield { rpcId: RpcId(`p-${request.rpcId}`), payload: { type: 'session/subscribed', sessionId: sid('s1'), lastSeq: 0 } }
+        },
+      },
+    })
+    const order: string[] = []
+    const iterator = client(api).events.mux({}, new AbortController().signal, () => order.push('open'))
+    expect(order).toEqual([]) // lazy generator: no fetch (and no onOpen) before iteration
+    for await (const _ of iterator) order.push('frame')
+    expect(order).toEqual(['open', 'frame'])
+
+    // Transport failure path: onOpen must not fire.
+    const failing = new InProcessApiClient({ fetch: () => Promise.resolve(new Response('down', { status: 503 })) })
+    const failOrder: string[] = []
+    await expect((async () => {
+      for await (const _ of failing.events.mux({}, new AbortController().signal, () => failOrder.push('open'))) { /* unreachable */ }
+    })()).rejects.toThrow(/transport failure/)
+    expect(failOrder).toEqual([])
+  })
+
+  it('stops consuming when the caller aborts', async () => {
+    let implSawAbort = false
+    const api = scriptedApi({
+      events: {
+        async *mux(_request, signal): AsyncGenerator<RpcRequest<MuxFrame>> {
+          try {
+            let n = 0
+            while (true) {
+              yield { rpcId: RpcId(`p${n}`), payload: { type: 'session/subscribed', sessionId: sid('s1'), lastSeq: n++ } }
+              await new Promise(resolve => setTimeout(resolve, 5))
+              if (signal.aborted) return
+            }
+          } finally {
+            implSawAbort = true
+          }
+        },
+      },
+    })
+    const abort = new AbortController()
+    let count = 0
+    // In-process abort ends the stream (impl returns on signal.aborted); over a real
+    // network fetch the same abort surfaces as a rejection — both stop the loop.
+    await (async () => {
+      for await (const _ of client(api).events.mux({}, abort.signal)) {
+        if (++count === 2) abort.abort()
+      }
+    })().catch(() => undefined)
+    expect(count).toBe(2)
+    // Generator teardown may lag the abort by a microtask; poll briefly.
+    await vi.waitFor(() => { expect(implSawAbort).toBe(true) })
+  })
+})
+
+describe('respond path', () => {
+  it('round-trips a client-response to a receipt', async () => {
+    const seen: unknown[] = []
+    const api = scriptedApi({
+      respond: (message) => {
+        seen.push(message)
+        return Promise.resolve({ accepted: true as const })
+      },
+    })
+    const receipt = await client(api).respond({ type: 'client-response', rpcId: RpcId('req-1'), result: { ok: true, value: { behavior: 'allow' } } })
+    expect(receipt).toEqual({ accepted: true })
+    expect(seen).toEqual([{ type: 'client-response', rpcId: 'req-1', result: { ok: true, value: { behavior: 'allow' } } }])
+  })
+
+  it('returns bad-response for a malformed client-response without reaching the impl', async () => {
+    const respond = vi.fn()
+    const handler = toFetchHandler(scriptedApi({ respond }))
+    const response = await handler.fetch('http://dsh.internal/api/respond', { method: 'POST', body: JSON.stringify({ type: 'client-response' }) })
+    expect(await response.json()).toEqual({ accepted: false, reason: 'bad-response' })
+    expect(respond).not.toHaveBeenCalled()
+  })
+})
+
+describe('envelope tap', () => {
+  it('delivers one microtask batch of full forms per unary call', async () => {
+    const api = scriptedApi()
+    const tapped = client(api)
+    const batches: (readonly RpcMessage[])[] = []
+    tapped.subscribeEnvelopes(batch => batches.push(batch))
+    await tapped.sessions.list({})
+    await vi.waitFor(() => { expect(batches.length).toBeGreaterThan(0) })
+    const all = batches.flat()
+    expect(all.map(m => m.type)).toEqual(['client-request', 'server-response'])
+    expect(all[0]?.rpcId).toBe(all[1]?.rpcId)
+  })
+
+  it('isolates a throwing listener and keeps serving the call', async () => {
+    const api = scriptedApi()
+    const tapped = client(api)
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    try {
+      const good: string[] = []
+      tapped.subscribeEnvelopes(() => { throw new Error('listener bug') })
+      tapped.subscribeEnvelopes(batch => good.push(...batch.map(m => m.type)))
+      const response = await tapped.sessions.list({})
+      expect(response.result.ok).toBe(true)
+      await vi.waitFor(() => { expect(good).toContain('server-response') })
+    } finally {
+      errorSpy.mockRestore()
+    }
+  })
+
+  it('buffers nothing with zero subscribers and unsubscribes cleanly', async () => {
+    const api = scriptedApi()
+    const tapped = client(api)
+    await tapped.sessions.list({}) // no subscribers: must not accumulate
+    const batches: (readonly RpcMessage[])[] = []
+    const unsubscribe = tapped.subscribeEnvelopes(batch => batches.push(batch))
+    unsubscribe()
+    await tapped.sessions.list({})
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(batches).toEqual([])
+  })
+})
diff --git a/packages/host/apiproxy/tests/fetch-carrier.spec.ts b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
new file mode 100644
index 0000000000..d097daecef
--- /dev/null
+++ b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
@@ -0,0 +1,305 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { ApiProxy, HostFrame, MuxFrame } from '../src/api/index.ts'
+import type { ClientResponse, RpcMessage, RpcReceipt, RpcRequest } from '../src/api/rpc.ts'
+import { RpcId } from '../src/api/rpc.ts'
+import { toFetchHandler } from '../src/fetch/handler.ts'
+import { AbstractApiClient, InProcessApiClient } from '../src/fetch/client.ts'
+
+/** Minimal in-memory ApiProxy: echoes rpcIds, scripts one frame per stream. */
+function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFrame[]; crashOn: string }> = {}): ApiProxy {
+  const muxFrames = overrides.muxFrames ?? [{ type: 'session/subscribed', sessionId: 's1' as never, lastSeq: -1 }]
+  const hostFrames = overrides.hostFrames ?? [{ type: 'host/session-removed', sessionId: 's1' as never }]
+  async function * stream<F>(frames: F[], signal: AbortSignal): AsyncGenerator<RpcRequest<F>> {
+    for (const payload of frames) {
+      if (signal.aborted) return
+      yield { rpcId: RpcId(`frame-${String(frames.indexOf(payload))}`), payload }
+    }
+  }
+  return {
+    sessions: {
+      async list(request) {
+        if (overrides.crashOn === 'session.list') throw new Error('impl crashed')
+        return { rpcId: request.rpcId, result: { ok: true, value: { items: [] } } }
+      },
+      async create(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { sessionId: 's-new' as never } } }
+      },
+      async history(request) {
+        return {
+          rpcId: request.rpcId,
+          result: { ok: false, error: { code: 'session-not-found', message: 'nope', details: { sessionId: request.payload.sessionId } } },
+        }
+      },
+      async prompt(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } }
+      },
+      async cancel(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } }
+      },
+    },
+    host: {
+      async describe(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { version: 'v', cwd: '/w', attachedSessions: 0 } } }
+      },
+    },
+    events: {
+      mux: (_request, signal) => stream(muxFrames, signal),
+      host: (_request, signal) => stream(hostFrames, signal),
+    },
+    async respond(message: ClientResponse): Promise<RpcReceipt> {
+      return message.rpcId === 'known' ? { accepted: true } : { accepted: false, reason: 'not-pending' }
+    },
+  }
+}
+
+function client(api: ApiProxy = fakeApi()): InProcessApiClient {
+  return new InProcessApiClient(toFetchHandler(api))
+}
+
+async function collect<F>(stream: AsyncIterable<RpcRequest<F>>): Promise<RpcRequest<F>[]> {
+  const out: RpcRequest<F>[] = []
+  for await (const envelope of stream) out.push(envelope)
+  return out
+}
+
+describe('unary round trip (handler ⇄ client, no network)', () => {
+  it('carries a success result and echoes the minted rpcId', async () => {
+    const response = await client().sessions.list({})
+    expect(response.result).toEqual({ ok: true, value: { items: [] } })
+    expect(response.rpcId).toMatch(/[0-9a-f-]{36}/)
+  })
+
+  it('carries a business error as 200 + error result', async () => {
+    const response = await client().sessions.history({ sessionId: 'missing' as never })
+    expect(response.result.ok).toBe(false)
+    if (!response.result.ok) expect(response.result.error.code).toBe('session-not-found')
+  })
+
+  it('covers create/prompt/cancel/describe passthrough', async () => {
+    const c = client()
+    expect((await c.sessions.create({})).result.ok).toBe(true)
+    expect((await c.sessions.prompt({ sessionId: 's' as never, mode: 'queue', content: [{ type: 'text', text: 'x' }] })).result.ok).toBe(true)
+    expect((await c.sessions.cancel({ sessionId: 's' as never })).result.ok).toBe(true)
+    expect((await c.host.describe({})).result.ok).toBe(true)
+  })
+})
+
+describe('handler carrier-layer statuses', () => {
+  const handler = toFetchHandler(fakeApi())
+
+  it('404s unknown paths and non-POST non-stream methods', async () => {
+    expect((await handler.fetch(new Request('http://x/other', { method: 'POST', body: '{}' }))).status).toBe(404)
+    expect((await handler.fetch(new Request('http://x/api/session.list', { method: 'GET' }))).status).toBe(404)
+    expect((await handler.fetch(new Request('http://x/api/no.such', { method: 'POST', body: JSON.stringify({ type: 'client-request', rpcId: 'r', method: 'no.such', payload: {} }) }))).status).toBe(404)
+  })
+
+  it('400s a non-JSON body', async () => {
+    const response = await handler.fetch(new Request('http://x/api/session.list', { method: 'POST', body: 'not json' }))
+    expect(response.status).toBe(400)
+  })
+
+  it('rejects a malformed envelope with bad-request and the invalid-request sentinel rpcId', async () => {
+    const response = await handler.fetch(new Request('http://x/api/session.list', { method: 'POST', body: JSON.stringify({ nope: true }) }))
+    expect(response.status).toBe(200)
+    const body = await response.json() as { rpcId: string; result: { ok: boolean; error?: { code: string } } }
+    expect(body.rpcId).toBe('invalid-request')
+    expect(body.result.error?.code).toBe('bad-request')
+  })
+
+  it('rejects a method/path mismatch echoing the envelope rpcId', async () => {
+    const body = JSON.stringify({ type: 'client-request', rpcId: 'r-9', method: 'session.cancel', payload: {} })
+    const response = await handler.fetch(new Request('http://x/api/session.list', { method: 'POST', body }))
+    const parsed = await response.json() as { rpcId: string; result: { error?: { message: string } } }
+    expect(parsed.rpcId).toBe('r-9')
+    expect(parsed.result.error?.message).toContain('does not match path')
+  })
+
+  it('rejects an invalid payload with the zod issues attached', async () => {
+    const body = JSON.stringify({ type: 'client-request', rpcId: 'r-10', method: 'session.cancel', payload: {} })
+    const response = await handler.fetch(new Request('http://x/api/session.cancel', { method: 'POST', body }))
+    const parsed = await response.json() as { result: { error?: { code: string; details: { issues: unknown[] } } } }
+    expect(parsed.result.error?.code).toBe('bad-request')
+    expect(parsed.result.error?.details.issues.length).toBeGreaterThan(0)
+  })
+
+  it('500s when the impl itself throws', async () => {
+    const crashing = toFetchHandler(fakeApi({ crashOn: 'session.list' }))
+    const body = JSON.stringify({ type: 'client-request', rpcId: 'r-11', method: 'session.list', payload: {} })
+    const response = await crashing.fetch(new Request('http://x/api/session.list', { method: 'POST', body }))
+    expect(response.status).toBe(500)
+    expect(await response.text()).toContain('impl crashed')
+  })
+
+  it('routes /api/respond, rejecting malformed client-responses as a receipt', async () => {
+    const good = JSON.stringify({ type: 'client-response', rpcId: 'known', result: { ok: true, value: null } })
+    const goodReceipt: unknown = await (await handler.fetch(new Request('http://x/api/respond', { method: 'POST', body: good }))).json()
+    expect(goodReceipt).toEqual({ accepted: true })
+    const bad = JSON.stringify({ type: 'client-request', rpcId: 'r', method: 'x', payload: {} })
+    const badReceipt: unknown = await (await handler.fetch(new Request('http://x/api/respond', { method: 'POST', body: bad }))).json()
+    expect(badReceipt).toEqual({ accepted: false, reason: 'bad-response' })
+  })
+
+  it('accepts (url, init) form fetch invocation', async () => {
+    const body = JSON.stringify({ type: 'client-request', rpcId: 'r-12', method: 'session.list', payload: {} })
+    const response = await handler.fetch('http://x/api/session.list', { method: 'POST', body })
+    expect(response.status).toBe(200)
+  })
+})
+
+describe('SSE streams through the carrier', () => {
+  it('yields mux frames as ServerRequest narrow forms and completes', async () => {
+    const ac = new AbortController()
+    const frames = await collect(client().events.mux({}, ac.signal))
+    expect(frames).toHaveLength(1)
+    expect(frames[0]?.payload).toMatchObject({ type: 'session/subscribed' })
+    expect(frames[0]?.rpcId).toBe('frame-0')
+  })
+
+  it('yields host frames', async () => {
+    const ac = new AbortController()
+    const frames = await collect(client().events.host({}, ac.signal))
+    expect(frames[0]?.payload).toMatchObject({ type: 'host/session-removed' })
+  })
+
+  it('drops frames after the consumer aborts mid-stream', async () => {
+    const many = Array.from({ length: 50 }, (_, i): MuxFrame => ({ type: 'session/subscribed', sessionId: `s${String(i)}` as never, lastSeq: i }))
+    const ac = new AbortController()
+    const received: RpcRequest<MuxFrame>[] = []
+    for await (const envelope of client(fakeApi({ muxFrames: many })).events.mux({}, ac.signal)) {
+      received.push(envelope)
+      if (received.length === 2) break // generator return → reader.cancel path
+    }
+    expect(received).toHaveLength(2)
+  })
+
+  it('swallows a reader.cancel rejection on early exit', async () => {
+    const encoder = new TextEncoder()
+    const body = new ReadableStream<Uint8Array>({
+      start(controller) {
+        const frame = { type: 'server-request', rpcId: 'f0', method: 'session/subscribed', payload: { type: 'session/subscribed', sessionId: 's', lastSeq: -1 } }
+        controller.enqueue(encoder.encode(`data: ${JSON.stringify(frame)}\n\n`))
+        // stream intentionally left open: the consumer breaks first
+      },
+      cancel() {
+        throw new Error('cancel refused')
+      },
+    })
+    const c = new InProcessApiClient({ fetch: async () => new Response(body, { headers: { 'content-type': 'text/event-stream' } }) })
+    const received: RpcRequest<MuxFrame>[] = []
+    for await (const envelope of c.events.mux({}, new AbortController().signal)) {
+      received.push(envelope)
+      break
+    }
+    expect(received).toHaveLength(1)
+  })
+
+  it('surfaces a mid-stream impl failure as one stream/error frame, then the stream ends', async () => {
+    const api = fakeApi()
+    api.events.mux = (_request, _signal) => (async function * (): AsyncGenerator<RpcRequest<MuxFrame>> {
+      yield { rpcId: RpcId('f0'), payload: { type: 'session/subscribed', sessionId: 's' as never, lastSeq: -1 } }
+      throw new Error('stream source died')
+    })()
+    const frames = await collect(client(api).events.mux({}, new AbortController().signal))
+    expect(frames).toHaveLength(2)
+    expect(frames[1]?.payload).toMatchObject({ type: 'stream/error', error: { code: 'internal' } })
+  })
+})
+
+describe('client respond and transport failures', () => {
+  it('passes a client-response through and parses the receipt', async () => {
+    const receipt = await client().respond({ type: 'client-response', rpcId: RpcId('known'), result: { ok: true, value: null } })
+    expect(receipt).toEqual({ accepted: true })
+    const late = await client().respond({ type: 'client-response', rpcId: RpcId('late'), result: { ok: true, value: null } })
+    expect(late).toEqual({ accepted: false, reason: 'not-pending' })
+  })
+
+  it('throws on non-OK unary and respond and stream transport', async () => {
+    const broken = new InProcessApiClient({ fetch: async () => new Response('down', { status: 503 }) })
+    await expect(broken.sessions.list({})).rejects.toThrow('transport failure for /api/session.list: HTTP 503')
+    await expect(broken.respond({ type: 'client-response', rpcId: RpcId('r'), result: { ok: true, value: null } }))
+      .rejects.toThrow('transport failure for /api/respond')
+    await expect(collect(broken.events.mux({}, new AbortController().signal))).rejects.toThrow('transport failure for /api/events.mux')
+  })
+
+  it('throws on an rpcId echo mismatch', async () => {
+    const lying = new InProcessApiClient({
+      fetch: async () => Response.json({ type: 'server-response', rpcId: 'someone-else', result: { ok: true, value: { items: [] } } }),
+    })
+    await expect(lying.sessions.list({})).rejects.toThrow('rpcId mismatch')
+  })
+})
+
+describe('envelope observation', () => {
+  it('batches envelopes per microtask and isolates a throwing listener', async () => {
+    const c = client()
+    const batches: (readonly RpcMessage[])[] = []
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    const unsubscribeThrowing = c.subscribeEnvelopes(() => { throw new Error('observer bug') })
+    const unsubscribe = c.subscribeEnvelopes((batch) => { batches.push(batch) })
+    await c.sessions.list({})
+    await new Promise((resolve) => { setTimeout(resolve, 0) })
+    // request and response tap in separate microtask windows (the await between
+    // them yields), so both arrive but batch count is timing-defined
+    expect(batches.flatMap(batch => batch.map(message => message.type))).toEqual(['client-request', 'server-response'])
+    expect(errorSpy).toHaveBeenCalled()
+    unsubscribe()
+    unsubscribeThrowing()
+    errorSpy.mockRestore()
+  })
+
+  it('skips buffering entirely with no listeners and after unsubscribe', async () => {
+    const c = client()
+    const seen: RpcMessage[] = []
+    const unsubscribe = c.subscribeEnvelopes((batch) => { seen.push(...batch) })
+    unsubscribe()
+    await c.sessions.list({})
+    await new Promise((resolve) => { setTimeout(resolve, 0) })
+    expect(seen).toHaveLength(0)
+  })
+
+  it('coalesces multiple calls in one microtask window into one flush', async () => {
+    const c = client()
+    const batches: (readonly RpcMessage[])[] = []
+    c.subscribeEnvelopes((batch) => { batches.push(batch) })
+    await Promise.all([c.sessions.list({}), c.host.describe({})])
+    await new Promise((resolve) => { setTimeout(resolve, 0) })
+    const total = batches.reduce((n, batch) => n + batch.length, 0)
+    expect(total).toBe(4)
+  })
+})
+
+describe('resolveBase', () => {
+  it('prefers a real location.origin and falls back to the internal authority', async () => {
+    class Probe extends AbstractApiClient {
+      urls: string[] = []
+      protected async doFetch(input: URL): Promise<Response> {
+        this.urls.push(input.href)
+        return Response.json({ type: 'server-response', rpcId: this.lastMinted, result: { ok: true, value: { items: [] } } })
+      }
+
+      lastMinted = ''
+      protected override mintRpcId(): ReturnType<AbstractApiClient['mintRpcId']> {
+        const id = super.mintRpcId()
+        this.lastMinted = id
+        return id
+      }
+    }
+    const probe = new Probe()
+    await probe.sessions.list({})
+    expect(probe.urls[0]).toMatch(/^http:\/\/dsh\.internal\//)
+
+    const globalWithLocation = globalThis as { location?: { origin?: string } }
+    globalWithLocation.location = { origin: 'http://host.example' }
+    try {
+      const probe2 = new Probe()
+      await probe2.sessions.list({})
+      expect(probe2.urls[0]).toMatch(/^http:\/\/host\.example\//)
+      globalWithLocation.location = { origin: 'null' } // sandboxed iframe shape
+      const probe3 = new Probe()
+      await probe3.sessions.list({})
+      expect(probe3.urls[0]).toMatch(/^http:\/\/dsh\.internal\//)
+    } finally {
+      delete globalWithLocation.location
+    }
+  })
+})
diff --git a/packages/host/apiproxy/tests/rpc-schemas.spec.ts b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
new file mode 100644
index 0000000000..764c9673b9
--- /dev/null
+++ b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
@@ -0,0 +1,161 @@
+import { describe, expect, it } from 'vitest'
+import { RpcId } from '../src/api/rpc.ts'
+import {
+  clientRequestSchema, clientResponseSchema, rpcErrorSchema, rpcIdSchema, rpcMessageSchema,
+  rpcReceiptSchema, rpcResultSchema, serverRequestSchema, serverResponseSchema,
+} from '../src/api/rpc.schema.ts'
+import { z } from 'zod'
+import {
+  contentBlockSchema, sessionCancelRequestSchema, sessionCancelValueSchema, sessionCreateRequestSchema,
+  sessionCreateValueSchema, sessionEventSchema, sessionHistoryRequestSchema, sessionHistoryValueSchema,
+  sessionIdSchema, sessionListRequestSchema, sessionListValueSchema, sessionPromptRequestSchema,
+  sessionPromptValueSchema, sessionSummarySchema,
+} from '../src/api/sessions.schema.ts'
+import { hostDescribeRequestSchema, hostDescribeValueSchema } from '../src/api/host.schema.ts'
+import { hostFrameSchema, muxFrameSchema, askUserQuestionItemSchema } from '../src/api/events.schema.ts'
+import { approvalRequestIdSchema, approvalResponsePayloadSchema } from '../src/api/approvals.schema.ts'
+import { askUserQuestionAnswerSchema, questionResponsePayloadSchema } from '../src/api/questions.schema.ts'
+
+describe('RpcId', () => {
+  it('brands a raw string at zero runtime cost', () => {
+    expect(RpcId('abc')).toBe('abc')
+    expect(rpcIdSchema.parse('abc')).toBe('abc')
+    // No min-length: the id is an opaque echo token (see rpcIdSchema's contract).
+    expect(rpcIdSchema.parse('')).toBe('')
+    expect(() => rpcIdSchema.parse(42)).toThrow()
+  })
+})
+
+describe('rpcErrorSchema', () => {
+  it('accepts every code branch with its required details', () => {
+    expect(rpcErrorSchema.parse({ code: 'bad-request', message: 'm', details: { issues: [] } }).code).toBe('bad-request')
+    expect(rpcErrorSchema.parse({ code: 'session-not-found', message: 'm', details: { sessionId: 's' } }).code).toBe('session-not-found')
+    expect(rpcErrorSchema.parse({ code: 'agent-busy', message: 'm', details: { reason: 'r' } }).code).toBe('agent-busy')
+    expect(rpcErrorSchema.parse({ code: 'internal', message: 'm', details: {} }).code).toBe('internal')
+  })
+
+  it('rejects a known code with missing details', () => {
+    expect(() => rpcErrorSchema.parse({ code: 'agent-busy', message: 'm', details: {} })).toThrow()
+    expect(() => rpcErrorSchema.parse({ code: 'nope', message: 'm', details: {} })).toThrow()
+  })
+})
+
+describe('rpcResultSchema', () => {
+  it('accepts both result branches and rejects hybrids', () => {
+    const schema = rpcResultSchema(z.object({ n: z.number() }))
+    expect(schema.parse({ ok: true, value: { n: 1 } })).toEqual({ ok: true, value: { n: 1 } })
+    const err = schema.parse({ ok: false, error: { code: 'internal', message: 'x', details: {} } })
+    expect(err).toMatchObject({ ok: false })
+    expect(() => schema.parse({ ok: true, error: {} })).toThrow()
+  })
+})
+
+describe('wire full-form schemas', () => {
+  it('parses the four quadrants and the union discriminates on type', () => {
+    const cq = { type: 'client-request', rpcId: 'r1', method: 'session.list', payload: {} }
+    const sr = { type: 'server-response', rpcId: 'r1', result: { ok: true, value: 1 } }
+    const rq = { type: 'server-request', rpcId: 'r2', method: 'session/event', payload: { a: 1 } }
+    const cr = { type: 'client-response', rpcId: 'r2', result: { ok: true, value: null } }
+    expect(clientRequestSchema.parse(cq).method).toBe('session.list')
+    expect(serverResponseSchema.parse(sr).rpcId).toBe('r1')
+    expect(serverRequestSchema.parse(rq).method).toBe('session/event')
+    expect(clientResponseSchema.parse(cr).rpcId).toBe('r2')
+    for (const message of [cq, sr, rq, cr]) expect(rpcMessageSchema.parse(message)).toBeTruthy()
+    expect(() => rpcMessageSchema.parse({ type: 'other', rpcId: 'x' })).toThrow()
+  })
+
+  it('rejects a quadrant missing its members', () => {
+    expect(() => clientRequestSchema.parse({ type: 'client-request', rpcId: 'r1' })).toThrow()
+    expect(() => serverResponseSchema.parse({ type: 'server-response', rpcId: 'r1', result: { ok: true } })).toThrow()
+  })
+})
+
+describe('rpcReceiptSchema', () => {
+  it('accepts both receipt branches with the closed reason set', () => {
+    expect(rpcReceiptSchema.parse({ accepted: true })).toEqual({ accepted: true })
+    expect(rpcReceiptSchema.parse({ accepted: false, reason: 'not-pending' })).toEqual({ accepted: false, reason: 'not-pending' })
+    expect(rpcReceiptSchema.parse({ accepted: false, reason: 'bad-response' })).toEqual({ accepted: false, reason: 'bad-response' })
+    expect(() => rpcReceiptSchema.parse({ accepted: false, reason: 'other' })).toThrow()
+  })
+})
+
+describe('sessions domain schemas', () => {
+  it('validates ids, summaries, and the event passthrough envelope', () => {
+    expect(sessionIdSchema.parse('s1')).toBe('s1')
+    expect(() => sessionIdSchema.parse('')).toThrow()
+    expect(sessionSummarySchema.parse({ sessionId: 's1', updatedAt: 1, running: false })).toMatchObject({ sessionId: 's1' })
+    expect(sessionSummarySchema.parse({ sessionId: 's1', updatedAt: 1, running: true, parentSessionId: 'p', cwd: '/x' }).cwd).toBe('/x')
+    const event = sessionEventSchema.parse({ type: 'user/message', seq: 0, time: 1, data: { any: true } })
+    expect(event).toMatchObject({ type: 'user/message' })
+    expect(() => sessionEventSchema.parse({ type: 'user/message', seq: -1, time: 1, data: {} })).toThrow()
+  })
+
+  it('validates the per-method request/value pairs', () => {
+    expect(sessionListRequestSchema.parse({})).toEqual({})
+    expect(sessionListRequestSchema.parse({ cursor: 'c' }).cursor).toBe('c')
+    expect(sessionListValueSchema.parse({ items: [] }).items).toEqual([])
+    expect(sessionCreateRequestSchema.parse({ cwd: '/w' }).cwd).toBe('/w')
+    expect(sessionCreateValueSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
+    expect(sessionHistoryRequestSchema.parse({ sessionId: 's1', beforeSeq: 3, maxMessages: 5 }).beforeSeq).toBe(3)
+    expect(() => sessionHistoryRequestSchema.parse({ sessionId: 's1', maxMessages: 0 })).toThrow()
+    expect(sessionHistoryValueSchema.parse({ events: [], hasMore: false }).hasMore).toBe(false)
+    const prompt = sessionPromptRequestSchema.parse({ sessionId: 's1', mode: 'queue', content: [{ type: 'text', text: 'hi' }] })
+    expect(prompt.mode).toBe('queue')
+    expect(() => sessionPromptRequestSchema.parse({ sessionId: 's1', mode: 'inject', content: [] })).toThrow()
+    expect(sessionPromptValueSchema.parse({ accepted: true }).accepted).toBe(true)
+    expect(sessionCancelRequestSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
+    expect(sessionCancelValueSchema.parse({ accepted: true }).accepted).toBe(true)
+    expect(contentBlockSchema.parse({ type: 'text', text: 'x', extra: 1 })).toMatchObject({ extra: 1 })
+  })
+})
+
+describe('host domain schemas', () => {
+  it('validates describe request/value', () => {
+    expect(hostDescribeRequestSchema.parse({})).toEqual({})
+    const value = hostDescribeValueSchema.parse({ version: '1', cwd: '/x', provider: 'p', model: 'm', attachedSessions: 2 })
+    expect(value.attachedSessions).toBe(2)
+    expect(hostDescribeValueSchema.parse({ version: '1', cwd: '/x', attachedSessions: 0 }).provider).toBeUndefined()
+  })
+})
+
+describe('events frame schemas', () => {
+  it('accepts every mux frame branch', () => {
+    const frames = [
+      { type: 'session/event', sessionId: 's', event: { type: 't', seq: 0, time: 1, data: null } },
+      { type: 'session/subscribed', sessionId: 's', lastSeq: -1 },
+      { type: 'approval/requested', sessionId: 's', approvalId: 'a', toolName: 'bash', callId: 'c', reason: 'r' },
+      { type: 'approval/resolved', sessionId: 's', approvalId: 'a', outcome: 'allowed-once' },
+      { type: 'question/requested', sessionId: 's', questions: [{ id: 'q', question: 'Q?', options: [{ label: 'L' }], multiSelect: true }] },
+      { type: 'question/resolved', sessionId: 's', questionRpcId: 'r', outcome: 'answered' },
+      { type: 'stream/error', error: { code: 'internal', message: 'm', details: {} } },
+    ]
+    for (const frame of frames) expect(muxFrameSchema.parse(frame)).toMatchObject({ type: frame.type })
+    expect(() => muxFrameSchema.parse({ type: 'unknown/frame' })).toThrow()
+    expect(askUserQuestionItemSchema.parse({ id: 'q', question: 'Q?' }).id).toBe('q')
+  })
+
+  it('accepts every host frame branch', () => {
+    const frames = [
+      { type: 'host/session-added', sessionId: 's', parentSessionId: 'p' },
+      { type: 'host/session-added', sessionId: 's' },
+      { type: 'host/session-removed', sessionId: 's' },
+      { type: 'host/session-status', sessionId: 's', running: true },
+      { type: 'host/agent-error', sessionId: 's', message: 'boom' },
+      { type: 'stream/error', error: { code: 'internal', message: 'm', details: {} } },
+    ]
+    for (const frame of frames) expect(hostFrameSchema.parse(frame)).toMatchObject({ type: frame.type })
+  })
+})
+
+describe('respond payload schemas', () => {
+  it('validates approval and question answer payloads', () => {
+    expect(approvalRequestIdSchema.parse('a1')).toBe('a1')
+    const approval = approvalResponsePayloadSchema.parse({ sessionId: 's', approvalId: 'a', outcome: 'rejected' })
+    expect(approval.outcome).toBe('rejected')
+    expect(() => approvalResponsePayloadSchema.parse({ sessionId: 's', approvalId: 'a', outcome: 'cancelled' })).toThrow()
+    const answer = askUserQuestionAnswerSchema.parse({ answers: [{ id: 'q', selected: ['x'], custom: 'c' }] })
+    expect(answer.answers[0]?.selected).toEqual(['x'])
+    const payload = questionResponsePayloadSchema.parse({ sessionId: 's', answer: { answers: [] } })
+    expect(payload.sessionId).toBe('s')
+  })
+})
diff --git a/packages/host/apiproxy/tsconfig.json b/packages/host/apiproxy/tsconfig.json
new file mode 100644
index 0000000000..718c5a9042
--- /dev/null
+++ b/packages/host/apiproxy/tsconfig.json
@@ -0,0 +1,33 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../util/brand"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../core/tools"
+    },
+    {
+      "path": "../../ui/user-approval"
+    },
+    {
+      "path": "../../ui/user-interaction"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/host/runtime/README.md b/packages/host/runtime/README.md
new file mode 100644
index 0000000000..39f9888180
--- /dev/null
+++ b/packages/host/runtime/README.md
@@ -0,0 +1,31 @@
+# @deepseek-ai/dsh-host-runtime
+
+Host runtime assembly for `dsc`: `bootHost` composes the core plugin spine (LLM service + DeepSeek adapter, sessions with JSONL persistence, system prompt, tools, agents, agent loop, local bash), `createApiProxy` implements the [`dsh-host-apiproxy`](../apiproxy/README.md) contract over that composition, and `startHost` is the one-step shell seam returning `{ api, handler, defaults, ctx, dispose }`.
+
+Which plugins mount and with what defaults is decided only here — shells must not `ctx.plugin` to alter the assembly. `RunningHost.ctx` is a formal seam with exactly two sanctioned uses: mounting protocol front-door plugins (e.g. a future `dsh acp`) and headless session-event subscription; consuming clients must not bypass `api` through it.
+
+## Configuration
+
+| Key | Default | Contract |
+|---|---:|---|
+| `persistenceRoot` | (required) | Root directory for JSONL session persistence. |
+| `provider` | `'deepseek'` | Default provider route injected as agentOptions on create/resume and reported by `host.describe`. |
+| `model` | `'deepseek-v4-flash'` | Default model id, same single source as `provider`. |
+
+## ApiProxy implementation notes
+
+Unary methods take the narrow `RpcRequest<P>` and echo `request.rpcId`; a prompt's rpcId rides `MessageSource` into the `user/message` event so clients can promote optimistic echoes. `history`/`prompt` on a cold session implicitly resume it, deduplicating concurrent calls through an in-flight table; `history` paginates backwards on message boundaries (never mid-message). The mux stream replays a `session/subscribed` baseline per attached session on open; the host stream carries session lifecycle, running flips, and `agent/error` as the only outlet for live failures with no turn position.
+
+## Model Experience
+
+Indirectly, through the model-facing plugins bootHost mounts and the provider/model defaults injected into created and resumed agents.
+
+#### KV Cache effect
+
+No direct invalidation; the mounted model-facing plugins own their request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **`respond` is a stub** — it always returns `not-pending`; the approval/question pending registry (stable-rpcId mint on accept, baseline replay on stream reopen, wire answerer) is the next host-side step.
+- **`session.list` covers live sessions only** — cold sessions in the persistence directory are not yet merged into the listing; `host.describe.version` is a placeholder rather than the `apps/cli` package version.
+- **The assembly is fixed** — per-deployment plugin selection (user profile, log sinks, alternative persistence) has a documented home here but no configuration surface yet.
diff --git a/packages/host/runtime/package.json b/packages/host/runtime/package.json
new file mode 100644
index 0000000000..ea32040012
--- /dev/null
+++ b/packages/host/runtime/package.json
@@ -0,0 +1,82 @@
+{
+  "name": "@deepseek-ai/dsh-host-runtime",
+  "description": "Host runtime assembly for dsh: bootHost composes the core spine, createApiProxy implements the contract, startHost is the one-step shell seam",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@cordisjs/plugin-loader": "workspace:^",
+    "@cordisjs/plugin-timer": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-bash-local": "workspace:^",
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-client-i18n": "workspace:^",
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-sidebar": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-theme": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-trajectory": "workspace:^",
+    "@deepseek-ai/dsh-compact-basic": "workspace:^",
+    "@deepseek-ai/dsh-fs-local": "workspace:^",
+    "@deepseek-ai/dsh-fs-policy": "workspace:^",
+    "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-llm-deepseek": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
+    "@deepseek-ai/dsh-skill": "workspace:^",
+    "@deepseek-ai/dsh-skill-local": "workspace:^",
+    "@deepseek-ai/dsh-spill-local": "workspace:^",
+    "@deepseek-ai/dsh-spill-policy": "workspace:^",
+    "@deepseek-ai/dsh-subagent": "workspace:^",
+    "@deepseek-ai/dsh-subagent-fork": "workspace:^",
+    "@deepseek-ai/dsh-subagent-spawn": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tasks": "workspace:^",
+    "@deepseek-ai/dsh-timeout-policy": "workspace:^",
+    "@deepseek-ai/dsh-token-meter": "workspace:^",
+    "@deepseek-ai/dsh-tool-bash": "workspace:^",
+    "@deepseek-ai/dsh-tool-fs": "workspace:^",
+    "@deepseek-ai/dsh-tool-fs-search": "workspace:^",
+    "@deepseek-ai/dsh-tool-skill": "workspace:^",
+    "@deepseek-ai/dsh-tool-subagent": "workspace:^",
+    "@deepseek-ai/dsh-tool-tasks": "workspace:^",
+    "@deepseek-ai/dsh-tool-todo": "workspace:^",
+    "@deepseek-ai/dsh-tool-workflow": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-workflow-workerthread": "workspace:^"
+  },
+  "peerDependencies": {
+    "cordis": "^4.0.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "^0.0.1"
+  },
+  "devDependencies": {
+    "cordis": "^4.0.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "workspace:^"
+  }
+}
diff --git a/packages/host/runtime/src/api-proxy.ts b/packages/host/runtime/src/api-proxy.ts
new file mode 100644
index 0000000000..0621fbecb9
--- /dev/null
+++ b/packages/host/runtime/src/api-proxy.ts
@@ -0,0 +1,429 @@
+/**
+ * Host-side ApiProxy implementation (minimal-first —
+ * describe/list/create/history/prompt/cancel and both streams are real,
+ * respond is a stub). Signature discipline: unary takes the narrow
+ * RpcRequest<P> and echoes request.rpcId on the RpcResponse<T>.
+ */
+
+import { randomUUID } from 'node:crypto'
+import { stat } from 'node:fs/promises'
+import type { Context } from 'cordis'
+import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
+import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
+import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
+import type { ApiProxy, HistoryEntry, HostFrame, MuxFrame, SessionSummary, ToolEventView } from '@deepseek-ai/dsh-host-apiproxy/api'
+import type { ClientResponse, RpcError, RpcReceipt, RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+
+/** Page size when history is called without maxMessages. */
+const DEFAULT_MAX_MESSAGES = 50
+
+/** Surface message event types (the pagination counting unit). */
+const MESSAGE_TYPES = new Set(['user/message', 'assistant/message', 'steering/message'])
+
+/**
+ * Message-boundary pagination: count maxMessages surface messages backwards from
+ * the window tail; the cut is the starting seq of the oldest message group
+ * (chunks group via sourceEventSeqs — never cut mid-message). The tail page
+ * naturally includes the in-progress partial.
+ */
+function paginate(
+  events: readonly SessionEvent[],
+  beforeSeq: number | undefined,
+  maxMessages: number,
+): { events: SessionEvent[]; hasMore: boolean } {
+  const window = beforeSeq === undefined ? [...events] : events.filter(event => event.seq < beforeSeq)
+  let count = 0
+  let cut = 0
+  for (let i = window.length - 1; i >= 0; i--) {
+    const event = window[i] as SessionEvent
+    if (!MESSAGE_TYPES.has(event.type)) continue
+    count++
+    const sources = (event as { sourceEventSeqs?: number[] }).sourceEventSeqs
+    const groupStart = sources !== undefined && sources.length > 0 ? Math.min(event.seq, ...sources) : event.seq
+    if (count >= maxMessages) {
+      cut = groupStart
+      break
+    }
+  }
+  const page = window.filter(event => event.seq >= cut)
+  return { events: page, hasMore: cut > 0 }
+}
+
+/** Wrap an ok result echoing the request's rpcId. */
+function ok<T>(request: RpcRequest<unknown>, value: T): RpcResponse<T> {
+  return { rpcId: request.rpcId, result: { ok: true, value } }
+}
+
+/** Wrap an error result echoing the request's rpcId. */
+function err<T>(request: RpcRequest<unknown>, error: RpcError): RpcResponse<T> {
+  return { rpcId: request.rpcId, result: { ok: false, error } }
+}
+
+/** Simple async queue: core callbacks push, the AsyncIterable pulls; abort/return cleans up. */
+class FrameQueue<F> {
+  private buffer: F[] = []
+  private waiter: (() => void) | undefined
+  private done = false
+
+  push(item: F): void {
+    if (this.done) return
+    this.buffer.push(item)
+    this.waiter?.()
+  }
+
+  end(): void {
+    this.done = true
+    this.waiter?.()
+  }
+
+  async *iterate(signal: AbortSignal, cleanup: () => void): AsyncGenerator<F> {
+    const onAbort = (): void => { this.end() }
+    signal.addEventListener('abort', onAbort, { once: true })
+    try {
+      while (true) {
+        while (this.buffer.length > 0) yield this.buffer.shift() as F
+        if (this.done || signal.aborted) return
+        await new Promise<void>((resolve) => { this.waiter = resolve })
+        this.waiter = undefined
+      }
+    } finally {
+      signal.removeEventListener('abort', onAbort)
+      cleanup()
+    }
+  }
+}
+
+/**
+ * Server-side frame mint: pure pushes get a fresh rpcId per frame (stable ids
+ * for answerable frames belong to the approval/question registry, absent in
+ * this minimal version).
+ */
+function frame<F>(payload: F): RpcRequest<F> {
+  return { rpcId: RpcId(randomUUID()), payload }
+}
+
+/** SessionSummary projection for attached (in-memory) sessions. */
+function summarize(session: Session, running: boolean): SessionSummary {
+  return {
+    sessionId: session.id,
+    updatedAt: session.events.at(-1)?.time ?? session.header.createdAt,
+    running,
+    ...session.header.parentSession === undefined ? {} : { parentSessionId: session.header.parentSession },
+    ...session.header.cwd === undefined ? {} : { cwd: session.header.cwd },
+  }
+}
+
+/**
+ * SessionSummary projection for cold (persisted, unattached) sessions.
+ * updatedAt is the log file's mtime; backends without a per-session file
+ * (locate() undefined) fall back to the header's createdAt.
+ */
+async function summarizeCold(persistence: SessionPersistence, meta: SessionHeader): Promise<SessionSummary> {
+  let updatedAt = meta.createdAt
+  const location = persistence.locate(meta)
+  if (location !== undefined) {
+    try {
+      updatedAt = (await stat(location.path)).mtimeMs
+    } catch {
+      // The log vanished between list() and stat() (concurrent cleanup); createdAt stands in.
+    }
+  }
+  return {
+    sessionId: meta.id,
+    updatedAt,
+    running: false,
+    ...meta.parentSession === undefined ? {} : { parentSessionId: meta.parentSession },
+    /* v8 ignore next -- the empty arm needs a cwd-less meta, but list()
+    filters those out (legacy logs are not served); the conditional mirrors
+    summarize() shape. */
+    ...meta.cwd === undefined ? {} : { cwd: meta.cwd },
+  }
+}
+
+/** Host-level default agent routing (same shape as bootHost's HostDefaults; avoids an impl→index reverse import). */
+export interface ApiProxyDefaults {
+  provider: string
+  model: string
+  /** Default project directory for new sessions whose create request carries no cwd. */
+  cwd: string
+}
+
+/** The tool/call payload fields the presenter path reads. */
+interface ToolCallData { callId: string; name: string; arguments: string }
+/** The tool/result payload fields the presenter path reads. */
+interface ToolResultData { callId: string; content: ContentBlock[]; isError: boolean; meta?: unknown }
+
+/**
+ * Compute the render intent for a tool/call or tool/result event through the
+ * presenters registered at this moment; every other event type gets none. A
+ * result's presenter needs its call's parsed args — `argsFor` supplies them
+ * (live: the per-session call table; history: an in-page backscan), returning
+ * undefined when the pairing is unavailable (e.g. the call fell off the page),
+ * which soft-falls to no view. Presenter or JSON.parse throws also soft-fall:
+ * the client's documented default (generic JSON card) covers every miss.
+ */
+function viewFor(ctx: Context, event: SessionEvent, argsFor: (callId: string) => unknown): ToolEventView | undefined {
+  try {
+    if (event.type === 'tool/call') {
+      const { name, arguments: raw } = event.data as ToolCallData
+      const view = ctx.tools.get(name)?.presentCall?.(JSON.parse(raw))
+      return view === undefined ? undefined : { for: 'call', view }
+    }
+    if (event.type === 'tool/result') {
+      const { callId, content, isError, meta } = event.data as ToolResultData
+      const call = argsFor(callId) as { name: string; args: unknown } | undefined
+      if (call === undefined) return undefined
+      const view = ctx.tools.get(call.name)?.presentResult?.(call.args, { content, isError, ...meta === undefined ? {} : { meta } })
+      return view === undefined ? undefined : { for: 'result', view }
+    }
+  } catch (error: unknown) {
+    // A throwing presenter (or unparseable arguments) must not break delivery;
+    // the event still ships, just without a view.
+    console.error(`api-proxy: presenter failed for ${event.type}, falling back to generic: ${String(error)}`)
+  }
+  return undefined
+}
+
+/**
+ * Resolve a tool/result's call pairing by scanning a window of events backwards
+ * for the matching tool/call. Used by the history path (the page is the
+ * window — a cross-page pairing soft-falls to no view) and by live-path table
+ * misses after a reconnect-eviction.
+ */
+function backscanArgs(events: readonly SessionEvent[], callId: string): { name: string; args: unknown } | undefined {
+  for (let i = events.length - 1; i >= 0; i--) {
+    const event = events[i] as SessionEvent
+    if (event.type !== 'tool/call') continue
+    const data = event.data as ToolCallData
+    if (data.callId !== callId) continue
+    try {
+      return { name: data.name, args: JSON.parse(data.arguments) }
+    } catch {
+      // Unparseable stored arguments: same soft-fall as a live parse failure.
+      return undefined
+    }
+  }
+  return undefined
+}
+
+/**
+ * Thrown by the cold-resume path when the id names no servable session
+ * (absent from the store, or a pre-project legacy log without a cwd).
+ */
+class SessionNotFound extends Error {}
+
+/**
+ * Implement ApiProxy over the ctx composed by bootHost.
+ * @param ctx - the root context returned by bootHost (sessions/agents services mounted).
+ * @param defaults - host-level default provider/model: injected as
+ * agentOptions on create/resume, reported by describe from the same source.
+ * @returns the ApiProxy implementation (minimal-first; stubs noted per method).
+ */
+export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiProxy {
+  const agentOptions = { provider: defaults.provider, model: defaults.model }
+  /** Implicit resume of cold sessions, deduplicating concurrent calls (follows the jsonrpc sessionCreations precedent). */
+  const resumes = new Map<SessionId, Promise<Agent>>()
+
+  /**
+   * Gate the cold path on the store: an id absent from it, or naming a legacy
+   * log without a cwd (pre-release stance: not served, no compatibility), is
+   * not-found before any resume is attempted. With the gate passed, a later
+   * resume failure is genuinely internal. No persistence configured skips the
+   * gate — resume itself then fails loud with its own diagnostic.
+   */
+  async function assertServable(sessionId: SessionId): Promise<void> {
+    const persistence = ctx.get('sessionPersistence')
+    if (persistence === undefined) return
+    const meta = (await persistence.list()).find(m => m.id === sessionId)
+    if (meta === undefined || meta.cwd === undefined) throw new SessionNotFound(`session "${sessionId}" not found`)
+  }
+
+  async function agentFor(sessionId: SessionId): Promise<{ agent: Agent } | { error: RpcError }> {
+    const live = ctx.agents.get(sessionId)
+    if (live !== undefined) return { agent: live }
+    let resume = resumes.get(sessionId)
+    if (resume === undefined) {
+      resume = (async () => {
+        try {
+          await assertServable(sessionId)
+          const handle = await ctx.agents.resume({ resumeSessionId: sessionId, agentOptions })
+          return handle.agent
+        } finally {
+          resumes.delete(sessionId)
+        }
+      })()
+      resumes.set(sessionId, resume)
+    }
+    try {
+      return { agent: await resume }
+    } catch (error: unknown) {
+      if (error instanceof SessionNotFound) {
+        return { error: { code: 'session-not-found', message: error.message, details: { sessionId } } }
+      }
+      // The internal details slot is contractually {}; the reason rides the message.
+      return { error: { code: 'internal', message: `resume failed for session "${sessionId}": ${String(error)}`, details: {} } }
+    }
+  }
+
+  return {
+    sessions: {
+      // Attached sessions summarize from memory; persisted-but-unattached (cold)
+      // sessions merge in from the persistence store so history survives restarts.
+      // Legacy logs without a cwd (pre-project stance) are not served — every
+      // session now records its project at create time.
+      async list(request) {
+        const items = ctx.sessions.list().map((session) => {
+          const agent = ctx.agents.get(session.id)
+          return summarize(session, agent?.status === 'running')
+        })
+        const attached = new Set(items.map(item => item.sessionId))
+        const persistence = ctx.get('sessionPersistence')
+        if (persistence !== undefined) {
+          const cold = (await persistence.list()).filter(meta => !attached.has(meta.id) && meta.cwd !== undefined)
+          items.push(...await Promise.all(cold.map(meta => summarizeCold(persistence, meta))))
+        }
+        items.sort((a, b) => b.updatedAt - a.updatedAt)
+        return ok(request, { items })
+      },
+
+      async create(request) {
+        const sessionId = `session-${randomUUID()}` as SessionId
+        // A session's cwd is its project path. When the creator does not choose
+        // one, the default project is the host-level default (the host process
+        // working directory unless boot overrides it).
+        const cwd = request.payload.cwd ?? defaults.cwd
+        const handle = await ctx.agents.create({ sessionId, agentOptions, meta: { cwd } })
+        return ok(request, { sessionId: handle.agent.id })
+      },
+
+      async history(request) {
+        const { sessionId, beforeSeq, maxMessages } = request.payload
+        const found = await agentFor(sessionId)
+        if ('error' in found) return err(request, found.error)
+        const page = paginate(found.agent.session.events, beforeSeq, maxMessages ?? DEFAULT_MAX_MESSAGES)
+        // Views are computed against the registry at pagination time; result
+        // pairing scans within the page only (message-boundary pagination keeps
+        // a call and its result on one page — a cross-page miss soft-falls).
+        const entries: HistoryEntry[] = page.events.map((event) => {
+          const view = viewFor(ctx, event, callId => backscanArgs(page.events, callId))
+          return { event, ...view === undefined ? {} : { view } }
+        })
+        return ok(request, { events: entries, hasMore: page.hasMore })
+      },
+
+      async prompt(request) {
+        const { sessionId, mode, content } = request.payload
+        const found = await agentFor(sessionId)
+        if ('error' in found) return err(request, found.error)
+        const agent = found.agent
+        // The rpcId rides MessageSource into user/message (merge declaration in api/sessions.ts; provisional correlation).
+        const source: MessageSource = { kind: 'user', rpcId: request.rpcId }
+        try {
+          if (mode === 'steer') agent.steer(content, { source })
+          else agent.send(content, { source })
+        } catch (error: unknown) {
+          // A synchronous throw from send/steer means disposed or invalid input; surface as agent-busy with the reason attached.
+          return err(request, { code: 'agent-busy', message: 'prompt rejected', details: { reason: String(error) } })
+        }
+        return ok(request, { accepted: true as const })
+      },
+
+      cancel(request) {
+        const { sessionId } = request.payload
+        const agent = ctx.agents.get(sessionId)
+        if (agent === undefined) {
+          return Promise.resolve(err(request, {
+            code: 'session-not-found',
+            message: `session "${sessionId}" not found (not attached)`,
+            details: { sessionId },
+          }))
+        }
+        agent.cancel()
+        return Promise.resolve(ok(request, { accepted: true as const }))
+      },
+    },
+
+    host: {
+      describe(request) {
+        // TODO(step2): version should read apps/cli's package.json; placeholder for now.
+        return Promise.resolve(ok(request, {
+          version: '0.0.1',
+          cwd: process.cwd(),
+          provider: defaults.provider,
+          model: defaults.model,
+          attachedSessions: ctx.agents.list().length,
+        }))
+      },
+    },
+
+    events: {
+      mux(_request, signal) {
+        const queue = new FrameQueue<RpcRequest<MuxFrame>>()
+        for (const session of ctx.sessions.list()) {
+          queue.push(frame({ type: 'session/subscribed', sessionId: session.id, lastSeq: session.seq - 1 }))
+        }
+        // Per-session open-call table for result-view pairing. Bounded by the
+        // per-turn call count: entries clear on turn/end; a table miss (stream
+        // opened mid-turn) backscans the session's in-memory events instead.
+        const openCalls = new Map<SessionId, Map<string, { name: string; args: unknown }>>()
+        const disposers = [
+          ctx.on('session/event', (session: Session, event: SessionEvent) => {
+            if (event.type === 'tool/call') {
+              const data = event.data as ToolCallData
+              try {
+                let table = openCalls.get(session.id)
+                if (table === undefined) openCalls.set(session.id, table = new Map<string, { name: string; args: unknown }>())
+                table.set(data.callId, { name: data.name, args: JSON.parse(data.arguments) })
+              } catch {
+                // Unparseable model arguments: leave the table unset; the result view soft-falls.
+              }
+            } else if (event.type === 'turn/end') {
+              openCalls.delete(session.id)
+            }
+            const view = viewFor(ctx, event, callId =>
+              openCalls.get(session.id)?.get(callId) ?? backscanArgs(session.events, callId))
+            queue.push(frame({ type: 'session/event', sessionId: session.id, event, ...view === undefined ? {} : { view } }))
+          }),
+          ctx.on('session/created', (session: Session) => {
+            queue.push(frame({ type: 'session/subscribed', sessionId: session.id, lastSeq: session.seq - 1 }))
+          }),
+          ctx.on('session/disposed', (session: Session) => {
+            openCalls.delete(session.id)
+          }),
+        ]
+        return queue.iterate(signal, () => { for (const dispose of disposers) dispose() })
+      },
+
+      host(_request, signal) {
+        const queue = new FrameQueue<RpcRequest<HostFrame>>()
+        const disposers = [
+          ctx.on('session/created', (session: Session) => {
+            queue.push(frame({
+              type: 'host/session-added',
+              sessionId: session.id,
+              ...session.header.parentSession === undefined ? {} : { parentSessionId: session.header.parentSession },
+            }))
+          }),
+          ctx.on('session/disposed', (session: Session) => {
+            queue.push(frame({ type: 'host/session-removed', sessionId: session.id }))
+          }),
+          ctx.on('agent/status', (agent: Agent, status: AgentStatus) => {
+            if (status === 'disposed') return
+            queue.push(frame({ type: 'host/session-status', sessionId: agent.id, running: status === 'running' }))
+          }),
+          ctx.on('agent/error', (agent: Agent, _turn: number, _step: number, error: Error) => {
+            queue.push(frame({ type: 'host/agent-error', sessionId: agent.id, message: String(error) }))
+          }),
+        ]
+        return queue.iterate(signal, () => { for (const dispose of disposers) dispose() })
+      },
+    },
+
+    // TODO(step2): approval/question pending registry (wire answerer + proxy provider).
+    respond(_message: ClientResponse): Promise<RpcReceipt> {
+      return Promise.resolve({ accepted: false, reason: 'not-pending' })
+    },
+  }
+}
diff --git a/packages/host/runtime/src/boot.ts b/packages/host/runtime/src/boot.ts
new file mode 100644
index 0000000000..ca40b9f8b3
--- /dev/null
+++ b/packages/host/runtime/src/boot.ts
@@ -0,0 +1,133 @@
+/**
+ * Core spine composition for the dsh host: mounts the harness core plugins
+ * one by one (each awaited so a load failure surfaces deterministically at
+ * boot, unlike bundle plugins whose children mount unawaited).
+ */
+
+import { Context } from 'cordis'
+import Timer from '@cordisjs/plugin-timer'
+import LlmService from '@deepseek-ai/dsh-llm'
+import SessionStore from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import TaskService from '@deepseek-ai/dsh-tasks'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
+import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
+import LocalBashExecutor from '@deepseek-ai/dsh-bash-local'
+import * as toolBash from '@deepseek-ai/dsh-tool-bash'
+import * as toolTodo from '@deepseek-ai/dsh-tool-todo'
+import * as toolTasks from '@deepseek-ai/dsh-tool-tasks'
+import FsLocal from '@deepseek-ai/dsh-fs-local'
+import * as fsPolicy from '@deepseek-ai/dsh-fs-policy'
+import * as toolFs from '@deepseek-ai/dsh-tool-fs'
+import * as toolFsSearch from '@deepseek-ai/dsh-tool-fs-search'
+import SkillService from '@deepseek-ai/dsh-skill'
+import * as SkillLocal from '@deepseek-ai/dsh-skill-local'
+import * as toolSkill from '@deepseek-ai/dsh-tool-skill'
+import TokenMeter from '@deepseek-ai/dsh-token-meter'
+import CompactBasic from '@deepseek-ai/dsh-compact-basic'
+import SubagentService from '@deepseek-ai/dsh-subagent'
+import * as SubagentSpawn from '@deepseek-ai/dsh-subagent-spawn'
+import * as SubagentFork from '@deepseek-ai/dsh-subagent-fork'
+import * as toolSubagent from '@deepseek-ai/dsh-tool-subagent'
+import WorkflowWorkerthread from '@deepseek-ai/dsh-workflow-workerthread'
+import * as toolWorkflow from '@deepseek-ai/dsh-tool-workflow'
+import * as timeoutPolicy from '@deepseek-ai/dsh-timeout-policy'
+import SpillLocal from '@deepseek-ai/dsh-spill-local'
+import * as spillPolicy from '@deepseek-ai/dsh-spill-policy'
+
+/** Options for bootHost — the assembly-layer composition knobs. */
+export interface BootHostOptions {
+  /** Root directory for JSONL session persistence. */
+  persistenceRoot: string
+  /** Default provider route for created/resumed agents (defaults to 'deepseek', the only adapter bootHost registers). */
+  provider?: string
+  /** Default model id (defaults to 'deepseek-v4-flash', matching the demos). */
+  model?: string
+  /**
+   * Default project directory for sessions created without an explicit cwd
+   * (defaults to the host process working directory). A session's cwd is its
+   * project path — a per-session choice, not a host property; this option only
+   * supplies the value used when the creator does not choose one.
+   */
+  cwd?: string
+}
+
+/** Host-level default agent routing: the single source injected on create and reported by host.describe. */
+export interface HostDefaults {
+  provider: string
+  model: string
+  /** Default project directory for new sessions whose create request carries no cwd. */
+  cwd: string
+}
+
+/** Booted host handle: composed root context + resolved defaults + disposer. */
+export interface HostHandle {
+  /** Root context with the full plugin assembly mounted. */
+  ctx: Context
+  /** Resolved default agent routing (options ?? built-in fallbacks). */
+  defaults: HostDefaults
+  /** Tear down the whole plugin tree. */
+  dispose(): Promise<void>
+}
+
+/**
+ * Compose the harness host plugin assembly (the one place deciding which plugins mount and
+ * with what defaults — shells must not alter the assembly).
+ * @param options - persistence root and optional default provider/model.
+ * @returns the booted handle (ctx + defaults + dispose).
+ */
+export async function bootHost(options: BootHostOptions): Promise<HostHandle> {
+  const defaults: HostDefaults = {
+    provider: options.provider ?? 'deepseek',
+    model: options.model ?? 'deepseek-v4-flash',
+    cwd: options.cwd ?? process.cwd(),
+  }
+  const ctx = new Context()
+  await ctx.plugin(Timer)
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt, { persona: '' })
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(TaskService)
+  await ctx.plugin(AgentLoop, { agents: [] })
+  await ctx.plugin(LlmDeepSeek, {})
+  await ctx.plugin(SessionPersistenceJsonl, { root: options.persistenceRoot, compression: 'none' })
+  await ctx.plugin(LocalBashExecutor, {})
+  // Tool suite mirroring the demo:repl composition (repl-agent/cordis.yml +
+  // the agent-spine bundle) so web sessions get the same coding-agent tool
+  // face; deviations are noted inline.
+  await ctx.plugin(toolBash, {})
+  await ctx.plugin(toolTodo)
+  await ctx.plugin(toolTasks, {})
+  // fs paths resolve against the host default project rather than the raw
+  // process cwd — the same source create() injects into session.cwd.
+  await ctx.plugin(FsLocal, { cwd: defaults.cwd })
+  await ctx.plugin(fsPolicy)
+  await ctx.plugin(toolFs, {})
+  await ctx.plugin(toolFsSearch, {})
+  // Skill stack with the demo default dshHome (~/.dsh via resolveDshHome).
+  await ctx.plugin(SkillService, {})
+  await ctx.plugin(SkillLocal, {})
+  await ctx.plugin(toolSkill, {})
+  // Request pressure + compaction (service-wide defaults, as in repl-agent).
+  await ctx.plugin(TokenMeter)
+  await ctx.plugin(CompactBasic)
+  // Subagent spawn/fork backends and their two model-facing tool instances.
+  await ctx.plugin(SubagentService)
+  await ctx.plugin(SubagentSpawn, { providerName: 'spawn' })
+  await ctx.plugin(SubagentFork, { providerName: 'fork' })
+  await ctx.plugin(toolSubagent, { provider: 'spawn', toolName: 'subagent' })
+  await ctx.plugin(toolSubagent, { provider: 'fork', toolName: 'subagent_fork' })
+  await ctx.plugin(WorkflowWorkerthread, { provider: 'spawn' })
+  await ctx.plugin(toolWorkflow, {})
+  // Declared per-tool timeouts become enforced deadlines.
+  await ctx.plugin(timeoutPolicy)
+  // Oversized tool output spills to session-scoped files (repl-agent budget).
+  await ctx.plugin(SpillLocal, {})
+  await ctx.plugin(spillPolicy, { maxInlineBytes: 50000 })
+  return { ctx, defaults, dispose: () => ctx.fiber.dispose() }
+}
diff --git a/packages/host/runtime/src/index.ts b/packages/host/runtime/src/index.ts
new file mode 100644
index 0000000000..55e143a495
--- /dev/null
+++ b/packages/host/runtime/src/index.ts
@@ -0,0 +1,14 @@
+/**
+ * @deepseek-ai/dsh-host-runtime — host runtime assembly layer: the core spine
+ * composition (bootHost), the ApiProxy implementation (createApiProxy), and
+ * the one-step shell seam (startHost). Host-level configuration (defaults,
+ * persistenceRoot, future user profile) lives here.
+ */
+
+export { bootHost } from './boot.ts'
+export type { BootHostOptions, HostDefaults, HostHandle } from './boot.ts'
+export { createApiProxy } from './api-proxy.ts'
+export type { ApiProxyDefaults } from './api-proxy.ts'
+export { startHost } from './start.ts'
+export type { StartHostOptions, RunningHost } from './start.ts'
+export { mountWebPlugins, WEB_UI_PLUGINS } from './web-plugins.ts'
diff --git a/packages/host/runtime/src/invariant.ts b/packages/host/runtime/src/invariant.ts
new file mode 100644
index 0000000000..649df3c1b6
--- /dev/null
+++ b/packages/host/runtime/src/invariant.ts
@@ -0,0 +1,31 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-host-runtime`.
+ * @module @deepseek-ai/dsh-host-runtime/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-host-runtime'
+
+/** Cordis companion plugin name. */
+export const name = 'host-runtime-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this assembly layer only composes plugins owned
+ * elsewhere; the event/data relations it touches (session events, agent
+ * lifecycle, wire frames) are asserted by their owning packages' companions.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/host/runtime/src/start.ts b/packages/host/runtime/src/start.ts
new file mode 100644
index 0000000000..44412cf184
--- /dev/null
+++ b/packages/host/runtime/src/start.ts
@@ -0,0 +1,58 @@
+/**
+ * One-step host startup seam: boot core → assemble ApiProxy → assemble the
+ * fetch handler. The returned RunningHost is shell-agnostic — node:http
+ * (dsh web), in-process injection (dsh -p, tests), an IPC bridge (future
+ * Electron sidecar), and front-door plugin mounting (future dsh acp) all
+ * consume the same shape.
+ */
+
+import type { Context } from 'cordis'
+import type { ApiProxy } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
+import { bootHost } from './boot.ts'
+import type { BootHostOptions, HostDefaults } from './boot.ts'
+import { createApiProxy } from './api-proxy.ts'
+
+/** Options for startHost. */
+export interface StartHostOptions {
+  /**
+   * Passed through to bootHost verbatim (persistenceRoot required +
+   * provider?/model?). Future host-level knobs (profile, log sink — any
+   * output added to the assembly MUST be switchable off here) land as
+   * additive fields.
+   */
+  boot: BootHostOptions
+}
+
+/** Running host handle: the contract impl plus its fetch carrier and root ctx. */
+export interface RunningHost {
+  /** Contract implementation (direct calls for in-process consumers; the input of an IPC adapter). */
+  api: ApiProxy
+  /** WHATWG-fetch-shaped carrier (web shell bridges it to node:http; host-side endpoint of an IPC bridge). */
+  handler: { fetch: typeof fetch }
+  /** Host-level default routing (describe and every shell share this single source). */
+  defaults: HostDefaults
+  /**
+   * Root context — a formal seam, not an escape hatch: (1) the mount point for
+   * protocol front-door plugins (`dsh acp` = startHost() → ctx.plugin(uiAcp, config));
+   * (2) headless session-event subscription. Discipline: consuming clients must
+   * not bypass `api` through ctx; shells must not ctx.plugin to alter the
+   * assembly (mounting a front door is the shell's own shape, not an assembly change).
+   */
+  ctx: Context
+  /** Single shutdown exit (ctx.fiber.dispose()). Idempotent: a second call returns the same promise. */
+  dispose(): Promise<void>
+}
+
+/**
+ * Boot the host and assemble its consumption surfaces in one step.
+ * @param options - boot passthrough (see StartHostOptions).
+ * @returns the running host handle shared by every shell shape.
+ */
+export async function startHost(options: StartHostOptions): Promise<RunningHost> {
+  const host = await bootHost(options.boot)
+  const api = createApiProxy(host.ctx, host.defaults)
+  const handler = toFetchHandler(api)
+  let disposing: Promise<void> | undefined
+  return { api, handler, defaults: host.defaults, ctx: host.ctx, dispose: () => (disposing ??= host.dispose()) }
+}
diff --git a/packages/host/runtime/src/web-plugins.ts b/packages/host/runtime/src/web-plugins.ts
new file mode 100644
index 0000000000..26ce5b3396
--- /dev/null
+++ b/packages/host/runtime/src/web-plugins.ts
@@ -0,0 +1,63 @@
+/**
+ * Web UI plugin assembly: mounts @cordisjs/plugin-loader with an in-memory
+ * entry tree listing the eight UI plugin packages (the P-I config-source bar —
+ * a cordis.yml file form comes later; install/remove currently means editing
+ * this list and restarting). The web plugin registry discovers the entries by
+ * their package.json dshClient declarations; node halves are empty applies,
+ * so mounting them here costs nothing beyond Loader governance.
+ */
+import { createRequire } from 'node:module'
+import type { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+
+/** The eight UI plugin packages served to the browser (order = manifest order). */
+export const WEB_UI_PLUGINS = [
+  '@deepseek-ai/dsh-client-connection',
+  '@deepseek-ai/dsh-client-runtime',
+  '@deepseek-ai/dsh-client-ui-theme',
+  '@deepseek-ai/dsh-client-i18n',
+  '@deepseek-ai/dsh-client-ui-layout',
+  '@deepseek-ai/dsh-client-ui-sidebar',
+  '@deepseek-ai/dsh-client-ui-conversation',
+  '@deepseek-ai/dsh-client-ui-trajectory',
+] as const
+
+/** What the shell hands the web plugin registry (loader view + module resolution seam). */
+export interface MountedWebPlugins {
+  /** Entry enumeration surface of the mounted Loader (registry scan source). */
+  loader: { entries(): Iterable<{ options: { name: string }; fiber?: unknown; disabled: boolean }> }
+  /** Resolve a plugin package's package.json absolute path. */
+  resolvePkgJson: (name: string) => string
+}
+
+/**
+ * Mount the Loader (when absent) and create one in-memory entry per UI
+ * plugin, then wait for the tree to settle. A plugin whose import fails
+ * leaves its entry fiber-less — surfaced here as a loud throw listing the
+ * failures (misconfiguration must not silently drop a UI plugin).
+ * @param ctx - host root context (bootHost product).
+ * @returns the loader view and package.json resolver the registry consumes.
+ */
+export async function mountWebPlugins(ctx: Context): Promise<MountedWebPlugins> {
+  // The Loader resolves bare specifiers against ctx.baseUrl; without one the
+  // import silently fails and every entry stays fiber-less. This package
+  // depends on all eight UI plugins, so its own URL is the right anchor.
+  ctx.baseUrl ??= import.meta.url
+  if (ctx.get('loader') === undefined) await ctx.plugin(Loader)
+  const existing = new Set([...ctx.loader.entries()].map(entry => entry.options.name))
+  for (const name of WEB_UI_PLUGINS) {
+    if (!existing.has(name)) await ctx.loader.create({ name })
+  }
+  await ctx.loader.await()
+  const dead = [...ctx.loader.entries()]
+    .filter(entry => (WEB_UI_PLUGINS as readonly string[]).includes(entry.options.name))
+    .filter(entry => entry.fiber === undefined && !entry.disabled)
+  if (dead.length > 0) {
+    throw new Error(`web-plugins: UI plugin(s) failed to load: ${dead.map(e => e.options.name).join(', ')}`)
+  }
+  const require = createRequire(import.meta.url)
+  return {
+    loader: ctx.loader,
+    resolvePkgJson: name => require.resolve(`${name}/package.json`),
+  }
+}
diff --git a/packages/host/runtime/tests/api-proxy-cold.spec.ts b/packages/host/runtime/tests/api-proxy-cold.spec.ts
new file mode 100644
index 0000000000..01f1da7d17
--- /dev/null
+++ b/packages/host/runtime/tests/api-proxy-cold.spec.ts
@@ -0,0 +1,94 @@
+/**
+ * Cold-session and degenerate-composition paths of the host ApiProxy:
+ * sessions.list merging persisted-but-unattached summaries (mtime source,
+ * createdAt fallbacks, lineage projection) and the resume error split when
+ * the composition has no persistence gate and no agent factory.
+ */
+
+import { mkdtempSync, writeFileSync, utimesSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SessionStore from '@deepseek-ai/dsh-session'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import type { RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { createApiProxy } from '../src/api-proxy.ts'
+
+const sid = (id: string): SessionId => id as SessionId
+
+let nextRpc = 1
+function request<P>(payload: P): RpcRequest<P> {
+  return { rpcId: RpcId(`cold-${String(nextRpc++)}`), payload }
+}
+
+function header(id: string, createdAt: number, extra: Partial<SessionHeader> = {}): SessionHeader {
+  return { version: 0, id: sid(id), createdAt, cwd: '/proj', ...extra }
+}
+
+describe('sessions.list cold merge', () => {
+  it('summarizes unattached sessions: log mtime, locate-less and vanished-log createdAt fallbacks, lineage', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const root = mkdtempSync(join(tmpdir(), 'dsh-cold-'))
+    const logPath = join(root, 'a.log')
+    writeFileSync(logPath, 'log-bytes')
+    utimesSync(logPath, 5000, 5000) // mtime 5_000_000 ms — newer than every createdAt below
+    const metas = [
+      header('session-a', 1000),
+      header('session-b', 2000, { parentSession: sid('session-parent') }),
+      header('session-c', 1500),
+    ]
+    // Structural fake of the persistence face list() consumes: list + locate.
+    // locate: a real per-session file (mtime wins), a backend without one
+    // (SQLite shape → createdAt), and a path whose file vanished (stat ENOENT
+    // → createdAt).
+    ctx.provide('sessionPersistence', {
+      list: () => Promise.resolve(metas),
+      locate: (meta: SessionHeader) => {
+        if (meta.id === sid('session-a')) return { kind: 'jsonl', path: logPath }
+        if (meta.id === sid('session-c')) return { kind: 'jsonl', path: join(root, 'vanished.log') }
+        return undefined
+      },
+    })
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
+
+    const response = await api.sessions.list(request({}))
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) throw new Error('unreachable')
+    const items = response.result.value.items
+    expect(items.map(item => item.sessionId)).toEqual(['session-a', 'session-b', 'session-c'])
+    const [a, b, c] = items
+    expect(a?.updatedAt).toBeCloseTo(5_000_000, -3)
+    expect(a?.running).toBe(false)
+    expect(a?.cwd).toBe('/proj')
+    expect(a?.parentSessionId).toBeUndefined()
+    expect(b?.updatedAt).toBe(2000)
+    expect(b?.parentSessionId).toBe('session-parent')
+    expect(c?.updatedAt).toBe(1500)
+  })
+})
+
+describe('degenerate composition (no persistence, no factory)', () => {
+  it('list skips the cold merge and resume maps a non-not-found failure to internal', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
+
+    const listed = await api.sessions.list(request({}))
+    expect(listed.result.ok).toBe(true)
+    if (listed.result.ok) expect(listed.result.value.items).toEqual([])
+
+    // No persistence → the servable gate passes silently; the factory-less
+    // registry then rejects resume, which is NOT a SessionNotFound.
+    const response = await api.sessions.history(request({ sessionId: sid('session-ghost') }))
+    expect(response.result.ok).toBe(false)
+    if (!response.result.ok) {
+      expect(response.result.error.code).toBe('internal')
+      expect(response.result.error.message).toMatch(/resume failed for session "session-ghost"/)
+    }
+  })
+})
diff --git a/packages/host/runtime/tests/api-proxy-view.spec.ts b/packages/host/runtime/tests/api-proxy-view.spec.ts
new file mode 100644
index 0000000000..d000742262
--- /dev/null
+++ b/packages/host/runtime/tests/api-proxy-view.spec.ts
@@ -0,0 +1,179 @@
+/**
+ * Tool-card view computation over the mux live path: three standard card types
+ * arrive on the frame, a presenterless tool ships no view field, and a throwing
+ * presenter soft-falls to no view (the event still ships). Result pairing works
+ * both through the live open-call table and the backscan fallback after
+ * turn/end cleared it.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import SessionStore from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import type { Session, SessionId } from '@deepseek-ai/dsh-session'
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
+import type { MuxFrame, RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { createApiProxy } from '../src/api-proxy.ts'
+
+const reply = (text: string): Promise<ContentBlock[]> => Promise.resolve([{ type: 'text', text }])
+
+function tool(name: string, presenters: Pick<ToolDefinition, 'presentCall' | 'presentResult'>): ToolDefinition {
+  return {
+    name,
+    description: `tool ${name}`,
+    parameters: { type: 'object', properties: {} },
+    execute: () => reply(`ran:${name}`),
+    ...presenters,
+  }
+}
+
+async function harness(): Promise<{ ctx: Context }> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt, { persona: '' })
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  ctx.tools.register(tool('gen', {
+    presentCall: () => ({ card: 'generic', title: 'gen call' }),
+    presentResult: (_args, result) => ({ card: 'generic', title: result.isError ? 'gen failed' : 'gen done' }),
+  }))
+  ctx.tools.register(tool('term', {
+    presentCall: args => ({ card: 'terminal', title: (args as { cmd?: string }).cmd ?? '' }),
+    presentResult: () => ({ card: 'terminal', output: 'done' }),
+  }))
+  ctx.tools.register(tool('diffy', {
+    presentCall: () => ({ card: 'diff', title: 'Write f.txt', diffs: [{ path: 'f.txt', oldText: null, newText: 'x' }] }),
+  }))
+  ctx.tools.register(tool('plain', {}))
+  ctx.tools.register(tool('boom', {
+    presentCall: () => { throw new Error('presenter exploded') },
+  }))
+  return { ctx }
+}
+
+/** Drain frames from an open mux stream until `count` session/event frames arrived. */
+async function collect(iterable: AsyncIterable<RpcRequest<MuxFrame>>, count: number, abort: AbortController): Promise<MuxFrame[]> {
+  const frames: MuxFrame[] = []
+  for await (const frame of iterable) {
+    frames.push(frame.payload)
+    if (frames.filter(f => f.type === 'session/event').length >= count) abort.abort()
+  }
+  return frames
+}
+
+describe('mux live view computation', () => {
+  it('attaches the three standard card views, omits view without a presenter, soft-falls on throw', async () => {
+    const { ctx } = await harness()
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
+    const abort = new AbortController()
+    const stream = api.events.mux({ rpcId: RpcId('t-mux'), payload: {} }, abort.signal)
+    const collected = collect(stream, 7, abort)
+
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-gen'), name: 'gen', arguments: '{}' })
+    session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-term'), name: 'term', arguments: '{"cmd":"echo hi"}' })
+    session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-diff'), name: 'diffy', arguments: '{}' })
+    session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-plain'), name: 'plain', arguments: '{}' })
+    session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-boom'), name: 'boom', arguments: '{}' })
+    session.append('tool/result', { turn: 1, step: 1, callId: CallId('c-gen'), content: [{ type: 'text', text: 'ok' }], isError: false }, { surfaceOp: 'append' })
+
+    const frames = await collected
+    const events = frames.filter(f => f.type === 'session/event')
+    const byCall = new Map(events
+      .filter(f => f.event.type === 'tool/call' || f.event.type === 'tool/result')
+      .map(f => [`${f.event.type}:${(f.event.data as { callId: string }).callId}`, f]))
+
+    expect(byCall.get('tool/call:c-gen')?.view).toEqual({ for: 'call', view: { card: 'generic', title: 'gen call' } })
+    expect(byCall.get('tool/call:c-term')?.view).toEqual({ for: 'call', view: { card: 'terminal', title: 'echo hi' } })
+    expect(byCall.get('tool/call:c-diff')?.view?.view.card).toBe('diff')
+    // No presenter → the frame carries no view property at all.
+    expect('view' in (byCall.get('tool/call:c-plain') ?? {})).toBe(false)
+    // Throwing presenter → soft-fall: event ships, no view.
+    expect(byCall.get('tool/call:c-boom')).toBeDefined()
+    expect('view' in (byCall.get('tool/call:c-boom') ?? {})).toBe(false)
+    // Result pairing through the live table: presentResult saw the call's args.
+    expect(byCall.get('tool/result:c-gen')?.view).toEqual({ for: 'result', view: { card: 'generic', title: 'gen done' } })
+  })
+
+  it('serves history entries with call/result views, backscan pairing, and soft-falls', async () => {
+    const { ctx } = await harness()
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
+    const session = ctx.sessions.create()
+    // history resolves the agent first; a live structural stub is enough (only
+    // .session is read on this path).
+    ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('tool/call', { turn: 1, step: 1, callId: CallId('h-term'), name: 'term', arguments: '{"cmd":"ls"}' })
+    // meta rides through to presentResult's ToolResult (the spread arm).
+    session.append('tool/result', { turn: 1, step: 1, callId: CallId('h-term'), content: [{ type: 'text', text: 'ok' }], isError: false, meta: { n: 1 } }, { surfaceOp: 'append' })
+    // Unpaired result: no tool/call with this id anywhere in the page.
+    session.append('tool/result', { turn: 1, step: 1, callId: CallId('h-orphan'), content: [{ type: 'text', text: 'x' }], isError: false }, { surfaceOp: 'append' })
+    // Paired, but the call's stored arguments do not parse: backscan soft-falls.
+    session.append('tool/call', { turn: 1, step: 1, callId: CallId('h-bad'), name: 'term', arguments: '{broken' })
+    session.append('tool/result', { turn: 1, step: 1, callId: CallId('h-bad'), content: [{ type: 'text', text: 'y' }], isError: false }, { surfaceOp: 'append' })
+    // Presenterless tool: pairing succeeds but presentResult is absent.
+    session.append('tool/call', { turn: 1, step: 1, callId: CallId('h-plain'), name: 'plain', arguments: '{}' })
+    session.append('tool/result', { turn: 1, step: 1, callId: CallId('h-plain'), content: [{ type: 'text', text: 'z' }], isError: false }, { surfaceOp: 'append' })
+
+    const response = await api.sessions.history({ rpcId: RpcId('t-hist'), payload: { sessionId: session.id } })
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) throw new Error('unreachable')
+    const entries = response.result.value.events
+    const byKey = new Map(entries
+      .filter(entry => entry.event.type === 'tool/call' || entry.event.type === 'tool/result')
+      .map(entry => [`${entry.event.type}:${(entry.event.data as { callId: string }).callId}`, entry]))
+    expect(byKey.get('tool/call:h-term')?.view).toEqual({ for: 'call', view: { card: 'terminal', title: 'ls' } })
+    expect(byKey.get('tool/result:h-term')?.view).toEqual({ for: 'result', view: { card: 'terminal', output: 'done' } })
+    expect('view' in (byKey.get('tool/result:h-orphan') ?? {})).toBe(false)
+    expect('view' in (byKey.get('tool/result:h-bad') ?? {})).toBe(false)
+    expect('view' in (byKey.get('tool/result:h-plain') ?? {})).toBe(false)
+  })
+
+  it('drops a disposed session from the live open-call table (result after dispose gets no view)', async () => {
+    const { ctx } = await harness()
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
+    const abort = new AbortController()
+    const stream = api.events.mux({ rpcId: RpcId('t-mux3'), payload: {} }, abort.signal)
+
+    let session: Session | undefined
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      session = inner.sessions.create('session-doomed' as SessionId)
+    }, { inject: ['sessions'] }))
+    session?.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session?.append('tool/call', { turn: 1, step: 1, callId: CallId('c-doomed'), name: 'term', arguments: '{"cmd":"x"}' })
+    // Disposing the owning fiber detaches the session mid-stream; the
+    // session/disposed listener must clear its open-call table entry.
+    await fiber.dispose()
+
+    const frames = await collect(stream, 2, abort)
+    const call = frames.find(f => f.type === 'session/event' && f.event.type === 'tool/call')
+    expect(call?.type === 'session/event' && call.view?.for).toBe('call')
+  })
+
+  it('pairs a result after turn/end via the in-memory backscan fallback', async () => {
+    const { ctx } = await harness()
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
+    const abort = new AbortController()
+    const stream = api.events.mux({ rpcId: RpcId('t-mux2'), payload: {} }, abort.signal)
+    const collected = collect(stream, 4, abort)
+
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-late'), name: 'term', arguments: '{"cmd":"tail"}' })
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    // The turn/end above cleared the live table; pairing must fall back to
+    // scanning the session's in-memory events.
+    session.append('tool/result', { turn: 1, step: 1, callId: CallId('c-late'), content: [{ type: 'text', text: 'ok' }], isError: false }, { surfaceOp: 'append' })
+
+    const frames = await collected
+    const result = frames.find(f => f.type === 'session/event' && f.event.type === 'tool/result')
+    expect(result?.type === 'session/event' && result.view).toEqual({ for: 'result', view: { card: 'terminal', output: 'done' } })
+  })
+})
diff --git a/packages/host/runtime/tests/host-runtime.spec.ts b/packages/host/runtime/tests/host-runtime.spec.ts
new file mode 100644
index 0000000000..f3a2dc9a82
--- /dev/null
+++ b/packages/host/runtime/tests/host-runtime.spec.ts
@@ -0,0 +1,367 @@
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { Context } from 'cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { agentEvents } from '@deepseek-ai/dsh-agent'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { LlmAdapter } from '@deepseek-ai/dsh-llm'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { HostFrame, MuxFrame } from '@deepseek-ai/dsh-host-apiproxy/api'
+import type { RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { bootHost, startHost, type HostHandle, type RunningHost } from '../src/index.ts'
+
+/** Scripted adapter: each model call consumes the next chunk list; 'hang' streams then waits for abort. */
+class ScriptedAdapter extends LlmAdapter {
+  constructor(private script: (StreamChunk[] | 'hang')[]) {
+    super()
+  }
+
+  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    const entry = this.script.shift()
+    if (!entry) throw new Error('ScriptedAdapter: script exhausted')
+    if (entry === 'hang') {
+      yield { type: 'block-start', index: 0, blockType: 'text' }
+      await new Promise<void>((_resolve, reject) => {
+        options.signal?.addEventListener('abort', () => { reject(new Error('aborted')) }, { once: true })
+      })
+      return
+    }
+    yield * entry
+  }
+}
+
+function textResponse(text: string): StreamChunk[] {
+  return [
+    { type: 'block-start', index: 0, blockType: 'text' },
+    { type: 'text-delta', index: 0, text },
+    { type: 'block-end', index: 0, block: { type: 'text', text } },
+    { type: 'usage', usage: { inputTokens: 10, outputTokens: text.length } },
+    { type: 'finish', reason: { kind: 'stop' } },
+  ]
+}
+
+function request<P>(payload: P): RpcRequest<P> {
+  return { rpcId: RpcId(`req-${String(nextRpc++)}`), payload }
+}
+let nextRpc = 1
+
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
+  return new Promise((resolve) => {
+    const dispose = ctx.on('agent/status', (subject: Agent, status: string) => {
+      if (subject === agent && status === 'idle') {
+        dispose()
+        resolve()
+      }
+    })
+  })
+}
+
+function expectOk<T>(response: RpcResponse<T>): T {
+  expect(response.result.ok).toBe(true)
+  if (!response.result.ok) throw new Error('unreachable')
+  return response.result.value
+}
+
+let host: RunningHost | undefined
+
+beforeEach(() => {
+  vi.stubEnv('DEEPSEEK_API_KEY', 'spec-placeholder-key')
+})
+
+afterEach(async () => {
+  await host?.dispose()
+  host = undefined
+  vi.unstubAllEnvs()
+})
+
+async function boot(script: (StreamChunk[] | 'hang')[] = []): Promise<RunningHost> {
+  host = await startHost({
+    boot: { persistenceRoot: mkdtempSync(join(tmpdir(), 'dsh-host-runtime-')), provider: 'scripted', model: 'test-model' },
+  })
+  host.ctx.llm.registerAdapter(['scripted'], new ScriptedAdapter(script))
+  return host
+}
+
+describe('bootHost / startHost', () => {
+  it('falls back to the deepseek defaults and disposes idempotently', async () => {
+    const handle: HostHandle = await bootHost({ persistenceRoot: mkdtempSync(join(tmpdir(), 'dsh-boot-')) })
+    expect(handle.defaults).toMatchObject({ provider: 'deepseek', model: 'deepseek-v4-flash' })
+    expect(typeof handle.defaults.cwd).toBe('string')
+    await handle.dispose()
+  })
+
+  it('startHost assembles api + handler over the same defaults and dedupes dispose', async () => {
+    const running = await boot()
+    expect(running.defaults).toMatchObject({ provider: 'scripted', model: 'test-model' })
+    const body = JSON.stringify({ type: 'client-request', rpcId: 'r-h', method: 'host.describe', payload: {} })
+    const response = await running.handler.fetch(new Request('http://x/api/host.describe', { method: 'POST', body }))
+    const parsed = await response.json() as { result: { ok: boolean; value: { provider: string } } }
+    expect(parsed.result.value.provider).toBe('scripted')
+    const first = running.dispose()
+    expect(running.dispose()).toBe(first)
+    await first
+    host = undefined
+  })
+})
+
+describe('host.describe', () => {
+  it('reports version, cwd, defaults, and the attached count', async () => {
+    const { api } = await boot()
+    const value = expectOk(await api.host.describe(request({})))
+    expect(value).toMatchObject({ version: '0.0.1', cwd: process.cwd(), provider: 'scripted', model: 'test-model', attachedSessions: 0 })
+  })
+})
+
+describe('sessions.create / list', () => {
+  it('creates a session (echoing the request rpcId) and lists it newest-first', async () => {
+    const { api } = await boot()
+    const created = await api.sessions.create(request({ cwd: '/tmp' }))
+    const { sessionId } = expectOk(created)
+    expect(created.rpcId).toMatch(/^req-/)
+    const second = expectOk(await api.sessions.create(request({}))).sessionId
+
+    const { items } = expectOk(await api.sessions.list(request({})))
+    expect(items.map(item => item.sessionId)).toContain(sessionId)
+    expect(items.map(item => item.sessionId)).toContain(second)
+    const first = items.find(item => item.sessionId === sessionId)
+    expect(first?.cwd).toBe('/tmp')
+    expect(first?.running).toBe(false)
+    expect(first?.parentSessionId).toBeUndefined()
+  })
+})
+
+describe('sessions.prompt / cancel', () => {
+  it('queues a prompt whose rpcId rides into user/message, then the reply lands', async () => {
+    const running = await boot([textResponse('pong')])
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId)
+    expect(agent).toBeDefined()
+    const idle = waitForIdle(ctx, agent as Agent)
+    const promptRequest = request({ sessionId, mode: 'queue' as const, content: [{ type: 'text' as const, text: 'ping' }] })
+    expectOk(await api.sessions.prompt(promptRequest))
+    await idle
+
+    const value = expectOk(await api.sessions.history(request({ sessionId })))
+    const events = value.events.map(entry => entry.event)
+    const userEvent = events.find(event => event.type === 'user/message') as
+      | { data: { source?: { rpcId?: string } } } | undefined
+    expect(userEvent?.data.source?.rpcId).toBe(promptRequest.rpcId)
+    const reply = events.find(event => event.type === 'assistant/message')
+    expect(reply).toBeDefined()
+  })
+
+  it('steer on an idle agent falls through to send', async () => {
+    const running = await boot([textResponse('steered')])
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const idle = waitForIdle(ctx, ctx.agents.get(sessionId) as Agent)
+    expectOk(await api.sessions.prompt(request({ sessionId, mode: 'steer' as const, content: [{ type: 'text' as const, text: 'now' }] })))
+    await idle
+  })
+
+  it('errors session-not-found on a ghost session', async () => {
+    const { api } = await boot()
+    const response = await api.sessions.prompt(request({ sessionId: 'session-void' as SessionId, mode: 'queue' as const, content: [{ type: 'text' as const, text: 'x' }] }))
+    expect(response.result.ok).toBe(false)
+    if (!response.result.ok) expect(response.result.error.code).toBe('session-not-found')
+  })
+
+  it('maps a synchronous send throw to agent-busy', async () => {
+    const { api } = await boot()
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const poisoned = [{ type: 'text', text: 'x', bad: () => 1 }] as never
+    const response = await api.sessions.prompt(request({ sessionId, mode: 'queue' as const, content: poisoned }))
+    expect(response.result.ok).toBe(false)
+    if (!response.result.ok) expect(response.result.error.code).toBe('agent-busy')
+  })
+
+  it('cancels an attached agent and rejects an unattached one', async () => {
+    const running = await boot(['hang'])
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId) as Agent
+    agent.send([{ type: 'text', text: 'run forever' }])
+    expectOk(await api.sessions.cancel(request({ sessionId })))
+
+    const missing = await api.sessions.cancel(request({ sessionId: 'session-none' as SessionId }))
+    expect(missing.result.ok).toBe(false)
+    if (!missing.result.ok) expect(missing.result.error.code).toBe('session-not-found')
+  })
+})
+
+describe('sessions.history', () => {
+  it('implicitly resumes a cold session, deduplicating concurrent calls to one attach', async () => {
+    const persistenceRoot = mkdtempSync(join(tmpdir(), 'dsh-host-resume-'))
+    const first = await startHost({ boot: { persistenceRoot, provider: 'scripted', model: 'test-model' } })
+    first.ctx.llm.registerAdapter(['scripted'], new ScriptedAdapter([textResponse('persisted')]))
+    const { sessionId } = expectOk(await first.api.sessions.create(request({})))
+    const agent = first.ctx.agents.get(sessionId) as Agent
+    const idle = waitForIdle(first.ctx, agent)
+    agent.send([{ type: 'text', text: 'save me' }])
+    await idle
+    await first.dispose()
+
+    host = await startHost({ boot: { persistenceRoot, provider: 'scripted', model: 'test-model' } })
+    host.ctx.llm.registerAdapter(['scripted'], new ScriptedAdapter([]))
+    expect(host.ctx.agents.get(sessionId)).toBeUndefined()
+    const [a, b] = await Promise.all([
+      host.api.sessions.history(request({ sessionId })),
+      host.api.sessions.history(request({ sessionId })),
+    ])
+    for (const response of [a, b]) {
+      const value = expectOk(response)
+      expect(value.events.some(entry => entry.event.type === 'assistant/message')).toBe(true)
+    }
+    expect(host.ctx.agents.get(sessionId)).toBeDefined()
+    expect(host.ctx.agents.list()).toHaveLength(1)
+  })
+
+  it('errors session-not-found when resume fails, deduplicating concurrent resumes', async () => {
+    const { api } = await boot()
+    const ghost = 'session-ghost' as SessionId
+    const [first, second] = await Promise.all([
+      api.sessions.history(request({ sessionId: ghost })),
+      api.sessions.history(request({ sessionId: ghost })),
+    ])
+    for (const response of [first, second]) {
+      expect(response.result.ok).toBe(false)
+      if (!response.result.ok) expect(response.result.error.code).toBe('session-not-found')
+    }
+  })
+
+  it('paginates backwards on message boundaries with hasMore', async () => {
+    const running = await boot([textResponse('a1'), textResponse('a2'), textResponse('a3')])
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId) as Agent
+    for (const text of ['q1', 'q2', 'q3']) {
+      const idle = waitForIdle(ctx, agent)
+      agent.send([{ type: 'text', text }])
+      await idle
+    }
+
+    const all = expectOk(await api.sessions.history(request({ sessionId })))
+    expect(all.hasMore).toBe(false)
+    const messageCount = all.events.filter(entry => entry.event.type === 'user/message' || entry.event.type === 'assistant/message').length
+    expect(messageCount).toBe(6)
+
+    const lastPage = expectOk(await api.sessions.history(request({ sessionId, maxMessages: 1 })))
+    expect(lastPage.hasMore).toBe(true)
+    expect(lastPage.events.filter(entry => entry.event.type === 'assistant/message')).toHaveLength(1)
+    expect(lastPage.events.filter(entry => entry.event.type === 'user/message')).toHaveLength(0)
+
+    const firstSeq = lastPage.events[0]?.event.seq as number
+    const olderPage = expectOk(await api.sessions.history(request({ sessionId, beforeSeq: firstSeq, maxMessages: 2 })))
+    expect(olderPage.events.at(-1)?.event.seq).toBeLessThan(firstSeq)
+    expect(olderPage.hasMore).toBe(true)
+    expect(olderPage.events.filter(entry => entry.event.type === 'user/message' || entry.event.type === 'assistant/message').length).toBe(2)
+  })
+})
+
+describe('events streams', () => {
+  it('mux: a pending pull wakes when a frame arrives (waiter path)', async () => {
+    const running = await boot()
+    const { api } = running
+    const ac = new AbortController()
+    const stream = api.events.mux(request({}), ac.signal)[Symbol.asyncIterator]()
+    // no sessions yet: next() must pend on the queue's waiter, not the buffer
+    const pending = stream.next()
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const frame = (await pending).value as RpcRequest<MuxFrame>
+    expect(frame.payload).toMatchObject({ type: 'session/subscribed', sessionId })
+    ac.abort()
+    expect((await stream.next()).done).toBe(true)
+  })
+
+  it('lists fork lineage and announces it on the host stream', async () => {
+    const running = await boot()
+    const { api, ctx } = running
+    const { sessionId: parent } = expectOk(await api.sessions.create(request({})))
+    const ac = new AbortController()
+    const stream = api.events.host(request({}), ac.signal)[Symbol.asyncIterator]()
+    const child = `session-child-${String(Date.now())}` as SessionId
+    const handle = await ctx.agents.create({ sessionId: child, meta: { parentSession: parent }, agentOptions: { provider: 'scripted', model: 'test-model' } })
+    expect(handle.agent.id).toBe(child)
+    const added = (await stream.next()).value as RpcRequest<HostFrame>
+    expect(added.payload).toMatchObject({ type: 'host/session-added', sessionId: child, parentSessionId: parent })
+    const { items } = expectOk(await api.sessions.list(request({})))
+    expect(items.find(item => item.sessionId === child)?.parentSessionId).toBe(parent)
+
+    await handle.dispose()
+    let frame: RpcRequest<HostFrame>
+    do frame = (await stream.next()).value as RpcRequest<HostFrame>
+    while (frame.payload.type !== 'host/session-removed')
+    expect(frame.payload).toMatchObject({ type: 'host/session-removed', sessionId: child })
+    ac.abort()
+  })
+
+  it('mux: emits subscribed baselines, live session events, and new-session subscriptions until abort', async () => {
+    const running = await boot([textResponse('live')])
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+
+    const ac = new AbortController()
+    const stream = api.events.mux(request({}), ac.signal)[Symbol.asyncIterator]()
+    const baseline = await stream.next()
+    expect((baseline.value as RpcRequest<MuxFrame>).payload).toMatchObject({ type: 'session/subscribed', sessionId })
+
+    const agent = ctx.agents.get(sessionId) as Agent
+    const idle = waitForIdle(ctx, agent)
+    agent.send([{ type: 'text', text: 'go' }])
+    await idle
+    const live = await stream.next()
+    expect((live.value as RpcRequest<MuxFrame>).payload.type).toBe('session/event')
+
+    const other = expectOk(await api.sessions.create(request({}))).sessionId
+    let frame: RpcRequest<MuxFrame>
+    do frame = (await stream.next()).value as RpcRequest<MuxFrame>
+    while (!(frame.payload.type === 'session/subscribed' && frame.payload.sessionId === other))
+
+    ac.abort()
+    expect((await stream.next()).done).toBe(true)
+  })
+
+  it('host: session lifecycle, status flips (disposed suppressed), and agent errors', async () => {
+    const running = await boot([textResponse('x')])
+    const { api, ctx } = running
+    const ac = new AbortController()
+    const stream = api.events.host(request({}), ac.signal)[Symbol.asyncIterator]()
+
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const added = await stream.next()
+    expect((added.value as RpcRequest<HostFrame>).payload).toMatchObject({ type: 'host/session-added', sessionId })
+
+    const agent = ctx.agents.get(sessionId) as Agent
+    const idle = waitForIdle(ctx, agent)
+    agent.send([{ type: 'text', text: 'run' }])
+    await idle
+    const runningFrame = await stream.next()
+    expect((runningFrame.value as RpcRequest<HostFrame>).payload).toMatchObject({ type: 'host/session-status', running: true })
+    const idleFrame = await stream.next()
+    expect((idleFrame.value as RpcRequest<HostFrame>).payload).toMatchObject({ type: 'host/session-status', running: false })
+
+    // Raw ctx.emit lacks the scope carrier the mounted invariants plugin now
+    // enforces; dispatch the way the loop does.
+    agentEvents(ctx, agent).emit('agent/error', 1, 1, new Error('boom'))
+    const errorFrame = await stream.next()
+    expect((errorFrame.value as RpcRequest<HostFrame>).payload).toMatchObject({ type: 'host/agent-error', message: 'Error: boom' })
+
+    ac.abort()
+    // Push-after-done: an event landing between abort and generator wind-down
+    // must be dropped silently, not crash the queue.
+    agentEvents(ctx, agent).emit('agent/error', 1, 1, new Error('late'))
+    expect((await stream.next()).done).toBe(true)
+  })
+})
+
+describe('respond stub', () => {
+  it('always reports not-pending (step2 registry pending)', async () => {
+    const { api } = await boot()
+    const receipt = await api.respond({ type: 'client-response', rpcId: RpcId('r'), result: { ok: true, value: null } })
+    expect(receipt).toEqual({ accepted: false, reason: 'not-pending' })
+  })
+})
diff --git a/packages/host/runtime/tests/web-plugins.e2e.ts b/packages/host/runtime/tests/web-plugins.e2e.ts
new file mode 100644
index 0000000000..8d89d8a16e
--- /dev/null
+++ b/packages/host/runtime/tests/web-plugins.e2e.ts
@@ -0,0 +1,71 @@
+/**
+ * Web UI plugin assembly: the in-memory Loader tree mounts all eight UI
+ * packages (node halves), and the webserver registry built over it yields the
+ * full __DSH_BOOT__ manifest — the P-I config-source bar end to end.
+ *
+ * The Loader imports plugin packages through their exports maps (lib/), so
+ * this is a built-artifact e2e: it skips until the workspace build has run
+ * (`pnpm run build`), like the other built-* e2e suites.
+ */
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { Context } from 'cordis'
+import { afterEach, describe, expect, it } from 'vitest'
+import { createHostWebPluginRegistry } from '@deepseek-ai/dsh-host-webserver'
+import { WEB_UI_PLUGINS, mountWebPlugins } from '../src/web-plugins.ts'
+
+const nodeRequire = createRequire(import.meta.url)
+const built = WEB_UI_PLUGINS.every((name) => {
+  try {
+    return existsSync(nodeRequire.resolve(name))
+  } catch {
+    return false
+  }
+})
+
+let root: Context | undefined
+
+afterEach(async () => {
+  await root?.fiber.dispose()
+  root = undefined
+})
+
+describe.skipIf(!built)('mountWebPlugins + registry', () => {
+  it('mounts the eight-package in-memory Loader tree and projects the boot manifest', async () => {
+    root = new Context()
+    const mounted = await mountWebPlugins(root)
+    const registry = createHostWebPluginRegistry({
+      ctx: root,
+      loader: mounted.loader,
+      resolvePkgJson: mounted.resolvePkgJson,
+      onError: (err) => { throw err },
+    })
+    const rows = registry.snapshot()
+    expect(rows.map(r => r.id)).toEqual([...WEB_UI_PLUGINS])
+    // The infra four are the early-load group; the UI four are not.
+    const immediate = rows.filter(r => r.immediately === true).map(r => r.id)
+    expect(immediate).toEqual([
+      '@deepseek-ai/dsh-client-connection',
+      '@deepseek-ai/dsh-client-runtime',
+      '@deepseek-ai/dsh-client-ui-theme',
+      '@deepseek-ai/dsh-client-i18n',
+    ])
+    // Every row resolves a client path under its own package dist/.
+    for (const row of rows) {
+      expect(registry.clientPath(row.id)).toMatch(/dist[/\\]client\.js$/)
+      expect(row.url).toBe(`/plugins/${row.id}/client.js`)
+    }
+    registry.dispose()
+  })
+
+  it('is idempotent: a second mount reuses the loader and creates no duplicate entries', async () => {
+    root = new Context()
+    await mountWebPlugins(root)
+    const second = await mountWebPlugins(root)
+    // ctx.loader hands out a fresh traced proxy per access, so loader identity
+    // is not assertable; the observable contract is a single entry per package.
+    const names = [...second.loader.entries()].map(e => e.options.name)
+      .filter(n => (WEB_UI_PLUGINS as readonly string[]).includes(n))
+    expect(names.length).toBe(WEB_UI_PLUGINS.length)
+  })
+})
diff --git a/packages/host/runtime/tests/web-plugins.spec.ts b/packages/host/runtime/tests/web-plugins.spec.ts
new file mode 100644
index 0000000000..6c6a996517
--- /dev/null
+++ b/packages/host/runtime/tests/web-plugins.spec.ts
@@ -0,0 +1,114 @@
+/**
+ * mountWebPlugins unit coverage (keyless; the real eight-package walk is the
+ * built-artifact e2e). The Loader-facing behavior — baseUrl anchoring, entry
+ * creation with idempotent reuse, the fiber-less fail-loud sweep, and the
+ * resolver seam — is exercised against a stubbed loader service so it runs
+ * without built lib/ artifacts.
+ */
+import { Context } from 'cordis'
+import { afterEach, describe, expect, it } from 'vitest'
+import { WEB_UI_PLUGINS, mountWebPlugins } from '../src/web-plugins.ts'
+
+interface FakeEntry {
+  options: { name: string }
+  fiber?: unknown
+  disabled: boolean
+}
+
+/** Loader stub provided under the real service name (mountWebPlugins skips ctx.plugin(Loader) when present). */
+class FakeLoader {
+  readonly created: string[] = []
+  awaited = 0
+  constructor(private readonly entriesList: FakeEntry[], private readonly onCreate?: (name: string) => void) {}
+  entries(): Iterable<FakeEntry> {
+    return this.entriesList
+  }
+  async create(options: { name: string }): Promise<void> {
+    this.created.push(options.name)
+    this.onCreate?.(options.name)
+  }
+  async await(): Promise<void> {
+    this.awaited += 1
+  }
+}
+
+let root: Context | undefined
+
+afterEach(async () => {
+  await root?.fiber.dispose()
+  root = undefined
+})
+
+function withLoader(entriesList: FakeEntry[], onCreate?: (name: string) => void): { ctx: Context; loader: FakeLoader } {
+  root = new Context()
+  const loader = new FakeLoader(entriesList, onCreate)
+  root.reflect.provide('loader', loader)
+  return { ctx: root, loader }
+}
+
+describe('mountWebPlugins (stubbed loader)', () => {
+  it('creates one entry per UI plugin, awaits the tree, and returns the loader view + resolver', async () => {
+    const entriesList: FakeEntry[] = []
+    const { ctx, loader } = withLoader(entriesList, (name) => {
+      entriesList.push({ options: { name }, fiber: {}, disabled: false })
+    })
+    const mounted = await mountWebPlugins(ctx)
+    expect(loader.created).toEqual([...WEB_UI_PLUGINS])
+    expect(loader.awaited).toBe(1)
+    expect([...mounted.loader.entries()].map(e => e.options.name)).toEqual([...WEB_UI_PLUGINS])
+    // The resolver resolves this package's own manifest through real module resolution.
+    expect(mounted.resolvePkgJson('@deepseek-ai/dsh-host-runtime')).toMatch(/package\.json$/)
+    expect(ctx.baseUrl).toBeDefined()
+  })
+
+  it('reuses existing entries (idempotent mount creates no duplicates)', async () => {
+    const preexisting: FakeEntry[] = WEB_UI_PLUGINS.map(name => ({ options: { name }, fiber: {}, disabled: false }))
+    const { ctx, loader } = withLoader(preexisting)
+    await mountWebPlugins(ctx)
+    expect(loader.created).toEqual([])
+  })
+
+  it('throws listing every fiber-less entry (silent import failure must not drop a UI plugin)', async () => {
+    const entriesList: FakeEntry[] = []
+    const { ctx } = withLoader(entriesList, (name) => {
+      // First two load; the rest stay fiber-less (import failed silently).
+      entriesList.push({ options: { name }, fiber: entriesList.length < 2 ? {} : undefined, disabled: false })
+    })
+    await expect(mountWebPlugins(ctx)).rejects.toThrow(/UI plugin\(s\) failed to load: .*dsh-client-ui-theme/)
+  })
+
+  it('skips disabled entries in the fail-loud sweep (disabled is the one valid fiber-less state)', async () => {
+    const entriesList: FakeEntry[] = WEB_UI_PLUGINS.map(name => ({ options: { name }, fiber: undefined, disabled: true }))
+    const { ctx } = withLoader(entriesList)
+    await expect(mountWebPlugins(ctx)).resolves.toBeDefined()
+  })
+
+  it('mounts the real Loader when none is present (the ctx.plugin(Loader) branch)', async () => {
+    root = new Context()
+    // Environment-dependent outcome: with built lib/ the eight imports load
+    // and the mount resolves; without them every entry stays fiber-less and
+    // the sweep throws its loud list. Either way the branch under test is the
+    // Loader auto-mount. Manual try/catch keeps cordis-traced proxies out of
+    // expect()'s formatting path (pretty-format probes throw on them).
+    // Plain string: the success sentinel and error text share one channel.
+    let outcome: string
+    try {
+      await mountWebPlugins(root)
+      outcome = 'resolved'
+    } catch (error) {
+      outcome = error instanceof Error ? error.message : String(error)
+    }
+    expect(outcome === 'resolved' || /UI plugin\(s\) failed to load/.test(outcome)).toBe(true)
+    expect(root.get('loader') !== undefined).toBe(true)
+  }, 30_000) // built-env run imports eight real plugin packages through the Loader
+
+  it('keeps a caller-set baseUrl (anchors only when absent)', async () => {
+    const entriesList: FakeEntry[] = []
+    const { ctx } = withLoader(entriesList, (name) => {
+      entriesList.push({ options: { name }, fiber: {}, disabled: false })
+    })
+    ctx.baseUrl = 'file:///caller/anchor/'
+    await mountWebPlugins(ctx)
+    expect(ctx.baseUrl).toBe('file:///caller/anchor/')
+  })
+})
diff --git a/packages/host/runtime/tsconfig.json b/packages/host/runtime/tsconfig.json
new file mode 100644
index 0000000000..9836e0b5fd
--- /dev/null
+++ b/packages/host/runtime/tsconfig.json
@@ -0,0 +1,144 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/timer"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../llm/llm-deepseek"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../core/system-prompt"
+    },
+    {
+      "path": "../../core/tools"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../tasks/tasks"
+    },
+    {
+      "path": "../../core/agent-loop"
+    },
+    {
+      "path": "../../session-persistence/session-persistence-jsonl"
+    },
+    {
+      "path": "../../bash/bash-local"
+    },
+    {
+      "path": "../../bash/tool-bash"
+    },
+    {
+      "path": "../../compact/compact-basic"
+    },
+    {
+      "path": "../../fs/fs-local"
+    },
+    {
+      "path": "../../fs/fs-policy"
+    },
+    {
+      "path": "../../fs/tool-fs"
+    },
+    {
+      "path": "../../fs/tool-fs-search"
+    },
+    {
+      "path": "../../llm/token-meter"
+    },
+    {
+      "path": "../../skill/skill"
+    },
+    {
+      "path": "../../skill/skill-local"
+    },
+    {
+      "path": "../../skill/tool-skill"
+    },
+    {
+      "path": "../../spill/spill-local"
+    },
+    {
+      "path": "../../spill/spill-policy"
+    },
+    {
+      "path": "../../subagent/subagent"
+    },
+    {
+      "path": "../../subagent/subagent-fork"
+    },
+    {
+      "path": "../../subagent/subagent-spawn"
+    },
+    {
+      "path": "../../subagent/tool-subagent"
+    },
+    {
+      "path": "../../support/invariants"
+    },
+    {
+      "path": "../../tasks/tool-tasks"
+    },
+    {
+      "path": "../../timeout/timeout-policy"
+    },
+    {
+      "path": "../../todo/tool-todo"
+    },
+    {
+      "path": "../../workflow/tool-workflow"
+    },
+    {
+      "path": "../../workflow/workflow-workerthread"
+    },
+    {
+      "path": "../apiproxy"
+    },
+    {
+      "path": "../../../vendor/loader"
+    },
+    {
+      "path": "../../client/connection"
+    },
+    {
+      "path": "../../client/runtime"
+    },
+    {
+      "path": "../../client/ui-theme"
+    },
+    {
+      "path": "../../client/i18n"
+    },
+    {
+      "path": "../../client/ui-layout"
+    },
+    {
+      "path": "../../client/ui-sidebar"
+    },
+    {
+      "path": "../../client/ui-conversation"
+    },
+    {
+      "path": "../../client/ui-trajectory"
+    }
+  ]
+}
diff --git a/packages/host/webserver/README.md b/packages/host/webserver/README.md
new file mode 100644
index 0000000000..28f7ccd49c
--- /dev/null
+++ b/packages/host/webserver/README.md
@@ -0,0 +1,23 @@
+# @deepseek-ai/dsh-host-webserver
+
+Web-shape HTTP carrier: a `node:http` server routing `/api/*` to an injected fetch-shaped handler (node:http ↔ WHATWG bridge with SSE streamed out chunk by chunk) and everything else to static file serving with the step1-locked semantics — traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), unknown extensions ship as octet-stream, non-GET/HEAD is 405.
+
+The package has zero workspace dependencies on purpose: the handler arrives by structural typing (`{ fetch: typeof fetch }`), so `webserver ← runtime` is a runtime injection relationship, never a package dependency. Web (browser) shape only — Electron loads dist over `file://` and carries fetch over an IPC bridge, not this server. This package never prints; the URL line belongs to the shell.
+
+Client-disconnect detection hangs off the **response** `close` event, not the request: since Node 16, `IncomingMessage` `close` fires as soon as the request body is consumed (immediately for a bodyless GET), which would abort every SSE stream right after open. `RunningWebServer.close()` pairs `close()` with `closeAllConnections()` because SSE connections never end on their own.
+
+A request whose handling throws (a malformed %-escape hitting `decodeURIComponent`, a client dropping mid-body) is answered 400 — or the socket destroyed when headers are already out — and reported to `onError`; it never becomes a process-killing unhandled rejection.
+
+## Model Experience
+
+None, as the package is a pure HTTP carrier between the browser and the injected API handler; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **No TLS, auth, or origin policy** — the server binds `0.0.0.0` and trusts its network; deployment hardening (or fronting it with a real reverse proxy) is deliberately out of scope for the dev-facing v1.
+- **The starter MIME table is minimal** — extensions beyond the vite-emitted set fall back to `application/octet-stream`; extend the table when an asset class actually ships.
+- **`port` is the only listen knob** — bind address and socket options are fixed until a deployment needs them.
diff --git a/packages/host/webserver/package.json b/packages/host/webserver/package.json
new file mode 100644
index 0000000000..01d8a22e9d
--- /dev/null
+++ b/packages/host/webserver/package.json
@@ -0,0 +1,37 @@
+{
+  "name": "@deepseek-ai/dsh-host-webserver",
+  "description": "Web-shape HTTP carrier: static file serving plus the /api/* bridge to an injected fetch-shaped handler (SSE streamed through)",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "cordis": "^4.0.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "^0.0.1"
+  },
+  "devDependencies": {
+    "cordis": "^4.0.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "workspace:^"
+  }
+}
diff --git a/packages/host/webserver/src/index.ts b/packages/host/webserver/src/index.ts
new file mode 100644
index 0000000000..3d7531caed
--- /dev/null
+++ b/packages/host/webserver/src/index.ts
@@ -0,0 +1,208 @@
+/**
+ * @deepseek-ai/dsh-host-webserver — the web-shape HTTP carrier: node:http server
+ * routing /api/* to an injected fetch-shaped handler (node:http ↔ WHATWG
+ * bridge with SSE streamed out chunk by chunk) and everything else to static
+ * file serving. Web (browser) shape only — Electron loads dist over file://
+ * and carries fetch over an IPC bridge, not this server. This package never
+ * prints: the URL line belongs to the shell.
+ */
+
+import { createServer } from 'node:http'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { readFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import { serveStatic } from './static.ts'
+import type { HostWebPluginRegistry } from './web-plugins.ts'
+
+export { createHostWebPluginRegistry } from './web-plugins.ts'
+export type {
+  HostWebPluginRegistry, LoaderEntryView, LoaderView, WebPluginBootEntry, WebPluginRegistryDeps,
+} from './web-plugins.ts'
+
+/** Options for startWebServer. */
+export interface WebServerOptions {
+  /** Port to listen on (0.0.0.0). */
+  port: number
+  /**
+   * Absolute path of index.html inside the static root — the caller resolves
+   * it (dist location is workspace knowledge of the shell, not this package's).
+   */
+  distIndex: string
+  /** Fetch-shaped API carrier; /api/*-prefixed requests are bridged to it. */
+  apiHandler: { fetch: typeof fetch }
+  /**
+   * Web plugin table. When present, every index.html response carries a
+   * `window.__DSH_BOOT__` manifest script and `/plugins/<id>/client.js` serves
+   * each plugin's client bundle. Absent = both surfaces off (carrier-only use).
+   */
+  webPlugins?: Pick<HostWebPluginRegistry, 'snapshot' | 'clientPath'>
+}
+
+/** Listening web server handle. */
+export interface RunningWebServer {
+  /** The listening port (for the shell's URL line; equals options.port). */
+  port: number
+  /**
+   * Shutdown: close + closeAllConnections (SSE connections never end on their
+   * own; without the force-close, close() would hang). Idempotent.
+   */
+  close(): Promise<void>
+}
+
+/**
+ * Start the web-shape HTTP server: listen(port, '0.0.0.0').
+ * Routing: /api/* → apiHandler bridge; non-GET/HEAD → 405; everything else →
+ * static with the step1-locked semantics (403 traversal, SPA fallback 200).
+ * A listen failure (EADDRINUSE…) rejects — the shell decides how to exit; a
+ * server error after listen goes to onError. A request whose handling throws
+ * (malformed %-escapes, a client dropping mid-body) is answered 400 — or the
+ * socket destroyed when headers are already out — and reported to onError;
+ * it never becomes an unhandled rejection.
+ * @param options - port, static root anchor, and the API carrier.
+ * @param onError - sink for post-listen server errors and per-request handling failures.
+ * @returns the running server handle once listening.
+ */
+export function startWebServer(options: WebServerOptions, onError: (err: Error) => void): Promise<RunningWebServer> {
+  const { port, distIndex, apiHandler, webPlugins } = options
+  const distRoot = dirname(distIndex)
+  const renderIndex = webPlugins === undefined ? undefined : async (): Promise<string> => {
+    const html = await readFile(distIndex, 'utf8')
+    return injectBootManifest(html, webPlugins.snapshot())
+  }
+
+  const handle = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    /* v8 ignore next -- `?? '/'` arm: node:http always sets url on server
+    requests; the field is only optional on the client-side IncomingMessage type */
+    const rawPath = new URL(req.url ?? '/', 'http://x').pathname
+    if (rawPath.startsWith('/api/')) {
+      await bridge(req, res, apiHandler)
+      return
+    }
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      res.writeHead(405)
+      res.end()
+      return
+    }
+    if (webPlugins !== undefined && rawPath.startsWith('/plugins/') && rawPath.endsWith('/client.js')) {
+      await servePluginBundle(decodeURIComponent(rawPath), res, webPlugins)
+      return
+    }
+    await serveStatic(decodeURIComponent(rawPath), res, distRoot, distIndex, renderIndex)
+  }
+  // Last-resort guard: handle() rejecting would otherwise be an unhandled
+  // rejection, and one malformed request (a bad %-escape hitting
+  // decodeURIComponent, a client dropping mid-body) would kill the whole
+  // process. Nothing after this catch can throw again on the same response.
+  const server = createServer((req, res) => {
+    handle(req, res).catch((err: unknown) => {
+      onError(err instanceof Error ? err : new Error(String(err)))
+      if (res.headersSent) {
+        res.destroy()
+        return
+      }
+      res.writeHead(400)
+      res.end()
+    })
+  })
+
+  let closing: Promise<void> | undefined
+  const close = (): Promise<void> => (closing ??= new Promise((resolveClose) => {
+    server.close(() => { resolveClose() })
+    server.closeAllConnections()
+  }))
+
+  return new Promise((resolveListen, rejectListen) => {
+    server.once('error', rejectListen)
+    server.listen(port, '0.0.0.0', () => {
+      server.off('error', rejectListen)
+      server.on('error', onError)
+      resolveListen({ port, close })
+    })
+  })
+}
+
+/**
+ * Inject the boot manifest into index.html: `window.__DSH_BOOT__` as the first
+ * script in <head> (before the shell bundle reads it). `<` is escaped in the
+ * JSON so plugin-controlled strings cannot break out of the script element.
+ * @param html - the index.html source.
+ * @param plugins - the manifest rows from the registry snapshot.
+ * @returns the html with the manifest script injected.
+ */
+export function injectBootManifest(html: string, plugins: readonly unknown[]): string {
+  const json = JSON.stringify({ plugins }).replaceAll('<', '\\u003c')
+  const script = `<script>window.__DSH_BOOT__ = ${json}</script>`
+  const head = html.indexOf('<head>')
+  if (head !== -1) return `${html.slice(0, head + 6)}${script}${html.slice(head + 6)}`
+  // Headless fixture pages may lack <head>; prepending keeps the read-before-shell ordering.
+  return `${script}${html}`
+}
+
+/** Serve one plugin client bundle from the registry table (unknown id = 404; the id may contain a scope slash). */
+async function servePluginBundle(
+  pathname: string, res: ServerResponse, webPlugins: Pick<HostWebPluginRegistry, 'clientPath'>,
+): Promise<void> {
+  const id = pathname.slice('/plugins/'.length, -'/client.js'.length)
+  const path = webPlugins.clientPath(id)
+  if (path === undefined) {
+    res.writeHead(404)
+    res.end()
+    return
+  }
+  try {
+    const body = await readFile(path)
+    res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8' })
+    res.end(body)
+  } catch {
+    // Registered but unreadable (bundle not built yet): loud 404 beats a silent SPA-fallback HTML page.
+    res.writeHead(404)
+    res.end()
+  }
+}
+
+/** Bridge one node:http request to the WHATWG fetch handler (client close aborts; SSE bodies stream out chunk by chunk). */
+async function bridge(req: IncomingMessage, res: ServerResponse, apiHandler: { fetch: typeof fetch }): Promise<void> {
+  const abort = new AbortController()
+  // Client-disconnect detection MUST hang off the response, not the request:
+  // since Node 16, IncomingMessage 'close' fires as soon as the request body is
+  // fully consumed (immediately for a bodyless GET), which would abort every SSE
+  // stream right after open. ServerResponse 'close' fires on connection teardown;
+  // writableEnded distinguishes a normal end() from the client going away.
+  res.on('close', () => {
+    if (!res.writableEnded) abort.abort()
+  })
+  const chunks: Buffer[] = []
+  for await (const chunk of req) chunks.push(chunk as Buffer)
+  /* v8 ignore next 3 -- `??` arms: node:http always sets url/method on server
+  requests; the fields are only optional on the client-side IncomingMessage type */
+  const request = new Request(new URL(req.url ?? '/', 'http://dsh.internal'), {
+    method: req.method ?? 'GET',
+    headers: Object.fromEntries(Object.entries(req.headers).filter(([, v]) => typeof v === 'string') as [string, string][]),
+    ...chunks.length > 0 ? { body: Buffer.concat(chunks) } : {},
+    signal: abort.signal,
+  })
+  const response = await apiHandler.fetch(request)
+  res.writeHead(response.status, Object.fromEntries(response.headers.entries()))
+  if (response.body === null) {
+    res.end()
+    return
+  }
+  for await (const chunk of response.body) {
+    // Backpressure: a false return means the socket buffer is full — wait for drain
+    // instead of buffering unboundedly (slow/suspended SSE 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)) {
+      await new Promise<void>((resolve) => {
+        const done = (): void => {
+          res.off('drain', done)
+          res.off('close', done)
+          resolve()
+        }
+        res.once('drain', done)
+        res.once('close', done)
+      })
+    }
+  }
+  res.end()
+}
diff --git a/packages/host/webserver/src/invariant.ts b/packages/host/webserver/src/invariant.ts
new file mode 100644
index 0000000000..87e3463121
--- /dev/null
+++ b/packages/host/webserver/src/invariant.ts
@@ -0,0 +1,49 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-host-webserver`.
+ * @module @deepseek-ai/dsh-host-webserver/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-host-webserver'
+
+/** Cordis companion plugin name. */
+export const name = 'host-webserver-invariant'
+/** Service required before the companion can register. */
+export const inject = ['invariants']
+
+/**
+ * Owned relation: the web plugin registry's boot manifest must stay
+ * self-consistent — every snapshot() row must resolve a clientPath under the
+ * same id (the /plugins/<id>/client.js URL it advertises would otherwise 404
+ * on a browser that just received the manifest). Checked synchronously on
+ * every rescan trigger (cordis 'internal/plugin'): snapshot() and
+ * clientPath() read the same table object, so the relation is
+ * self-consistent at any instant — no need to wait out the registry's own
+ * debounced rescan. The registry arrives through the context key the
+ * assembly publishes it under.
+ */
+const install: InvariantInstaller = (ctx, fail) => {
+  ctx.on('internal/plugin', () => {
+    const registry = ctx.get('webPlugins') as
+      | { snapshot(): { id: string; url: string }[]; clientPath(id: string): string | undefined }
+      | undefined
+    if (registry === undefined) return // carrier-only deployments never publish the registry
+    for (const row of registry.snapshot()) {
+      if (registry.clientPath(row.id) === undefined) {
+        fail(`web plugin manifest row "${row.id}" advertises ${row.url} but resolves no client bundle path — the served __DSH_BOOT__ would 404 on fetch`)
+      }
+    }
+  }, { global: true })
+}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/host/webserver/src/static.ts b/packages/host/webserver/src/static.ts
new file mode 100644
index 0000000000..e5cfdd106f
--- /dev/null
+++ b/packages/host/webserver/src/static.ts
@@ -0,0 +1,58 @@
+/**
+ * Static file serving for the web shell: the starter MIME table and the
+ * request handler with the semantics locked by the step1 acceptance list —
+ * traversal outside the dist root is 403, any miss falls back to index.html
+ * with HTTP 200 (SPA routing), unknown extensions ship as octet-stream.
+ */
+
+import type { ServerResponse } from 'node:http'
+import { extname, join, normalize, resolve } from 'node:path'
+import { readFile } from 'node:fs/promises'
+
+const MIME: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.json': 'application/json',
+  '.map': 'application/json',
+}
+
+/**
+ * Serve one GET/HEAD static request from the dist root.
+ * @param pathname - decoded URL pathname of the request.
+ * @param res - the node:http response to write.
+ * @param distRoot - absolute dist root directory (resolved by the caller).
+ * @param distIndex - absolute path of index.html inside distRoot.
+ * @param renderIndex - when set, produces the index.html body (boot-manifest
+ * injection) for `/` and every SPA fallback; undefined serves the file verbatim.
+ */
+export async function serveStatic(
+  pathname: string, res: ServerResponse, distRoot: string, distIndex: string,
+  renderIndex?: () => Promise<string>,
+): Promise<void> {
+  const target = resolve(normalize(join(distRoot, pathname)))
+  // Traversal rejection: the target must be distRoot itself (`/`) or stay under it.
+  if (target !== distRoot && !target.startsWith(distRoot + '/')) {
+    res.writeHead(403)
+    res.end()
+    return
+  }
+  const serveIndex = async (): Promise<void> => {
+    const body = renderIndex === undefined ? await readFile(distIndex) : await renderIndex()
+    res.writeHead(200, { 'content-type': MIME['.html'] })
+    res.end(body)
+  }
+  if (target === distRoot || target === distIndex) {
+    await serveIndex()
+    return
+  }
+  try {
+    const body = await readFile(target)
+    res.writeHead(200, { 'content-type': MIME[extname(target)] ?? 'application/octet-stream' })
+    res.end(body)
+  } catch {
+    // Miss (ENOENT/EISDIR) falls back to index.html with 200 (SPA routing).
+    await serveIndex()
+  }
+}
diff --git a/packages/host/webserver/src/web-plugins.ts b/packages/host/webserver/src/web-plugins.ts
new file mode 100644
index 0000000000..ee1e72f34c
--- /dev/null
+++ b/packages/host/webserver/src/web-plugins.ts
@@ -0,0 +1,184 @@
+/**
+ * HostWebPluginRegistry: discovers web-client plugins among the host Loader's
+ * loaded entries by their package.json `dshClient` declaration and resolves
+ * each one's client bundle path from `exports["./client"]`. The webserver
+ * consumes the table to emit `window.__DSH_BOOT__` and to serve
+ * `GET /plugins/<id>/client.js`. Discovery is declaration-only: plugin authors
+ * write package.json; no serve() call surface exists.
+ *
+ * The vendored loader emits no "entry loaded" event (only `loader/entry-init`,
+ * which fires at Entry construction before import/apply), so the registry
+ * scans `loader.entries()` and rescans on cordis `internal/plugin` (fiber
+ * create/dispose), microtask-debounced. Plugin-set changes take effect on
+ * restart per the config-source ruling; the subscription only keeps the table
+ * fresh within a process lifetime.
+ */
+
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import type { Context } from 'cordis'
+
+/** One `window.__DSH_BOOT__.plugins` row (wire shape of api-contracts v3 §9.2). */
+export interface WebPluginBootEntry {
+  /** Plugin id = package name (may contain a scope slash). */
+  id: string
+  /** Bundle URL served by this webserver (`/plugins/<id>/client.js`). */
+  url: string
+  /** Client-half load dependencies (plugin ids), topologically ordered by the client loader. */
+  inject: string[]
+  /** Marks the early-load group: fetched in parallel and applied before all other plugins. */
+  immediately?: boolean
+}
+
+/** The web plugin table consumed by the boot injection and the bundle endpoint. */
+export interface HostWebPluginRegistry {
+  /** Current manifest rows (stable order: loader entry order). */
+  snapshot(): WebPluginBootEntry[]
+  /**
+   * Absolute path of a plugin's client bundle.
+   * @param id - plugin id (package name).
+   * @returns the path, or undefined for an unknown id.
+   */
+  clientPath(id: string): string | undefined
+  /** Remove the loader subscription. */
+  dispose(): void
+}
+
+/** Structural view of a loader entry (webserver keeps zero workspace dependencies; cordis stays a type-only peer). */
+export interface LoaderEntryView {
+  options: { name: string }
+  /** Present once the entry's plugin fiber exists (import succeeded and apply ran/started). */
+  fiber?: unknown
+  /** True when the entry or an owning group is disabled. */
+  disabled: boolean
+}
+
+/** Structural view of the host Loader (entry enumeration is all the registry needs). */
+export interface LoaderView {
+  entries(): Iterable<LoaderEntryView>
+}
+
+/** Dependencies injected by the assembly layer. */
+export interface WebPluginRegistryDeps {
+  /** Host root context; used only to subscribe `internal/plugin` for rescans. */
+  ctx: Context
+  /** The host Loader owning the plugin entries. */
+  loader: LoaderView
+  /**
+   * Resolve a package specifier to its package.json absolute path (assembly
+   * passes `createRequire(...).resolve(`${name}/package.json`)`); injected so
+   * the registry makes no module-resolution assumptions of its own.
+   */
+  resolvePkgJson: (name: string) => string
+  /** Sink for rescan failures (the initial scan throws instead — misconfiguration fails loud at load). */
+  onError: (err: Error) => void
+}
+
+/** package.json `dshClient` declaration shape (file boundary — validated field by field). */
+interface DshClientDeclaration {
+  inject?: string[]
+  platform: string
+  immediately?: boolean
+}
+
+interface WebPluginRecord {
+  entry: WebPluginBootEntry
+  clientPath: string
+}
+
+/** Narrow an unknown parsed JSON value to the dshClient declaration, throwing on malformed fields. */
+function parseDshClient(name: string, value: unknown): DshClientDeclaration | undefined {
+  if (value === undefined) return undefined
+  if (typeof value !== 'object' || value === null) {
+    throw new Error(`web-plugins: ${name} has a non-object dshClient declaration`)
+  }
+  const decl = value as Record<string, unknown>
+  if (typeof decl.platform !== 'string') {
+    throw new Error(`web-plugins: ${name} dshClient.platform must be a string`)
+  }
+  if (decl.inject !== undefined && (!Array.isArray(decl.inject) || decl.inject.some(i => typeof i !== 'string'))) {
+    throw new Error(`web-plugins: ${name} dshClient.inject must be a string array`)
+  }
+  if (decl.immediately !== undefined && typeof decl.immediately !== 'boolean') {
+    throw new Error(`web-plugins: ${name} dshClient.immediately must be a boolean`)
+  }
+  return {
+    platform: decl.platform,
+    ...(decl.inject !== undefined ? { inject: decl.inject as string[] } : {}),
+    ...(decl.immediately !== undefined ? { immediately: decl.immediately } : {}),
+  }
+}
+
+/** Resolve `exports["./client"]` to a relative path, accepting the string and one-level conditional forms. */
+function clientExportOf(name: string, exportsField: unknown): string | undefined {
+  if (typeof exportsField !== 'object' || exportsField === null) return undefined
+  const client = (exportsField as Record<string, unknown>)['./client']
+  if (client === undefined) return undefined
+  if (typeof client === 'string') return client
+  if (typeof client === 'object' && client !== null) {
+    const fallback = (client as Record<string, unknown>).default
+    if (typeof fallback === 'string') return fallback
+  }
+  throw new Error(`web-plugins: ${name} exports["./client"] has an unsupported shape`)
+}
+
+/**
+ * Build the web plugin registry: scan once synchronously (a malformed
+ * declaration throws here — load-time fail loud), then rescan on
+ * `internal/plugin`, microtask-debounced (failures go to `deps.onError`).
+ * @param deps - loader view, resolution hook, and error sink (see {@link WebPluginRegistryDeps}).
+ * @returns the registry handle.
+ */
+export function createHostWebPluginRegistry(deps: WebPluginRegistryDeps): HostWebPluginRegistry {
+  let table = scan(deps)
+
+  let pending = false
+  const unsubscribe = deps.ctx.on('internal/plugin', () => {
+    if (pending) return
+    pending = true
+    queueMicrotask(() => {
+      pending = false
+      try {
+        table = scan(deps)
+      } catch (error) {
+        // Keep serving the previous table: a mid-flight rescan failure must not
+        // take down the boot manifest for plugins that were fine.
+        deps.onError(error instanceof Error ? error : new Error(String(error)))
+      }
+    })
+  })
+
+  return {
+    snapshot: () => [...table.values()].map(record => record.entry),
+    clientPath: id => table.get(id)?.clientPath,
+    dispose: () => { unsubscribe() },
+  }
+}
+
+/** One full table build from the loader's current entries. */
+function scan(deps: WebPluginRegistryDeps): Map<string, WebPluginRecord> {
+  const table = new Map<string, WebPluginRecord>()
+  for (const entry of deps.loader.entries()) {
+    if (entry.fiber === undefined || entry.disabled) continue
+    const name = entry.options.name
+    if (table.has(name)) continue
+    const pkgPath = deps.resolvePkgJson(name)
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as Record<string, unknown>
+    const decl = parseDshClient(name, pkg.dshClient)
+    if (decl === undefined || decl.platform !== 'web') continue
+    const clientRel = clientExportOf(name, pkg.exports)
+    if (clientRel === undefined) {
+      throw new Error(`web-plugins: ${name} declares dshClient but exports no "./client" bundle`)
+    }
+    table.set(name, {
+      entry: {
+        id: name,
+        url: `/plugins/${name}/client.js`,
+        inject: decl.inject ?? [],
+        ...(decl.immediately === true ? { immediately: true } : {}),
+      },
+      clientPath: join(dirname(pkgPath), clientRel),
+    })
+  }
+  return table
+}
diff --git a/packages/host/webserver/tests/invariant.spec.ts b/packages/host/webserver/tests/invariant.spec.ts
new file mode 100644
index 0000000000..8fddba992a
--- /dev/null
+++ b/packages/host/webserver/tests/invariant.spec.ts
@@ -0,0 +1,50 @@
+/**
+ * Webserver invariant companion: the boot-manifest consistency audit — every
+ * registry snapshot row must resolve a clientPath, checked on fiber lifecycle
+ * events against the assembly-published 'webPlugins' context key.
+ */
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as WebserverInvariant from '../src/invariant.ts'
+
+interface RegistryStub {
+  snapshot(): { id: string; url: string }[]
+  clientPath(id: string): string | undefined
+}
+
+async function setup(registry?: RegistryStub): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(InvariantService, { enabled: true })
+  await ctx.plugin(WebserverInvariant).await()
+  if (registry !== undefined) ctx.reflect.provide('webPlugins', registry)
+  return ctx
+}
+
+/** Fire the audit trigger directly (same technique as the scope invariant
+ *  spec): a synchronous emit propagates the fail() throw to the caller. */
+function trigger(ctx: Context): void {
+  ;(ctx.emit as (event: string, ...args: unknown[]) => void)('internal/plugin', ctx.fiber)
+}
+
+describe('webserver manifest invariant', () => {
+  it('stays silent without a registry (carrier-only deployment) and with a consistent table', async () => {
+    const bare = await setup()
+    expect(() => { trigger(bare) }).not.toThrow() // no 'webPlugins' key published
+
+    const consistent = await setup({
+      snapshot: () => [{ id: 'p1', url: '/plugins/p1/client.js' }],
+      clientPath: () => '/tmp/p1/lib/client.js',
+    })
+    expect(() => { trigger(consistent) }).not.toThrow()
+  })
+
+  it('throws on a manifest row whose bundle path no longer resolves', async () => {
+    const ctx = await setup({
+      snapshot: () => [{ id: 'ghost', url: '/plugins/ghost/client.js' }],
+      clientPath: () => undefined,
+    })
+    expect(() => { trigger(ctx) })
+      .toThrow(/manifest row "ghost".*resolves no client bundle path/)
+  })
+})
diff --git a/packages/host/webserver/tests/web-plugins.spec.ts b/packages/host/webserver/tests/web-plugins.spec.ts
new file mode 100644
index 0000000000..bb08f2ac11
--- /dev/null
+++ b/packages/host/webserver/tests/web-plugins.spec.ts
@@ -0,0 +1,210 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import { createHostWebPluginRegistry, injectBootManifest } from '../src/index.ts'
+import type { LoaderEntryView, WebPluginRegistryDeps } from '../src/index.ts'
+
+/** Write a fake installed package (package.json + optional client bundle) and return its package.json path. */
+function makePkg(root: string, name: string, pkg: Record<string, unknown>, withBundle = true): string {
+  const dir = join(root, name.replaceAll('/', '__'))
+  mkdirSync(join(dir, 'lib'), { recursive: true })
+  writeFileSync(join(dir, 'package.json'), JSON.stringify({ name, ...pkg }))
+  if (withBundle) writeFileSync(join(dir, 'lib', 'client.js'), `// bundle of ${name}`)
+  return join(dir, 'package.json')
+}
+
+const webDecl = (extra: Record<string, unknown> = {}): Record<string, unknown> => ({
+  dshClient: { inject: [], platform: 'web', ...extra },
+  exports: { '.': './lib/index.js', './client': './lib/client.js' },
+})
+
+interface Fixture {
+  deps: WebPluginRegistryDeps
+  entries: LoaderEntryView[]
+  errors: Error[]
+  ctx: Context
+}
+
+function makeDeps(
+  specs: { name: string; pkg: Record<string, unknown>; loaded?: boolean; disabled?: boolean; withBundle?: boolean }[],
+): Fixture {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-webplugins-'))
+  const paths = new Map<string, string>()
+  const entries: LoaderEntryView[] = specs.map((spec) => {
+    paths.set(spec.name, makePkg(root, spec.name, spec.pkg, spec.withBundle ?? true))
+    return { options: { name: spec.name }, fiber: spec.loaded === false ? undefined : {}, disabled: spec.disabled ?? false }
+  })
+  const ctx = new Context()
+  const errors: Error[] = []
+  const deps: WebPluginRegistryDeps = {
+    ctx,
+    loader: { entries: () => entries },
+    resolvePkgJson: (name) => {
+      const path = paths.get(name)
+      if (path === undefined) throw new Error(`unresolvable ${name}`)
+      return path
+    },
+    onError: err => void errors.push(err),
+  }
+  return { deps, entries, errors, ctx }
+}
+
+describe('createHostWebPluginRegistry', () => {
+  it('collects loaded web-declared plugins with url/inject/immediately and client paths', () => {
+    const { deps } = makeDeps([
+      { name: '@deepseek-ai/dsh-client-connection', pkg: webDecl({ immediately: true }) },
+      { name: '@deepseek-ai/dsh-client-ui-layout', pkg: webDecl({ inject: ['@deepseek-ai/dsh-client-runtime'] }) },
+      { name: '@deepseek-ai/dsh-agent', pkg: { exports: { '.': './lib/index.js' } } }, // no dshClient: skipped
+    ])
+    const registry = createHostWebPluginRegistry(deps)
+    const rows = registry.snapshot()
+    expect(rows).toEqual([
+      {
+        id: '@deepseek-ai/dsh-client-connection',
+        url: '/plugins/@deepseek-ai/dsh-client-connection/client.js',
+        inject: [],
+        immediately: true,
+      },
+      {
+        id: '@deepseek-ai/dsh-client-ui-layout',
+        url: '/plugins/@deepseek-ai/dsh-client-ui-layout/client.js',
+        inject: ['@deepseek-ai/dsh-client-runtime'],
+      },
+    ])
+    expect(registry.clientPath('@deepseek-ai/dsh-client-connection')).toMatch(/lib[/\\]client\.js$/)
+    expect(registry.clientPath('@deepseek-ai/dsh-agent')).toBeUndefined()
+    registry.dispose()
+  })
+
+  it('skips entries that are unloaded, disabled, or declare another platform', () => {
+    const { deps } = makeDeps([
+      { name: 'not-loaded', pkg: webDecl(), loaded: false },
+      { name: 'disabled', pkg: webDecl(), disabled: true },
+      { name: 'electron-only', pkg: { dshClient: { platform: 'electron' }, exports: { './client': './lib/client.js' } } },
+    ])
+    const registry = createHostWebPluginRegistry(deps)
+    expect(registry.snapshot()).toEqual([])
+    registry.dispose()
+  })
+
+  it('fails loud at build time on a dshClient declaration without a "./client" export', () => {
+    const { deps } = makeDeps([
+      { name: 'broken', pkg: { dshClient: { platform: 'web' }, exports: { '.': './lib/index.js' } } },
+    ])
+    expect(() => createHostWebPluginRegistry(deps)).toThrow(/declares dshClient but exports no/)
+  })
+
+  it('fails loud on malformed declaration fields', () => {
+    for (const dshClient of [42, { platform: 7 }, { platform: 'web', inject: 'nope' }, { platform: 'web', immediately: 'yes' }]) {
+      const { deps } = makeDeps([{ name: 'bad', pkg: { dshClient, exports: { './client': './lib/client.js' } } }])
+      expect(() => createHostWebPluginRegistry(deps)).toThrow(/dshClient/)
+    }
+  })
+
+  it('rescans on internal/plugin (debounced) and keeps the old table when a rescan fails', async () => {
+    const { deps, entries, errors, ctx } = makeDeps([
+      { name: 'late-loader', pkg: webDecl(), loaded: false },
+    ])
+    const registry = createHostWebPluginRegistry(deps)
+    expect(registry.snapshot()).toEqual([])
+
+    // Entry finishes loading; a fiber lifecycle event triggers the debounced rescan.
+    ;(entries[0] as { fiber?: unknown }).fiber = {}
+    ctx.emit('internal/plugin', ctx.fiber)
+    ctx.emit('internal/plugin', ctx.fiber) // debounce: two emissions, one rescan
+    await Promise.resolve()
+    expect(registry.snapshot().map(row => row.id)).toEqual(['late-loader'])
+
+    // A failing rescan reports the error and keeps serving the previous table.
+    entries.push({ options: { name: 'ghost' }, fiber: {}, disabled: false })
+    ctx.emit('internal/plugin', ctx.fiber)
+    await Promise.resolve()
+    expect(errors).toHaveLength(1)
+    expect(registry.snapshot().map(row => row.id)).toEqual(['late-loader'])
+
+    // After dispose, further fiber events no longer rescan.
+    registry.dispose()
+    entries.pop()
+    ctx.emit('internal/plugin', ctx.fiber)
+    await Promise.resolve()
+    expect(errors).toHaveLength(1)
+  })
+})
+
+describe('injectBootManifest', () => {
+  it('injects the manifest as the first script inside <head> and escapes </script> breakouts', () => {
+    const html = '<html><head><script src="app.js"></script></head><body></body></html>'
+    const out = injectBootManifest(html, [{ id: 'x</script><script>alert(1)', url: '/plugins/x/client.js', inject: [] }])
+    expect(out.indexOf('window.__DSH_BOOT__')).toBeLessThan(out.indexOf('app.js'))
+    expect(out).not.toContain('</script><script>alert(1)')
+    expect(out).toContain('\\u003c/script')
+  })
+
+  it('prepends when the page has no <head>', () => {
+    const out = injectBootManifest('<body>x</body>', [])
+    expect(out.startsWith('<script>window.__DSH_BOOT__')).toBe(true)
+  })
+})
+
+describe('clientExportOf shapes (through the registry build)', () => {
+  it('accepts the conditional {types, default} export form', () => {
+    const { deps } = makeDeps([{
+      name: 'conditional',
+      pkg: {
+        dshClient: { platform: 'web' },
+        exports: { './client': { types: './lib/types/client/index.d.ts', default: './lib/client.js' } },
+      },
+    }])
+    const registry = createHostWebPluginRegistry(deps)
+    expect(registry.clientPath('conditional')).toMatch(/lib[/\\]client\.js$/)
+    registry.dispose()
+  })
+
+  it('rejects a conditional form without a string default, an array form, and a non-object exports field', () => {
+    for (const exportsField of [
+      { './client': { types: './x.d.ts' } },
+      { './client': ['./a.js'] },
+    ]) {
+      const { deps } = makeDeps([{ name: 'bad-shape', pkg: { dshClient: { platform: 'web' }, exports: exportsField } }])
+      expect(() => createHostWebPluginRegistry(deps)).toThrow(/unsupported shape/)
+    }
+    // Non-object exports: treated as "no ./client export" → the declares-but-no-bundle throw.
+    const { deps } = makeDeps([{ name: 'no-exports', pkg: { dshClient: { platform: 'web' }, exports: './single.js' } }])
+    expect(() => createHostWebPluginRegistry(deps)).toThrow(/declares dshClient but exports no/)
+  })
+
+  it('skips duplicate loader entries for the same package name (first wins)', () => {
+    const { deps, entries } = makeDeps([{ name: 'dup-entry', pkg: webDecl() }])
+    const first = entries[0] as LoaderEntryView
+    entries.push({ options: { name: 'dup-entry' }, fiber: {}, disabled: false })
+    void first
+    const registry = createHostWebPluginRegistry(deps)
+    expect(registry.snapshot().filter(r => r.id === 'dup-entry')).toHaveLength(1)
+    registry.dispose()
+  })
+
+  it('rejects a null conditional form and wraps a non-Error rescan throw', async () => {
+    // client: null → the object-form branch's null guard.
+    const nulled = makeDeps([{ name: 'null-client', pkg: { dshClient: { platform: 'web' }, exports: { './client': null } } }])
+    expect(() => createHostWebPluginRegistry(nulled.deps)).toThrow(/unsupported shape/)
+
+    // Non-Error rescan throw: resolvePkgJson throws a string; onError must get a wrapped Error.
+    const { deps, entries, errors, ctx } = makeDeps([{ name: 'ok-one', pkg: webDecl() }])
+    const registry = createHostWebPluginRegistry(deps)
+    entries.push({ options: { name: 'ghost-two' }, fiber: {}, disabled: false })
+    const original = deps.resolvePkgJson
+    deps.resolvePkgJson = (name) => {
+
+      if (name === 'ghost-two') throw 'string failure'
+      return original(name)
+    }
+    ctx.emit('internal/plugin', ctx.fiber)
+    await Promise.resolve()
+    expect(errors[0]).toBeInstanceOf(Error)
+    expect(String(errors[0])).toContain('string failure')
+    registry.dispose()
+  })
+
+})
diff --git a/packages/host/webserver/tests/webserver.spec.ts b/packages/host/webserver/tests/webserver.spec.ts
new file mode 100644
index 0000000000..4cf69b41e4
--- /dev/null
+++ b/packages/host/webserver/tests/webserver.spec.ts
@@ -0,0 +1,337 @@
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
+import { createServer as createNetServer, type AddressInfo } from 'node:net'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { startWebServer, type RunningWebServer } from '../src/index.ts'
+
+/** RunningWebServer.port echoes options.port, so tests must pick a concrete free port up front. */
+function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const probe = createNetServer()
+    probe.once('error', reject)
+    probe.listen(0, () => {
+      const port = (probe.address() as AddressInfo).port
+      probe.close(() => { resolve(port) })
+    })
+  })
+}
+
+/** dist fixture: index.html + one asset of each MIME class + a subdir. */
+function makeDist(): { distIndex: string; distRoot: string } {
+  const distRoot = mkdtempSync(join(tmpdir(), 'dsh-webserver-'))
+  writeFileSync(join(distRoot, 'index.html'), '<html>INDEX</html>')
+  writeFileSync(join(distRoot, 'app.js'), 'console.log(1)')
+  writeFileSync(join(distRoot, 'app.css'), 'body{}')
+  writeFileSync(join(distRoot, 'logo.svg'), '<svg/>')
+  writeFileSync(join(distRoot, 'data.json'), '{}')
+  writeFileSync(join(distRoot, 'app.js.map'), '{}')
+  writeFileSync(join(distRoot, 'blob.bin'), 'BIN')
+  mkdirSync(join(distRoot, 'sub'))
+  writeFileSync(join(distRoot, 'sub', 'page.html'), '<html>SUB</html>')
+  return { distIndex: join(distRoot, 'index.html'), distRoot }
+}
+
+const echoingApi = {
+  fetch: async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const req = input instanceof Request ? input : new Request(input, init)
+    if (req.url.endsWith('/api/echo')) {
+      return Response.json({ method: req.method, body: await req.text(), header: req.headers.get('x-probe') })
+    }
+    if (req.url.endsWith('/api/empty')) return new Response(null, { status: 204 })
+    if (req.url.endsWith('/api/big')) {
+      // Chunks far above any socket highWaterMark force res.write to return false.
+      const big = new Uint8Array(4 * 1024 * 1024).fill(65)
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(big)
+          controller.enqueue(big)
+          controller.close()
+        },
+      })
+      return new Response(stream, { headers: { 'content-type': 'application/octet-stream' } })
+    }
+    if (req.url.endsWith('/api/sse')) {
+      const encoder = new TextEncoder()
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(encoder.encode('data: one\n\n'))
+          controller.enqueue(encoder.encode('data: two\n\n'))
+          controller.close()
+        },
+      })
+      return new Response(stream, { headers: { 'content-type': 'text/event-stream' } })
+    }
+    if (req.url.endsWith('/api/throw-string')) {
+      // Non-Error rejection: the guard must wrap it for onError.
+      throw 'string failure'
+    }
+    if (req.url.endsWith('/api/explode-mid-stream')) {
+      // Headers go out with the first chunk, then the source errors: the
+      // guard's headersSent leg must destroy the socket, not writeHead again.
+      // The error is deferred a tick so the 200 + first chunk actually flush
+      // to the client before the teardown.
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(new TextEncoder().encode('data: first\n\n'))
+          setTimeout(() => { controller.error(new Error('stream exploded')) }, 20)
+        },
+      })
+      return new Response(stream, { headers: { 'content-type': 'text/event-stream' } })
+    }
+    if (req.url.endsWith('/api/abort-probe')) {
+      // Endless SSE that only ends when the request signal aborts.
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          req.signal.addEventListener('abort', () => {
+            try {
+              controller.close()
+            } catch { /* already closed by teardown: nothing else can reach this */ }
+          }, { once: true })
+          controller.enqueue(new TextEncoder().encode('data: open\n\n'))
+        },
+      })
+      return new Response(stream, { headers: { 'content-type': 'text/event-stream' } })
+    }
+    return new Response('nope', { status: 404 })
+  },
+}
+
+let server: RunningWebServer | undefined
+
+afterEach(async () => {
+  await server?.close()
+  server = undefined
+})
+
+async function boot(onError: (err: Error) => void = () => undefined): Promise<string> {
+  const { distIndex } = makeDist()
+  const port = await freePort()
+  server = await startWebServer({ port, distIndex, apiHandler: echoingApi }, onError)
+  return `http://127.0.0.1:${String(server.port)}`
+}
+
+describe('startWebServer', () => {
+  it('reports the listening port and closes idempotently', async () => {
+    const { distIndex } = makeDist()
+    const port = await freePort()
+    server = await startWebServer({ port, distIndex, apiHandler: echoingApi }, () => undefined)
+    expect(server.port).toBe(port)
+    const first = server.close()
+    const second = server.close()
+    expect(second).toBe(first)
+    await first
+    server = undefined
+  })
+
+  it('rejects when the port is already taken', async () => {
+    const { distIndex } = makeDist()
+    const port = await freePort()
+    server = await startWebServer({ port, distIndex, apiHandler: echoingApi }, () => undefined)
+    await expect(startWebServer({ port, distIndex, apiHandler: echoingApi }, () => undefined))
+      .rejects.toMatchObject({ code: 'EADDRINUSE' })
+  })
+})
+
+describe('static serving', () => {
+  it('serves index at /, subpaths by MIME, octet-stream for unknown, SPA fallback on miss', async () => {
+    const base = await boot()
+    const index = await fetch(`${base}/`)
+    expect(index.status).toBe(200)
+    expect(index.headers.get('content-type')).toBe('text/html; charset=utf-8')
+    expect(await index.text()).toBe('<html>INDEX</html>')
+
+    expect((await fetch(`${base}/app.js`)).headers.get('content-type')).toBe('text/javascript; charset=utf-8')
+    expect((await fetch(`${base}/app.css`)).headers.get('content-type')).toBe('text/css; charset=utf-8')
+    expect((await fetch(`${base}/logo.svg`)).headers.get('content-type')).toBe('image/svg+xml')
+    expect((await fetch(`${base}/data.json`)).headers.get('content-type')).toBe('application/json')
+    expect((await fetch(`${base}/app.js.map`)).headers.get('content-type')).toBe('application/json')
+    expect((await fetch(`${base}/blob.bin`)).headers.get('content-type')).toBe('application/octet-stream')
+    expect(await (await fetch(`${base}/sub/page.html`)).text()).toBe('<html>SUB</html>')
+
+    const miss = await fetch(`${base}/routes/deep/link`)
+    expect(miss.status).toBe(200)
+    expect(await miss.text()).toBe('<html>INDEX</html>')
+  })
+
+  it('403s traversal outside the dist root and 405s non-GET/HEAD', async () => {
+    const base = await boot()
+    // %2e%2e would be dot-collapsed by WHATWG URL parsing on both ends; an
+    // encoded slash keeps the segment intact until the server's decodeURIComponent.
+    const traversal = await fetch(`${base}/..%2f..%2fetc%2fpasswd`)
+    expect(traversal.status).toBe(403)
+    const put = await fetch(`${base}/index.html`, { method: 'PUT', body: 'x' })
+    expect(put.status).toBe(405)
+  })
+
+  it('answers HEAD like GET (no 405)', async () => {
+    const base = await boot()
+    const head = await fetch(`${base}/`, { method: 'HEAD' })
+    expect(head.status).toBe(200)
+  })
+})
+
+describe('web plugin surfaces (boot injection + bundle endpoint)', () => {
+  const rows = [
+    { id: '@deepseek-ai/dsh-client-connection', url: '/plugins/@deepseek-ai/dsh-client-connection/client.js', inject: [], immediately: true },
+    { id: '@deepseek-ai/dsh-client-ui-layout', url: '/plugins/@deepseek-ai/dsh-client-ui-layout/client.js', inject: ['@deepseek-ai/dsh-client-runtime'] },
+  ]
+
+  async function bootWithPlugins(): Promise<string> {
+    const { distIndex, distRoot } = makeDist()
+    writeFileSync(join(distRoot, 'bundle.js'), 'window.DSHClientProxy.loadPlugin({})')
+    const webPlugins = {
+      snapshot: () => rows,
+      clientPath: (id: string) => id === rows[0]?.id ? join(distRoot, 'bundle.js') : undefined,
+    }
+    const port = await freePort()
+    server = await startWebServer({ port, distIndex, apiHandler: echoingApi, webPlugins }, () => undefined)
+    return `http://127.0.0.1:${String(server.port)}`
+  }
+
+  it('injects window.__DSH_BOOT__ into / and SPA fallbacks; asset requests stay verbatim', async () => {
+    const base = await bootWithPlugins()
+    const index = await (await fetch(`${base}/`)).text()
+    expect(index).toContain('window.__DSH_BOOT__')
+    const manifest = /window\.__DSH_BOOT__ = (.*?)<\/script>/.exec(index)?.[1]
+    expect(JSON.parse(manifest ?? '')).toEqual({ plugins: rows })
+
+    const fallback = await (await fetch(`${base}/routes/deep/link`)).text()
+    expect(fallback).toContain('window.__DSH_BOOT__')
+    const direct = await (await fetch(`${base}/index.html`)).text()
+    expect(direct).toContain('window.__DSH_BOOT__')
+
+    expect(await (await fetch(`${base}/app.js`)).text()).toBe('console.log(1)')
+  })
+
+  it('serves registered client bundles and 404s unknown ids (no SPA fallback)', async () => {
+    const base = await bootWithPlugins()
+    const bundle = await fetch(`${base}/plugins/@deepseek-ai/dsh-client-connection/client.js`)
+    expect(bundle.status).toBe(200)
+    expect(bundle.headers.get('content-type')).toBe('text/javascript; charset=utf-8')
+    expect(await bundle.text()).toContain('DSHClientProxy')
+
+    expect((await fetch(`${base}/plugins/unknown/client.js`)).status).toBe(404)
+  })
+
+  it('404s a registered id whose bundle file is unreadable (unbuilt dist must fail loud, not fall back to HTML)', async () => {
+    const { distIndex } = makeDist()
+    const webPlugins = {
+      snapshot: () => rows,
+      clientPath: () => '/nonexistent/lib/client.js',
+    }
+    const port = await freePort()
+    server = await startWebServer({ port, distIndex, apiHandler: echoingApi, webPlugins }, () => undefined)
+    const res = await fetch(`http://127.0.0.1:${String(server.port)}/plugins/@deepseek-ai/dsh-client-connection/client.js`)
+    expect(res.status).toBe(404)
+  })
+
+  it('keeps both surfaces off without the webPlugins option', async () => {
+    const base = await boot()
+    expect(await (await fetch(`${base}/`)).text()).toBe('<html>INDEX</html>')
+    // No plugin route: falls through to static SPA fallback semantics.
+    const res = await fetch(`${base}/plugins/x/client.js`)
+    expect(res.status).toBe(200)
+    expect(await res.text()).toBe('<html>INDEX</html>')
+  })
+})
+
+describe('request-handling guard (one bad request must not kill the process)', () => {
+  it('400s malformed %-escapes, reports to onError, and stays alive', async () => {
+    const errors: Error[] = []
+    const base = await boot(err => errors.push(err))
+    for (const path of ['/%', '/%c0', '/%zz%']) {
+      expect((await fetch(`${base}${path}`)).status).toBe(400)
+    }
+    expect(errors.length).toBe(3)
+    expect(errors[0]?.name).toBe('URIError')
+    // The barrage left the server serving.
+    expect((await fetch(`${base}/`)).status).toBe(200)
+  })
+
+  it('wraps a non-Error throw for onError and still answers 400', async () => {
+    const errors: Error[] = []
+    const base = await boot(err => errors.push(err))
+    expect((await fetch(`${base}/api/throw-string`, { method: 'POST' })).status).toBe(400)
+    expect(errors[0]).toBeInstanceOf(Error)
+    expect(errors[0]?.message).toBe('string failure')
+  })
+
+  it('destroys the socket when the failure lands after headers went out', async () => {
+    const errors: Error[] = []
+    const base = await boot(err => errors.push(err))
+    const response = await fetch(`${base}/api/explode-mid-stream`)
+    expect(response.status).toBe(200) // headers made it out before the explosion
+    await expect(response.text()).rejects.toThrow() // then the socket is torn down
+    expect(errors.length).toBe(1)
+    expect((await fetch(`${base}/`)).status).toBe(200)
+  })
+})
+
+describe('/api bridge', () => {
+  it('forwards method, headers, and body; relays status and body back', async () => {
+    const base = await boot()
+    const response = await fetch(`${base}/api/echo`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-probe': 'p1' },
+      body: JSON.stringify({ n: 1 }),
+    })
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({ method: 'POST', body: '{"n":1}', header: 'p1' })
+  })
+
+  it('relays a bodyless response', async () => {
+    const base = await boot()
+    const response = await fetch(`${base}/api/empty`, { method: 'POST' })
+    expect(response.status).toBe(204)
+    expect(await response.text()).toBe('')
+  })
+
+  it('streams SSE frames through chunk by chunk', async () => {
+    const base = await boot()
+    const response = await fetch(`${base}/api/sse`)
+    expect(response.headers.get('content-type')).toBe('text/event-stream')
+    expect(await response.text()).toBe('data: one\n\ndata: two\n\n')
+  })
+
+  it('waits for drain when a streamed chunk overfills the socket buffer', async () => {
+    // 4 MiB chunks dwarf the socket highWaterMark, so res.write returns false
+    // and the bridge parks on 'drain'; reading the body to completion proves
+    // the loop resumed instead of dropping the remainder.
+    const base = await boot()
+    const response = await fetch(`${base}/api/big`)
+    const body = new Uint8Array(await response.arrayBuffer())
+    expect(body.length).toBe(8 * 1024 * 1024)
+    expect(body[0]).toBe(65)
+    expect(body[body.length - 1]).toBe(65)
+  })
+
+  it('releases a drain wait when the client disconnects mid-chunk', async () => {
+    // The 'close' leg of the drain race: abort while the socket buffer is
+    // still full so the parked write wakes via 'close', not 'drain'.
+    const base = await boot()
+    const ac = new AbortController()
+    const response = await fetch(`${base}/api/big`, { signal: ac.signal })
+    const reader = response.body?.getReader()
+    const first = await reader?.read()
+    expect(first?.value?.length).toBeGreaterThan(0)
+    ac.abort()
+    // afterEach close() completing is the leak assertion, same as abort-probe.
+    await new Promise((resolve) => { setTimeout(resolve, 50) })
+  })
+
+  it('aborts the bridged request when the client disconnects mid-SSE', async () => {
+    const base = await boot()
+    const ac = new AbortController()
+    const response = await fetch(`${base}/api/abort-probe`, { signal: ac.signal })
+    const reader = response.body?.getReader()
+    expect(reader).toBeDefined()
+    const first = await reader?.read()
+    expect(new TextDecoder().decode(first?.value)).toContain('open')
+    ac.abort()
+    // server-side abort propagation has no client-observable handshake beyond
+    // the closed connection; close() would hang on a leaked live SSE socket,
+    // so afterEach completing IS the assertion that the bridge released it.
+    await new Promise((resolve) => { setTimeout(resolve, 50) })
+  })
+})
diff --git a/packages/host/webserver/tsconfig.json b/packages/host/webserver/tsconfig.json
new file mode 100644
index 0000000000..e1c893a8fc
--- /dev/null
+++ b/packages/host/webserver/tsconfig.json
@@ -0,0 +1,18 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/llm/llm-retry/tests/loader-composition.spec.ts b/packages/llm/llm-retry/tests/loader-composition.spec.ts
index c00175b20d..1aafc91d92 100644
--- a/packages/llm/llm-retry/tests/loader-composition.spec.ts
+++ b/packages/llm/llm-retry/tests/loader-composition.spec.ts
@@ -84,7 +84,10 @@ async function loadYaml(lines: readonly string[]): Promise<Context> {
 }
 
 describe('real Loader composition', () => {
-  it('loads the flat policy and records recovery through the shipping loop', async () => {
+  // Real-Loader composition resolves workspace packages through tsx at test
+  // time; first resolution after the host/client program split is slow enough
+  // to trip the default 5s budget on cold caches.
+  it('loads the flat policy and records recovery through the shipping loop', { timeout: 60_000 }, async () => {
     const loaded = await loadYaml([
       "- name: '@deepseek-ai/dsh-llm'",
       "- name: '@deepseek-ai/dsh-session'",
diff --git a/packages/llm/llm/package.json b/packages/llm/llm/package.json
index 9ef3e3323e..cc13bc183e 100644
--- a/packages/llm/llm/package.json
+++ b/packages/llm/llm/package.json
@@ -15,12 +15,21 @@
       "types": "./lib/types/invariant.d.ts",
       "default": "./lib/invariant.js"
     },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./brand": {
+      "types": "./lib/types/brand.d.ts",
+      "default": "./lib/types/brand.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
     "lib/invariant.js",
+    "lib/types/**/*.js",
     "lib/types/**/*.d.ts",
     "lib/types/**/*.d.ts.map",
     "src"
diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts
index fc4f92dfad..4ea35a782f 100644
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -102,10 +102,10 @@ async function tick(): Promise<void> {
 async function setup(options: TuiHarnessOptions = {}) {
   const terminal = new FakeTerminal()
   const exit = vi.fn()
-  const result = await createTuiTestHarness(terminal, exit, {
-    ...options,
-    cwd: options.cwd === undefined ? process.cwd() : options.cwd,
-  })
+  // Let the harness default cwd ('/workspace') stand: a checkout-dependent
+  // process.cwd() longer than the 88-column fake terminal pushes the footer
+  // token counters off-screen and fails their assertions by location.
+  const result = await createTuiTestHarness(terminal, exit, options)
   await tick()
   return result
 }
diff --git a/packages/ui/user-approval/package.json b/packages/ui/user-approval/package.json
index 098a0cc44b..0cc005cfa1 100644
--- a/packages/ui/user-approval/package.json
+++ b/packages/ui/user-approval/package.json
@@ -15,12 +15,17 @@
       "types": "./lib/types/invariant.d.ts",
       "default": "./lib/invariant.js"
     },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
     "lib/invariant.js",
+    "lib/types/**/*.js",
     "lib/types/**/*.d.ts",
     "lib/types/**/*.d.ts.map",
     "src"
diff --git a/packages/ui/user-approval/src/index.ts b/packages/ui/user-approval/src/index.ts
index 69a243a854..329fad33a7 100644
--- a/packages/ui/user-approval/src/index.ts
+++ b/packages/ui/user-approval/src/index.ts
@@ -7,7 +7,6 @@
 import { randomUUID } from 'node:crypto'
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
-import type { Branded } from '@deepseek-ai/dsh-brand'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { CallId } from '@deepseek-ai/dsh-llm'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
@@ -69,26 +68,11 @@ declare module '@deepseek-ai/dsh-session' {
   }
 }
 
-/**
- * Pairs one `approval/asked` audit event with its `approval/decided`.
- * Service-issued (one fresh id per {@link ApprovalService.request} call).
- */
-export type ApprovalRequestId = Branded<'ApprovalRequestId'>
+import { ApprovalRequestId } from './types.ts'
+import type { ApprovalOutcome } from './types.ts'
 
-/**
- * Brand a string as an {@link ApprovalRequestId}.
- * @param id - the raw id string to brand.
- * @returns the same string carrying the brand.
- */
-export function ApprovalRequestId(id: string): ApprovalRequestId {
-  return id as ApprovalRequestId
-}
-
-/**
- * Closed approval outcomes: a one-shot grant, explicit rejection, withdrawn
- * request, or unavailable answerer. Callers fail closed on `unavailable`.
- */
-export type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'
+export { ApprovalRequestId } from './types.ts'
+export type { ApprovalOutcome } from './types.ts'
 
 /** Every {@link ApprovalOutcome}, for runtime normalization of answerer returns. */
 const OUTCOMES: readonly ApprovalOutcome[] = ['allowed-once', 'rejected', 'cancelled', 'unavailable']
diff --git a/packages/ui/user-approval/src/types.ts b/packages/ui/user-approval/src/types.ts
new file mode 100644
index 0000000000..5a862ea546
--- /dev/null
+++ b/packages/ui/user-approval/src/types.ts
@@ -0,0 +1,29 @@
+/**
+ * Wire-safe approval identifiers and outcome vocabulary, free of
+ * cordis/service imports so browser type chains (apiproxy api → client) can
+ * consume them without loading this package's Context augmentation.
+ * @module @deepseek-ai/dsh-user-approval/types
+ */
+
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/**
+ * Pairs one `approval/asked` audit event with its `approval/decided`.
+ * Service-issued (one fresh id per {@link ApprovalService.request} call).
+ */
+export type ApprovalRequestId = Branded<'ApprovalRequestId'>
+
+/**
+ * Brand a string as an {@link ApprovalRequestId}.
+ * @param id - the raw id string to brand.
+ * @returns the same string carrying the brand.
+ */
+export function ApprovalRequestId(id: string): ApprovalRequestId {
+  return id as ApprovalRequestId
+}
+
+/**
+ * Closed approval outcomes: a one-shot grant, explicit rejection, withdrawn
+ * request, or unavailable answerer. Callers fail closed on `unavailable`.
+ */
+export type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'
diff --git a/packages/ui/user-approval/tsdown.config.ts b/packages/ui/user-approval/tsdown.config.ts
new file mode 100644
index 0000000000..5ebe27accb
--- /dev/null
+++ b/packages/ui/user-approval/tsdown.config.ts
@@ -0,0 +1,30 @@
+import { defineConfig } from 'tsdown'
+
+/**
+ * Build index and the invariant companion as separate single-entry bundles.
+ * Both entries import src/types.ts (the browser-safe subpath), so a
+ * multi-entry build emits a shared chunk the package's exact `files`
+ * whitelist omits; separate builds inline it.
+ */
+export default defineConfig([
+  {
+    entry: ['lib/types/index.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+  {
+    entry: ['lib/types/invariant.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+])
diff --git a/packages/ui/user-interaction/package.json b/packages/ui/user-interaction/package.json
index bcabc951df..07522d1d1a 100644
--- a/packages/ui/user-interaction/package.json
+++ b/packages/ui/user-interaction/package.json
@@ -15,12 +15,17 @@
       "types": "./lib/types/invariant.d.ts",
       "default": "./lib/invariant.js"
     },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
     "lib/invariant.js",
+    "lib/types/**/*.js",
     "lib/types/**/*.d.ts",
     "lib/types/**/*.d.ts.map",
     "src"
diff --git a/packages/ui/user-interaction/src/index.ts b/packages/ui/user-interaction/src/index.ts
index f9c1616ade..4b5caf6a55 100644
--- a/packages/ui/user-interaction/src/index.ts
+++ b/packages/ui/user-interaction/src/index.ts
@@ -17,27 +17,11 @@ declare module 'cordis' {
   }
 }
 
-/** One selectable answer offered to the user. */
-export interface AskUserQuestionOption {
-  /** User-facing label. */
-  label: string
-  /** Optional extra context rendered by capable UIs. */
-  description?: string
-}
+import type { AskUserQuestionAnswer, AskUserQuestionItem } from './types.ts'
 
-/** One question in an ask_user_question request. */
-export interface AskUserQuestionItem {
-  /** Stable model-provided question id, echoed in the answer. */
-  id: string
-  /** The question to display. */
-  question: string
-  /** Optional short heading/group label. */
-  header?: string
-  /** Optional choices the UI can render as a menu. */
-  options?: AskUserQuestionOption[]
-  /** Whether more than one option may be selected. Defaults to single-select. */
-  multiSelect?: boolean
-}
+export type {
+  AskUserQuestionAnswer, AskUserQuestionAnswerItem, AskUserQuestionItem, AskUserQuestionOption,
+} from './types.ts'
 
 /** Request for a human answer. */
 export interface AskUserQuestionRequest {
@@ -49,22 +33,6 @@ export interface AskUserQuestionRequest {
   signal?: AbortSignal
 }
 
-/** Answer to one question. */
-export interface AskUserQuestionAnswerItem {
-  /** The answered question id. */
-  id: string
-  /** Selected option labels. Empty when the answer is purely custom text. */
-  selected: string[]
-  /** Optional free-text "Other" answer. */
-  custom?: string
-}
-
-/** The human's answer. */
-export interface AskUserQuestionAnswer {
-  /** Structured answers keyed by question id. */
-  answers: AskUserQuestionAnswerItem[]
-}
-
 /** UI-side provider for user questions. */
 export interface UserInteractionProvider {
   ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
diff --git a/packages/ui/user-interaction/src/types.ts b/packages/ui/user-interaction/src/types.ts
new file mode 100644
index 0000000000..2ebb4503ce
--- /dev/null
+++ b/packages/ui/user-interaction/src/types.ts
@@ -0,0 +1,44 @@
+/**
+ * Wire-safe question/answer shapes, free of cordis/service imports so browser
+ * type chains (apiproxy api → client) can consume them without loading this
+ * package's Context augmentation.
+ * @module @deepseek-ai/dsh-user-interaction/types
+ */
+
+/** One selectable answer offered to the user. */
+export interface AskUserQuestionOption {
+  /** User-facing label. */
+  label: string
+  /** Optional extra context rendered by capable UIs. */
+  description?: string
+}
+
+/** One question in an ask_user_question request. */
+export interface AskUserQuestionItem {
+  /** Stable model-provided question id, echoed in the answer. */
+  id: string
+  /** The question to display. */
+  question: string
+  /** Optional short heading/group label. */
+  header?: string
+  /** Optional choices the UI can render as a menu. */
+  options?: AskUserQuestionOption[]
+  /** Whether more than one option may be selected. Defaults to single-select. */
+  multiSelect?: boolean
+}
+
+/** Answer to one question. */
+export interface AskUserQuestionAnswerItem {
+  /** The answered question id. */
+  id: string
+  /** Selected option labels. Empty when the answer is purely custom text. */
+  selected: string[]
+  /** Optional free-text "Other" answer. */
+  custom?: string
+}
+
+/** The human's answer. */
+export interface AskUserQuestionAnswer {
+  /** Structured answers keyed by question id. */
+  answers: AskUserQuestionAnswerItem[]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e4b786c053..bf971067c5 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -14,6 +14,12 @@ importers:
       '@stylistic/eslint-plugin':
         specifier: ^5.10.0
         version: 5.10.0(eslint@10.5.0(jiti@2.7.0))
+      '@testing-library/dom':
+        specifier: ^10.4.1
+        version: 10.4.1
+      '@testing-library/react':
+        specifier: ^16.3.2
+        version: 16.3.2(@testing-library/dom@10.4.1)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       '@types/js-yaml':
         specifier: ^4.0.9
         version: 4.0.9
@@ -53,6 +59,9 @@ importers:
       lefthook:
         specifier: ^2.1.9
         version: 2.1.9
+      lightningcss:
+        specifier: ^1.32.0
+        version: 1.32.0
       mdast-util-from-markdown:
         specifier: ^2.0.3
         version: 2.0.3
@@ -90,6 +99,79 @@ importers:
         specifier: ^4.1.8
         version: 4.1.8(@types/node@22.20.0)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@8.0.16(@types/node@22.20.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0))
 
+  apps/cli:
+    dependencies:
+      '@deepseek-ai/dsh-app-boot':
+        specifier: workspace:^
+        version: link:../../packages/ui/app-boot
+      '@deepseek-ai/dsh-frontend':
+        specifier: workspace:^
+        version: link:../web
+      '@deepseek-ai/dsh-host-apiproxy':
+        specifier: workspace:^
+        version: link:../../packages/host/apiproxy
+      '@deepseek-ai/dsh-host-runtime':
+        specifier: workspace:^
+        version: link:../../packages/host/runtime
+      '@deepseek-ai/dsh-host-webserver':
+        specifier: workspace:^
+        version: link:../../packages/host/webserver
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../packages/core/session
+
+  apps/web:
+    dependencies:
+      '@deepseek-ai/dsh-client-web':
+        specifier: workspace:^
+        version: link:../../packages/client/web
+      react:
+        specifier: ^18.2.0
+        version: 18.3.1
+      react-dom:
+        specifier: ^18.2.0
+        version: 18.3.1(react@18.3.1)
+    devDependencies:
+      '@deepseek-ai/dsh-client-runtime':
+        specifier: workspace:^
+        version: link:../../packages/client/runtime
+      '@deepseek-ai/dsh-client-ui-primitives':
+        specifier: workspace:^
+        version: link:../../packages/client/ui-primitives
+      '@deepseek-ai/dsh-client-ui-slots':
+        specifier: workspace:^
+        version: link:../../packages/client/ui-slots
+      '@deepseek-ai/dsh-client-web-react':
+        specifier: workspace:^
+        version: link:../../packages/client/web-react
+      '@deepseek-ai/dsh-host-webserver':
+        specifier: workspace:^
+        version: link:../../packages/host/webserver
+      '@types/node':
+        specifier: ^22.0.0
+        version: 22.20.0
+      '@types/react':
+        specifier: ~18.3.1
+        version: 18.3.31
+      '@types/react-dom':
+        specifier: ~18.3.0
+        version: 18.3.7(@types/react@18.3.31)
+      '@vitejs/plugin-react':
+        specifier: ^4.0.0
+        version: 4.7.0(vite@6.4.3(@types/node@22.20.0)(jiti@2.7.0)(lightningcss@1.32.0)(tsx@4.22.4)(yaml@2.9.0))
+      playwright:
+        specifier: ^1.49.0
+        version: 1.61.1
+      typescript:
+        specifier: ^6.0.3
+        version: 6.0.3
+      vite:
+        specifier: ^6.0.0
+        version: 6.4.3(@types/node@22.20.0)(jiti@2.7.0)(lightningcss@1.32.0)(tsx@4.22.4)(yaml@2.9.0)
+      vitest:
+        specifier: ^4.1.8
+        version: 4.1.8(@types/node@22.20.0)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@6.4.3(@types/node@22.20.0)(jiti@2.7.0)(lightningcss@1.32.0)(tsx@4.22.4)(yaml@2.9.0))
+
   examples:
     dependencies:
       '@cordisjs/plugin-hmr':
@@ -378,6 +460,307 @@ importers:
         specifier: ^4.0.0-rc.7
         version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
 
+  packages/client/connection:
+    dependencies:
+      '@deepseek-ai/dsh-host-apiproxy':
+        specifier: workspace:^
+        version: link:../../host/apiproxy
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+
+  packages/client/i18n:
+    dependencies:
+      '@deepseek-ai/dsh-client-web-react':
+        specifier: workspace:^
+        version: link:../web-react
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+
+  packages/client/runtime:
+    dependencies:
+      '@deepseek-ai/dsh-client-connection':
+        specifier: workspace:^
+        version: link:../connection
+      '@deepseek-ai/dsh-client-ui-slots':
+        specifier: workspace:^
+        version: link:../ui-slots
+      '@deepseek-ai/dsh-client-web-react':
+        specifier: workspace:^
+        version: link:../web-react
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      react:
+        specifier: ^18.2.0
+        version: 18.3.1
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@types/react':
+        specifier: ~18.3.1
+        version: 18.3.31
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+
+  packages/client/ui-conversation:
+    dependencies:
+      '@deepseek-ai/dsh-client-i18n':
+        specifier: workspace:^
+        version: link:../i18n
+      '@deepseek-ai/dsh-client-runtime':
+        specifier: workspace:^
+        version: link:../runtime
+      '@deepseek-ai/dsh-client-ui-layout':
+        specifier: workspace:^
+        version: link:../ui-layout
+      '@deepseek-ai/dsh-client-ui-primitives':
+        specifier: workspace:^
+        version: link:../ui-primitives
+      '@deepseek-ai/dsh-client-ui-slots':
+        specifier: workspace:^
+        version: link:../ui-slots
+      '@deepseek-ai/dsh-client-web-react':
+        specifier: workspace:^
+        version: link:../web-react
+      clsx:
+        specifier: ^2.0.0
+        version: 2.1.1
+      react:
+        specifier: ^18.2.0
+        version: 18.3.1
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@types/react':
+        specifier: ~18.3.1
+        version: 18.3.31
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+
+  packages/client/ui-layout:
+    dependencies:
+      '@deepseek-ai/dsh-client-runtime':
+        specifier: workspace:^
+        version: link:../runtime
+      '@deepseek-ai/dsh-client-ui-slots':
+        specifier: workspace:^
+        version: link:../ui-slots
+      '@deepseek-ai/dsh-client-web-react':
+        specifier: workspace:^
+        version: link:../web-react
+      react:
+        specifier: ^18.2.0
+        version: 18.3.1
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@types/react':
+        specifier: ~18.3.1
+        version: 18.3.31
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+
+  packages/client/ui-primitives:
+    dependencies:
+      clsx:
+        specifier: ^2.0.0
+        version: 2.1.1
+      react:
+        specifier: ^18.2.0
+        version: 18.3.1
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@types/react':
+        specifier: ~18.3.1
+        version: 18.3.31
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+
+  packages/client/ui-sidebar:
+    dependencies:
+      '@deepseek-ai/dsh-client-runtime':
+        specifier: workspace:^
+        version: link:../runtime
+      '@deepseek-ai/dsh-client-ui-layout':
+        specifier: workspace:^
+        version: link:../ui-layout
+      '@deepseek-ai/dsh-client-ui-primitives':
+        specifier: workspace:^
+        version: link:../ui-primitives
+      '@deepseek-ai/dsh-client-ui-slots':
+        specifier: workspace:^
+        version: link:../ui-slots
+      '@deepseek-ai/dsh-client-web-react':
+        specifier: workspace:^
+        version: link:../web-react
+      clsx:
+        specifier: ^2.0.0
+        version: 2.1.1
+      react:
+        specifier: ^18.2.0
+        version: 18.3.1
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@types/react':
+        specifier: ~18.3.1
+        version: 18.3.31
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+
+  packages/client/ui-slots:
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@types/react':
+        specifier: ~18.3.1
+        version: 18.3.31
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+
+  packages/client/ui-theme:
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+
+  packages/client/ui-trajectory:
+    dependencies:
+      '@deepseek-ai/dsh-client-ui-conversation':
+        specifier: workspace:^
+        version: link:../ui-conversation
+      '@deepseek-ai/dsh-client-web-react':
+        specifier: workspace:^
+        version: link:../web-react
+      react:
+        specifier: ^18.2.0
+        version: 18.3.1
+    devDependencies:
+      '@deepseek-ai/dsh-client-runtime':
+        specifier: workspace:^
+        version: link:../runtime
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@types/react':
+        specifier: ~18.3.1
+        version: 18.3.31
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+
+  packages/client/web:
+    dependencies:
+      '@deepseek-ai/dsh-client-connection':
+        specifier: workspace:^
+        version: link:../connection
+      '@deepseek-ai/dsh-client-runtime':
+        specifier: workspace:^
+        version: link:../runtime
+      '@deepseek-ai/dsh-client-ui-primitives':
+        specifier: workspace:^
+        version: link:../ui-primitives
+      '@deepseek-ai/dsh-client-ui-slots':
+        specifier: workspace:^
+        version: link:../ui-slots
+      '@deepseek-ai/dsh-client-ui-theme':
+        specifier: workspace:^
+        version: link:../ui-theme
+      '@deepseek-ai/dsh-client-web-react':
+        specifier: workspace:^
+        version: link:../web-react
+      react:
+        specifier: ^18.2.0
+        version: 18.3.1
+      react-dom:
+        specifier: ^18.2.0
+        version: 18.3.1(react@18.3.1)
+    devDependencies:
+      '@deepseek-ai/dsh-client-ui-layout':
+        specifier: workspace:^
+        version: link:../ui-layout
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@types/react':
+        specifier: ~18.3.1
+        version: 18.3.31
+      '@types/react-dom':
+        specifier: ~18.3.0
+        version: 18.3.7(@types/react@18.3.31)
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+      typescript:
+        specifier: ^6.0.3
+        version: 6.0.3
+
+  packages/client/web-react:
+    dependencies:
+      '@deepseek-ai/dsh-client-ui-slots':
+        specifier: workspace:^
+        version: link:../ui-slots
+      immer:
+        specifier: ^10.1.1
+        version: 10.2.0
+      react:
+        specifier: ^18.2.0
+        version: 18.3.1
+      use-sync-external-store:
+        specifier: 1.2.0
+        version: 1.2.0(react@18.3.1)
+      zustand:
+        specifier: ~4.4.7
+        version: 4.4.7(@types/react@18.3.31)(immer@10.2.0)(react@18.3.1)
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@types/react':
+        specifier: ~18.3.1
+        version: 18.3.31
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+
   packages/code-runtime/code-runtime:
     devDependencies:
       '@deepseek-ai/dsh-invariants':
@@ -1453,6 +1836,185 @@ importers:
         specifier: ^4.0.0-rc.7
         version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
 
+  packages/host/apiproxy:
+    dependencies:
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+      '@deepseek-ai/dsh-user-approval':
+        specifier: workspace:^
+        version: link:../../ui/user-approval
+      '@deepseek-ai/dsh-user-interaction':
+        specifier: workspace:^
+        version: link:../../ui/user-interaction
+      zod:
+        specifier: ^4.4.3
+        version: 4.4.3
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+
+  packages/host/runtime:
+    dependencies:
+      '@cordisjs/plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
+      '@cordisjs/plugin-timer':
+        specifier: workspace:^
+        version: link:../../../vendor/timer
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-agent-loop':
+        specifier: workspace:^
+        version: link:../../core/agent-loop
+      '@deepseek-ai/dsh-bash-local':
+        specifier: workspace:^
+        version: link:../../bash/bash-local
+      '@deepseek-ai/dsh-client-connection':
+        specifier: workspace:^
+        version: link:../../client/connection
+      '@deepseek-ai/dsh-client-i18n':
+        specifier: workspace:^
+        version: link:../../client/i18n
+      '@deepseek-ai/dsh-client-runtime':
+        specifier: workspace:^
+        version: link:../../client/runtime
+      '@deepseek-ai/dsh-client-ui-conversation':
+        specifier: workspace:^
+        version: link:../../client/ui-conversation
+      '@deepseek-ai/dsh-client-ui-layout':
+        specifier: workspace:^
+        version: link:../../client/ui-layout
+      '@deepseek-ai/dsh-client-ui-sidebar':
+        specifier: workspace:^
+        version: link:../../client/ui-sidebar
+      '@deepseek-ai/dsh-client-ui-theme':
+        specifier: workspace:^
+        version: link:../../client/ui-theme
+      '@deepseek-ai/dsh-client-ui-trajectory':
+        specifier: workspace:^
+        version: link:../../client/ui-trajectory
+      '@deepseek-ai/dsh-compact-basic':
+        specifier: workspace:^
+        version: link:../../compact/compact-basic
+      '@deepseek-ai/dsh-fs-local':
+        specifier: workspace:^
+        version: link:../../fs/fs-local
+      '@deepseek-ai/dsh-fs-policy':
+        specifier: workspace:^
+        version: link:../../fs/fs-policy
+      '@deepseek-ai/dsh-host-apiproxy':
+        specifier: workspace:^
+        version: link:../apiproxy
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-llm-deepseek':
+        specifier: workspace:^
+        version: link:../../llm/llm-deepseek
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-session-persistence':
+        specifier: workspace:^
+        version: link:../../session-persistence/session-persistence
+      '@deepseek-ai/dsh-session-persistence-jsonl':
+        specifier: workspace:^
+        version: link:../../session-persistence/session-persistence-jsonl
+      '@deepseek-ai/dsh-skill':
+        specifier: workspace:^
+        version: link:../../skill/skill
+      '@deepseek-ai/dsh-skill-local':
+        specifier: workspace:^
+        version: link:../../skill/skill-local
+      '@deepseek-ai/dsh-spill-local':
+        specifier: workspace:^
+        version: link:../../spill/spill-local
+      '@deepseek-ai/dsh-spill-policy':
+        specifier: workspace:^
+        version: link:../../spill/spill-policy
+      '@deepseek-ai/dsh-subagent':
+        specifier: workspace:^
+        version: link:../../subagent/subagent
+      '@deepseek-ai/dsh-subagent-fork':
+        specifier: workspace:^
+        version: link:../../subagent/subagent-fork
+      '@deepseek-ai/dsh-subagent-spawn':
+        specifier: workspace:^
+        version: link:../../subagent/subagent-spawn
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../../core/system-prompt
+      '@deepseek-ai/dsh-tasks':
+        specifier: workspace:^
+        version: link:../../tasks/tasks
+      '@deepseek-ai/dsh-timeout-policy':
+        specifier: workspace:^
+        version: link:../../timeout/timeout-policy
+      '@deepseek-ai/dsh-token-meter':
+        specifier: workspace:^
+        version: link:../../llm/token-meter
+      '@deepseek-ai/dsh-tool-bash':
+        specifier: workspace:^
+        version: link:../../bash/tool-bash
+      '@deepseek-ai/dsh-tool-fs':
+        specifier: workspace:^
+        version: link:../../fs/tool-fs
+      '@deepseek-ai/dsh-tool-fs-search':
+        specifier: workspace:^
+        version: link:../../fs/tool-fs-search
+      '@deepseek-ai/dsh-tool-skill':
+        specifier: workspace:^
+        version: link:../../skill/tool-skill
+      '@deepseek-ai/dsh-tool-subagent':
+        specifier: workspace:^
+        version: link:../../subagent/tool-subagent
+      '@deepseek-ai/dsh-tool-tasks':
+        specifier: workspace:^
+        version: link:../../tasks/tool-tasks
+      '@deepseek-ai/dsh-tool-todo':
+        specifier: workspace:^
+        version: link:../../todo/tool-todo
+      '@deepseek-ai/dsh-tool-workflow':
+        specifier: workspace:^
+        version: link:../../workflow/tool-workflow
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+      '@deepseek-ai/dsh-workflow-workerthread':
+        specifier: workspace:^
+        version: link:../../workflow/workflow-workerthread
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@vendor+loader)
+
+  packages/host/webserver:
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+
   packages/llm/llm:
     devDependencies:
       '@deepseek-ai/dsh-brand':
@@ -3646,10 +4208,10 @@ importers:
         version: 5.4.21(@types/node@25.9.3)(lightningcss@1.32.0)
       vitepress:
         specifier: ^1.6.4
-        version: 1.6.4(@algolia/client-search@5.55.2)(@types/node@25.9.3)(lightningcss@1.32.0)(postcss@8.5.15)(search-insights@2.17.3)(typescript@6.0.3)
+        version: 1.6.4(@algolia/client-search@5.55.2)(@types/node@25.9.3)(@types/react@18.3.31)(lightningcss@1.32.0)(postcss@8.5.15)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(search-insights@2.17.3)(typescript@6.0.3)
       vitepress-plugin-mermaid:
         specifier: ^2.0.17
-        version: 2.0.17(mermaid@11.16.0)(vitepress@1.6.4(@algolia/client-search@5.55.2)(@types/node@25.9.3)(lightningcss@1.32.0)(postcss@8.5.15)(search-insights@2.17.3)(typescript@6.0.3))
+        version: 2.0.17(mermaid@11.16.0)(vitepress@1.6.4(@algolia/client-search@5.55.2)(@types/node@25.9.3)(@types/react@18.3.31)(lightningcss@1.32.0)(postcss@8.5.15)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(search-insights@2.17.3)(typescript@6.0.3))
 
 packages:
 
@@ -3866,10 +4428,44 @@ packages:
     resolution: {integrity: sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw==}
     engines: {node: '>=6.9.0'}
 
+  '@babel/compat-data@7.29.7':
+    resolution: {integrity: sha512-locTkQyKvwIEgBzVrn8693ebc97F2U8ZHjbXwDXJ5Fn2TCpNwTlKcaKLkdHop5c/icOFE7qt7Q9JC5hnKNa6Gg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/core@7.29.7':
+    resolution: {integrity: sha512-RgHBCvtjbOK2gXSNBNIkNoEc9qoVEtau3hj8gEqKQuL3HZAibKarWFEI3Lfm6EYKkLalOh8eSrj9b+ch9H/VBA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/generator@7.29.7':
+    resolution: {integrity: sha512-DkXD5OJQaAQIdZ1bt3UZdEnHAn9Imd3IVBdX03UFe+ony9Ojw5pzr9YVKGDY1jt+Gcn/FnGkNf8r+Vj5NOJWtQ==}
+    engines: {node: '>=6.9.0'}
+
   '@babel/generator@8.0.0-rc.6':
     resolution: {integrity: sha512-6mIzgVK8DgEzvIapoQwhXTMnnkuE4STQmVv9H03i/tZ2ml8oev3TRvZJgTenK2Bsq0YWNtzOrFdTyNzCMFtjJQ==}
     engines: {node: ^22.18.0 || >=24.11.0}
 
+  '@babel/helper-compilation-targets@7.29.7':
+    resolution: {integrity: sha512-wem6WaBj4NaVYVdNhLPPVacES6ZJ+KBBfSkTMD3YZxbP3rm3Di85tJU5ljaUNhaOynt+Aj0xruhYuzQBt8n71g==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-globals@7.29.7':
+    resolution: {integrity: sha512-3nQVUAtvkKH9zahfWgw96Jc/uFOmjACE1kQz82E2lqWmHBgjzbNlsC22nuQTfahmWeQtTq5nQ/4Nnd2A1wj4zA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-module-imports@7.29.7':
+    resolution: {integrity: sha512-ejHwrQQYcm9xnTivShn2IDOlIzInN34AXskvq9QicvCtEzq1Vzclu/tKF8Jq1Cg8JG2GL6/EmjgsCT7lXepE3g==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-module-transforms@7.29.7':
+    resolution: {integrity: sha512-UPUVSyXbOh627KiCIGQSgwWzGeBKLkaJ9PJEdrngIwMSzxLR4jS4+f1f1jb7VzBbg8nFLaYotvVPFCTqdrmTAg==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0
+
+  '@babel/helper-plugin-utils@7.29.7':
+    resolution: {integrity: sha512-G7sHYigPY17oO5SYWnfD/0MTBwVR781S/JI643e/JhUYgVgWE/61SoW3NH9KWUKyKq5LVh3npif99Wkt6j86Jw==}
+    engines: {node: '>=6.9.0'}
+
   '@babel/helper-string-parser@7.29.7':
     resolution: {integrity: sha512-Pb5ijPrZ89GDH8223L4UP8i6QApWxs04RbPQJTeWDV0/keR2E36MeKnyr6LYmUUvqRRI+Iv87SuF1W6ErINzYw==}
     engines: {node: '>=6.9.0'}
@@ -3886,6 +4482,14 @@ packages:
     resolution: {integrity: sha512-nVJ+1JcCgntv8d78rRo++o2wuODT0Irknx2BF8Np4Ft2CRgjLqIs4qzSZ8b66yGbBdMWGmZBO9WEZv1hhNiSpg==}
     engines: {node: ^22.18.0 || >=24.11.0}
 
+  '@babel/helper-validator-option@7.29.7':
+    resolution: {integrity: sha512-N9ZErrD+yW5geCDtBqnOoxmR8+tNKiGuxKlDpuJxfsqpa2dFcexaziGAE/qoHLiDDreVNMupxGmSoNlyvsA3gw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helpers@7.29.7':
+    resolution: {integrity: sha512-1k2lAGRMfHTcwuNYcCNUmaUffmQv8KWMfh2iJUUeRlwlwH4FdNG7mfPI10NPfLHJFThE4Tyr4mv7kTNZOiPuBg==}
+    engines: {node: '>=6.9.0'}
+
   '@babel/parser@7.29.7':
     resolution: {integrity: sha512-hnORnjP/1P/zFEndoeX+n+t1RwWRJiJpM/jO7FW32Kn9r5+sJB2JWOdYo4L6k78j15eCwY3Gm/7364B1EMwtNg==}
     engines: {node: '>=6.0.0'}
@@ -3896,10 +4500,30 @@ packages:
     engines: {node: ^22.18.0 || >=24.11.0}
     hasBin: true
 
+  '@babel/plugin-transform-react-jsx-self@7.29.7':
+    resolution: {integrity: sha512-TL0hMc9xzy86VD31nUiwzd5otRAcyEPcsegCxolO0PvcXuH1v0kECe/UIznYFihpkvU5wg/jk4v0TTEFfm53fw==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-transform-react-jsx-source@7.29.7':
+    resolution: {integrity: sha512-06IyK09H3wi4cGbhDBwp5gUGo0IKtnYa8tyTiephirPCK6fbobVGiXMMI5zLQ4aKEYP3wZ3ArU44o+8KMrSG/Q==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
   '@babel/runtime@7.29.7':
     resolution: {integrity: sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw==}
     engines: {node: '>=6.9.0'}
 
+  '@babel/template@7.29.7':
+    resolution: {integrity: sha512-puq+Gf35oI24FeN11LkoUQFqv9uwNeWpxXZi/Ji3rRIoKAzKnxRaZ+Gkj0vKS9ZCiTESfng1N9LyOyXvo+m+Gg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/traverse@7.29.7':
+    resolution: {integrity: sha512-EhlfNQtZ+NK22w5BM61ciuiq1m58ed33Wr1Xan//ZRTy6hgjnwyCffRYwzsGXdASJSUJ1guZILsErh1eQcl+zw==}
+    engines: {node: '>=6.9.0'}
+
   '@babel/types@7.29.7':
     resolution: {integrity: sha512-4zBIxpPzowiZpusoFkyGVwakdRJUyuH5PxQ/PrqghfdFWWasvnCdPfQXHrenDai+gyLARulZjZowCOj6fjT4pA==}
     engines: {node: '>=6.9.0'}
@@ -4045,6 +4669,12 @@ packages:
     cpu: [ppc64]
     os: [aix]
 
+  '@esbuild/aix-ppc64@0.25.12':
+    resolution: {integrity: sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
   '@esbuild/aix-ppc64@0.28.1':
     resolution: {integrity: sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ==}
     engines: {node: '>=18'}
@@ -4057,6 +4687,12 @@ packages:
     cpu: [arm64]
     os: [android]
 
+  '@esbuild/android-arm64@0.25.12':
+    resolution: {integrity: sha512-6AAmLG7zwD1Z159jCKPvAxZd4y/VTO0VkprYy+3N2FtJ8+BQWFXU+OxARIwA46c5tdD9SsKGZ/1ocqBS/gAKHg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
   '@esbuild/android-arm64@0.28.1':
     resolution: {integrity: sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg==}
     engines: {node: '>=18'}
@@ -4069,6 +4705,12 @@ packages:
     cpu: [arm]
     os: [android]
 
+  '@esbuild/android-arm@0.25.12':
+    resolution: {integrity: sha512-VJ+sKvNA/GE7Ccacc9Cha7bpS8nyzVv0jdVgwNDaR4gDMC/2TTRc33Ip8qrNYUcpkOHUT5OZ0bUcNNVZQ9RLlg==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
   '@esbuild/android-arm@0.28.1':
     resolution: {integrity: sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ==}
     engines: {node: '>=18'}
@@ -4081,6 +4723,12 @@ packages:
     cpu: [x64]
     os: [android]
 
+  '@esbuild/android-x64@0.25.12':
+    resolution: {integrity: sha512-5jbb+2hhDHx5phYR2By8GTWEzn6I9UqR11Kwf22iKbNpYrsmRB18aX/9ivc5cabcUiAT/wM+YIZ6SG9QO6a8kg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
   '@esbuild/android-x64@0.28.1':
     resolution: {integrity: sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng==}
     engines: {node: '>=18'}
@@ -4093,6 +4741,12 @@ packages:
     cpu: [arm64]
     os: [darwin]
 
+  '@esbuild/darwin-arm64@0.25.12':
+    resolution: {integrity: sha512-N3zl+lxHCifgIlcMUP5016ESkeQjLj/959RxxNYIthIg+CQHInujFuXeWbWMgnTo4cp5XVHqFPmpyu9J65C1Yg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
   '@esbuild/darwin-arm64@0.28.1':
     resolution: {integrity: sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q==}
     engines: {node: '>=18'}
@@ -4105,6 +4759,12 @@ packages:
     cpu: [x64]
     os: [darwin]
 
+  '@esbuild/darwin-x64@0.25.12':
+    resolution: {integrity: sha512-HQ9ka4Kx21qHXwtlTUVbKJOAnmG1ipXhdWTmNXiPzPfWKpXqASVcWdnf2bnL73wgjNrFXAa3yYvBSd9pzfEIpA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
   '@esbuild/darwin-x64@0.28.1':
     resolution: {integrity: sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ==}
     engines: {node: '>=18'}
@@ -4117,6 +4777,12 @@ packages:
     cpu: [arm64]
     os: [freebsd]
 
+  '@esbuild/freebsd-arm64@0.25.12':
+    resolution: {integrity: sha512-gA0Bx759+7Jve03K1S0vkOu5Lg/85dou3EseOGUes8flVOGxbhDDh/iZaoek11Y8mtyKPGF3vP8XhnkDEAmzeg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
   '@esbuild/freebsd-arm64@0.28.1':
     resolution: {integrity: sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw==}
     engines: {node: '>=18'}
@@ -4129,6 +4795,12 @@ packages:
     cpu: [x64]
     os: [freebsd]
 
+  '@esbuild/freebsd-x64@0.25.12':
+    resolution: {integrity: sha512-TGbO26Yw2xsHzxtbVFGEXBFH0FRAP7gtcPE7P5yP7wGy7cXK2oO7RyOhL5NLiqTlBh47XhmIUXuGciXEqYFfBQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
   '@esbuild/freebsd-x64@0.28.1':
     resolution: {integrity: sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ==}
     engines: {node: '>=18'}
@@ -4141,6 +4813,12 @@ packages:
     cpu: [arm64]
     os: [linux]
 
+  '@esbuild/linux-arm64@0.25.12':
+    resolution: {integrity: sha512-8bwX7a8FghIgrupcxb4aUmYDLp8pX06rGh5HqDT7bB+8Rdells6mHvrFHHW2JAOPZUbnjUpKTLg6ECyzvas2AQ==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
   '@esbuild/linux-arm64@0.28.1':
     resolution: {integrity: sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g==}
     engines: {node: '>=18'}
@@ -4153,6 +4831,12 @@ packages:
     cpu: [arm]
     os: [linux]
 
+  '@esbuild/linux-arm@0.25.12':
+    resolution: {integrity: sha512-lPDGyC1JPDou8kGcywY0YILzWlhhnRjdof3UlcoqYmS9El818LLfJJc3PXXgZHrHCAKs/Z2SeZtDJr5MrkxtOw==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
   '@esbuild/linux-arm@0.28.1':
     resolution: {integrity: sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ==}
     engines: {node: '>=18'}
@@ -4165,6 +4849,12 @@ packages:
     cpu: [ia32]
     os: [linux]
 
+  '@esbuild/linux-ia32@0.25.12':
+    resolution: {integrity: sha512-0y9KrdVnbMM2/vG8KfU0byhUN+EFCny9+8g202gYqSSVMonbsCfLjUO+rCci7pM0WBEtz+oK/PIwHkzxkyharA==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
   '@esbuild/linux-ia32@0.28.1':
     resolution: {integrity: sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w==}
     engines: {node: '>=18'}
@@ -4177,6 +4867,12 @@ packages:
     cpu: [loong64]
     os: [linux]
 
+  '@esbuild/linux-loong64@0.25.12':
+    resolution: {integrity: sha512-h///Lr5a9rib/v1GGqXVGzjL4TMvVTv+s1DPoxQdz7l/AYv6LDSxdIwzxkrPW438oUXiDtwM10o9PmwS/6Z0Ng==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
   '@esbuild/linux-loong64@0.28.1':
     resolution: {integrity: sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg==}
     engines: {node: '>=18'}
@@ -4189,6 +4885,12 @@ packages:
     cpu: [mips64el]
     os: [linux]
 
+  '@esbuild/linux-mips64el@0.25.12':
+    resolution: {integrity: sha512-iyRrM1Pzy9GFMDLsXn1iHUm18nhKnNMWscjmp4+hpafcZjrr2WbT//d20xaGljXDBYHqRcl8HnxbX6uaA/eGVw==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
   '@esbuild/linux-mips64el@0.28.1':
     resolution: {integrity: sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ==}
     engines: {node: '>=18'}
@@ -4201,6 +4903,12 @@ packages:
     cpu: [ppc64]
     os: [linux]
 
+  '@esbuild/linux-ppc64@0.25.12':
+    resolution: {integrity: sha512-9meM/lRXxMi5PSUqEXRCtVjEZBGwB7P/D4yT8UG/mwIdze2aV4Vo6U5gD3+RsoHXKkHCfSxZKzmDssVlRj1QQA==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
   '@esbuild/linux-ppc64@0.28.1':
     resolution: {integrity: sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ==}
     engines: {node: '>=18'}
@@ -4213,6 +4921,12 @@ packages:
     cpu: [riscv64]
     os: [linux]
 
+  '@esbuild/linux-riscv64@0.25.12':
+    resolution: {integrity: sha512-Zr7KR4hgKUpWAwb1f3o5ygT04MzqVrGEGXGLnj15YQDJErYu/BGg+wmFlIDOdJp0PmB0lLvxFIOXZgFRrdjR0w==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
   '@esbuild/linux-riscv64@0.28.1':
     resolution: {integrity: sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ==}
     engines: {node: '>=18'}
@@ -4225,6 +4939,12 @@ packages:
     cpu: [s390x]
     os: [linux]
 
+  '@esbuild/linux-s390x@0.25.12':
+    resolution: {integrity: sha512-MsKncOcgTNvdtiISc/jZs/Zf8d0cl/t3gYWX8J9ubBnVOwlk65UIEEvgBORTiljloIWnBzLs4qhzPkJcitIzIg==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
   '@esbuild/linux-s390x@0.28.1':
     resolution: {integrity: sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag==}
     engines: {node: '>=18'}
@@ -4237,12 +4957,24 @@ packages:
     cpu: [x64]
     os: [linux]
 
+  '@esbuild/linux-x64@0.25.12':
+    resolution: {integrity: sha512-uqZMTLr/zR/ed4jIGnwSLkaHmPjOjJvnm6TVVitAa08SLS9Z0VM8wIRx7gWbJB5/J54YuIMInDquWyYvQLZkgw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
   '@esbuild/linux-x64@0.28.1':
     resolution: {integrity: sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA==}
     engines: {node: '>=18'}
     cpu: [x64]
     os: [linux]
 
+  '@esbuild/netbsd-arm64@0.25.12':
+    resolution: {integrity: sha512-xXwcTq4GhRM7J9A8Gv5boanHhRa/Q9KLVmcyXHCTaM4wKfIpWkdXiMog/KsnxzJ0A1+nD+zoecuzqPmCRyBGjg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
   '@esbuild/netbsd-arm64@0.28.1':
     resolution: {integrity: sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw==}
     engines: {node: '>=18'}
@@ -4255,12 +4987,24 @@ packages:
     cpu: [x64]
     os: [netbsd]
 
+  '@esbuild/netbsd-x64@0.25.12':
+    resolution: {integrity: sha512-Ld5pTlzPy3YwGec4OuHh1aCVCRvOXdH8DgRjfDy/oumVovmuSzWfnSJg+VtakB9Cm0gxNO9BzWkj6mtO1FMXkQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
   '@esbuild/netbsd-x64@0.28.1':
     resolution: {integrity: sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg==}
     engines: {node: '>=18'}
     cpu: [x64]
     os: [netbsd]
 
+  '@esbuild/openbsd-arm64@0.25.12':
+    resolution: {integrity: sha512-fF96T6KsBo/pkQI950FARU9apGNTSlZGsv1jZBAlcLL1MLjLNIWPBkj5NlSz8aAzYKg+eNqknrUJ24QBybeR5A==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
   '@esbuild/openbsd-arm64@0.28.1':
     resolution: {integrity: sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q==}
     engines: {node: '>=18'}
@@ -4273,12 +5017,24 @@ packages:
     cpu: [x64]
     os: [openbsd]
 
+  '@esbuild/openbsd-x64@0.25.12':
+    resolution: {integrity: sha512-MZyXUkZHjQxUvzK7rN8DJ3SRmrVrke8ZyRusHlP+kuwqTcfWLyqMOE3sScPPyeIXN/mDJIfGXvcMqCgYKekoQw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
   '@esbuild/openbsd-x64@0.28.1':
     resolution: {integrity: sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw==}
     engines: {node: '>=18'}
     cpu: [x64]
     os: [openbsd]
 
+  '@esbuild/openharmony-arm64@0.25.12':
+    resolution: {integrity: sha512-rm0YWsqUSRrjncSXGA7Zv78Nbnw4XL6/dzr20cyrQf7ZmRcsovpcRBdhD43Nuk3y7XIoW2OxMVvwuRvk9XdASg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
   '@esbuild/openharmony-arm64@0.28.1':
     resolution: {integrity: sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg==}
     engines: {node: '>=18'}
@@ -4291,6 +5047,12 @@ packages:
     cpu: [x64]
     os: [sunos]
 
+  '@esbuild/sunos-x64@0.25.12':
+    resolution: {integrity: sha512-3wGSCDyuTHQUzt0nV7bocDy72r2lI33QL3gkDNGkod22EsYl04sMf0qLb8luNKTOmgF/eDEDP5BFNwoBKH441w==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
   '@esbuild/sunos-x64@0.28.1':
     resolution: {integrity: sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ==}
     engines: {node: '>=18'}
@@ -4303,6 +5065,12 @@ packages:
     cpu: [arm64]
     os: [win32]
 
+  '@esbuild/win32-arm64@0.25.12':
+    resolution: {integrity: sha512-rMmLrur64A7+DKlnSuwqUdRKyd3UE7oPJZmnljqEptesKM8wx9J8gx5u0+9Pq0fQQW8vqeKebwNXdfOyP+8Bsg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
   '@esbuild/win32-arm64@0.28.1':
     resolution: {integrity: sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA==}
     engines: {node: '>=18'}
@@ -4315,6 +5083,12 @@ packages:
     cpu: [ia32]
     os: [win32]
 
+  '@esbuild/win32-ia32@0.25.12':
+    resolution: {integrity: sha512-HkqnmmBoCbCwxUKKNPBixiWDGCpQGVsrQfJoVGYLPT41XWF8lHuE5N6WhVia2n4o5QK5M4tYr21827fNhi4byQ==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
   '@esbuild/win32-ia32@0.28.1':
     resolution: {integrity: sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg==}
     engines: {node: '>=18'}
@@ -4327,6 +5101,12 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@esbuild/win32-x64@0.25.12':
+    resolution: {integrity: sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
   '@esbuild/win32-x64@0.28.1':
     resolution: {integrity: sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A==}
     engines: {node: '>=18'}
@@ -4423,6 +5203,9 @@ packages:
   '@jridgewell/gen-mapping@0.3.13':
     resolution: {integrity: sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==}
 
+  '@jridgewell/remapping@2.3.5':
+    resolution: {integrity: sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ==}
+
   '@jridgewell/resolve-uri@3.1.2':
     resolution: {integrity: sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==}
     engines: {node: '>=6.0.0'}
@@ -5008,6 +5791,9 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@rolldown/pluginutils@1.0.0-beta.27':
+    resolution: {integrity: sha512-+d0F4MKMCbeVUJwG96uQ4SgAznZNSq93I3V+9NHA4OpvqG8mRCpGdKmK8l/dl02h2CCDHwW2FqilnTyDcAnqjA==}
+
   '@rolldown/pluginutils@1.0.1':
     resolution: {integrity: sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==}
 
@@ -5222,12 +6008,46 @@ packages:
     peerDependencies:
       eslint: ^9.0.0 || ^10.0.0
 
+  '@testing-library/dom@10.4.1':
+    resolution: {integrity: sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg==}
+    engines: {node: '>=18'}
+
+  '@testing-library/react@16.3.2':
+    resolution: {integrity: sha512-XU5/SytQM+ykqMnAnvB2umaJNIOsLF3PVv//1Ew4CTcpz0/BRyy/af40qqrt7SjKpDdT1saBMc42CUok5gaw+g==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@testing-library/dom': ^10.0.0
+      '@types/react': ^18.0.0 || ^19.0.0
+      '@types/react-dom': ^18.0.0 || ^19.0.0
+      react: ^18.0.0 || ^19.0.0
+      react-dom: ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
   '@tybys/wasm-util@0.10.2':
     resolution: {integrity: sha512-RoBvJ2X0wuKlWFIjrwffGw1IqZHKQqzIchKaadZZfnNpsAYp2mM0h36JtPCjNDAHGgYez/15uMBpfGwchhiMgg==}
 
+  '@types/aria-query@5.0.4':
+    resolution: {integrity: sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw==}
+
   '@types/babel__code-frame@7.27.0':
     resolution: {integrity: sha512-Dwlo+LrxDx/0SpfmJ/BKveHf7QXWvLBLc+x03l5sbzykj3oB9nHygCpSECF1a+s+QIxbghe+KHqC90vGtxLRAA==}
 
+  '@types/babel__core@7.20.5':
+    resolution: {integrity: sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA==}
+
+  '@types/babel__generator@7.27.0':
+    resolution: {integrity: sha512-ufFd2Xi92OAVPYsy+P4n7/U7e68fex0+Ee8gSG9KX7eo084CWiQ4sdxktvdl0bOPupXtVJPY19zk6EwWqUQ8lg==}
+
+  '@types/babel__template@7.4.4':
+    resolution: {integrity: sha512-h/NUaSyG5EyxBIp8YRxo4RMe2/qQgvyowRwVMzhYhBCONbW8PUsg4lkFMrhgZhUe5z3L3MiLDuvyJ/CaPa2A8A==}
+
+  '@types/babel__traverse@7.28.0':
+    resolution: {integrity: sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q==}
+
   '@types/chai@5.2.3':
     resolution: {integrity: sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==}
 
@@ -5378,6 +6198,17 @@ packages:
   '@types/picomatch@3.0.2':
     resolution: {integrity: sha512-n0i8TD3UDB7paoMMxA3Y65vUncFJXjcUf7lQY7YyKGl6031FNjfsLs6pdLFCy2GNFxItPJG8GvvpbZc2skH7WA==}
 
+  '@types/prop-types@15.7.15':
+    resolution: {integrity: sha512-F6bEyamV9jKGAFBEmlQnesRPGOQqS2+Uwi0Em15xenOxHaf2hv6L8YCVn3rPdPJOiJfPiCnLIRyvwVaqMY3MIw==}
+
+  '@types/react-dom@18.3.7':
+    resolution: {integrity: sha512-MEe3UeoENYVFXzoXEWsvcpg6ZvlrFNlOQ7EOsvhI3CfAXwzPfO8Qwuxd40nepsYKqyyVQnTdEfv68q91yLcKrQ==}
+    peerDependencies:
+      '@types/react': ^18.0.0
+
+  '@types/react@18.3.31':
+    resolution: {integrity: sha512-vfEqpXTvwT91yhmwdfouStN2hSKwTvyRs8qpLfADyrq/kxDw0hZM7Wk9Ug1FELj8hIby+S/+kQCSRFF32nv2Qw==}
+
   '@types/retry@0.12.0':
     resolution: {integrity: sha512-wWKOClTTiizcZhXnPY4wikVAwmdYHp8q6DmC+EJUzAMsycb7HB32Kh9RN4+0gExjmPmZSAQjgURXIGATPegAvA==}
 
@@ -5458,6 +6289,12 @@ packages:
   '@upsetjs/venn.js@2.0.0':
     resolution: {integrity: sha512-WbBhLrooyePuQ1VZxrJjtLvTc4NVfpOyKx0sKqioq9bX1C1m7Jgykkn8gLrtwumBioXIqam8DLxp88Adbue6Hw==}
 
+  '@vitejs/plugin-react@4.7.0':
+    resolution: {integrity: sha512-gUu9hwfWvvEDBBmgtAowQCojwZmJ5mcLn3aufeCsitijs3+f2NsrPtlAWIR6OPiqljl96GVCUbLe0HyqIpVaoA==}
+    engines: {node: ^14.18.0 || >=16.0.0}
+    peerDependencies:
+      vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0
+
   '@vitejs/plugin-vue@5.2.4':
     resolution: {integrity: sha512-7Yx/SXSOcQq5HiiV3orevHUFn+pmMB4cgbEkDYgnkUWb0WfeQ/wa2yFv6D5ICiCQOVpjA7vYDXrC7AGO8yjDHA==}
     engines: {node: ^18.0.0 || >=20.0.0}
@@ -5642,6 +6479,10 @@ packages:
     resolution: {integrity: sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==}
     engines: {node: '>=8'}
 
+  ansi-styles@5.2.0:
+    resolution: {integrity: sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==}
+    engines: {node: '>=10'}
+
   ansi-styles@6.2.3:
     resolution: {integrity: sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==}
     engines: {node: '>=12'}
@@ -5656,6 +6497,9 @@ packages:
   argparse@2.0.1:
     resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==}
 
+  aria-query@5.3.0:
+    resolution: {integrity: sha512-b0P0sZPKtyu8HkeRAfCq0IfURZK+SuwMjY1UXGBU27wpAiTwQAIlq56IbIO+ytk/JjS1fMR14ee5WBBfKi5J6A==}
+
   assertion-error@2.0.1:
     resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==}
     engines: {node: '>=12'}
@@ -5677,6 +6521,11 @@ packages:
   base64-js@1.5.1:
     resolution: {integrity: sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==}
 
+  baseline-browser-mapping@2.10.43:
+    resolution: {integrity: sha512-AjYpR78kDWAY3Efj+cDTFH9t9SCoL7OoTp1BOb0mQV7S+6CiLwnWM3FyxhJtdPufDFKzmCSFoUncKjWgJEZTCQ==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
   bidi-js@1.0.3:
     resolution: {integrity: sha512-RKshQI1R3YQ+n9YJz2QQ147P66ELpa1FQEg20Dk8oW9t2KgLbpDLLp9aGZ7y8WHSshDknG0bknqGw5/tyCs5tw==}
 
@@ -5703,6 +6552,11 @@ packages:
     resolution: {integrity: sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g==}
     engines: {node: 18 || 20 || >=22}
 
+  browserslist@4.28.6:
+    resolution: {integrity: sha512-FQBYNK15VMslhLHpA7+n+n1GOlF1kId2xcCg7/j95f24AOF6VDYMNH4mFxF7KuaTdv627faazpOAjFzMrfJOUw==}
+    engines: {node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7}
+    hasBin: true
+
   buffer-equal-constant-time@1.0.1:
     resolution: {integrity: sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA==}
 
@@ -5726,6 +6580,9 @@ packages:
     resolution: {integrity: sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==}
     engines: {node: '>= 0.4'}
 
+  caniuse-lite@1.0.30001806:
+    resolution: {integrity: sha512-72Cuvd95zbSYPKq6Fhg8eDJRlzgWDf7/mtoZv6Qe/DYNCEBdNxoA3+rZAU2ZhGCpZlns3EssFavaZomckT5Uuw==}
+
   ccount@2.0.1:
     resolution: {integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==}
 
@@ -5746,6 +6603,10 @@ packages:
     resolution: {integrity: sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==}
     engines: {node: '>= 14.16.0'}
 
+  clsx@2.1.1:
+    resolution: {integrity: sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==}
+    engines: {node: '>=6'}
+
   color-convert@2.0.1:
     resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==}
     engines: {node: '>=7.0.0'}
@@ -6048,6 +6909,9 @@ packages:
     resolution: {integrity: sha512-svtcdpS8CgJyqAjEQIXdb3OjhFVVYjzGAPO8WGCmRbrml64SPw/jJD4GoE98aR7r25A0XcgrK3F02yw9R/vhQw==}
     engines: {node: '>=0.3.1'}
 
+  dom-accessibility-api@0.5.16:
+    resolution: {integrity: sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==}
+
   dompurify@3.4.11:
     resolution: {integrity: sha512-zhlUV12GsaRzMsf9q5M254YhA4+VuF0fG+QFqu6aYpoGlKtz+w8//jBcGVYBgQkR5GHjUomejY84AV+/uPbWdw==}
 
@@ -6073,6 +6937,9 @@ packages:
   ee-first@1.1.1:
     resolution: {integrity: sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==}
 
+  electron-to-chromium@1.5.393:
+    resolution: {integrity: sha512-kiDJdIUawuEIcp9XoICKp1iTYDEbgguIPq526N1Q7jIQDeQ3CqoMx71025PI/7E48Ddtw2HuWsVjY7afEgNxmg==}
+
   emoji-regex-xs@1.0.0:
     resolution: {integrity: sha512-LRlerrMYoIDrT6jgpeZ2YYl/L8EulRTt5hQcYjy5AInh7HWXKimpqx68aknBFpGL2+/IcogTcaydJEgaTmOpDg==}
 
@@ -6121,11 +6988,20 @@ packages:
     engines: {node: '>=12'}
     hasBin: true
 
+  esbuild@0.25.12:
+    resolution: {integrity: sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg==}
+    engines: {node: '>=18'}
+    hasBin: true
+
   esbuild@0.28.1:
     resolution: {integrity: sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==}
     engines: {node: '>=18'}
     hasBin: true
 
+  escalade@3.2.0:
+    resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==}
+    engines: {node: '>=6'}
+
   escape-html@1.0.3:
     resolution: {integrity: sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==}
 
@@ -6318,6 +7194,11 @@ packages:
     resolution: {integrity: sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==}
     engines: {node: '>= 0.8'}
 
+  fsevents@2.3.2:
+    resolution: {integrity: sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
   fsevents@2.3.3:
     resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
     engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
@@ -6337,6 +7218,10 @@ packages:
     resolution: {integrity: sha512-zV/5HKTfCeKWnxG0Dmrw51hEWFGfcF2xiXqcA3+J90WDuP0SvoiSO5ORvcBsifmx/FoIjgQN3oNOGaQ5PhLFkg==}
     engines: {node: '>=18'}
 
+  gensync@1.0.0-beta.2:
+    resolution: {integrity: sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==}
+    engines: {node: '>=6.9.0'}
+
   get-east-asian-width@1.6.0:
     resolution: {integrity: sha512-QRbvDIbx6YklUe6RxeTeleMR0yv3cYH6PsPZHcnVn7xv7zO1BHN8r0XETu8n6Ye3Q+ahtSarc3WgtNWmehIBfA==}
     engines: {node: '>=18'}
@@ -6461,6 +7346,9 @@ packages:
   immediate@3.0.6:
     resolution: {integrity: sha512-XXOFtyqDjNDAQxVfYxuF7g9Il/IbWmmlQg2MYKOH8ExIT1qg6xc4zyS3HaEEATgs1btfzxq15ciUiY7gjSXRGQ==}
 
+  immer@10.2.0:
+    resolution: {integrity: sha512-d/+XTN3zfODyjr89gM3mPq1WNX2B8pYsu7eORitdwyA2sBubnTl3laYlBk4sXY5FUa5qTZGBDPJICVbvqzjlbw==}
+
   import-meta-resolve@4.2.0:
     resolution: {integrity: sha512-Iqv2fzaTQN28s/FwZAoFq0ZSs/7hMAHJVX+w8PZl3cY19Pxk6jFFalxQoIfW2826i/fDLXv8IiEZRIT0lDuWcg==}
 
@@ -6624,6 +7512,11 @@ packages:
   json-stable-stringify-without-jsonify@1.0.1:
     resolution: {integrity: sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==}
 
+  json5@2.2.3:
+    resolution: {integrity: sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==}
+    engines: {node: '>=6'}
+    hasBin: true
+
   jsonc-parser@3.3.1:
     resolution: {integrity: sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==}
 
@@ -6815,6 +7708,10 @@ packages:
   longest-streak@3.1.0:
     resolution: {integrity: sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g==}
 
+  loose-envify@1.4.0:
+    resolution: {integrity: sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==}
+    hasBin: true
+
   lru-cache@10.4.3:
     resolution: {integrity: sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==}
 
@@ -6822,6 +7719,13 @@ packages:
     resolution: {integrity: sha512-RPimw/7aMdv2oqRrxKwvZXcPfwBrn/JZ2xYcY9Hus/6LaS3VOAKVWKWgNLCFSiOm1ESXinjsDlidVU7JlnCN2A==}
     engines: {node: 20 || >=22}
 
+  lru-cache@5.1.1:
+    resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==}
+
+  lz-string@1.5.0:
+    resolution: {integrity: sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==}
+    hasBin: true
+
   magic-string@0.30.21:
     resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
 
@@ -7120,6 +8024,10 @@ packages:
   node-pty@1.1.0:
     resolution: {integrity: sha512-20JqtutY6JPXTUnL0ij1uad7Qe1baT46lyolh2sSENDd4sTzKZ4nmAFkeAARDKwmlLjPx6XKRlwRUxwjOy+lUg==}
 
+  node-releases@2.0.51:
+    resolution: {integrity: sha512-wRNIrw4DmVLKQlbgOMdkMx27Wrpzes2hh5Jtbi2bjPd+4wJstWIqP5A+lscnqbm0xxmT5Bpg8Lec5ItEBwx6BQ==}
+    engines: {node: '>=18'}
+
   non-layered-tidy-tree-layout@2.0.2:
     resolution: {integrity: sha512-gkXMxRzUH+PB0ax9dUN0yYF0S25BqeAYqhgMaLUFmpXLEk7Fcu8f4emJuOAY0V8kjDICxROIKsTAKsV/v355xw==}
 
@@ -7238,6 +8146,16 @@ packages:
     resolution: {integrity: sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==}
     engines: {node: '>=16.20.0'}
 
+  playwright-core@1.61.1:
+    resolution: {integrity: sha512-h7Qlt6m4REp25qvIdvbDtVmD4LqVXfpRxhORv9L0jzETM05p4fuPJ3dKyuSXQxDSbXnmS79HAgi9589lGSpLkg==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  playwright@1.61.1:
+    resolution: {integrity: sha512-DWnY5o3YbLWK4GovuAVwpqL+1VwGNdUGrRr++8j8PtQQzvAVZUIMjKQ90fY689sEJZJBbZVw1rXaOKSTitkzPQ==}
+    engines: {node: '>=18'}
+    hasBin: true
+
   points-on-curve@0.2.0:
     resolution: {integrity: sha512-0mYKnYYe9ZcqMCWhUjItv/oHjvgEsfKvnUTg8sAtnHr3GVy7rGkXCb6d5cSyqrWqL4k81b9CPg3urd+T7aop3A==}
 
@@ -7260,6 +8178,10 @@ packages:
     resolution: {integrity: sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==}
     engines: {node: '>= 0.8.0'}
 
+  pretty-format@27.5.1:
+    resolution: {integrity: sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ==}
+    engines: {node: ^10.13.0 || ^12.13.0 || ^14.15.0 || >=15.0.0}
+
   process-nextick-args@2.0.1:
     resolution: {integrity: sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag==}
 
@@ -7301,6 +8223,22 @@ packages:
     resolution: {integrity: sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==}
     engines: {node: '>= 0.10'}
 
+  react-dom@18.3.1:
+    resolution: {integrity: sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==}
+    peerDependencies:
+      react: ^18.3.1
+
+  react-is@17.0.2:
+    resolution: {integrity: sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==}
+
+  react-refresh@0.17.0:
+    resolution: {integrity: sha512-z6F7K9bV85EfseRCp2bzrpyQ0Gkw1uLoCel9XBVWPg/TjRj94SkJzUTGfOa4bs7iJvBWtQG0Wq7wnI0syw3EBQ==}
+    engines: {node: '>=0.10.0'}
+
+  react@18.3.1:
+    resolution: {integrity: sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==}
+    engines: {node: '>=0.10.0'}
+
   readable-stream@2.3.8:
     resolution: {integrity: sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==}
 
@@ -7403,6 +8341,9 @@ packages:
     resolution: {integrity: sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==}
     engines: {node: '>=v12.22.7'}
 
+  scheduler@0.23.2:
+    resolution: {integrity: sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==}
+
   schemastery@3.18.0:
     resolution: {integrity: sha512-Jw2uxjoyyqc/yeurmChUEc/jbi8GsrdXV/KmqRUDZXJAXAmrJiPsz8vKa17l/VckyzljHZ9oGaul443CQiXxtA==}
 
@@ -7413,6 +8354,10 @@ packages:
   search-insights@2.17.3:
     resolution: {integrity: sha512-RQPdCYTa8A68uM2jwxoY842xDhvx3E5LFL1LxvxCNMev4o5mLuokczhzjAgGwUZBAmOKZknArSxLKmXtIi2AxQ==}
 
+  semver@6.3.1:
+    resolution: {integrity: sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==}
+    hasBin: true
+
   semver@7.8.4:
     resolution: {integrity: sha512-rUCObTnP32Q08R2uuIrt7r9PlEonuTmtuXYcW6s5kjdlj3xbnwe+21yXptAUYcMAABLkYYTtnmzb3w3EDZfueA==}
     engines: {node: '>=10'}
@@ -7724,9 +8669,20 @@ packages:
     resolution: {integrity: sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==}
     engines: {node: '>= 0.8'}
 
+  update-browserslist-db@1.2.3:
+    resolution: {integrity: sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==}
+    hasBin: true
+    peerDependencies:
+      browserslist: '>= 4.21.0'
+
   uri-js@4.4.1:
     resolution: {integrity: sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==}
 
+  use-sync-external-store@1.2.0:
+    resolution: {integrity: sha512-eEgnFxGQ1Ife9bzYs6VLi8/4X6CObHMw9Qr9tPY43iKwsPw8xE8+EFsf/2cFZ5S3esXgpWgtSCtLNS41F+sKPA==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0
+
   util-deprecate@1.0.2:
     resolution: {integrity: sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==}
 
@@ -7780,6 +8736,46 @@ packages:
       terser:
         optional: true
 
+  vite@6.4.3:
+    resolution: {integrity: sha512-NTKlcQjlAK7MlQoyb6LgaqHc8sso/pVyUJYWMws3jg21uTJw/LddqIFPcPqP6PzpgbIcZyKI85sFE4HBrQDA8A==}
+    engines: {node: ^18.0.0 || ^20.0.0 || >=22.0.0}
+    hasBin: true
+    peerDependencies:
+      '@types/node': ^18.0.0 || ^20.0.0 || >=22.0.0
+      jiti: '>=1.21.0'
+      less: '*'
+      lightningcss: ^1.21.0
+      sass: '*'
+      sass-embedded: '*'
+      stylus: '*'
+      sugarss: '*'
+      terser: ^5.16.0
+      tsx: ^4.8.1
+      yaml: ^2.4.2
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+      jiti:
+        optional: true
+      less:
+        optional: true
+      lightningcss:
+        optional: true
+      sass:
+        optional: true
+      sass-embedded:
+        optional: true
+      stylus:
+        optional: true
+      sugarss:
+        optional: true
+      terser:
+        optional: true
+      tsx:
+        optional: true
+      yaml:
+        optional: true
+
   vite@8.0.16:
     resolution: {integrity: sha512-h9bXPmJichP5fLmVQo3PyaGSDE2n3aPuomeAlVRm0JLmt4rY6zmPKd59HYI4LNW8oTK7tlTsuC7l/m7awx9Jcw==}
     engines: {node: ^20.19.0 || >=22.12.0}
@@ -7979,6 +8975,9 @@ packages:
   xmlchars@2.2.0:
     resolution: {integrity: sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==}
 
+  yallist@3.1.1:
+    resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==}
+
   yaml@2.9.0:
     resolution: {integrity: sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==}
     engines: {node: '>= 14.6'}
@@ -7996,6 +8995,21 @@ packages:
   zod@4.4.3:
     resolution: {integrity: sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==}
 
+  zustand@4.4.7:
+    resolution: {integrity: sha512-QFJWJMdlETcI69paJwhSMJz7PPWjVP8Sjhclxmxmxv/RYI7ZOvR5BHX+ktH0we9gTWQMxcne8q1OY8xxz604gw==}
+    engines: {node: '>=12.7.0'}
+    peerDependencies:
+      '@types/react': '>=16.8'
+      immer: '>=9.0'
+      react: '>=16.8'
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      immer:
+        optional: true
+      react:
+        optional: true
+
   zwitch@2.0.4:
     resolution: {integrity: sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==}
 
@@ -8377,6 +9391,36 @@ snapshots:
       js-tokens: 4.0.0
       picocolors: 1.1.1
 
+  '@babel/compat-data@7.29.7': {}
+
+  '@babel/core@7.29.7':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/generator': 7.29.7
+      '@babel/helper-compilation-targets': 7.29.7
+      '@babel/helper-module-transforms': 7.29.7(@babel/core@7.29.7)
+      '@babel/helpers': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/template': 7.29.7
+      '@babel/traverse': 7.29.7
+      '@babel/types': 7.29.7
+      '@jridgewell/remapping': 2.3.5
+      convert-source-map: 2.0.0
+      debug: 4.4.3
+      gensync: 1.0.0-beta.2
+      json5: 2.2.3
+      semver: 6.3.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/generator@7.29.7':
+    dependencies:
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+      jsesc: 3.1.0
+
   '@babel/generator@8.0.0-rc.6':
     dependencies:
       '@babel/parser': 8.0.0-rc.6
@@ -8386,6 +9430,34 @@ snapshots:
       '@types/jsesc': 2.5.1
       jsesc: 3.1.0
 
+  '@babel/helper-compilation-targets@7.29.7':
+    dependencies:
+      '@babel/compat-data': 7.29.7
+      '@babel/helper-validator-option': 7.29.7
+      browserslist: 4.28.6
+      lru-cache: 5.1.1
+      semver: 6.3.1
+
+  '@babel/helper-globals@7.29.7': {}
+
+  '@babel/helper-module-imports@7.29.7':
+    dependencies:
+      '@babel/traverse': 7.29.7
+      '@babel/types': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-module-transforms@7.29.7(@babel/core@7.29.7)':
+    dependencies:
+      '@babel/core': 7.29.7
+      '@babel/helper-module-imports': 7.29.7
+      '@babel/helper-validator-identifier': 7.29.7
+      '@babel/traverse': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-plugin-utils@7.29.7': {}
+
   '@babel/helper-string-parser@7.29.7': {}
 
   '@babel/helper-string-parser@8.0.0-rc.6': {}
@@ -8394,6 +9466,13 @@ snapshots:
 
   '@babel/helper-validator-identifier@8.0.0-rc.6': {}
 
+  '@babel/helper-validator-option@7.29.7': {}
+
+  '@babel/helpers@7.29.7':
+    dependencies:
+      '@babel/template': 7.29.7
+      '@babel/types': 7.29.7
+
   '@babel/parser@7.29.7':
     dependencies:
       '@babel/types': 7.29.7
@@ -8402,8 +9481,36 @@ snapshots:
     dependencies:
       '@babel/types': 8.0.0-rc.6
 
+  '@babel/plugin-transform-react-jsx-self@7.29.7(@babel/core@7.29.7)':
+    dependencies:
+      '@babel/core': 7.29.7
+      '@babel/helper-plugin-utils': 7.29.7
+
+  '@babel/plugin-transform-react-jsx-source@7.29.7(@babel/core@7.29.7)':
+    dependencies:
+      '@babel/core': 7.29.7
+      '@babel/helper-plugin-utils': 7.29.7
+
   '@babel/runtime@7.29.7': {}
 
+  '@babel/template@7.29.7':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
+
+  '@babel/traverse@7.29.7':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/generator': 7.29.7
+      '@babel/helper-globals': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/template': 7.29.7
+      '@babel/types': 7.29.7
+      debug: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
+
   '@babel/types@7.29.7':
     dependencies:
       '@babel/helper-string-parser': 7.29.7
@@ -8492,9 +9599,9 @@ snapshots:
 
   '@docsearch/css@3.8.2': {}
 
-  '@docsearch/js@3.8.2(@algolia/client-search@5.55.2)(search-insights@2.17.3)':
+  '@docsearch/js@3.8.2(@algolia/client-search@5.55.2)(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(search-insights@2.17.3)':
     dependencies:
-      '@docsearch/react': 3.8.2(@algolia/client-search@5.55.2)(search-insights@2.17.3)
+      '@docsearch/react': 3.8.2(@algolia/client-search@5.55.2)(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(search-insights@2.17.3)
       preact: 10.29.7
     transitivePeerDependencies:
       - '@algolia/client-search'
@@ -8504,13 +9611,16 @@ snapshots:
       - react-dom
       - search-insights
 
-  '@docsearch/react@3.8.2(@algolia/client-search@5.55.2)(search-insights@2.17.3)':
+  '@docsearch/react@3.8.2(@algolia/client-search@5.55.2)(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(search-insights@2.17.3)':
     dependencies:
       '@algolia/autocomplete-core': 1.17.7(@algolia/client-search@5.55.2)(algoliasearch@5.55.2)(search-insights@2.17.3)
       '@algolia/autocomplete-preset-algolia': 1.17.7(@algolia/client-search@5.55.2)(algoliasearch@5.55.2)
       '@docsearch/css': 3.8.2
       algoliasearch: 5.55.2
     optionalDependencies:
+      '@types/react': 18.3.31
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
       search-insights: 2.17.3
     transitivePeerDependencies:
       - '@algolia/client-search'
@@ -8575,147 +9685,225 @@ snapshots:
   '@esbuild/aix-ppc64@0.21.5':
     optional: true
 
+  '@esbuild/aix-ppc64@0.25.12':
+    optional: true
+
   '@esbuild/aix-ppc64@0.28.1':
     optional: true
 
   '@esbuild/android-arm64@0.21.5':
     optional: true
 
+  '@esbuild/android-arm64@0.25.12':
+    optional: true
+
   '@esbuild/android-arm64@0.28.1':
     optional: true
 
   '@esbuild/android-arm@0.21.5':
     optional: true
 
+  '@esbuild/android-arm@0.25.12':
+    optional: true
+
   '@esbuild/android-arm@0.28.1':
     optional: true
 
   '@esbuild/android-x64@0.21.5':
     optional: true
 
+  '@esbuild/android-x64@0.25.12':
+    optional: true
+
   '@esbuild/android-x64@0.28.1':
     optional: true
 
   '@esbuild/darwin-arm64@0.21.5':
     optional: true
 
+  '@esbuild/darwin-arm64@0.25.12':
+    optional: true
+
   '@esbuild/darwin-arm64@0.28.1':
     optional: true
 
   '@esbuild/darwin-x64@0.21.5':
     optional: true
 
+  '@esbuild/darwin-x64@0.25.12':
+    optional: true
+
   '@esbuild/darwin-x64@0.28.1':
     optional: true
 
   '@esbuild/freebsd-arm64@0.21.5':
     optional: true
 
+  '@esbuild/freebsd-arm64@0.25.12':
+    optional: true
+
   '@esbuild/freebsd-arm64@0.28.1':
     optional: true
 
   '@esbuild/freebsd-x64@0.21.5':
     optional: true
 
+  '@esbuild/freebsd-x64@0.25.12':
+    optional: true
+
   '@esbuild/freebsd-x64@0.28.1':
     optional: true
 
   '@esbuild/linux-arm64@0.21.5':
     optional: true
 
+  '@esbuild/linux-arm64@0.25.12':
+    optional: true
+
   '@esbuild/linux-arm64@0.28.1':
     optional: true
 
   '@esbuild/linux-arm@0.21.5':
     optional: true
 
+  '@esbuild/linux-arm@0.25.12':
+    optional: true
+
   '@esbuild/linux-arm@0.28.1':
     optional: true
 
   '@esbuild/linux-ia32@0.21.5':
     optional: true
 
+  '@esbuild/linux-ia32@0.25.12':
+    optional: true
+
   '@esbuild/linux-ia32@0.28.1':
     optional: true
 
   '@esbuild/linux-loong64@0.21.5':
     optional: true
 
+  '@esbuild/linux-loong64@0.25.12':
+    optional: true
+
   '@esbuild/linux-loong64@0.28.1':
     optional: true
 
   '@esbuild/linux-mips64el@0.21.5':
     optional: true
 
+  '@esbuild/linux-mips64el@0.25.12':
+    optional: true
+
   '@esbuild/linux-mips64el@0.28.1':
     optional: true
 
   '@esbuild/linux-ppc64@0.21.5':
     optional: true
 
+  '@esbuild/linux-ppc64@0.25.12':
+    optional: true
+
   '@esbuild/linux-ppc64@0.28.1':
     optional: true
 
   '@esbuild/linux-riscv64@0.21.5':
     optional: true
 
+  '@esbuild/linux-riscv64@0.25.12':
+    optional: true
+
   '@esbuild/linux-riscv64@0.28.1':
     optional: true
 
   '@esbuild/linux-s390x@0.21.5':
     optional: true
 
+  '@esbuild/linux-s390x@0.25.12':
+    optional: true
+
   '@esbuild/linux-s390x@0.28.1':
     optional: true
 
   '@esbuild/linux-x64@0.21.5':
     optional: true
 
+  '@esbuild/linux-x64@0.25.12':
+    optional: true
+
   '@esbuild/linux-x64@0.28.1':
     optional: true
 
+  '@esbuild/netbsd-arm64@0.25.12':
+    optional: true
+
   '@esbuild/netbsd-arm64@0.28.1':
     optional: true
 
   '@esbuild/netbsd-x64@0.21.5':
     optional: true
 
+  '@esbuild/netbsd-x64@0.25.12':
+    optional: true
+
   '@esbuild/netbsd-x64@0.28.1':
     optional: true
 
+  '@esbuild/openbsd-arm64@0.25.12':
+    optional: true
+
   '@esbuild/openbsd-arm64@0.28.1':
     optional: true
 
   '@esbuild/openbsd-x64@0.21.5':
     optional: true
 
+  '@esbuild/openbsd-x64@0.25.12':
+    optional: true
+
   '@esbuild/openbsd-x64@0.28.1':
     optional: true
 
+  '@esbuild/openharmony-arm64@0.25.12':
+    optional: true
+
   '@esbuild/openharmony-arm64@0.28.1':
     optional: true
 
   '@esbuild/sunos-x64@0.21.5':
     optional: true
 
+  '@esbuild/sunos-x64@0.25.12':
+    optional: true
+
   '@esbuild/sunos-x64@0.28.1':
     optional: true
 
   '@esbuild/win32-arm64@0.21.5':
     optional: true
 
+  '@esbuild/win32-arm64@0.25.12':
+    optional: true
+
   '@esbuild/win32-arm64@0.28.1':
     optional: true
 
   '@esbuild/win32-ia32@0.21.5':
     optional: true
 
+  '@esbuild/win32-ia32@0.25.12':
+    optional: true
+
   '@esbuild/win32-ia32@0.28.1':
     optional: true
 
   '@esbuild/win32-x64@0.21.5':
     optional: true
 
+  '@esbuild/win32-x64@0.25.12':
+    optional: true
+
   '@esbuild/win32-x64@0.28.1':
     optional: true
 
@@ -8810,6 +9998,11 @@ snapshots:
       '@jridgewell/sourcemap-codec': 1.5.5
       '@jridgewell/trace-mapping': 0.3.31
 
+  '@jridgewell/remapping@2.3.5':
+    dependencies:
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+
   '@jridgewell/resolve-uri@3.1.2': {}
 
   '@jridgewell/sourcemap-codec@1.5.5': {}
@@ -9204,6 +10397,8 @@ snapshots:
   '@rolldown/binding-win32-x64-msvc@1.1.1':
     optional: true
 
+  '@rolldown/pluginutils@1.0.0-beta.27': {}
+
   '@rolldown/pluginutils@1.0.1': {}
 
   '@rollup/rollup-android-arm-eabi@4.62.2':
@@ -9387,13 +10582,57 @@ snapshots:
       estraverse: 5.3.0
       picomatch: 4.0.4
 
+  '@testing-library/dom@10.4.1':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/runtime': 7.29.7
+      '@types/aria-query': 5.0.4
+      aria-query: 5.3.0
+      dom-accessibility-api: 0.5.16
+      lz-string: 1.5.0
+      picocolors: 1.1.1
+      pretty-format: 27.5.1
+
+  '@testing-library/react@16.3.2(@testing-library/dom@10.4.1)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@babel/runtime': 7.29.7
+      '@testing-library/dom': 10.4.1
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@tybys/wasm-util@0.10.2':
     dependencies:
       tslib: 2.8.1
     optional: true
 
+  '@types/aria-query@5.0.4': {}
+
   '@types/babel__code-frame@7.27.0': {}
 
+  '@types/babel__core@7.20.5':
+    dependencies:
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
+      '@types/babel__generator': 7.27.0
+      '@types/babel__template': 7.4.4
+      '@types/babel__traverse': 7.28.0
+
+  '@types/babel__generator@7.27.0':
+    dependencies:
+      '@babel/types': 7.29.7
+
+  '@types/babel__template@7.4.4':
+    dependencies:
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
+
+  '@types/babel__traverse@7.28.0':
+    dependencies:
+      '@babel/types': 7.29.7
+
   '@types/chai@5.2.3':
     dependencies:
       '@types/deep-eql': 4.0.2
@@ -9570,6 +10809,17 @@ snapshots:
 
   '@types/picomatch@3.0.2': {}
 
+  '@types/prop-types@15.7.15': {}
+
+  '@types/react-dom@18.3.7(@types/react@18.3.31)':
+    dependencies:
+      '@types/react': 18.3.31
+
+  '@types/react@18.3.31':
+    dependencies:
+      '@types/prop-types': 15.7.15
+      csstype: 3.2.3
+
   '@types/retry@0.12.0': {}
 
   '@types/tough-cookie@4.0.5': {}
@@ -9679,6 +10929,18 @@ snapshots:
       d3-selection: 3.0.0
       d3-transition: 3.0.1(d3-selection@3.0.0)
 
+  '@vitejs/plugin-react@4.7.0(vite@6.4.3(@types/node@22.20.0)(jiti@2.7.0)(lightningcss@1.32.0)(tsx@4.22.4)(yaml@2.9.0))':
+    dependencies:
+      '@babel/core': 7.29.7
+      '@babel/plugin-transform-react-jsx-self': 7.29.7(@babel/core@7.29.7)
+      '@babel/plugin-transform-react-jsx-source': 7.29.7(@babel/core@7.29.7)
+      '@rolldown/pluginutils': 1.0.0-beta.27
+      '@types/babel__core': 7.20.5
+      react-refresh: 0.17.0
+      vite: 6.4.3(@types/node@22.20.0)(jiti@2.7.0)(lightningcss@1.32.0)(tsx@4.22.4)(yaml@2.9.0)
+    transitivePeerDependencies:
+      - supports-color
+
   '@vitejs/plugin-vue@5.2.4(vite@5.4.21(@types/node@25.9.3)(lightningcss@1.32.0))(vue@3.5.39(typescript@6.0.3))':
     dependencies:
       vite: 5.4.21(@types/node@25.9.3)(lightningcss@1.32.0)
@@ -9707,6 +10969,14 @@ snapshots:
       chai: 6.2.2
       tinyrainbow: 3.1.0
 
+  '@vitest/mocker@4.1.8(vite@6.4.3(@types/node@22.20.0)(jiti@2.7.0)(lightningcss@1.32.0)(tsx@4.22.4)(yaml@2.9.0))':
+    dependencies:
+      '@vitest/spy': 4.1.8
+      estree-walker: 3.0.3
+      magic-string: 0.30.21
+    optionalDependencies:
+      vite: 6.4.3(@types/node@22.20.0)(jiti@2.7.0)(lightningcss@1.32.0)(tsx@4.22.4)(yaml@2.9.0)
+
   '@vitest/mocker@4.1.8(vite@8.0.16(@types/node@22.20.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0))':
     dependencies:
       '@vitest/spy': 4.1.8
@@ -9904,6 +11174,8 @@ snapshots:
     dependencies:
       color-convert: 2.0.1
 
+  ansi-styles@5.2.0: {}
+
   ansi-styles@6.2.3: {}
 
   ansis@4.3.1: {}
@@ -9912,6 +11184,10 @@ snapshots:
 
   argparse@2.0.1: {}
 
+  aria-query@5.3.0:
+    dependencies:
+      dequal: 2.0.3
+
   assertion-error@2.0.1: {}
 
   ast-kit@3.0.0-beta.1:
@@ -9932,6 +11208,8 @@ snapshots:
 
   base64-js@1.5.1: {}
 
+  baseline-browser-mapping@2.10.43: {}
+
   bidi-js@1.0.3:
     dependencies:
       require-from-string: 2.0.2
@@ -9966,6 +11244,14 @@ snapshots:
     dependencies:
       balanced-match: 4.0.4
 
+  browserslist@4.28.6:
+    dependencies:
+      baseline-browser-mapping: 2.10.43
+      caniuse-lite: 1.0.30001806
+      electron-to-chromium: 1.5.393
+      node-releases: 2.0.51
+      update-browserslist-db: 1.2.3(browserslist@4.28.6)
+
   buffer-equal-constant-time@1.0.1: {}
 
   builtin-modules@3.3.0: {}
@@ -9984,6 +11270,8 @@ snapshots:
       call-bind-apply-helpers: 1.0.2
       get-intrinsic: 1.3.0
 
+  caniuse-lite@1.0.30001806: {}
+
   ccount@2.0.1: {}
 
   chai@6.2.2: {}
@@ -9998,6 +11286,8 @@ snapshots:
     dependencies:
       readdirp: 4.1.2
 
+  clsx@2.1.1: {}
+
   color-convert@2.0.1:
     dependencies:
       color-name: 1.1.4
@@ -10309,6 +11599,8 @@ snapshots:
 
   diff@9.0.0: {}
 
+  dom-accessibility-api@0.5.16: {}
+
   dompurify@3.4.11:
     optionalDependencies:
       '@types/trusted-types': 2.0.7
@@ -10331,6 +11623,8 @@ snapshots:
 
   ee-first@1.1.1: {}
 
+  electron-to-chromium@1.5.393: {}
+
   emoji-regex-xs@1.0.0: {}
 
   emoji-regex@8.0.0: {}
@@ -10383,6 +11677,35 @@ snapshots:
       '@esbuild/win32-ia32': 0.21.5
       '@esbuild/win32-x64': 0.21.5
 
+  esbuild@0.25.12:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.25.12
+      '@esbuild/android-arm': 0.25.12
+      '@esbuild/android-arm64': 0.25.12
+      '@esbuild/android-x64': 0.25.12
+      '@esbuild/darwin-arm64': 0.25.12
+      '@esbuild/darwin-x64': 0.25.12
+      '@esbuild/freebsd-arm64': 0.25.12
+      '@esbuild/freebsd-x64': 0.25.12
+      '@esbuild/linux-arm': 0.25.12
+      '@esbuild/linux-arm64': 0.25.12
+      '@esbuild/linux-ia32': 0.25.12
+      '@esbuild/linux-loong64': 0.25.12
+      '@esbuild/linux-mips64el': 0.25.12
+      '@esbuild/linux-ppc64': 0.25.12
+      '@esbuild/linux-riscv64': 0.25.12
+      '@esbuild/linux-s390x': 0.25.12
+      '@esbuild/linux-x64': 0.25.12
+      '@esbuild/netbsd-arm64': 0.25.12
+      '@esbuild/netbsd-x64': 0.25.12
+      '@esbuild/openbsd-arm64': 0.25.12
+      '@esbuild/openbsd-x64': 0.25.12
+      '@esbuild/openharmony-arm64': 0.25.12
+      '@esbuild/sunos-x64': 0.25.12
+      '@esbuild/win32-arm64': 0.25.12
+      '@esbuild/win32-ia32': 0.25.12
+      '@esbuild/win32-x64': 0.25.12
+
   esbuild@0.28.1:
     optionalDependencies:
       '@esbuild/aix-ppc64': 0.28.1
@@ -10412,6 +11735,8 @@ snapshots:
       '@esbuild/win32-ia32': 0.28.1
       '@esbuild/win32-x64': 0.28.1
 
+  escalade@3.2.0: {}
+
   escape-html@1.0.3: {}
 
   escape-string-regexp@4.0.0: {}
@@ -10660,6 +11985,9 @@ snapshots:
 
   fresh@2.0.0: {}
 
+  fsevents@2.3.2:
+    optional: true
+
   fsevents@2.3.3:
     optional: true
 
@@ -10683,6 +12011,8 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  gensync@1.0.0-beta.2: {}
+
   get-east-asian-width@1.6.0: {}
 
   get-intrinsic@1.3.0:
@@ -10832,6 +12162,8 @@ snapshots:
 
   immediate@3.0.6: {}
 
+  immer@10.2.0: {}
+
   import-meta-resolve@4.2.0: {}
 
   import-without-cache@0.4.0: {}
@@ -10971,6 +12303,8 @@ snapshots:
 
   json-stable-stringify-without-jsonify@1.0.1: {}
 
+  json5@2.2.3: {}
+
   jsonc-parser@3.3.1: {}
 
   jsx-ast-utils-x@0.1.0: {}
@@ -11154,10 +12488,20 @@ snapshots:
 
   longest-streak@3.1.0: {}
 
+  loose-envify@1.4.0:
+    dependencies:
+      js-tokens: 4.0.0
+
   lru-cache@10.4.3: {}
 
   lru-cache@11.5.1: {}
 
+  lru-cache@5.1.1:
+    dependencies:
+      yallist: 3.1.1
+
+  lz-string@1.5.0: {}
+
   magic-string@0.30.21:
     dependencies:
       '@jridgewell/sourcemap-codec': 1.5.5
@@ -11625,6 +12969,8 @@ snapshots:
     dependencies:
       node-addon-api: 7.1.1
 
+  node-releases@2.0.51: {}
+
   non-layered-tidy-tree-layout@2.0.2:
     optional: true
 
@@ -11761,6 +13107,14 @@ snapshots:
 
   pkce-challenge@5.0.1: {}
 
+  playwright-core@1.61.1: {}
+
+  playwright@1.61.1:
+    dependencies:
+      playwright-core: 1.61.1
+    optionalDependencies:
+      fsevents: 2.3.2
+
   points-on-curve@0.2.0: {}
 
   points-on-path@0.2.1:
@@ -11778,6 +13132,12 @@ snapshots:
 
   prelude-ls@1.2.1: {}
 
+  pretty-format@27.5.1:
+    dependencies:
+      ansi-regex: 5.0.1
+      ansi-styles: 5.2.0
+      react-is: 17.0.2
+
   process-nextick-args@2.0.1: {}
 
   property-information@7.2.0: {}
@@ -11828,6 +13188,20 @@ snapshots:
       iconv-lite: 0.7.3
       unpipe: 1.0.0
 
+  react-dom@18.3.1(react@18.3.1):
+    dependencies:
+      loose-envify: 1.4.0
+      react: 18.3.1
+      scheduler: 0.23.2
+
+  react-is@17.0.2: {}
+
+  react-refresh@0.17.0: {}
+
+  react@18.3.1:
+    dependencies:
+      loose-envify: 1.4.0
+
   readable-stream@2.3.8:
     dependencies:
       core-util-is: 1.0.3
@@ -11991,6 +13365,10 @@ snapshots:
     dependencies:
       xmlchars: 2.2.0
 
+  scheduler@0.23.2:
+    dependencies:
+      loose-envify: 1.4.0
+
   schemastery@3.18.0:
     dependencies:
       '@standard-schema/spec': 1.1.0
@@ -12004,6 +13382,8 @@ snapshots:
 
   search-insights@2.17.3: {}
 
+  semver@6.3.1: {}
+
   semver@7.8.4: {}
 
   send@1.2.1:
@@ -12302,10 +13682,20 @@ snapshots:
 
   unpipe@1.0.0: {}
 
+  update-browserslist-db@1.2.3(browserslist@4.28.6):
+    dependencies:
+      browserslist: 4.28.6
+      escalade: 3.2.0
+      picocolors: 1.1.1
+
   uri-js@4.4.1:
     dependencies:
       punycode: 2.3.1
 
+  use-sync-external-store@1.2.0(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+
   util-deprecate@1.0.2: {}
 
   uuid@14.0.1: {}
@@ -12342,6 +13732,22 @@ snapshots:
       fsevents: 2.3.3
       lightningcss: 1.32.0
 
+  vite@6.4.3(@types/node@22.20.0)(jiti@2.7.0)(lightningcss@1.32.0)(tsx@4.22.4)(yaml@2.9.0):
+    dependencies:
+      esbuild: 0.25.12
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
+      postcss: 8.5.15
+      rollup: 4.62.2
+      tinyglobby: 0.2.17
+    optionalDependencies:
+      '@types/node': 22.20.0
+      fsevents: 2.3.3
+      jiti: 2.7.0
+      lightningcss: 1.32.0
+      tsx: 4.22.4
+      yaml: 2.9.0
+
   vite@8.0.16(@types/node@22.20.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0):
     dependencies:
       lightningcss: 1.32.0
@@ -12372,17 +13778,17 @@ snapshots:
       tsx: 4.22.4
       yaml: 2.9.0
 
-  vitepress-plugin-mermaid@2.0.17(mermaid@11.16.0)(vitepress@1.6.4(@algolia/client-search@5.55.2)(@types/node@25.9.3)(lightningcss@1.32.0)(postcss@8.5.15)(search-insights@2.17.3)(typescript@6.0.3)):
+  vitepress-plugin-mermaid@2.0.17(mermaid@11.16.0)(vitepress@1.6.4(@algolia/client-search@5.55.2)(@types/node@25.9.3)(@types/react@18.3.31)(lightningcss@1.32.0)(postcss@8.5.15)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(search-insights@2.17.3)(typescript@6.0.3)):
     dependencies:
       mermaid: 11.16.0
-      vitepress: 1.6.4(@algolia/client-search@5.55.2)(@types/node@25.9.3)(lightningcss@1.32.0)(postcss@8.5.15)(search-insights@2.17.3)(typescript@6.0.3)
+      vitepress: 1.6.4(@algolia/client-search@5.55.2)(@types/node@25.9.3)(@types/react@18.3.31)(lightningcss@1.32.0)(postcss@8.5.15)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(search-insights@2.17.3)(typescript@6.0.3)
     optionalDependencies:
       '@mermaid-js/mermaid-mindmap': 9.3.0
 
-  vitepress@1.6.4(@algolia/client-search@5.55.2)(@types/node@25.9.3)(lightningcss@1.32.0)(postcss@8.5.15)(search-insights@2.17.3)(typescript@6.0.3):
+  vitepress@1.6.4(@algolia/client-search@5.55.2)(@types/node@25.9.3)(@types/react@18.3.31)(lightningcss@1.32.0)(postcss@8.5.15)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(search-insights@2.17.3)(typescript@6.0.3):
     dependencies:
       '@docsearch/css': 3.8.2
-      '@docsearch/js': 3.8.2(@algolia/client-search@5.55.2)(search-insights@2.17.3)
+      '@docsearch/js': 3.8.2(@algolia/client-search@5.55.2)(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(search-insights@2.17.3)
       '@iconify-json/simple-icons': 1.2.90
       '@shikijs/core': 2.5.0
       '@shikijs/transformers': 2.5.0
@@ -12429,6 +13835,35 @@ snapshots:
       - typescript
       - universal-cookie
 
+  vitest@4.1.8(@types/node@22.20.0)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@6.4.3(@types/node@22.20.0)(jiti@2.7.0)(lightningcss@1.32.0)(tsx@4.22.4)(yaml@2.9.0)):
+    dependencies:
+      '@vitest/expect': 4.1.8
+      '@vitest/mocker': 4.1.8(vite@6.4.3(@types/node@22.20.0)(jiti@2.7.0)(lightningcss@1.32.0)(tsx@4.22.4)(yaml@2.9.0))
+      '@vitest/pretty-format': 4.1.8
+      '@vitest/runner': 4.1.8
+      '@vitest/snapshot': 4.1.8
+      '@vitest/spy': 4.1.8
+      '@vitest/utils': 4.1.8
+      es-module-lexer: 2.1.0
+      expect-type: 1.3.0
+      magic-string: 0.30.21
+      obug: 2.1.3
+      pathe: 2.0.3
+      picomatch: 4.0.4
+      std-env: 4.1.0
+      tinybench: 2.9.0
+      tinyexec: 1.2.4
+      tinyglobby: 0.2.17
+      tinyrainbow: 3.1.0
+      vite: 6.4.3(@types/node@22.20.0)(jiti@2.7.0)(lightningcss@1.32.0)(tsx@4.22.4)(yaml@2.9.0)
+      why-is-node-running: 2.3.0
+    optionalDependencies:
+      '@types/node': 22.20.0
+      '@vitest/coverage-v8': 4.1.8(vitest@4.1.8)
+      jsdom: 29.1.1
+    transitivePeerDependencies:
+      - msw
+
   vitest@4.1.8(@types/node@22.20.0)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@8.0.16(@types/node@22.20.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)):
     dependencies:
       '@vitest/expect': 4.1.8
@@ -12563,6 +13998,8 @@ snapshots:
 
   xmlchars@2.2.0: {}
 
+  yallist@3.1.1: {}
+
   yaml@2.9.0: {}
 
   yocto-queue@0.1.0: {}
@@ -12573,4 +14010,12 @@ snapshots:
 
   zod@4.4.3: {}
 
+  zustand@4.4.7(@types/react@18.3.31)(immer@10.2.0)(react@18.3.1):
+    dependencies:
+      use-sync-external-store: 1.2.0(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      immer: 10.2.0
+      react: 18.3.1
+
   zwitch@2.0.4: {}
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 62a78a2e69..ea61dd1e6d 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -1,6 +1,7 @@
 packages:
   - vendor/*
   - packages/*/*
+  - apps/*
   - website
   # The runnable demo leaves join as ONE workspace member: examples/package.json
   # declares the union of every leaf's cordis.yml plugins as workspace:*, so a
diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts
index 2a9cf01bdb..ac0854c413 100644
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -115,13 +115,35 @@ function expectedDshPackageFiles(manifest: PackageManifest): readonly string[] {
     'lib/invariant.js',
     ...manifest.bin ? ['lib/bin.js'] : [],
     ...manifest.exports?.['./worker'] ? ['lib/worker.cjs'] : [],
+    // UI plugin packages ship their browser bundle beside the node lib
+    // (single-artifact ruling: dist/ retired, ./client resolves lib/client.js).
+    // Keyed on the artifact path, not the subpath name: apiproxy's ./client is
+    // a browser-safe source channel, not a bundle.
+    ...manifest.exports?.['./client']?.default === './lib/client.js' ? ['lib/client.js'] : [],
+    // runtime's shell-held loader subpath ships as its own bundle beside the client half.
+    ...manifest.exports?.['./loader']?.default === './lib/loader.js' ? ['lib/loader.js'] : [],
+    // web-react's store subpath ships its own bundle (single-entry builds; no shared chunk).
+    ...manifest.exports?.['./store']?.default === './lib/store/index.js' ? ['lib/store/index.js'] : [],
     ...extras,
+    // Subpaths whose runtime default is the tsc-emitted tree (lib/types/*.js —
+    // browser-safe source channels rehomed off src so plain Node can import
+    // them without type stripping) publish the emitted JS alongside the
+    // declarations.
+    ...usesEmittedTreeDefaults(manifest) ? ['lib/types/**/*.js'] : [],
     'lib/types/**/*.d.ts',
     'lib/types/**/*.d.ts.map',
     'src',
   ]
 }
 
+/** Whether any export's runtime default points into the tsc-emitted lib/types tree. */
+function usesEmittedTreeDefaults(manifest: PackageManifest): boolean {
+  return Object.values(manifest.exports ?? {}).some(entry =>
+    typeof entry === 'object' && entry !== null
+    && typeof (entry as { default?: unknown }).default === 'string'
+    && ((entry as { default: string }).default).startsWith('./lib/types/'))
+}
+
 function checkWorkspace({ dir, manifest }: WorkspaceManifest): string[] {
   const errors: string[] = []
   const label = manifest.name ?? dir
diff --git a/scripts/client-bundle-purity.spec.ts b/scripts/client-bundle-purity.spec.ts
new file mode 100644
index 0000000000..8f04e2f044
--- /dev/null
+++ b/scripts/client-bundle-purity.spec.ts
@@ -0,0 +1,60 @@
+/**
+ * Pins the client-bundle purity gate (tsdown preset resolveId classifier):
+ * a bare-name import of a module-table package must rewrite to its /client
+ * external form (inlining it duplicates runtime identity — the P0
+/* leak that is not an
+ * inline-safe wire layer must fail the build loudly.
+ */
+import { describe, expect, it } from 'vitest'
+import { CLIENT_EXTERNALS, clientBundle } from '../packages/client/tsdown.client.ts'
+
+type ResolveId = (source: string) => null | { id: string; external: boolean }
+
+function purityResolveId(): ResolveId {
+  // libEntry is spelled at every call site (no default) so the
+  // package-invariants text check can see the invariant entry per package.
+  const configs = clientBundle('@deepseek-ai/dsh-client-test', ['lib/types/index.js', 'lib/types/invariant.js'])
+  const plugins = (configs[1] as { plugins: { name: string; resolveId?: unknown }[] }).plugins
+  const gate = plugins.find(p => p.name === 'dsh-client-bundle-purity')
+  if (gate?.resolveId === undefined) throw new Error('purity plugin missing from client config')
+  return gate.resolveId as ResolveId
+}
+
+describe('client bundle purity gate', () => {
+  const resolveId = purityResolveId()
+
+  it('leaves table entries and non-scoped specifiers alone', () => {
+    expect(resolveId('@deepseek-ai/dsh-client-ui-slots')).toBeNull()
+    expect(resolveId('@deepseek-ai/dsh-client-runtime/client')).toBeNull()
+    expect(resolveId('react')).toBeNull()
+    expect(resolveId('zod')).toBeNull()
+  })
+
+  it('rewrites a bare table-package name to its external /client form (duplicate-instance prevention)', () => {
+    expect(resolveId('@deepseek-ai/dsh-client-connection')).toEqual({
+      id: '@deepseek-ai/dsh-client-connection/client',
+      external: true,
+    })
+    expect(resolveId('@deepseek-ai/dsh-client-ui-layout')).toEqual({
+      id: '@deepseek-ai/dsh-client-ui-layout/client',
+      external: true,
+    })
+  })
+
+  it('lets inline-safe wire layers inline', () => {
+    expect(resolveId('@deepseek-ai/dsh-host-apiproxy/api')).toBeNull()
+    expect(resolveId('@deepseek-ai/dsh-session/surface')).toBeNull()
+    expect(resolveId('@deepseek-ai/dsh-brand')).toBeNull()
+  })
+
+  it('throws on any other @deepseek-ai leak', () => {
+    expect(() => resolveId('@deepseek-ai/dsh-agent')).toThrow(/purity/)
+    expect(() => resolveId('@deepseek-ai/dsh-client-web')).toThrow(/purity/)
+  })
+
+  it('every /client external has no bare-name twin in the table (the rewrite assumption)', () => {
+    for (const entry of CLIENT_EXTERNALS) {
+      if (entry.endsWith('/client')) expect(CLIENT_EXTERNALS).not.toContain(entry.slice(0, -'/client'.length))
+    }
+  })
+})
diff --git a/scripts/doc-typecheck-paths.ts b/scripts/doc-typecheck-paths.ts
index 03b7edb118..dc5a6a9d05 100644
--- a/scripts/doc-typecheck-paths.ts
+++ b/scripts/doc-typecheck-paths.ts
@@ -1,11 +1,22 @@
 /** Map one workspace source alias target to its declaration-build target. */
 export function builtDeclarationPath(candidate: string): string {
+  // Two workspace shapes exist: whole-package entries end in /src, subpath
+  // wildcards (apiproxy's browser-safe /api and /client channels) in /src/*.
   if (candidate.endsWith('/src')) {
     return `${candidate.slice(0, -'/src'.length)}/lib/types`
   }
+  if (candidate.endsWith('/src/*')) {
+    return `${candidate.slice(0, -'/src/*'.length)}/lib/types/*`
+  }
   const sourceFile = /^(.*)\/src\/(.+)\.ts$/.exec(candidate)
   if (sourceFile?.[1] && sourceFile[2]) {
     return `${sourceFile[1]}/lib/types/${sourceFile[2]}.d.ts`
   }
+  // Directory subpath entries (web-react's /store, runtime's /client): the
+  // source dir maps to the same dir under lib/types (index resolution applies).
+  const sourceDir = /^(.*)\/src\/(.+)$/.exec(candidate)
+  if (sourceDir?.[1] && sourceDir[2]) {
+    return `${sourceDir[1]}/lib/types/${sourceDir[2]}`
+  }
   throw new Error(`doc-typecheck: cannot map workspace source path to built declarations: ${candidate}`)
 }
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 0d0fd1318b..486ed2914a 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -177,6 +177,9 @@ const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   CompactAgentContext: 'compaction service input is owned by packages/compact/compact/src/index.ts',
   CreateAgentOptions: 'agent creation contract is owned by packages/core/agent/README.md',
   InvariantInstaller: 'service-local contribution contract is owned by packages/support/invariants/README.md',
+  LocaleDict: 'service-local dictionary shape is owned by packages/client/i18n/src/index.ts',
+  ThemeTokens: 'service-local token dictionary is owned by packages/client/ui-theme/src/index.ts',
+  Translate: 'service-local bound translator is owned by packages/client/i18n/src/index.ts',
   InvariantRegistration: 'service-local lifecycle handle is owned by packages/support/invariants/README.md',
   PresetOption: 'deployment menu metadata is owned by packages/ui/permission/README.md',
   PresetSpec: 'deployment preset composition is owned by packages/ui/permission/README.md',
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 2de30b76a7..ed7e4d067b 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -195,10 +195,12 @@ function gatesForMode(selected: Mode): Gate[] {
       return [
         pnpmScript('runtime-closure', 'verify-runtime-closure', { label: 'runtime closure' }),
         pnpmScript('cordis-config', 'verify-cordis-config', { label: 'Cordis config' }),
+        pnpmScript('client-domain-graph', 'verify-client-domain-graph', { label: 'client domain graph' }),
         pnpmScript('test', 'test'),
         pnpmScript('duplication', 'duplication'),
         snapshotGate(),
         pnpmScript('build', 'build'),
+        pnpmScript('build:web', 'build:web'),
         ...hygieneLeafGates({ artifactNeeds: ['build'] }),
         ...docSyncLeafGates({
           docTypecheckNeeds: ['build'],
diff --git a/scripts/translation-pairing.manifest.json b/scripts/translation-pairing.manifest.json
index b34c66880f..b96b92c7a8 100644
--- a/scripts/translation-pairing.manifest.json
+++ b/scripts/translation-pairing.manifest.json
@@ -1,6 +1,13 @@
 {
   "requiredSince": "2026-07-14",
   "required": [
+    ".agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md",
+    ".agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md",
+    ".agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md",
+    ".agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md",
+    ".agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md",
+    ".agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md",
+    ".agents/notes/implemented/process/2026-07-19-web-styling-system.md",
     "README.md",
     "docs/cookbook/adding-a-package.md",
     "docs/cookbook/adding-a-tool.md",
@@ -23,9 +30,6 @@
     "docs/user/guide/index.md",
     "docs/user/guide/quickstart.md",
     "docs/user/index.md",
-    ".agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md",
-    ".agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md",
-    ".agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md",
     "python/README.md",
     "python/sdk-runtime/README.md",
     "python/sdk/README.md"
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index e24f7e4d77..e8788689e7 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -1,98 +1,416 @@
 {
   "comment": "Maps each ` ```ts type-equiv ` or ` ```ts public-api ` block (by doc + declared symbol + projection) to the source declaration and original JSDoc it must match. Omit projection for the complete declaration; use public-api with a ` ```ts public-api ` block for a body-stripped public class declaration. verify-type-equiv.ts enforces a 1:1 correspondence: every source-equivalence block has exactly one entry here, and every entry resolves to exactly one block. Add an entry when you add a source-equivalence block; remove it when you remove the block.",
   "entries": [
-    { "doc": "docs/core-data-structures/core.md", "symbol": "Branded", "source": "packages/util/brand/src/index.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "ContentBlockMap", "source": "packages/llm/llm/src/types.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "AssistantProvenance", "source": "packages/llm/llm/src/types.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "Message", "source": "packages/llm/llm/src/types.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "MessageSourceMap", "source": "packages/llm/llm/src/types.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "FinishReasonMap", "source": "packages/llm/llm/src/types.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "LlmProviderInfo", "source": "packages/llm/llm/src/types.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "LlmModelInfo", "source": "packages/llm/llm/src/types.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "LlmModelContext", "source": "packages/llm/llm/src/types.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "GenerateOptions", "source": "packages/llm/llm/src/types.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "ToolSchema", "source": "packages/llm/llm/src/types.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "LlmCallConfig", "source": "packages/llm/llm/src/call-config.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "AgentCancelCause", "source": "packages/core/agent/src/types.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "InjectOptions", "source": "packages/core/agent/src/types.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "Agent", "source": "packages/core/agent/src/types.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "HookContext", "source": "packages/core/agent/src/types.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "PromptDecision", "source": "packages/core/agent/src/types.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "ContinuationDecision", "source": "packages/core/agent/src/types.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "RequestError", "source": "packages/core/agent/src/types.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "RequestErrorDecision", "source": "packages/core/agent/src/types.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "ContinuationStop", "source": "packages/core/agent/src/types.ts" },
-    { "doc": "docs/core-data-structures/core.md", "symbol": "SessionStartSource", "source": "packages/core/agent/src/types.ts" },
-
-    { "doc": "docs/core-data-structures/scope.md", "symbol": "ScopeKey", "source": "packages/core/scope/src/index.ts" },
-    { "doc": "docs/core-data-structures/scope.md", "symbol": "Scoped", "source": "packages/core/scope/src/index.ts" },
-    { "doc": "docs/core-data-structures/scope.md", "symbol": "Scope", "source": "packages/core/scope/src/index.ts" },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "Branded",
+      "source": "packages/util/brand/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "ContentBlockMap",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "AssistantProvenance",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "Message",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "MessageSourceMap",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "FinishReasonMap",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "LlmProviderInfo",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "LlmModelInfo",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "LlmModelContext",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "GenerateOptions",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "ToolSchema",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "LlmCallConfig",
+      "source": "packages/llm/llm/src/call-config.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "SessionEvent",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "AgentCancelCause",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "InjectOptions",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "Agent",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "HookContext",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "PromptDecision",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "ContinuationDecision",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "RequestError",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "RequestErrorDecision",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "ContinuationStop",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "SessionStartSource",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/scope.md",
+      "symbol": "ScopeKey",
+      "source": "packages/core/scope/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/scope.md",
+      "symbol": "Scoped",
+      "source": "packages/core/scope/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/scope.md",
+      "symbol": "Scope",
+      "source": "packages/core/scope/src/index.ts"
+    },
     { "doc": "docs/core-data-structures/scope.md", "symbol": "ScopeLayer", "source": "packages/core/scope/src/store.ts" },
-
-    { "doc": "docs/core-data-structures/goal.md", "symbol": "GoalRef", "source": "packages/goal/goal/src/types.ts" },
-    { "doc": "docs/core-data-structures/goal.md", "symbol": "GoalPhase", "source": "packages/goal/goal/src/types.ts" },
-    { "doc": "docs/core-data-structures/goal.md", "symbol": "GoalBlockReason", "source": "packages/goal/goal/src/types.ts" },
-    { "doc": "docs/core-data-structures/goal.md", "symbol": "GoalSnapshot", "source": "packages/goal/goal/src/types.ts" },
-    { "doc": "docs/core-data-structures/goal.md", "symbol": "GoalView", "source": "packages/goal/goal/src/types.ts" },
-    { "doc": "docs/core-data-structures/goal.md", "symbol": "GoalSnapshotChangeMeta", "source": "packages/goal/goal/src/types.ts" },
-    { "doc": "docs/core-data-structures/goal.md", "symbol": "GoalClearChangeMeta", "source": "packages/goal/goal/src/types.ts" },
-    { "doc": "docs/core-data-structures/goal.md", "symbol": "GoalMessageSource", "source": "packages/goal/goal/src/types.ts" },
-    { "doc": "docs/core-data-structures/goal.md", "symbol": "CreateGoalRequest", "source": "packages/goal/goal/src/types.ts" },
-    { "doc": "docs/core-data-structures/goal.md", "symbol": "EditGoalRequest", "source": "packages/goal/goal/src/types.ts" },
-    { "doc": "docs/core-data-structures/goal.md", "symbol": "GoalChanged", "source": "packages/goal/goal/src/types.ts" },
-
-    { "doc": "docs/core-data-structures/commands.md", "symbol": "CommandInputDescriptor", "source": "packages/ui/commands/src/index.ts" },
-    { "doc": "docs/core-data-structures/commands.md", "symbol": "CommandDefinition", "source": "packages/ui/commands/src/index.ts" },
-    { "doc": "docs/core-data-structures/commands.md", "symbol": "CommandInvocation", "source": "packages/ui/commands/src/index.ts" },
-    { "doc": "docs/core-data-structures/commands.md", "symbol": "CommandResult", "source": "packages/ui/commands/src/index.ts" },
-    { "doc": "docs/core-data-structures/commands.md", "symbol": "CommandDescriptor", "source": "packages/ui/commands/src/index.ts" },
-    { "doc": "docs/core-data-structures/commands.md", "symbol": "ParsedCommand", "source": "packages/ui/commands/src/index.ts" },
-
-    { "doc": "docs/core-data-structures/system-prompt.md", "symbol": "AssembleContext", "source": "packages/core/system-prompt/src/index.ts" },
-    { "doc": "docs/core-data-structures/system-prompt.md", "symbol": "PromptSection", "source": "packages/core/system-prompt/src/index.ts" },
-    { "doc": "docs/core-data-structures/system-prompt.md", "symbol": "ToolProviderResult", "source": "packages/core/system-prompt/src/index.ts" },
-
-    { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "StreamChunk", "source": "packages/llm/llm/src/types.ts" },
-    { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "LlmFailure", "source": "packages/llm/llm/src/types.ts" },
-    { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "TokenUsage", "source": "packages/llm/llm/src/types.ts" },
-    { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "ContentBlockMap", "source": "packages/llm/llm/src/types.ts" },
-    { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "AppIdentity", "source": "packages/llm/llm/src/attribution.ts" },
-    { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "BlockAssembler", "source": "packages/llm/llm/src/assembler.ts", "projection": "public-api" },
-    { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "LlmAdapter", "source": "packages/llm/llm/src/index.ts", "projection": "public-api" },
-
-    { "doc": "docs/core-data-structures/token-meter.md", "symbol": "TokenMeasurement", "source": "packages/llm/token-meter/src/types.ts" },
-    { "doc": "docs/core-data-structures/token-meter.md", "symbol": "TokenSurfaceNode", "source": "packages/llm/token-meter/src/types.ts" },
-
-    { "doc": "docs/core-data-structures/session.md", "symbol": "SessionEventMap", "source": "packages/core/session/src/types.ts" },
+    {
+      "doc": "docs/core-data-structures/goal.md",
+      "symbol": "GoalRef",
+      "source": "packages/goal/goal/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/goal.md",
+      "symbol": "GoalPhase",
+      "source": "packages/goal/goal/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/goal.md",
+      "symbol": "GoalBlockReason",
+      "source": "packages/goal/goal/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/goal.md",
+      "symbol": "GoalSnapshot",
+      "source": "packages/goal/goal/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/goal.md",
+      "symbol": "GoalView",
+      "source": "packages/goal/goal/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/goal.md",
+      "symbol": "GoalSnapshotChangeMeta",
+      "source": "packages/goal/goal/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/goal.md",
+      "symbol": "GoalClearChangeMeta",
+      "source": "packages/goal/goal/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/goal.md",
+      "symbol": "GoalMessageSource",
+      "source": "packages/goal/goal/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/goal.md",
+      "symbol": "CreateGoalRequest",
+      "source": "packages/goal/goal/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/goal.md",
+      "symbol": "EditGoalRequest",
+      "source": "packages/goal/goal/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/goal.md",
+      "symbol": "GoalChanged",
+      "source": "packages/goal/goal/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/commands.md",
+      "symbol": "CommandInputDescriptor",
+      "source": "packages/ui/commands/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/commands.md",
+      "symbol": "CommandDefinition",
+      "source": "packages/ui/commands/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/commands.md",
+      "symbol": "CommandInvocation",
+      "source": "packages/ui/commands/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/commands.md",
+      "symbol": "CommandResult",
+      "source": "packages/ui/commands/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/commands.md",
+      "symbol": "CommandDescriptor",
+      "source": "packages/ui/commands/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/commands.md",
+      "symbol": "ParsedCommand",
+      "source": "packages/ui/commands/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/system-prompt.md",
+      "symbol": "AssembleContext",
+      "source": "packages/core/system-prompt/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/system-prompt.md",
+      "symbol": "PromptSection",
+      "source": "packages/core/system-prompt/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/system-prompt.md",
+      "symbol": "ToolProviderResult",
+      "source": "packages/core/system-prompt/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/llm-streaming.md",
+      "symbol": "StreamChunk",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/llm-streaming.md",
+      "symbol": "LlmFailure",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/llm-streaming.md",
+      "symbol": "TokenUsage",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/llm-streaming.md",
+      "symbol": "ContentBlockMap",
+      "source": "packages/llm/llm/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/llm-streaming.md",
+      "symbol": "AppIdentity",
+      "source": "packages/llm/llm/src/attribution.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/llm-streaming.md",
+      "symbol": "BlockAssembler",
+      "source": "packages/llm/llm/src/assembler.ts",
+      "projection": "public-api"
+    },
+    {
+      "doc": "docs/core-data-structures/llm-streaming.md",
+      "symbol": "LlmAdapter",
+      "source": "packages/llm/llm/src/index.ts",
+      "projection": "public-api"
+    },
+    {
+      "doc": "docs/core-data-structures/token-meter.md",
+      "symbol": "TokenMeasurement",
+      "source": "packages/llm/token-meter/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/token-meter.md",
+      "symbol": "TokenSurfaceNode",
+      "source": "packages/llm/token-meter/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.md",
+      "symbol": "SessionEventMap",
+      "source": "packages/core/session/src/types.ts"
+    },
     { "doc": "docs/core-data-structures/session.md", "symbol": "OutOfBandSessionEventMap", "source": "packages/core/session/src/types.ts" },
-    { "doc": "docs/core-data-structures/session.md", "symbol": "EpochHeader", "source": "packages/core/session/src/types.ts" },
-    { "doc": "docs/core-data-structures/session.md", "symbol": "TodoItem", "source": "packages/core/session/src/types.ts" },
-    { "doc": "docs/core-data-structures/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" },
-    { "doc": "docs/core-data-structures/session.md", "symbol": "TurnTriggerMap", "source": "packages/core/session/src/types.ts" },
-    { "doc": "docs/core-data-structures/session.md", "symbol": "TurnEndReasonMap", "source": "packages/core/session/src/types.ts" },
-    { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceEventType", "source": "packages/core/session/src/types.ts" },
-    { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceOp", "source": "packages/core/session/src/types.ts" },
-    { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceIntent", "source": "packages/core/session/src/types.ts" },
-    { "doc": "docs/core-data-structures/session.md", "symbol": "SessionSurface", "source": "packages/core/session/src/surface.ts" },
-    { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceFoldReplacement", "source": "packages/core/session/src/surface.ts" },
-    { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceFoldResult", "source": "packages/core/session/src/surface.ts" },
-    { "doc": "docs/core-data-structures/session.md", "symbol": "Session", "source": "packages/core/session/src/index.ts", "projection": "public-api" },
-
-    { "doc": "docs/core-data-structures/persistence.md", "symbol": "SessionHeader", "source": "packages/core/session/src/types.ts" },
-    { "doc": "docs/core-data-structures/persistence.md", "symbol": "CreateSessionOptions", "source": "packages/core/session/src/types.ts" },
-    { "doc": "docs/core-data-structures/persistence.md", "symbol": "SessionLocation", "source": "packages/session-persistence/session-persistence/src/index.ts" },
-
-    { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionEventSurface", "source": "packages/session-query/session-query/src/types.ts" },
-    { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionRecord", "source": "packages/session-query/session-query/src/types.ts" },
-    { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionEventRecord", "source": "packages/session-query/session-query/src/types.ts" },
-    { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionLineageNode", "source": "packages/session-query/session-query/src/types.ts" },
-    { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionLineageTrace", "source": "packages/session-query/session-query/src/types.ts" },
-    { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionQueryErrorCode", "source": "packages/session-query/session-query/src/config.ts" },
-    { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionEventReadRequest", "source": "packages/session-query/session-query/src/types.ts" },
-    { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionEventWindow", "source": "packages/session-query/session-query/src/types.ts" },
-    { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionEventTraceRequest", "source": "packages/session-query/session-query/src/types.ts" },
-    { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionEventTrace", "source": "packages/session-query/session-query/src/types.ts" },
+    {
+      "doc": "docs/core-data-structures/session.md",
+      "symbol": "EpochHeader",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.md",
+      "symbol": "TodoItem",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.md",
+      "symbol": "SessionEvent",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.md",
+      "symbol": "TurnTriggerMap",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.md",
+      "symbol": "TurnEndReasonMap",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.md",
+      "symbol": "SurfaceEventType",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.md",
+      "symbol": "SurfaceOp",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.md",
+      "symbol": "SurfaceIntent",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.md",
+      "symbol": "SessionSurface",
+      "source": "packages/core/session/src/surface.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.md",
+      "symbol": "SurfaceFoldReplacement",
+      "source": "packages/core/session/src/surface.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.md",
+      "symbol": "SurfaceFoldResult",
+      "source": "packages/core/session/src/surface.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session.md",
+      "symbol": "Session",
+      "source": "packages/core/session/src/index.ts",
+      "projection": "public-api"
+    },
+    {
+      "doc": "docs/core-data-structures/persistence.md",
+      "symbol": "SessionHeader",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/persistence.md",
+      "symbol": "CreateSessionOptions",
+      "source": "packages/core/session/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/persistence.md",
+      "symbol": "SessionLocation",
+      "source": "packages/session-persistence/session-persistence/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionEventSurface",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionRecord",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionEventRecord",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionLineageNode",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionLineageTrace",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionQueryErrorCode",
+      "source": "packages/session-query/session-query/src/config.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionEventReadRequest",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionEventWindow",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionEventTraceRequest",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionEventTrace",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
 
     { "doc": "docs/core-data-structures/session-title.md", "symbol": "SessionTitleProviderId", "source": "packages/session-title/session-title/src/index.ts" },
     { "doc": "docs/core-data-structures/session-title.md", "symbol": "SessionTitleModelProvenance", "source": "packages/session-title/session-title/src/index.ts" },
@@ -105,132 +423,565 @@
     { "doc": "docs/core-data-structures/session-title.md", "symbol": "SessionTitleProviderRequest", "source": "packages/session-title/session-title/src/index.ts" },
     { "doc": "docs/core-data-structures/session-title.md", "symbol": "SessionTitleProviderResult", "source": "packages/session-title/session-title/src/index.ts" },
     { "doc": "docs/core-data-structures/session-title.md", "symbol": "SessionTitleProvider", "source": "packages/session-title/session-title/src/index.ts" },
-
-    { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolDefinition", "source": "packages/core/tools/src/index.ts" },
-    { "doc": "docs/core-data-structures/tools.md", "symbol": "SchemaProp", "source": "packages/core/tools/src/schema.ts" },
-    { "doc": "docs/core-data-structures/tools.md", "symbol": "SchemaSpec", "source": "packages/core/tools/src/schema.ts" },
-    { "doc": "docs/core-data-structures/tools.md", "symbol": "InferArgs", "source": "packages/core/tools/src/schema.ts" },
-    { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecutionToken", "source": "packages/core/tools/src/index.ts" },
-    { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecutionInput", "source": "packages/core/tools/src/index.ts" },
-    { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecution", "source": "packages/core/tools/src/index.ts" },
-    { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolDispatchExecution", "source": "packages/core/tools/src/index.ts" },
-    { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecutionMode", "source": "packages/core/tools/src/index.ts" },
-    { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolRunContext", "source": "packages/core/tools/src/index.ts" },
-    { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolGuard", "source": "packages/core/tools/src/index.ts" },
-    { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolRestriction", "source": "packages/core/tools/src/index.ts" },
-    { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecutionResult", "source": "packages/core/tools/src/index.ts" },
-    { "doc": "docs/core-data-structures/tools.md", "symbol": "PreToolDecision", "source": "packages/core/tools/src/index.ts" },
-    { "doc": "docs/core-data-structures/tools.md", "symbol": "PostToolDecision", "source": "packages/core/tools/src/index.ts" },
-    { "doc": "docs/core-data-structures/tools.md", "symbol": "StructuredScalar", "source": "packages/core/tools/src/json-schema.ts" },
-    { "doc": "docs/core-data-structures/tools.md", "symbol": "StructuredSchemaType", "source": "packages/core/tools/src/json-schema.ts" },
-    { "doc": "docs/core-data-structures/tools.md", "symbol": "StructuredSchemaNode", "source": "packages/core/tools/src/json-schema.ts" },
-    { "doc": "docs/core-data-structures/tools.md", "symbol": "StructuredOutputSchema", "source": "packages/core/tools/src/json-schema.ts" },
-
-    { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionOption", "source": "packages/ui/user-interaction/src/index.ts" },
-    { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionItem", "source": "packages/ui/user-interaction/src/index.ts" },
-    { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionRequest", "source": "packages/ui/user-interaction/src/index.ts" },
-    { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionAnswerItem", "source": "packages/ui/user-interaction/src/index.ts" },
-    { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionAnswer", "source": "packages/ui/user-interaction/src/index.ts" },
-    { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "UserInteractionProvider", "source": "packages/ui/user-interaction/src/index.ts" },
-    { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "UserInteractionError", "source": "packages/ui/user-interaction/src/index.ts" },
-
-    { "doc": "docs/core-data-structures/approval.md", "symbol": "ApprovalRequestId", "source": "packages/ui/user-approval/src/index.ts" },
-    { "doc": "docs/core-data-structures/approval.md", "symbol": "ApprovalOutcome", "source": "packages/ui/user-approval/src/index.ts" },
-    { "doc": "docs/core-data-structures/approval.md", "symbol": "ApprovalPolicy", "source": "packages/ui/user-approval/src/index.ts" },
-    { "doc": "docs/core-data-structures/approval.md", "symbol": "ApprovalRequest", "source": "packages/ui/user-approval/src/index.ts" },
-
-    { "doc": "docs/core-data-structures/bash.md", "symbol": "DshEnvironmentKey", "source": "packages/bash/bash/src/types.ts" },
-    { "doc": "docs/core-data-structures/bash.md", "symbol": "DshEnvironment", "source": "packages/bash/bash/src/types.ts" },
-    { "doc": "docs/core-data-structures/bash.md", "symbol": "BashExecRequest", "source": "packages/bash/bash/src/types.ts" },
-    { "doc": "docs/core-data-structures/bash.md", "symbol": "BashExecSpec", "source": "packages/bash/bash/src/types.ts" },
-    { "doc": "docs/core-data-structures/bash.md", "symbol": "BashRunResult", "source": "packages/bash/bash/src/types.ts" },
-    { "doc": "docs/core-data-structures/bash.md", "symbol": "BashSandboxInfo", "source": "packages/bash/bash/src/types.ts" },
-    { "doc": "docs/core-data-structures/bash.md", "symbol": "CollectedOutput", "source": "packages/bash/bash/src/types.ts" },
-    { "doc": "docs/core-data-structures/bash.md", "symbol": "BashProcess", "source": "packages/bash/bash/src/types.ts" },
-    { "doc": "docs/core-data-structures/bash.md", "symbol": "BashProcessRead", "source": "packages/bash/bash/src/types.ts" },
-
-    { "doc": "docs/core-data-structures/tasks.md", "symbol": "TaskKindMap", "source": "packages/tasks/tasks/src/types.ts" },
-    { "doc": "docs/core-data-structures/tasks.md", "symbol": "TaskStart", "source": "packages/tasks/tasks/src/types.ts" },
-    { "doc": "docs/core-data-structures/tasks.md", "symbol": "TaskHooks", "source": "packages/tasks/tasks/src/types.ts" },
-    { "doc": "docs/core-data-structures/tasks.md", "symbol": "TaskOutcome", "source": "packages/tasks/tasks/src/types.ts" },
-    { "doc": "docs/core-data-structures/tasks.md", "symbol": "TaskSnapshot", "source": "packages/tasks/tasks/src/types.ts" },
-    { "doc": "docs/core-data-structures/tasks.md", "symbol": "TaskRead", "source": "packages/tasks/tasks/src/types.ts" },
-
-    { "doc": "docs/core-data-structures/sandbox.md", "symbol": "SandboxMode", "source": "packages/sandbox/sandbox/src/index.ts" },
-    { "doc": "docs/core-data-structures/sandbox.md", "symbol": "ConfinedSandboxMode", "source": "packages/sandbox/sandbox/src/index.ts" },
-    { "doc": "docs/core-data-structures/sandbox.md", "symbol": "SandboxEnforcement", "source": "packages/sandbox/sandbox/src/index.ts" },
-    { "doc": "docs/core-data-structures/sandbox.md", "symbol": "SandboxPolicy", "source": "packages/sandbox/sandbox/src/index.ts" },
-    { "doc": "docs/core-data-structures/sandbox.md", "symbol": "ConfinedArgv", "source": "packages/sandbox/sandbox/src/index.ts" },
-
-    { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeRunRequest", "source": "packages/code-runtime/code-runtime/src/types.ts" },
-    { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeRunResult", "source": "packages/code-runtime/code-runtime/src/types.ts" },
-    { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeBindingNamespace", "source": "packages/code-runtime/code-runtime/src/types.ts" },
-    { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeBindingFunction", "source": "packages/code-runtime/code-runtime/src/types.ts" },
-    { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeRunFailure", "source": "packages/code-runtime/code-runtime/src/types.ts" },
-
-    { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsTarget", "source": "packages/fs/fs/src/types.ts" },
-    { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsTargetKey", "source": "packages/fs/fs/src/types.ts" },
-    { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsVersion", "source": "packages/fs/fs/src/types.ts" },
-    { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsInfo", "source": "packages/fs/fs/src/types.ts" },
-    { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsPathInfo", "source": "packages/fs/fs/src/types.ts" },
-    { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsDirEntry", "source": "packages/fs/fs/src/types.ts" },
-    { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsWriteIntent", "source": "packages/fs/fs/src/types.ts" },
-    { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsWriteOutcome", "source": "packages/fs/fs/src/types.ts" },
-    { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsEditRequest", "source": "packages/fs/fs/src/types.ts" },
-    { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsEditOutcome", "source": "packages/fs/fs/src/types.ts" },
-    { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsErrorCode", "source": "packages/fs/fs/src/types.ts" },
-    { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsPolicyExec", "source": "packages/fs/fs-policy/src/types.ts" },
-    { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FileReadOutcome", "source": "packages/fs/tool-fs/src/read-render.ts" },
-
-    { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillSource", "source": "packages/skill/skill/src/index.ts" },
-    { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillResourceBase", "source": "packages/skill/skill/src/index.ts" },
-    { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillSummary", "source": "packages/skill/skill/src/index.ts" },
-    { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillCandidate", "source": "packages/skill/skill/src/index.ts" },
-    { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillDefinition", "source": "packages/skill/skill/src/index.ts" },
-    { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillRegistration", "source": "packages/skill/skill/src/index.ts" },
-    { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillLookupOptions", "source": "packages/skill/skill/src/index.ts" },
-    { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillProvider", "source": "packages/skill/skill/src/index.ts" },
-    { "doc": "docs/core-data-structures/skills.md", "symbol": "Config", "source": "packages/skill/skill/src/index.ts" },
-
-    { "doc": "docs/core-data-structures/compaction.md", "symbol": "CompactionResult", "source": "packages/compact/compact/src/types.ts" },
-    { "doc": "docs/core-data-structures/compaction.md", "symbol": "CompactionTrigger", "source": "packages/compact/compact/src/index.ts" },
-    { "doc": "docs/core-data-structures/compaction.md", "symbol": "PrunedEntry", "source": "packages/compact/compact-tool-result-prune/src/types.ts" },
-    { "doc": "docs/core-data-structures/compaction.md", "symbol": "PruneResult", "source": "packages/compact/compact-tool-result-prune/src/types.ts" },
-
-    { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentCapabilities", "source": "packages/subagent/subagent/src/types.ts" },
-    { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentStartRequest", "source": "packages/subagent/subagent/src/types.ts" },
-    { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentResult", "source": "packages/subagent/subagent/src/types.ts" },
-    { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentStopReasonMap", "source": "packages/subagent/subagent/src/types.ts" },
-    { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentRun", "source": "packages/subagent/subagent/src/types.ts" },
-    { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentProvider", "source": "packages/subagent/subagent/src/types.ts" },
-
-    { "doc": "docs/core-data-structures/web.md", "symbol": "WebSearchRequest", "source": "packages/web/web/src/types.ts" },
-    { "doc": "docs/core-data-structures/web.md", "symbol": "WebSearchResult", "source": "packages/web/web/src/types.ts" },
-    { "doc": "docs/core-data-structures/web.md", "symbol": "WebSearchSource", "source": "packages/web/web/src/types.ts" },
-    { "doc": "docs/core-data-structures/web.md", "symbol": "WebFetchRequest", "source": "packages/web/web/src/types.ts" },
-    { "doc": "docs/core-data-structures/web.md", "symbol": "WebFetchResult", "source": "packages/web/web/src/types.ts" },
-    { "doc": "docs/core-data-structures/web.md", "symbol": "WebFetchBody", "source": "packages/web/web/src/types.ts" },
-
-    { "doc": "docs/core-data-structures/spill.md", "symbol": "SaveTextSpill", "source": "packages/spill/spill/src/types.ts" },
-    { "doc": "docs/core-data-structures/spill.md", "symbol": "SpillOwner", "source": "packages/spill/spill/src/types.ts" },
-    { "doc": "docs/core-data-structures/spill.md", "symbol": "SpillSource", "source": "packages/spill/spill/src/types.ts" },
-    { "doc": "docs/core-data-structures/spill.md", "symbol": "SpillRef", "source": "packages/spill/spill/src/types.ts" },
-    { "doc": "docs/core-data-structures/spill.md", "symbol": "SpillLocator", "source": "packages/spill/spill/src/types.ts" },
-
-    { "doc": "docs/core-data-structures/workflow.md", "symbol": "WorkflowStartRequest", "source": "packages/workflow/workflow/src/types.ts" },
-    { "doc": "docs/core-data-structures/workflow.md", "symbol": "WorkflowMeta", "source": "packages/workflow/workflow/src/types.ts" },
-    { "doc": "docs/core-data-structures/workflow.md", "symbol": "WorkflowResult", "source": "packages/workflow/workflow/src/types.ts" },
-    { "doc": "docs/core-data-structures/workflow.md", "symbol": "WorkflowRun", "source": "packages/workflow/workflow/src/types.ts" },
-
-    { "doc": "docs/core-data-structures/lsp.md", "symbol": "LspOperation", "source": "packages/lsp/lsp/src/types.ts" },
-    { "doc": "docs/core-data-structures/lsp.md", "symbol": "LspPosition", "source": "packages/lsp/lsp/src/types.ts" },
-    { "doc": "docs/core-data-structures/lsp.md", "symbol": "LspRange", "source": "packages/lsp/lsp/src/types.ts" },
-    { "doc": "docs/core-data-structures/lsp.md", "symbol": "LspQueryRequest", "source": "packages/lsp/lsp/src/types.ts" },
-    { "doc": "docs/core-data-structures/lsp.md", "symbol": "LspProviderQuery", "source": "packages/lsp/lsp/src/types.ts" },
-    { "doc": "docs/core-data-structures/lsp.md", "symbol": "LspLocation", "source": "packages/lsp/lsp/src/types.ts" },
-    { "doc": "docs/core-data-structures/lsp.md", "symbol": "LspHover", "source": "packages/lsp/lsp/src/types.ts" },
-    { "doc": "docs/core-data-structures/lsp.md", "symbol": "LspQueryResult", "source": "packages/lsp/lsp/src/types.ts" },
-    { "doc": "docs/core-data-structures/lsp.md", "symbol": "LspProvider", "source": "packages/lsp/lsp/src/types.ts" },
-    { "doc": "docs/core-data-structures/lsp.md", "symbol": "LspService", "source": "packages/lsp/lsp/src/types.ts" }
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "ToolDefinition",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "SchemaProp",
+      "source": "packages/core/tools/src/schema.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "SchemaSpec",
+      "source": "packages/core/tools/src/schema.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "InferArgs",
+      "source": "packages/core/tools/src/schema.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "ToolExecutionToken",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "ToolExecutionInput",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "ToolExecution",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "ToolDispatchExecution",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "ToolExecutionMode",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "ToolRunContext",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "ToolGuard",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "ToolRestriction",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "ToolExecutionResult",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "PreToolDecision",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "PostToolDecision",
+      "source": "packages/core/tools/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "StructuredScalar",
+      "source": "packages/core/tools/src/json-schema.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "StructuredSchemaType",
+      "source": "packages/core/tools/src/json-schema.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "StructuredSchemaNode",
+      "source": "packages/core/tools/src/json-schema.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tools.md",
+      "symbol": "StructuredOutputSchema",
+      "source": "packages/core/tools/src/json-schema.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/user-interaction.md",
+      "symbol": "AskUserQuestionOption",
+      "source": "packages/ui/user-interaction/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/user-interaction.md",
+      "symbol": "AskUserQuestionItem",
+      "source": "packages/ui/user-interaction/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/user-interaction.md",
+      "symbol": "AskUserQuestionRequest",
+      "source": "packages/ui/user-interaction/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/user-interaction.md",
+      "symbol": "AskUserQuestionAnswerItem",
+      "source": "packages/ui/user-interaction/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/user-interaction.md",
+      "symbol": "AskUserQuestionAnswer",
+      "source": "packages/ui/user-interaction/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/user-interaction.md",
+      "symbol": "UserInteractionProvider",
+      "source": "packages/ui/user-interaction/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/user-interaction.md",
+      "symbol": "UserInteractionError",
+      "source": "packages/ui/user-interaction/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/approval.md",
+      "symbol": "ApprovalRequestId",
+      "source": "packages/ui/user-approval/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/approval.md",
+      "symbol": "ApprovalOutcome",
+      "source": "packages/ui/user-approval/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/approval.md",
+      "symbol": "ApprovalPolicy",
+      "source": "packages/ui/user-approval/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/approval.md",
+      "symbol": "ApprovalRequest",
+      "source": "packages/ui/user-approval/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/bash.md",
+      "symbol": "DshEnvironmentKey",
+      "source": "packages/bash/bash/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/bash.md",
+      "symbol": "DshEnvironment",
+      "source": "packages/bash/bash/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/bash.md",
+      "symbol": "BashExecRequest",
+      "source": "packages/bash/bash/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/bash.md",
+      "symbol": "BashExecSpec",
+      "source": "packages/bash/bash/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/bash.md",
+      "symbol": "BashRunResult",
+      "source": "packages/bash/bash/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/bash.md",
+      "symbol": "BashSandboxInfo",
+      "source": "packages/bash/bash/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/bash.md",
+      "symbol": "CollectedOutput",
+      "source": "packages/bash/bash/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/bash.md",
+      "symbol": "BashProcess",
+      "source": "packages/bash/bash/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/bash.md",
+      "symbol": "BashProcessRead",
+      "source": "packages/bash/bash/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tasks.md",
+      "symbol": "TaskKindMap",
+      "source": "packages/tasks/tasks/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tasks.md",
+      "symbol": "TaskStart",
+      "source": "packages/tasks/tasks/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tasks.md",
+      "symbol": "TaskHooks",
+      "source": "packages/tasks/tasks/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tasks.md",
+      "symbol": "TaskOutcome",
+      "source": "packages/tasks/tasks/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tasks.md",
+      "symbol": "TaskSnapshot",
+      "source": "packages/tasks/tasks/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/tasks.md",
+      "symbol": "TaskRead",
+      "source": "packages/tasks/tasks/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/sandbox.md",
+      "symbol": "SandboxMode",
+      "source": "packages/sandbox/sandbox/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/sandbox.md",
+      "symbol": "ConfinedSandboxMode",
+      "source": "packages/sandbox/sandbox/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/sandbox.md",
+      "symbol": "SandboxEnforcement",
+      "source": "packages/sandbox/sandbox/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/sandbox.md",
+      "symbol": "SandboxPolicy",
+      "source": "packages/sandbox/sandbox/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/sandbox.md",
+      "symbol": "ConfinedArgv",
+      "source": "packages/sandbox/sandbox/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/code-runtime.md",
+      "symbol": "CodeRunRequest",
+      "source": "packages/code-runtime/code-runtime/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/code-runtime.md",
+      "symbol": "CodeRunResult",
+      "source": "packages/code-runtime/code-runtime/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/code-runtime.md",
+      "symbol": "CodeBindingNamespace",
+      "source": "packages/code-runtime/code-runtime/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/code-runtime.md",
+      "symbol": "CodeBindingFunction",
+      "source": "packages/code-runtime/code-runtime/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/code-runtime.md",
+      "symbol": "CodeRunFailure",
+      "source": "packages/code-runtime/code-runtime/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.md",
+      "symbol": "FsTarget",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.md",
+      "symbol": "FsTargetKey",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.md",
+      "symbol": "FsVersion",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.md",
+      "symbol": "FsInfo",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.md",
+      "symbol": "FsPathInfo",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.md",
+      "symbol": "FsDirEntry",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.md",
+      "symbol": "FsWriteIntent",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.md",
+      "symbol": "FsWriteOutcome",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.md",
+      "symbol": "FsEditRequest",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.md",
+      "symbol": "FsEditOutcome",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.md",
+      "symbol": "FsErrorCode",
+      "source": "packages/fs/fs/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.md",
+      "symbol": "FsPolicyExec",
+      "source": "packages/fs/fs-policy/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/filesystem.md",
+      "symbol": "FileReadOutcome",
+      "source": "packages/fs/tool-fs/src/read-render.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/skills.md",
+      "symbol": "SkillSource",
+      "source": "packages/skill/skill/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/skills.md",
+      "symbol": "SkillResourceBase",
+      "source": "packages/skill/skill/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/skills.md",
+      "symbol": "SkillSummary",
+      "source": "packages/skill/skill/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/skills.md",
+      "symbol": "SkillCandidate",
+      "source": "packages/skill/skill/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/skills.md",
+      "symbol": "SkillDefinition",
+      "source": "packages/skill/skill/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/skills.md",
+      "symbol": "SkillRegistration",
+      "source": "packages/skill/skill/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/skills.md",
+      "symbol": "SkillLookupOptions",
+      "source": "packages/skill/skill/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/skills.md",
+      "symbol": "SkillProvider",
+      "source": "packages/skill/skill/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/skills.md",
+      "symbol": "Config",
+      "source": "packages/skill/skill/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/compaction.md",
+      "symbol": "CompactionResult",
+      "source": "packages/compact/compact/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/compaction.md",
+      "symbol": "CompactionTrigger",
+      "source": "packages/compact/compact/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/compaction.md",
+      "symbol": "PrunedEntry",
+      "source": "packages/compact/compact-tool-result-prune/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/compaction.md",
+      "symbol": "PruneResult",
+      "source": "packages/compact/compact-tool-result-prune/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "SubagentCapabilities",
+      "source": "packages/subagent/subagent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "SubagentStartRequest",
+      "source": "packages/subagent/subagent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "SubagentResult",
+      "source": "packages/subagent/subagent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "SubagentStopReasonMap",
+      "source": "packages/subagent/subagent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "SubagentRun",
+      "source": "packages/subagent/subagent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "SubagentProvider",
+      "source": "packages/subagent/subagent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/web.md",
+      "symbol": "WebSearchRequest",
+      "source": "packages/web/web/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/web.md",
+      "symbol": "WebSearchResult",
+      "source": "packages/web/web/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/web.md",
+      "symbol": "WebSearchSource",
+      "source": "packages/web/web/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/web.md",
+      "symbol": "WebFetchRequest",
+      "source": "packages/web/web/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/web.md",
+      "symbol": "WebFetchResult",
+      "source": "packages/web/web/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/web.md",
+      "symbol": "WebFetchBody",
+      "source": "packages/web/web/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/spill.md",
+      "symbol": "SaveTextSpill",
+      "source": "packages/spill/spill/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/spill.md",
+      "symbol": "SpillOwner",
+      "source": "packages/spill/spill/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/spill.md",
+      "symbol": "SpillSource",
+      "source": "packages/spill/spill/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/spill.md",
+      "symbol": "SpillRef",
+      "source": "packages/spill/spill/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/spill.md",
+      "symbol": "SpillLocator",
+      "source": "packages/spill/spill/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/workflow.md",
+      "symbol": "WorkflowStartRequest",
+      "source": "packages/workflow/workflow/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/workflow.md",
+      "symbol": "WorkflowMeta",
+      "source": "packages/workflow/workflow/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/workflow.md",
+      "symbol": "WorkflowResult",
+      "source": "packages/workflow/workflow/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/workflow.md",
+      "symbol": "WorkflowRun",
+      "source": "packages/workflow/workflow/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/lsp.md",
+      "symbol": "LspOperation",
+      "source": "packages/lsp/lsp/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/lsp.md",
+      "symbol": "LspPosition",
+      "source": "packages/lsp/lsp/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/lsp.md",
+      "symbol": "LspRange",
+      "source": "packages/lsp/lsp/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/lsp.md",
+      "symbol": "LspQueryRequest",
+      "source": "packages/lsp/lsp/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/lsp.md",
+      "symbol": "LspProviderQuery",
+      "source": "packages/lsp/lsp/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/lsp.md",
+      "symbol": "LspLocation",
+      "source": "packages/lsp/lsp/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/lsp.md",
+      "symbol": "LspHover",
+      "source": "packages/lsp/lsp/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/lsp.md",
+      "symbol": "LspQueryResult",
+      "source": "packages/lsp/lsp/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/lsp.md",
+      "symbol": "LspProvider",
+      "source": "packages/lsp/lsp/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/lsp.md",
+      "symbol": "LspService",
+      "source": "packages/lsp/lsp/src/types.ts"
+    }
   ]
 }
diff --git a/scripts/verify-client-domain-graph.ts b/scripts/verify-client-domain-graph.ts
new file mode 100644
index 0000000000..a0520f5fa6
--- /dev/null
+++ b/scripts/verify-client-domain-graph.ts
@@ -0,0 +1,102 @@
+/**
+ * Enforce intra-package domain layering inside `packages/client/*\/src/client/`.
+ * verify-module-graph covers package-level edges; this gate covers the
+ * directory level the future package split will land on: domain directories
+ * may import `contract/` and never each other, and only the assembly point
+ * (`apply.ts` / `index.ts`) may import across domains.
+ *
+ * Layer model (lower may not import higher):
+ *   0  contract/            shared contract surface (types + slot declarations)
+ *   1  <domain>/ + service  domain implementations (skeleton/, chat/, ...)
+ *   2  apply.ts, index.ts   assembly point and re-export shell
+ *
+ * Not yet wired into the gate sequence (loose-gate window); run directly:
+ *   pnpm exec tsx scripts/verify-client-domain-graph.ts
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+const root = resolve(import.meta.dirname, '..')
+const CLIENT_DIR = join(root, 'packages/client')
+
+/** Directory names treated as the shared contract layer (importable by all). */
+const CONTRACT_DIRS = new Set(['contract'])
+/** Top-level client files allowed to import across domains (assembly layer). */
+const ASSEMBLY_FILES = new Set(['apply.ts', 'index.ts', 'index.tsx'])
+
+interface Violation { file: string; imported: string; reason: string }
+
+/** Recursively list .ts/.tsx files under dir (relative paths). */
+function listSources(dir: string, prefix = ''): string[] {
+  const out: string[] = []
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name)
+    const rel = prefix ? `${prefix}/${name}` : name
+    if (statSync(full).isDirectory()) out.push(...listSources(full, rel))
+    else if (/\.tsx?$/.test(name) && !/\.legacy\./.test(name)) out.push(rel)
+  }
+  return out
+}
+
+/** First path segment of a client-relative file, or '' for top-level files. */
+function domainOf(rel: string): string {
+  const ix = rel.indexOf('/')
+  return ix === -1 ? '' : rel.slice(0, ix)
+}
+
+function checkPackage(pkgName: string, clientDir: string): Violation[] {
+  const violations: Violation[] = []
+  const files = listSources(clientDir)
+  for (const rel of files) {
+    const fromDomain = domainOf(rel)
+    const isAssembly = fromDomain === '' && ASSEMBLY_FILES.has(rel)
+    if (isAssembly) continue
+    const source = readFileSync(join(clientDir, rel), 'utf8')
+    for (const match of source.matchAll(/from\s+['"](\.[^'"]+)['"]/g)) {
+      const spec = match[1]
+      if (spec === undefined) continue
+      // Resolve the relative specifier against the importing file's directory
+      // to a client-dir-relative path.
+      const fromDir = rel.includes('/') ? rel.slice(0, rel.lastIndexOf('/')) : ''
+      const parts = (fromDir ? fromDir.split('/') : [])
+      for (const seg of spec.split('/')) {
+        if (seg === '.') continue
+        if (seg === '..') parts.pop()
+        else parts.push(seg)
+      }
+      const target = parts.join('/')
+      if (target.startsWith('..')) continue // out of client dir (package root) — package-level rules govern
+      const toDomain = domainOf(target)
+      if (toDomain === '' || CONTRACT_DIRS.has(toDomain)) continue // top-level shared file or contract layer
+      if (fromDomain === toDomain) continue // inside one domain
+      violations.push({
+        file: `${pkgName}/src/client/${rel}`,
+        imported: spec,
+        reason: fromDomain === ''
+          ? `top-level non-assembly file imports domain "${toDomain}" (only apply/index may assemble)`
+          : `domain "${fromDomain}" imports sibling domain "${toDomain}" (route shared surface through contract/)`,
+      })
+    }
+  }
+  return violations
+}
+
+const violations: Violation[] = []
+for (const pkg of readdirSync(CLIENT_DIR)) {
+  const clientDir = join(CLIENT_DIR, pkg, 'src/client')
+  try {
+    if (!statSync(clientDir).isDirectory()) continue
+  } catch {
+    // No client half in this package — nothing to layer-check.
+    continue
+  }
+  violations.push(...checkPackage(pkg, clientDir))
+}
+
+if (violations.length > 0) {
+  console.error(`verify-client-domain-graph: ${violations.length} violation(s):`)
+  for (const v of violations) console.error(`  ${v.file} -> ${v.imported}\n    ${v.reason}`)
+  process.exit(1)
+}
+console.log('verify-client-domain-graph: client domain layering clean.')
diff --git a/scripts/verify-cordis-config.ts b/scripts/verify-cordis-config.ts
index 88615ee57a..c9820a67a8 100644
--- a/scripts/verify-cordis-config.ts
+++ b/scripts/verify-cordis-config.ts
@@ -152,15 +152,29 @@ function localPackageDirectories(): Map<string, string> {
 }
 
 function rootProjectReferences(): Set<string> {
-  const config = ts.readConfigFile(resolve(root, 'tsconfig.json'), path => ts.sys.readFile(path))
-  if (config.error !== undefined) {
-    throw new Error(ts.flattenDiagnosticMessageText(config.error.messageText, '\n'))
+  // Typecheck runs two sibling aggregates (root = host program,
+  // tsconfig.client.json = client program; the two sides merge cordis Context
+  // under the same keys, so one program cannot see both). Seed both and follow
+  // any nested aggregate references to collect the covered leaf project set.
+  const collected = new Set<string>()
+  const queue = [resolve(root, 'tsconfig.json'), resolve(root, 'tsconfig.client.json')]
+  const seen = new Set<string>()
+  for (let file = queue.pop(); file !== undefined; file = queue.pop()) {
+    if (seen.has(file)) continue
+    seen.add(file)
+    const config = ts.readConfigFile(file, path => ts.sys.readFile(path))
+    if (config.error !== undefined) {
+      throw new Error(ts.flattenDiagnosticMessageText(config.error.messageText, '\n'))
+    }
+    const references = (config.config as { references?: Array<{ path?: unknown }> }).references ?? []
+    for (const reference of references) {
+      if (typeof reference.path !== 'string') continue
+      const target = resolve(dirname(file), reference.path)
+      if (target.endsWith('.json')) queue.push(target)
+      else collected.add(target)
+    }
   }
-  const references = (config.config as { references?: Array<{ path?: unknown }> }).references ?? []
-  return new Set(references.flatMap((reference) => {
-    if (typeof reference.path !== 'string') return []
-    return [resolve(root, reference.path)]
-  }))
+  return collected
 }
 
 function packageNameFromSpecifier(specifier: string): string | undefined {
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 11eef97698..6fc46dbdb8 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -45,11 +45,26 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/bash/bash-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-bash.' },
   'packages/code-runtime/code-runtime': { kind: 'indirect', reason: 'The service interface delegates model rendering to Code Mode in dsh-tools.' },
   'packages/code-runtime/code-runtime-worker': { kind: 'indirect', reason: 'The worker backend delegates model rendering to Code Mode in dsh-tools.' },
+  'packages/client/ui-slots': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/ui-primitives': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/web-react': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/connection': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/runtime': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/ui-layout': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/ui-sidebar': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/ui-conversation': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/ui-trajectory': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/ui-theme': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/i18n': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/web': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/examples/agent-spine-demo': { kind: 'indirect', reason: 'The bundle only mounts model-facing child plugins.' },
   'packages/fs/fs': { kind: 'indirect', reason: 'The service interface delegates model rendering to dsh-tool-fs.' },
   'packages/fs/fs-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-fs.' },
   'packages/fs/fs-sandbox': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-fs.' },
   'packages/hooks/hook-protocol': { kind: 'indirect', reason: 'Only the hook bridge plugins render decoded hook output to a model.' },
+  'packages/host/apiproxy': { kind: 'none', reason: 'The wire contract and fetch carriers move already-composed messages and register no model surface.' },
+  'packages/host/runtime': { kind: 'indirect', reason: 'The assembly mounts model-facing plugins and injects provider/model defaults into agents.' },
+  'packages/host/webserver': { kind: 'none', reason: 'The HTTP carrier bridges browser and API handler and registers no model surface.' },
   'packages/llm/llm': { kind: 'none', reason: 'The adapter registry forwards already-assembled requests unchanged.' },
   'packages/llm/token-meter': { kind: 'indirect', reason: 'The measurement service leaves model-visible changes to its consumers.' },
   'packages/lsp/lsp': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-lsp.' },
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 74463e5ff6..ee6ec2f993 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -36,6 +36,12 @@
       "@cordisjs/plugin-logger-console": ["./vendor/logger-console/src"],
       "@deepseek-ai/dsh-invariants": ["./packages/support/invariants/src/index.ts"],
       "@deepseek-ai/dsh-session/invariant": ["./packages/core/session/src/invariant.ts"],
+      "@deepseek-ai/dsh-session/types": ["./packages/core/session/src/types.ts"],
+      "@deepseek-ai/dsh-llm/types": ["./packages/llm/llm/src/types.ts"],
+      "@deepseek-ai/dsh-llm/brand": ["./packages/llm/llm/src/brand.ts"],
+      "@deepseek-ai/dsh-tools/presentation": ["./packages/core/tools/src/presentation.ts"],
+      "@deepseek-ai/dsh-user-approval/types": ["./packages/ui/user-approval/src/types.ts"],
+      "@deepseek-ai/dsh-user-interaction/types": ["./packages/ui/user-interaction/src/types.ts"],
       "@deepseek-ai/dsh-agent/invariant": ["./packages/core/agent/src/invariant.ts"],
       "@deepseek-ai/dsh-scope/invariant": ["./packages/core/scope/src/invariant.ts"],
       "@deepseek-ai/dsh-agent-loop/invariant": ["./packages/core/agent-loop/src/invariant.ts"],
@@ -75,6 +81,32 @@
       // unambiguous; adding a package under an existing group needs no edit
       // here. The build graph's project references (tsconfig.build.json) stay
       // explicit — TS project references have no wildcard form.
+      "@deepseek-ai/dsh-host-apiproxy": ["./packages/host/apiproxy/src"],
+      "@deepseek-ai/dsh-host-apiproxy/*": ["./packages/host/apiproxy/src/*"],
+      "@deepseek-ai/dsh-host-runtime": ["./packages/host/runtime/src"],
+      "@deepseek-ai/dsh-host-webserver": ["./packages/host/webserver/src"],
+      "@deepseek-ai/dsh-client-ui-slots": ["./packages/client/ui-slots/src"],
+      "@deepseek-ai/dsh-client-ui-primitives": ["./packages/client/ui-primitives/src"],
+      "@deepseek-ai/dsh-client-web-react": ["./packages/client/web-react/src"],
+      "@deepseek-ai/dsh-client-web-react/store": ["./packages/client/web-react/src/store"],
+      "@deepseek-ai/dsh-client-connection": ["./packages/client/connection/src"],
+      "@deepseek-ai/dsh-client-connection/client": ["./packages/client/connection/src/client"],
+      "@deepseek-ai/dsh-client-runtime": ["./packages/client/runtime/src"],
+      "@deepseek-ai/dsh-client-runtime/loader": ["./packages/client/runtime/src/client/loader"],
+      "@deepseek-ai/dsh-client-runtime/client": ["./packages/client/runtime/src/client"],
+      "@deepseek-ai/dsh-client-ui-layout": ["./packages/client/ui-layout/src"],
+      "@deepseek-ai/dsh-client-ui-layout/client": ["./packages/client/ui-layout/src/client"],
+      "@deepseek-ai/dsh-client-ui-sidebar": ["./packages/client/ui-sidebar/src"],
+      "@deepseek-ai/dsh-client-ui-sidebar/client": ["./packages/client/ui-sidebar/src/client"],
+      "@deepseek-ai/dsh-client-ui-conversation": ["./packages/client/ui-conversation/src"],
+      "@deepseek-ai/dsh-client-ui-conversation/client": ["./packages/client/ui-conversation/src/client"],
+      "@deepseek-ai/dsh-client-ui-trajectory": ["./packages/client/ui-trajectory/src"],
+      "@deepseek-ai/dsh-client-ui-trajectory/client": ["./packages/client/ui-trajectory/src/client"],
+      "@deepseek-ai/dsh-client-ui-theme": ["./packages/client/ui-theme/src"],
+      "@deepseek-ai/dsh-client-ui-theme/client": ["./packages/client/ui-theme/src/client"],
+      "@deepseek-ai/dsh-client-i18n": ["./packages/client/i18n/src"],
+      "@deepseek-ai/dsh-client-i18n/client": ["./packages/client/i18n/src/client"],
+      "@deepseek-ai/dsh-client-web": ["./packages/client/web/src"],
       "@deepseek-ai/dsh-*": [
         "./packages/core/*/src",
         "./packages/prompt/*/src",
@@ -106,7 +138,9 @@
         "./packages/examples/*/src",
         "./packages/util/*/src",
         "./packages/mcp/*/src",
-        "./packages/support/*/src"
+        "./packages/support/*/src",
+        "./packages/host/*/src",
+        "./packages/client/*/src"
       ]
     }
   }
diff --git a/tsconfig.build.json b/tsconfig.build.json
index e332336315..9800433ecb 100644
--- a/tsconfig.build.json
+++ b/tsconfig.build.json
@@ -108,6 +108,21 @@
     { "path": "./packages/hooks/hooks-claude" },
     { "path": "./packages/hooks/hooks-codex" },
     { "path": "./packages/mcp/mcp-client" },
+    { "path": "./packages/host/apiproxy" },
+    { "path": "./packages/host/runtime" },
+    { "path": "./packages/host/webserver" },
+    { "path": "./packages/client/ui-slots" },
+    { "path": "./packages/client/ui-primitives" },
+    { "path": "./packages/client/web-react" },
+    { "path": "./packages/client/connection" },
+    { "path": "./packages/client/runtime" },
+    { "path": "./packages/client/ui-layout" },
+    { "path": "./packages/client/ui-sidebar" },
+    { "path": "./packages/client/ui-conversation" },
+    { "path": "./packages/client/ui-trajectory" },
+    { "path": "./packages/client/ui-theme" },
+    { "path": "./packages/client/i18n" },
+    { "path": "./packages/client/web" },
     { "path": "./packages/sdk/helper" },
     { "path": "./packages/sdk/scripts" },
     { "path": "./packages/sdk/create-sdk" },
diff --git a/tsconfig.client.json b/tsconfig.client.json
new file mode 100644
index 0000000000..ceb498a1a9
--- /dev/null
+++ b/tsconfig.client.json
@@ -0,0 +1,42 @@
+{
+  // Client-side typecheck aggregate: packages/client tests (.ts and .tsx).
+  // Split from the host aggregate because both sides merge cordis Context
+  // under the same keys (sessions, loader) with different services; shared
+  // leaves (session/llm/tools/apiproxy/...) build once and are referenced by
+  // both programs through each client package's own references.
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rewriteRelativeImportExtensions": false,
+    "jsx": "react-jsx",
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    // Tests execute under vitest on node (e2e files spawn processes); browser
+    // purity of package src is each package's own tsconfig + verify-client-closure.
+    "types": ["node"]
+  },
+  "include": [
+    "packages/client/*/tests/**/*.ts",
+    "packages/client/*/tests/**/*.tsx",
+    "packages/client/tsdown.client.ts",
+    "scripts/client-bundle-purity.spec.ts"
+  ],
+  "references": [
+    // Shared leaf: web e2e boots the real host webserver (fixture + real-host
+    // smoke policy). webserver has zero workspace deps and no cordis merge,
+    // so it cannot drag host-side Context augmentation into this program.
+    { "path": "./packages/host/webserver" },
+    { "path": "./packages/client/ui-slots" },
+    { "path": "./packages/client/ui-primitives" },
+    { "path": "./packages/client/web-react" },
+    { "path": "./packages/client/connection" },
+    { "path": "./packages/client/runtime" },
+    { "path": "./packages/client/ui-layout" },
+    { "path": "./packages/client/ui-sidebar" },
+    { "path": "./packages/client/ui-conversation" },
+    { "path": "./packages/client/ui-trajectory" },
+    { "path": "./packages/client/ui-theme" },
+    { "path": "./packages/client/i18n" },
+    { "path": "./packages/client/web" },
+    { "path": "./apps/web" }
+  ]
+}
diff --git a/tsconfig.json b/tsconfig.json
index 295e2a6365..8648886d81 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,4 +1,6 @@
 {
+  // Host aggregate. packages/client type-checks in tsconfig.client.json: the two
+  // sides merge cordis Context under the same keys, one program cannot see both.
   "extends": "./tsconfig.base.json",
   "compilerOptions": {
     "noEmit": true,
@@ -13,6 +15,10 @@
     "website/**/*.ts",
     "website/.vitepress/**/*.ts"
   ],
+  "exclude": [
+    "packages/client/**",
+    "scripts/client-bundle-purity.spec.ts"
+  ],
   "references": [
     { "path": "./vendor/cosmokit" },
     { "path": "./vendor/schemastery" },
@@ -122,6 +128,9 @@
     { "path": "./packages/hooks/hooks-claude" },
     { "path": "./packages/hooks/hooks-codex" },
     { "path": "./packages/mcp/mcp-client" },
+    { "path": "./packages/host/apiproxy" },
+    { "path": "./packages/host/runtime" },
+    { "path": "./packages/host/webserver" },
     { "path": "./packages/sdk/helper" },
     { "path": "./packages/sdk/scripts" },
     { "path": "./packages/sdk/create-sdk" },
diff --git a/tsconfig.vitest.json b/tsconfig.vitest.json
new file mode 100644
index 0000000000..9cb8a888c6
--- /dev/null
+++ b/tsconfig.vitest.json
@@ -0,0 +1,15 @@
+{
+  // Path-map scope for vite-tsconfig-paths in vitest only (never a tsc -b target):
+  // widens include to package src and .tsx so bare workspace imports resolve to source.
+  "extends": "./tsconfig.base.json",
+  "include": [
+    "examples/*/src/**/*.ts",
+    "examples/*/start.ts",
+    "examples/*/tests/**/*.ts",
+    "packages/*/*/src/**/*.ts",
+    "packages/*/*/src/**/*.tsx",
+    "packages/*/*/tests/**/*.ts",
+    "packages/*/*/tests/**/*.tsx",
+    "scripts/**/*.ts"
+  ]
+}
diff --git a/vitest.config.ts b/vitest.config.ts
index 8baa7c7b32..569674637b 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -24,24 +24,31 @@ const windowsCoverageExclusions = process.platform === 'win32'
 
 export default defineConfig({
   // Native path resolution reads each package's nearest tsconfig, but only the root defines
-  // workspace paths. Keep this plugin pinned to the root map so unbuilt bare package imports resolve
-  // to source; native resolution would fall through to absent `lib/` outputs.
-  plugins: [tsconfigPaths({ projects: ['./tsconfig.json'] })],
+  // workspace paths. Keep this plugin pinned to the root map so bare package imports resolve
+  // to source — with built lib/ present, manifest-exports fallthrough would load a second
+  // copy of module singletons. tsconfig.vitest.json widens include to .tsx specs (the root
+  // include stops at .ts for tsc -b; the plugin scopes applicability by include).
+  plugins: [tsconfigPaths({ projects: ['./tsconfig.vitest.json'] })],
   test: {
     setupFiles: ['./scripts/test-invariants.ts'],
-    include: ['packages/*/*/tests/**/*.spec.ts', 'examples/*/tests/**/*.spec.ts', 'scripts/**/*.spec.ts'],
+    // .tsx: client component specs (jsdom via per-file @vitest-environment pragma).
+    include: ['packages/*/*/tests/**/*.spec.{ts,tsx}', 'examples/*/tests/**/*.spec.ts', 'scripts/**/*.spec.ts'],
     exclude: windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`),
     coverage: {
       provider: 'v8',
       // Coverage measures OUR runtime source. Types-only files carry no
       // executable code; vendor/ and examples/ are out of scope (examples are
       // exercised by the demo smoke test instead).
-      include: ['packages/*/*/src/**/*.ts'],
+      // .tsx: client components are gated like everything else (jsdom lane).
+      include: ['packages/*/*/src/**/*.{ts,tsx}'],
       // Types-only files have no runtime coverage. Importing self-executing bins/workers would boot
       // them inside the unit process, so real subprocess/Worker tests cover their thin entry glue.
       exclude: [
+        
         'packages/*/*/src/types.ts',
+       
         'packages/*/*/src/bin.ts',
+       
         'packages/*/*/src/worker.ts',
         ...windowsUnsupportedPackages.map(path => `${path}/src/**/*.ts`),
         ...windowsCoverageExclusions,
diff --git a/vitest.e2e.config.ts b/vitest.e2e.config.ts
index c5f26b90a3..97be1395b3 100644
--- a/vitest.e2e.config.ts
+++ b/vitest.e2e.config.ts
@@ -29,8 +29,13 @@ const e2eMaxWorkers = positiveIntFromEnv('DSH_E2E_MAX_WORKERS', DEFAULT_E2E_MAX_
 
 export default defineConfig({
   // Same resolution note as vitest.config.ts: bare workspace names resolve
-  // through the root tsconfig paths map; the native option cannot do this.
-  plugins: [tsconfigPaths({ projects: ['./tsconfig.json'] })],
+  // through the vitest-scoped tsconfig paths map (its include spans package
+  // src, so client-package sources get mapping too — the root tsconfig
+  // excludes packages/client, which would drop /client subpath imports onto
+  // package exports and load browser dist bundles into node). Built-artifact
+  // e2e suites are unaffected: their built-ness lives in subprocesses and
+  // createRequire lookups, which bypass vite resolution entirely.
+  plugins: [tsconfigPaths({ projects: ['./tsconfig.vitest.json'] })],
   test: {
     setupFiles: ['./scripts/test-invariants.ts'],
     include: ['packages/*/*/tests/**/*.e2e.ts', 'examples/*/tests/**/*.e2e.ts'],
diff --git a/vitest.web.config.ts b/vitest.web.config.ts
new file mode 100644
index 0000000000..765fb2e4a9
--- /dev/null
+++ b/vitest.web.config.ts
@@ -0,0 +1,30 @@
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vitest/config'
+
+// Web smoke lane (GUI, gate-exempt — not part of the CI sequence yet): built
+// page + real chromium, so it lives outside the unit/e2e includes. The
+// real-host test self-skips without DEEPSEEK_API_KEY; the fixture test is
+// keyless and deterministic.
+try {
+  // Node >= 21.7 native; throws when the file does not exist.
+  process.loadEnvFile(new URL('.env', import.meta.url).pathname)
+} catch {
+  // No .env — fine, the environment may already carry the variables.
+}
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      // apps/web/tests is outside the root tsconfig include, so the shared
+      // tsconfig-paths plugin never maps it; alias the one bare import to source.
+      '@deepseek-ai/dsh-host-webserver': fileURLToPath(new URL('packages/host/webserver/src/index.ts', import.meta.url)),
+    },
+  },
+  test: {
+    include: ['apps/web/tests/**/*.e2e.ts'],
+    // Browser boot + real-model turns are slow; files share one browser, run serial.
+    testTimeout: 180_000,
+    hookTimeout: 120_000,
+    fileParallelism: false,
+  },
+})