diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
index 612ab83bdd..d8ddbe592a 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
-2026-07-19-gui-web-client-architecture.md: 409c4347bca42dd96fd134e0133a1721fdaebd5d
-2026-07-19-gui-web-client-architecture.zh.md: 58235981471eeb365f7416fcd2e5530468e1e3ff
+2026-07-19-gui-web-client-architecture.md: 55421d1ad6df192d08c431af3633675036a4a857
+2026-07-19-gui-web-client-architecture.zh.md: 6fb3f9a512389710f6708b7f36f42e90eef11b28
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
index 409c4347bc..55421d1ad6 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
@@ -44,7 +44,7 @@ Implementation homes: registry core and the props-share types live in `packages/
 
 A service is a plugin's only API toward other plugins (UI components and injection faces are not APIs; a plugin nobody calls mounts no service — ui-trajectory is the minimal-plugin exemplar: no ctx service, only view-slot registrations). The roster: `ctx.connection` (RPC transport + generation state), `ctx.slots` (registry wrapper emitting `slots/changed`, render entry, renderer installation contract), `ctx.sessions` (list store, current-session state, scope tree), `ctx.loader`, `ctx.theme`, `ctx.i18n`, `ctx.layout` (cross-plugin view navigation), `ctx.conversation` (send/cancel/startSession). Viewing state that used to live in service stores (panel widths, selection, drafts) now lives in entry-declared stores per the [slot system standard](2026-07-22-slot-type-chain-implementation.md).
 
-There is no component registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Final Chat business Nodes dispatch through the keyed/session `'conversation.chat.node'` slot; ui-tool owns its `tool-call` entry, recursively renders the supplied `subCalls`, and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and roots and descendants dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>' }, Row))`; the declaration is the load and reload dependency ([decision](../../archived/architecture/2026-08-05-slot-declaration-injection.md)). ui-conversation separately delegates the selected call's details body through `'conversation.details.tool'`, so ui-tool's card models remain the single presentation owner without making conversation import Tool components. The target-neutral event and view registries are data assembly seams rather than parallel component registries ([decision](2026-08-09-client-conversation-node-assembly.md)).
+There is no component registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Final Chat business Nodes dispatch through the keyed/session `'conversation.chat.node'` slot; ui-tool owns its `tool-call` entry, recursively renders the supplied `subCalls`, and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and roots and descendants dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>' }, Row))`; the declaration is the load and reload dependency ([decision](../../archived/architecture/2026-08-05-slot-declaration-injection.md)). The right column is the `rightbar` seat ui-sidebar-right fills with one docking surface per session; the former details column and its `'conversation.details.tool'` seat are gone ([decision](../feature/2026-09-04-right-sidebar-docking-infrastructure.md)). The target-neutral event and view registries are data assembly seams rather than parallel component registries ([decision](2026-08-09-client-conversation-node-assembly.md)).
 
 **Scope addressing** mirrors the host's agent-scope idiom: services are root singletons whose methods take no sessionId — they read the caller's scope mark (`scopeOf(ctx)`). Inside a session scope, `ctx.conversation.send('hi', 'queue')` targets that session; cross-session calls re-target by switching ctx (`ctx.sessions.scope(id)!.conversation.send(...)`); calling a scoped method from root ctx throws. Client session scopes are minted like host agent scopes (a no-op plugin fiber + a scope-key extend), built lazily on first viewing and torn down only when the session is removed and unwatched — host-session death alone does not tear a scope (it freezes into a read-only viewport).
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
index 5823598147..6fb3f9a512 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
@@ -44,7 +44,7 @@ slot 体系有自己的笔记——[slot 体系标准](2026-07-22-slot-type-chai
 
 服务是插件对其他插件的唯一 API（UI 组件与注入面都不是 API；无人调用的插件不挂服务——ui-trajectory 即最小插件样板：无 ctx 服务，只做视图 slot 注册）。名册：`ctx.connection`（RPC 传输 + generation 状态）、`ctx.slots`（注册表包装层，发 `slots/changed`，渲染入口，渲染器安装约定）、`ctx.sessions`（列表 store、当前会话状态、scope 树）、`ctx.loader`、`ctx.theme`、`ctx.i18n`、`ctx.layout`（跨插件视图导航）、`ctx.conversation`（send/cancel/startSession）。过去住在服务 store 里的观看态（面板宽、选中、草稿）现按 [slot 体系标准](2026-07-22-slot-type-chain-implementation.zh.md) 住 entry 声明的 store。
 
-slot 之外不存在第二种组件注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list slot entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。最终 Chat 业务 Node 通过 keyed/session `'conversation.chat.node'` slot 分发；ui-tool 拥有其中的 `tool-call` entry，递归渲染传入的 `subCalls`，并声明 keyed/session `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与任意深度的后代都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>' }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](../../archived/architecture/2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托 selected call 的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。与 target 无关的事件注册表和视图注册表是数据组装 seam，不是平行组件注册表（[决策](2026-08-09-client-conversation-node-assembly.zh.md)）。
+slot 之外不存在第二种组件注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list slot entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。最终 Chat 业务 Node 通过 keyed/session `'conversation.chat.node'` slot 分发；ui-tool 拥有其中的 `tool-call` entry，递归渲染传入的 `subCalls`，并声明 keyed/session `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与任意深度的后代都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>' }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](../../archived/architecture/2026-08-05-slot-declaration-injection.md)）。右列是 ui-sidebar-right 以每会话一个停靠面填充的 `rightbar` 坑位；原来的详情列及其 `'conversation.details.tool'` 坑位已删除（[决策](../feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md)）。与 target 无关的事件注册表和视图注册表是数据组装 seam，不是平行组件注册表（[决策](2026-08-09-client-conversation-node-assembly.zh.md)）。
 
 **scope 寻址**与 host 侧 agent（智能体）scope 惯例同构：服务是 root 单例，方法不收 sessionId——它们读调用方 ctx 上的 scope 标（`scopeOf(ctx)`）。在会话 scope 内，`ctx.conversation.send('hi', 'queue')` 自动打到该会话；跨会话调用换 ctx 定向（`ctx.sessions.scope(id)!.conversation.send(...)`）；从 root ctx 直接调 scoped 方法即 throw。client 会话 scope 的铸造方式与 host agent scope 相同（no-op 插件 fiber + scope 键 extend），首次观看时惰性建，只有会话被移除且无人观看才拆——仅 host 会话死亡不拆 scope（冻结为只读视窗）。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml
index aaba9b1db2..892e3a8fc0 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md
-2026-07-29-projected-token-usage-and-request-context.md: d62f7dccd544a342da64fc35c24d32d53bf56231
-2026-07-29-projected-token-usage-and-request-context.zh.md: 6d2bb624ac11dbcdac30695913d3c16513bfdf9e
+2026-07-29-projected-token-usage-and-request-context.md: f96257243bef91ff6a73418231de5e777d8edb2e
+2026-07-29-projected-token-usage-and-request-context.zh.md: 7365d5d816f9f9b324f3e3d3b4db0d3346851bdf
diff --git a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md
index d62f7dccd5..f96257243b 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md
@@ -26,7 +26,7 @@ Capacity deliberately stays out of `EpochHeader`. That type is the reconstructio
 
 Both units ride the standard projection lifecycle: history tail baselines, `session/projection` live frames, higher-seq-wins client storage, JSON checkpoints, cache recovery, and unit unload. There is no token-specific history field, mux frame, projector, revision counter, or client fence.
 
-The Web `StatsLine` reads both through the standard `useProjection` seat. Window nodes still supply turn and step counts plus LLM and tool wall times — those answer "what is on screen" and are correctly window-scoped. Durable token and context groups remain when compaction leaves no visible assistant step. Cache writes count in billed input and in the cache-hit denominator. A deployment without token-meter drops the token groups; occupancy stays hidden until both pressure and capacity are known. The exact-overflow tooltip mounts its measuring child only for a non-empty line and retains one `ResizeObserver` while values change; text changes perform one direct measurement without replacing the observer.
+The Web [`StatsPills`](../feature/2026-09-07-composer-session-stats-pills.md) reads both through the standard `useProjection` seat. Window nodes still supply turn and step counts plus LLM and tool wall times as the no-projection fallback — those answer "what is on screen" and are correctly window-scoped. The durable usage pill remains when compaction leaves no visible assistant step. Cache writes count in billed input and in the cache-hit denominator. A deployment without token-meter drops the usage pill; context occupancy lives on the composer's ContextMeter ring. Exact token figures show in the usage pill's click-open dialog rather than a hover tooltip.
 
 ## Context occupancy is approximate, and that is the decision
 
@@ -48,7 +48,7 @@ That cost bought a worse display: occupancy went blank after every reconnect and
 
 **Resolve capacity inside token-meter.** The package documents itself as independent of model routing and is otherwise a pure reader that never appends to the log. AgentLoop already holds the resolved metadata where the header is written.
 
-**Extend the `session.models` RPC with capacity.** The handler already resolves and discards it, so the field is nearly free — but `StatsLine` lives in `ui-conversation` while the model directory lives in `ui-model-selection`, and `ui-conversation` cannot depend on `ui-model-selection`. Delivering it would have required either a second dock entry splitting one text row across two plugins, or a cross-plugin store write.
+**Extend the `session.models` RPC with capacity.** The handler already resolves and discards it, so the field is nearly free — but the stats display (now `StatsPills`, ui-chat) and the model directory live in separate plugins with no dependency between them. Delivering it would have required either a second dock entry splitting one surface across two plugins, or a cross-plugin store write.
 
 **Add a context circle beside the model selector.** That placement suggests selected-model state. The stats line carries the figure without a duplicate UI or data path.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md
index 6d2bb624ac..7365d5d816 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md
@@ -26,7 +26,7 @@ token-meter 还拥有在持久事件上运行的共享纯 attempt／Turn fold。
 
 两个单元都沿用标准投影生命周期：历史尾页基线、`session/projection` 实时帧、seq 高者胜的客户端存储、JSON 检查点、缓存恢复和单元卸载。系统没有任何 token 专用的历史字段、mux 帧、投影器、修订计数器或客户端栅栏。
 
-Web `StatsLine` 通过标准 `useProjection` 席位读取两者。窗口内节点仍提供轮次和步骤计数，以及 LLM（大语言模型）与工具的墙钟时间：它们回答的是「屏幕上有什么」，按窗口作用域正是正确的。压缩使可见 assistant 步骤归零后，持久 token 与上下文分组仍会保留。缓存写入会计入计费输入和缓存命中率分母。未部署 token-meter 时会去掉 token 分组；只有压力与容量都已知时才显示占用率。精确 overflow tooltip 只在统计行非空时挂载测量子组件，并在值变化期间保留同一个 `ResizeObserver`；文本变化只直接测量一次，不替换 observer。
+Web [`StatsPills`](../feature/2026-09-07-composer-session-stats-pills.zh.md) 通过标准 `useProjection` 席位读取两者。窗口内节点仍作为无投影回退提供轮次和步骤计数，以及 LLM（大语言模型）与工具的墙钟时间：它们回答的是「屏幕上有什么」，按窗口作用域正是正确的。压缩使可见 assistant 步骤归零后，持久用量 pill 仍会保留。缓存写入会计入计费输入和缓存命中率分母。未部署 token-meter 时会去掉用量 pill；上下文占用率由输入框旁的 ContextMeter 圆环承载。精确 token 数字显示在用量 pill 点击展开的弹层里，而非悬停提示。
 
 ## 上下文占用率是近似值，而这正是决策本身
 
@@ -48,7 +48,7 @@ Web `StatsLine` 通过标准 `useProjection` 席位读取两者。窗口内节
 
 **在 token-meter 内部解析容量。** 该包自述与模型路由无关，且在其他方面是一个从不向日志追加内容的纯读取方。AgentLoop 在写入请求头的位置已经持有已解析的元数据。
 
-**为 `session.models` RPC 增加容量字段。** 其处理器已经解析出容量又将其丢弃，因此这个字段几乎是免费的；但 `StatsLine` 位于 `ui-conversation`，模型目录位于 `ui-model-selection`，而 `ui-conversation` 不能依赖 `ui-model-selection`。要送达它，就得增加第二个 dock 条目、把一行文本拆到两个插件里，或者做一次跨插件的 store 写入。
+**为 `session.models` RPC 增加容量字段。** 其处理器已经解析出容量又将其丢弃，因此这个字段几乎是免费的；但统计展示（现为 `StatsPills`，ui-chat）与模型目录位于两个互不依赖的插件。要送达它，就得增加第二个 dock 条目把一个表面拆到两个插件里，或者做一次跨插件的 store 写入。
 
 **在模型选择器旁增加上下文圆环。** 该位置会让人以为这是所选模型的状态。统计行可以承载该数字，无需引入重复的 UI 或数据路径。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
index f1d03b2fae..70634bb543 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
-2026-08-05-profile-plugin-bundles.md: ccfa3306fd88b4f291085cae2bd02305b2c11fc6
-2026-08-05-profile-plugin-bundles.zh.md: e15ad15978ab57dcada8ecc877e0036cfde6b21e
+2026-08-05-profile-plugin-bundles.md: 7e51345e7eba8a58db63807e31d4a11481e3ffea
+2026-08-05-profile-plugin-bundles.zh.md: b2631603737ea9412eb97029ff01d751d8084cec
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
index ccfa3306fd..7e51345e7e 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
@@ -12,7 +12,7 @@ The `dsh` launcher hardcoded its compositions: `base.cordis.yml` + `web.cordis.y
 
 Everything becomes a **profile**: a directory `$DSH_HOME/profiles/<name>` with a `package.json` (pnpm-managed out-of-tree plugin `dependencies` plus the profile manifest `dsh.profile` with its ordered `bundles` layer list) and a user `cordis.patch.yml`. A **bundle** is an npm package declaring `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`; the two manifest kinds live under distinct `dsh.profile` / `dsh.bundle` keys so a package.json states which role it plays. The tree composes over an empty root by applying each bundle's patch in `dsh.profile.bundles` order, then the user layer and `--patch` overlays — one `applyEntryPatches` call shared by boot and `--dump-config`. App invocation values later moved from launcher-derived patches to startup services in the [app-owned command-line decision](../../archived/architecture/2026-08-06-app-owned-command-line.md).
 
-The default Profile templates use `@deepseek-ai/dsh-base` as the shared core for `web`, `headless`, `sdk`, and `acp`, with one mode bundle above it. The [standalone `sdk-minimal` profile](../../../../packages/bundle/sdk-minimal/README.md) instead lists one bundle that owns its complete explicit tree. Generic `dsh --profile <name>` hands its remaining arguments to that profile's command-line startup row: Web owns its flag family, headless owns its task positional, and the protocol profiles accept no app options. Patch overlays use launcher-owned `--patch`. `dsh plugin --profile <name> <args...>` is a thin pnpm forwarder that initializes the profile and reconciles `dsh.profile.bundles` with installed bundle declarations; a package without a bundle declaration remains a plain dependency. [Headless as a direct core entry point](../../archived/architecture/2026-08-09-headless-direct-core-entry-point.md) owns the headless composition contract.
+The default Profile templates use `@deepseek-ai/dsh-base` as the shared core for `web`, `headless`, `sdk`, and `acp`, with one mode bundle above it. The [standalone `sdk-minimal` profile](../../../../packages/bundle/sdk-minimal/README.md) instead lists one bundle that owns its complete explicit tree. Generic `dsh --profile <name>` hands its remaining arguments to that profile's command-line startup row: Web owns its flag family, headless owns its task positional, and the protocol profiles accept no app options. Patch overlays use launcher-owned `--patch`. A new, non-shipped target can use `--from-default-profile <template>` to copy one default template's bundle list and patch-reload policy before boot or config dump. This creates an independent profile with empty dependencies and an empty user patch: it neither reads a local profile named by the template nor records an inheritance relationship. The launcher claims the complete target directory exclusively, so existing state and concurrent creators fail without modification. `dsh plugin --profile <name> <args...>` is a thin pnpm forwarder that initializes a base-backed profile and reconciles `dsh.profile.bundles` with installed bundle declarations; a package without a bundle declaration remains a plain dependency. [Headless as a direct core entry point](../../archived/architecture/2026-08-09-headless-direct-core-entry-point.md) owns the headless composition contract.
 
 Resolution is two-anchored by construction: `dsh.profile.bundles` names resolve from the dsh installation first, then the profile directory — so in-box bundles always come from the same installation as the running `dsh` and pnpm never manages them — while bare plugin names in patch rows resolve through the profile directory's Node parent-walk into the maintained flat fallback `$DSH_HOME/profiles/node_modules` (one symlink per package the installation's app and bundles depend on, healed on every launch).
 
@@ -24,10 +24,12 @@ Two supporting refactors: the webserver's built-in static dist serving became th
 - **`link:` entries for in-box bundles**: pnpm cannot version, install, or update a `link:` into the installation, it embeds a machine path in a user file, and it breaks when the installation moves. The two-anchor resolution plus healed symlink fallback gives the same guarantee ("bundles come from the installation") without ceremony.
 - **A pre-boot `context` module in the bundle manifest** for boot-time values (dist path, flag facts): rejected in favor of pure plugins — the glue is ordinary rows and app-owned startup services, so the composition stays fully dumpable and the manifest stays data-only. The launcher-provided host slots (`ctx.cmdlineArgs`, `ctx.appExit`, and the environment snapshot) are provided in `boot()`'s `prepare` hook, before any config-tree entry mounts.
 - **Transitive bundle auto-application**: only direct `dsh.profile.bundles` entries contribute layers; a meta-bundle wanting to re-export another bundle's patch must do so explicitly in its own patch file.
+- **Dynamic template inheritance or cloning a local profile**: recording a parent would require merge and upgrade rules for bundle membership, dependencies, and user patches, while copying local state would duplicate machine-specific choices. Template-based creation copies only installation-owned defaults once.
 
 ## Consequences
 
 - New composition surfaces (a TUI, provider packs) ship as ordinary npm packages installable per profile, without a repository row for every deployment shape.
+- Users can start an independent custom profile from any shipped application template without copying machine-local profile state.
 - `apps/cli` shrank to argv parsing, profile machinery consumption, and the pnpm forwarder; `AppCLIEntry` and the per-surface boot paths are gone.
 - The keyless web e2e scaffold boots the same bundle layers over the same empty-root shape as production, including the profiles module fallback, so composition drift between test and product fails loudly.
 - Under the pre-release stance, backends carry no compatibility behavior for old on-disk configuration; `$DSH_HOME/config.yaml` is ignored.
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
index e15ad15978..b263160373 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 一切都变成 **profile**：即目录 `$DSH_HOME/profiles/<name>`，其中包含一个 `package.json`（pnpm 管理的树外插件 `dependencies`，加上 profile manifest `dsh.profile` 及其有序的 `bundles` 层列表）和一份用户 `cordis.patch.yml`。**组合包**（bundle）是声明了 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；两种 manifest 分别位于互不相同的 `dsh.profile` / `dsh.bundle` 键下，因此一份 package.json 能说明自己扮演哪种角色。配置树在空的根之上组合：按 `dsh.profile.bundles` 顺序应用每个组合包的 patch，然后是用户层与 `--patch` overlay——启动与 `--dump-config` 共享同一条 `applyEntryPatches` 路径。随后，[应用持有命令行的决策](../../archived/architecture/2026-08-06-app-owned-command-line.md)又把调用期取值从启动器派生的 patch 迁移到了启动服务。
 
-默认 Profile 模板为 `web`、`headless`、`sdk` 与 `acp` 使用 `@deepseek-ai/dsh-base` 作为共享核心，并在其上叠加一个模式组合包。[独立 `sdk-minimal` profile](../../../../packages/bundle/sdk-minimal/README.zh.md)则只列出一个拥有完整显式配置树的组合包。通用的 `dsh --profile <name>` 把剩余参数交给该 profile 的命令行启动行：Web 持有自己的 flag 家族，headless 持有任务位置参数，协议 profile 不接受应用选项。patch overlay 使用启动器持有的 `--patch`。`dsh plugin --profile <name> <args...>` 是一层薄薄的 pnpm 转发器，负责初始化 profile，并依据已安装包的组合包声明调和 `dsh.profile.bundles`；没有组合包声明的包保持为普通依赖。[Headless 作为直接 core 入口](../../archived/architecture/2026-08-09-headless-direct-core-entry-point.md)负责 headless 组合约定。
+默认 Profile 模板为 `web`、`headless`、`sdk` 与 `acp` 使用 `@deepseek-ai/dsh-base` 作为共享核心，并在其上叠加一个模式组合包。[独立 `sdk-minimal` profile](../../../../packages/bundle/sdk-minimal/README.zh.md)则只列出一个拥有完整显式配置树的组合包。通用的 `dsh --profile <name>` 把剩余参数交给该 profile 的命令行启动行：Web 持有自己的 flag 家族，headless 持有任务位置参数，协议 profile 不接受应用选项。patch overlay 使用启动器持有的 `--patch`。新的非内置目标可以使用 `--from-default-profile <template>`，在启动或配置 dump 之前复制一个默认模板的 bundle 列表与 patch 重载策略。这会创建依赖为空、用户 patch 为空的独立 profile：它既不读取与模板同名的本地 profile，也不记录继承关系。launcher 会以独占方式领取完整的目标目录，因此既有状态和并发创建者都会在不作修改的情况下失败。`dsh plugin --profile <name> <args...>` 是一层薄薄的 pnpm 转发器，负责初始化一个以 base 为基础的 profile，并依据已安装包的组合包声明调和 `dsh.profile.bundles`；没有组合包声明的包保持为普通依赖。[Headless 作为直接 core 入口](../../archived/architecture/2026-08-09-headless-direct-core-entry-point.md)负责 headless 组合约定。
 
 解析在构造上就是双锚点的：`dsh.profile.bundles` 中的名称先从 dsh 安装目录解析，再从 profile 目录解析——因此内置组合包始终来自与运行中 `dsh` 相同的安装，pnpm 从不管理它们——而 patch 行中的裸插件名称经 profile 目录的 Node 父目录逐级查找，落到受维护的扁平回退目录 `$DSH_HOME/profiles/node_modules`（安装目录的应用与各组合包所依赖的每个包各一个符号链接，每次启动时修复）。
 
@@ -24,10 +24,12 @@ Status: implemented
 - **内置组合包使用 `link:` 条目**：pnpm 无法对指向安装目录的 `link:` 做版本管理、安装或更新，它会把机器路径嵌进用户文件，并且在安装目录移动后失效。双锚点解析加上每次启动修复的符号链接回退提供了同样的保证（「组合包来自安装目录」），且没有这些繁文缛节。
 - **在组合包 manifest 中放一个启动前 `context` 模块**承载启动期取值（dist 路径、flag 事实）：否决，改用纯插件——粘合逻辑就是普通配置行和由应用持有的启动服务，因此组合始终可完整 dump，manifest 保持纯数据。启动器提供的宿主 slot（`ctx.cmdlineArgs`、`ctx.appExit` 与环境快照）在任何配置树条目挂载之前，于 `boot()` 的 `prepare` 钩子中提供。
 - **组合包的传递式自动应用**：只有直接列在 `dsh.profile.bundles` 中的条目才贡献层；想重新导出另一个组合包 patch 的元组合包，必须在自己的 patch 文件中显式完成。
+- **动态模板继承或克隆本地 profile**：记录父级会要求为 bundle 成员关系、依赖和用户 patch 制定合并与升级规则，而复制本地状态会重复机器特定选择。基于模板的创建只会一次性复制安装自有的默认值。
 
 ## Consequences
 
 - 新的组合表层（TUI、提供方扩展包）以普通 npm 包形式交付，可按 profile 安装，无需在仓库中为每种部署形态各留一行。
+- 用户可以从任意随附应用模板启动一个独立的自定义 profile，而不会复制机器本地的 profile 状态。
 - `apps/cli` 收缩为 argv 解析、profile 机制的消费方和 pnpm 转发器；`AppCLIEntry` 与各表层专属的启动路径全部移除。
 - 无密钥 web e2e 脚手架以与生产相同的空根形态启动相同的组合包层，包括 profiles 模块回退，因此测试与产品之间的组合漂移会响亮失败。
 - 按发布前姿态，后端不携带旧磁盘配置的兼容行为；`$DSH_HOME/config.yaml` 会被忽略。
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
index b7a8cc094a..eb701400a4 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
-2026-08-09-client-conversation-node-assembly.md: 7f5b948f9083b20edd037fe32c55df7ba3378692
-2026-08-09-client-conversation-node-assembly.zh.md: 8716b25584a8cefd8d2239f242d430775ed2a8ef
+2026-08-09-client-conversation-node-assembly.md: 842dfb0218478591f975c97064f101a35ea2f211
+2026-08-09-client-conversation-node-assembly.zh.md: 6ab64c25957d33487461fe56e122faedb19f9421
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
index 7f5b948f90..842dfb0218 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
@@ -315,7 +315,7 @@ The shell synchronously resolves the persisted selection when a Session binding
 
 Ordinary prepend and append flushes call `apply({ upserts, timeline })` only for active targets. Complete window replacement and Registry rebuild call `replace()` only for active targets. Unsubscription does not remove a target, so returning to an opened View does not rebuild it.
 
-[`ChatSnapshotBuilder`](../../../../packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts) maintains `order`, a keyed `nodes` store with identity-stable Node and Turn-process sources, the turn/step `locations` index, `timeline`, and the `legacy` slice used by StatsLine and mirrored into top-level public compatibility fields.
+[`ChatSnapshotBuilder`](../../../../packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts) maintains `order`, a keyed `nodes` store with identity-stable Node and Turn-process sources, the turn/step `locations` index, `timeline`, and the `legacy` slice used by StatsPills and mirrored into top-level public compatibility fields.
 
 Only a new key or a change to `anchorSeq`, visibility, or Location identity makes a Chat update structural. An ordinary content change does not rebuild `order`; the keyed Node store replaces that key's value and publishes only its source. The Turn-process projector recalculates cross-Node presentation only for a Turn whose structure, specification, or status changed, then publishes only that Turn's process sources.
 
@@ -424,4 +424,4 @@ Inbox Context retention grows with splice count and claimed message count rather
 
 The cost is new Runtime contracts for Registry, Assembler, Location data, dependency replay, and per-target Builders, plus parent-owned common inject and per-occurrence `hookContext` in UI Slots. Definitions that consume Assistant deltas also maintain equivalent scalar and packed update branches. Definition authors must understand stable IDs, unique scalar starts, forward replay, Step→Turn publication order, read-only Reader access, and the prohibition on Node withdrawal.
 
-`useTurnData()` does not revoke the standard `useSession` capability from session-scoped renderers, so this boundary relies on API guidance and tests rather than capability isolation. Registry changes remain low-frequency full rebuilds; the Chat Builder still maintains a legacy slice for StatsLine and the top-level public fields, while Trajectory owns target-specific Definitions and a Builder over the shared Session window. Built-in Definitions remain in their respective UI packages, and these compatibility boundaries do not return business interpretation to Session.
+`useTurnData()` does not revoke the standard `useSession` capability from session-scoped renderers, so this boundary relies on API guidance and tests rather than capability isolation. Registry changes remain low-frequency full rebuilds; the Chat Builder still maintains a legacy slice for StatsPills and the top-level public fields, while Trajectory owns target-specific Definitions and a Builder over the shared Session window. Built-in Definitions remain in their respective UI packages, and these compatibility boundaries do not return business interpretation to Session.
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
index 8716b25584..6ab64c2595 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
@@ -315,7 +315,7 @@ Session binding 可用、缓存的 binding 成为 current 或 View roster 变化
 
 普通 prepend 与 append flush 只对 active target 调用 `apply({ upserts, timeline })`。完整 window replace 与 Registry rebuild 只对 active target 调用 `replace()`。取消订阅不会移除 target，因此返回已打开的 View 不会重建。
 
-[`ChatSnapshotBuilder`](../../../../packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts) 维护 `order`、带身份稳定 Node 与 Turn-process source 的 keyed `nodes` store、turn/step `locations` index、`timeline`，以及由 StatsLine 使用并镜像到顶层公共兼容字段的 `legacy` slice。
+[`ChatSnapshotBuilder`](../../../../packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts) 维护 `order`、带身份稳定 Node 与 Turn-process source 的 keyed `nodes` store、turn/step `locations` index、`timeline`，以及由 StatsPills 使用并镜像到顶层公共兼容字段的 `legacy` slice。
 
 Chat 结构变化只由新 key、`anchorSeq`、visibility 或 Location identity 变化触发。普通内容变化不重建 `order`；keyed Node store 只替换该 key 的 value 并发布其 source。Turn-process projector 仅为结构、规格或状态发生变化的 Turn 重算跨 Node 呈现，再只发布该 Turn 的 process source。
 
@@ -424,4 +424,4 @@ Inbox Context 的保留量随 splice 数和已 claim 消息数增长，不再随
 
 代价是 Runtime 新增 Registry、Assembler、Location data、依赖重放和 per-target Builder 契约，UI Slots 也新增 parent-owned common inject 与 per-occurrence `hookContext`。消费 Assistant delta 的 Definition 还需要维护等价的 scalar 与 packed update 分支。Definition 作者必须理解稳定 ID、唯一 scalar start、正序 replay、Step→Turn 发布顺序、只读 Reader 和 Node 不撤回规则。
 
-`useTurnData()` 不撤销 session-scoped renderer 的标准 `useSession`，因此该边界依靠 API 引导和测试，而不是能力隔离。Registry 变化仍是低频完整 rebuild；Chat Builder 继续为 StatsLine 和顶层公共字段维护 legacy slice，Trajectory 则在共享 Session 窗口上拥有 target 专属 Definition 与 Builder。内建 Definition 分别留在所属 UI package；这些兼容边界不把业务解释权交还给 Session。
+`useTurnData()` 不撤销 session-scoped renderer 的标准 `useSession`，因此该边界依靠 API 引导和测试，而不是能力隔离。Registry 变化仍是低频完整 rebuild；Chat Builder 继续为 StatsPills 和顶层公共字段维护 legacy slice，Trajectory 则在共享 Session 窗口上拥有 target 专属 Definition 与 Builder。内建 Definition 分别留在所属 UI package；这些兼容边界不把业务解释权交还给 Session。
diff --git a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.i18n.yaml
index 21599ff5f7..6f20df4af6 100644
--- a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md
-2026-08-23-client-derived-tool-presentation.md: 58a8f23d717580355b852703f448c723d9c3a7ea
-2026-08-23-client-derived-tool-presentation.zh.md: 8e1a02eff57cce7967985a22c5bdcec7c18e6059
+2026-08-23-client-derived-tool-presentation.md: 6b19dc881d572bfece345cbbd5eca688b2e05aab
+2026-08-23-client-derived-tool-presentation.zh.md: 98ada31627398f317e4c41336af56e8c6cf0837e
diff --git a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md
index 58a8f23d71..6b19dc881d 100644
--- a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md
+++ b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md
@@ -248,7 +248,7 @@ Host presenter APIs describe top-level calls and results. Code Dispatch subcalls
 
 Code Dispatch start and result events already carry `parentCallId`. Conversation preserves that existing fact on each child `ToolCallBlock`; root Session calls omit it. The diff, read, search, and web models accept only blocks without `parentCallId`; the terminal model and existing renderers that intentionally support nested calls accept child blocks.
 
-The Details panel delegates the selected block unchanged. Shared card models apply the same terminal eligibility and nonterminal child restrictions in rows and Details, so the Details slot needs no placement field.
+Shared card models apply the same terminal eligibility and nonterminal child restrictions wherever a block renders, so no second presentation surface needs a placement field; the details panel that once delegated a selected block was removed with the right-hand details column ([decision](../feature/2026-09-04-right-sidebar-docking-infrastructure.md)).
 
 The keyed slot continues dispatching every subcall by its real tool name. `parentCallId` restricts only the diff, read, search, and web structured models covered by this decision. Existing specialized renderers such as Skill and Cordis, which already read raw blocks, remain unchanged.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.zh.md b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.zh.md
index 8e1a02eff5..98ada31627 100644
--- a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.zh.md
@@ -248,7 +248,7 @@ Host presenter API 描述顶层 call/result。本决定覆盖的 diff、read、s
 
 Code Dispatch start 与 result event 已经携带 `parentCallId`。Conversation 在每个 child `ToolCallBlock` 上保留这项现有事实，root Session call 则不携带它。diff、read、search 和 web model 只接受没有 `parentCallId` 的 block；terminal model 与原本有意支持嵌套调用的 renderer 接受 child block。
 
-Details panel 原样委托选中的 block。共享 card model 在行与 Details 中应用相同的 terminal 适用规则和非 terminal 子调用限制，因此 Details slot 不需要 placement 字段。
+共享的 card model 在 block 渲染到哪里都施加同样的终端资格与非终端子调用限制，因此不需要第二个展示面带 placement 字段；曾经原样委托选中 block 的详情面板已随右侧详情列一并删除（[决策](../feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md)）。
 
 keyed slot 仍按每个子调用的真实 tool name 分发；`parentCallId` 只限制本决定覆盖的 diff/read/search/web 结构化模型。Skill、Cordis 等已经直接读取 raw block 的专用 renderer 保持现状。
 
diff --git a/.agents/notes/implemented/architecture/2026-09-05-client-resource-model.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-05-client-resource-model.i18n.yaml
new file mode 100644
index 0000000000..72cf5954dc
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-05-client-resource-model.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-05-client-resource-model.md
+2026-09-05-client-resource-model.md: 75502ffc91af049bf89b7c36ec6ae3dc1339a5f8
+2026-09-05-client-resource-model.zh.md: d1430e88fc16b46a6ad32bbeacb1d59e0a7f6131
diff --git a/.agents/notes/implemented/architecture/2026-09-05-client-resource-model.md b/.agents/notes/implemented/architecture/2026-09-05-client-resource-model.md
new file mode 100644
index 0000000000..75502ffc91
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-05-client-resource-model.md
@@ -0,0 +1,88 @@
+# Agent Note: Client resource model
+
+Status: implemented
+
+English | [中文](2026-09-05-client-resource-model.zh.md)
+
+## Problem
+
+A right-Sidebar tab body, a chat card, or any other slot component often needs live data it knows only by address: the file an agent just wrote, later a chat node or a terminal. Before the resource model each consumer fetched for itself — the text preview owned its own Remote call and refresh loop — so every mount re-read, two components showing one file held two copies, switching tabs unmounted the body and lost its content, and each new kind of content meant a new bespoke hook.
+
+The tab record set the constraint. A tab must survive undo, redo, reload, and hot module replacement without the code that opened it, so the record can hold only serializable data: an address and navigation parameters. The opener therefore cannot hand a body its data, and injection is the wrong tool — injection is a registration-time relation between a domain and a seat, while opening is a runtime event. A component has to find its data from the address alone, through something registered once by whoever owns that kind of data.
+
+## Decision
+
+[`packages/client/resources`](../../../../packages/client/resources/README.md) (`@deepseek-ai/dsh-client-resources`) provides `ctx.resources` and the `useResource` global standard hook. Anything a consumer reads live is a **resource**, a resource is identified by its **address** and nothing else, and the address's protocol names the one **provider** that turns it into a frame stream.
+
+### Addresses
+
+A resource address is a `dsh-resource://<type>/…` URL. The host is the protocol key — the key of `ResourceProtocolMap` — and the path belongs to the protocol's owner. `RESOURCE_SCHEME = 'dsh-resource'` is the one scheme constant; `protocolOf(address)` parses the string with `new URL`, requires `protocol === 'dsh-resource:'`, and returns the lower-cased host, or `undefined` for a string the parser rejects, another scheme, or an empty host. `dsh-resource` is not one of the URL specification's special schemes, so the parser keeps the host's case and treats the path as opaque; the lower-casing is explicit, and each path segment is percent-encoded by the protocol that defines it. A protocol that needs a scope encodes it in the path: `dsh-resource://file/session/<sessionId>/<path relative to that session's workspace root>`, with `session/<sessionId>` naming the session whose root resolves the file, or `dsh-resource://file/absolute/<absolute path>`, which carries no session and is read through the current one ([grammar](../../../../packages/util/workspace-path/README.md)). Any other scheme — `sidebar://guide` — is a navigation address: it names a tab, not data, and the model answers `none` for it ([tab types and navigation](2026-09-05-sidebar-tab-types-and-navigation.md)).
+
+### The service
+
+```ts ignore-check
+interface Resources {
+  register<P extends ResourceProtocol>(provider: ResourceProvider<P>): () => void
+  pin(address: string, signal: AbortSignal): void
+  source(address: string): ObservableSnapshot<ResourceSnapshot<unknown>>
+}
+
+interface ResourceProvider<P extends ResourceProtocol> {
+  readonly protocol: P
+  open(address: string, ctx: { readonly signal: AbortSignal }): AsyncIterable<RemoteResult<ResourceProtocolMap[P]>>
+  reload?(address: string): void
+}
+
+interface ResourceSnapshot<Value> {
+  readonly status: 'none' | 'loading' | 'live' | 'failed'
+  readonly value: Value | undefined
+  readonly failure: RemoteFailure | undefined
+  readonly reload: () => void
+}
+
+type UseResource = <P extends ResourceProtocol>(address: string) => ResourceSnapshot<ResourceProtocolMap[P]>
+```
+
+`register` owns exactly one provider per protocol: a second registration for the same protocol throws, and the registration is an effect on the registering plugin's fiber, so a protocol leaves with its plugin and may be registered again afterwards. `pin` holds a resource open without subscribing until the signal aborts; an already-aborted signal pins nothing. `source` is the bare observable behind the hook, reference-stable per address, for callers outside React. The value type is looked up in `ResourceProtocolMap`, declared as an empty interface in `ui-slots` beside `SlotMap` — a module augmentation cannot introduce an export the target module lacks, and every consumer already depends on `ui-slots` — and each protocol's owner declaration-merges its member (`file: WorkspaceFileResource`); the resources package re-exports the type.
+
+### The hook
+
+`useResource` is declared on `GlobalStandardProps` in `ui-slots`, so every slot component has it whatever its scope, and the plugin provides it through `ctx.slots.provideRoot({ keyedHooks: { resource: address => resources.source(address) } })`, the same root keyed-hook path `useSessions` uses. It is not a session standard prop: a resource carries its own scope in its address, and components outside any session scope read resources too. `useResource<P>(address)` returns the snapshot: `none` when the address's protocol has no provider or the address is not a resource address, `loading` between the stream opening and its first frame, `live` with the latest `ok` value, `failed` with the latest frame's failure beside the last value. `reload()` asks the provider for a fresh frame and is a no-op when the protocol has no provider or no `reload`.
+
+### Frames
+
+A provider yields `RemoteResult` frames: the current state first, one frame per later change. An `ok` frame makes the resource `live`, replaces the value, and clears the failure; an `ok: false` frame makes it `failed`, records the failure, and keeps the last value. Failure is data, not an exception: the Remote face already folds failures into `ok: false` and never rejects, providers pass those frames on, and the model neither catches nor wraps — a throw inside a provider's stream is a programming error left to surface. A stream that ends on its own keeps its last state; frames a provider yields after the release that aborted it are dropped and the iterator is returned. Streams carry metadata, not payload: the `file` value is `{ absolutePath, version, bytes?, changed }`, and a consumer reads content itself, by page, through the [Workspace Files service](2026-09-05-workspace-files-service.md).
+
+### Lifecycle
+
+One record exists per address. Its holders are the hook's subscribers plus pins; the first holder opens the provider's stream under an `AbortController`, later holders share it and read the latest value at once, and the last release aborts the stream and resets the snapshot to idle — `loading` while a provider is registered, `none` otherwise. A provider that arrives while an address is already held opens that address's stream; one that leaves aborts it and the address reads `none`. Records are kept for the page lifetime so `source(address)` stays reference-stable across React's render-then-subscribe window and a StrictMode remount, where a recreated record would resubscribe and restart the stream on every render.
+
+The right Sidebar's Tab domain pins every open tab record's address for the record's life, so switching tabs unmounts a body without closing its stream and switching back reads the latest value; a record restored by undo is a new pin, and a resource the model already let go is read again ([tab types and navigation](2026-09-05-sidebar-tab-types-and-navigation.md)). `openResource(address)` accepts resource addresses only; pages such as the guide and the file tree are opened by kind and never enter the resource model.
+
+## Alternatives considered
+
+**Session-bound resources: `useResource` on the session kit and a `(session, address)` identity.** The first form. Rejected because a file is not a session concern — the session is only who authorizes the path — and because the model must serve protocols and components outside any session scope. Identity became the address alone, the scope moved into the address grammar, and the hook moved to the global kit.
+
+**Content in the resource stream.** Rejected: content can be arbitrarily large, and a stream is for pushing change, not payload. The stream carries metadata and the consumer reads content by page, which is also what lets one open tab hold a multi-megabyte file at the cost of one page.
+
+**Failure as a thrown error, wrapping a non-`RemoteFailure` throw as `gateway/internal`.** Rejected: the Remote face never rejects, so anything a provider throws is a bug, and wrapping it would be a fallback that hides the bug from the developer who caused it. A failure is an `ok: false` frame; a throw surfaces.
+
+**`file:/<scope>/<id>/<path>`, then `file://<scope>/<id>/<path>` with the scope in the authority.** Two earlier grammars. The single-slash form was not a URL the platform parser accepted, so every consumer hand-parsed it. Moving the scope into the authority made it a URL but gave each resource protocol its own scheme — `file://`, later `chat://`, `terminal://` — so the set of schemes grew with the set of protocols, a `file://` address no longer meant what it means everywhere else, and telling a resource address from a navigation address needed a list. The single `dsh-resource://<type>/…` scheme makes that test one comparison, leaves the host free to name the protocol, and keeps every other scheme available to navigation.
+
+**A hand-parsed scheme prefix instead of the URL parser.** The first `protocolOf` matched a regular expression for the scheme. Rejected once addresses were URLs: the parser already decides validity and case, and a string it rejects should read as "no protocol" rather than be half-parsed.
+
+**A per-tab stream hook, or a framework-managed `useTabResource(fetch)`.** Rejected in turn: a stream hook on the tab domain asks the wrong owner — `file` data must come from the workspace file service, chat data from the chat domain — and a framework-owned fetch has no good cache key. What remains is owner props on the tab plus one client-wide `useResource` keyed by address.
+
+## Consequences
+
+Any slot component reads live data by address and nothing else, so an opener passes data only and a body reconstructs itself from its record after undo, reload, or hot replacement. Two components showing one address share one stream, and a pinned address survives its body's unmount. A protocol's transport lives in exactly one provider, and adding a protocol is one declaration-merged type plus one registration.
+
+The costs are recorded here so they are not rediscovered. Records are never reclaimed: memory grows with the number of distinct addresses ever read, not with reads. Abort compliance rests with the provider; the model drops what a released stream still yields but cannot stop a provider that ignores the signal before its next frame. The failure type is the Remote face's `RemoteFailure`, so a provider whose source is not a Remote call has to mint one. A navigation address or a malformed string reads as `none` rather than an error, which keeps mixed address lists cheap to render but gives a misspelled protocol no diagnostic beyond the missing value.
+
+## Testing
+
+`packages/client/resources/tests/resources.client.spec.ts` drives the registry with scripted feeds: protocol ownership and disposal, `none` for a protocol without a provider and for a navigation address, a provider arriving after a held address and leaving while it is held, registrations dropped with their fiber, open-on-first-holder and close-on-last, one source per address, pins including an already-aborted signal, a remount reading the latest value without reopening, reopening as a fresh stream, frames after abort dropped with the iterator returned, a stream ending on its own, failure frames beside the last value, and `reload` forwarding. `tests/apply.client.spec.ts` mounts the plugin in `SlotTestRuntime` and checks, through a root-scope probe component, that `useResource` reaches props, that rendering it opens the provider's stream, and that disposing the plugin withdraws both the service and the hook.
+
+## Deferred
+
+Reclaiming idle records, a resource-owned failure type decoupled from the Remote face, and the `chat` and `terminal` protocols are open; each waits for a consumer. The developer-facing reference is [docs/subsystems/client-resources.md](../../../../docs/subsystems/client-resources.md); the Sidebar that consumes the model is described in [docs/subsystems/sidebar-right.md](../../../../docs/subsystems/sidebar-right.md).
diff --git a/.agents/notes/implemented/architecture/2026-09-05-client-resource-model.zh.md b/.agents/notes/implemented/architecture/2026-09-05-client-resource-model.zh.md
new file mode 100644
index 0000000000..d1430e88fc
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-05-client-resource-model.zh.md
@@ -0,0 +1,88 @@
+# Agent Note: 客户端资源模型
+
+Status: implemented
+
+[English](2026-09-05-client-resource-model.md) | 中文
+
+## Problem
+
+右侧 Sidebar 的 tab 正文、聊天卡片或任何别的 slot 组件，常常需要只以地址可知的活数据：agent 刚写的文件，将来的聊天节点或终端。资源模型出现前每个消费方各自取数——文本预览自己持有 Remote 调用与刷新循环——于是每次挂载都重读、两个组件显示同一文件就持有两份、切 tab 卸载正文就丢内容，每种新内容都意味着一个新的专用 hook。
+
+约束来自 tab 记录。tab 必须在打开它的代码不在场时挺过撤销、重做、刷新与热替换，所以记录只能存可序列化的数据：一个地址与导航参数。因此开启方不能把数据交给正文，注入也不是合适的工具——注入是领域与席位之间注册期的关系，而打开是运行期事件。组件必须只凭地址找到数据，途径是由数据拥有者注册一次的东西。
+
+## Decision
+
+[`packages/client/resources`](../../../../packages/client/resources/README.zh.md)（`@deepseek-ai/dsh-client-resources`）提供 `ctx.resources` 与 `useResource` 全局标准 hook。消费方活读的任何东西都是**资源**，资源只由其**地址**标识，地址的协议命名唯一一个把它变成帧流的**提供方**。
+
+### 地址
+
+资源地址是 `dsh-resource://<type>/…` 形式的 URL。host 是协议键——`ResourceProtocolMap` 的键——路径归协议拥有者。`RESOURCE_SCHEME = 'dsh-resource'` 是唯一的 scheme 常量；`protocolOf(address)` 用 `new URL` 解析字串，要求 `protocol === 'dsh-resource:'`，返回小写 host；解析器拒绝的字串、其它 scheme 或空 host 返回 `undefined`。`dsh-resource` 不是 URL 规范里的特殊 scheme，解析器会保留 host 的大小写并把路径当作不透明串，所以小写化是显式做的，每段路径由定义它的协议做百分号编码。需要作用域的协议把作用域编进路径：`dsh-resource://file/session/<sessionId>/<相对该会话工作区根的路径>`，`session/<sessionId>` 命名以其根解析该文件的会话；或 `dsh-resource://file/absolute/<绝对路径>`，不带会话、经当前会话读取（[语法](../../../../packages/util/workspace-path/README.zh.md)）。其它任何 scheme——`sidebar://guide`——是导航地址：它命名一个 tab 而非数据，模型对它回答 `none`（[tab 类型与导航](2026-09-05-sidebar-tab-types-and-navigation.zh.md)）。
+
+### 服务
+
+```ts ignore-check
+interface Resources {
+  register<P extends ResourceProtocol>(provider: ResourceProvider<P>): () => void
+  pin(address: string, signal: AbortSignal): void
+  source(address: string): ObservableSnapshot<ResourceSnapshot<unknown>>
+}
+
+interface ResourceProvider<P extends ResourceProtocol> {
+  readonly protocol: P
+  open(address: string, ctx: { readonly signal: AbortSignal }): AsyncIterable<RemoteResult<ResourceProtocolMap[P]>>
+  reload?(address: string): void
+}
+
+interface ResourceSnapshot<Value> {
+  readonly status: 'none' | 'loading' | 'live' | 'failed'
+  readonly value: Value | undefined
+  readonly failure: RemoteFailure | undefined
+  readonly reload: () => void
+}
+
+type UseResource = <P extends ResourceProtocol>(address: string) => ResourceSnapshot<ResourceProtocolMap[P]>
+```
+
+`register` 让每个协议恰有一个提供方：同一协议的第二次注册抛错，注册是挂在注册方插件 fiber 上的 effect，所以协议随插件离开、之后可再注册。`pin` 在不订阅的情况下让资源保持打开直到信号中止；已中止的信号什么也不钉。`source` 是 hook 背后的裸 observable，按地址引用稳定，供 React 之外的调用方使用。值类型在 `ResourceProtocolMap` 里查得，它作为空接口声明在 `ui-slots` 里、与 `SlotMap` 并列——模块增强无法给目标模块添加它没有的导出，而每个消费方本来就依赖 `ui-slots`——各协议拥有者声明合并自己的成员（`file: WorkspaceFileResource`）；resources 包再导出这个类型。
+
+### hook
+
+`useResource` 声明在 `ui-slots` 的 `GlobalStandardProps` 上，因此每个 slot 组件不论作用域都有它，插件经 `ctx.slots.provideRoot({ keyedHooks: { resource: address => resources.source(address) } })` 提供，与 `useSessions` 走同一条根 keyed hook 路径。它不是会话标准 prop：资源的作用域随地址携带，会话作用域之外的组件也要读资源。`useResource<P>(address)` 返回快照：地址协议没有提供方或地址不是资源地址时为 `none`，流已打开、首帧未到时为 `loading`，`live` 携带最新 `ok` 值，`failed` 在最后一个值旁携带最新帧的失败。`reload()` 请提供方给一个新帧，协议没有提供方或提供方没有 `reload` 时是空操作。
+
+### 帧
+
+提供方产出 `RemoteResult` 帧：首帧是当前状态，之后每次变化一帧。`ok` 帧使资源 `live`、替换值、清除失败；`ok: false` 帧使其 `failed`、记下失败、保留最后一个值。失败是数据不是异常：Remote 面本来就把失败折进 `ok: false` 且从不 reject，提供方原样转发这些帧，模型既不捕获也不包装——提供方流里抛出是编程错误，任其冒出。自行结束的流保持最后状态；提供方在中止它的那次释放之后产出的帧被丢弃，迭代器被归还。流只推元数据不推载荷：`file` 的值是 `{ absolutePath, version, bytes?, changed }`，消费方自己经 [Workspace Files 服务](2026-09-05-workspace-files-service.zh.md)按页读内容。
+
+### 生命周期
+
+每个地址一条记录。持有者是 hook 的订阅者加 pin；第一个持有者在 `AbortController` 下打开提供方的流，之后的持有者共享它并立刻读到最新值，最后一个释放时中止流并把快照重置为空闲——有提供方注册时为 `loading`，否则为 `none`。地址已被持有时到达的提供方会打开该地址的流；离开的提供方中止它，地址读作 `none`。记录在页面存续期内保留，使 `source(address)` 在 React 渲染到订阅的窗口与 StrictMode 重挂载之间保持引用稳定，否则重建记录会让每次渲染重订阅、重开流。
+
+右侧 Sidebar 的 Tab 域在每条打开的 tab 记录存续期内钉住其地址，所以切 tab 卸载正文不关流、切回读到最新值；撤销恢复的记录是一次新的钉住，模型已放掉的资源会重新读取（[tab 类型与导航](2026-09-05-sidebar-tab-types-and-navigation.zh.md)）。`openResource(address)` 只收资源地址；引导页与文件树这类页面按 kind 打开，从不进入资源模型。
+
+## Alternatives considered
+
+**会话绑定的资源：`useResource` 挂会话标准件、身份为 `(session, address)`。** 第一版形态。被否，因为文件不是会话的事——会话只是路径的授权者——而且模型必须服务会话作用域之外的协议与组件。身份改为只有地址，作用域进入地址语法，hook 移到全局标准件。
+
+**内容进资源流。** 被否：内容可能任意大，流是用来推变化的，不是推载荷。流只带元数据，消费方按页读内容，这也是一个打开的 tab 能以一页的代价承载数兆字节文件的原因。
+
+**以抛错表达失败，并把非 `RemoteFailure` 的抛出包装成 `gateway/internal`。** 被否：Remote 面从不 reject，所以提供方抛出的任何东西都是 bug，包装它就是把 bug 藏起来不让肇事者看见的 fallback。失败是 `ok: false` 帧；抛出就冒出来。
+
+**`file:/<scope>/<id>/<path>`，再到把作用域放在 authority 位的 `file://<scope>/<id>/<path>`。** 两版更早的语法。单斜杠形态不是平台解析器接受的 URL，每个消费方都得手工解析。把作用域移到 authority 位使它成为 URL，却让每个资源协议各占一个 scheme——`file://`、将来的 `chat://`、`terminal://`——scheme 的集合随协议集合增长，`file://` 地址不再是它在别处的含义，区分资源地址与导航地址需要一张清单。单一 scheme `dsh-resource://<type>/…` 让这个判断只需一次比较，host 留给协议命名，其它所有 scheme 留给导航。
+
+**手写 scheme 前缀解析代替 URL 解析器。** 第一版 `protocolOf` 用正则匹配 scheme。地址成为 URL 后被否：解析器已经决定合法性与大小写，它拒绝的字串应读作「无协议」而不是被解析一半。
+
+**每 tab 一个流 hook，或框架代管的 `useTabResource(fetch)`。** 依次被否：挂在 tab 域上的流 hook 问错了拥有者——`file` 数据必须来自工作区文件服务，聊天数据来自聊天域——而框架代管的 fetch 没有好的缓存键。留下的是 tab 上的 owner props 加一个按地址的客户端级 `useResource`。
+
+## Consequences
+
+任何 slot 组件只凭地址读活数据，于是开启方只传数据，正文在撤销、刷新或热替换后能从记录重建自己。显示同一地址的两个组件共享一条流，被钉住的地址在正文卸载后仍存活。一个协议的传输只住在一个提供方里，新增协议只是一个声明合并的类型加一次注册。
+
+代价记录在此以免被重新发现。记录不回收：内存随读过的不同地址数增长，而非随读取次数增长。中止合规归提供方；模型会丢弃已释放的流仍产出的帧，却阻止不了忽略信号的提供方跑到下一帧。失败类型是 Remote 面的 `RemoteFailure`，来源不是 Remote 调用的提供方得自己铸一个。导航地址或畸形字串读作 `none` 而非报错，这让混合地址列表渲染起来便宜，却让拼错的协议除了缺值之外没有任何诊断。
+
+## Testing
+
+`packages/client/resources/tests/resources.client.spec.ts` 用脚本化的 feed 驱动注册表：协议归属与注销、无提供方的协议与导航地址都为 `none`、提供方在地址已被持有后到达与在持有中离开、注册随 fiber 消失、首个持有者开流末个关流、一址一源、包括已中止信号在内的 pin、重挂读到最新值且不重开、重开为新流、中止后帧丢弃且迭代器归还、流自行结束、失败帧与最后值并存、`reload` 转发。`tests/apply.client.spec.ts` 在 `SlotTestRuntime` 里挂载插件，经一个根作用域探针组件验证 `useResource` 到达 props、渲染它即打开提供方的流、dispose 插件同时撤走服务与 hook。
+
+## Deferred
+
+回收空闲记录、与 Remote 面解耦的资源自有失败类型、`chat` 与 `terminal` 协议都还开放；各自等待一个消费方。面向开发者的参考是 [docs/subsystems/client-resources.md](../../../../docs/subsystems/client-resources.zh.md)；消费这个模型的 Sidebar 见 [docs/subsystems/sidebar-right.md](../../../../docs/subsystems/sidebar-right.zh.md)。
diff --git a/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.i18n.yaml
new file mode 100644
index 0000000000..f7a6978cca
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.md
+2026-09-05-sidebar-tab-types-and-navigation.md: a79292eba25828287ce43ad16b7eb917dcdddcb4
+2026-09-05-sidebar-tab-types-and-navigation.zh.md: bf661948036257366714617b192525ac35b0905f
diff --git a/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.md b/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.md
new file mode 100644
index 0000000000..a79292eba2
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.md
@@ -0,0 +1,121 @@
+# Agent Note: Right Sidebar tab types and navigation
+
+Status: implemented
+
+English | [中文](2026-09-05-sidebar-tab-types-and-navigation.zh.md)
+
+## Problem
+
+The [docking surface](../feature/2026-09-04-right-sidebar-docking-infrastructure.md) gives the right Sidebar panes, tabs, and floating panels, but a pane full of tabs is only useful if other plugins can put content into them. That needs three contracts the surface itself does not define: how a plugin declares a kind of tab and the addresses it can show, how any caller — a produced-file chip in the conversation, a row in a file tree, a plugin's own button — asks the Sidebar to show something, and what a tab's body may rely on at runtime. Each contract is a public face that plugins shipped from outside this repository will write against, so each has to be settled before those plugins exist: a renamed field, a changed enum value, or a different address grammar afterwards breaks every one of them.
+
+Two constraints shaped the answers. Dynamic client plugins may not import runtime values from one another — a function, a constant, a class — only types, so nothing in these contracts may require a helper function or an exported constant from the Sidebar package. And the Web client already has one component model, the Slot system; a second one for tabs would be a parallel framework to learn and maintain.
+
+## Decision
+
+A tab type is a static registration into `ctx.sidebarRightTabs`; a tab's body and title are ordinary keyed Slot registrations; `ctx.sidebarRight` opens content in exactly two ways — a resource by address, or a page by kind — and otherwise only operates the layout; and bodies read occurrence information through the framework-injected `useTabInfo()`. The four faces are described below in the order a plugin author meets them.
+
+### The type registry: `ctx.sidebarRightTabs`
+
+`register(definition): () => void` records one tab type and returns the disposer the caller holds in its own `ctx.effect`, so a type lives exactly as long as the plugin that contributed it. The definition is static:
+
+```ts ignore-check
+interface SidebarRightTabDefinition {
+  readonly id: string                                   // this implementation's identity in the tab system
+  readonly kind: string                                 // what the tabs of this type are; what openTab names
+  readonly patterns?: readonly string[]                 // resource-address globs; omitted by a page type
+  readonly priority?: 'extension' | 'builtin' | 'fallback'   // defaults to extension
+  readonly canOpen?: (address: string) => boolean       // veto after a glob matched
+  readonly title: (address: string) => string           // chip text, captured at open time
+  readonly guide?: readonly SidebarRightGuideEntry[]    // entry boxes on the guide page
+}
+```
+
+`id` and `kind` are different things. `kind` is the type discriminator — what a tab *is*, what `openTab` names, what tab identity is built from. `id` is the identity of one *implementation* of a kind, unique across every registration; a package name is the natural value. The two are separate because a kind is not unique: an `extension` may register the kind a `builtin` already holds, and the two implementations then coexist in the registry with the extension in force. The registry rejects a second registration of an `id`, a second registration in the same band of a kind, and any registration meeting a `fallback` of the same kind; it accepts exactly the extension-over-builtin pair, and the builtin resumes when the extension unregisters.
+
+`patterns` are globs over resource addresses, matched with `picomatch` under VS Code's editor-resolver rule with one local change: a pattern containing `:` is matched against the whole address (`dsh-resource://file/**`), one without is matched against the URI's path at any depth (`*.md`), matching ignores case and does not hide dotfiles, and an address that is not a URI matches no path pattern. A page type — the guide, the file tree — recognizes no address and omits `patterns`; it is opened by kind.
+
+`priority` is one of three literal bands, spelled as strings so that a type from another package needs no runtime import: `extension` is the band of a type from outside the product and the highest, so a type that declares nothing outranks every viewer shipped here; `builtin` is the ordinary band for shipped types; `fallback` is the plain-content position that anything more specific should beat, which VS Code's text editor holds implicitly and our text preview holds explicitly. `candidates(address)` returns every type whose globs match and whose `canOpen` does not veto, ranked by band, then by the length of the longest pattern that matched, then by registration order. `claim(address, kind?)` takes the best candidate, or the named kind's type in force when the caller overrides (its globs are not consulted; naming the type is the decision), and throws for an address nothing will open — a wiring mistake, not a user error. `get(kind)` returns the type in force; `entries()` and `guide()` list the types and their guide boxes in force; `subscribe` observes changes.
+
+`title(address)` and `guide[].title()` are thunks read on every use, so a language change needs no re-registration. The registry itself is a plain object provided at `apply`'s top level **without** `Service.tracker`: a tracker would rebind `this.ctx` to the caller's context, and a cross-package `register()` would then add its effect to the caller's fiber while that fiber is the active scope, stalling the browser boot with no error.
+
+### Bodies and titles: keyed Slot seats under the definition's `id`
+
+The type registry says what a type is; the Slot system says what it looks like. A type registers its body into the keyed, session-scoped seat `sidebar.right.pane.tab` under its own `id`, and may register a title component into `sidebar.right.pane.tab.title` under the same key. The seat that draws a tab resolves the tab's `kind` to the type in force through the registry and dispatches to that type's `id`, so an extension taking over a builtin's kind is rendered without either package knowing about the other, and without any priority number crossing a package boundary. A kind with no type in force renders the owner's "nothing can view this" notice; a type with no title registration gets the `title(address)` text the registry captured when the tab opened.
+
+Two further seats extend the guide and the menu: `sidebar.right.tab.guide` is a chain whose first non-declining entry replaces the shipped guide body without replacing the tab, and `sidebar.right.tab.menu.item` is a list appended after the kit's own layout actions, for actions that mean something about a tab's content. A type's controls — a reload, a wrap toggle — live inside its own body; the strip belongs to the panel and carries only the panel's controls. A type's own state is an ordinary Slot store and inject face on the body registration; the framework adds nothing to the component model.
+
+### Tab occurrence information
+
+[Responsive Sidebar and tab information](2026-09-07-sidebar-responsive-tab-info.md) supersedes this note's choice of flat owner props for occurrence information. Bodies, titles and guide replacements receive the framework-injected `useTabInfo()` to read `{ sidebar, panel, tab }`. The record, navigation, visibility, signal and bound actions live inside `tab`; exact fields belong to the [Sidebar reference](../../../../docs/subsystems/sidebar-right.md).
+
+The Tab domain still owns one occurrence per committed record, with an `AbortController`, navigation snapshot and actions bound to its Session. It pins the address in the [resource model](2026-09-05-client-resource-model.md) for the record's lifetime; hiding and switching Sessions do not end it, while closing the record aborts and releases it. Existing framework store and navigation hooks provide live reads, without subscriptions in tab implementations.
+
+### Navigation: `ctx.sidebarRight`
+
+The face opens content in two ways and does nothing else with content:
+
+```ts ignore-check
+openResource(address: string, options?: { kind?: string; params?: SidebarRightResourceParams; paneId?; replaceTab?: TabId; revealIfOpened?: boolean }): void
+openTab<K extends string>(kind: K, options?: { params?: SidebarRightTabParamsFor<K>; paneId?; replaceTab?: TabId; revealIfOpened?: boolean }): void
+```
+
+`openResource` takes a resource address — a `dsh-resource://<type>/…` URI, the only scheme the resource model has — and asks the registry who shows it: without `kind`, every type is consulted and the ranking decides; with `kind`, that type's implementation in force opens it. An address with any other scheme fails on the same path as an address nothing claims. `openTab` opens a page type by kind and never sees an address: the Sidebar records the tab under `sidebar://<kind>`, composed in one place inside the package, so that a page tab has a `contentId` for identity and history like any other tab. The scheme is bookkeeping: no caller composes it, no business package contains the literal, and the file tree and the guide are opened as `openTab('files')` and `openTab('guide')`.
+
+Both opens run the same four steps: resolve the type (by ranking or by kind), locate an existing tab by `(kind, contentId)` unless `revealIfOpened` is `false`, place the tab — in `replaceTab`'s pane and strip slot, in `paneId`, or in the active pane — and record the expansion, the open-or-focus, and the `replaceTab` close as one history entry before handing `{ address, params }` to the tab domain. Placement is the caller's business, never a type-level trait: the file tree opens into its own pane because it says so, as VS Code's Explorer passes `SIDE_GROUP` or `ACTIVE_GROUP` itself. `replaceTab` means one thing — open in that tab's place and close it in the same step — and exists for the guide's entry boxes, which hand their tab over to the page they name.
+
+Parameters are typed by what is being opened, through two merge-extensible maps declared in the Sidebar package and augmented by the owners of the keys:
+
+```ts
+interface SidebarRightResourceParamsMap {}   // key: resource type — the text preview declares { line?: number }
+interface SidebarRightTabParamsMap {}        // key: kind — a page type declares its own shape, or nothing
+```
+
+`openResource` accepts the union of every declared resource shape and `openTab<K>` the shape declared for `K`; a body narrows `navigation.params` by the protocol or kind it knows it serves. Parameters belong to the resource type rather than to the viewer because a line number is a fact about a file location, not about the text preview, and any type that claims `file` addresses receives the same shape. Values must be JSON-serializable, and a record must be rebuildable from address and parameters alone, because undo, redo, reload, and HMR rebuild tabs after the opener is gone.
+
+Beside the two opens, the face carries `close(tabId)`, `active()`, `isExpanded()`, `toggleExpanded()`, and four operational methods — `focus(tabId)`, `split(paneId?)` (returning the new pane, or `undefined` when the pane budget or the width rule forbids the split, recording nothing), `float(tabId, rect?)`, and `dock(paneId)` — each recording one history entry and a no-op on a missing target or one already in the requested state. There is no layout snapshot, no subscription, and no lookup by address: the face grants control over the layout, not a view of it. The seat publishes its binding — its session, its store's actions, and its surface — while mounted; a command on the public face acts on the mounted session and throws with no mounted session surface. A tab's own actions reach their session's own store instead: the slot runtime mints one store per session, the plugin adopts each as it is minted, and the controller routes by session id, so an action fired after the user switched sessions still lands, and does nothing for a session whose store was never minted.
+
+### Addresses
+
+Addresses come in two families that never mix. Resource addresses are the resource model's `dsh-resource://<type>/…` URIs (a workspace file is `dsh-resource://file/session/<sessionId>/<path relative to that session's workspace root>`, an arbitrary file `dsh-resource://file/absolute/<absolute path>`, both built and parsed by `dsh-util-workspace-path`); they are what `openResource` takes, what `patterns` match, and what `useResource` reads. Navigation addresses name pages rather than data; today the only one is the internal `sidebar://<kind>` a page tab is recorded under. Only the resource family is a contract: the navigation family is composed and consumed inside the Sidebar, and a fuller navigation protocol is a later decision that this one leaves room for by keeping every navigation literal in one place.
+
+### Entry points
+
+The conversation's `openFile(path, { line? })` — tool-row path links, produced-file chips, closing-message mentions — encodes the path as a file resource address for the Session, and calls `openResource` with `params.line` when the caller knows one; the `read` tool row passes the line its `offset` argument started from. The strip's `+` calls `openTab('guide', { paneId, revealIfOpened: false })` for the pane it sits in; a guide entry box calls `tab.actions.openTab(entry.kind, { replaceTab: true })`; a file-tree row calls `tab.actions.openResource(address)`, which lands in the tree's own pane.
+
+## Alternatives considered
+
+**A chain slot for tab dispatch, or a keyed slot alone.** A chain's `select` is not enumerable, and the guide page and the navigation face must enumerate types; a keyed slot carries a body and nothing else, so a type's title and address recognition had nowhere to live. Two stages — a definition registry plus keyed component seats — is the repository's existing pattern (`ConversationViewRegistry`).
+
+**Runtime hooks or an instance object per tab.** Several forms were tried on paper — a Cordis fiber per tab, an abstract base class, an `initial`/`create` pair returning an instance with `dispose`, a set of `useTab*` hooks, a framework-managed `useTabResource(fetch)`, a `useTabStream`. Rejected in turn: a fiber per tab is far too heavy; dynamic packages cannot share a base class or an exported constant; an instance layer duplicates what a Slot store and inject face already are; per-tab hooks restate owner props; a framework-owned fetch has no good cache key; and a stream hook on the tab domain asks the wrong owner — chat data must come from the chat domain, file data from the workspace file service. What remains is owner props plus one client-wide `useResource`. `visible` was later added as a prop rather than a hook for the same reason: it is one more fact about the occurrence, and the props already carry the occurrence. The rejection of occurrence-reading hooks is superseded by the [tab information decision](2026-09-07-sidebar-responsive-tab-info.md); the independent instance, fiber and data-stream ownership rationale still applies.
+
+**A per-pane tools seat for the active tab's controls (`sidebar.right.pane.tab.tools`).** Shipped for one review round, then removed: it put type-private buttons on the panel's strip beside the split and collapse controls, where they read as panel chrome. A type's controls belong in its own body.
+
+**Type-level placement (`opensInto`) and a hidden sibling heuristic.** Rejected: where a tab lands is the opener's business, exactly as VS Code's Explorer decides `sideBySide` itself.
+
+**Extension lists and numeric priorities.** `claims.extensions` cannot express `.d.ts`, `Dockerfile`, a directory constraint, or a whole scheme — it is a degenerate glob; numeric priorities need an exported constant that dynamic packages cannot import. Literal bands over globs. VS Code's own bands were reduced from five to three: an `option` band (listed, never chosen automatically) has no consumer until an "open with…" affordance exists, and a `default` band was renamed `extension` because the name read as the lowest tier while it is the highest.
+
+**One `open(address)` for everything, with a helper that builds page addresses.** The first design opened pages by address too, so a business package needed a `sidebar://<kind>` literal or a `sidebarAddress(kind)` helper from the Sidebar package. Both are forbidden by the value-import rule and both leak a navigation scheme that is not yet designed. Splitting the face into `openResource` and `openTab` puts the only literal inside the package and lets each mode type its parameters.
+
+**Naming a specific implementation when opening (`?impl=`), `find(address)`, `mode()`/`setMode()`, a layout snapshot, a `features` list.** All considered and left out. Naming an implementation belongs to a navigation protocol that does not exist yet; `find` and a snapshot would make the face a view of the layout when it is meant to be control over it; presentation mode is a UI toggle, not a plugin concern; a capability list is premature while the face is settling.
+
+**Slot priorities to express an extension taking over a builtin, then registry-minted slot keys.** The first attempt had the overriding type register its body at a lower slot priority through an exported constant — a value import across dynamic plugins, and a second rule system (slot priority) standing in for the registry's. The second attempt had the registry mint a key per registration and return it from `register()`, which made registration a two-step dance whose ordering mattered. Letting the implementation declare its own `id` — required, unique, the same string it registers its seats under — needs no constant, no minting, and no ordering, and gives the registry the identity it needs to reject duplicates.
+
+## Consequences
+
+- A type is one static object plus one or two keyed seat registrations; its occurrence information is read through injected `useTabInfo()`. The framework grows no per-type API surface, and a type shipped from outside this repository imports only types from the Sidebar package.
+- Two opens with two parameter maps mean a caller cannot open a page by address or a resource by kind alone, and the compiler tells it so; the cost is that every new resource type or page kind that wants typed parameters augments a map.
+- `id` and `kind` being distinct lets an extension replace a shipped type in place, per kind, with the builtin resuming when the extension unregisters; the cost is one more required field on every definition.
+- The navigation face is control-only. A plugin that needs to know the layout cannot ask for it, which keeps the layout's shape out of every plugin's contract until a navigation protocol decides what to expose.
+- The `sidebar://<kind>` literal lives in one file. Changing the navigation grammar later touches the Sidebar package and nothing else.
+- These faces are the part of the Sidebar that is fixed: addresses, registration fields and bands, the two opens and their parameter maps, seat names and injected tab information. Everything a user sees as behaviour — where a float snaps, when a split control greys out, the copy, the tree's ordering — is a product rule outside every contract here and changes without notice to any plugin.
+
+## Testing
+
+`ui-sidebar-right` specs cover the registry (bands, extension-over-builtin with resumption, `id` and same-band collisions, glob and path matching, `canOpen`, ranking and tiebreaks), both opens (normal, edge, and failure paths including the wrong scheme and an unregistered kind), `replaceTab` as one history entry, the seat resolving a kind to the implementation in force and back, `useTabInfo()` including `tab.visible` under collapse and floating, and the operational methods with their no-op and throw cases. The Web e2e suite drives the guide, the file tree, and a file open through the real plugin graph in Chromium. Both suites are keyless.
+
+## Deferred
+
+- A navigation protocol beyond `sidebar://<kind>`: sub-routes within a page, naming an implementation, and the ecosystem-facing rules for other navigation schemes.
+- Parameters for the shipped page types, which today declare none.
+- Opening into a session other than the one on screen from the public face, which acts on the mounted session only; a tab's own actions already act on their tab's session.
+- A localized message when an open fails from the conversation; the failure is currently the thrown error's text.
diff --git a/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.zh.md b/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.zh.md
new file mode 100644
index 0000000000..bf66194803
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.zh.md
@@ -0,0 +1,121 @@
+# Agent Note: 右侧 Sidebar 的 tab 类型与导航
+
+Status: implemented
+
+[English](2026-09-05-sidebar-tab-types-and-navigation.md) | 中文
+
+## Problem
+
+[停靠面](../feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md)给了右侧 Sidebar 分栏、tab 与浮动面板，但一格 tab 只有在别的插件能往里放内容时才有用。这需要三份停靠面自身不定义的契约：插件如何声明一种 tab 及其能展示的地址；任何调用方——会话区里的产出文件 chip、文件树里的一行、插件自己的按钮——如何请 Sidebar 展示某样东西；以及 tab 的正文在运行时能依赖什么。每一份都是仓外插件将来要对着写的公开面，所以必须在那些插件出现之前定下来：之后改一个字段名、一个枚举值或地址语法，就会同时弄坏它们全部。
+
+两条约束决定了答案。动态客户端插件之间不允许引用运行时值——函数、常量、类——只能引类型，因此这些契约里不得要求从 Sidebar 包引入帮助函数或导出常量。而 Web 客户端已经有一套组件模型，即 Slot 系统；再为 tab 造一套，就是第二个要学要维护的并行框架。
+
+## Decision
+
+tab 类型是向 `ctx.sidebarRightTabs` 的一次静态注册；tab 的正文与标题是普通的 keyed Slot 注册；`ctx.sidebarRight` 只以两种方式打开内容——按地址开资源、按 kind 开页——其余只操作布局；正文通过框架注入的 `useTabInfo()` 读取实例信息。下面按插件作者遇到的顺序描述这四个面。
+
+### 类型注册表：`ctx.sidebarRightTabs`
+
+`register(definition): () => void` 记录一种 tab 类型并返回注销器，调用方把它放进自己的 `ctx.effect`，于是类型的寿命恰好等于贡献它的插件。定义是静态的：
+
+```ts ignore-check
+interface SidebarRightTabDefinition {
+  readonly id: string                                   // this implementation's identity in the tab system
+  readonly kind: string                                 // what the tabs of this type are; what openTab names
+  readonly patterns?: readonly string[]                 // resource-address globs; omitted by a page type
+  readonly priority?: 'extension' | 'builtin' | 'fallback'   // defaults to extension
+  readonly canOpen?: (address: string) => boolean       // veto after a glob matched
+  readonly title: (address: string) => string           // chip text, captured at open time
+  readonly guide?: readonly SidebarRightGuideEntry[]    // entry boxes on the guide page
+}
+```
+
+`id` 与 `kind` 是两回事。`kind` 是类型判别符——tab *是什么*、`openTab` 点名什么、tab 身份由什么构成。`id` 是某个 kind 的一个*实现*的身份，在全部注册里唯一，包名是自然的取值。两者分开是因为 kind 并不唯一：`extension` 可以注册一个 `builtin` 已持有的 kind，两个实现随即在注册表里共存，生效的是 extension。注册表拒绝重复的 `id`、同一 kind 在同一档的第二次注册、以及任何与同 kind 的 `fallback` 相遇的注册；它只接受 extension 压 builtin 这一对，extension 注销后 builtin 恢复。
+
+`patterns` 是资源地址上的 glob，用 `picomatch` 按 VS Code 编辑器解析器的规则匹配，只有一处本地改动：含 `:` 的 pattern 匹配整个地址（`dsh-resource://file/**`），不含的匹配 URI 的路径且任意深度（`*.md`），匹配不区分大小写、不隐藏 dotfile，不是 URI 的地址不匹配任何路径 pattern。页类型——引导页、文件树——不识别任何地址，省略 `patterns`，按 kind 打开。
+
+`priority` 是三个字面量档位之一，写成字符串，好让别的包的类型不需要任何运行时引入：`extension` 是来自产品之外的类型的档位也是最高档，所以什么都不声明的类型压过这里随包交付的每个查看器；`builtin` 是随包类型的常规档；`fallback` 是任何更具体的东西都应压过的纯内容位置，VS Code 的文本编辑器隐含地占据它，我们的文本预览明确地占据它。`candidates(address)` 返回 glob 命中且 `canOpen` 未否决的每个类型，按档位、再按命中的最长 pattern 长度、再按注册顺序排序。`claim(address, kind?)` 取最佳候选，或在调用方指定时取该 kind 生效的类型（不查它的 glob；点名即决定），对无人愿开的地址抛错——这是接线错误，不是用户错误。`get(kind)` 返回生效类型；`entries()` 与 `guide()` 列出生效类型及其引导入口；`subscribe` 观察变化。
+
+`title(address)` 与 `guide[].title()` 是每次使用时重读的 thunk，语言切换无需重新注册。注册表本身是 `apply` 顶层提供的普通对象，**不带** `Service.tracker`：tracker 会把 `this.ctx` 重绑到调用方上下文，跨包 `register()` 就会在调用方 fiber 仍是活动作用域时往它上加 effect，浏览器启动会无声卡死。
+
+### 正文与标题：按定义 `id` keyed 的 Slot 坑位
+
+类型注册表说类型是什么；Slot 系统说它长什么样。类型把正文注册进 keyed、session 作用域的坑位 `sidebar.right.pane.tab`，键是自己的 `id`，并可把标题组件注册进 `sidebar.right.pane.tab.title`，键相同。画 tab 的座位经注册表把 tab 的 `kind` 解析成生效类型，再派发到该类型的 `id`，于是 extension 接管 builtin 的 kind 时两个包互不知晓也能正确渲染，且没有任何优先级数字跨过包边界。没有生效类型的 kind 渲染属主的「没有东西能查看它」提示；没注册标题的类型得到注册表在打开时捕获的 `title(address)` 文本。
+
+另有两个坑位扩展引导与菜单：`sidebar.right.tab.guide` 是 chain，第一个不拒绝的条目在不替换 tab 的前提下替换随包引导正文；`sidebar.right.tab.menu.item` 是 list，追加在库自身布局动作之后，放与 tab 内容有关的动作。类型自己的控件——重载、换行开关——住在自己正文里；tab 条属于面板，只放面板的控件。类型自己的状态是正文注册上普通的 Slot store 与 inject 面；框架不给组件模型添任何东西。
+
+### 标签实例信息
+
+[响应式 Sidebar 与标签信息](2026-09-07-sidebar-responsive-tab-info.zh.md)取代本记录中以平铺 owner props 传递实例信息的选择。正文、标题与引导页替换项接收框架注入的 `useTabInfo()`，以 `{ sidebar, panel, tab }` 读取所属 Sidebar、窗格与标签。实例的记录、导航、可见性、signal 与绑定动作均在 `tab` 内；精确字段见 [Sidebar 参考](../../../../docs/subsystems/sidebar-right.zh.md)。
+
+标签域仍为每个已提交记录拥有一个实例，包括 `AbortController`、导航快照和绑定到所属 Session 的动作。记录存活期间，其地址被钉在[资源模型](2026-09-05-client-resource-model.zh.md)中；隐藏与切换 Session 不结束实例，关闭记录则中止并释放它。框架已有的存储与导航钩子提供实时读取，类型不自行订阅。
+
+### 导航：`ctx.sidebarRight`
+
+该面以两种方式打开内容，对内容不做别的事：
+
+```ts ignore-check
+openResource(address: string, options?: { kind?: string; params?: SidebarRightResourceParams; paneId?; replaceTab?: TabId; revealIfOpened?: boolean }): void
+openTab<K extends string>(kind: K, options?: { params?: SidebarRightTabParamsFor<K>; paneId?; replaceTab?: TabId; revealIfOpened?: boolean }): void
+```
+
+`openResource` 接一个资源地址——`dsh-resource://<type>/…` URI，资源模型仅有的 scheme——并问注册表谁来展示：不带 `kind` 时问遍所有类型由排序决定；带 `kind` 时由该类型生效的实现打开。其它 scheme 的地址与无人认领的地址走同一条失败路径。`openTab` 按 kind 打开页类型，永远见不到地址：Sidebar 把该 tab 记账在 `sidebar://<kind>` 下，这个字面量只在包内一处拼装，为的是页 tab 与其它 tab 一样有 `contentId` 供身份与历史使用。这个 scheme 只是记账：没有调用方拼它，业务包里没有这个字面量，文件树与引导页分别以 `openTab('files')`、`openTab('guide')` 打开。
+
+两种打开走同样四步：解析类型（按排序或按 kind）；除非 `revealIfOpened` 为 `false`，否则按 `(kind, contentId)` 定位已有 tab；落位——落在 `replaceTab` 的格与条位、`paneId`、或活跃格；把展开、打开或聚焦、以及 `replaceTab` 的关闭记为一条历史，再把 `{ address, params }` 交给 tab 域。落位是调用方的事，从不是类型级特性：文件树把文件开进自己的格是因为它自己说了，正如 VS Code 的 Explorer 自己传 `SIDE_GROUP` 或 `ACTIVE_GROUP`。`replaceTab` 只有一个含义——在那个 tab 的位置打开并在同一步关掉它——为的是引导页入口框把自己的 tab 交给所点的页。
+
+参数按被打开的东西定型，经 Sidebar 包声明、由键的拥有者增补的两张可声明合并表：
+
+```ts
+interface SidebarRightResourceParamsMap {}   // key: resource type — the text preview declares { line?: number }
+interface SidebarRightTabParamsMap {}        // key: kind — a page type declares its own shape, or nothing
+```
+
+`openResource` 接受所有已声明资源形状的联合，`openTab<K>` 接受为 `K` 声明的形状；正文按自己所服务的协议或 kind 收窄 `navigation.params`。参数属于资源类型而非查看器，因为行号是关于文件位置的事实，不是关于文本预览的，任何认领 `file` 地址的类型收到同一形状。值必须可 JSON 序列化，一条记录必须只凭地址与参数就能重建，因为撤销、重做、刷新与 HMR 都在开启方已不在时重建 tab。
+
+除两种打开外，该面还有 `close(tabId)`、`active()`、`isExpanded()`、`toggleExpanded()`，以及四个操作型方法——`focus(tabId)`、`split(paneId?)`（返回新格，预算或宽度规则不允许分栏时返回 `undefined` 且不记账）、`float(tabId, rect?)` 与 `dock(paneId)`——每个记一条历史，目标不存在或已在目标态时为 no-op。没有布局快照、没有订阅、没有按地址查找：该面给的是对布局的控制权，不是布局的视图。座位挂载期间发布其绑定——自己的会话、其 store 的 action 与其面；公开面上的命令作用于已挂载会话，没有已挂载会话面时抛错。tab 自己的动作则到达其会话自己的 store：slot 运行时每个会话铸一个 store，插件在铸出时逐个收养，控制器按会话 id 路由，因此用户切换会话之后触发的动作照样落地，而 store 从未铸出的会话什么也不做。
+
+### 地址
+
+地址分两族，永不混用。资源地址是资源模型的 `dsh-resource://<type>/…` URI（工作区文件是 `dsh-resource://file/session/<sessionId>/<相对该会话工作区根的路径>`，任意文件是 `dsh-resource://file/absolute/<绝对路径>`，都由 `dsh-util-workspace-path` 构造与解析）；它们是 `openResource` 的入参、`patterns` 的匹配对象、`useResource` 的读取对象。导航地址命名的是页而非数据；今天唯一的一种是页 tab 记账用的内部 `sidebar://<kind>`。只有资源族是契约：导航族在 Sidebar 内部拼装与消费，更完整的导航协议是之后的决定，本决定通过把所有导航字面量留在一处为它预留空间。
+
+### 入口
+
+会话区的 `openFile(path, { line? })`——工具行路径链接、产出文件 chip、收尾消息提及——把路径编码为该 Session 的文件资源地址并调用 `openResource`，调用方知道行号时带 `params.line`；`read` 工具行传入其 `offset` 参数起始的行。tab 条的「+」为所在格调用 `openTab('guide', { paneId, revealIfOpened: false })`；引导入口框调用 `tab.actions.openTab(entry.kind, { replaceTab: true })`；文件树的一行调用 `tab.actions.openResource(address)`，落在树自己的格里。
+
+## Alternatives considered
+
+**用 chain 坑位派发 tab，或只用 keyed 坑位。** chain 的 `select` 不可枚举，而引导页与导航面必须枚举类型；keyed 坑位只带正文，类型的标题与地址识别无处可住。两段——定义注册表加 keyed 组件坑位——是仓库既有模式（`ConversationViewRegistry`）。
+
+**运行时 hook 或每 tab 一个实例对象。** 纸面上试过多种形态——每 tab 一个 Cordis fiber、抽象基类、返回带 `dispose` 实例的 `initial`/`create` 对、一组 `useTab*` hook、框架托管的 `useTabResource(fetch)`、`useTabStream`。依次否决：每 tab 一个 fiber 太重；动态包无法共享基类或导出常量；实例层重复了 Slot store 与 inject 面已经是的东西；每 tab hook 复述 owner props；框架托管的 fetch 没有好的缓存键；tab 域上的流 hook 问错了主人——聊天数据必须来自聊天域，文件数据来自工作区文件服务。剩下的是 owner props 加一个全客户端的 `useResource`。`visible` 后来以 prop 而非 hook 加入也是同一理由：它是关于该次出现的又一个事实，而 props 已经承载了该次出现。 对实例读取钩子的否决由[标签信息决策](2026-09-07-sidebar-responsive-tab-info.zh.md)取代；对独立实例对象、fiber 与数据流所有权的理由仍适用。
+
+**每格一个工具区坑位放活跃 tab 的控件（`sidebar.right.pane.tab.tools`）。** 上线一轮评审后删除：它把类型私有按钮放到面板 tab 条上、与分栏和收起控件并列，读起来像面板 chrome。类型的控件属于自己的正文。
+
+**类型级落位（`opensInto`）与隐藏的相邻格启发式。** 否决：tab 落在哪是开启方的事，正如 VS Code 的 Explorer 自己决定 `sideBySide`。
+
+**扩展名列表与数字优先级。** `claims.extensions` 表达不了 `.d.ts`、`Dockerfile`、目录约束或整个 scheme——它是退化的 glob；数字优先级需要动态包无法引入的导出常量。字面量档位加 glob。VS Code 自己的档位从五个收成三个：`option` 档（只列出、永不自动选中）在「用其他方式打开」存在之前没有消费者，`default` 档改名 `extension`，因为那个名字读起来像最低档而它是最高档。
+
+**一个 `open(address)` 包打天下，外加拼页地址的帮助函数。** 第一版页也按地址打开，于是业务包需要 `sidebar://<kind>` 字面量或来自 Sidebar 包的 `sidebarAddress(kind)` 帮助函数。两者都被值引用规则禁止，也都泄露了尚未设计的导航 scheme。把面拆成 `openResource` 与 `openTab`，唯一的字面量留在包内，且每种模式各自定型参数。
+
+**打开时点名某个实现（`?impl=`）、`find(address)`、`mode()`/`setMode()`、布局快照、`features` 清单。** 都考虑过并留在外面。点名实现属于尚不存在的导航协议；`find` 与快照会把该面变成布局的视图，而它本该是对布局的控制；呈现模式是 UI 开关不是插件关心的事；能力清单在该面尚在收敛时为时过早。
+
+**用 Slot 优先级表达 extension 接管 builtin，随后是注册表铸造的坑位键。** 第一次尝试让覆盖方经一个导出常量以更低的 Slot 优先级注册正文——这是动态插件间的值引用，也是拿第二套规则（Slot 优先级）替注册表的规则站台。第二次尝试让注册表为每次注册铸一个键并从 `register()` 返回，这把注册变成了两步且顺序敏感的舞步。让实现自己声明 `id`——必填、唯一、与它注册坑位所用的同一个串——既不需要常量，也不需要铸键与顺序，还给了注册表拒绝重复所需的身份。
+
+## Consequences
+
+- 一个类型 = 一个静态对象 + 一到两个 keyed 坑位注册；其实例信息通过注入的 `useTabInfo()` 读取。框架不长任何按类型的 API 面，仓外类型从 Sidebar 包只引类型。
+- 两种打开配两张参数表，意味着调用方无法只按地址开页或只按 kind 开资源，编译器会说明；代价是每个想要类型化参数的新资源类型或页 kind 都要增补一张表。
+- `id` 与 `kind` 分离让 extension 能按 kind 原位替换随包类型，extension 注销后 builtin 恢复；代价是每个定义多一个必填字段。
+- 导航面只有控制权。需要知道布局的插件无法索取，这让布局的形状在导航协议决定暴露什么之前不进任何插件的契约。
+- `sidebar://<kind>` 字面量住在一个文件里。之后改导航语法只碰 Sidebar 包。
+- 这些面是 Sidebar 里被定死的部分：地址、注册字段与档位、两种打开及其参数表、slot 名与注入的标签信息。用户看到的一切行为——浮窗贴到哪、分栏控件何时置灰、文案、树的排序——都是这里任何契约之外的产品规则，改动无需通知任何插件。
+
+## Testing
+
+`ui-sidebar-right` 的 spec 覆盖注册表（档位、extension 压 builtin 及恢复、`id` 与同档冲突、glob 与路径匹配、`canOpen`、排序与平局）、两种打开（正常、边界与失败路径，含错误 scheme 与未注册 kind）、`replaceTab` 记一条历史、座位把 kind 解析到生效实现并回退、`useTabInfo()` 含折叠与浮窗下的 `tab.visible`、以及操作型方法的 no-op 与抛错情形。Web e2e 套件在 Chromium 里经真实插件图驱动引导页、文件树与一次文件打开。两套均无需密钥。
+
+## Deferred
+
+- `sidebar://<kind>` 之外的导航协议：页内子路由、点名实现、以及面向生态的其它导航 scheme 规则。
+- 随包页类型的参数，今天未声明任何。
+- 从公开面往屏上会话之外的会话里打开；公开面只作用于已挂载的会话，而 tab 自己的动作已作用于其所在会话。
+- 从会话区打开失败时的本地化提示；目前是抛错文本本身。
diff --git a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.i18n.yaml
new file mode 100644
index 0000000000..e8267647e2
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-05-workspace-files-service.md
+2026-09-05-workspace-files-service.md: a95e083f8cea57b957a2c060fe1b7f2b76050153
+2026-09-05-workspace-files-service.zh.md: 59c638157f3e65efe3b89b220401434d1f2370b0
diff --git a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.md b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.md
new file mode 100644
index 0000000000..a95e083f8c
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.md
@@ -0,0 +1,151 @@
+# Agent Note: Workspace file service
+
+Status: implemented
+
+English | [中文](2026-09-05-workspace-files-service.zh.md)
+
+## Problem
+
+The Web client needs to look at files inside a session's workspace from a browser that may not be on the Host machine: a file the agent produced, the path a `read` tool row names, later a file tree and previews of files that are neither small nor text. The one endpoint that read a workspace file over the wire lived on the Session Controller as `workspace-file.ts`, beside session lifecycle it had nothing to do with. It returned a whole file under one total byte cap, so a large log could not be looked at even in part and a binary could not be looked at at all; it had no `stat`, no listing, and no change signal, so a preview could not learn that the agent had rewritten the file without re-reading it; and its result named the file by a Host `url`, a spelling nothing on the Client used as an address.
+
+Two constraints frame any answer. Reads through `ctx.fs` are deliberately unconfined — the sandboxing backend fences writes and edits only and says so — so a web-facing read endpoint must own every fence itself, and the fences must survive a symlink that leaves the workspace, which a string-prefix test cannot see. And `dsh-fs` exposed one raw-byte read, `readBytes(target, signal, maxBytes)`, which refuses any file longer than its cap: correct for an image the model ingests whole, useless for one window of a large file.
+
+## Decision
+
+`packages/api/workspace-files` (`@deepseek-ai/dsh-api-workspace-files`) owns the Host `ctx.workspaceFiles` service, the `workspaceFiles` Remote namespace, and the Client `file` provider that turns `stat` and `changes` into live metadata for the [resource model](2026-09-05-client-resource-model.md); [dual-face packaging](2026-09-07-workspace-files-dual-face-package.md) governs their package organization. Every method confines itself to the workspace root the sandbox policy resolves for the addressed session, names files by their absolute path in the filesystem's execution world, and pages or windows content so that no method ever buffers a whole file. The byte window rides on a new `dsh-fs` seam, `FileSystem.readByteRange`, implemented by every provider. The Session Controller carries no workspace-file code.
+
+### Package topology
+
+[dual-face packaging](2026-09-07-workspace-files-dual-face-package.md) supersedes this note's choice of separate Host and Client packages; the file service, authorization, paging, and change-feed decisions here remain in force. Host and Client compile in separate leaf configurations, share wire types, and the Client does not import the Host runtime entry.
+
+| Face | Package | Files | Depends on |
+|---|---|---|---|
+| Host | `api/workspace-files/tsconfig.host.json` | `src/index.ts` (`WorkspaceFiles`, `Config`, gates, pager), `src/changes.ts` (`WorkspaceChangeFeed`), `src/types.ts` (wire types, error codes) | `dsh-fs`, `dsh-sandbox-policy`, `dsh-typert-protocol`, `dsh-agent`, `dsh-session` |
+| Client | `api/workspace-files/tsconfig.client.json` | `src/client/index.ts` (plugin body), `provider.ts`, `change-feed.ts`, `remote.ts`, `types.ts`, and shared `src/types.ts` | `dsh-api-gateway/client`, `dsh-api-session-controller/client`, `dsh-client-resources`, `dsh-util-workspace-path`, `dsh-typert-protocol`, and the package's generated `./remote` |
+
+`api/remotes` and both root aggregates reference the matching Host/Client leaf. The package exports `.`, `./client`, `./types`, `./typert`, and `./remote`, with one `workspace-files` web-app row supplying both faces. The Client plugin injects `['resources', 'remote', 'remote.workspaceFiles', 'sessions']`; the resource model takes result types directly from the protocol package, and the text preview owns the Sidebar parameter declaration, so the Client compilation graph has no reverse dependency on Remote assembly or Sidebar UI.
+
+### The `workspaceFiles` Remote namespace
+
+Every Host method takes the target `Agent` first, resolved by the Gateway from the Session identity on the wire, so a Client calls `remote.workspaceFiles.stat(sessionId, path, signal)` and never names a root. The five signatures, as `src/index.ts` declares them:
+
+```ts ignore-check
+@Remote async read(agent: Agent, path: string, range: WorkspaceFileRange, signal: AbortSignal): Promise<WorkspaceFileText>
+@Remote async readBytes(agent: Agent, path: string, range: WorkspaceByteRange, signal: AbortSignal): Promise<WorkspaceFileBytes>
+@Remote async stat(agent: Agent, path: string, signal: AbortSignal): Promise<WorkspaceFileStat>
+@Remote async list(agent: Agent, path: string, signal: AbortSignal): Promise<WorkspaceDirectoryListing>
+@Remote({ mode: 'stream' }) changes(agent: Agent, signal: AbortSignal): AsyncIterable<WorkspaceFileWatchFrame>
+```
+
+- **`stat`** returns `WorkspaceFileStat { absolutePath, version, bytes? }`: the file's identity, its opaque freshness token, and its size when the backend reports one. It accepts a regular file only.
+- **`read`** returns one window of lines, `WorkspaceFileText = WorkspaceFileStat & { offset, text, lines, eof }`; `lines` counts the page's lines, so a page holding one empty line (`text: ''`, `lines: 1`) and a page past the end (`lines: 0`) read differently. `range.offset` is the 1-based first line and defaults to 1; `range.limit` is the largest number of lines and defaults to `maxLines`, which it may not exceed. Lines end at `\n` and a final `\n` terminates the last line rather than opening an empty one; `text` joins the page's lines with `\n` and carries no terminator; `eof` is true when the page includes the last line, and an offset past the end returns an empty page with `eof` true. The pager walks `streamText`, counts the lines before the window without keeping them, admits each in-window segment against `maxBytes` before buffering it, and returns at the first character past the window, so a file of any size costs one page of memory. The `version` and `bytes` on a page are the stat's, taken before the stream.
+- **`readBytes`** returns one window of raw bytes, `WorkspaceFileBytes = WorkspaceFileStat & { offset, data, eof }`. `range.offset` is the 0-based first byte and defaults to 0; `range.length` is the largest byte count and defaults to `maxBytes`, which it may not exceed. `data` is base64, shorter than `length` where the file ends and empty at or past it; `eof` is true when the window includes the last byte. Nothing is decoded and nothing is refused as binary. `read` pages by lines and never by bytes; a byte window is `readBytes`.
+- **`list`** returns `WorkspaceDirectoryListing { path, entries, truncated }`: the listed directory as a workspace path relative to the root (empty for the root), its direct children in the backend's stable name order as `{ name, type, size? }`, and whether `maxEntries` cut the list. `type` is `file`, `directory`, or `other`; a symlink child reports the type of what it points to and a dangling one is `other`, while opening such a child still fails the link gate below. Dotfiles are listed; nothing is filtered.
+- **`changes`** yields `WorkspaceFileWatchFrame`: `{ kind: 'ready' }` after the observation queue is registered and the workspace root resolves, followed by `{ kind: 'change', change }`. The `WorkspaceFileChange` payload is `{ absolutePath, version }` for a present file or `{ absolutePath, absent: true }` for one observed gone. Its source is `fs/observed` inside the workspace root, never an OS watcher. Observations after the first pull are queued, including during root resolution; cancellation or plugin disposal ends the generation.
+
+### Paths on the wire
+
+Two path vocabularies leave the service, and each method uses exactly one. `read`, `readBytes`, `stat`, and `changes` name a file by `absolutePath`: its absolute path in the filesystem's execution world, symlinks resolved (`ctx.fs.processPath(target)`), so the Client provider matches a change frame to an open address by absolute path: the Client sends the address's path unchanged to the Host and binds the follower only to a successful `stat.absolutePath`, without reading a Session summary's cwd. `list` speaks workspace paths — the same syntax its `path` argument accepts, absolute or relative to the root — because its consumer is a tree rooted there. The field is called `absolutePath` and not `url` because it is not a resource address; the address grammar belongs to `dsh-util-workspace-path` and is described with the resource model. Input paths to `read`, `readBytes`, `stat`, and `list` are absolute or relative to the session's workspace root, never to the backend's own cwd.
+
+`version` is an opaque string a consumer compares for equality and never parses: the local backend derives it from device, inode, size, and nanosecond mtime and ctime, so a rewrite that leaves the content identical still changes it. `offset` means a line on `read` and a byte on `readBytes`; the two units never mix, and `eof` on either means the window reached the file's end.
+
+### The four gates
+
+Every `read`, `readBytes`, `stat`, and `list` passes four gates in order, and the constraints are the service's own because the filesystem does not confine reads. The path is inspected before containment is decided, so a caller learns whether an outside path exists and what kind it is before `outside-workspace` refuses it; that is accepted because the caller is the Session's own owner, who can already read the Host through the Agent.
+
+1. **The path itself.** `lstat` inspects the path before anything follows it: a missing path is `not-found`, and a symlink — wherever it points, including back inside the workspace — is `not-regular-file` (kind `symlink`) for the file methods and `not-directory` for `list`. An empty path is a `gateway/bad-request`.
+2. **Containment.** The path resolves to a target and `ctx.fs.contains(root, target)` decides, where `root` is `sandboxPolicy.resolve({ session }).workspaceRoot` resolved the same way (the session's cwd, falling back to the policy's configured root). A `..` traversal or an absolute path outside the root is `outside-workspace`. A string-prefix comparison is never used: `resolve` realpaths, so a prefix test cannot see a link that leaves the root.
+3. **The caps.** A page or window above `maxBytes`, or a `read` asking for more than `maxLines`, is refused, never shortened, because a silently cut page reads as the whole page; a listing above `maxEntries` is cut and says so.
+4. **Text.** For `read` only: content that is not UTF-8 up to the end of the page, a NUL byte in the backend's 8 KiB opening sample, or a NUL byte anywhere in the page is `not-text`; bytes past the page are not inspected.
+
+After the gates the file methods `stat` the target once more, because the file may have gone or changed kind between the inspection and the read: a vanished file is `not-found` and a replaced one `not-regular-file` with the new kind. The gate order has one visible consequence: an entry outside the root whose type already disqualifies it reports its kind, not its position.
+
+### Failures
+
+Each failure is one `RemoteError` code with typed details, declared beside the throwing code and discriminated by code, never by message.
+
+| Code | When | Details |
+|---|---|---|
+| `workspace-file/not-found` | no entry at the path, or the file vanished after the gates | `{ path }` |
+| `workspace-file/outside-workspace` | the resolved target is not inside the workspace root | `{ path }` |
+| `workspace-file/too-large` | a page's text or a requested byte window exceeds `maxBytes` | `{ path, limit }` |
+| `workspace-file/not-text` | invalid UTF-8 up to the page's end, or a NUL byte in the sample or the page (`read` only) | `{ path }` |
+| `workspace-file/not-regular-file` | `read`, `readBytes`, or `stat` on something that is not a regular file | `{ path, kind: 'directory' \| 'symlink' \| 'other' }` |
+| `workspace-file/not-directory` | `list` on something that is not a directory | `{ path, kind: 'file' \| 'symlink' \| 'other' }` |
+| `workspace-file/unsupported-address` | Client-minted: a resource address this provider cannot serve | `{ address }` |
+| `workspace-file/unknown-workspace` | Client-minted: an `absolute` address with no current Session | `{ address }` |
+| `gateway/bad-request` | an empty path, or an `offset`, `limit`, or `length` that is not an integer in range | `{}` |
+
+The set is append-only: a code may be added, and none is renamed or removed, because consumers branch on these strings across the wire.
+
+### Configuration
+
+Three fields, all validated positive integers changeable from `cordis.yml`, and no other tunables: `maxBytes` (default 2,097,152, 2 MiB) is the inclusive cap on one page's text and on one byte window; `maxLines` (default 5,000) is the default and largest page in lines; `maxEntries` (default 2,000) is the cap on returned directory entries. The file itself has no size cap: a caller pages or windows through it.
+
+### The `readByteRange` seam in `dsh-fs`
+
+A byte window of a large file needs a filesystem read bounded by the window, and `FileSystem` had only `readBytes(target, signal, maxBytes)`, which bounds by the whole file. `dsh-fs` therefore gains a second raw-byte primitive:
+
+```ts ignore-check
+abstract readByteRange(target: FsTarget, range: { offset: number; length: number }, signal?: AbortSignal): Promise<Uint8Array>
+```
+
+It returns the bytes at `[offset, offset + length)`, shorter when the file ends inside the window and empty when `offset` lies at or past the end. The window is the bound: a backend transfers at most `length` bytes beyond the prefix it skips to reach `offset` and never buffers the whole file, so the caller's cap on `length` is the guard against unbounded buffering, sitting beside `readBytes`'s bound rather than replacing it. The parameter order follows `readText`, `streamText`, and `listDir` — target, then the operation's own arguments, then an optional signal — rather than `readBytes`'s signal-in-the-middle form, which is the one exception in the class. Both `offset` and `length` are non-negative integers by precondition; the seam is a typed same-process boundary and validates nothing, and the Remote method validates at the wire.
+
+`fs-local` opens `createReadStream(targetKey, { start: offset, end: offset + length - 1 })` after the same regular-file stat as its other reads, returning an empty array for `length` 0 without opening a stream; `fs-sandbox` extends `LocalFileSystem` and inherits it. `fs-e2b` has an SDK that streams only from a file's start, so it skips `offset` bytes, copies `length` into the window, and cancels the stream the moment the window is full, transferring no more than the window beyond the skipped prefix; a stream that ends first is left to close. The four test doubles that extend `FileSystem` implement the method too.
+
+### The Client `file` provider
+
+The Client export registers one `ResourceProvider<'file'>` into `ctx.resources` for the plugin's lifetime and declares `ResourceProtocolMap.file`. The text-preview package registers this package's exported `WorkspaceFileParams` as `SidebarRightResourceParamsMap.file`.
+
+- **The value is metadata**, `WorkspaceFileResource { absolutePath, version, bytes?, changed }`; content never rides the stream because content can be arbitrarily large and a stream is for pushing change, not payload. A consumer reads pages with `read` (or windows with `readBytes`) and uses `version` and `changed` to know when they are stale.
+- **The address names the file; its scope selects the Session.** A `session` address's relative path reaches the Host unchanged for resolution and containment against that Session's workspace root; Client cwd is not a prerequisite. An `absolute` address reads through the current Session, failing with `workspace-file/unknown-workspace` when none is current. Unsupported grammar yields `workspace-file/unsupported-address`. These two Client errors end the stream and make reload a no-op.
+- **The frames.** The first frame is a `stat` (`changed: false`) or its failure as an `ok: false` frame; the provider throws and catches nothing, because the Remote face never rejects and a throw inside a provider stream is a programming error left to surface. A Host write carrying a version the value does not hold yields `changed: true` with the byte count kept and no stat; a frame carrying the held version is dropped. A reported disappearance stats again — still there is fresh metadata flagged `changed`, gone is a `not-found` frame with the previous value left for display. `reload(address)` stats again and yields `changed: false`. The follow is on the address, not the file: after a failed stat the stream continues, so the agent creating the file, or a reload, brings the resource live. Aborting the signal ends the stream silently.
+- **One `changes` subscription per Session.** The first follower opens `remote.$stream`, the last release disposes it, and successor streams and plugin teardown await pending closes. The Client starts its first `stat` only after accepting Host `ready`; sending a local WebSocket request is not Host acknowledgement. A follower registers by address, queues changes before its path is known, then filters queued and live frames by the successful stat's `absolutePath`, normalizing backslashes to slashes. Any Session write can trigger a re-stat before the first successful binding. Gateway supervision reconnects carrier loss; Host end or terminal failure ends followers and retains their last metadata until reopened.
+- **Navigation parameters.** `SidebarRightResourceParamsMap.file` is `WorkspaceFileParams { line?: number }`, a 1-based line to reveal. A line travels as a navigation parameter and not as part of the address, because the file is one piece of content whether it opens at the top or at line 400.
+
+### Related notes
+
+The [resource model](2026-09-05-client-resource-model.md) owns `ctx.resources`, `useResource`, the `dsh-resource://<type>/…` address grammar, and the reasoning for one resource per address; the [text preview and file tree](../feature/2026-09-05-sidebar-text-preview-and-file-tree.md) are the shipped consumers of `read`, `list`, and the `file` provider; the [right Sidebar docking infrastructure](../feature/2026-09-04-right-sidebar-docking-infrastructure.md) is the surface they open into; [workspace file links](../feature/2026-07-31-web-workspace-file-links.md) is where serving files over HTTP was rejected. Anyone extending this system reaches the same five methods through `remote.workspaceFiles` and the same `file` resource through `useResource<'file'>`; the wire types are published as `@deepseek-ai/dsh-api-workspace-files/types`.
+
+## Alternatives considered
+
+**Keeping the workspace file endpoint on the Session Controller.** The first form: one `read` under a total byte cap, registered as a sub-plugin of the Session Controller because that is where the wire entry already was. Rejected because a Workspace File service is its own capability — reading, statting, listing, and observing files inside a workspace root — and everything that queries workspace files belongs to it, while the Session Controller's concern is session lifecycle. The move also let the service grow to five methods without the Controller's file gaining a second purpose.
+
+**A dual-face package with reverse UI dependencies.** The split-package choice followed two project-reference cycles after `api/remotes` referenced the Client leaf: the resource model imported Remote assembly for result types, and the file provider imported Sidebar UI for its parameter map. TypeScript rejected these cycles with `TS6202`. [dual-face packaging](2026-09-07-workspace-files-dual-face-package.md) supersedes that split: result types come directly from the protocol package, and Sidebar parameter registration belongs to the text preview; both root aggregates retain explicit compiler entries.
+
+**Serving workspace files over HTTP.** Already rejected by [workspace file links](../feature/2026-07-31-web-workspace-file-links.md) on origin grounds and not revisited: `read` and `readBytes` carry plain text and base64 over the authenticated Remote carrier, so no document is served, no URL is minted, and no origin question arises.
+
+**Log-reachable authorization for the read.** The one precedent that sends file content over the wire, command attachments, authorizes only files that appear in the session log. Enough for produced files, but a typed path or a directory tree could never open. Path containment inside the workspace root was chosen, with the endpoint owning the constraints the filesystem's unconfined reads do not, and containment decided by `fs.contains` on resolved targets so a symlink cannot escape it.
+
+**Whole-file read and slice for the byte window.** The interim form of `readBytes` read the file from its start to the window's end through `readBytes(target, signal, offset + length)` and sliced. It cannot read a window of a file longer than that end — the seam refuses such a file as too large — so no window could ever report `eof: false`, which contradicts the reason the method exists. Rejected in favour of the `readByteRange` seam, whose bound is the window.
+
+**Naming the file field `url` (or `hostUrl`).** The Session Controller's `WorkspaceFileText.url` was the Host's `file:` URL of the file. Rejected once resource addresses existed: a URL on the wire reads as an address, and this one was not one — it was a differently encoded spelling of the same path the address carries, which the Client had to decode to match change frames. A wire field is named by what it is, so the field is `absolutePath` and the `changes` frames carry the same field.
+
+**A default `readByteRange` in the `FileSystem` base class.** A non-abstract default over `readBytes` would have spared the test doubles a method but could only be implemented by reading the whole file up to the window's end, the very behaviour rejected above, or by passing an unbounded cap. Abstract, with every provider and double implementing it.
+
+**String-prefix containment.** Comparing resolved path strings against the root is simpler than `fs.contains`, but `resolve` realpaths, so a symlink that leaves the root resolves to a path outside it while a prefix test on the unresolved spelling passes; and a prefix test on the resolved spelling still needs the backend's notion of "same file". The filesystem decides containment.
+
+## Consequences
+
+- Workspace file access belongs to the Host/Client faces of `api/workspace-files`; the Session Controller carries neither implementation, and compiler and runtime entries stay separate.
+- A file of any size opens: text by line page, anything by byte window, each costing one page or window of memory on the Host and never a whole file; the cost is that a consumer assembles pages itself and that a single line above `maxBytes` has no page at all, because pages are cut by lines.
+- Every filesystem provider now offers a windowed raw read. `fs-e2b` pays for it by transferring the skipped prefix, since its SDK cannot seek; `fs-local` seeks.
+- Paths on the wire are canonical: `absolutePath` and change frames spell a file with symlinks resolved. An address built from another spelling of the same file — a workspace root reached through a symlink — opens and stats it, but its change frames never match, so `changed` stays false until a reload.
+- Change frames report the agent's own operations only. A file edited by the user's editor, a shell, or a subprocess raises no frame; an agent merely reading a file that something else changed does raise one, because the read observes a new version.
+- The gate order reports kind before position, a page's `version` may be one write behind its content, and a stalled `changes` consumer grows Host memory, because a generation's queue is unbounded; each is a known trade-off recorded in the package README.
+- The `file` resource pushes change, not content, so a preview learns a file moved on without a payload and reads the pages it wants; a failed open keeps following the address, so the agent creating the file brings the tab live without user action.
+- `readBytes` has no shipped consumer yet: it is the wire form the image and binary previews build on.
+
+## Testing
+
+Host specs in `packages/api/workspace-files/tests` exercise the paged read (whole file, nested path, empty file, multi-byte UTF-8, the line window's edges, defaults and refused limits, carriage returns kept), the byte window (defaults, a middle window with more following, tail windows exact and short, past-end and empty files, NUL and invalid UTF-8 round-tripping through base64, version parity with `stat`, the cap as `too-large`, bad ranges, a window of a file far above the cap, and `eof` inferred without a size), `stat`, `list` with truncation, symlink children, and `not-directory`, the `changes` stream driven by `fs/observed` and filtered by root, and every gate and code against a real local backend, because a fake filesystem would let a prefix test pass the symlink case the gate exists to catch. Client specs in `packages/api/workspace-files/tests` cover the provider's frames (opening stat, failure frames, writes without content, disappearance, reload, recovery, abort), the change feed (one stream per session, fan-out by normalized path, queued frames, ending on signal or Host close), the unsupported-address cases, and registration and disposal with the fiber. `fs/fs`, `fs-local`, and `fs-e2b` specs pin `readByteRange`'s range semantics — a middle window, a tail shorter than asked, past-end and zero-length windows, errors, aborts, and the e2b cancel — and `dsh-util-workspace-path` specs pin the file-address grammar. The connection fixture serves `stat`, paged `read`, `list`, and an opt-in `changes` frame for the web e2e suite.
+
+## Deferred
+
+- A web e2e chain through the Sidebar: open a file, have the agent write it, see `changed`, reload.
+- Aliasing a follower under the Host's canonical spelling once the first `stat` reveals it, so a symlinked workspace root still receives change frames.
+- A bound on a `changes` generation's queue.
+- The shipped consumer of `readBytes` (image and binary previews) and any write, search, or media route; the service is read-only.
+- Scopes other than `session` in the file address; the grammar leaves room, the provider serves one.
+- Reload delivery per record: today `reload` re-stats every follower of the file's absolute path in the session, so two records naming one file — a `session` and an `absolute` address, or two readers with different addresses — clear each other's `changed` flag.
diff --git a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.zh.md b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.zh.md
new file mode 100644
index 0000000000..59c638157f
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.zh.md
@@ -0,0 +1,151 @@
+# Agent Note: 工作区文件服务
+
+Status: implemented
+
+[English](2026-09-05-workspace-files-service.md) | 中文
+
+## Problem
+
+Web 客户端需要从一个未必在 Host 机器上的浏览器查看会话工作区里的文件：agent 产出的文件、`read` 工具行点名的路径，之后还有文件树，以及既不小也不是文本的文件预览。唯一一个经线路读取工作区文件的端点以 `workspace-file.ts` 住在 Session Controller 上，与它毫无关系的会话生命周期为邻。它在一个总字节上限之下返回整个文件，因此大日志连一部分都看不了、二进制根本看不了；它没有 `stat`、没有列举、没有变更信号，预览不重读就无法得知 agent 已改写文件；其结果还以 Host 的 `url` 命名文件，而 Client 上没有任何东西把这种拼法当地址用。
+
+两个约束框定了任何答案。经 `ctx.fs` 的读取是有意不受限的——沙箱后端只围栏写与编辑，并明说了这一点——所以面向 web 的读端点必须自己拥有每一道围栏，而且围栏必须经得住一条离开工作区的符号链接，这是字符串前缀测试看不见的。另外 `dsh-fs` 只暴露一种原始字节读取 `readBytes(target, signal, maxBytes)`，它拒绝任何比上限更长的文件：对模型整体摄入的图片是正确的，对大文件的一个窗口则毫无用处。
+
+## Decision
+
+`packages/api/workspace-files`（`@deepseek-ai/dsh-api-workspace-files`）同时拥有 Host 服务 `ctx.workspaceFiles`、`workspaceFiles` Remote 命名空间，以及将 `stat` 与 `changes` 转成[资源模型](2026-09-05-client-resource-model.zh.md)实时元数据的 Client `file` 提供者；包组织方式由[双面包组织](2026-09-07-workspace-files-dual-face-package.zh.md)规定。每个方法都把自己限制在沙箱策略为被寻址会话解析出的工作区根内，以文件在文件系统执行环境中的绝对路径命名文件，并对内容分页或开窗，因此没有任何方法会缓冲整个文件。字节窗口依托 `dsh-fs` 新增的 seam `FileSystem.readByteRange`，由每个提供者实现。Session Controller 不再携带任何工作区文件代码。
+
+### 包拓扑
+
+[双面包组织](2026-09-07-workspace-files-dual-face-package.zh.md)取代本记录中把 Host 与 Client 分成两个包的组织选择；这里的文件服务、授权、分页和变更流约定保持不变。Host 与 Client 分别编译在两个叶配置中，共享线路类型，Client 不导入 Host 运行时入口。
+
+| 面 | 包 | 文件 | 依赖 |
+|---|---|---|---|
+| Host | `api/workspace-files/tsconfig.host.json` | `src/index.ts`（`WorkspaceFiles`、`Config`、围栏、切页器）、`src/changes.ts`（`WorkspaceChangeFeed`）、`src/types.ts`（线路类型、错误码） | `dsh-fs`、`dsh-sandbox-policy`、`dsh-typert-protocol`、`dsh-agent`、`dsh-session` |
+| Client | `api/workspace-files/tsconfig.client.json` | `src/client/index.ts`（插件体）、`provider.ts`、`change-feed.ts`、`remote.ts`、`types.ts`，以及共享的 `src/types.ts` | `dsh-api-gateway/client`、`dsh-api-session-controller/client`、`dsh-client-resources`、`dsh-util-workspace-path`、`dsh-typert-protocol`，以及本包生成的 `./remote` |
+
+`api/remotes` 和两个根聚合分别引用匹配的 Host/Client 叶子。包导出 `.`、`./client`、`./types`、`./typert` 和 `./remote`，web-app 中单个 `workspace-files` 条目供应两面。Client 插件注入 `['resources', 'remote', 'remote.workspaceFiles', 'sessions']`；资源模型直接从协议包取结果类型，Sidebar 参数声明归文本预览，因此 Client 编译图不再反向依赖 Remote 装配或右栏 UI。
+
+### `workspaceFiles` Remote 命名空间
+
+每个 Host 方法首参都是目标 `Agent`，由 Gateway 从线路上的 Session 身份解析而来，因此 Client 调用 `remote.workspaceFiles.stat(sessionId, path, signal)`，从不自行命名根。五个签名照 `src/index.ts` 的声明：
+
+```ts ignore-check
+@Remote async read(agent: Agent, path: string, range: WorkspaceFileRange, signal: AbortSignal): Promise<WorkspaceFileText>
+@Remote async readBytes(agent: Agent, path: string, range: WorkspaceByteRange, signal: AbortSignal): Promise<WorkspaceFileBytes>
+@Remote async stat(agent: Agent, path: string, signal: AbortSignal): Promise<WorkspaceFileStat>
+@Remote async list(agent: Agent, path: string, signal: AbortSignal): Promise<WorkspaceDirectoryListing>
+@Remote({ mode: 'stream' }) changes(agent: Agent, signal: AbortSignal): AsyncIterable<WorkspaceFileWatchFrame>
+```
+
+- **`stat`** 返回 `WorkspaceFileStat { absolutePath, version, bytes? }`：文件身份、不透明的新鲜度令牌，以及后端报得出时的大小。它只接受普通文件。
+- **`read`** 返回一个行窗口 `WorkspaceFileText = WorkspaceFileStat & { offset, text, lines, eof }`；`lines` 计页内行数，使只含一个空行的页（`text: ''`、`lines: 1`）与越过文件末尾的页（`lines: 0`）可区分。`range.offset` 是 1 起算的首行，缺省 1；`range.limit` 是最多行数，缺省 `maxLines` 且不得超过。行以 `\n` 结束，末尾的 `\n` 终止最后一行而不是开启一空行；`text` 以 `\n` 连接本页各行且不带终止符；页含最后一行时 `eof` 为 true，越过末尾的 offset 返回 `eof` 为 true 的空页。切页器沿 `streamText` 前进，数过窗口前的行而不保留，把每个窗内片段先按 `maxBytes` 核准再缓冲，并在越过窗口的第一个字符处返回，因此任意大小的文件只花一页内存。页上的 `version` 与 `bytes` 来自流之前的那次 stat。
+- **`readBytes`** 返回一个原始字节窗口 `WorkspaceFileBytes = WorkspaceFileStat & { offset, data, eof }`。`range.offset` 是 0 起算的首字节，缺省 0；`range.length` 是最多字节数，缺省 `maxBytes` 且不得超过。`data` 为 base64，文件在窗内结束则短于 `length`，位于或越过末尾则为空；窗口含最后一个字节时 `eof` 为 true。不做任何解码，也不按二进制拒绝。`read` 按行分页、绝不按字节；字节窗口走 `readBytes`。
+- **`list`** 返回 `WorkspaceDirectoryListing { path, entries, truncated }`：被列目录相对根的工作区路径（根为空串）、其直接子项按后端的稳定名序以 `{ name, type, size? }` 给出，以及 `maxEntries` 是否截断了列表。`type` 为 `file`、`directory` 或 `other`；符号链接子项报告其指向目标的类型，悬空者为 `other`，而打开这样的子项仍会在下文的链接关被拒。dotfile 照常列出，不做任何过滤。
+- **`changes`** 产出 `WorkspaceFileWatchFrame`：在观察队列注册且工作区根解析完成后先发 `{ kind: 'ready' }`，随后为 `{ kind: 'change', change }`。载荷 `WorkspaceFileChange` 对存在的文件为 `{ absolutePath, version }`，对消失的文件为 `{ absolutePath, absent: true }`。来源是工作区根内的 `fs/observed`，不监视操作系统。首次拉取后的观察都会排队，包括根解析期间的观察；取消或插件释放会结束该代流。
+
+### 线路上的路径
+
+离开服务的路径词汇有两套，每个方法只用其中一套。`read`、`readBytes`、`stat` 与 `changes` 以 `absolutePath` 命名文件：它在文件系统执行环境中、符号链接已解析的绝对路径（`ctx.fs.processPath(target)`），因此 Client 提供者按绝对路径把变更帧匹配到已打开的地址：Client 把地址路径原样交给 Host，并只按成功的 `stat.absolutePath` 绑定跟随者，不读取会话摘要的 cwd。`list` 说工作区路径——与其 `path` 参数相同的语法，绝对或相对根——因为其消费方是一棵以根为起点的树。该字段叫 `absolutePath` 而不叫 `url`，因为它不是资源地址；地址语法归 `dsh-util-workspace-path` 所有，与资源模型一并描述。`read`、`readBytes`、`stat` 与 `list` 的输入路径是绝对路径或相对会话工作区根的路径，从不相对后端自己的 cwd。
+
+`version` 是消费者只比较是否相等、从不解析的不透明字符串：本地后端由设备、inode、大小及纳秒级 mtime 与 ctime 导出，因此内容不变的重写也会改变它。`offset` 在 `read` 上指行、在 `readBytes` 上指字节；两套单位从不混用，二者的 `eof` 都表示窗口到达了文件末尾。
+
+### 四道关
+
+每次 `read`、`readBytes`、`stat` 与 `list` 依次过四道关，而这些约束是服务自己的，因为文件系统并不限制读取。路径先被检视再判定是否在工作区内，因此调用方在 `outside-workspace` 拒绝之前就能得知工作区外的路径是否存在、是何种类；这一点被接受，因为调用方就是 Session 的所有者，本来就能经 Agent 读 Host。
+
+1. **路径本身。** `lstat` 在跟随任何东西之前检查路径：缺失路径为 `not-found`；符号链接——不论指向哪里，包括指回工作区内——对文件方法为 `not-regular-file`（kind 为 `symlink`），对 `list` 为 `not-directory`。空路径是 `gateway/bad-request`。
+2. **包含关系。** 路径解析为目标，由 `ctx.fs.contains(root, target)` 判定，其中 `root` 是以同样方式解析的 `sandboxPolicy.resolve({ session }).workspaceRoot`（会话 cwd，退而取策略配置的根）。`..` 爬出或根外绝对路径为 `outside-workspace`。从不使用字符串前缀比较：`resolve` 会取 realpath，前缀测试看不见离开根的链接。
+3. **上限。** 超过 `maxBytes` 的页或窗口，或 `read` 索要超过 `maxLines` 的行数，一律拒绝、绝不截短，因为悄悄截短的页读起来就像整页；超过 `maxEntries` 的列表被截断并如实报告。
+4. **文本。** 仅限 `read`：到页末为止不是 UTF-8 的内容、后端 8 KiB 开头样本里的 NUL 字节，或页内任何位置的 NUL 字节，都是 `not-text`；页之后的字节不检查。
+
+过关之后文件方法再对目标 `stat` 一次，因为在检查与读取之间文件可能已消失或换了种类：消失者为 `not-found`，被替换者为带新种类的 `not-regular-file`。关的顺序有一个可见后果：根外条目若类型本身已不合格，报告的是其种类而不是其位置。
+
+### 失败
+
+每种失败都是一个带类型化 details 的 `RemoteError` 代码，声明在抛出它的代码旁，按代码而非消息区分。
+
+| 代码 | 何时 | Details |
+|---|---|---|
+| `workspace-file/not-found` | 路径处无条目，或文件在过关后消失 | `{ path }` |
+| `workspace-file/outside-workspace` | 解析出的目标不在工作区根内 | `{ path }` |
+| `workspace-file/too-large` | 一页文本或所请求的字节窗口超过 `maxBytes` | `{ path, limit }` |
+| `workspace-file/not-text` | 到页末为止的非法 UTF-8，或样本或页内的 NUL 字节（仅 `read`） | `{ path }` |
+| `workspace-file/not-regular-file` | 对非普通文件执行 `read`、`readBytes` 或 `stat` | `{ path, kind: 'directory' \| 'symlink' \| 'other' }` |
+| `workspace-file/not-directory` | 对非目录执行 `list` | `{ path, kind: 'file' \| 'symlink' \| 'other' }` |
+| `workspace-file/unsupported-address` | Client 铸出：本提供者无法服务的资源地址 | `{ address }` |
+| `workspace-file/unknown-workspace` | Client 铸出：没有当前会话时的 `absolute` 地址 | `{ address }` |
+| `gateway/bad-request` | 空路径，或不是范围内整数的 `offset`、`limit`、`length` | `{}` |
+
+这个集合只增不改不删：可以新增代码，但不重命名、不移除任何一个，因为消费方跨线路按这些字符串分支。
+
+### 配置
+
+三个字段，都是可在 `cordis.yml` 中修改、经校验的正整数，此外没有其他可调项：`maxBytes`（默认 2,097,152，即 2 MiB）是单页文本与单个字节窗口的含上限；`maxLines`（默认 5,000）是页的缺省与最大行数；`maxEntries`（默认 2,000）是返回目录条目数的上限。文件本身没有大小上限：调用方分页或开窗读完它。
+
+### `dsh-fs` 中的 `readByteRange` seam
+
+大文件的字节窗口需要一种以窗口为界的文件系统读取，而 `FileSystem` 只有以整文件为界的 `readBytes(target, signal, maxBytes)`。因此 `dsh-fs` 新增第二个原始字节原语：
+
+```ts ignore-check
+abstract readByteRange(target: FsTarget, range: { offset: number; length: number }, signal?: AbortSignal): Promise<Uint8Array>
+```
+
+它返回 `[offset, offset + length)` 处的字节，文件在窗内结束则变短，`offset` 位于或越过末尾则为空。窗口即界：后端最多传输为到达 `offset` 而跳过的前缀之外的 `length` 字节，从不缓冲整个文件，因此调用方对 `length` 的上限就是防无界缓冲的守卫，与 `readBytes` 的界并列而非取代它。参数顺序遵循 `readText`、`streamText` 与 `listDir`——先目标，再操作自己的参数，最后可选 signal——而不是 `readBytes` 把 signal 放中间的形式，那是该类中唯一的例外。`offset` 与 `length` 按前置条件都是非负整数；seam 是类型化的同进程边界，不做任何校验，由 Remote 方法在线路处校验。
+
+`fs-local` 在与其他读取相同的普通文件 stat 之后打开 `createReadStream(targetKey, { start: offset, end: offset + length - 1 })`，对 `length` 为 0 直接返回空数组而不开流；`fs-sandbox` 继承 `LocalFileSystem`，随之继承该方法。`fs-e2b` 的 SDK 只能从文件开头开始流式读取，于是它跳过 `offset` 字节、把 `length` 字节拷入窗口，并在窗口填满的那一刻取消流，除跳过的前缀外传输量不超过窗口；先行结束的流则任其关闭。继承 `FileSystem` 的四个测试替身也实现了该方法。
+
+### Client `file` 提供者
+
+Client 导出向 `ctx.resources` 注册一个 `ResourceProvider<'file'>`，存活期与插件相同，并声明 `ResourceProtocolMap.file`。文本预览包把本包导出的 `WorkspaceFileParams` 注册为 `SidebarRightResourceParamsMap.file`。
+
+- **值是元数据**，`WorkspaceFileResource { absolutePath, version, bytes?, changed }`；内容从不进入流，因为内容可以任意大，而流是用来推送变更而不是载荷的。消费者用 `read` 读页（或用 `readBytes` 开窗），并以 `version` 与 `changed` 得知它们何时过时。
+- **地址命名文件，作用域决定读取会话。** `session` 地址携带的相对路径原样交给 Host，由 Host 按该会话的工作区根解析并检查包含关系，不要求 Client 持有 cwd。`absolute` 地址经当前会话读取，缺少当前会话时产生 `workspace-file/unknown-workspace`。不支持的语法产生 `workspace-file/unsupported-address`。这两种 Client 错误会结束流，刷新无动作。
+- **帧。** 第一帧是 `stat`（`changed: false`）或其失败的 `ok: false` 帧；提供者不抛也不接，因为 Remote 面从不 reject，而提供者流里的抛错只可能是编程错误，任其浮出。携带值尚未持有的版本的 Host 写入产生 `changed: true`、保留字节数、不做 stat；携带已持有版本的帧被丢弃。报告的消失会再 stat 一次——仍在则是标为 `changed` 的新元数据，不在则是保留上一个值供展示的 `not-found` 帧。`reload(address)` 再 stat 一次并产生 `changed: false`。跟随的是地址而不是文件：stat 失败后流继续，因此 agent 创建该文件或一次刷新会让资源恢复正常。中止 signal 则流静默结束。
+- **每会话一条 `changes` 订阅。** 首位跟随者打开 `remote.$stream`，最后一位离开时释放，后继流和插件拆除等待关闭完成。Client 接受 Host 的 `ready` 后才开始首次 `stat`；本地发出 WebSocket 请求不是 Host 确认。跟随者先按地址注册，缓冲路径未知期间的变更，成功 stat 后按返回的 `absolutePath` 过滤排队与实时帧，反斜杠归一为斜杠。尚未成功绑定时，Session 内任何写入均可触发重新 stat。载体掉线由 Gateway 监督器重连；Host 结束或终态失败会结束跟随者，并保留最近元数据，直到重新打开。
+- **导航参数。** `SidebarRightResourceParamsMap.file` 是 `WorkspaceFileParams { line?: number }`，即要显露的 1 起算行号。行号作为导航参数而不是地址的一部分传递，因为不论从顶部还是第 400 行打开，文件都是同一份内容。
+
+### 相关记录
+
+[资源模型](2026-09-05-client-resource-model.zh.md)拥有 `ctx.resources`、`useResource`、`dsh-resource://<type>/…` 地址语法以及"每个地址一份资源"的推理；[文本预览与文件树](../feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md)是 `read`、`list` 与 `file` 提供者随包交付的消费方；[右侧 Sidebar 停靠基础设施](../feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md)是它们打开进去的界面；[工作区文件链接](../feature/2026-07-31-web-workspace-file-links.zh.md)是经 HTTP 供文件被否决之处。任何在这套体系上扩展的人都经 `remote.workspaceFiles` 触达同样的五个方法、经 `useResource<'file'>` 触达同样的 `file` 资源；线路类型以 `@deepseek-ai/dsh-api-workspace-files/types` 发布。
+
+## Alternatives considered
+
+**把工作区文件端点留在 Session Controller 上。** 最初形态：总字节上限之下的一个 `read`，作为 Session Controller 的子插件注册，因为线路入口本来就在那里。被否，因为 Workspace File 服务是自己的能力——在工作区根内读取、stat、列举与观察文件——凡查询工作区文件的都归它，而 Session Controller 关心的是会话生命周期。搬出也让服务长到五个方法而不给 Controller 的文件添第二重目的。
+
+**带有反向 UI 依赖的双面包。** 拆包选择源于 `api/remotes` 引用 Client 叶子后形成的两条工程引用环：资源模型为了结果类型引用 Remote 装配，文件提供者为了 Sidebar 参数表引用右栏 UI。TypeScript 以 `TS6202` 拒绝这些环。[双面包组织](2026-09-07-workspace-files-dual-face-package.zh.md)取代拆包选择：结果类型直接取自协议包，Sidebar 参数注册移至文本预览；保留两个根聚合中的显式编译入口。
+
+**经 HTTP 供工作区文件。** 已被[工作区文件链接](../feature/2026-07-31-web-workspace-file-links.zh.md)以 origin 理由否决且未重议：`read` 与 `readBytes` 经认证的 Remote 载体传送纯文本与 base64，因此不供文档、不铸 URL，也不产生 origin 问题。
+
+**读取的"日志可达"授权。** 唯一把文件内容送过线路的先例——命令附件——只授权出现在会话日志里的文件。对产出文件够用，但手输的路径或目录树永远打不开。选择了工作区根内的路径包含，端点自行承担文件系统不受限读取所不具备的约束，并由 `fs.contains` 对已解析目标判定包含关系，使符号链接无法逃逸。
+
+**为字节窗口整文件读取再切片。** `readBytes` 的临时形态经 `readBytes(target, signal, offset + length)` 从文件开头读到窗口末端再切片。它读不了比该末端更长的文件的窗口——seam 会以过大拒绝这样的文件——因此没有任何窗口能报告 `eof: false`，与该方法存在的理由相悖。被否，改为以窗口为界的 `readByteRange` seam。
+
+**把文件字段命名为 `url`（或 `hostUrl`）。** Session Controller 的 `WorkspaceFileText.url` 是 Host 侧文件的 `file:` URL。资源地址出现后即被否：线路上的 URL 读起来像地址，而这个不是——它只是地址所携同一路径的另一种编码拼法，Client 必须解码才能匹配变更帧。线路字段按其所是命名，因此字段为 `absolutePath`，`changes` 帧携带同一字段。
+
+**在 `FileSystem` 基类里给 `readByteRange` 一个默认实现。** 基于 `readBytes` 的非抽象默认能免去测试替身一个方法，但只能靠把文件从头读到窗口末端来实现——正是上文否决的行为——或者传一个无界上限。改为抽象方法，由每个提供者与替身实现。
+
+**字符串前缀包含判定。** 把解析后的路径字符串与根比较比 `fs.contains` 简单，但 `resolve` 会取 realpath，离开根的符号链接解析到根外路径，而对未解析拼法的前缀测试会放行；对已解析拼法的前缀测试也仍需后端对"同一文件"的定义。由文件系统判定包含关系。
+
+## Consequences
+
+- 工作区文件访问由 `api/workspace-files` 的 Host/Client 两面共同承担；Session Controller 不携带其中任何实现，两面的编译与运行时入口保持独立。
+- 任意大小的文件都能打开：文本按行页、任何文件按字节窗口，在 Host 上各自只花一页或一窗内存、从不整文件；代价是消费者自己拼装页面，且单行超过 `maxBytes` 的行没有任何页，因为页按行切。
+- 每个文件系统提供者现在都提供开窗的原始读取。`fs-e2b` 为此付出传输被跳过前缀的代价，因为其 SDK 不能 seek；`fs-local` 能 seek。
+- 线路上的路径是规范的：`absolutePath` 与变更帧以符号链接已解析的拼法命名文件。由同一文件另一种拼法铸出的地址——经符号链接到达的工作区根——能打开并 stat 它，但其变更帧永不匹配，因此 `changed` 在刷新前保持 false。
+- 变更帧只报告 agent 自己的操作。用户编辑器、shell 或子进程改动的文件不产生帧；agent 仅仅读取一个被别处改动的文件却会产生帧，因为读取观察到了新版本。
+- 关的顺序先报种类后报位置，页的 `version` 可能落后内容一次写入，停滞的 `changes` 消费者会让 Host 内存增长，因为一代流的队列无界；每一条都是包 README 记录在册的已知取舍。
+- `file` 资源推送变更而非内容，因此预览不靠载荷就得知文件已更新并读取它想要的页；失败的打开继续跟随地址，因此 agent 创建该文件时 tab 无需用户动作即恢复正常。
+- `readBytes` 尚无随包交付的消费方：它是图片与二进制预览赖以构建的线路形态。
+
+## Testing
+
+`packages/api/workspace-files/tests` 中的 Host spec 覆盖分页读取（整文件、嵌套路径、空文件、多字节 UTF-8、行窗口边界、缺省与被拒的 limit、保留回车）、字节窗口（缺省值、后面还有内容的中段窗口、恰好与变短的尾窗、越界与空文件、NUL 与非法 UTF-8 经 base64 往返、与 `stat` 一致的版本、作为 `too-large` 的上限、坏范围、远超上限的文件的一个窗口、无大小时推断的 `eof`）、`stat`、带截断、符号链接子项与 `not-directory` 的 `list`、由 `fs/observed` 驱动并按根过滤的 `changes` 流，以及针对真实本地后端的每道关与每个代码——因为假文件系统会让前缀测试放过这道关本为捕获的符号链接场景。`packages/api/workspace-files/tests` 中的 Client spec 覆盖提供者的帧（开头 stat、失败帧、不带内容的写入、消失、刷新、恢复、中止）、变更流（每会话一条流、按归一路径扇出、排队的帧、因 signal 或 Host 关闭而结束）、不支持地址的各种情形，以及随 fiber 的注册与释放。`fs/fs`、`fs-local` 与 `fs-e2b` 的 spec 钉住 `readByteRange` 的范围语义——中段窗口、短于所求的尾窗、越界与零长窗口、错误、中止以及 e2b 的取消——`dsh-util-workspace-path` 的 spec 钉住文件地址语法。connection fixture 为 web e2e 套件提供 `stat`、分页 `read`、`list` 与一帧可选启用的 `changes`。
+
+## Deferred
+
+- 一条经 Sidebar 的 web e2e 链：打开文件、让 agent 写它、看到 `changed`、刷新。
+- 在首次 `stat` 揭示 Host 的规范拼法后为跟随者加别名，使经符号链接的工作区根也能收到变更帧。
+- 给 `changes` 一代流的队列加上限。
+- `readBytes` 随包交付的消费方（图片与二进制预览）以及任何写入、搜索或媒体路由；本服务只读。
+- 文件地址中 `session` 之外的作用域；语法留有余地，提供者只服务一个。
+- 按记录投递重载：今天 `reload` 重新 stat 该会话中此文件绝对路径的所有跟随者，因此命名同一文件的两条记录——`session` 与 `absolute` 地址，或地址不同的两个读者——会互相清掉 `changed` 标记。
diff --git a/.agents/notes/implemented/architecture/2026-09-07-sidebar-responsive-tab-info.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-07-sidebar-responsive-tab-info.i18n.yaml
new file mode 100644
index 0000000000..0a04d3712e
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-07-sidebar-responsive-tab-info.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-07-sidebar-responsive-tab-info.md
+2026-09-07-sidebar-responsive-tab-info.md: ade20148cccd2233224417f762e65492828943bb
+2026-09-07-sidebar-responsive-tab-info.zh.md: 0903e4ff06ca187fcc1fd0e9d8de63f70d5cc427
diff --git a/.agents/notes/implemented/architecture/2026-09-07-sidebar-responsive-tab-info.md b/.agents/notes/implemented/architecture/2026-09-07-sidebar-responsive-tab-info.md
new file mode 100644
index 0000000000..ade20148cc
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-07-sidebar-responsive-tab-info.md
@@ -0,0 +1,31 @@
+# Agent Note: Responsive Sidebar and injected tab information
+
+Status: implemented
+
+English | [中文](2026-09-07-sidebar-responsive-tab-info.zh.md)
+
+## Problem
+
+Tab extensions need consistent live information about their containing pane and Sidebar without a growing list of owner props. The workbench must also preserve content while adapting to limited viewport space, without reopening a Sidebar the user has closed.
+
+## Decision
+
+The slot framework injects one `useTabInfo()` returning nested `sidebar`, `panel`, and `tab` fields. It composes the framework-bound layout and navigation hooks; extensions neither subscribe themselves nor receive a service object. Body visibility requires an active tab in an expanded Sidebar; title visibility does not require an active tab. Hiding or switching Sessions leaves the tab lifetime intact. Closing the record aborts its signal. Tab actions stay bound to their owning Session. Store adoption is a private capability of the plugin assembly, not a public controller operation.
+
+The frame protects 400px for the conversation by shrinking the right column, then closing it before shrinking the conversation. Its first-open preference is 45% of the viewport, retained thereafter in pixels, with a 300px floor and 70% viewport ceiling. The left column keeps its preference at widths of at least 1024px. Closing is recorded state: widening never opens it, while a user action or explicit Session API may. Refresh restores defaults rather than persisting layout.
+
+Fullscreen uses the same mounted content tree and covers the viewport while retaining the underlying column reservation. Opening below 768px selects automatic fullscreen; exiting it there closes the Sidebar. Widening can end automatic fullscreen but leaves manually selected fullscreen intact. The product permits two horizontal panes, a 50/50 initial split, and a 20–80% divider; narrow panes refuse new splits. The generic docking engine retains its independent capabilities. A fullscreen entry completes its slide before reporting the underlying track; that covered width change is instantaneous, so neither entry nor returning to normal reveals a background reflow. At the two-pane budget the split control is hidden; a one-pane width refusal remains disabled. On exit, the frame prepares the destination before the overlay retreats: no right track for close, a normal track for restore. Transition suppression survives clearing the fullscreen report and ends on the next geometry action.
+
+This decision supersedes the flat owner-props choice in [tab types and navigation](2026-09-05-sidebar-tab-types-and-navigation.md) and the no-concession, overlay presentation and product pane limit in [docking infrastructure](../feature/2026-09-04-right-sidebar-docking-infrastructure.md). Their registration, record-lifetime, state ownership and engine-selection rationale remain active.
+
+## Alternatives considered
+
+**Flat information props or three separate hooks.** A single nested read groups the three ownership levels and allows additional fields without proliferating props or readers.
+
+**Automatic reopening after a viewport change.** It makes opening depend on layout history rather than an explicit action. A closed Sidebar stays closed, with its content preserved.
+
+**A separate fullscreen content tree.** Remounting would interrupt tab-local state. The same element changes presentation instead.
+
+## Consequences
+
+Tab extensions use a framework-injected reader and keep their own store actions separate from `tab.actions`. Layout, seat and docking tests cover width concessions, explicit reopening, body/title visibility, tab lifetimes, horizontal drop zones and divider limits; browser tests exercise the assembled application. Compact mobile controls and layout persistence remain outside this decision.
diff --git a/.agents/notes/implemented/architecture/2026-09-07-sidebar-responsive-tab-info.zh.md b/.agents/notes/implemented/architecture/2026-09-07-sidebar-responsive-tab-info.zh.md
new file mode 100644
index 0000000000..0903e4ff06
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-07-sidebar-responsive-tab-info.zh.md
@@ -0,0 +1,31 @@
+# Agent Note: 响应式 Sidebar 与注入的标签信息
+
+Status: implemented
+
+[English](2026-09-07-sidebar-responsive-tab-info.md) | 中文
+
+## 问题
+
+标签扩展需要一致的所属窗格与 Sidebar 实时信息，而不依赖不断增长的 owner props。工作区也需要适应有限的视口空间，同时保留内容，并且不重新打开用户已经关闭的 Sidebar。
+
+## 决策
+
+Slot 框架注入一个 `useTabInfo()`，返回嵌套的 `sidebar`、`panel` 与 `tab` 字段。它组合框架绑定的布局与导航 hook；扩展既不自行订阅，也不接收服务对象。正文可见要求 Sidebar 展开且标签活跃；标题可见不要求标签活跃。隐藏或切换 Session 保留标签生命周期。关闭记录会中止其 signal。标签动作始终绑定到所属 Session。Store 收编是插件组装的私有能力，不是公共控制器操作。
+
+框架先缩小右列，再关闭右列，最后才缩小会话区，以保护会话区的 400px 宽度。右列首次打开偏好为视口的 45%，此后按像素保留，下限为 300px，上限为视口的 70%。在宽度至少为 1024px 时，左列保持自身偏好。关闭是被记录的状态：变宽不会打开右栏，用户动作或显式 Session API 可以打开。刷新恢复默认值，不持久化布局。
+
+全屏使用同一棵已挂载内容树，覆盖视口并保留底层列的占位。在 768px 以下打开会选择自动全屏；在此宽度下退出全屏会关闭 Sidebar。变宽可以结束自动全屏，但保留手动选择的全屏。产品允许两个水平窗格，初始按 50/50 分割，分割线范围为 20–80%；窄窗格拒绝新分栏。通用停靠引擎保留其独立能力。 全屏入场先完成滑入，再报告底层轨道；被覆盖的宽度变化瞬间完成，因此入场及返回普通模式都不暴露底层重排。达到两格预算时隐藏分栏控件；单格宽度不足时仍显示禁用控件。 退场时，框架先准备目标布局，再让覆盖层退出：关闭不留右轨道，恢复保留普通轨道。清除全屏报告时仍保留过渡抑制，直到下一次几何操作才结束。
+
+本决策取代[标签类型与导航](2026-09-05-sidebar-tab-types-and-navigation.zh.md)的平铺 owner props 选择，以及[停靠基础设施](../feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md)中的无让步、覆盖模式和产品窗格上限。它们的注册、记录生命周期、状态所有权与引擎选型理由继续有效。
+
+## 考虑过的替代方案
+
+**平铺信息 props 或三个独立 hook。** 一个嵌套读取接口按三个所有权层级分组，允许增加字段而不增加 props 或读取接口。
+
+**视口变化后自动重开。** 这会让打开依赖布局历史，而不是显式动作。关闭的 Sidebar 保持关闭，同时保留内容。
+
+**独立的全屏内容树。** 重新挂载会打断标签局部状态。因此由同一元素改变呈现方式。
+
+## 后果
+
+标签扩展使用框架注入的读取接口，自身 store actions 与 `tab.actions` 保持分离。布局、seat 与停靠测试覆盖列宽让步、显式重开、正文与标题可见性、标签生命周期、水平放置区与分割比例；浏览器测试覆盖组装后的应用。紧凑移动端控件与布局持久化不属于本决策。
diff --git a/.agents/notes/implemented/architecture/2026-09-07-workspace-files-dual-face-package.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-07-workspace-files-dual-face-package.i18n.yaml
new file mode 100644
index 0000000000..2b1ef7d81a
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-07-workspace-files-dual-face-package.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-07-workspace-files-dual-face-package.md
+2026-09-07-workspace-files-dual-face-package.md: adc900865cb8d5f19518828a9cb230a835d025f5
+2026-09-07-workspace-files-dual-face-package.zh.md: ccfa60417284129a280efd7ddad2ea275c242f1e
diff --git a/.agents/notes/implemented/architecture/2026-09-07-workspace-files-dual-face-package.md b/.agents/notes/implemented/architecture/2026-09-07-workspace-files-dual-face-package.md
new file mode 100644
index 0000000000..adc900865c
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-07-workspace-files-dual-face-package.md
@@ -0,0 +1,36 @@
+# Agent Note: Workspace files as one dual-face API package
+
+Status: implemented
+
+English | [中文](2026-09-07-workspace-files-dual-face-package.zh.md)
+
+## Problem
+
+The workspace file service and its browser resource provider evolve together, but their compiler graph contained reverse dependencies on Remote assembly and Sidebar UI. Splitting the packages avoided the cycles while separating ownership of the wire protocol from its Client model. A Host-only package with a types-only Client compiler entry also lacks the `dsh.client` and `./client` declarations that distinguish runtime exports in Client catalog analysis.
+
+## Decision
+
+`packages/api/workspace-files` owns both implementations. Its Host and Client leaf configurations remain direct references of their respective root aggregates; the solution root references both leaves. The Host exports the file service, `./client` exports the actual resource-provider plugin, and `dsh.client` declares the browser plugin. One web-app row loads both faces. This supersedes only the package-splitting decision in the [workspace file service note](2026-09-05-workspace-files-service.md), whose authorization, paging, and stream semantics remain unchanged.
+
+Two dependency directions keep the compiler graph acyclic:
+
+- `client/resources` imports `RemoteResult` and `RemoteFailure` from their defining `typert/protocol` package, not from `api/remotes`, which assembles providers that consume the resource model.
+- The text preview declares `SidebarRightResourceParamsMap.file` using the file package's exported parameter type. The file provider declares its resource value but imports no Sidebar UI. The caller imports the viewer's type entry when it needs that navigation declaration.
+
+These remove `remotes → workspace-files → resources → remotes` and `remotes → workspace-files → sidebar-right → ui-conversation → remotes`. Runtime Cordis service injection remains independent from TypeScript project references.
+
+## Alternatives considered
+
+**Keep separate packages.** This isolates the compiler cycle but splits one file capability's Host and Client ownership. Removing the reverse type dependencies permits the same dual-face organization as other API controllers.
+
+**Remove the root Client reference.** Transitive references still compile the leaf, but both root aggregates must explicitly name this package's matching face.
+
+**Change catalog analysis or add an empty Client plugin.** Neither supplies the requested browser implementation. A real `./client` export with `dsh.client` uses the analyzer's existing supported dual-face path.
+
+## Consequences
+
+Host wire methods and browser resource behavior are unchanged. The browser implementation, tests, and documentation have one package owner; Client type dependencies stop at the protocol and resource-model layers instead of reaching UI or Remote assembly.
+
+## Verification
+
+The Cordis inspect catalog check analyzes the declared Client export, both compiler aggregates retain their leaf references, and the Host and Client file-service tests exercise the same implementations. The existing dependency and project-reference checks enforce their compilation relationships.
diff --git a/.agents/notes/implemented/architecture/2026-09-07-workspace-files-dual-face-package.zh.md b/.agents/notes/implemented/architecture/2026-09-07-workspace-files-dual-face-package.zh.md
new file mode 100644
index 0000000000..ccfa604172
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-07-workspace-files-dual-face-package.zh.md
@@ -0,0 +1,36 @@
+# Agent Note: 工作区文件统一为 API 双面包
+
+Status: implemented
+
+[English](2026-09-07-workspace-files-dual-face-package.md) | 中文
+
+## Problem
+
+工作区文件服务与浏览器资源提供者共同演进，但其编译图包含指向 Remote 装配和 Sidebar UI 的反向依赖。拆包避开了这些环，却分离了线路协议与其 Client 模型的归属。只有 Host 实现、Client 编译入口仅含类型的包，也缺少 Client 目录分析用于区分运行时导出的 `dsh.client` 与 `./client` 声明。
+
+## Decision
+
+`packages/api/workspace-files` 拥有两面的实现。Host 与 Client 叶配置仍由各自的根聚合直接引用，solution 根配置引用两片叶子。Host 导出文件服务，`./client` 导出实际的资源提供者插件，`dsh.client` 声明浏览器插件。web-app 的一个条目加载两面。这只取代[工作区文件服务记录](2026-09-05-workspace-files-service.zh.md)中的拆包决定，其授权、分页与流语义保持不变。
+
+两条依赖方向使编译图保持无环：
+
+- `client/resources` 从定义 `RemoteResult` 与 `RemoteFailure` 的 `typert/protocol` 包导入它们，不依赖 `api/remotes`；后者负责装配消费资源模型的提供者。
+- 文本预览使用文件包导出的参数类型声明 `SidebarRightResourceParamsMap.file`。文件提供者声明其资源值，但不导入 Sidebar UI。调用方需要该导航声明时，导入查看器的类型入口。
+
+这消除了 `remotes → workspace-files → resources → remotes` 和 `remotes → workspace-files → sidebar-right → ui-conversation → remotes`。Cordis 运行时服务注入仍独立于 TypeScript 工程引用。
+
+## Alternatives considered
+
+**保留两个包。** 这隔离了编译环，却拆开同一文件能力的 Host 与 Client 归属。删除反向类型依赖后，可以采用与其它 API Controller 相同的双面组织。
+
+**删除根 Client 引用。** 传递引用仍会编译该叶子，但两个根聚合必须显式命名本包对应的编译面。
+
+**修改目录分析或增加空 Client 插件。** 两者都不能提供要求的浏览器实现。实际的 `./client` 导出和 `dsh.client` 使用分析器已有的双面支持路径。
+
+## Consequences
+
+Host 线路方法和浏览器资源行为不变。浏览器实现、测试与文档归同一个包所有；Client 类型依赖止于协议和资源模型层，不反向触及 UI 或 Remote 装配。
+
+## Verification
+
+Cordis inspect 目录检查分析声明的 Client 导出，两个编译聚合保留其叶引用，Host 与 Client 文件服务测试覆盖相同的实现。现有依赖与工程引用检查约束这些编译关系。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-03-root-marker-metadata-failures.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-03-root-marker-metadata-failures.i18n.yaml
new file mode 100644
index 0000000000..3c4cb67d7d
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-03-root-marker-metadata-failures.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-09-03-root-marker-metadata-failures.md
+2026-09-03-root-marker-metadata-failures.md: e31ef646d7190a1239684f7b66a118deb9ae1087
+2026-09-03-root-marker-metadata-failures.zh.md: 4b62f4e01ba56074a10dbcb3ae37c4478fe82379
diff --git a/.agents/notes/implemented/bug-fix/2026-09-03-root-marker-metadata-failures.md b/.agents/notes/implemented/bug-fix/2026-09-03-root-marker-metadata-failures.md
new file mode 100644
index 0000000000..e31ef646d7
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-03-root-marker-metadata-failures.md
@@ -0,0 +1,27 @@
+# Agent Note: Root marker metadata failures
+
+Status: implemented
+
+English | [中文](2026-09-03-root-marker-metadata-failures.zh.md)
+
+## Problem
+
+Project-root discovery probes each configured marker while walking upward from the session working directory. Treating every resolve or stat failure as a missing marker lets a permission, I/O, or provider failure continue into an ancestor project and load unrelated workspace instructions. The discovery result must distinguish confirmed absence from unavailable metadata.
+
+## Decision
+
+Root-marker discovery continues upward only when host stat reports `ENOENT` or `ENOTDIR`, or when a filesystem provider returns no stat information or reports `FS_NOT_FOUND` from resolution or stat. It rethrows every other marker error unchanged after checking cancellation. Instruction-file candidates keep their separate availability policy: resolution, stat, and read failures skip only that candidate because files can race with discovery without changing project identity.
+
+## Alternatives considered
+
+**Treat every marker failure as absence and continue upward.** Rejected because an inaccessible child directory could inherit instructions from an unrelated ancestor project while discovery reports success.
+
+**Stop at the first unavailable marker and use the session working directory as the root.** Rejected because it converts an unknown project root into a different project identity and can silently omit valid broader instructions.
+
+## Consequences
+
+Project-root discovery favors correct project identity over availability: one non-missing metadata failure anywhere in the ancestor walk rejects baseline loading with the original error. Instruction-file candidate failures retain their existing skip behavior. A failed baseline creates no workspace-context Session event, so the keyless recorded-session harness has no durable output for this path.
+
+## Verification
+
+Focused unit tests cover confirmed provider absence and unavailable host and provider marker metadata. The unavailable cases also prove that ancestor instructions do not enter derived model history.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-03-root-marker-metadata-failures.zh.md b/.agents/notes/implemented/bug-fix/2026-09-03-root-marker-metadata-failures.zh.md
new file mode 100644
index 0000000000..4b62f4e01b
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-03-root-marker-metadata-failures.zh.md
@@ -0,0 +1,27 @@
+# Agent Note: 根标记元数据故障
+
+Status: implemented
+
+[English](2026-09-03-root-marker-metadata-failures.md) | 中文
+
+## 问题
+
+项目根发现从会话工作目录向上遍历时，会探测每个已配置的标记。把所有 resolve 或 stat 故障都当作标记缺失，会使权限、I/O 或提供方故障越过该目录继续搜索祖先项目，并加载无关的工作区指令。发现结果必须区分确认缺失与元数据不可用。
+
+## 决策
+
+只有当宿主 stat 报告 `ENOENT` 或 `ENOTDIR`，或文件系统提供方未返回 stat 信息，或从解析或 stat 报告 `FS_NOT_FOUND` 时，根标记发现才会继续向上。检查取消后，其他标记错误会原样重新抛出。指令文件候选项保留独立的可用性策略：解析、stat 和读取故障只会跳过该候选项，因为文件可能与发现过程发生竞争，而不会改变项目身份。
+
+## 考虑过的替代方案
+
+**把所有标记故障都当作缺失并继续向上。** 不予采用，因为无法访问的子目录可能继承无关祖先项目中的指令，而发现过程仍报告成功。
+
+**在第一个不可用标记处停止，并把会话工作目录用作根目录。** 不予采用，因为这会把未知的项目根转换为另一个项目身份，并可能静默省略有效的更宽泛指令。
+
+## 后果
+
+项目根发现优先保证项目身份正确，而非可用性：祖先遍历中任何不是缺失的元数据故障都会使基线加载以原始错误拒绝。指令文件候选项故障保留现有的跳过行为。失败的基线不会创建工作区上下文 Session event，因此无密钥录制会话 harness 没有可用于该路径的持久输出。
+
+## 验证
+
+聚焦单元测试覆盖确认的提供方缺失，以及不可用的宿主与提供方标记元数据。不可用情况还证明祖先指令不会进入派生模型历史。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-03-user-owned-goal-pause-activation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-03-user-owned-goal-pause-activation.i18n.yaml
new file mode 100644
index 0000000000..f4d9692b37
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-03-user-owned-goal-pause-activation.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-09-03-user-owned-goal-pause-activation.md
+2026-09-03-user-owned-goal-pause-activation.md: d58566938ef87ca2f25fd94d726dc28209f61b2b
+2026-09-03-user-owned-goal-pause-activation.zh.md: 675d61009f0a7d0f98c8f6d7568466d6651f2a42
diff --git a/.agents/notes/implemented/bug-fix/2026-09-03-user-owned-goal-pause-activation.md b/.agents/notes/implemented/bug-fix/2026-09-03-user-owned-goal-pause-activation.md
new file mode 100644
index 0000000000..d58566938e
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-03-user-owned-goal-pause-activation.md
@@ -0,0 +1,35 @@
+# Agent Note: User-owned goal pause exposes live activation
+
+Status: implemented
+
+English | [中文](2026-09-03-user-owned-goal-pause-activation.zh.md)
+
+## Problem
+
+The host-pause fix in [Host-initiated goal pause aborts the live turn](../../archived/bug-fix/2026-09-01-host-goal-pause-aborts-turn.md) stopped the current model turn, but a later human turn could still use `update_goal resume` to lift a durable `paused` goal. The Web strip also read only the durable `goal` projection, so an active-but-disarmed goal and an armed goal rendered identically and offered the same pause action.
+
+## Decision
+
+`ctx.goals.get` is a read-only Remote method. `GoalService` emits `goal/activation-changed` whenever its process-local activation changes, with `{ sessionId, goal: { id, revision, activation } }` or no goal after a clear. The API Remote allowlist forwards that JSON payload to Web clients.
+
+The GoalBar consumes a registrant-private activation hook source created by its slot inject. The source starts while the framework hook observes it, reads `ctx.remote.goals.get`, subscribes to `goal/activation-changed`, and refreshes on running-state or connection resets. Activation edges advance an epoch that invalidates in-flight reads, so a stale HTTP response cannot overwrite a newer edge; running refreshes retain the last activation until the read resolves. Active goals render `Ongoing Goal` only when armed; active-but-disarmed goals render `Inactive Goal`, expose resume instead of pause, and durable paused goals keep exposing resume. Pause authority remains in the goal domain and human `/goal resume` command, which can still resume every resumable phase.
+
+The `update_goal resume` action rejects a durable paused goal with `GOAL_TOOL_RESUME_PAUSED` before calling the goal service. It still resumes an active-but-disarmed goal after session restore or fork and a blocked goal after human continuation. The model prompt and tool description state that the user owns durable paused resume.
+
+## Alternatives considered
+
+**Store activation in the durable `GoalSnapshot`.** Rejected: activation is process-local by the goal domain contract and must not survive restore or fork.
+
+**Add activation to the persisted session projection.** Rejected: projection state is checkpointed; a cached `armed` value would incorrectly outlive the process that armed it.
+
+**Forward the full scoped `goal/changed` event to clients.** Rejected: its `Agent` payload is not JSON wire data. The dedicated activation event carries only the session id, goal ref, and activation clients need.
+
+**Let the model resume durable paused goals from natural-language turns.** Rejected: a manual pause is a user control, and prompt-only restraint leaves the same turn-level undo available to the model.
+
+## Consequences
+
+The Web can distinguish running, disarmed, and paused goals without persisting activation. A durable paused goal is resumable only through the Web control, `/goal resume`, or another direct goal-service caller; model `update_goal resume` is limited to disarmed-active and blocked goals. The API surface gains one read and one forwarded live event; durable goal change payloads and projection state versions are unchanged. Components own no Remote subscriptions; the activation source follows the established inject-hooks live-data channel.
+
+## Testing
+
+Goal unit tests pin the activation event id and revision across create, session start, and resume. Tool tests pin rejection of a durable paused goal in a later human turn while restored disarmed-active goals still resume. API Remote tests pin JSON forwarding. Activation-source tests pin stale-read rejection and running-refresh retention. Web unit tests pin armed pause versus disarmed resume rendering. The assembled goal-bar browser scenario uses the fixture timing hook to pin both armed and active-disarmed goldens.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-03-user-owned-goal-pause-activation.zh.md b/.agents/notes/implemented/bug-fix/2026-09-03-user-owned-goal-pause-activation.zh.md
new file mode 100644
index 0000000000..675d61009f
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-03-user-owned-goal-pause-activation.zh.md
@@ -0,0 +1,35 @@
+# Agent Note: 用户独占的 goal 暂停并暴露实时激活态
+
+Status: implemented
+
+[English](2026-09-03-user-owned-goal-pause-activation.md) | 中文
+
+## 问题
+
+[宿主发起的 goal 暂停中止当前轮次](../../archived/bug-fix/2026-09-01-host-goal-pause-aborts-turn.md) 修复了当前模型轮次不停止的问题，但之后的人类轮次仍可通过 `update_goal resume` 解除持久的 `paused` goal。Web 条带也只读取持久的 `goal` 投影，因此 active-but-disarmed 的 goal 与 armed 的 goal 渲染相同，并提供相同的暂停动作。
+
+## 决策
+
+`ctx.goals.get` 现在是一个只读 Remote 方法。`GoalService` 在进程本地 activation 变化时发出 `goal/activation-changed`，载荷为 `{ sessionId, goal: { id, revision, activation } }`，clear 后则不携带 goal。API Remote 允许列表把这份 JSON 载荷转发给 Web 客户端。
+
+GoalBar 消费由 slot inject 创建的 registrant-private activation hook source。该 source 仅在框架 hook 观察期间启动，读取 `ctx.remote.goals.get`、订阅 `goal/activation-changed`，并在 running 状态或连接 reset 时刷新。activation 边界推进 epoch，使在途读取失效，因此较旧的 HTTP 响应不能覆盖更新的边界；running 刷新会保留最后一次 activation，直到读取完成。Active goal 仅在 armed 时渲染 `Ongoing Goal`；active-but-disarmed goal 渲染 `Inactive Goal`，暴露 resume 而不是 pause；持久 paused goal 继续暴露 resume。暂停权威仍属于 goal 领域和人类 `/goal resume` 命令，它们仍可恢复每个可恢复 phase。
+
+`update_goal resume` 会在调用 goal 服务前用 `GOAL_TOOL_RESUME_PAUSED` 拒绝持久 paused goal。它仍会在会话恢复或 fork 后恢复 active-but-disarmed goal，并在人类要求继续时恢复 blocked goal。模型提示词和工具描述说明持久 paused 的恢复由用户独占。
+
+## 考虑过的替代方案
+
+**把 activation 存入持久 `GoalSnapshot`。** 否决：按 goal 领域约定，activation 是进程本地的，绝不能跨恢复或 fork 存活。
+
+**把 activation 加入持久 session projection。** 否决：投影状态会写入检查点；缓存的 `armed` 会在武装它的进程消失后继续错误存在。
+
+**把完整的 scoped `goal/changed` 事件转发给客户端。** 否决：其 `Agent` 载荷不是 JSON wire 数据。专用 activation 事件只携带客户端需要的 session id、goal ref 与 activation。
+
+**允许模型从自然语言轮次恢复持久 paused goal。** 否决：人工暂停是用户控制，仅靠提示词约束仍会把同轮撤销能力留给模型。
+
+## 后果
+
+Web 无需持久化 activation 就能区分运行中、disarmed 与 paused goal。持久 paused goal 只能通过 Web 控件、`/goal resume` 或其他直接调用 goal 服务的调用方恢复；模型 `update_goal resume` 仅限 disarmed-active 与 blocked goal。API 表面新增一个读取和一个转发 live 事件；持久 goal change 载荷与投影 stateVersion 不变。组件不持有 Remote 订阅；activation source 遵循既有的 inject-hooks live-data 通道。
+
+## 测试
+
+Goal 单元测试固定 create、session start 与 resume 过程中 activation 事件的 id 与 revision。工具测试固定后续人类轮次中持久 paused goal 的拒绝，同时保留已恢复 disarmed-active goal 的恢复。API Remote 测试固定 JSON 转发。Activation-source 测试固定 stale read 拒绝与 running 刷新保留旧值。Web 单元测试固定 armed 显示 pause、disarmed 显示 resume；组装的 goal-bar 浏览器场景通过 fixture timing hook 同时固定 armed 与 active-disarmed golden。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-04-busy-send-button-follows-enter-setting.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-04-busy-send-button-follows-enter-setting.i18n.yaml
new file mode 100644
index 0000000000..0dfc11edca
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-04-busy-send-button-follows-enter-setting.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-09-04-busy-send-button-follows-enter-setting.md
+2026-09-04-busy-send-button-follows-enter-setting.md: 2db0848e3ce3b7a1b6b07ff6d6d23c06b23be5ef
+2026-09-04-busy-send-button-follows-enter-setting.zh.md: 7062f60320c4bc56f15f57388e79df9ce0e45c2f
diff --git a/.agents/notes/implemented/bug-fix/2026-09-04-busy-send-button-follows-enter-setting.md b/.agents/notes/implemented/bug-fix/2026-09-04-busy-send-button-follows-enter-setting.md
new file mode 100644
index 0000000000..2db0848e3c
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-04-busy-send-button-follows-enter-setting.md
@@ -0,0 +1,35 @@
+# Agent Note: The busy Send button follows the Enter setting
+
+Status: implemented
+
+English | [中文](2026-09-04-busy-send-button-follows-enter-setting.zh.md)
+
+## Problem
+
+The Web composer offers one user-facing choice for submitting while the agent is running: the `ui-conversation.busyEnter` setting selects Queue or Steer. [Running drafts take the primary Send action](../../archived/bug-fix/2026-08-20-running-draft-primary-send.md) (archived) gave a running draft a pointer Send button, deliberately kept it off the preference to avoid an invisible mode on a button labeled only Send, and routed every click through the public `InputActions.submit()` face, which `SessionInputShell.actions` fixes to `'queue'`. A user who chose Steer in Settings got Steer from Enter and Queue from the button beside the same draft, with the button labeled only "Send message". Nothing in the composer explained the divergence, and the Settings row's title and description named only the Enter key, so the setting looked broken rather than deliberately partial.
+
+## Decision
+
+The running Send button delivers through the same mode as plain Enter. `InputBar` computes `resolveSubmitMode(busyEnter, running, 'enter', steeringAvailable)` once per render, where `steeringAvailable` is the same ordinary-Session-or-continuable-child predicate the keyboard path uses, applies it to the primary click through `ComposerKeyboard.submit(mode)`, and applies it to the primary label exactly when the click would deliver a plain message: the composer is running and steer-capable, the button is enabled (no file upload still pending), and the draft is non-empty, unclaimed, and not a `/` line headed for command adjudication. That state shows `input.send.queue` ("Queue message" / "排队发送") or `input.send.steer` ("Steer message" / "插话发送") as both the tooltip and the accessible name; every other state in which the seat is a Send button — idle sessions, one-shot children, locked composers, a continuable child's empty draft, drafts with a pending upload, and command drafts whose click executes the command rather than delivering a message — keeps `input.send` ("Send message"); an ordinary running session with an empty or owner-blocked draft shows Stop in that seat instead. Cmd/Ctrl+Enter still resolves to the opposite mode, and the empty-draft accelerated gesture still steers the whole queue. The [continuable subagent interrupt note](../feature/2026-08-06-continuable-subagent-interrupt.md) describes the child's Send with this delivery.
+
+The composer bar's inject face carries the live preference instead of a resolver closure. `ComposerBarInjected.hooks.busyEnter` publishes `ComposerSubmissionPolicy.busyEnter`, so the bar receives a `useBusyEnter` selector hook and re-renders the label when the Settings row or a Host settings update changes the value. `resolveSubmitMode` is a pure exported function in `submission-policy.ts` taking the preference explicitly; the policy class keeps only the store and its Host adoption and write-through.
+
+The Settings row is retitled to cover both inputs: "Send behavior while busy" / "繁忙时的发送行为", described as what Enter and the Send button do while the agent is running, with the Cmd/Ctrl+Enter opposite-mode note retained. The `busyEnter` field name, its `queue` default, and the Host schema are unchanged, so existing `settings.yaml` documents keep their meaning.
+
+## Verification
+
+`input-bar.client.spec.tsx` asserts that a running draft's button is labeled by mode and submits with that mode under both preferences, that flipping the preference store re-labels the mounted button before the next click, that idle Send keeps the plain label and Queue delivery regardless of the preference, that a continuable subagent's Send follows the same mode and label as an ordinary Session while its empty-draft disabled button and a one-shot child keep plain Send, and that a `/` line, a claimed command, and a draft with a still-uploading file keep plain Send while running. `submission-policy.client.spec.ts` pins `resolveSubmitMode` for every preference, running, gesture, and steering-availability combination. `enter-behavior-row.client.spec.tsx` and the `settings-chrome` ARIA goldens carry the new Settings copy. The keyless `live-interactions` Web scenario waits for "Queue message" on the parked running draft and asserts that no "Send message" button exists at that moment, and its `running-draft.expected.md` golden records the new name.
+
+## Alternatives considered
+
+**Keep the button on Queue and only reword the Settings row.** This preserves the earlier decision but leaves the composer with two submission paths for one draft under one setting. A user who prefers Steer still cannot get it by pointer, and the reworded row would have to document a keyboard-only scope that no other composer control shares.
+
+**Add a second running button, one per mode.** Both delivery modes become reachable by pointer without a hidden state, but the ordinary session has one primary seat that already alternates between Stop and Send; a permanent second control spends space and introduces a hierarchy the draft itself does not need. The single setting already expresses the user's default, and Cmd/Ctrl+Enter remains the per-message override.
+
+**Thread the mode through `InputActions.submit(mode)`.** Widening the public provide-channel face would let any session-scope slot pick a delivery mode, which no other consumer needs, and would move a composer presentation decision into the machine's public contract. The package-private `ComposerKeyboard.submit(mode)` already exists for exactly this purpose, so the button uses it.
+
+**Keep `resolveSubmitMode` as a closure on the inject face and add a separate `busyEnter` hook only for the label.** Two sources for one fact invite drift between what the label says and what the click does. Publishing the preference once and resolving it in the bar keeps label and delivery derived from the same value in the same render.
+
+## Consequences
+
+The setting governs every busy-state submission a user can trigger with a message, and the button announces which delivery it performs, so choosing Steer no longer produces a Queue row from the button beside the draft. Users who relied on the button as an always-Queue escape while their setting selected Steer now use Cmd/Ctrl+Enter for that. The running Send label changes for every user, including under the default Queue preference, which the Web e2e scenarios that click Send during a running turn account for; idle-session flows and one-shot subagent composers see no change. The archived running-draft note's clause that the pointer action ignores the preference is reversed here; its primary-seat, owner-block, and subagent-control decisions stand as shipped and are described by the `ui-conversation` README.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-04-busy-send-button-follows-enter-setting.zh.md b/.agents/notes/implemented/bug-fix/2026-09-04-busy-send-button-follows-enter-setting.zh.md
new file mode 100644
index 0000000000..7062f60320
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-04-busy-send-button-follows-enter-setting.zh.md
@@ -0,0 +1,35 @@
+# Agent Note: 繁忙态 Send 按钮跟随 Enter 设置
+
+Status: implemented
+
+[English](2026-09-04-busy-send-button-follows-enter-setting.md) | 中文
+
+## 问题
+
+Web composer 为 agent（智能体）运行期间的提交只提供一个面向用户的选择：`ui-conversation.busyEnter` 设置在 Queue 与 Steer 之间选择。[运行中草稿取得主 Send 操作](../../archived/bug-fix/2026-08-20-running-draft-primary-send.md)（已归档）为运行中的草稿提供了指针 Send 按钮，有意让它不跟随该偏好，以避免一个只标注为 Send 的按钮携带不可见模式，并把每次点击都路由到公共的 `InputActions.submit()` 接口，而 `SessionInputShell.actions` 把该接口固定为 `'queue'`。用户在设置中选择 Steer 后，Enter 得到 Steer，同一草稿旁的按钮却得到 Queue，且按钮只标注为"发送消息"。composer 中没有任何内容解释这一分歧，设置行的标题和描述也只提到 Enter 键，因此该设置看起来像是失效，而不是有意只覆盖一部分。
+
+## 决策
+
+运行中的 Send 按钮按与 plain Enter 相同的模式投递。`InputBar` 每次渲染计算一次 `resolveSubmitMode(busyEnter, running, 'enter', steeringAvailable)`，其中 `steeringAvailable` 与键盘路径使用同一个"普通 Session 或可继续 child"判定；用它通过 `ComposerKeyboard.submit(mode)` 执行主按钮点击，并且仅在点击会投递一条普通消息时用它决定主按钮标签：composer 运行中且可 steering、按钮可用（没有仍在上传的文件）、草稿非空、未被认领且不是将进入命令 adjudication 的 `/` 行。该状态把 `input.send.queue`（"Queue message" / "排队发送"）或 `input.send.steer`（"Steer message" / "插话发送"）同时用作 tooltip 与可访问名称；该位置仍为 Send 按钮的其余所有状态——空闲会话、one-shot child、锁定的 composer、可继续 child 的空草稿、带待上传附件的草稿，以及点击会执行命令而非投递消息的命令草稿——保留 `input.send`（"Send message"）；普通运行中会话在空草稿或 owner block 时该位置显示的是 Stop。Cmd/Ctrl+Enter 仍解析为相反模式，空草稿下的加速手势仍对整个队列执行 steering（中途引导）。[可继续 subagent 中断 Agent Note](../feature/2026-08-06-continuable-subagent-interrupt.zh.md)以此投递方式描述 child 的 Send。
+
+composer bar 的 inject 接口携带实时偏好，而不是解析闭包。`ComposerBarInjected.hooks.busyEnter` 发布 `ComposerSubmissionPolicy.busyEnter`，因此 bar 获得 `useBusyEnter` 选择器 hook，并在设置行或 Host 设置更新改变该值时重新渲染标签。`resolveSubmitMode` 是 `submission-policy.ts` 中导出的纯函数，显式接收偏好值；policy 类只保留 store 及其 Host 采纳与写回。
+
+设置行重新命名以覆盖两种输入："Send behavior while busy" / "繁忙时的发送行为"，描述为 agent 运行时 Enter 与 Send 按钮的行为，并保留 Cmd/Ctrl+Enter 使用相反模式的说明。`busyEnter` 字段名、其 `queue` 默认值和 Host schema 均未改变，因此现有 `settings.yaml` 文档保持原有含义。
+
+## 验证
+
+`input-bar.client.spec.tsx` 断言运行中草稿的按钮在两种偏好下都按模式标注并以该模式提交，切换偏好 store 会在下一次点击前重新标注已挂载的按钮，空闲 Send 无论偏好如何都保留普通标签与 Queue 投递，可继续 subagent 的 Send 与普通 Session 遵循同一模式与标签，而其空草稿下的禁用按钮与 one-shot child 保留普通 Send，运行中的 `/` 行、已认领命令与带仍在上传文件的草稿也保留普通 Send。`submission-policy.client.spec.ts` 钉住 `resolveSubmitMode` 在偏好、运行状态、手势与 steering 可用性所有组合下的结果。`enter-behavior-row.client.spec.tsx` 与 `settings-chrome` ARIA golden 携带新的设置文案。无密钥的 `live-interactions` Web 场景在停住的运行中草稿上等待"Queue message"，并断言此刻不存在"Send message"按钮，其 `running-draft.expected.md` golden 记录了新名称。
+
+## 备选方案
+
+**保持按钮使用 Queue，只改写设置行文案。** 这保留了先前决策，但让同一设置下的同一草稿拥有两条提交路径。偏好 Steer 的用户仍无法通过指针得到它，而改写后的设置行必须记录一种其他 composer 控件都不具备的仅键盘生效范围。
+
+**增加第二个运行中按钮，每种模式一个。** 两种投递模式都可以通过指针到达且没有隐藏状态，但普通会话只有一个主操作位置，且已在 Stop 与 Send 之间交替；永久增加第二个控件会占用空间，并引入草稿本身不需要的层级。单一设置已经表达了用户默认值，Cmd/Ctrl+Enter 仍是逐条消息的覆盖手段。
+
+**通过 `InputActions.submit(mode)` 传递模式。** 拓宽公共 provide 通道接口会让任何 session 作用域的 slot 都能选择投递模式，而没有其他消费者需要它，并且会把 composer 的呈现决策推入机器的公共契约。包内私有的 `ComposerKeyboard.submit(mode)` 正是为此存在，因此按钮直接使用它。
+
+**在 inject 接口上保留 `resolveSubmitMode` 闭包，仅为标签另加一个 `busyEnter` hook。** 同一事实有两个来源，会让标签所说与点击所做之间产生偏差。只发布一次偏好并在 bar 中解析，可以让标签与投递在同一次渲染中源自同一个值。
+
+## 影响
+
+该设置约束用户能以消息触发的每一种繁忙态提交，且按钮会声明它执行哪种投递，因此选择 Steer 后不再会从草稿旁的按钮产生 Queue 行。此前在设置为 Steer 时依赖按钮作为始终 Queue 逃生口的用户，现在改用 Cmd/Ctrl+Enter。运行中的 Send 标签对每位用户都会变化，包括默认的 Queue 偏好下，运行中点击 Send 的 Web e2e 场景已相应处理；空闲会话流程和 one-shot subagent composer 没有变化。已归档的运行中草稿 Agent Note 中"指针操作忽略偏好"的条款在此被反转；其主操作位置、owner block 与 subagent 控件决策按已交付状态继续有效，并由 `ui-conversation` README 描述。
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
index eb54244e5a..b55c40d769 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
-2026-07-16-harness-level-loop.md: 90f9b9d9d78bab620a0150d6e480485e37cb762f
-2026-07-16-harness-level-loop.zh.md: c1709f8743e6fecbf576bc540cbba934e8bb23bd
+2026-07-16-harness-level-loop.md: 43b8f867ae9af92f22fdae0cecef37803b49be30
+2026-07-16-harness-level-loop.zh.md: 40af80d95127974bcbed4f7114dec048e0dbdc57
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
index 90f9b9d9d7..43b8f867ae 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
@@ -50,7 +50,7 @@ One session has at most one current goal. Every mutation commits through a durab
 
 Durable phases are only `active`, `paused`, `blocked`, and `complete`. A blocked goal carries a required `GoalBlockReason` with a stable lower-kebab-case `code` and a non-empty human-readable `message`; usage limits, round exhaustion, model failures, and policy rejection are reason codes rather than extra lifecycle phases. Separate activation is `armed` or `disarmed` and is never persisted. Creation and explicit resume arm a goal; stop transitions, session start, fork replay, driver replacement, and driver teardown leave it disarmed.
 
-This separation makes session restoration observable and unsurprising. Reopening a session never starts goal work by itself. A later human prompt such as “continue”, “resume the goal”, or an equivalent request in any language gives the runtime-root model a new turn in which it may read the goal and call `update_goal(..., action: 'resume')`. `/goal resume` is the direct human-command path. The runtime authenticates that the request came from a live direct-human turn; prompt policy lets the model interpret whether the wording semantically authorizes creation or resumption.
+This separation makes session restoration observable and unsurprising. Reopening a session never starts goal work by itself. A later human prompt such as “continue”, “resume the goal”, or an equivalent request in any language gives the runtime-root model a new turn in which it may read an active-but-disarmed goal and call `update_goal(..., action: 'resume')`. A durable paused goal is resumed through `/goal resume`, the Web control, or another direct goal-service caller; the model tool rejects it under the [user-owned pause decision](../bug-fix/2026-09-03-user-owned-goal-pause-activation.md). The runtime authenticates that the request came from a live direct-human turn; prompt policy lets the model interpret whether the wording semantically authorizes creation or resumption.
 
 Forked sessions inherit the durable goal prefix because that is the natural replay result. The fork starts disarmed, so inheritance does not imply execution authority and no synthetic goal cancellation is inserted into history.
 
@@ -62,7 +62,7 @@ The goal-round driver owns at most one pending reservation per exact live agent.
 
 Only an admitted positive-round goal-sourced `user/message` charges a round. A stale reservation closes a blocked no-step turn without consuming the cap. A concurrent goal revision wins over settlement from an older round.
 
-Normal turn completion schedules another round only while the goal remains active, armed, and below its cap. Cancellation pauses. Rate limiting or quota exhaustion blocks with code `usage-limited`; cap exhaustion blocks with `round-limit`; queue failure uses `queue-failed`; turn errors, max-token stops, policy rejection, and unknown terminal results use their corresponding blocker codes. An independently composed request-recovery plugin may retry transient provider failures within that same turn; the goal driver never invents another round after an abnormal terminal outcome. A human can later authorize resume through ordinary language or `/goal resume`.
+Normal turn completion schedules another round only while the goal remains active, armed, and below its cap. Cancellation pauses. Rate limiting or quota exhaustion blocks with code `usage-limited`; cap exhaustion blocks with `round-limit`; queue failure uses `queue-failed`; turn errors, max-token stops, policy rejection, and unknown terminal results use their corresponding blocker codes. An independently composed request-recovery plugin may retry transient provider failures within that same turn; the goal driver never invents another round after an abnormal terminal outcome. A human can later resume through `/goal resume` or the Web control; a blocked goal also remains eligible for model `update_goal resume`, while a durable paused goal does not.
 
 ### Human and model interactions
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
index c1709f8743..40af80d951 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
@@ -50,7 +50,7 @@ Status: implemented
 
 持久阶段只有 `active`、`paused`、`blocked` 与 `complete`。阻塞目标必须携带 `GoalBlockReason`，其中包含稳定的小写 kebab-case `code` 与非空的人类可读 `message`；用量限制、Round 耗尽、模型失败与策略拒绝都是原因代码，而不是额外生命周期阶段。独立激活态是 `armed` 或 `disarmed`，且永不持久化。创建与显式恢复会激活目标；停止转换、会话启动、fork 回放、驱动器替换和驱动器拆卸都会让目标保持未激活。
 
-这种分离让会话恢复可观察且符合直觉。重新打开会话绝不会自行开始目标工作。随后的人类提示词，例如「继续」、「恢复目标」或任何语言中的等价请求，会给运行时根 agent 的模型一个新轮次；模型可在其中读取目标并调用 `update_goal(..., action: 'resume')`。`/goal resume` 是直接人类命令路径。运行时认证请求来自实时直接人类轮次；提示策略让模型解释措辞在语义上是否授权创建或恢复。
+这种分离让会话恢复可观察且符合直觉。重新打开会话绝不会自行开始目标工作。随后的人类提示词，例如「继续」、「恢复目标」或任何语言中的等价请求，会给运行时根 agent 的模型一个新轮次；模型可在其中读取 active-but-disarmed 目标并调用 `update_goal(..., action: 'resume')`。持久的 paused 目标通过 `/goal resume`、Web 控件或其他直接调用 goal 服务的调用方恢复；模型工具依据[用户独占暂停决策](../bug-fix/2026-09-03-user-owned-goal-pause-activation.zh.md)拒绝它。运行时认证请求来自实时直接人类轮次；提示策略让模型解释措辞在语义上是否授权创建或恢复。
 
 fork 会话会继承持久目标前缀，因为这是自然的重放结果。fork 从未激活状态开始，因此继承不等于执行权限，历史中也不会插入合成目标取消。
 
@@ -62,7 +62,7 @@ Goal Round 驱动器为每个特定的实时 agent 至多拥有一个待定预
 
 只有已接纳、Round 为正数且带目标来源的 `user/message` 会计入一个 Round。陈旧预留会结束一个阻塞的零步骤轮次，不会消耗上限。并发目标修订会胜过旧 Round 的结算。
 
-普通轮次完成后，只有目标仍活跃、已激活且低于上限时才会安排另一个 Round。取消会暂停。速率限制或配额耗尽以代码 `usage-limited` 阻塞；上限耗尽使用 `round-limit`；队列失败使用 `queue-failed`；轮次错误、max-token 停止、策略拒绝与未知终止结果使用各自对应的阻塞代码。独立组合的请求恢复插件可以在同一个轮次内重试暂时性提供方失败；目标驱动器绝不会在异常终止结果后凭空发起另一个 Round。人类随后可以通过普通语言或 `/goal resume` 授权恢复。
+普通轮次完成后，只有目标仍活跃、已激活且低于上限时才会安排另一个 Round。取消会暂停。速率限制或配额耗尽以代码 `usage-limited` 阻塞；上限耗尽使用 `round-limit`；队列失败使用 `queue-failed`；轮次错误、max-token 停止、策略拒绝与未知终止结果使用各自对应的阻塞代码。独立组合的请求恢复插件可以在同一个轮次内重试暂时性提供方失败；目标驱动器绝不会在异常终止结果后凭空发起另一个 Round。人类随后可以通过 `/goal resume` 或 Web 控件恢复；blocked 目标也仍可由模型 `update_goal resume` 恢复，而持久 paused 目标不能。
 
 ### 人类与模型交互
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
index b8dbc7c937..3a30f6624d 100644
--- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
-2026-07-19-model-facing-goal-tools.md: 67668652adfa29d0a702f363cd9b12367411382f
-2026-07-19-model-facing-goal-tools.zh.md: 1db8d53393146a333738ad0248aba5ccf968a566
+2026-07-19-model-facing-goal-tools.md: 2c05c8aa0ee2caecb0264fa87984085b3df5d785
+2026-07-19-model-facing-goal-tools.zh.md: f16055e52e4a3d6a4db423699a36929f6f8c4cd2
diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
index 67668652ad..2c05c8aa0e 100644
--- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
+++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
@@ -16,9 +16,9 @@ The tool API also needs to preserve the separation between durable state and liv
 
 ### Tools and model contract
 
-`get_goal()` returns the current goal or `null`. A non-null result contains the compare-and-set id and revision, objective, durable phase, admitted and maximum goal rounds, any blocker reason, plus the process-local activation observation. `create_goal(objective, max_goal_rounds?)` creates one long-running same-session objective. `update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` supports `edit`, `pause`, `resume`, `complete`, and `blocked`; replacement fields are valid only for `edit`, while a non-empty `blocked_reason` is required only for `blocked` and persists under the stable `model-reported` code. The executor treats exact empty-string optional fields and a zero `max_goal_rounds` as strict-schema fillers: they count as omitted, an edit still requires at least one meaningful replacement, and all non-filler values retain the action restrictions.
+`get_goal()` returns the current goal or `null`. A non-null result contains the compare-and-set id and revision, objective, durable phase, admitted and maximum goal rounds, any blocker reason, plus the process-local activation observation. `create_goal(objective, max_goal_rounds?)` creates one long-running same-session objective. `update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` supports `edit`, `pause`, `resume`, `complete`, and `blocked`; replacement fields are valid only for `edit`, while a non-empty `blocked_reason` is required only for `blocked` and persists under the stable `model-reported` code. A durable paused goal rejects `resume` with `GOAL_TOOL_RESUME_PAUSED`; the user-facing command or Web control owns that transition. The executor treats exact empty-string optional fields and a zero `max_goal_rounds` as strict-schema fillers: they count as omitted, an edit still requires at least one meaningful replacement, and all non-filler values retain the action restrictions.
 
-The prompt tells the model that it may infer goal intent from a direct human request in any wording or language, but should not convert routine single-turn work into a goal. It must read the current goal before updating and copy the exact id and revision. On a restored or forked active-but-disarmed goal, a semantic human request to continue is grounds for `resume`. Completion is reserved for an achieved objective, and difficulty or uncertainty alone is not a blocker; a block report must name the concrete condition.
+The prompt tells the model that it may infer goal intent from a direct human request in any wording or language, but should not convert routine single-turn work into a goal. It must read the current goal before updating and copy the exact id and revision. On a restored or forked active-but-disarmed goal, a semantic human request to continue is grounds for `resume`. The prompt does not announce the durable paused boundary; execution rejects that attempt with `GOAL_TOOL_RESUME_PAUSED`, and the user-facing resume path owns the transition. Completion is reserved for an achieved objective, and difficulty or uncertainty alone is not a blocker; a block report must name the concrete condition.
 
 All three tools use exclusive execution so a model-ordered batch observes prior mutations and their new revisions. Results are compact JSON. UI presentation is a pure function of arguments and uses generic read or mutation cards; mutation cards select meaningful action values before the goal id, so accepted fillers cannot blank their input. Activation is reported only as live observation and is never written into replay state.
 
@@ -38,7 +38,7 @@ Complete and blocked accept either direct-human authority or the exact current g
 
 ## Testing
 
-Unit coverage pins registration and disposal, exclusive scheduling, generated prompt policy, filler-safe generic presentation, direct-human creation in a non-English turn, exact/stale/non-running agent and driver checks, live-child rejection, resumed-fork root authority, steering, mismatched initiators, read/create/partial-edit/pause/resume behavior including strict-schema fillers, conditional blocker explanations, rearming after a session-start edge, authority-before-conditional-argument failures, exact goal-round completion, autonomous-only terminal stopping, the configured blocking threshold, and immediate human blocking. A keyless replay snapshot mounts the goal domain and tools into the real headless one-shot application, drives a strict-filler `update_goal` probe plus `create_goal` and `get_goal` through the shipped loop and persistence stack, pins its stream-json transcript, and inspects the externally persisted goal change. The echo-agent fixture is intentionally not used as an application-UX surrogate.
+Unit coverage pins registration and disposal, exclusive scheduling, generated prompt policy, filler-safe generic presentation, direct-human creation in a non-English turn, exact/stale/non-running agent and driver checks, live-child rejection, resumed-fork root authority, steering, mismatched initiators, read/create/partial-edit/pause behavior including strict-schema fillers, durable-paused resume rejection, conditional blocker explanations, rearming after a session-start edge, authority-before-conditional-argument failures, exact goal-round completion, autonomous-only terminal stopping, the configured blocking threshold, and immediate human blocking. A keyless replay snapshot mounts the goal domain and tools into the real headless one-shot application, drives a strict-filler `update_goal` probe plus `create_goal` and `get_goal` through the shipped loop and persistence stack, pins its stream-json transcript, and inspects the externally persisted goal change. The echo-agent fixture is intentionally not used as an application-UX surrogate.
 
 ## Alternatives considered
 
@@ -54,7 +54,7 @@ Unit coverage pins registration and disposal, exclusive scheduling, generated pr
 
 - Models receive a stable, compact lifecycle API without direct access to the goal service.
 - State-changing calls require a live runtime-root agent and a direct human message in the current turn, as well as durable compare-and-set references.
-- Human requests can create and rearm goals through ordinary natural language, while restored sessions remain inert until such input arrives.
+- Human requests can create goals and rearm restored or blocked goals through ordinary natural language; a durable paused goal requires the user-facing resume path.
 - Goal rounds can finish or report a repeated blocker but cannot broaden their own mandate.
 - Deployment policy selects the blocking lower bound; the same resolved value controls enforcement and prompt guidance.
 - Strict-schema provider fillers interoperate without allowing meaningful cross-action updates.
@@ -62,6 +62,7 @@ Unit coverage pins registration and disposal, exclusive scheduling, generated pr
 ## Known limitations and deferred work
 
 - Semantic classification of a substantial goal, a request to continue, objective completion, and the same blocking condition remains model judgment. An independent evaluator or completion certificate is deferred.
+- The model cannot resume a durable paused goal; that user-owned path is enforced by the separate [user-owned goal pause decision](../bug-fix/2026-09-03-user-owned-goal-pause-activation.md).
 - These tools mutate goal state but do not schedule goal rounds, classify abnormal driver stops, or cancel an active turn; the same-session driver owns those behaviors.
 - Goal-round authority is dormant unless a separately mounted continuation driver admits goal-sourced user turns; this tool package never manufactures that authority itself.
 - Human slash-command discovery and rendering are owned by the separate [`dsh-command-goal`](../../../../packages/goal/command-goal/README.md) plugin.
diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
index 1db8d53393..f16055e52e 100644
--- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
@@ -16,9 +16,9 @@ Status: implemented
 
 ### 工具与模型约定
 
-`get_goal()` 返回当前目标或 `null`。非空结果包含用于比较并交换的 id 与修订号、目标描述、持久阶段、已接纳和最大 Goal Round 数、可能存在的阻塞原因，以及进程本地激活态观察。`create_goal(objective, max_goal_rounds?)` 创建一个长时间运行的同会话目标。`update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` 支持 `edit`、`pause`、`resume`、`complete` 和 `blocked`；替换字段仅对 `edit` 有效，非空的 `blocked_reason` 仅在 `blocked` 时必填，并以稳定代码 `model-reported` 持久化。执行器把值恰好为空字符串的可选字段和值为 0 的 `max_goal_rounds` 视为严格 schema 占位值：这些值等同于省略；编辑时仍必须提供至少一个有实际意义的替换字段；所有非占位值仍受对应操作的限制。
+`get_goal()` 返回当前目标或 `null`。非空结果包含用于比较并交换的 id 与修订号、目标描述、持久阶段、已接纳和最大 Goal Round 数、可能存在的阻塞原因，以及进程本地激活态观察。`create_goal(objective, max_goal_rounds?)` 创建一个长时间运行的同会话目标。`update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` 支持 `edit`、`pause`、`resume`、`complete` 和 `blocked`；替换字段仅对 `edit` 有效，非空的 `blocked_reason` 仅在 `blocked` 时必填，并以稳定代码 `model-reported` 持久化。持久 paused goal 会以 `GOAL_TOOL_RESUME_PAUSED` 拒绝 `resume`；面向用户的命令或 Web 控件拥有该转换。执行器把值恰好为空字符串的可选字段和值为 0 的 `max_goal_rounds` 视为严格 schema 占位值：这些值等同于省略；编辑时仍必须提供至少一个有实际意义的替换字段；所有非占位值仍受对应操作的限制。
 
-提示词告诉模型：它可以从任何措辞或语言的直接人类请求中推断目标意图，但不应把常规单轮工作转换为目标。更新前必须读取当前目标，并复制准确的 id 和修订号。对于恢复或 fork 后处于活跃但未激活状态的目标，人类在语义上要求继续即可成为执行 `resume` 的依据。只有目标已经实现时才能标记完成，困难或不确定性本身不构成阻塞；阻塞报告必须说明具体条件。
+提示词告诉模型：它可以从任何措辞或语言的直接人类请求中推断目标意图，但不应把常规单轮工作转换为目标。更新前必须读取当前目标，并复制准确的 id 和修订号。对于恢复或 fork 后处于活跃但未激活状态的目标，人类在语义上要求继续即可成为执行 `resume` 的依据。提示词不会静态声明持久 paused 的边界；执行时以 `GOAL_TOOL_RESUME_PAUSED` 拒绝该尝试，面向用户的恢复路径拥有该转换。只有目标已经实现时才能标记完成，困难或不确定性本身不构成阻塞；阻塞报告必须说明具体条件。
 
 三个工具都采用独占执行，使模型排序的批次可以观察此前变更及其新修订号。结果为紧凑 JSON。UI 展示是参数的纯函数，使用通用读取或变更卡片；变更卡片选择输入时，先取有实际意义的操作值，再取目标 id，因此允许的占位值不会使卡片输入留空。激活态仅作为实时观察返回，绝不会写入回放状态。
 
@@ -38,7 +38,7 @@ Status: implemented
 
 ## 测试
 
-单元测试固定注册与 dispose（资源释放）、独占调度、生成的提示词策略、可安全处理占位值的通用展示、非英语轮次中的直接人类创建、精确/陈旧/非运行中智能体与驱动检查、实时子智能体拒绝、恢复后 fork 根的权限、steering、发起者不匹配、读取/创建/部分字段编辑/暂停/恢复行为（包括严格 schema 占位值）、条件式阻塞说明、会话启动边沿后的重新激活、权限检查先于条件参数检查的失败行为、准确 Goal Round 的完成、仅自主 Round 触发终止、已配置的阻塞阈值，以及人类立即阻塞。无密钥回放快照把目标领域和工具挂载到真实的 headless 单次运行应用中，通过随附循环与持久化栈驱动一次携带严格 schema 占位值的 `update_goal` 探测，以及对 `create_goal` 和 `get_goal` 的调用，固定 stream-json transcript（文本记录），并检查外部持久化的目标变更。这里有意不把 echo-agent fixture（测试前置数据）当作应用 UX 的替代品。
+单元测试固定注册与 dispose（资源释放）、独占调度、生成的提示词策略、可安全处理占位值的通用展示、非英语轮次中的直接人类创建、精确/陈旧/非运行中智能体与驱动检查、实时子智能体拒绝、恢复后 fork 根的权限、steering、发起者不匹配、读取/创建/部分字段编辑/暂停行为（包括严格 schema 占位值）、持久 paused 的 resume 拒绝、条件式阻塞说明、会话启动边沿后的重新激活、权限检查先于条件参数检查的失败行为、准确 Goal Round 的完成、仅自主 Round 触发终止、已配置的阻塞阈值，以及人类立即阻塞。无密钥回放快照把目标领域和工具挂载到真实的 headless 单次运行应用中，通过随附循环与持久化栈驱动一次携带严格 schema 占位值的 `update_goal` 探测，以及对 `create_goal` 和 `get_goal` 的调用，固定 stream-json transcript（文本记录），并检查外部持久化的目标变更。这里有意不把 echo-agent fixture（测试前置数据）当作应用 UX 的替代品。
 
 ## 考虑过的替代方案
 
@@ -54,7 +54,7 @@ Status: implemented
 
 - 模型获得稳定而紧凑的生命周期 API，无需直接访问目标服务。
 - 改变状态的调用要求实时运行时根 agent、当前轮次中人类直接发送的消息，以及持久比较并交换引用。
-- 人类可以通过普通自然语言请求创建和重新激活目标，而恢复后的会话在收到此类输入前保持静止。
+- 人类可以通过普通自然语言请求创建目标，并重新激活已恢复或 blocked 的目标；持久 paused goal 需要面向用户的恢复路径。
 - Goal Round 可以完成或报告重复阻塞，但不能自行扩大任务权限。
 - 部署策略选择阻塞下限；同一个解析后的值同时控制执行与提示词指导。
 - 系统可兼容采用严格 schema 的提供方所填入的占位值，同时不会放行有实际意义的跨操作更新。
@@ -62,6 +62,7 @@ Status: implemented
 ## 已知限制与暂缓事项
 
 - 是否属于重大目标、是否要求继续、目标是否完成以及阻塞条件是否相同，仍由模型进行语义分类。独立评估器或完成证书予以延期。
+- 模型不能恢复持久 paused goal；该用户独占路径由独立的[用户独占 goal 暂停决策](../bug-fix/2026-09-03-user-owned-goal-pause-activation.zh.md)强制执行。
 - 这些工具会改变目标状态，但不调度 Goal Round、不分类异常驱动停止，也不取消活跃轮次；这些行为由同会话驱动器负责。
 - 除非另行挂载的继续执行驱动器接纳了目标来源的用户轮次，否则 Goal Round 权限路径处于休眠状态；本工具包本身不会制造这种权限。
 - 面向人类的斜杠命令发现与渲染由独立的 [`dsh-command-goal`](../../../../packages/goal/command-goal/README.zh.md) 插件负责。
diff --git a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.i18n.yaml
index 88beb1d0b3..ff57ba5953 100644
--- a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md
-2026-07-27-workspace-registration-deletion.md: aa3b3aaa107a87fe55395ae8cba65ab0430b6fbf
-2026-07-27-workspace-registration-deletion.zh.md: 4552e54770eb85098093f0d8f366cd5f58fc3f31
+2026-07-27-workspace-registration-deletion.md: 1d9804cfc4e2d44ea6c44f69b69dd6b10578f08a
+2026-07-27-workspace-registration-deletion.zh.md: 54e10b67a7607e32b08609fe00191da87d75f7e8
diff --git a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md
index aa3b3aaa10..1d9804cfc4 100644
--- a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md
+++ b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md
@@ -52,7 +52,7 @@ The menu, Modal, and buttons retain their existing structure and design tokens.
 
 Workspace package tests pin successful metadata-only deletion, same-path re-registration, unknown-id idempotence, table-failure rollback, explicit-marker restart recovery, unexplained-corruption rejection, and cache/table invariant behavior. Apiproxy and carrier tests pin the schema, handler, `workspace-not-found`, retained Session/folder, fresh-id re-registration, and committed `host/workspace-removed` frame. Client tests pin unary direct echo, duplicate removal, late changed frames, and deletion racing an in-flight baseline. Component tests pin confirmation, projection-settled closing, success-frame-before-unary ordering, failure, Cancel, Escape, and Close. The browser scenario observes every transient alert, slot error, console error, and page error while reusing a deleted title for a different directory.
 
-The assembled keyless Web scenario registers an existing temporary project directory, accounts a persisted Session, makes that Session current, confirms deletion in Chromium, and verifies the Workspace group disappears while Ungrouped retains the current Session. It checks the user file and JSONL log before and after deletion and repeats the UI, directory, and log assertions after reload.
+The assembled keyless Web scenario registers an existing temporary project directory, accounts a persisted Session, makes that Session current, confirms deletion in Chromium, and verifies the Workspace group disappears while Ungrouped retains the current Session. It checks the user file and JSONL log before and after deletion and repeats the UI, directory, and log assertions after reload. The scenario holds the seeded attachment frame until the browser selects the adoption-created New Session, proves that the seed is absent from the group, then delivers the frame and selects the only non-blank Session. Host attachment completion and a two-row count cannot prove browser membership: the group header plus New Session already satisfy that count, and the arriving seed can replace the positional locator between click and assertion.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md
index 4552e54770..54e10b67a7 100644
--- a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md
@@ -52,7 +52,7 @@ Host 流在前一笔全局顺序写入期间继续保留其已提交 id 集合
 
 Workspace 包测试固定了仅删除元数据的成功路径、同路径重新注册、未知 id 的幂等行为、表操作失败回滚、明确标记的重启恢复、来源不明损坏的拒绝，以及缓存／表不变量行为。Apiproxy 与载体测试固定了 schema、处理器、`workspace-not-found`、保留会话／文件夹、使用新 id 重新注册，以及已提交的 `host/workspace-removed` 帧。客户端测试固定了一元直接回显、重复移除、延迟到达的 changed 帧，以及删除与进行中基线并发的行为。组件测试固定了确认交互、投影稳定后关闭、成功帧先于一元响应、失败、Cancel、Escape 与 Close。浏览器场景会在为不同目录复用已删除名称时，观测每一次瞬时 alert、slot error、console error 与 page error。
 
-组装后的无密钥 Web 场景会注册一个已有临时项目目录，将持久化会话计入账本，把该会话设为当前会话，在 Chromium 中确认删除，并验证 Workspace 分组消失，而 Ungrouped 保留当前会话。该场景在删除前后检查用户文件和 JSONL 日志，并在刷新后重复验证 UI、目录与日志。
+组装后的无密钥 Web 场景会注册一个已有临时项目目录，将持久化会话计入账本，把该会话设为当前会话，在 Chromium 中确认删除，并验证 Workspace 分组消失，而 Ungrouped 保留当前会话。该场景在删除前后检查用户文件和 JSONL 日志，并在刷新后重复验证 UI、目录与日志。场景会扣住种子会话的归属帧，直到浏览器选中接纳目录时创建的 New Session，确认分组中尚无种子会话，再交付该帧并选中唯一的非空白会话。Host 完成归属写入和行数达到二都不能证明浏览器已收到成员关系：分组标题加 New Session 已满足该行数，而到达的种子会话会使位置定位器在点击与断言之间指向另一行。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
index 46a62de31a..a8899fea13 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
-2026-07-31-web-workspace-file-links.md: 87e8829b52f36ab9eb12149ff28775931a5ded1b
-2026-07-31-web-workspace-file-links.zh.md: 36b31c1224d3e51d5ed18b071495b2389f1bface
+2026-07-31-web-workspace-file-links.md: 1fd58deafa99f6c84371d2a2c3975eae86522ac2
+2026-07-31-web-workspace-file-links.zh.md: 8cb1d06562398a832fed0743a7c06894d0a4212b
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
index 87e8829b52..1fd58deafa 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
@@ -18,6 +18,8 @@ Two distinct defects sat behind that. The transcript never said what a turn had
 
 **The path link reads as a link.** Underlined at rest, not only on hover. This is the smaller half of the diff and the larger half of the fix.
 
+**Superseded for the web client by the [right Sidebar](2026-09-04-right-sidebar-docking-infrastructure.md):** `openFile` now opens a text-preview tab in the right Sidebar, which reads the file's text over the authenticated Remote carrier — no document is served, so the origin questions below do not arise — and the **Show in folder** action is gone; `session/openWorkspacePath` remains on the Host with no web caller. The decision as it shipped in July follows.
+
 **Opening stays the Host's job, and prefers the default browser.** `session/openWorkspacePath` hands the path to the operating system, which yields a `file://` document in a real browser: full page capabilities, and no reachability into `/api`, because a `file://` document is not same-origin with it. Measured on the reported artifact: `localStorage` works, the theme toggle flips, the tabs switch, and `fetch` to the API fails. For documents a browser renders — `.html`, `.htm`, `.xhtml`, `.svg` — the opener resolves the default *browser* rather than the type's default application when the platform can name one, because a developer who binds `.html` to an editor would otherwise click a produced page and get source code. macOS reads the LaunchServices `https` handler and desktop Linux reads `$BROWSER`; either falls back to the default application when no browser can be named. Windows uses its registered association, and WSL first translates the path before using that same Windows handoff. When files are hidden, **Show in folder** passes `.` through the same owner `openFile`; it appears only for a loopback page whose current `host.describe.canOpenPath` permits native opening. Other deployments omit it, with `nativeOpen: false` available when desktop detection would be a false positive.
 
 **Serving workspace files over HTTP is out of scope, and so are non-local clients.** Serving files from the harness itself — same-origin with `/api`, behind `CSP: sandbox`, or from a second listener whose own port gives served documents their own origin — was rejected with the product scope: previews for a browser that is not on the Host machine are not supported, so the Host opener answers the supported case completely and the HTTP machinery would answer only the unsupported one.
@@ -33,4 +35,4 @@ Two distinct defects sat behind that. The transcript never said what a turn had
 
 ## Consequences
 
-Every existing file affordance changed at once: write, edit, read, and the generic single-file card all reach `openFile`, so the link fix and browser preference apply without per-row changes. The assembled Web test covers single-line CSS overflow and a one-click Host handoff without launching a native application. A produced `file://` document cannot `fetch` its own siblings (while `<script src>`, `<img>`, and CSS `@import` work), the one capability HTTP serving had that this does not. Remote clients keep the chips but omit the folder action; the full path remains in each chip's `title`. Markdown still opens in the platform's `.md` application; in-product rendering is separate work.
+Every existing file affordance changed at once: write, edit, read, and the generic single-file card all reach `openFile`, so the link fix and browser preference apply without per-row changes. The assembled Web test covers single-line CSS overflow and a one-click Host handoff without launching a native application. A produced `file://` document cannot `fetch` its own siblings (while `<script src>`, `<img>`, and CSS `@import` work), the one capability HTTP serving had that this does not. Every client keeps the chips and none offers a folder action; the full path remains in each chip's `title`. Markdown still opens in the platform's `.md` application; in-product rendering is separate work.
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
index 36b31c1224..8cb1d06562 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
@@ -18,6 +18,8 @@ Status: implemented
 
 **路径链接读得出是链接。** 静止状态下就带下划线，而不只在悬停时。这是本次改动中更小的那一半，却是修复中更大的那一半。
 
+**对 web 客户端已被[右侧 Sidebar](2026-09-04-right-sidebar-docking-infrastructure.zh.md)取代：** `openFile` 现在在右侧 Sidebar 里打开一个文本预览 tab，经已认证的 Remote 载体读取文件文本——不再提供任何文档，下文的同源问题因此不再出现——**Show in folder** 动作已删除；`session/openWorkspacePath` 留在 Host 上，已无 web 调用方。以下是七月交付时的决定原文。
+
 **打开仍然是 Host 的职责，并且优先选用默认浏览器。** `session/openWorkspacePath` 把路径交给操作系统，得到的是真实浏览器里的一份 `file://` 文档：页面能力完整，且够不到 `/api`——因为 `file://` 文档与它并不同源。在所报告的那份产物上实测：`localStorage` 可用、主题切换生效、tabs 可切换，而对 API 的 `fetch` 失败。对浏览器能渲染的文档——`.html`、`.htm`、`.xhtml`、`.svg`——平台能够确定默认浏览器时，打开器解析的是默认**浏览器**而非该类型的默认应用，因为把 `.html` 绑给编辑器的开发者，否则点开一个产出的页面得到的会是源码。macOS 读取 LaunchServices 的 `https` 处理程序，桌面 Linux 读取 `$BROWSER`；无法确定浏览器时，两者都会回退到默认应用。Windows 使用其注册的文件关联，WSL 则先转换路径，再使用同一 Windows 交接。存在隐藏文件时，**在文件夹中显示**会把 `.` 经由同一 owner `openFile` 传递；它只在 loopback 页面的当前 `host.describe.canOpenPath` 允许原生打开时出现。其他部署会省略它；桌面探测误报时可配置 `nativeOpen: false`。
 
 **以 HTTP 提供工作区文件不在范围内，非本机客户端亦然。** 由 harness 自己提供文件——与 `/api` 同源、置于 `CSP: sandbox` 之后、或交给一个以自身端口给所服务文档独立源的第二监听器——随产品范围一并否决：不为「浏览器不在 Host 机器上」的场景提供预览，因此 Host 打开器完整回答受支持的场景，而那套 HTTP 机制只会回答不受支持的那个。
@@ -33,4 +35,4 @@ Status: implemented
 
 ## 后果
 
-现有的每一处文件交互都同时改变了：write、edit、read 与通用单文件卡片都汇到 `openFile`，因此链接修复与浏览器优先策略无需逐行改动。组装层 Web 测试覆盖单行 CSS 溢出和单次点击的 Host 交接，且不会启动原生应用。产出的 `file://` 文档无法 `fetch` 同级文件（但 `<script src>`、`<img>` 和 CSS `@import` 可用），这是 HTTP 提供曾有、而此处没有的能力。远程客户端保留 chip，但省略文件夹操作；每个 chip 的 `title` 仍保留完整路径。Markdown 仍由平台的 `.md` 应用打开；产品内渲染属于另一项工作。
+现有的每一处文件交互都同时改变了：write、edit、read 与通用单文件卡片都汇到 `openFile`，因此链接修复与浏览器优先策略无需逐行改动。组装层 Web 测试覆盖单行 CSS 溢出和单次点击的 Host 交接，且不会启动原生应用。产出的 `file://` 文档无法 `fetch` 同级文件（但 `<script src>`、`<img>` 和 CSS `@import` 可用），这是 HTTP 提供曾有、而此处没有的能力。每个客户端都保留 chip，且都不提供文件夹操作；每个 chip 的 `title` 仍保留完整路径。Markdown 仍由平台的 `.md` 应用打开；产品内渲染属于另一项工作。
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
index 4ea0331b57..ff0246f556 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
-2026-08-06-continuable-subagent-interrupt.md: c59601fd486d40c3a9367f2af132fb30207c35c9
-2026-08-06-continuable-subagent-interrupt.zh.md: b56b94e30fc544e77c0be99dcb759e56e47ef5d4
+2026-08-06-continuable-subagent-interrupt.md: e865415bbba4ea196afd7d075a079412f18e5a1e
+2026-08-06-continuable-subagent-interrupt.zh.md: ed4981bdac12a5c8b09b2e8dbc6363817e4d7dea
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
index c59601fd48..e865415bbb 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
@@ -39,7 +39,7 @@ A human or ancestor can stop a runaway continuable turn without losing the child
 
 The address-only RPC exposes one bit of live residency: an absent target is accepted while a live target under a mismatched parent returns `subagent-unauthorized`. The single-user local Host trust model accepts that observability; a future multi-principal Host must revisit both authority and response indistinguishability.
 
-The Web surface keeps Send and Stop as independent actions for a running continuable child: the client `Session.cancel()` routes Stop through `subagent.interrupt` (one-shot addresses stay uncancellable, ordinary sessions keep their existing primary Send/Stop toggle through `session.cancel`), while Send continues to queue follow-ups. A running parent-offline continuable child keeps the default composer with input and Send disabled but Stop reachable, returning to the read-only takeover once it stops ([Web subagent conversations](2026-07-27-web-subagent-conversations.md) owns the surrounding catalog and composer contract).
+The Web surface keeps Send and Stop as independent actions for a running continuable child: the client `Session.cancel()` routes Stop through `subagent.interrupt` (one-shot addresses stay uncancellable, ordinary sessions keep their existing primary Send/Stop toggle through `session.cancel`), while Send delivers follow-ups through the busy-Enter setting's mode — Queue by default, Steer when selected — exactly as plain Enter does ([busy Send button](../bug-fix/2026-09-04-busy-send-button-follows-enter-setting.md)). A running parent-offline continuable child keeps the default composer with input and Send disabled but Stop reachable, returning to the read-only takeover once it stops ([Web subagent conversations](2026-07-27-web-subagent-conversations.md) owns the surrounding catalog and composer contract).
 
 The model-facing `interrupt_agent(agent_id)` tool in `dsh-tool-subagent-control` passes `exec.agent` as the `ancestor` authority and adds none of its own: the core primitive verifies live registry identity and recorded lineage, so the tool can name a direct child or a deeper descendant with the same generic `agent_id` parameter — deliberately not `subagent_id`, which would imply direct children only. Discovery rides `list_agents({ scope: 'descendants' })` over the new `SubagentRuntime.listDescendants()` one-trace pre-order walk with verified `parentId`/`depth` per entry ([durable catalog note](../../archived/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md) owns the listing contract); discovery is a hint, never authority. `send_message` keeps its exact-direct-parent authority — only interrupt is ancestor-wide.
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
index b56b94e30f..ed4981bdac 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
@@ -39,7 +39,7 @@ Host RPC `subagent.interrupt` 接收 continuable 的 `SubagentAddress` 并返回
 
 仅凭地址的 RPC 会暴露一项关于在线驻留状态的二值信息：不存在的目标会被接受，而 parent 不匹配的在线目标会返回 `subagent-unauthorized`。单用户本地 Host 的信任模型接受这种可观察性；未来的多主体 Host 必须重新审视权限和响应不可区分性。
 
-在 Web 侧，正在运行的 continuable child 使用相互独立的 Send 与 Stop 操作：客户端 `Session.cancel()` 将 Stop 路由到 `subagent.interrupt`（one-shot 地址保持不可取消，普通会话仍通过 `session.cancel` 保留既有的 primary Send/Stop 切换），同时 Send 继续将后续消息加入队列。parent 离线但仍在运行的 continuable child 保留默认 composer，禁用输入区与 Send，但 Stop 仍然可达；停止后恢复为只读接管界面（周边目录与 composer 约定由 [Web subagent 对话](2026-07-27-web-subagent-conversations.zh.md)拥有）。
+在 Web 侧，正在运行的 continuable child 使用相互独立的 Send 与 Stop 操作：客户端 `Session.cancel()` 将 Stop 路由到 `subagent.interrupt`（one-shot 地址保持不可取消，普通会话仍通过 `session.cancel` 保留既有的 primary Send/Stop 切换），同时 Send 按繁忙态 Enter 设置的模式投递后续消息——默认 Queue，选择后为 Steer——与 plain Enter 完全一致（[繁忙态 Send 按钮](../bug-fix/2026-09-04-busy-send-button-follows-enter-setting.zh.md)）。parent 离线但仍在运行的 continuable child 保留默认 composer，禁用输入区与 Send，但 Stop 仍然可达；停止后恢复为只读接管界面（周边目录与 composer 约定由 [Web subagent 对话](2026-07-27-web-subagent-conversations.zh.md)拥有）。
 
 `dsh-tool-subagent-control` 中面向模型的 `interrupt_agent(agent_id)` 工具把 `exec.agent` 作为 `ancestor` 授权传入，自身不增加任何权限：核心原语校验在线注册表身份与记录的 lineage，因此该工具可以用同一个通用 `agent_id` 参数指定直接 child 或更深的后代——刻意不用会暗示仅限直接 child 的 `subagent_id`。发现依赖 `list_agents({ scope: 'descendants' })`，其底层是新的 `SubagentRuntime.listDescendants()` 单次追踪 pre-order 遍历，每个条目带经校验的 `parentId`／`depth`（列表约定由[持久化目录 note](../../archived/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)拥有）；发现只是提示，绝非权限。`send_message` 保持其确切直接 parent 权限——只有中断是 ancestor 级的。
 
diff --git a/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.i18n.yaml b/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.i18n.yaml
new file mode 100644
index 0000000000..a9da3ca3f4
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.md
+2026-09-04-right-sidebar-docking-infrastructure.md: 8e1d1b5518c3b80a05be877ee9796883b6eb9a60
+2026-09-04-right-sidebar-docking-infrastructure.zh.md: 6830bf74734bbc8072b201ded6194e1d20ddbc88
diff --git a/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.md b/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.md
new file mode 100644
index 0000000000..8e1d1b5518
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.md
@@ -0,0 +1,100 @@
+# Agent Note: Right Sidebar docking infrastructure
+
+Status: implemented
+
+English | [中文](2026-09-04-right-sidebar-docking-infrastructure.zh.md)
+
+## Problem
+
+The Web client's right column was a single-purpose Detail panel: `ui-chat` occupied the `details` slot with `DetailsPanel`, which showed one selected Tool call's raw payload through a `conversation.details.tool` child seat. Nothing else could live there. A plugin that wanted a persistent side surface — a file preview, a task list, a diff — had no seat to register into, no way to open its content from the conversation, and no shared layout to share the column with.
+
+Files the agent produced were the sharpest case. A produced-file chip or a `read` row's path link handed the path to the operating system through `session/openWorkspacePath`, so a browser that was not on the Host machine could not look at the file at all, and even a local one left the product to do so. The details panel meanwhile duplicated the chat rows' cards at full height, a second presentation surface every card had to keep in step.
+
+## Decision
+
+The right column is a per-session docking surface — split panes, tabs, floating panels, and an undoable operation sequence — owned by `ui-sidebar-right` over the `ui-dockkit` engine, replacing the Detail panel. This note owns the surface: the engine, the frame's right column, the panel's presentations and controls, and the per-session state. What lives in the surface is decided elsewhere: how plugins declare tab types, open content, and receive their props is [tab types and navigation](../architecture/2026-09-05-sidebar-tab-types-and-navigation.md); live data behind an address is the [client resource model](../architecture/2026-09-05-client-resource-model.md); reading workspace files is the [workspace file service](../architecture/2026-09-05-workspace-files-service.md); and the guide, the text preview, and the file tree are the [shipped types](2026-09-05-sidebar-text-preview-and-file-tree.md).
+
+### Package topology
+
+| Package | Kind | Owns |
+|---|---|---|
+| `packages/client/ui-dockkit` | static-linked library, zero DSH dependencies | the layout engine and the React components that render and drive it; consumers compile its sources, and it keeps exactly one stylesheet because a consumer de-duplicates injected sheets by file name |
+| `packages/client/ui-sidebar-right` | dynamic plugin | the `rightbar` panel seat and the `conversation.session.header.corner` expand button over one store, one surface per session, both presentations, the float host, `ctx.sidebarRight`, `ctx.sidebarRightTabs`, the tab domain (one occurrence per tab record), the three extension seats, the guide tab type, and the `sidebarRight` copy namespace |
+
+The kit is the product's first embedder and knows nothing about it: every string arrives through `DockLabels`, every tab body through a `TabRenderer` dispatching on an opaque `kind`, and every gesture leaves through `DockIntents`. The integration package supplies what the kit refuses to know.
+
+### Layout engine
+
+The engine is a normalized recursive split tree: `nodes` keyed by id, `rootId` for the docked root, `floats` bottom-to-top. The ids are branded (`PaneId`, `SplitId`, `TabId`; `NodeId` is the pane/split union), minted only by a `Mint`, so no id kind stands in for another or for a bare string. A floating panel is a pane whose `host` is `'float'` with capacity one, drawn without a tab strip. `applyOp(state, op)` returns the next state and the operations that undo it, captured when the operation runs because the pre-operation state is gone by undo time. Every operation carries the ids it creates, so `replay(initial, ops)` reproduces the same tree from the same start; the engine reads no clock and no random source. The `Sequencer` keeps a linear history with one entry per intent — the operations one gesture or command produced undo and redo together — a run of consecutive focus-only entries steps as one, and a new entry after stepping back drops the forward branch. Planners are the pure intent layer — `(state, mint, args) → LayoutOp[]` — and `DockController` is a thin observable shell over them. `planSettle` is the opt-in follow-up planner that merges away every docked pane an intent emptied and reseeds an emptied root pane through the embedder's factory.
+
+Components render a snapshot and report settled intents, one per gesture: a drag previews in local state while the gesture's facts stay in its closure, and the release folds the net result into one operation. Gestures are pointer events with pointer capture rather than HTML5 drag-and-drop. A chip is a capsule carrying one control, its close; a secondary press opens the context menu (close plus the embedder's `renderTabMenuItems`). After the chips sits the add control, which asks the embedder through `DockIntents.addTab` to seat its seeded tab (`planAddTab`). Floating is the drag released clear of the surface, and copying has no kit control at all — `DockIntents.duplicateTab` stays for embedder APIs. The split control's glyph is a frame bisected vertically, as the split is. Four interaction rules fix defects found in a real browser and are kept on purpose: capture the pointer on gesture start, never make the tab strip a scroll container, land focus on click rather than press, and let a control nested in a draggable chip stop its own press. The tab's actions menu renders in a portal positioned against its control, because the strip's deliberate overflow clip would otherwise cut it off. The kit ships no undo/redo control, and no header: an embedder's surface-wide controls go through `DockSurface`'s `chrome` prop, which the kit places at the far end of the top-right pane's strip (`topRightPaneId`: the last child of every row split, the first of every column split). The generic kit defaults to four panes; the Sidebar supplies its two-pane product limit.
+
+### The frame's right column
+
+[Responsive Sidebar and tab information](../architecture/2026-09-07-sidebar-responsive-tab-info.md) supersedes this note's no-concession layout, overlay presentation and product pane limit. `ui-layout` still owns three-column geometry and pixel width preferences; the Sidebar occupant reports presentation through `ctx.layout.openRightbar(track, fullscreen)` and `closeRightbar()`, without the frame injecting the Sidebar package. Exact width rules belong to [ui-layout](../../../../packages/client/ui-layout/README.md).
+
+The right Sidebar uses one mounted content tree in normal and fullscreen modes; hiding preserves tab state, and fullscreen covers the viewport while retaining underlying column reservation. Floats still use viewport coordinates through a portal and remain open when the Sidebar closes. The product limits docking to two horizontal panes and a 20–80% divider; the generic engine keeps its own defaults.
+
+### State
+
+`ui-sidebar-right` keeps one `SurfaceState` per session id — the layout, its history, and the mint counter — in a store declared at the seat registration. Every action mints the ids its intent needs, asks a kit planner for the operations, runs the settle planner over the result, and records the whole intent as one history entry before assigning the session's surface back; no action edits a layout in place. The settle step is the product's rule: a docked pane whose last tab is closed, moved out, or floated is merged away, and when only the root pane remains and it is empty, the guide tab is reseeded — there is always at least one tab and never an empty pane, so no pane-closing gesture exists. State is memory-only: a reload returns every session to the collapsed default, and switching sessions keeps each surface where it was. Layout is presentation state and never enters the session log.
+
+### Beyond the surface
+
+The surface renders tabs whose bodies it does not know: each tab carries a `kind`, and the panel asks the type registry for the implementation in force and dispatches to its keyed body seat. Everything a body may rely on — its record, its pane, whether it is visible, how it was navigated to, an abort signal, and the actions it may take — is read through the framework-injected `useTabInfo()`. The registry, the navigation face `ctx.sidebarRight`, the seats, and the tab information are specified in [tab types and navigation](../architecture/2026-09-05-sidebar-tab-types-and-navigation.md); a body that shows data reads it through the [client resource model](../architecture/2026-09-05-client-resource-model.md).
+
+### Entry points and removals
+
+`ui-chat`'s `openFile(path, { line? })` — reached by tool-row path links, produced-file chips, and closing-message mentions — now opens the file into the Sidebar through the navigation face (see [tab types and navigation](../architecture/2026-09-05-sidebar-tab-types-and-navigation.md)). The `Show in folder` action and its `canOpenWorkspacePath` probe are removed from `ui-deliverables`: the Sidebar has no directory form, and the product keeps no secondary entry. `DetailsPanel`, `ToolDetails`, the tool-node reader, the chat store's selection, `ToolDetailsProps`, and `CENTER_MIN` are removed. `session/openWorkspacePath` remains on the Host with no web caller.
+
+## Alternatives considered
+
+**Adopt a docking library.** Six engines were evaluated against the product's state-ownership requirement (the layout is a recorded, replayable sequence the product owns). dockview is uncontrolled and its only external entry is a destructive `fromJSON`, with undo in a paid tier; react-mosaic has no floating layer and rests on a drag base unmaintained for years; rc-dock, golden-layout, and Lumino failed on state ownership. FlexLayout 0.10.x was the one viable candidate — external Model, vetoable `onAction`, content-preserving `fromJson` — and was kept as a verified fallback whose switch points were the prototype's five-zone dock and multi-float tests. Both passed self-built with no switch signal, and its 0.x minors carry breaking changes, so it was not adopted.
+
+**Layered reuse: `react-resizable-panels` for sizes, Pragmatic drag-and-drop for gestures.** The planned main line before the prototype. Rejected once the prototype's own size and gesture layers passed in a real browser: the layers the plan meant to save had already been written and verified, so the remaining value was only long-tail edge handling. It stays a replaceable layer if snap or priority sizing is ever required.
+
+**A drawer over `shell.overlay`, or a double-layer shell (root rail, session content).** The prototype shipped as a drawer to avoid touching the frame. Rejected for the product: a drawer is not a column and never squeezes the conversation, and the double-layer shell hit the slot core's one-handle-one-scope rule, which would have made collapsing un-undoable. The frame owns a real column; content and state stay session-bound.
+
+**A frame-owned 32px rail as the collapsed state, the panel living inside the animated grid track, and the overlay as a separate portal.** The first shipped form. Rejected after review: a solid rail track pushes the conversation's scrollbar inboard for a strip that exists only while collapsed; a panel inside the animating track is stretched and re-laid-out by every track transition, so the Sidebar itself visibly moved when it should not; and two code paths for one panel meant switching presentation remounted it. The panel is now one edge-anchored box that slides and the track only reserves room.
+
+**A 40px rail inside the conversation column, with its own `sidebar.right.rail.item` seat.** Tried next, so the rail could leave with the panel. Rejected on review as visually too heavy for what it carried: a full-height strip for one button and a placeholder. The expand control is now a single header button and the collapsed-state seat is deferred until something needs it.
+
+**A header row on the panel.** The first form carried a title and its controls in a 40px row above the strip. Removed: the strip already is the panel's top edge, so the controls sit at the strip's end in the top-right pane through the kit's chrome seat, and the title said nothing the tabs did not.
+
+**The expand button as a `conversation.session.header.utilities` entry.** Tried after the rail. Rejected on review: as a list entry it sat inside the utilities row, so it was not at the header's true corner, and its appearance and disappearance shifted the Session log control beside it. A dedicated corner seat with a reserved footprint fixes both.
+
+**A per-chip "more" control with copy and float items.** The first form gave every chip a `⋯` menu holding close, copy, and float. Rejected on review: the chip now carries only its close, the menu moved to the secondary press with only close (plus embedder items), and copy and float left the panel entirely — copy stays an API (`open` with `duplicate: true`), float stays the drag. The kit's `duplicateTab` / `floatTab` intents and planners are unchanged.
+
+**Undo and redo buttons on the panel header.** Shipped first, then removed: the sequence is an architectural fact, and stepping it is not a product action yet. The API stays reachable as `@internal` methods for tests and the future navigation controller.
+
+**Empty panes as a persistent state.** The first design allowed a pane to stay after its last tab left, with a placeholder. Rejected because nothing offered a way to close such a pane; every intent now settles the surface so an emptied pane is merged away and an emptied root pane reseeds the guide.
+
+**Inline the kit through `packages/util` and the `INLINE_SAFE` list.** A build probe showed it works, but the util build chain has no CSS pipeline and the kit ships a stylesheet; the static-linked client package (the `ui-primitives` precedent) was chosen knowing that changing the kit means rebuilding the shell and reloading.
+
+## Consequences
+
+- The docking surface itself no longer overflows its panel: `.surface` and `.pane` clamp to the column (`min-width: 0`, `overflow: hidden`), so a long unwrapped line scrolls inside the body and the strip's controls stay in view in every split.
+- Layout is undoable and per session, and it is memory-only; a reload starts every session collapsed. Undo is reachable only through `@internal` service methods; the product shows no history controls.
+- A pane cannot be left empty and the surface cannot be left tabless: closing, moving out, or floating a pane's last tab drops the pane, and emptying the last pane brings the guide back.
+- A pane holds at most one guide tab: a second one cannot be added, opened, duplicated, or moved in; the guide's uniqueness is per pane, so a split still seeds its new pane with a guide.
+- A pane may split only when each equal half can still hold what cannot shrink: the strip's fixed controls (its width minus the chip box and the fill, so the top-right pane's chrome counts on the half that hosts it) plus one chip at its minimum, measured in the component layer after every commit and on resize. Otherwise the split control stays, disabled with its own copy, the matching edge drop zones are withheld, and panes the user narrows keep their size; the product permits at most two horizontal panes, regardless of widening or divider movement.
+- The Sidebar panel never moves when the presentation switches, and its slide is the same in both presentations; the conversation is the only thing that animates on a switch. A hidden panel keeps its tabs mounted, so a preview survives a collapse.
+- Collapsed, the Sidebar is one header-corner button: the conversation keeps its full width and its scrollbar at its edge, the button leaves when the panel opens, and its footprint stays so nothing else in the header moves.
+- A tab is closed from its chip; copying and floating have no panel control (copying is API-only, floating is the drag). The context menu is reachable by right-click and carries close plus embedder items.
+- The Detail panel and its duplicate card presentation are gone (a net removal of roughly 1,400 lines); cards are read in place, and `inspect` opens the trajectory view.
+- The frame has no centre floor: a viewport narrower than the two edge columns squeezes the conversation toward zero instead of closing a column.
+- The kit is compiled by its consumers, so a kit change requires a shell rebuild and a page reload; there is no HMR for it.
+- The panel, the float host, and the portalled tab menu use hard-coded z-index values; the client still has no z-index token layer.
+
+## Testing
+
+`ui-dockkit` specs pin the engine's invariants — every operation's inverse round-trips, `replay` over any prefix of the history equals the recorded state, one compound intent steps as one entry, focus runs coalesce symmetrically, the pane cap and the width rule refuse with no record — and drive the components with props alone, with no scaffold. `ui-sidebar-right` specs cover the per-session store, the seat's presentations and controls, per-pane guide uniqueness, and the width-aware split. The Web e2e suite drives the shipped Sidebar in Chromium through the real plugin graph: expand and collapse, split to the limit and the greyed control, floats, docking back, and the guide. Both suites are keyless.
+
+## Deferred
+
+- A z-index token layer, then the panel's, the float host's, and the menu's hard-coded values.
+- The assembled session-switch case, blocked on the fixture composition opening its settings surface by default.
+- Chinese counterparts for the new packages' READMEs and for the English documentation this change edited.
+- Snap or priority pane sizing, touch tuning, and keyboard routes for split, move, and float.
+- Persistence of the layout, popout windows, and a content navigation stack (entries keyed by pane and content, adjacent duplicates replaced, a `navigating` guard, closed tabs left in the stack).
+- A non-closable tab (a `closable` flag on `TabRecord`, drawn as a fixed leading marker rather than a capsule) once a tab type needs one.
diff --git a/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md b/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md
new file mode 100644
index 0000000000..6830bf7473
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md
@@ -0,0 +1,100 @@
+# Agent Note: 右侧 Sidebar 停靠基础设施
+
+Status: implemented
+
+[English](2026-09-04-right-sidebar-docking-infrastructure.md) | 中文
+
+## Problem
+
+Web 客户端的右列曾是单一用途的 Detail 面板：`ui-chat` 以 `DetailsPanel` 占据 `details` 坑位，通过 `conversation.details.tool` 子坑位展示一个被选中 Tool 调用的原始载荷。其他任何内容都无法住在那里。想要一个常驻侧面的插件——文件预览、任务清单、diff——没有可注册的坑位，没有从会话流打开自己内容的通道，也没有可共享的布局来与他人分享这一列。
+
+Agent 产出的文件是最尖锐的案例。产出文件 chip 或 `read` 行的路径链接会经 `session/openWorkspacePath` 把路径交给操作系统，因此不在 Host 机器上的浏览器完全看不到该文件，即便本机浏览器也要离开产品才能查看。与此同时 Detail 面板以全高重复渲染会话行的卡片，成为每张卡片都必须保持同步的第二个展示面。
+
+## Decision
+
+右列是每会话一份的停靠面（分栏 pane、tab、浮动面板与可撤销的操作序列），由 `ui-sidebar-right` 基于 `ui-dockkit` 引擎持有，取代原来的 Detail 面板。本篇只管这个面：引擎、框架的右列、面板的两种呈现与控件、每会话的状态。面里放什么由别处决定：插件如何声明 tab 类型、打开内容、拿到 props 见[tab 类型与导航](../architecture/2026-09-05-sidebar-tab-types-and-navigation.zh.md)；地址背后的活数据见[客户端资源模型](../architecture/2026-09-05-client-resource-model.zh.md)；读工作区文件见[工作区文件服务](../architecture/2026-09-05-workspace-files-service.zh.md)；引导页、文本预览与文件树见[随包类型](2026-09-05-sidebar-text-preview-and-file-tree.zh.md)。
+
+### 包拓扑
+
+| 包 | 形态 | 所有物 |
+|---|---|---|
+| `packages/client/ui-dockkit` | 静态链接库，零 DSH 依赖 | 布局引擎与渲染/驱动它的 React 组件；消费方编译其源码，且它只保留一张样式表，因为消费方按文件名去重注入的样式表 |
+| `packages/client/ui-sidebar-right` | 动态插件 | 共用一个 store 的 `rightbar` 面板坑位与 `conversation.session.header.corner` 展开按钮、每会话一份 surface、两种呈现模式、浮层宿主、`ctx.sidebarRight`、`ctx.sidebarRightTabs`、tab 域（每条 tab 记录一个 occurrence）、三个扩展坑位、引导 tab 类型与 `sidebarRight` 文案命名空间 |
+
+该库的第一个嵌入方就是本产品，而库对此一无所知：所有字符串经 `DockLabels` 传入，所有 tab 正文经按不透明 `kind` 分派的 `TabRenderer` 传入，所有手势经 `DockIntents` 传出。集成包提供库拒绝知晓的一切。
+
+### 布局引擎
+
+引擎是归一化的递归分裂树：`nodes` 按 id 索引，`rootId` 指向停靠根，`floats` 自底向上排列。id 带 brand（`PaneId`、`SplitId`、`TabId`；`NodeId` 是 pane 与 split 的并集），只由 `Mint` 铸出，任何一种 id 都不能充当另一种或裸字符串。悬浮面板是 `host` 为 `'float'`、容量为一的 pane，不绘制 tab 条。`applyOp(state, op)` 返回下一状态以及撤销它的操作，逆操作在执行时刻捕获，因为到 undo 时操作前状态已不存在。每个操作携带自己创建的 id，所以 `replay(initial, ops)` 从同一初态重现同一棵树；引擎不读时钟也不读随机源。`Sequencer` 维护线性历史，一个意图一条账——一次手势或命令产生的全部操作一起撤销与重做——连续的纯焦点条目合并为一步，后退后的新条目丢弃前向分支。planner 是纯意图层——`(state, mint, args) → LayoutOp[]`——`DockController` 是其上的薄可观察壳。`planSettle` 是可选的收尾 planner：合并掉意图留下的每个空停靠 pane，并经嵌入方的工厂重新种上被清空的根 pane。
+
+组件渲染快照并上报已落定的意图，每个手势一条：拖拽过程只在本地 state 预览、手势的事实住在它的闭包里，松手把净结果折成一条操作。手势基于 pointer 事件与 pointer capture，而非 HTML5 拖放。chip 是胶囊形，只带一个控件——关闭；右键打开上下文菜单（关闭加嵌入方的 `renderTabMenuItems`）。chip 之后是添加控件，经 `DockIntents.addTab` 请嵌入方种入它的种子 tab（`planAddTab`）。悬浮是把拖拽松手在面之外，复制则完全没有库控件——`DockIntents.duplicateTab` 留给嵌入方 API。分栏控件的图标是被竖线一分为二的方框，与分栏本身一致。四条交互规则修复了真实浏览器中发现的缺陷并被有意保留：手势开始即捕获指针；tab 条绝不做滚动容器；焦点落在 click 而非 press；可拖 chip 内嵌的控件自行拦截按下。tab 的操作菜单以 portal 渲染并对着它的按钮定位，因为 tab 条刻意裁切溢出，画在条内的菜单会被一起切掉。库不自带 undo/redo 控件，也不自带头部：嵌入方的面级控件经 `DockSurface` 的 `chrome` prop 传入，库把它们放在右上 pane 的 tab 条末端（`topRightPaneId`：每个行分裂取最后一个子节点、每个列分裂取第一个）。通用工具包默认允许四个窗格；Sidebar 传入产品的两格上限。
+
+### 框架的右列
+
+[响应式 Sidebar 与标签信息](../architecture/2026-09-07-sidebar-responsive-tab-info.zh.md)取代本记录中的无让步布局、覆盖模式与产品窗格上限。`ui-layout` 仍拥有三列几何与像素宽度偏好，Sidebar 占位项通过 `ctx.layout.openRightbar(track, fullscreen)` 和 `closeRightbar()` 报告呈现方式，框架不注入 Sidebar 包。具体宽度规则见 [ui-layout](../../../../packages/client/ui-layout/README.zh.md)。
+
+右栏在普通与全屏模式下使用同一棵已挂载内容树；隐藏保留标签状态，全屏覆盖视口并保留底层列占位。浮窗仍经 portal 使用视口坐标，不随右栏关闭。产品限制为两个水平窗格与 20–80% 分割比例，通用引擎保留自己的默认值。
+
+### 状态
+
+`ui-sidebar-right` 为每个会话 id 保存一份 `SurfaceState`——布局、历史与铸造计数——住在坑位注册时声明的 store 里。每个 action 先铸造意图所需的 id，向库的 planner 索取操作，对结果跑一遍 settle planner，把整个意图记为一条历史账，再把该会话的 surface 整体赋回；没有 action 就地改布局。settle 是产品规则：最后一个 tab 被关闭、拖走或悬浮出去的停靠 pane 会被合并掉；只剩根 pane 且为空时重新种上引导 tab——永远至少有一个 tab、永远没有空 pane，所以不存在"关闭 pane"手势。状态仅在内存：刷新使所有会话回到折叠默认态，切换会话时各 surface 保持原样。布局是呈现状态，永不进入会话日志。
+
+### 面之外
+
+这个面渲染的 tab 正文它自己并不认识：每个 tab 带一个 `kind`，面板向类型注册表询问该 kind 生效的实现，再派发到其 keyed 正文坑位。正文能依赖的一切——它的记录、所在格、是否可见、如何被导航到、中止信号、可做的动作——均通过框架注入的 `useTabInfo()` 从标签域读取。注册表、导航面 `ctx.sidebarRight`、坑位与 标签信息 在[tab 类型与导航](../architecture/2026-09-05-sidebar-tab-types-and-navigation.zh.md)里定；展示数据的正文经[客户端资源模型](../architecture/2026-09-05-client-resource-model.zh.md)读取。
+
+### 入口与删除
+
+`ui-chat` 的 `openFile(path, { line? })`——工具行路径链接、产出文件 chip 与收尾消息提及都经由它——现在经导航面把文件开进 Sidebar（见[tab 类型与导航](../architecture/2026-09-05-sidebar-tab-types-and-navigation.zh.md)）。`Show in folder` 动作及其 `canOpenWorkspacePath` 探针从 `ui-deliverables` 移除：Sidebar 没有目录形态，产品也不保留次级入口。`DetailsPanel`、`ToolDetails`、tool-node reader、chat store 的 selection、`ToolDetailsProps` 与 `CENTER_MIN` 一并删除。`session/openWorkspacePath` 留在 Host 上，已无 web 调用方。
+
+## Alternatives considered
+
+**采用停靠库。** 六个引擎按产品的状态所有权要求（布局是产品拥有的、可记录可回放的序列）评估。dockview 非受控，唯一外部入口是破坏性的 `fromJSON`，undo 划入付费层；react-mosaic 没有浮层，拖拽底座多年未维护；rc-dock、golden-layout、Lumino 在状态所有权上不可用。FlexLayout 0.10.x 是唯一可行候选——外置 Model、可否决的 `onAction`、保内容的 `fromJson`——被保留为已验证的降级预案，切换判定点是原型的五区 dock 与多浮层测试。两项自研均通过、无切换信号，且其 0.x minor 携带 breaking change，故未采用。
+
+**分层复用：`react-resizable-panels` 管尺寸、Pragmatic drag-and-drop 管手势。** 原型之前的规划主线。原型自己的尺寸层与手势层在真实浏览器中通过后即否决：计划要省下的两层已经写完并验证，剩余价值只在长尾边界处理。若将来需要 snap 或 priority 尺寸语义，它仍是可替换的一层。
+
+**挂在 `shell.overlay` 上的抽屉，或双层外壳（root rail、session 内容）。** 原型以抽屉形态交付以避免触碰框架。产品层面否决：抽屉不是一列，永不挤压会话区；双层外壳撞上 slot core 的 one-handle-one-scope 规则，会让折叠不可撤销。框架拥有一条真实的列；内容与状态仍绑定会话。
+
+**框架自有的 32px rail 作为折叠态、面板住在带动画的 grid 轨道里、覆盖态另走 portal。** 第一版交付形态。评审后否决：实体 rail 轨道为一条只在折叠态存在的条带把会话区滚动条向内挤；住在动画轨道里的面板被每次轨道过渡拉伸重排，Sidebar 自己在动而它本不该动；一个面板两条代码路径意味着切换呈现模式要重挂载它。现在面板是一个锚在边缘的盒子做平移，轨道只负责占位。
+
+**会话列内一条 40px 的 rail，带自己的 `sidebar.right.rail.item` 坑位。** 随后一试，好让 rail 能随面板离场。评审否决：为一个按钮加一个占位画一整条竖带，视觉太重。展开入口现在是头部的单个按钮，折叠态坑位推迟到有真实需求时再声明。
+
+**面板自带头部行。** 第一版在 tab 条上方有一条 40px 的标题加控件行。删除：tab 条本来就是面板的顶边，控件经库的 chrome 坑位坐到右上 pane 的条末端，标题说的也不比 tab 多。
+
+**展开按钮作为 `conversation.session.header.utilities` 的一个 list 条目。** rail 之后的一试。评审否决：作为 list 条目它坐在工具区行内，不在头部真正的角落，而且它的出现与消失会挪动旁边的 Session log 控件。专设一个保留占位宽度的角落坑位同时解决两点。
+
+**每个 chip 一个带复制与悬浮项的"更多"控件。** 第一版给每个 chip 一个 `⋯` 菜单，装关闭、复制、悬浮。评审否决：chip 现在只带关闭，菜单挪到右键且只剩关闭（加嵌入方条目），复制与悬浮整体离开面板——复制仍是 API（`open` 带 `duplicate: true`），悬浮仍是拖拽。库的 `duplicateTab` / `floatTab` 意图与 planner 不变。
+
+**面板头部的 undo 与 redo 按钮。** 先上后撤：序列是架构事实，步进它现在还不是产品动作。API 以 `@internal` 方法保留给测试与将来的导航控制器。
+
+**空 pane 作为一种持久状态。** 第一版允许 pane 在最后一个 tab 离开后带占位留下。否决，因为没有任何方式关掉这样的 pane；现在每个意图都会整理 surface，被清空的 pane 合并掉，被清空的根 pane 重新种上引导。
+
+**经 `packages/util` 与 `INLINE_SAFE` 清单内联库。** 构建探针证明可行，但 util 构建链没有 CSS 管线而库带样式表；在知晓改库须重建壳并刷新页面的前提下，选择静态链接的 client 包（`ui-primitives` 先例）。
+
+## Consequences
+
+- 停靠面自身不再溢出面板：`.surface` 与 `.pane` 收在列内（`min-width: 0`、`overflow: hidden`），长的不换行行在正文内滚动，tab 条控件在任何分栏下都可见。
+- 布局可撤销且按会话隔离，同时仅在内存；刷新使所有会话回到折叠态。undo 只能经 `@internal` 服务方法触达；产品不显示历史控件。
+- pane 不能留空、surface 不能没有 tab：关闭、拖走或悬浮出 pane 的最后一个 tab 会删掉该 pane，清空最后一个 pane 会让引导回来。
+- 一个 pane 最多持有一个引导 tab：第二个不能被添加、打开、复制或搬入；唯一性按 pane 算，所以分栏仍给新 pane 种引导。
+- pane 只有在等分后的两半都仍能容下不可收缩部分时才可分栏：tab 条的固定控件（条宽减去 chip 盒与填充，因此右上 pane 的面板控件只计在承载它的那一半）加一个最小宽度的 chip，由组件层在每次提交与尺寸变化后测量。否则分栏控件保留但禁用并带自己的文案，对应的边缘落区不再提供，用户拖窄的 pane 保持原尺寸；产品最多两个水平窗格，不因拉宽或拖分隔条而提高上限。
+- 切换呈现模式时 Sidebar 面板一动不动，两种模式的平移一模一样；切换时只有会话区在动。隐藏的面板保持 tab 挂载，预览在折叠后仍在。
+- 折叠时 Sidebar 只是头部角落的一个按钮：会话区保持全宽、滚动条停在自己的边缘，面板展开时按钮离场但占位保留，头部其余内容不动。
+- tab 从 chip 上关闭；复制与悬浮在面板上没有控件（复制仅 API、悬浮靠拖拽）。上下文菜单经右键打开，含关闭与嵌入方条目。
+- Detail 面板及其重复的卡片展示消失（净删约 1,400 行）；卡片就地阅读，`inspect` 打开 trajectory 视图。
+- 框架没有中列下限：视口窄于两侧列之和时会话区被挤向零，而不是关掉某一列。
+- 库由消费方编译，改库须重建壳并刷新页面；它没有 HMR。
+- 面板、浮层宿主与 portal 出去的 tab 菜单使用硬编码 z-index；客户端仍没有 z-index token 层。
+
+## Testing
+
+`ui-dockkit` 的规格钉住引擎不变量——每个操作的逆操作往返恒等、历史任意前缀的 `replay` 等于记录状态、一个复合意图作为一条账步进、焦点段对称合并、格数上限与宽度规则拒绝且零记账——并仅以 props 驱动组件，不用 scaffold。`ui-sidebar-right` 的规格覆盖 per-session store、座位的两种呈现与控件、按格唯一的引导、宽度感知分栏。Web e2e 套件在 Chromium 里经真实插件图驱动随包交付的 Sidebar：展开与收起、分到上限与置灰控件、浮窗、回坞、引导页。两套均无需密钥。
+
+## Deferred
+
+- z-index token 层，随后替换面板、浮层宿主与菜单的硬编码值。
+- 组合层的切换会话用例，受阻于 fixture 组合默认打开设置面。
+- 新包 README 与本次改动的英文文档的中文对。
+- snap 或 priority 面板尺寸语义、触屏调优，以及分栏/移动/悬浮的键盘路径。
+- 布局持久化、popout 窗口，以及内容导航栈（条目以 pane 与内容为键、相邻重复替换、`navigating` 守卫、已关 tab 留在栈中）。
+- 不可关闭的 tab（`TabRecord` 上的 `closable` 标志，画成固定的前置标记而非胶囊），等到有 tab 类型需要时再做。
diff --git a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.i18n.yaml b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.i18n.yaml
new file mode 100644
index 0000000000..e0a9906fd6
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md
+2026-09-05-sidebar-text-preview-and-file-tree.md: a21946c73302561a2cb8539ca314e0a5d4fb25b8
+2026-09-05-sidebar-text-preview-and-file-tree.zh.md: dc02c159e0e052a21f2f1c80ac2e6f30bf5cf416
diff --git a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md
new file mode 100644
index 0000000000..a21946c733
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md
@@ -0,0 +1,122 @@
+# Agent Note: Sidebar text preview and file tree
+
+Status: implemented
+
+English | [中文](2026-09-05-sidebar-text-preview-and-file-tree.zh.md)
+
+## Problem
+
+The right Sidebar's [docking infrastructure](2026-09-04-right-sidebar-docking-infrastructure.md) and its [tab type registry](../architecture/2026-09-05-sidebar-tab-types-and-navigation.md) give a plugin a place to register a tab type, but a surface with no types is an empty column. Three questions had to be answered by shipped code before anyone else could register a type: what a new pane shows before it holds content, how a file the agent produced or read is looked at without leaving the product, and how a reader finds a file the conversation never mentioned. The answers also had to demonstrate the type authoring model end to end — a static definition, a body in a keyed seat, a Slot store and inject face for the type's own state, `useResource` for live data behind an address — so that a type written outside `ui-sidebar-right` has a worked template rather than a contract alone.
+
+Each answer carries product rules that code alone does not explain: why a text file loads by page instead of whole, why a changed file is announced rather than refreshed, why the file tree is a page type that claims no address, why the guide gives its tab away instead of opening beside itself. This note records those decisions for the three shipped types.
+
+## Decision
+
+Three tab types ship with the Sidebar: the **guide** (`ui-sidebar-right`), the **text preview** (`ui-sidebar-textpreview`), and the **file tree** (`ui-sidebar-files`). Each registers a static definition into `ctx.sidebarRightTabs` and a body into the keyed `sidebar.right.pane.tab` seat under the definition's `id`, inside its own `ctx.effect`, so the type exists exactly as long as its plugin. The guide and the tree are page types opened by kind; the text preview is a viewer that claims every `file` resource address at the lowest band. A type's controls live in its own body; the pane's tab strip carries only the panel's actions. Copy is locale-owned in each package's namespace (`sidebarRight`, `sidebarTextpreview`, `sidebarFiles`).
+
+### The guide
+
+The guide is what a pane shows before it holds content. Its registration is `{ id: '@deepseek-ai/dsh-client-ui-sidebar-right/guide', kind: 'guide', priority: 'builtin', title }` with no `patterns`: a guide views nothing, so it is opened by kind through `openTab` and recorded under the page address `sidebar://guide`, which is the registry's bookkeeping and never composed by a caller. The tab's title is `开始` / `Start`, captured into the layout record when the pane is seeded, so a later language change relabels the type and not tabs already open.
+
+The body is a centred column — a lead line (`侧栏用来放你想一直看着的东西。` / `The sidebar holds what you want to keep looking at.`), one line of copy (`会话里的文件和产物会开在这一栏，也可以从下面的入口打开。` / `Files and artifacts from the conversation open in this column; the entries below open more.`), and a grid of entry boxes at most 480px wide, each box at least 160px, filling as many columns as fit. The boxes are projected from every registered type's `guide[]` in `order`, through the registry's observable `guide()` list, so a type registering later appears without the guide knowing it. A box shows the contributing type's glyph, title, and description, and picking it calls `tabActions.openTab(entry.kind, { replaceTab: true })`: the picked type opens in the guide's own tab, and the guide is gone. The guide is a doorway, not a page that stays open beside what it opened.
+
+The body is also the replacement seam. It renders the `sidebar.right.tab.guide` chain with the shipped guide as the chain's fallback, so a product that registers its own entry takes the whole body, and with no entry, or every entry declining, the shipped guide draws. Because the shipped guide is the fallback and not a chain entry, there is always exactly one body and it cannot be outvoted by accident.
+
+A pane holds at most one guide, and the docking layer enforces it as product behaviour: the strip's add control hides while a guide is present, opening the guide into such a pane focuses it, a guide is never duplicated, and a guide dragged, dropped, or docked into a pane that already has one merges into it (the arriving tab closes). Settling a surface reseeds the guide when the root pane empties, so there is always at least one tab and never an empty pane.
+
+### The text preview
+
+`text` is the fallback viewer for every file. Its registration is `{ id: '@deepseek-ai/dsh-client-ui-sidebar-textpreview', kind: 'text', patterns: ['dsh-resource://file/**'], priority: 'fallback', title: basenameOf }`. The pattern contains `:` and so matches the whole address; `fallback` is the lowest band, so a type at `extension` or `builtin` with a narrower pattern (`*.png`, say) takes those addresses and everything else lands here, while the text type stays in the candidate list for any file. The `id` is the package name and doubles as the `key` of the body seat, so an extension that takes the `text` kind over cannot make the seat pick up this body by mistake. The title is the address's decoded last segment: the whole address stays the content identity — two files with one name in different directories, or one path under two sessions, are two tabs — and only the chip text is shortened.
+
+A tab's address is `dsh-resource://file/session/<sessionId>/<path relative to that session's workspace root>` or `dsh-resource://file/absolute/<absolute path>` ([Workspace Files](../architecture/2026-09-05-workspace-files-service.md) owns the grammar and the `fileAddressFor` / `parseFileAddress` helpers in `dsh-util-workspace-path`). The preview never splits the string itself: `hostFileOf` in `rpc.ts` calls `parseFileAddress` and yields the `{ sessionId, path }` the endpoint takes — a `session` address reads under the session it names with the relative path the Host resolves, an `absolute` address reads under the session the slot was mounted for with the absolute path — and a malformed address throws, a programming error, because the registry routes every `file` address to this type and a caller building one is expected to use the helper.
+
+Metadata and content come from different places. `useResource<'file'>(tab.contentId)`, the global standard hook from the [client resource model](../architecture/2026-09-05-client-resource-model.md), yields `{ absolutePath, version, bytes, changed }` from the `file` provider; the body reads `changed` and the resource's failed state. Content is the type's own business, read one page of lines at a time through `remote.workspaceFiles.read(sessionId, path, { offset }, signal)` with no `limit`, so the page length is the Host's configured cap (`maxLines`, 5000 lines by default, and a page may not exceed `maxBytes`, 2 MB by default). The first mount reads the first page; a **Load more** button at the end of the loaded text reads the next page until `eof`, disabled and reading `正在读取…` / `Reading…` while a read is in flight, and absent once the file has ended or a page failed. Pages are appended in file order with no separators and no line numbers, each carrying its line count (`lines`) so one empty line and a page past the end read differently. A first page from a newer file version replaces the pages of the older one; a later page from a newer version is not adopted and the walk restarts from the first page, so the body never shows two versions at once. The face keeps a request generation per tab: a reload bumps it, and a page settling from an older generation writes nothing. A tab switched away from and back reads nothing, because the pages live in the store, not the body.
+
+The store is Slot-standard: one exclusive instance per session, bucketed by tab id, holding `{ version, pages, eof, loading, failure, scrollTop, wrap, revision }`. Bucketing by tab, not by file, is deliberate — two tabs of one file scroll independently. The face (`loadPage`, `reloadPages`) is the only asynchronous half: it marks a read in flight, awaits the Remote result, and writes a page or a failure through the store's actions, writing nothing if the owner's `signal` has fired. The `signal` also ends the bucket: the face arms one abort listener per tab at the tab's first read, and that listener forgets the bucket — not the body, which mounts and unmounts as tabs switch; a tab that never read has no bucket and no listener, and a record can end while its body is unmounted behind another tab. Scroll offset, wrap, and the navigation already answered therefore outlive the body: a tab comes back where the reader left it rather than re-reading or jumping again. Nothing persists across a page reload.
+
+Navigation is a `line`. The `read` tool row passes its 1-based `offset` as `openResource(address, { params: { line } })`, and the produced-file chip passes nothing; the body narrows `navigation.params` to `SidebarRightResourceParamsMap['file']` (`{ line?: number }`, declared by the `file` type's owner) without runtime validation, because caller and body meet at a typed same-process boundary. If the loaded pages do not reach the line, the body reads the next page, again, until they do or the file ends — pages load in order; there is no seek — then scrolls the line to the top of the body and highlights it, once per `navigation.revision`. The store records the answered revision, so a body remounting for the same revision restores the scroll offset instead of jumping, and a new `openResource` for the same file (revealed, not duplicated) arrives as a new revision and jumps again. A line past the end of the file stops silently at `eof`; a page that fails while walking stops the walk and shows the failure line.
+
+A changed file is announced, not applied. When the `file` resource reports `changed` — the agent wrote the file through a tool after the last `stat` — a bar above the path row says `文件已被修改，显示的还是旧内容。` / `The file has changed; this is the older text.` with a `重新载入` / `Reload` button. Only the click does two things at once: `meta.reload()` (a fresh `stat`, which clears `changed`) and `reloadPages` (drop every page, read the first one again). The scroll offset is kept, so the reader stays where they were. Nothing else triggers a reload: the tree and the preview do not watch the filesystem, and an external edit is not announced. A resource that turns `failed` — the file deleted, or the Host refusing it — puts a failure bar in the same place, its line from `failure-line.ts` and the same reload button, ahead of any pending `changed`; the pages already read stay beneath it.
+
+The body's header is one row: the file's path as the address names it on the left (12px, tertiary colour, one line, ellipsis when it overflows, full path on hover) and two 24px controls at its right end — a wrap toggle (`自动换行` / `Wrap lines`, pressed state shown, **on by default** per tab: long lines wrap and never scroll horizontally until the reader turns it off, whereupon the file body scrolls horizontally on its own) and a reload button (`重新读取文件` / `Read the file again`) that does exactly what the change bar's button does. Neither control is ever disabled. The preview takes the pane body's full height (`height: 100%` against the pane body, which is a block scroller of definite height) so a short file leaves no separately styled space below it, and the file body — monospace, 13px, line height 1.6, 10px vertical padding — is the only scroller: the header and the change bar stay put while a long file scrolls under them.
+
+A failed page keeps the pages already shown and adds one sentence at the end of the loaded text, in terms of the file rather than the transport, with a `重试` / `Retry` button that reads the same page again: `workspace-file/not-found` `这个文件不在了。可能已被移动或删除。` / `That file is gone. It may have been moved or deleted.`; `workspace-file/outside-workspace` `这个文件在工作区之外，侧栏不会读取它。` / `That file is outside the workspace, so the sidebar will not read it.`; `workspace-file/too-large` `这一页太大，侧栏不读取超过 {limit} 的页。` / `That page is too large; the sidebar does not read pages above {limit}.` with the byte cap rendered as `2 MB`; `workspace-file/not-text` `这不是文本文件，没法在这里查看。` / `That is not a text file, so it cannot be shown here.`; `workspace-file/not-regular-file` `这不是一个普通文件，没有可显示的文本。` / `That is not a regular file, so it has no text to show.`; any other failure, carrier or unclassified, `读取失败：{message}` / `Read failed: {message}` with the failure's own message. The mapping lives in `failure-line.ts`, apart from the component so it is testable on its own; a code the reader does not name falls to the generic line carrying the carrier's message. A directory or a binary file therefore shows one failure line and nothing else; an empty file shows the header and an empty body with no marker.
+
+### The file tree
+
+`files` is a page type, not a viewer: it claims no address. Its registration is `{ kind: 'files', id: '@deepseek-ai/dsh-client-ui-sidebar-files', priority: 'builtin', title, guide: [{ order: 10, title, description, icon: IconFolderClose16 }] }` — no `patterns`, because nothing navigates *to* a file tree by address; the guide's entry box opens the type itself. `id` is the implementation's identity in the Tab system and doubles as the `key` of the body seat `sidebar.right.pane.tab`, so the same string names the type and the component that draws it. `register()` returns a disposer and goes through `ctx.effect`, as every registration does.
+
+The root is the session's working directory as the Host reports it in the session list (`useSessions().byId[sessionId].cwd`), labelled by `workspaceTitleOf` from `dsh-util-workspace-path` — the final non-empty path segment — with the root string itself as the label when the path is separator-only. A session without a working directory shows one line (`noWorkspace`) and issues no request. There is no root chooser and no way to browse upward: the Host's `list` refuses paths outside the Session's workspace root, so the one directory the client can list is the one it shows.
+
+The tree is not one resource, and that decides where its state lives. A directory listing per level, expanded lazily, is view state the type owns, so it sits in a Slot-standard exclusive store (one instance per session) bucketed by tab id: `{ root, levels, expanded }`, with `levels` keyed by absolute path to `loading | ready | failed` and `expanded` the absolute paths currently open, root included. A resource has one address and one current value; a tree that pins a resource per expanded level would make the resource model carry which directories a reader has opened, which is the type's business. `useResource` stays for content with a single address.
+
+The face is the tree's only asynchronous half. `start(tabId, root, signal)` seeds the bucket with the root expanded and lists it; `toggle(tabId, path, loaded, signal)` flips the expanded set and lists the level only the first time; `load(tabId, path, signal)` marks `loading`, calls `remote.workspaceFiles.list(sessionId, absolutePath, signal)`, and writes `ready` or `failed`. The adapter keeps the listing's `entries` and `truncated` and drops its workspace-relative `path`: every key in the tree is absolute, and a child's key is its parent joined with the entry name by `/`. Collapsing keeps the level, so reopening draws from memory without a request; a level that failed is likewise kept and not retried on reopen — reload is the retry. The owner's `signal` ends a bucket: on abort the tab is forgotten and a listing that settles afterwards writes nothing, and a mounted body never re-seeds a bucket whose signal has fired.
+
+Rows are the reader's order, not the endpoint's: directories first, then files and other entries, each group by `Intl.Collator(undefined, { numeric: true, sensitivity: 'base' })` so `file2` precedes `file10` and case does not split the list. Dotfiles are shown like any other name; the tree filters nothing the Host returned. The three entry types draw differently: `directory` is a button with `aria-expanded` and an open/closed folder glyph whose children indent by 14px per level; `file` is a button with the document glyph and no size column; `other` (a symlink, socket, or device) is a greyed, non-focusable span with `aria-disabled` and a tooltip saying it cannot be opened, so a directory is reported whole without offering a click that would fail. A level the Host cut at its `maxEntries` cap ends with a `truncated` marker after the entries; an empty level says `empty`; a listing in flight shows `loading` under its directory.
+
+A file click is `tabActions.openResource(fileAddressFor(sessionId, root, absolutePath))`: the entry's absolute path under the tree's root becomes the `dsh-resource://file/session/<sessionId>/<path relative to the root>` address, each segment percent-encoded. The tree never names a viewer: the registry's claim decides who draws the address (`text` today, at `fallback`), and an extension that claims `dsh-resource://file/**` above it takes the click without the tree changing. The open lands in the pane holding the files tab at call time, and an already-open tab for the same address is revealed rather than duplicated — both the navigation controller's defaults. The user's call was explicit: a file opened from the tree does not force a split; it takes a new tab where the tree is.
+
+Reload is the tree's one control, an icon button (`reload`) at the right of the root's header row. It resets every level and lists again exactly the paths in `expanded`; a level that was listed and then collapsed is dropped and fetched anew the next time it opens. The control lives in the body because a type's controls belong to its body: the pane's tab strip carries only the kit's and the panel's actions, and no per-type tools seat exists. The tree does not watch the filesystem; a level changes only when reloaded or first expanded, and the `changes` stream is the text viewer's concern.
+
+Copy is the `sidebarFiles` namespace, thirteen keys. Row states: `loading` 「正在读取…」/ "Reading…", `empty` 「空目录」/ "Empty directory", `truncated` 「条目太多，只显示了一部分。」/ "Too many entries; showing only some of them.", `noWorkspace` 「这个会话没有工作区目录。」/ "This session has no workspace directory.", `entry.other` 「这不是文件或目录，没法打开。」/ "Not a file or a directory, so it cannot be opened.", `reload` 「重新读取」/ "Reload". Failure lines are one per Host code, in terms of the directory: `workspace-file/not-found` 「这个目录不在了。可能已被移动或删除。」/ "That directory is gone. It may have been moved or deleted.", `workspace-file/outside-workspace` 「这个目录在工作区之外，侧栏不会读取它。」/ "That directory is outside the workspace, so the sidebar will not read it.", `workspace-file/not-directory` 「这不是一个目录。」/ "That is not a directory."; any other failure, carrier or unclassified, shows `error.unavailable` 「读取失败：{message}」/ "Read failed: {message}" with the failure's own message, because the tree has nothing useful to add to a transport-level error.
+
+## Alternatives considered
+
+**A per-pane tools seat for the active tab's controls (`sidebar.right.pane.tab.tools`).** Shipped for one review round for the text preview's wrap and reload and the tree's reload, then removed on the user's call: it put type-private buttons on the panel's strip beside the split and collapse controls, where they read as panel chrome. A type's controls belong in its own body; the preview's sit at the right end of its path row and the tree's at the right end of its root row.
+
+**Keep `Show in folder`.** A directory has no destination in the Sidebar, and the product decision was no secondary entry to the desktop opener. Removed, with the capability loss stated: `openFile('.')` names a directory, which the text preview refuses with `not-regular-file`, so the row offers nothing rather than a button that always fails.
+
+**Content in the resource stream.** Content can be arbitrarily large, so the `file` resource carries metadata (`version`, `bytes`, `changed`) and the preview reads content by page through `workspaceFiles.read`; the `changed` flag is a notice, not a payload.
+
+**Reload re-fetches every page that was loaded.** The alternative to the shipped rule (drop every page, read the first one again). Not taken: re-fetching the loaded range means several sequential reads before anything can be shown, and the loaded range after an agent edit no longer describes the same lines; the reader keeps their scroll offset and asks for more where the loaded text ends. The reader's place can land in empty space when the earlier view was deep in the file, which is stated as a consequence.
+
+**Refresh the text under the reader when the file changes.** Rejected: reloading under a reader loses their place, and a file the agent is writing changes repeatedly. The bar waits for a click.
+
+**Whole-file read, or seekable pages.** A whole-file read has no bound; seekable pages need a line index the Host does not keep. Pages load in order from the first, and a navigation to a deep line walks pages until it is covered — the cost is stated under Consequences and the seek is deferred.
+
+**Validate `line` at run time.** The first form accepted `unknown` params and treated anything but a positive integer as no request. Rejected once `params` became typed: the `file` type's owner declares `{ line?: number }` in `SidebarRightResourceParamsMap`, caller and body meet at a typed same-process boundary, and the repository rule is not to add runtime validation there.
+
+**The read's session from the slot for every address.** The first form read under the session the body was mounted for. Kept only for the `absolute` scope, which names no session: a `session` address carries its session precisely so that one relative path in two sessions means two files.
+
+**Wrap off by default.** The first form. Reversed on the user's review: a preview column is narrow, and long lines scrolling horizontally hide the text; wrap is on until the reader turns it off, per tab.
+
+**Fill the pane by changing the docking kit's `.paneBody`.** The pane body is a block scroller with a definite height, not a flex container, so the preview's `flex: 1` did nothing and the pane body scrolled a 30,000px-tall preview. Rejected in favour of `height: 100%` on the preview root: the fix is the type's, the kit stays unaware of its bodies, and the file body becomes the one scroller so the header stays put and line jumps scroll the right element.
+
+**Key the store by file, not by tab.** Rejected: two tabs of one file are two reading positions; the pages could be shared but the view could not, and the saving is one page read.
+
+**A package-local `file:///` address builder, and a package-local basename for the tree's root label.** Rejected: a file address must carry its scope — the session whose root resolves a relative path, or the absolute path itself — hence the shared `fileAddressFor`; one `workspaceTitleOf` serves every workspace-label surface.
+
+**Model the whole tree as one resource.** Rejected: a resource has one address and one current value, and a tree that pins a resource per expanded level would make the resource model carry which directories a reader has opened, which is the type's business.
+
+**The guide as a chain entry rather than the chain's fallback.** Rejected: with the shipped guide as an entry, a product's replacement and the shipped guide would both be candidates and the winner would depend on registration order; as the fallback there is always exactly one body and it cannot be outvoted by accident.
+
+**The guide opens the picked type beside itself.** Rejected: the guide is a doorway, and a pane holding the guide plus what it opened would show a doorway that leads nowhere further; `openTab(kind, { replaceTab: true })` hands the tab over.
+
+## Consequences
+
+- A type written outside `ui-sidebar-right` has a complete template: `ui-sidebar-textpreview` shows a viewer with an address-derived read, an exclusive Slot store bucketed by tab, an inject face, typed navigation params, and body-owned controls; `ui-sidebar-files` shows a page type with a guide entry and a lazily filled store; the guide shows a chain fallback.
+- Reading by page bounds every request (`maxLines` lines, `maxBytes` bytes) at the cost of a **Load more** control, no total line count, and sequential walks to a deep line; a navigation to line 40,000 of a large file reads eight pages first.
+- Announcing a change instead of applying it keeps the reader's place during an agent's repeated writes, at the cost of showing stale text until the reader clicks; an external edit is never announced.
+- Reload reads the first page only, so a reader deep in a file reloads into the top of it and pages forward again; the scroll offset is preserved but may point past the loaded text.
+- Per-tab view state survives tab switches and remounts and is gone with the tab or the page; nothing is persisted.
+- The file tree renders whatever the Host lists, so a large directory shows up to `maxEntries` rows plus a marker with no search or filter, and a reader finds a deep file by expanding levels one at a time.
+- Every user-facing string of the three types is locale-owned and listed in this note, so a copy review has one place to read them.
+
+## Testing
+
+The text preview's `tests/` cover the registry claim and yielding (through the real `SidebarRightTabRegistry`), the address translation (`sessionFileOf` accepting the `session` scope and throwing on others), the store's page, version, reset, view, and forget actions, the face's in-flight, failure, aborted, and reload paths, the page arithmetic (`linesOf`, `offsetsOf`, `lastLineLoaded`), the body's first read, load-more, retry, change bar, navigation walk, jump-once, remount, wrap default and toggle, header controls, and forget-on-abort, the failure-line mapping, and the plugin's registrations and their removal on dispose. A Chromium probe against the built app recorded the fill and scroll numbers (`.artifacts/sidebar-tab-types/app-probe.log`, `ROUND3`): a short file's preview is the pane body's content height, a long file scrolls inside the preview body, and the pane body never scrolls. The file tree's `tests/` cover ordering, lazy loading, collapse memory, reload, the three entry types, truncation and failure rows, and forget-on-abort. `apps/web/tests/sidebar-right.e2e.ts` opens a produced file from the conversation into the preview over the real Remote carrier.
+
+## Deferred
+
+- Virtualized or seekable page loading (pages load in order), a reload that restores the loaded range, throttled scroll persistence, and a wrap icon in `ui-primitives`.
+- Line numbers, syntax highlighting, rendered Markdown, images, and search in the text preview; a total line count or end-of-file marker.
+- Search, an artifact filter, drag-and-drop, rename, a context menu, current-file highlight, filesystem watching, and browsing above the workspace root in the file tree.
+- Product review of the guide's copy, and the guide's behaviour when a type contributes several entries.
+- Chinese README counterparts for `ui-sidebar-textpreview` and `ui-sidebar-files`.
+
+## Related
+
+- [Right Sidebar docking infrastructure](2026-09-04-right-sidebar-docking-infrastructure.md) — the panel, panes, and the guide's one-per-pane rule.
+- [Sidebar tab types and navigation](../architecture/2026-09-05-sidebar-tab-types-and-navigation.md) — the registry, bands, `id`, `openTab` / `openResource`, and owner props these types consume.
+- [Client resource model](../architecture/2026-09-05-client-resource-model.md) — `useResource` and the `file` protocol's metadata.
+- [Workspace Files service](../architecture/2026-09-05-workspace-files-service.md) — the address grammar, `stat` / `read` / `list` / `changes`, and the error codes the failure lines map.
diff --git a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md
new file mode 100644
index 0000000000..dc02c159e0
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md
@@ -0,0 +1,122 @@
+# Agent Note: Sidebar 文本预览与文件树
+
+Status: implemented
+
+[English](2026-09-05-sidebar-text-preview-and-file-tree.md) | 中文
+
+## Problem
+
+右侧 Sidebar 的[停靠基础设施](2026-09-04-right-sidebar-docking-infrastructure.zh.md)与[tab 类型注册表](../architecture/2026-09-05-sidebar-tab-types-and-navigation.zh.md)给了插件一个注册 tab 类型的位置，但没有类型的停靠面只是一根空列。三个问题必须先由随包交付的代码答出来，别人才谈得上注册类型：一个新 pane 在承载内容之前显示什么；agent 产出或读过的文件如何不离开产品就能查看；读者如何找到会话从未提到的文件。这些答案还要把类型作者模型完整演示一遍——静态定义、keyed 坑位里的体、类型自有状态用的 Slot store 与 inject face、地址背后活数据用的 `useResource`——让 `ui-sidebar-right` 之外写的类型有一份可照抄的样板，而不只有一份契约。
+
+每个答案都带着代码本身解释不了的产品规则：文本文件为什么按页读而不是整读，文件变了为什么只提示不刷新，文件树为什么是不认领任何地址的页类型，引导页为什么交出自己的 tab 而不是在旁边再开一个。本文为三个随包交付的类型记下这些决定。
+
+## Decision
+
+Sidebar 随包交付三个 tab 类型：**引导页**（`ui-sidebar-right`）、**文本预览**（`ui-sidebar-textpreview`）与**文件树**（`ui-sidebar-files`）。每个类型都在自己的 `ctx.effect` 里把静态定义注册进 `ctx.sidebarRightTabs`、把体注册进 keyed 坑位 `sidebar.right.pane.tab`（键 = 定义的 `id`），因此类型的寿命恰等于其插件。引导页与文件树是按 kind 打开的页类型；文本预览是以最低档认领每个 `file` 资源地址的查看器。类型的控件住在自己的体里；pane 的 tab 条只承载面板自身的动作。文案由各包的命名空间（`sidebarRight`、`sidebarTextpreview`、`sidebarFiles`）以 locale 方式持有。
+
+### 引导页
+
+引导页是 pane 承载内容之前显示的东西。它的注册定义是 `{ id: '@deepseek-ai/dsh-client-ui-sidebar-right/guide', kind: 'guide', priority: 'builtin', title }`，没有 `patterns`：引导页不查看任何东西，所以经 `openTab` 按 kind 打开，并记在页地址 `sidebar://guide` 之下——那是注册表自己的记账，调用方从不拼它。tab 标题是 `开始` / `Start`，在 pane 播种时捕获进布局记录，于是之后切换语言只重标类型，不改已开着的 tab。
+
+体是一根居中的列——一句引导语（`侧栏用来放你想一直看着的东西。` / `The sidebar holds what you want to keep looking at.`）、一行文案（`会话里的文件和产物会开在这一栏，也可以从下面的入口打开。` / `Files and artifacts from the conversation open in this column; the entries below open more.`），以及一组最宽 480px 的入口框栅格，每框至少 160px，能放几列放几列。入口框按 `order` 从每个已注册类型的 `guide[]` 投影而来，经注册表可观察的 `guide()` 列表，因此后注册的类型不用引导页知道就能出现。一个框显示贡献类型的图标、标题与说明；点选它调用 `tabActions.openTab(entry.kind, { replaceTab: true })`：被选的类型在引导页自己的 tab 里打开，引导页随之消失。引导页是一扇门，不是留在被打开者旁边的一页。
+
+体同时也是替换接缝。它渲染 `sidebar.right.tab.guide` 链，并以随包交付的引导页作为链的 fallback，于是注册了自己入口的产品接管整个体，而没有入口、或每个入口都拒绝时，随包交付的引导页照常绘制。因为随包交付的引导页是 fallback 而不是链上的一个入口，所以永远恰有一个体，也不可能被意外投掉。
+
+一个 pane 最多持有一个引导页，停靠层把这条作为产品行为强制执行：有引导页时 tab 条的添加控件隐藏，往这样的 pane 打开引导页只是聚焦它，引导页永不复制，被拖拽、落下或回坞进已有引导页的 pane 的引导页并入它（来者关闭）。settle 一个 surface 时，根 pane 空了就重新播下引导页，于是永远至少有一个 tab、永远没有空 pane。
+
+### 文本预览
+
+`text` 是每个文件的兜底查看器。它的注册定义是 `{ id: '@deepseek-ai/dsh-client-ui-sidebar-textpreview', kind: 'text', patterns: ['dsh-resource://file/**'], priority: 'fallback', title: basenameOf }`。pattern 含 `:`，因此匹配整个地址；`fallback` 是最低档，所以 `extension` 或 `builtin` 档上一个 pattern 更窄的类型（比如 `*.png`）接走那些地址，其余一切落到这里，而 text 类型对任何文件都留在候选列表中。`id` 是包名，兼作体坑位的 `key`，于是一个接管了 `text` kind 的扩展不可能让坑位误拿到这个体。标题是地址解码后的最后一段：整个地址仍是内容身份——不同目录下同名的两个文件、或同一路径在两个会话之下，是两个 tab——只有 chip 上的文字被缩短。
+
+tab 的地址是 `dsh-resource://file/session/<sessionId>/<相对该会话工作区根的路径>` 或 `dsh-resource://file/absolute/<绝对路径>`（[Workspace Files](../architecture/2026-09-05-workspace-files-service.zh.md) 拥有这套语法及 `dsh-util-workspace-path` 里的 `fileAddressFor` / `parseFileAddress` 助手）。预览从不自己拆这个串：`rpc.ts` 里的 `hostFileOf` 调 `parseFileAddress` 得到端点所需的 `{ sessionId, path }`——`session` 地址在它命名的会话下以 Host 解析的相对路径读取，`absolute` 地址在坑位被挂载的会话下以绝对路径读取——畸形地址直接抛错，那是程序错误，因为注册表把每个 `file` 地址都路由给这个类型，而造地址的调用方本应使用助手。
+
+元数据与内容来自不同的地方。`useResource<'file'>(tab.contentId)`——[client 资源模型](../architecture/2026-09-05-client-resource-model.zh.md)提供的全局标准 hook——从 `file` 提供者得到 `{ absolutePath, version, bytes, changed }`；体读 `changed` 与资源的失败态。内容是类型自己的事，经 `remote.workspaceFiles.read(sessionId, path, { offset }, signal)` 一次读一页行，不传 `limit`，因此页长就是 Host 配置的上限（`maxLines`，默认 5000 行；且一页不得超过 `maxBytes`，默认 2 MB）。首次挂载读第 1 页；已加载文本末尾的 **加载更多** 按钮读下一页直到 `eof`，读取进行中它禁用并显示 `正在读取…` / `Reading…`，文件读完或某页失败后消失。页按文件顺序追加，没有分隔也没有行号，每页带着自己的行数（`lines`），单个空行与越过文件末尾的页由此区分。来自更新文件版本的第一页替换旧版本的页；更新版本的后续页不被采用，从第一页重新走一遍，于是体永不同时显示两个版本。face 按 tab 记请求代次：重载递增它，旧代次结算的页什么也不写。切走再切回的 tab 什么都不读，因为页住在 store 里而不是体里。
+
+store 是 Slot 标准件：每会话一个独占实例，按 tab id 分桶，持有 `{ version, pages, eof, loading, failure, scrollTop, wrap, revision }`。按 tab 而非按文件分桶是有意的——同一文件的两个 tab 各自滚动。face（`loadPage`、`reloadPages`）是唯一的异步半边：它标记读取进行中，等待 Remote 结果，再经 store 的 action 写入一页或一次失败；若 owner 的 `signal` 已触发则什么也不写。`signal` 同时终结这个桶：face 在 tab 首次读取时挂一个 abort 监听器，由它忘掉桶——不是体，体随 tab 切换反复挂载卸载；从未读过的 tab 没有桶也没有监听器，而 tab 记录可能在其体被另一 tab 挡住而卸载时结束。因此滚动位置、换行与已答过的导航都活得比体久：tab 回来时停在读者离开的地方，而不是重读或再跳一次。刷新页面后什么都不保留。
+
+导航是一个 `line`。`read` 工具行把它 1 起的 `offset` 以 `openResource(address, { params: { line } })` 传来，产物 chip 什么都不传；体把 `navigation.params` 收窄为 `SidebarRightResourceParamsMap['file']`（`{ line?: number }`，由 `file` 类型的拥有者声明），不做运行时校验，因为调用方与体相遇在同进程的类型化边界上。已加载的页够不到该行时，体读下一页，再读，直到覆盖它或文件结束——页按顺序加载，没有 seek——然后把该行滚到体顶部并高亮，每个 `navigation.revision` 一次。store 记下已答过的 revision，于是同一 revision 下重新挂载的体恢复滚动位置而不再跳；对同一文件再次 `openResource`（聚焦而非复制）以新 revision 到来并再跳一次。超出文件末尾的行在 `eof` 处静默停下；补页途中失败的页终止补页并显示失败行。
+
+文件变了只提示，不应用。当 `file` 资源报告 `changed`——agent 在上次 `stat` 之后经工具写了该文件——路径行上方出现一条提示 `文件已被修改，显示的还是旧内容。` / `The file has changed; this is the older text.`，带一个 `重新载入` / `Reload` 按钮。只有点击才同时做两件事：`meta.reload()`（重新 `stat`，清掉 `changed`）与 `reloadPages`（丢掉所有页，重读第 1 页）。滚动位置保留，读者停在原处。没有别的东西触发重载：树和预览都不监听文件系统，外部编辑不会被提示。资源变为 `failed`——文件被删，或 Host 拒绝——时，同一位置出现一条失败条，句子来自 `failure-line.ts`，带同一个重新载入按钮，并优先于尚未处理的 `changed`；已读的页留在它下方。
+
+体的头部是一行：左边是地址所命名的文件路径（12px、三级色、单行、溢出省略号、悬停显示完整路径），右端是两个 24px 控件——换行开关（`自动换行` / `Wrap lines`，显示按下态，**默认开**、按 tab 记：长行折行、绝不横向滚动，直到读者关掉它，此后文件体自己横向滚动）与一个重新读取按钮（`重新读取文件` / `Read the file again`），做的恰是变更提示条按钮做的事。两个控件都永不禁用。预览占满 pane 体的全部高度（对 pane 体取 `height: 100%`；pane 体是高度确定的块级滚动容器），于是短文件下方不留另一块样式不同的空白，而文件体——等宽、13px、行高 1.6、上下 10px 内边距——是唯一的滚动者：长文件在头部与变更提示条之下滚动，二者不动。
+
+某页失败时，已显示的页保留，并在已加载文本末尾加一句以文件而非传输为主语的说明，带一个重读同一页的 `重试` / `Retry` 按钮：`workspace-file/not-found` `这个文件不在了。可能已被移动或删除。` / `That file is gone. It may have been moved or deleted.`；`workspace-file/outside-workspace` `这个文件在工作区之外，侧栏不会读取它。` / `That file is outside the workspace, so the sidebar will not read it.`；`workspace-file/too-large` `这一页太大，侧栏不读取超过 {limit} 的页。` / `That page is too large; the sidebar does not read pages above {limit}.`，字节上限渲染为 `2 MB` 这样的形式；`workspace-file/not-text` `这不是文本文件，没法在这里查看。` / `That is not a text file, so it cannot be shown here.`；`workspace-file/not-regular-file` `这不是一个普通文件，没有可显示的文本。` / `That is not a regular file, so it has no text to show.`；其余任何失败，无论载体层还是未分类，`读取失败：{message}` / `Read failed: {message}` 并带上失败自身的消息。映射住在 `failure-line.ts` 里，与组件分开以便单独测试；读者未命名的错误码落到带传输层消息的通用句。目录或二进制文件因此只显示一行失败说明；空文件显示头部与一个空的体，没有任何标记。
+
+### 文件树
+
+`files` 是页类型，不是查看器：它不认领任何地址。注册定义是 `{ kind: 'files', id: '@deepseek-ai/dsh-client-ui-sidebar-files', priority: 'builtin', title, guide: [{ order: 10, title, description, icon: IconFolderClose16 }] }`——没有 `patterns`，因为没有谁按地址导航*到*一棵文件树；引导页的入口框打开的是类型本身。`id` 是这个实现在 Tab 系统里的唯一键，同时也是体坑位 `sidebar.right.pane.tab` 的 `key`，于是同一个串既命名类型也命名画它的组件。`register()` 返回 disposer 并经 `ctx.effect` 注册，与所有注册一致。
+
+根是 Host 在会话列表里上报的会话工作目录（`useSessions().byId[sessionId].cwd`），标签由 `dsh-util-workspace-path` 的 `workspaceTitleOf` 给出——路径最后一个非空段——路径只有分隔符时用根串本身作标签。没有工作目录的会话只显示一行（`noWorkspace`），不发请求。没有根选择器，也不能往上浏览：Host 的 `list` 拒绝会话工作区根之外的路径，所以客户端能列的那一个目录就是它显示的目录。
+
+树不是一个资源，这决定了它的状态住在哪。逐层懒加载的目录列表是类型自己拥有的视图状态，所以它住在 Slot 标准的独占 store（每会话一实例）里、按 tab id 分桶：`{ root, levels, expanded }`，`levels` 以绝对路径为键取 `loading | ready | failed`，`expanded` 是当前展开的绝对路径集合，含根。资源有一个地址和一个当前值；一棵为每个展开层钉一个资源的树，会让资源模型背上「读者展开了哪些目录」，而那是类型的事。`useResource` 留给只有一个地址的内容。
+
+face 是树唯一的异步半边。`start(tabId, root, signal)` 以根展开态播种桶并列出根；`toggle(tabId, path, loaded, signal)` 翻转展开集合并只在第一次列出该层；`load(tabId, path, signal)` 标 `loading`，调 `remote.workspaceFiles.list(sessionId, absolutePath, signal)`，写 `ready` 或 `failed`。适配层保留列表的 `entries` 与 `truncated`、丢弃其工作区相对 `path`：树里每个键都是绝对路径，子键 = 父路径以 `/` 拼上条目名。折叠保留该层，再展开直接从内存画不再请求；失败的层同样保留、再展开不重试——重试靠重新读取。owner 的 `signal` 终结一个桶：abort 时忘掉该 tab，其后才结算的列表什么也不写，已挂载的体也不会给 signal 已触发的桶重新播种。
+
+行序是读者的序，不是端点的序：目录在前，文件与其他条目在后，组内按 `Intl.Collator(undefined, { numeric: true, sensitivity: 'base' })`，于是 `file2` 排在 `file10` 前、大小写不拆开列表。dotfiles 与其他名字一样显示；Host 返回的东西树一个不过滤。三种条目类型画法不同：`directory` 是带 `aria-expanded` 的按钮、开/闭文件夹图标，子层每级缩进 14px；`file` 是带文档图标的按钮，没有大小列；`other`（符号链接、套接字、设备）是灰色、不可聚焦的 span，带 `aria-disabled` 与「不能打开」的提示，这样目录被完整报告，又不提供一个注定失败的点击。被 Host 按 `maxEntries` 上限截断的层在条目末尾以 `truncated` 标记收尾；空层显示 `empty`；进行中的列表在其目录下显示 `loading`。
+
+点文件即 `tabActions.openResource(fileAddressFor(sessionId, root, absolutePath))`：条目在树根之下的绝对路径成为每段百分号编码的 `dsh-resource://file/session/<sessionId>/<相对根的路径>` 地址。树从不指名查看器：由注册表的认领决定谁画这个地址（今天是 `fallback` 档的 `text`），一个在其上认领 `dsh-resource://file/**` 的扩展接走点击而树无需改动。打开落在点击时文件树 tab 所在的那个 pane，同地址已开着的 tab 被聚焦而不复制——两者都是导航控制器的缺省。用户明确拍过：从树里打开的文件不强制分格；它在树所在处开一个新 tab。
+
+重新读取是树唯一的控件，是根标题行右端的图标按钮（`reload`）。它重置所有层，并恰好重新列出 `expanded` 里的那些路径；曾列出后又折叠的层被丢弃，下次展开时重新拉取。控件住在体内，因为类型的控件属于它的体：pane 的 tab 条只承载布局库与面板自身的动作，不存在按类型的工具坑位。树不监听文件系统；一层只在重新读取或首次展开时变化，`changes` 流是文本查看器的事。
+
+文案是 `sidebarFiles` 命名空间，十三个键。行状态：`loading`「正在读取…」/ "Reading…"，`empty`「空目录」/ "Empty directory"，`truncated`「条目太多，只显示了一部分。」/ "Too many entries; showing only some of them."，`noWorkspace`「这个会话没有工作区目录。」/ "This session has no workspace directory."，`entry.other`「这不是文件或目录，没法打开。」/ "Not a file or a directory, so it cannot be opened."，`reload`「重新读取」/ "Reload"。失败行按 Host 错误码一码一句、以目录为主语：`workspace-file/not-found`「这个目录不在了。可能已被移动或删除。」/ "That directory is gone. It may have been moved or deleted."，`workspace-file/outside-workspace`「这个目录在工作区之外，侧栏不会读取它。」/ "That directory is outside the workspace, so the sidebar will not read it."，`workspace-file/not-directory`「这不是一个目录。」/ "That is not a directory."；其余任何失败，无论载体层还是未分类，显示 `error.unavailable`「读取失败：{message}」/ "Read failed: {message}" 并带上失败自身的消息，因为树对传输级错误没有什么有用的可补充。
+
+## Alternatives considered
+
+**给活跃 tab 的控件开一个按 pane 的工具坑位（`sidebar.right.pane.tab.tools`）。** 为文本预览的换行与重新读取、文件树的重新读取交付过一轮评审，随后按用户意见删除：它把类型私有的按钮放到面板 tab 条上、分栏与折叠控件旁边，读起来像面板自身的 chrome。类型的控件属于它自己的体；预览的在其路径行右端，树的在其根行右端。
+
+**保留 `Show in folder`。** 目录在 Sidebar 里没有去处，而产品决定是不给桌面打开器留次级入口。已删除，能力损失如实陈述：`openFile('.')` 命名的是目录，文本预览以 `not-regular-file` 拒绝它，于是该行什么都不提供，而不是给一个注定失败的按钮。
+
+**把内容放进资源流。** 内容可以任意大，所以 `file` 资源只携带元数据（`version`、`bytes`、`changed`），预览经 `workspaceFiles.read` 按页读内容；`changed` 是通知，不是载荷。
+
+**重新载入重取所有已加载过的页。** 相对于已交付规则（丢掉所有页、重读第 1 页）的另一条路。未采纳：重取已加载范围意味着显示任何东西之前要先做多次顺序读取，而 agent 编辑之后的已加载范围也不再描述同样的行；读者保留滚动位置，在已加载文本末尾继续要更多。先前视口在文件深处时读者的位置可能落到空白，这一点在 Consequences 里如实陈述。
+
+**文件变了就在读者眼前刷新文本。** 否决：在读者眼前重载会丢掉他的位置，而 agent 正在写的文件会反复变化。提示条等点击。
+
+**整文件读取，或可 seek 的页。** 整文件读取没有上界；可 seek 的页需要 Host 不维护的行索引。页从第 1 页起按顺序加载，导航到深处某行时逐页补到覆盖为止——代价在 Consequences 里陈述，seek 推迟。
+
+**在运行时校验 `line`。** 第一版接受 `unknown` 参数，非正整数一律视为没有请求。`params` 类型化之后否决：`file` 类型的拥有者在 `SidebarRightResourceParamsMap` 中声明 `{ line?: number }`，调用方与体相遇在同进程的类型化边界上，仓规是那里不加运行时校验。
+
+**每种地址都从坑位取读取的会话。** 第一版在体被挂载的会话下读取。只对不命名会话的 `absolute` 作用域保留：`session` 地址带着自己的会话，正是为了让同一相对路径在两个会话里是两个文件。
+
+**换行默认关。** 第一版。用户评审后反转：预览列很窄，长行横向滚动会把文字藏起来；换行默认开直到读者关掉，按 tab 记。
+
+**靠改布局库的 `.paneBody` 来撑满 pane。** pane 体是高度确定的块级滚动容器，不是 flex 容器，所以预览的 `flex: 1` 不起作用，pane 体滚动着一个 30,000px 高的预览。否决，改为在预览根上取 `height: 100%`：修复属于类型自己，布局库对其体保持无知，文件体成为唯一的滚动者，于是头部不动、跳行滚动的也是正确的元素。
+
+**store 按文件而非按 tab 分键。** 否决：同一文件的两个 tab 是两个阅读位置；页可以共享而视图不能，省下的只是一次页读取。
+
+**包内自造 `file:///` 地址，以及包内自写 basename 作树的根标签。** 否决：文件地址必须带自己的作用域——以其根解析相对路径的会话，或绝对路径本身——因此用共享的 `fileAddressFor`；一个 `workspaceTitleOf` 服务所有工作区标签面。
+
+**把整棵树建模为一个资源。** 否决：资源有一个地址和一个当前值，一棵为每个展开层钉一个资源的树，会让资源模型背上「读者展开了哪些目录」，而那是类型的事。
+
+**引导页作为链上的入口而非链的 fallback。** 否决：随包交付的引导页若是一个入口，产品的替换者与它会同为候选，胜者取决于注册顺序；作为 fallback 则永远恰有一个体，且不可能被意外投掉。
+
+**引导页在自己旁边打开被选的类型。** 否决：引导页是一扇门，一个同时持有引导页与它所打开内容的 pane 会显示一扇不再通向别处的门；`openTab(kind, { replaceTab: true })` 把 tab 交出去。
+
+## Consequences
+
+- `ui-sidebar-right` 之外写的类型有了一份完整样板：`ui-sidebar-textpreview` 演示一个查看器——由地址推出的读取、按 tab 分桶的独占 Slot store、inject face、类型化的导航参数与体内自有控件；`ui-sidebar-files` 演示一个带引导入口、懒填充 store 的页类型；引导页演示一个链 fallback。
+- 按页读取让每次请求都有界（`maxLines` 行、`maxBytes` 字节），代价是一个 **加载更多** 控件、没有总行数，以及到深处某行的顺序补页；导航到一个大文件的第 40,000 行要先读八页。
+- 只提示不应用，让读者在 agent 反复写入期间保住位置，代价是点击之前显示的是旧文本；外部编辑永不提示。
+- 重新载入只读第 1 页，所以身在文件深处的读者重载后回到文件开头再往后翻；滚动位置保留但可能指向已加载文本之外。
+- 按 tab 的视图状态跨 tab 切换与重新挂载存活，随 tab 或页面一起消失；什么都不持久化。
+- 文件树渲染 Host 列出的一切，因此大目录最多显示 `maxEntries` 行加一个标记，没有搜索或过滤，读者靠逐层展开找到深处的文件。
+- 三个类型面向用户的每条文案都由 locale 持有并列在本文中，文案评审只需读一处。
+
+## Testing
+
+文本预览的 `tests/` 覆盖：注册表认领与让位（经真实的 `SidebarRightTabRegistry`）、地址翻译（`sessionFileOf` 接受 `session` 作用域、其他一律抛错）、store 的页、版本、reset、视图与 forget 各 action、face 的进行中、失败、abort 与重载路径、页算术（`linesOf`、`offsetsOf`、`lastLineLoaded`）、体的首读、加载更多、重试、变更提示条、导航补页、只跳一次、重新挂载、换行默认与切换、头部控件与 abort 即忘、失败行映射，以及插件的各项注册与 dispose 时的撤销。针对已构建应用的 Chromium 探针记录了撑满与滚动的数字（`.artifacts/sidebar-tab-types/app-probe.log`，`ROUND3`）：短文件的预览高度等于 pane 体内容区高度，长文件在预览体内滚动，pane 体从不滚动。文件树的 `tests/` 覆盖排序、懒加载、折叠记忆、重新读取、三种条目类型、截断与失败行，以及 abort 即忘。`apps/web/tests/sidebar-right.e2e.ts` 经真实 Remote 载体把会话里的产物文件打开进预览。
+
+## Deferred
+
+- 虚拟化或可 seek 的分页加载（页按顺序加载）、恢复已加载范围的重新载入、节流的滚动位置持久化，以及 `ui-primitives` 里的换行图标。
+- 文本预览的行号、语法高亮、Markdown 渲染、图片与搜索；总行数或文件末尾标记。
+- 文件树的搜索、产物过滤、拖拽、重命名、右键菜单、高亮当前文件、文件系统监听，以及浏览到工作区根之上。
+- 引导页文案的产品评审，以及一个类型贡献多个入口时引导页的行为。
+- `ui-sidebar-textpreview` 与 `ui-sidebar-files` 的中文 README 对照。
+
+## Related
+
+- [右侧 Sidebar 停靠基础设施](2026-09-04-right-sidebar-docking-infrastructure.zh.md)——面板、pane 与引导页每 pane 一个的规则。
+- [Sidebar tab 类型与导航](../architecture/2026-09-05-sidebar-tab-types-and-navigation.zh.md)——这些类型消费的注册表、档位、`id`、`openTab` / `openResource` 与 owner props。
+- [Client 资源模型](../architecture/2026-09-05-client-resource-model.zh.md)——`useResource` 与 `file` 协议的元数据。
+- [Workspace Files 服务](../architecture/2026-09-05-workspace-files-service.zh.md)——地址语法、`stat` / `read` / `list` / `changes`，以及失败行所映射的错误码。
diff --git a/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.i18n.yaml b/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.i18n.yaml
new file mode 100644
index 0000000000..3fae385422
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.md
+2026-09-07-composer-session-stats-pills.md: 818c3c156f72816eb6540d505782be8e03dc6aa0
+2026-09-07-composer-session-stats-pills.zh.md: 8a74cddd3176026d799fb5b4223a51371ee8e253
diff --git a/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.md b/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.md
new file mode 100644
index 0000000000..818c3c156f
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.md
@@ -0,0 +1,31 @@
+# Agent Note: Composer session stats — two icon pills with click-open stat dialogs
+
+Status: implemented
+
+English | [中文](2026-09-07-composer-session-stats-pills.zh.md)
+
+## Problem
+
+The session stats strip under the composer (`StatsLine`, ui-chat, mounted on `conversation.composer.dock`) rendered every figure as one resident text line: turn/step counts, LLM and tool wall times, TTFT/TPS averages, and compact token totals with cache-hit share. The line crowded as figures accumulated, exact token counts appeared nowhere (the `ResizeObserver`-measured hover tooltip only restated the same compact line when it truncated), and the flat text gave no grouping — time figures and billing figures read as one undifferentiated row. An in-page A/B against a two-pill variant settled the direction: the pills won on scannability and on giving each figure family a home.
+
+## Decision
+
+`StatsPills` (packages/client/ui-chat/src/client/chat/StatsPills.tsx) replaces `StatsLine` on the same `conversation.composer.dock` slot; the losing variant is deleted, its shared helpers (`deriveStats`, `formatDuration`, `cacheHitPercent`, `billedInputTokens`) absorbed into the new module, and the dead `stats.llm`, `stats.toolCall`, `stats.ttftAverage`, `stats.tokensPerSecond`, and `stats.tokens` locale keys removed.
+
+- **Two icon pills, two dialogs.** A gauge pill (new `IconGaugeOutline16`, dial center optically dropped to y=8.75 because the bottom-open arc reads high) shows `{turns} 轮 {steps} 步` plus output TPS and click-opens the 会话统计 dialog (LLM time, tool time, average TTFT, TPS); a log with no timed figure would open an empty dialog, so that pill renders as a static reading instead of a button. A database pill (`IconDatabaseOutline16`) shows the compact billed total plus cache-hit share and click-opens the Token 用量 dialog (cache hit, uncached input, cache read, cache write, output — exact counts). Both dialogs wear the shared `stat-dialog` module (portal panel, anchored placement, outside-dismiss, optionally externally owned open state) extracted for exactly this two-consumer split; the pills row owns one exclusive open slot, so opening either dialog closes the other, and each button carries an explicit `aria-label` that separates with ` · ` the segments the aria-hidden sep glyph joins visually.
+- **Data sourcing is unchanged in architecture.** Counts and times prefer the durable `sessionStats` projection with the window fold as the assembly-without-the-unit fallback ([whole-session counts](../../archived/bug-fix/2026-08-12-full-session-turn-step-counts.md)); token figures ride `tokenUsage` only, so an absent projection drops the usage pill rather than showing window-derived billing. Cache writes stay in the billed total and the cache-hit denominator ([projection decision](../architecture/2026-07-29-projected-token-usage-and-request-context.md)). Context occupancy stays on the composer's ContextMeter ring, where it already lived beside `StatsLine` — the strip never carried it.
+- **Render discipline.** The row folds settled nodes only (`chat.legacy.nodes` identity), so streaming chunk frames cause zero rerenders — pinned by a render-count unit test. A session with no closed step and no billed tokens renders nothing.
+- **`data-composer-stats` is a cross-package attribute contract.** The pills' root carries it; ui-conversation's `InputBar.module.css` `:has([data-composer-stats])` rule tightens the composer's bottom clearance to 4px when the row is mounted. The producer side pins the attribute in unit tests, following the `data-trigger-menu` precedent.
+
+## Alternatives considered
+
+- **The single-line variant (StatsLine, the A/B loser).** All figures resident in one text row, with a hover tooltip restating the full line when it truncated. Lost on crowding and reach: exact token counts appeared nowhere (the line and its tooltip both carried compact totals only), and one row gave time and billing figures no visual grouping.
+- **Three resident groups with one shared dialog.** An intermediate iteration kept counts, time, and tokens as three inline groups. Two pills won because the time/usage split matches the two underlying projections one-to-one and each pill's icon telegraphs its dialog.
+- **Extracting the dl bucket rows shared with `TurnUsagePanel`.** The session-total dialog and the per-turn panel render the same skin but different contracts (all buckets always present vs optional per-turn fields plus model routes); a shared component would be conditionals around nine lines. The mirror is marked `jscpd:ignore` with the reason inline.
+
+## Consequences
+
+- `ChatSnapshotBuilder`'s legacy slice now serves StatsPills; the [node-assembly note](../architecture/2026-08-09-client-conversation-node-assembly.md) tracks that consumer rename.
+- Exact token counts become reachable at all — one click — where `StatsLine` showed only compact totals; the strip itself carries only the two headline readings.
+- Web e2e strip assertions match substring text inside the time pill; the fresh-round-trip aria goldens pin the two-pill structure, and stats-paged-history pins the counts reading alone over a log with no billed tokens.
+- The `conversation.composer.dock` occupant in the generated slot catalog is `client-ui-chat StatsPills id 'stats'`.
diff --git a/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.zh.md b/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.zh.md
new file mode 100644
index 0000000000..8a74cddd31
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.zh.md
@@ -0,0 +1,31 @@
+# Agent Note: 输入框下的会话统计 —— 双图标 pill 与点击展开的统计弹层
+
+Status: implemented
+
+[English](2026-09-07-composer-session-stats-pills.md) | 中文
+
+## 问题
+
+输入框下方的会话统计条（`StatsLine`，ui-chat，挂载于 `conversation.composer.dock`）把所有数字渲染成一整行常驻文本：轮/步计数、模型与工具用时、TTFT/TPS 均值、紧凑 token 总量与缓存命中率。数字越多行越拥挤，精确 token 计数无处可看（带 `ResizeObserver` 溢出测量的悬停提示只在截断时复述同一行紧凑文本），纯文本也没有分组——时间类数字和计费类数字读起来混作一行。一次页面内 A/B 对比双 pill 变体后方向定案：pill 方案在可扫读性和"每类数字有归属"上胜出。
+
+## 决定
+
+`StatsPills`（packages/client/ui-chat/src/client/chat/StatsPills.tsx）在同一 `conversation.composer.dock` 插槽上取代 `StatsLine`；落选变体已删除，其共享工具函数（`deriveStats`、`formatDuration`、`cacheHitPercent`、`billedInputTokens`）并入新模块，废弃的 `stats.llm`、`stats.toolCall`、`stats.ttftAverage`、`stats.tokensPerSecond`、`stats.tokens` 文案键一并移除。
+
+- **两个图标 pill、两个弹层。** 仪表盘 pill（新增 `IconGaugeOutline16`，因下开口圆弧视觉偏高而把表盘中心光学下移到 y=8.75）展示 `{turns} 轮 {steps} 步` 加输出 TPS，点击打开「会话统计」弹层（模型用时、工具调用用时、首 token 平均、输出速度）；日志里没有任何计时数字时弹层会是空的，此时该 pill 渲染为静态读数而非按钮。数据库 pill（`IconDatabaseOutline16`）展示紧凑计费总量加缓存命中率，点击打开「Token 用量」弹层（缓存命中、未缓存输入、缓存读取、缓存写入、输出——精确计数）。两个弹层共用为这两处消费者抽出的 `stat-dialog` 模块（portal 面板、锚定定位、点击外部关闭、可选的外部持有开合状态）；pill 行持有唯一的互斥开合槽位，打开任一弹层即关闭另一个，且每个按钮携带显式 `aria-label`，用 ` · ` 分隔 aria-hidden 分隔符在视觉上连接的两段文本。
+- **数据来源架构不变。** 计数与用时优先读取持久的 `sessionStats` 投影，窗口折叠仅作无该单元装配时的回退（[全会话计数](../../archived/bug-fix/2026-08-12-full-session-turn-step-counts.md)）；token 数字只走 `tokenUsage`，投影缺席时直接不渲染用量 pill，而非展示窗口推算的计费。缓存写入仍计入计费总量与缓存命中分母（[投影决定](../architecture/2026-07-29-projected-token-usage-and-request-context.zh.md)）。上下文占用仍在输入框旁的 ContextMeter 圆环上，`StatsLine` 时代它就在那里——统计条从未承载过它。
+- **渲染纪律。** 该行只折叠已定稿节点（`chat.legacy.nodes` 身份），流式 chunk 帧零重渲染——由渲染计数单测钉住。无已完成步且无计费 token 的会话什么都不渲染。
+- **`data-composer-stats` 是跨包属性契约。** pill 行根元素携带它；ui-conversation 的 `InputBar.module.css` 用 `:has([data-composer-stats])` 在该行挂载时把输入框底部留白收紧到 4px。生产方在单测里钉住该属性，沿用 `data-trigger-menu` 先例。
+
+## 备选方案
+
+- **单行变体（StatsLine，A/B 落选方）。** 全部数字常驻一行文本，悬停提示只在截断时复述整行。败在拥挤与可达性：精确 token 计数无处可看（行内和提示里都只有紧凑总量），单行也无法给时间与计费数字分组。
+- **三个常驻分组共享一个弹层。** 中间迭代曾把计数、时间、token 保持为三个内联分组。双 pill 胜出是因为时间/用量的切分与两个底层投影一一对应，且每个 pill 的图标直接预告其弹层内容。
+- **抽出与 `TurnUsagePanel` 共享的 dl 分桶行。** 会话总量弹层与逐轮面板皮肤相同但契约不同（此处所有分桶恒在；逐轮字段可选且含模型路由）；共享组件只是给九行代码包一层条件。该镜像以 `jscpd:ignore` 标注并内联说明理由。
+
+## 后果
+
+- `ChatSnapshotBuilder` 的 legacy 切片现在服务于 StatsPills；[节点装配 note](../architecture/2026-08-09-client-conversation-node-assembly.zh.md) 已跟进该消费者更名。
+- 精确 token 计数第一次变得可达——一次点击即可；`StatsLine` 只展示过紧凑总量。统计条本身只承载两个头条读数。
+- Web e2e 对统计条的断言匹配时间 pill 内的子串文本；fresh-round-trip 的 aria golden 钉住双 pill 结构，stats-paged-history 则在无计费 token 的日志上钉住单独的计数读数。
+- 生成的插槽目录中 `conversation.composer.dock` 占用者为 `client-ui-chat StatsPills id 'stats'`。
diff --git a/.agents/notes/implemented/process/2026-09-08-playwright-video-gif.i18n.yaml b/.agents/notes/implemented/process/2026-09-08-playwright-video-gif.i18n.yaml
new file mode 100644
index 0000000000..bdf8870e5f
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-09-08-playwright-video-gif.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-09-08-playwright-video-gif.md
+2026-09-08-playwright-video-gif.md: 44db04814900d4813f1d39521e4e84e7d0b8d1b8
+2026-09-08-playwright-video-gif.zh.md: 4922d739f0ff760afe12fe1a624abc1d1c4cd81f
diff --git a/.agents/notes/implemented/process/2026-09-08-playwright-video-gif.md b/.agents/notes/implemented/process/2026-09-08-playwright-video-gif.md
new file mode 100644
index 0000000000..44db048149
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-09-08-playwright-video-gif.md
@@ -0,0 +1,29 @@
+# Agent Note: Playwright video captures continuous browser demos
+
+Status: implemented
+
+English | [中文](2026-09-08-playwright-video-gif.zh.md)
+
+## Problem
+
+A screenshot storyboard omits intermediate animation frames and can miss short-lived progress indicators. Increasing the encoded GIF frame rate cannot recover motion absent from its source images. Continuous capture supplies those frames while the available browser-control workflow handles interaction.
+
+## Decision
+
+The [recording skill](../../../skills/record-browser-gif/SKILL.md) keeps the available browser-control workflow preferred. When that workflow exposes `recordVideo`, video captures intermediate frames in the same controlled context; otherwise the workflow captures screenshots. Standalone repository-declared Playwright remains the fallback when browser control is unavailable. For video, viewport and recording dimensions match explicitly, avoiding Playwright's default scaling to fit 800×800. The recorder retains the page video, awaits context closure, and saves the completed WebM before encoding.
+
+One encoder accepts either a video file or a screenshot directory. Video input selects one continuous interval, applies a declared playback multiplier, and extends its final frame. The JSON summary records source duration, selected interval, speed, final hold, and encoded dimensions, duration, frame count, and size. Mode-inappropriate options and invalid intervals fail. The original video remains available for review; trimming and speed never establish model response latency.
+
+The [evidence-chain decision](2026-08-08-browser-gif-evidence-chain.md) owns browser-control selection, isolated application state, real model execution, exact commit attribution, and verified publication. Video adds a higher-cadence capture option within those rules. Failed recordings cannot contribute frames to a successful run.
+
+## Alternatives considered
+
+**Increase only the encoded frame rate.** Repeating sparse screenshots does not capture additional motion. Screenshots remain useful for explicit state holds, requested storyboards, and browser workflows without video support.
+
+**Install a separate recorder or capture the desktop.** The repository already declares Playwright. Another driver adds setup and version management; desktop capture can include unrelated windows and personal state.
+
+## Consequences
+
+Continuous recording preserves intermediate states, so reviewers must inspect the selected interval for sensitive content and readability. Raw video consumes additional scratch storage, and encoding may require trimming or scaling to meet the byte limit. Context closure is part of successful recording, not optional cleanup.
+
+The encoder's local Python unittest suite invokes real ffmpeg and ffprobe to check timing, palette order, screenshot holds, rejected options, overwrite protection, and size limits. It requires the skill's media prerequisites and is run explicitly; repository CI does not provision these media binaries. Product demonstrations additionally exercise the pull request's built server and real model flow.
diff --git a/.agents/notes/implemented/process/2026-09-08-playwright-video-gif.zh.md b/.agents/notes/implemented/process/2026-09-08-playwright-video-gif.zh.md
new file mode 100644
index 0000000000..4922d739f0
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-09-08-playwright-video-gif.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: Playwright 视频录制连续浏览器演示
+
+Status: implemented
+
+[English](2026-09-08-playwright-video-gif.md) | 中文
+
+## 问题
+
+截图分镜省略了动画的中间帧，也可能遗漏短暂的进度指示。提高 GIF 编码帧率无法补回源图片未记录的运动。连续录制提供这些画面，同时由可用的浏览器控制工作流负责交互。
+
+## 决策
+
+[录制 skill](../../../skills/record-browser-gif/SKILL.md) 继续优先使用可用的浏览器控制工作流。该工作流提供 `recordVideo` 时，在同一受控上下文中用视频捕获中间帧；否则由该工作流截图。只有浏览器控制不可用时，才使用仓库已声明的独立 Playwright 作为备用方案。录制视频时，显式设置相同的 viewport 与录制尺寸，避免 Playwright 默认缩放到 800×800 以内。录制程序保留页面视频对象，等待上下文关闭，再保存完整 WebM 并编码。
+
+同一编码器接受视频文件或截图目录。视频输入选择一个连续区间，应用明确标注的播放倍率，并延长末帧。JSON 摘要记录源视频时长、所选区间、倍率、末帧停留时间，以及编码后的尺寸、时长、帧数和大小。与输入模式不符的选项及无效区间会失败。保留原视频供检查；裁剪与变速不能证明模型响应延迟。
+
+[证据链决策](2026-08-08-browser-gif-evidence-chain.zh.md)规定浏览器控制方式选择、应用状态隔离、真实模型执行、准确提交归属及发布验证。视频在这些规则内增加更高采样帧率的录制选项。失败录制的画面不得用于成功运行。
+
+## 曾考虑的替代方案
+
+**只提高编码帧率。**重复少量截图不能捕获更多运动。截图仍适合明确的状态停留、用户要求的分镜，以及不支持视频的浏览器工作流。
+
+**安装独立录制器或录制桌面。**仓库已经声明 Playwright。另一套驱动增加安装与版本管理成本；桌面录制可能包含无关窗口和个人状态。
+
+## 后果
+
+连续录制保留中间状态，因此检查者必须查看所选区间是否包含敏感内容，以及画面是否易读。原始视频占用额外临时空间，编码时可能需要裁剪或缩放以满足字节上限。关闭上下文是成功录制的一部分，不是可选清理。
+
+编码器的本地 Python unittest 测试调用真实 ffmpeg 和 ffprobe，检查时序、调色板顺序、截图停留、选项拒绝、覆盖保护和大小限制。测试依赖 skill 要求的媒体工具，需显式运行；仓库 CI 不预装这些媒体程序。产品演示还会执行 PR 构建后的服务器与真实模型流程。
diff --git a/.agents/notes/implemented/process/2026-09-08-trusted-changed-file-review-routing.i18n.yaml b/.agents/notes/implemented/process/2026-09-08-trusted-changed-file-review-routing.i18n.yaml
new file mode 100644
index 0000000000..6c9579402e
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-09-08-trusted-changed-file-review-routing.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-09-08-trusted-changed-file-review-routing.md
+2026-09-08-trusted-changed-file-review-routing.md: 246c223d976e312e5712d7baa150bd3e84f1363e
+2026-09-08-trusted-changed-file-review-routing.zh.md: 397d4174340fc9c6002419b21436b5c33542f7e4
diff --git a/.agents/notes/implemented/process/2026-09-08-trusted-changed-file-review-routing.md b/.agents/notes/implemented/process/2026-09-08-trusted-changed-file-review-routing.md
new file mode 100644
index 0000000000..246c223d97
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-09-08-trusted-changed-file-review-routing.md
@@ -0,0 +1,47 @@
+# Agent Note: Route reviews from trusted changed-file policy
+
+Status: implemented
+
+English | [中文](2026-09-08-trusted-changed-file-review-routing.zh.md)
+
+## Problem
+
+GitHub's native CODEOWNERS behavior requests reviewers whenever a matching path changes. It cannot apply this repository's distinction between reviewable implementation or documentation files and test-only evidence. A native CODEOWNERS file also makes GitHub, rather than an inspected repository program, responsible for the request decision.
+
+Review routing needs an observable changed-file input, explicit owner rules, complete test exclusions, and a write-capable workflow that remains safe for pull requests from forks.
+
+## Decision
+
+The repository keeps a CODEOWNERS-compatible map at [`.github/review-ownership/CODEOWNERS`](../../../../.github/review-ownership/CODEOWNERS), outside GitHub's native CODEOWNERS locations. The map accepts only explicit absolute directory patterns and individual GitHub users. It rejects wildcards, hidden-directory patterns, teams, duplicate patterns, and duplicate owners. Later matching patterns replace earlier matches.
+
+The policy test counts non-test tracked lines in directories that match an ownership rule. It rejects a map in which `@turtle1999` owns more than one third of that eligible owned codebase.
+
+The [`request-review` workflow](../../../../.github/workflows/request-review.yml) runs on non-draft `pull_request_target` events for opened, synchronized, reopened, and ready-for-review pull requests. Its write-capable job checks out the default branch and executes only the default branch's scanner and ownership map. It does not check out pull-request code or read repository secrets.
+
+The scanner fetches every changed-file record before deciding. It fails if the pull request reports more than GitHub's 3,000-file API limit or if pagination returns an incomplete list. It normalizes repository paths, evaluates old and new paths of a rename independently, and escapes filenames before logging them.
+
+The scanner excludes test-only paths before owner matching. Excluded paths comprise directories named `test`, `tests`, `__tests__`, `__snapshots__`, `benches`, or `stress-tests`; the top-level `benchmarks` and `snapshots` trees; `packages/test-support`; `scripts/fixtures` and `scripts/snapshots`; filenames ending in `.bench.<ext>`, `.corpus.<ext>`, `.e2e.<ext>`, `.perf.<ext>`, `.snapshot.<ext>`, `.spec.<ext>`, `.stress.<ext>`, or `.test.<ext>`; and Python `test_*.py`, `*_test.py`, or `*_tests.py` files. Test infrastructure such as `vitest*.config.ts` and gate implementations remains reviewable because it changes how repository evidence is produced.
+
+The workflow prints the changed non-test paths, excluded test paths, per-file owner matches, and final reviewer list before any review-request mutation. It requests the union of matched individual owners after removing the pull-request author and users who are already requested. A test-only or wholly unmatched change requests nobody.
+
+## Verification
+
+[Scanner tests](../../../../.github/review-ownership/request-review.test.mjs) cover admitted ownership syntax, rejected syntax, each test convention, production-name negative controls, renames, last-match behavior, unmatched files, complete pagination, the 3,000-file limit, log-before-request ordering, author and existing-reviewer filtering, test-only changes, drafts, and API failures. [Workflow tests](../../../../scripts/ci-workflow.spec.ts) pin the event set, least permissions, trusted default-branch checkout, absence of pull-request-head references and secrets, and executed command. The gate graph includes both suites in static CI and `check-all`.
+
+## Alternatives considered
+
+**Use native CODEOWNERS.** Native routing cannot ignore test-only changes and offers no repository-owned decision log before requesting reviewers.
+
+**Run under `pull_request` and check out the pull-request head.** A fork workflow does not receive a write-capable token, while granting a write token to code from an untrusted head is unsafe.
+
+**Execute the pull request's scanner or owner map under `pull_request_target`.** This lets an untrusted pull request choose its own write-capable behavior or owners.
+
+**Infer semantic source changes from patches or language parsers.** GitHub can truncate patches, and the repository spans TypeScript, JavaScript, Python, Rust, YAML, Markdown, and generated evidence. A cross-language semantic classifier would add ambiguous rules without providing a complete input. The scanner therefore uses the complete non-test changed-file list and does not claim to distinguish formatting, comments, or documentation-only edits inside an eligible file.
+
+## Consequences
+
+Reviewer requests are reproducible from a trusted policy and the file list printed in the workflow log. Test-only changes do not request owners. Ownership changes become effective only after merge, so the pull request that changes policy cannot apply its untrusted policy to itself.
+
+The workflow requests every matched owner rather than choosing one owner nondeterministically. Shared ownership on large directories therefore produces multiple requests. GitHub-generated review-request events may not start other workflows that depend on recursively triggered events from `GITHUB_TOKEN`; those workflows must not rely on this request as their only trigger.
+
+Any non-test change under an owned directory remains eligible, including comment-only or formatting-only edits and documentation changes. Unmatched paths are logged and request nobody. Pull requests above the API file limit fail without requesting a partial owner set.
diff --git a/.agents/notes/implemented/process/2026-09-08-trusted-changed-file-review-routing.zh.md b/.agents/notes/implemented/process/2026-09-08-trusted-changed-file-review-routing.zh.md
new file mode 100644
index 0000000000..397d417434
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-09-08-trusted-changed-file-review-routing.zh.md
@@ -0,0 +1,47 @@
+# Agent Note: 基于受信任的变更文件策略路由评审
+
+Status: implemented
+
+[English](2026-09-08-trusted-changed-file-review-routing.md) | 中文
+
+## 问题
+
+只要匹配路径发生变更，GitHub 原生 CODEOWNERS 就会请求评审者。它无法应用本仓库对需评审的实现或文档文件与纯测试证据的区分。使用原生 CODEOWNERS 文件还会让 GitHub 负责请求决策，而不是由可检查的仓库程序负责。
+
+评审路由需要可观测的变更文件输入、显式 owner 规则、完整的测试排除规则，以及对 fork PR 仍然安全且具备写权限的 workflow。
+
+## 决策
+
+仓库在 GitHub 原生 CODEOWNERS 路径之外的 [`.github/review-ownership/CODEOWNERS`](../../../../.github/review-ownership/CODEOWNERS) 中保存兼容 CODEOWNERS 格式的映射。该映射只接受显式绝对目录模式和 GitHub 个人用户。通配符、隐藏目录模式、团队、重复模式和重复 owner 都会被拒绝。靠后的匹配模式会替换靠前的匹配结果。
+
+策略测试会统计匹配所有权规则的目录中的非测试跟踪文件行数。如果 `@turtle1999` 拥有的有效代码库超过三分之一，测试就会拒绝该映射。
+
+[`request-review` workflow](../../../../.github/workflows/request-review.yml) 在非草稿 PR 的 `pull_request_target` 事件上运行，订阅创建、同步、重新打开和标记为可评审操作。具备写权限的 job 检出默认分支，只执行默认分支上的扫描器和所有权映射。它不会检出 PR 代码，也不会读取仓库 secret。
+
+扫描器在决策之前获取所有变更文件记录。如果 PR 报告的文件数超过 GitHub API 的 3,000 个文件上限，或者分页只返回了部分列表，扫描器就会失败。它会规范化仓库路径，分别检查重命名前后的路径，并在记录文件名之前进行转义。
+
+扫描器会在匹配 owner 之前排除纯测试路径。排除范围包括名为 `test`、`tests`、`__tests__`、`__snapshots__`、`benches` 或 `stress-tests` 的目录，顶层 `benchmarks` 和 `snapshots` 目录树，`packages/test-support`、`scripts/fixtures` 和 `scripts/snapshots`，以 `.bench.<ext>`、`.corpus.<ext>`、`.e2e.<ext>`、`.perf.<ext>`、`.snapshot.<ext>`、`.spec.<ext>`、`.stress.<ext>` 或 `.test.<ext>` 结尾的文件名，以及 Python 的 `test_*.py`、`*_test.py` 或 `*_tests.py` 文件。`vitest*.config.ts` 和门禁实现等测试基础设施仍需评审，因为它们会改变仓库证据的生成方式。
+
+Workflow 会在发出任何评审请求变更之前，依次打印变更的非测试路径、排除的测试路径、逐文件 owner 匹配结果和最终评审者列表。它合并匹配到的个人 owner，并排除 PR 作者和已经收到评审请求的用户。纯测试变更或全部未匹配的变更不会请求任何人。
+
+## 验证
+
+[扫描器测试](../../../../.github/review-ownership/request-review.test.mjs)覆盖允许的所有权语法、拒绝的语法、每种测试约定、生产文件名负向对照、重命名、最后匹配规则、未匹配文件、完整分页、3,000 个文件上限、先记录后请求的顺序、作者与现有评审者过滤、纯测试变更、草稿和 API 失败。[Workflow 测试](../../../../scripts/ci-workflow.spec.ts)固定事件集合、最小权限、受信任的默认分支检出、不引用 PR head 和 secret，以及执行的命令。门禁图在静态 CI 和 `check-all` 中包含这两组测试。
+
+## 考虑过的替代方案
+
+**使用原生 CODEOWNERS。** 原生路由无法忽略纯测试变更，也无法在请求评审者之前提供由仓库控制的决策日志。
+
+**在 `pull_request` 下运行并检出 PR head。** Fork workflow 无法获得具备写权限的 token，而向不受信任 head 中的代码授予写权限 token 并不安全。
+
+**在 `pull_request_target` 下执行 PR 中的扫描器或 owner 映射。** 这会让不受信任的 PR 选择自己的写权限行为或 owner。
+
+**根据补丁或语言解析器推断语义源码变更。** GitHub 可能截断补丁，而且仓库包含 TypeScript、JavaScript、Python、Rust、YAML、Markdown 和生成的证据。跨语言语义分类器会增加含义不明确的规则，却无法提供完整输入。因此，扫描器使用完整的非测试变更文件列表，并且不会声称能够区分合格文件中的纯格式、注释或仅文档编辑。
+
+## 后果
+
+评审请求可以根据受信任的策略和 workflow 日志中打印的文件列表复现。纯测试变更不会请求 owner。所有权变更只有合并后才会生效，因此修改策略的 PR 无法对自身应用其中不受信任的策略。
+
+Workflow 会请求所有匹配的 owner，不会随机选择一人。因此，大目录上的共享所有权会产生多个请求。GitHub 使用 `GITHUB_TOKEN` 生成的评审请求事件可能不会启动依赖递归触发事件的其他 workflow；这些 workflow 不得把此请求作为唯一触发条件。
+
+所有已分配目录下的非测试变更仍符合请求条件，其中包括纯注释、纯格式调整和文档变更。未匹配的路径会被记录，但不会请求任何人。超过 API 文件上限的 PR 会失败，并且不会请求不完整的 owner 集合。
diff --git a/.agents/notes/implemented/testing/2026-09-06-pr-ci-runner-temporary-storage.i18n.yaml b/.agents/notes/implemented/testing/2026-09-06-pr-ci-runner-temporary-storage.i18n.yaml
new file mode 100644
index 0000000000..dccefc4520
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-09-06-pr-ci-runner-temporary-storage.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-09-06-pr-ci-runner-temporary-storage.md
+2026-09-06-pr-ci-runner-temporary-storage.md: 59d609c08e1b228ae9a9705140f2832305dfead5
+2026-09-06-pr-ci-runner-temporary-storage.zh.md: f6765212af2424f2080063946f9104125993b9d5
diff --git a/.agents/notes/implemented/testing/2026-09-06-pr-ci-runner-temporary-storage.md b/.agents/notes/implemented/testing/2026-09-06-pr-ci-runner-temporary-storage.md
new file mode 100644
index 0000000000..59d609c08e
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-09-06-pr-ci-runner-temporary-storage.md
@@ -0,0 +1,51 @@
+# Agent Note: runner-owned temporary storage for PR CI
+
+Status: implemented
+
+English | [中文](2026-09-06-pr-ci-runner-temporary-storage.zh.md)
+
+## Problem
+
+The Linux failover pool runs multiple runner instances on one VM. PR coverage and snapshot processes use the operating-system temporary directory for transformed modules and fixtures. Files outside the runner's temporary directory escape its job cleanup, including when cancellation prevents process-level disposal. Exhausting that shared directory makes unrelated PRs fail before tests execute.
+
+## Decision
+
+The static, coverage, and consumer jobs in [PR CI](../../../../.github/workflows/ci.yml) export `TMPDIR=runner.temp` through `GITHUB_ENV` in their first step before any setup or test process starts. Node, Vite, tsx, and temporary test consumers inherit the runner-owned location. Each runner owns its directory and GitHub Actions clears its removable contents at job start and completion; fixtures still allocate unique children and retain their own cleanup.
+
+npm keeps its configured persistent cache, normally `$HOME/.npm` on POSIX, without a per-job override in the main CI or release workflows. The pnpm store remains shared at `$HOME/.local/share/pnpm/store`. Both retain cross-runner reuse under the package managers’ concurrent-access support; shared-cache capacity and filesystem failures remain operational responsibilities. The consumer job places Playwright browser downloads and installation locks beside `RUNNER_TEMP`; hosted cache restore uses that same location.
+
+The [release rehearsal decision](../process/2026-09-06-release-rehearsal-selfhosted.md) applies the same lifetime rule to release consumers. The [failover runbook](../process/2026-07-26-ci-failover-runbook.md) continues to own runner selection and shared-host capacity. This change does not retarget jobs, reduce concurrency, retry tests, weaken assertions, or modify master-only CI.
+
+## Recorded ACP completion order
+
+The [ACP diagnostic scenario](../../../../snapshots/session/subagent-acp-diagnostic/cordis.snapshot.yml) holds its scripted background response until `job_output` owns the completion wait. Without that synchronization, a fast child can publish a legitimate job notice between the recorded parent steps. A scenario-local wrapper releases the child after the jobs service registers the completion waiter; the mock watches an exclusive marker in the private test workspace and closes the watcher after release. The fixture restores the wrapped method on disposal. The recorded Session bytes and production job-notice behavior stay unchanged.
+
+## Workspace-grant fixture placement
+
+The headless `session-sandbox-root` fixture declares `workspace.parent: outside-temp`, not a home-filesystem dependency. Its allocator uses a sibling of the canonical platform temp root where the parent is writable and avoids system temporary grants, otherwise home, and rejects a cwd already covered by automatic temporary write grants. On the failover runner this keeps the test on the data volume without making its write succeed through a temporary-directory exemption. The filesystem-sandbox containment tests use the same allocator for their workspace and denied sibling; they register cleanup immediately after successful acquisition. Atomic workspace allocation, recorded Session bytes, and the independent expected file remain unchanged.
+
+## Live verification and browser fixture inputs
+
+The installed-wheel live SDK test externally replaces the created file with a fresh host-only challenge before asking the model to verify it; the verification prompt does not reveal that value. Both turns must contain model-requested tool calls, and the verifier compares the returned value and actual file bytes.
+
+The reference-composer fixture maps the known home-abbreviated workspace display to its existing cwd token and waits for the current exact suggestion set before selecting; neither host paths nor stale suggestions determine its result. The shared browser timezone, Inspector subscription synchronization, and PowerShell completion behavior follow the [existing platform-test decision](2026-09-07-pwsh-ci-observable-completion.md).
+
+The advanced Python snapshot pauses only its matching workflow child’s first pre-step until the parent’s durable workflow membership event is observed. The fixture supports either event-arrival order and cancels pending waits on abort or disposal. This pins the scenario’s cross-session ordering without sorting notifications or changing production scheduling.
+
+The queue snapshot moves the pointer away from the Stop/Send control and waits for its Send tooltip to close before capture. Workspace-management tests select the sole non-blank Session by its actions affordance, not row position, and select that Session before asserting that archiving it removes the empty Ungrouped bucket. Hover behavior, queue contents, durable archive identity, and reload assertions remain unchanged. The concurrent spill isolation test keeps each root paired with its run result rather than assuming filesystem allocation completion order matches input order.
+
+## Alternatives considered
+
+**Delete shared temporary files from a PR job.** Another runner may still own those files. Repository jobs must not reclaim a shared directory by pathname or age.
+
+**Retry tests or enlarge timeouts.** Neither recovers storage or gives residual files a cleanup owner.
+
+**Switch every job to hosted runners.** This avoids the affected VM but leaves the failover path defective and changes the operator's independent pool selection.
+
+## Consequences
+
+Output honoring `TMPDIR` follows the job lifetime instead of accumulating in unmanaged host storage. Package-manager and browser caches remain persistent. This does not reclaim existing shared temporary files, guarantee filesystem capacity, or clean files the runner account cannot remove. Operators still own historical residue, disk provisioning, and jobs outside this PR workflow.
+
+Linux bwrap and Landlock workspace-write profiles grant literal `/tmp` and the workspace, not an inherited `TMPDIR` outside it; confined fixtures must place temporary writes in those granted paths. The [snapshot spill helper](../../../../packages/test-support/session-snapshot/src/harness.ts) separates fixed-length logical locators from atomically allocated live storage. A fixture-only adapter delegates saves to the real local spill provider and resolves only locators saved by that run to their live files. Recorded preview lengths, omission counts, and retrieval assertions remain unchanged; no files are allocated at the logical `/tmp/dsh-acp-snap-*` prefix. This change does not widen product sandbox grants.
+
+The parsed-workflow cases in [ci-workflow.spec.ts](../../../../scripts/ci-workflow.spec.ts) require the assignment on all three workers and reject step-level overrides. They fail against the unmodified workflow. Independent-process smoke checks and repeated PR runs validate the actual tooling; the YAML assertions alone do not prove host capacity.
diff --git a/.agents/notes/implemented/testing/2026-09-06-pr-ci-runner-temporary-storage.zh.md b/.agents/notes/implemented/testing/2026-09-06-pr-ci-runner-temporary-storage.zh.md
new file mode 100644
index 0000000000..f6765212af
--- /dev/null
+++ b/.agents/notes/implemented/testing/2026-09-06-pr-ci-runner-temporary-storage.zh.md
@@ -0,0 +1,51 @@
+# Agent Note: PR CI 使用 runner 管理的临时存储
+
+Status: implemented
+
+[English](2026-09-06-pr-ci-runner-temporary-storage.md) | 中文
+
+## 问题
+
+Linux 故障切换池在同一台虚拟机上运行多个 runner 实例。PR 覆盖率和快照进程使用操作系统临时目录存放转换后的模块与测试夹具。runner 临时目录之外的文件不受作业清理管理，取消执行阻止进程自行清理时也不例外。该共享目录耗尽会让无关 PR 在测试执行前就失败。
+
+## 决策
+
+[PR CI](../../../../.github/workflows/ci.yml) 的静态检查、覆盖率和消费者作业在任何准备或测试进程启动前，在首个步骤通过 `GITHUB_ENV` 导出 `TMPDIR=runner.temp`。Node、Vite、tsx 和临时测试消费者继承 runner 管理的位置。每个 runner 管理自己的目录，GitHub Actions 在作业开始和完成时清除其中可删除的内容；测试夹具仍分配唯一子目录，并保留自身清理逻辑。
+
+npm 保留配置的持久化缓存，在 POSIX 上通常为 `$HOME/.npm`；主 CI 和发布工作流不设置每作业覆盖。pnpm store 保持共享于 `$HOME/.local/share/pnpm/store`。两者依靠包管理器的并发访问支持保留跨 runner 复用；共享缓存容量及文件系统故障仍由运维负责。消费者作业将 Playwright 浏览器下载和安装锁放在 `RUNNER_TEMP` 旁；托管缓存恢复使用同一位置。
+
+[发布演练决策](../process/2026-09-06-release-rehearsal-selfhosted.zh.md) 对发布消费者采用相同的生命周期规则。[故障切换运行手册](../process/2026-07-26-ci-failover-runbook.zh.md) 继续负责 runner 选择和共享主机容量。本变更不调整作业目标、不降低并发、不重试测试、不削弱断言，也不修改仅在 master 上执行的 CI。
+
+## ACP 完成顺序的录制
+
+[ACP 诊断场景](../../../../snapshots/session/subagent-acp-diagnostic/cordis.snapshot.yml) 暂停脚本化的后台响应，直到 `job_output` 开始等待完成。没有这种同步，快速子进程可能在录制的父步骤之间发布合法的作业通知。场景本地 wrapper 在 jobs 服务注册完成等待器后释放子进程；mock 在测试私有 workspace 中监听独占创建的标记，并在释放后关闭 watcher。夹具在销毁时恢复被包装的方法。录制的 Session 字节和生产作业通知行为保持不变。
+
+## Workspace 授权夹具的位置
+
+Headless 的 `session-sandbox-root` 夹具声明 `workspace.parent: outside-temp`，而不是依赖 home 所在文件系统。分配器在父目录可写且避开系统临时授权时选择规范化平台临时根目录的同级目录，否则使用 home，并拒绝已被自动临时写授权覆盖的 cwd。在故障切换 runner 上，这让测试留在数据卷中，同时不会让写入借助临时目录豁免而成功。文件系统沙箱的包含关系测试使用同一分配器创建 workspace 及被拒绝的同级目录，并在成功获取目录后立即注册清理。原子 workspace 分配、录制的 Session 字节以及独立预期文件保持不变。
+
+## 在线验证与浏览器夹具输入
+
+已安装 wheel 的在线 SDK 测试在要求模型验证前，由外部将创建的文件替换为新的、仅主机知道的挑战值；验证提示不暴露该值。两个 turn 必须包含模型请求的工具调用，验证器同时比较返回值及真实文件字节。
+
+Reference-composer 夹具将已知的 home 缩写 workspace 显示映射到既有 cwd token，并在选择前等待当前精确建议集；主机路径或过时建议都不决定测试结果。共享浏览器时区、Inspector 订阅同步及 PowerShell 完成行为遵循[既有平台测试决策](2026-09-07-pwsh-ci-observable-completion.zh.md)。
+
+高级 Python 快照仅暂停其匹配的 workflow 子进程首次 pre-step，直到观察到父 Session 的持久化 workflow 成员事件。夹具支持事件先到或等待先建立两种顺序，并在取消或销毁时结束未完成等待。这固定了场景的跨 Session 顺序，而不排序通知或改变生产调度。
+
+Queue 快照在捕获前将指针移离 Stop/Send 控件，并等待其 Send tooltip 关闭。Workspace-management 测试通过操作按钮定位唯一非空 Session，而不依赖行位置；在断言归档会移除空的 Ungrouped 分组前，先选中该 Session。Hover 行为、队列内容、持久化归档身份及重载断言保持不变。并发 spill 隔离测试将每个根目录与其运行结果关联，而不假设文件系统分配完成顺序与输入顺序一致。
+
+## 考虑过的替代方案
+
+**由 PR 作业删除共享临时文件。** 其他 runner 可能仍在使用这些文件。仓库作业不得按路径或文件年龄回收共享目录。
+
+**重试测试或增大超时。** 两者都不能恢复存储空间，也不能为残留文件指定清理责任方。
+
+**将所有作业切换到托管 runner。** 这能避开受影响的虚拟机，但故障切换路径的缺陷仍在，也会改变运维人员独立选择的执行池。
+
+## 影响
+
+遵循 `TMPDIR` 的输出随作业生命周期清理，而不累积于无人管理的主机存储。包管理器和浏览器缓存保持持久化。本方案不回收既有共享临时文件、不保证文件系统容量，也不清理 runner 账号无权删除的文件。历史残留、磁盘配置以及本 PR 工作流以外的作业仍由运维人员负责。
+
+Linux bwrap 和 Landlock 的 workspace-write profile 允许写入字面路径 `/tmp` 和 workspace，而不允许写入其外部继承的 `TMPDIR`；受限测试夹具必须将临时写入放在这些已授权路径中。[快照 spill helper](../../../../packages/test-support/session-snapshot/src/harness.ts) 将固定长度的逻辑定位符与原子分配的实际存储分开。仅用于夹具的适配器将保存操作委托给真实的本地 spill provider，并仅将本次运行已保存的定位符解析到实际文件。录制的预览长度、省略计数及检索断言保持不变；逻辑 `/tmp/dsh-acp-snap-*` 前缀下不分配文件。本变更不扩大产品沙箱授权。
+
+[ci-workflow.spec.ts](../../../../scripts/ci-workflow.spec.ts) 的 YAML 解析用例要求三个 worker 都包含该赋值，并拒绝步骤级别的覆盖。它们在未修改的工作流上失败。独立进程 smoke 检查和重复 PR 运行验证实际工具链；仅有 YAML 断言不能证明主机容量充足。
diff --git a/.agents/skills/record-browser-gif/SKILL.md b/.agents/skills/record-browser-gif/SKILL.md
index 93a55769c0..9222144902 100644
--- a/.agents/skills/record-browser-gif/SKILL.md
+++ b/.agents/skills/record-browser-gif/SKILL.md
@@ -1,11 +1,11 @@
 ---
 name: record-browser-gif
-description: Record browser or Web UI interaction demos as optimized GIFs using the available built-in browser, state-based frame capture, and deterministic encoding, then attach the GIF to a pull request with `gh --attach`, falling back to a dedicated assets branch where attach cannot apply. Use when asked to make, record, or generate a GIF that demonstrates a browser workflow, and for every pull request that changes product-user-visible GUI behavior, which MUST include a GIF recorded from the pull request's real server and model flow.
+description: Record browser or Web UI interaction demos as optimized GIFs using the available browser-control workflow, optional Playwright Videos for higher capture frame rates, and deterministic encoding, then attach the GIF to a pull request with `gh --attach`, falling back to a dedicated assets branch where attach cannot apply. Use when asked to make, record, or generate a GIF that demonstrates a browser workflow, and for every pull request that changes product-user-visible GUI behavior, which MUST include a GIF recorded from the pull request's real server and model flow.
 ---
 
 # Record Browser GIF
 
-Produce a short, truthful UI demonstration as a local GIF, and — only when the task includes attaching it to a pull request — publish it through the attach workflow at the end of this skill. Use the browser-control skill for interaction and the bundled encoder for repeatable timing, dimensions, and size.
+Produce a short, truthful UI demonstration as a local GIF, and — only when the task includes attaching it to a pull request — publish it through the attach workflow at the end of this skill. The available browser-control workflow remains preferred. Use [Playwright Videos](https://playwright.dev/docs/videos) when that workflow supports continuous capture at higher frame rates; use the bundled encoder for trimming, playback speed, final hold, dimensions, and size.
 
 The [evidence-chain decision](../../notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md) owns why one storyboard comes from one isolated run and why publication revalidates both the artifact and the demonstrated pull-request head.
 
@@ -17,7 +17,7 @@ The recording itself is part of the evidence: use a real server booted from that
 
 ## Keep recording separate from publication
 
-- Recording produces frame images and one local `.gif` artifact only; it never mutates remote state.
+- Recording produces local video or screenshots and one `.gif` artifact only; it never mutates remote state.
 - Publication — attaching the GIF to a pull request body with `gh --attach`, or pushing it to an assets branch and embedding its URL where attach cannot apply — is the separate final step, performed only when the task includes attaching the GIF to a pull request. It never touches the pull request's own branch.
 - Preserve the requested recording conditions. A real-server or real-API demo must not use fixture queries, mock transports, synthetic event injection, or test-only hooks. If credentials or the server are unavailable, report that limitation instead of substituting a fixture.
 - Never read or expose credential values. Use the application's normal configuration path and a benign demonstration prompt.
@@ -33,49 +33,86 @@ A GIF for a specific pull request demonstrates that pull request's tree, so stag
 
 ## Record the flow
 
-1. Invoke the available browser-control skill and follow its setup, interaction, and cleanup instructions. Use the user's existing Chrome state only when requested or required; state that exception in the provenance and do not claim fresh client state. If browser control is unavailable, use the repository-declared Playwright dependency in an isolated headless browser; do not install another driver or launch the user's browser. State that fallback in the provenance.
-2. Before recording, identify the exact origin, whether the app is built or in development, the transport, and any fixture or mock mode. Record only claims that the observed setup supports.
-3. When a production default opens a native operating-system surface that headless automation cannot drive, select an official browser-operable production backend through the application's normal configuration. State the override in the provenance; a fixture, mock transport, or test-only hook is not an acceptable substitute.
-4. Choose three to six states that tell one story, such as typed, running, settled, and detail. Prefer semantic state changes over continuous capture; omit loading churn that does not help the viewer.
-5. Keep one viewport and crop for every frame, and name frames lexically: `00-initial.png`, `01-typed.png`, and so on.
-6. Store frames under the repository's gitignored `.playwright-mcp/` directory — browser-tool screenshots can only be written under the tool's allowed roots, and relative filenames resolve against the repository root. Create the frame subdirectory first (`mkdir -p .playwright-mcp/gif-frames-<label>`); writing into a missing directory fails with ENOENT at capture time.
-7. Before each screenshot, wait for a concrete UI condition such as a unique label, enabled control, changed document title, or completed response. Require the locator to resolve exactly one element; for Playwright accessible-name locators, use `exact: true` when equality is intended because descendant text or a prompt echo can otherwise create a false match. Do not use a fixed delay as proof that the application reached the state.
-8. Make completion predicates match an exact-text element — for example, an element whose trimmed text equals the expected reply — never a substring check such as `body.textContent.includes(...)`, which the echo of the user's own prompt also satisfies.
-9. When the claim involves a tool call, rejection, or recovery, include a detail or trajectory frame that shows the tool identity, status or stable error code, and the downstream result. A chat-only outcome does not prove why the tool path behaved that way.
-10. Capture a transient state (spinner, running row) by driving a slow foreground operation — for example, a `sleep 15` bash command — and polling a concrete DOM marker (a `data-*` attribute) inside one browser-script call that also takes the screenshot. State polled across separate tool calls is lost, because the turn settles between calls.
-11. Engineer the prompt so the state you need actually occurs: instruct the model to wait in the foreground when it would otherwise background a slow command, and give it a settle sentinel such as "reply with the single word done" to anchor the completion predicate.
-12. Capture no secrets, personal data, unrelated tabs, or transient notifications. Stop any unnecessarily long real-API run after the demonstrated state is visible.
+Follow the available browser-control workflow's setup, interaction, and cleanup instructions. When it exposes `recordVideo`, enable video on the same controlled context to capture more intermediate frames. Otherwise use [screenshot capture](#screenshot-capture) within that workflow; video availability does not determine which browser-control workflow to use. Existing user browser state remains an explicit provenance exception.
 
-Use the browser's own screenshot API. When it returns image bytes, save those bytes directly; the encoder detects image content independently of the filename extension.
+Only when browser control is unavailable, use the repository-declared Playwright dependency in an isolated headless browser and state that fallback in the provenance. In this repository it resolves from `apps/web/package.json`; do not install another driver or open the user's browser.
+
+Before recording, identify the origin, built or development server, transport, and any mode overrides. When a production default opens a native surface that automation cannot drive, select an official browser-operable production backend through normal application configuration and disclose the override.
+
+Store the script, raw video, timing notes, QA frames, and GIF under the repository's gitignored `.playwright-mcp/` directory. Create the run directory first.
+
+### Capture video
+
+Match `viewport` and `recordVideo.size` explicitly: Playwright otherwise scales the video down to fit 800×800, which can make UI text unreadable.
+
+Configure video through the chosen browser-control workflow. The standalone Playwright fallback uses:
+
+```js
+const { chromium } = createRequire(join(repo, 'apps/web/package.json'))('playwright')
+const browser = await chromium.launch()
+const size = { width: 1440, height: 900 }
+const context = await browser.newContext({
+  viewport: size,
+  recordVideo: { dir: join(runDir, 'videos'), size },
+})
+try {
+  const page = await context.newPage()
+  const video = page.video()
+  // Navigate and exercise the real application here.
+  await context.close()
+  await video.saveAs(join(runDir, 'demo.webm'))
+} finally {
+  await context.close()
+  await browser.close()
+}
+```
+
+Import `createRequire` from `node:module` and `join` from `node:path`; set `repo` and a fresh `runDir` to absolute paths in the recording script. Retain the page's video handle before closing it. Await `context.close()` before `video.saveAs()` or encoding; closing only the browser does not guarantee the video's flush. Each page has its own video: choose the demonstrated page explicitly and do not concatenate unrelated pages or runs. Failed runs are diagnostic only.
+
+Choose a short story with three to six meaningful states. Wait for unique semantic locators before acting; use `exact: true` for accessible-name equality and exact-text completion predicates that cannot match a prompt echo. Fixed waits may provide a reading hold after the state is verified, but never establish readiness. When capturing video, preserve animations and scrolling.
+
+When demonstrating a tool call, rejection, or recovery, open its detail or trajectory so the video shows the tool identity, status or stable error code, and downstream result. If a transient running state matters, prompt for a slow foreground operation and observe its concrete DOM marker; continuous video captures its intermediate frames. Give the model a short final sentinel to anchor completion. Stop an unnecessarily long real-API run after the demonstrated state is visible.
+
+Capture no secrets, personal data, unrelated tabs, or notifications. Browser video contains page content, not browser chrome; avoid rendering credential-bearing URLs in the application. Review the whole selected interval, including intermediate states. Keep one viewport throughout.
 
 ## Encode the GIF
 
-Require `python3`, `ffmpeg`, and `ffprobe`. If either media binary is missing, report the dependency instead of installing software without authorization.
-
-Export `GIF_SKILL_DIR` as this skill's absolute directory on its own line before the python command — an inline `GIF_SKILL_DIR=... python3 "$GIF_SKILL_DIR/..."` assignment fails, because the argument expands before the assignment takes effect:
+Require `python3`, `ffmpeg`, and `ffprobe`. If a media binary is missing, report the dependency instead of installing software without authorization. Export `GIF_SKILL_DIR` on its own line before using it; an inline assignment cannot affect argument expansion in the same command.
 
 ```sh
 export GIF_SKILL_DIR=/absolute/path/to/this/skill
 python3 "$GIF_SKILL_DIR/scripts/encode_gif.py" \
-  /absolute/path/to/frames \
+  /absolute/path/to/demo.webm \
   /absolute/path/to/demo.gif \
-  --durations 1.5,1.5,1.5,3.5 \
-  --fps 10 \
-  --max-width 1200 \
-  --colors 128
+  --start 2 --end 32 --speed 2 --final-hold 3 \
+  --fps 10 --max-width 1200 --colors 128
 ```
 
-One duration applies to every frame; otherwise provide one comma-separated positive duration per frame, holding the final settled state longest. The encoder rejects fewer than two frames, mismatched dimensions or durations, invalid limits, accidental overwrite, unexpected duration, and output above `--max-bytes`.
+`--start` and `--end` select one continuous source interval in seconds. Defaults retain the full video at 1× speed and add a two-second final hold. `--speed` changes playback speed; disclose it and the selected interval beside the GIF so the demo cannot imply measured response latency. Use observed video times, not guessed wall-clock offsets, and preserve the complete cause and outcome of the demonstrated behavior. The final hold repeats the last selected frame. `--fps` sets the encoded GIF frame rate; increasing it cannot recover motion that the source recording did not capture. Keep the original WebM for QA; do not splice separate runs or synthesize missing states.
 
-For a large artifact, reduce `--max-width` first, then `--colors` or `--fps`; retain readable text and the final state long enough to inspect. Use `--force` only after resolving the exact output path.
+The encoder probes WebM container duration, applies trim and speed before palette conversion, and checks encoded duration, animation, width, and byte size. It refuses an empty or out-of-range interval, a selection shorter than two output frames, mode-inappropriate flags, and accidental overwrite. Reduce `--max-width`, then `--colors` or `--fps` for a large artifact; preserve readable text. Use `--force` only after resolving the exact output path.
+
+### Screenshot capture
+
+When continuous video is unavailable or the user requests a storyboard, follow the available browser-control workflow. Capture three to six verified states from one isolated run with the browser's screenshot API. Save returned image bytes directly under one run directory as `00-initial.png`, `01-typed.png`, and so on; use identical dimensions and crop. For a transient state, poll its DOM marker and capture within the same browser-script call.
+
+```sh
+python3 "$GIF_SKILL_DIR/scripts/encode_gif.py" \
+  /absolute/path/to/frames /absolute/path/to/demo.gif \
+  --durations 1.5,1.5,1.5,3.5 --fps 10 --max-width 1200 --colors 128
+```
+
+One duration applies to every screenshot; otherwise supply one positive duration per frame and hold the settled state longest. Directory input rejects fewer than two frames and mismatched dimensions or duration counts. Video timing flags apply only to video files; `--durations` and `--pattern` apply only to screenshot directories.
 
 ## Verify the artifact
 
-1. Read the encoder's JSON summary and confirm the output path, source and encoded frame counts, dimensions, duration, and byte size.
+1. Read the encoder's JSON summary and confirm the output path, source interval and speed (or screenshot count), encoded frame count, dimensions, duration, and byte size.
 2. Visually read the encoded GIF itself, not only the source frames. Confirm that the transition is legible, the last state is held long enough, and no sensitive content appears. If the viewer renders only the first frame, decode representative frames from the encoded GIF with `ffmpeg` and inspect those; the pre-encode screenshots do not prove the encoded order, palette, or final hold.
-3. Run `git status --short` and confirm frames and the artifact landed only under ignored paths.
+3. Run `git status --short` and confirm raw video, QA frames, and the artifact landed only under ignored paths.
 4. Return the absolute GIF path, render it when the client supports local media, and state whether the recording used a real API, fixture, or another transport. When the task does not include attaching the GIF to a pull request, stop here.
 
+Encoder maintenance: run `python3 -m unittest discover -s "$GIF_SKILL_DIR/scripts" -p 'test_*.py' -v` with the media prerequisites installed. These local media tests do not run in repository CI.
+
 ## Publish the GIF
 
 Perform this step only when the task includes attaching the GIF to a pull request.
@@ -92,14 +129,16 @@ Write the GIF into the body file as an ordinary local-path reference, using the
 ![<alt text>](<path/to/demo.gif>)
 ```
 
-Immediately before attaching, re-read the pull request's live head — for a new pull request, the pushed branch tip — and compare it with the commit recorded next to the GIF. Stop and re-record when it moved. Then attach:
+The demonstrated pull request is normally the publication target. A tooling pull request may instead embed a clearly labeled example from another pull request; name that source PR and compare its live head in every check below. Never attribute the example to the tooling branch.
+
+Immediately before attaching, re-read the demonstrated pull request's live head — for a new demonstrated pull request, the pushed branch tip — and compare it with the commit recorded next to the GIF. Stop and re-record when it moved. Then attach:
 
 ```sh
 gh pr create --body-file <body.md> --attach <path/to/demo.gif>     # new pull request
 gh pr edit <pr> --body-file <body.md> --attach <path/to/demo.gif>  # existing pull request
 ```
 
-`--attach` is repeatable but refuses the same file twice. A GIF the body does not reference is appended at the end, where alt text set on the flag (`--attach '<path>#<alt text>'`) applies; a rewritten reference keeps the body's alt text. After attaching, re-read the live head and require it to remain at that recorded commit. Re-read the live body and confirm the reference now points at the uploaded URL, render the body through GitHub's Markdown API and confirm the expected `<img>`, and fetch the uploaded URL once to confirm `200` and `image/gif`.
+`--attach` is repeatable but refuses the same file twice. A GIF the body does not reference is appended at the end, where alt text set on the flag (`--attach '<path>#<alt text>'`) applies; a rewritten reference keeps the body's alt text. After attaching, re-read the demonstrated live head and require it to remain at that recorded commit. Re-read the live body and confirm the reference now points at the uploaded URL, render the body through GitHub's Markdown API and confirm the expected `<img>`, and fetch the uploaded URL once to confirm `200` and `image/gif`.
 
 ### Fall back to an assets branch
 
@@ -122,7 +161,7 @@ For a new series, make a fresh shallow scratch clone (`git clone --depth 1 <repo
 
 After pushing, use authenticated GitHub API or raw requests to confirm the remote path, byte size, checksum, `200` response, and `image/gif` content type. An anonymous `404` does not disprove a private-repository asset; authenticate the verification instead. This proves the repository-member review path, not public availability.
 
-Immediately before editing the pull-request body, re-read its live head and compare it with the commit recorded next to the GIF. Stop and re-record when it moved. After the edit, re-read the live head and require it to remain at that recorded commit. Separately, render the body through GitHub's Markdown API and confirm that the expected `<img>` is present.
+Immediately before editing the pull-request body, re-read the demonstrated pull request's live head and compare it with the commit recorded next to the GIF. Stop and re-record when it moved. After the edit, re-read the demonstrated live head and require it to remain at that recorded commit. Separately, render the body through GitHub's Markdown API and confirm that the expected `<img>` is present.
 
 Embed the GIF in the pull request body with the raw blob URL; the `?raw=true` suffix is required, because the plain blob URL renders GitHub's file page instead of the image:
 
diff --git a/.agents/skills/record-browser-gif/scripts/encode_gif.py b/.agents/skills/record-browser-gif/scripts/encode_gif.py
index 2a14ae47fd..cfda42ccab 100755
--- a/.agents/skills/record-browser-gif/scripts/encode_gif.py
+++ b/.agents/skills/record-browser-gif/scripts/encode_gif.py
@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Encode lexically ordered browser screenshots into a verified GIF."""
+"""Encode a Playwright video or ordered browser screenshots into a verified GIF."""
 
 from __future__ import annotations
 
@@ -43,6 +43,17 @@ def positive_int(value: str) -> int:
     return parsed
 
 
+def nonnegative_float(value: str) -> float:
+    """Parse a finite nonnegative timestamp or hold duration."""
+    try:
+        parsed = float(value)
+    except ValueError:
+        fail(f"expected a number, got {value!r}")
+    if not math.isfinite(parsed) or parsed < 0:
+        fail(f"expected a nonnegative finite number, got {value!r}")
+    return parsed
+
+
 def parse_durations(value: str, frame_count: int) -> list[float]:
     """Expand one hold duration or validate one duration per source frame."""
     parts = [part.strip() for part in value.split(",")]
@@ -102,6 +113,17 @@ def probe_stream(ffprobe: str, path: Path) -> dict[str, object]:
     return streams[0]
 
 
+def video_duration(ffprobe: str, path: Path) -> float:
+    """Read container duration because Playwright WebM omits stream duration."""
+    result = run_json([
+        ffprobe, "-v", "error", "-show_entries", "format=duration", "-of", "json", str(path),
+    ])
+    metadata = result.get("format")
+    if not isinstance(metadata, dict):
+        fail(f"missing format metadata for {path}")
+    return positive_float(str(metadata.get("duration")))
+
+
 def stream_int(stream: dict[str, object], key: str, path: Path) -> int:
     """Read a positive integer stream field."""
     try:
@@ -134,14 +156,17 @@ def write_concat_manifest(path: Path, frames: list[Path], durations: list[float]
 def build_parser() -> argparse.ArgumentParser:
     """Build the command-line contract."""
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("frames", type=Path, help="directory containing lexically ordered frames")
+    parser.add_argument("input", type=Path, help="video file or directory of ordered screenshots")
     parser.add_argument("output", type=Path, help="output .gif path")
-    parser.add_argument("--pattern", default="*.png", help="frame glob within the input directory")
+    parser.add_argument("--pattern", help="screenshot glob (default: *.png; directory input only)")
     parser.add_argument(
         "--durations",
-        default="2",
-        help="one hold duration or one comma-separated value per frame",
+        help="screenshot holds (default: 2 seconds each; directory input only)",
     )
+    parser.add_argument("--start", type=nonnegative_float, help="video trim start in seconds (default: 0)")
+    parser.add_argument("--end", type=positive_float, help="video trim end in seconds (default: EOF)")
+    parser.add_argument("--speed", type=positive_float, help="video playback multiplier (default: 1)")
+    parser.add_argument("--final-hold", type=nonnegative_float, help="extra final video frame hold (default: 2 seconds)")
     parser.add_argument("--fps", type=positive_int, default=10, help="encoded frames per second")
     parser.add_argument(
         "--max-width",
@@ -168,11 +193,14 @@ def build_parser() -> argparse.ArgumentParser:
 def main() -> None:
     """Validate inputs, encode the GIF, verify it, and print a JSON summary."""
     args = build_parser().parse_args()
-    frame_dir = args.frames.resolve()
+    source = args.input.resolve()
     output = args.output.resolve()
 
-    if not frame_dir.is_dir():
-        fail(f"frame directory does not exist: {frame_dir}")
+    if not source.exists():
+        fail(f"input does not exist: {source}")
+    is_video = source.is_file()
+    if not is_video and not source.is_dir():
+        fail(f"input must be a video file or frame directory: {source}")
     if output.suffix.lower() != ".gif":
         fail(f"output must end in .gif: {output}")
     if output.exists() and not args.force:
@@ -182,33 +210,68 @@ def main() -> None:
     if args.fps > 30:
         fail("--fps must not exceed 30")
 
-    frames = sorted(path.resolve() for path in frame_dir.glob(args.pattern) if path.is_file())
-    if len(frames) < 2:
-        fail(f"expected at least two frames matching {args.pattern!r} in {frame_dir}")
-    if output in frames:
-        fail("output path must not match an input frame")
-
-    durations = parse_durations(args.durations, len(frames))
-    expected_duration = sum(durations)
     ffmpeg = require_binary("ffmpeg")
     ffprobe = require_binary("ffprobe")
-
-    dimensions = {
-        (stream_int(stream, "width", frame), stream_int(stream, "height", frame))
-        for frame in frames
-        for stream in [probe_stream(ffprobe, frame)]
-    }
-    if len(dimensions) != 1:
-        fail(f"all frames must have identical dimensions, got {sorted(dimensions)}")
+    details: dict[str, object]
+    if is_video:
+        if args.pattern is not None or args.durations is not None:
+            fail("--pattern and --durations require a screenshot directory")
+        if source == output:
+            fail("output path must not match the input video")
+        probe_stream(ffprobe, source)
+        source_duration = video_duration(ffprobe, source)
+        start = args.start if args.start is not None else 0.0
+        end = args.end if args.end is not None else source_duration
+        speed = args.speed if args.speed is not None else 1.0
+        final_hold = args.final_hold if args.final_hold is not None else 2.0
+        if not start < end <= source_duration:
+            fail(f"video trim must satisfy 0 <= start < end <= {source_duration:.3f}")
+        if (end - start) / speed < 2 / args.fps:
+            fail("video selection must span at least two output frames before the final hold")
+        expected_duration = (end - start) / speed + final_hold
+        details = {
+            "sourceVideo": str(source), "sourceDurationSeconds": source_duration,
+            "startSeconds": start, "endSeconds": end, "speed": speed,
+            "finalHoldSeconds": final_hold,
+        }
+    else:
+        if any(value is not None for value in (args.start, args.end, args.speed, args.final_hold)):
+            fail("--start, --end, --speed and --final-hold require a video file")
+        pattern = args.pattern if args.pattern is not None else "*.png"
+        if not pattern:
+            fail("--pattern must not be empty")
+        frames = sorted(path.resolve() for path in source.glob(pattern) if path.is_file())
+        if len(frames) < 2:
+            fail(f"expected at least two frames in {source}")
+        if output in frames:
+            fail("output path must not match an input frame")
+        durations = parse_durations(args.durations if args.durations is not None else "2", len(frames))
+        expected_duration = sum(durations)
+        dimensions = {
+            (stream_int(stream, "width", frame), stream_int(stream, "height", frame))
+            for frame in frames
+            for stream in [probe_stream(ffprobe, frame)]
+        }
+        if len(dimensions) != 1:
+            fail(f"all frames must have identical dimensions, got {sorted(dimensions)}")
+        details = {"sourceFrames": len(frames)}
 
     output.parent.mkdir(parents=True, exist_ok=True)
     with tempfile.TemporaryDirectory(prefix="record-browser-gif-") as temporary:
-        manifest = Path(temporary) / "frames.ffconcat"
-        write_concat_manifest(manifest, frames, durations)
+        if is_video:
+            inputs = ["-i", str(source)]
+            timing = f"trim=start={start}:end={end},setpts=(PTS-STARTPTS)/{speed},"
+            hold = f",tpad=stop_mode=clone:stop_duration={final_hold}"
+        else:
+            manifest = Path(temporary) / "frames.ffconcat"
+            write_concat_manifest(manifest, frames, durations)
+            inputs = ["-f", "concat", "-safe", "0", "-i", str(manifest)]
+            timing = ""
+            hold = ""
         scale = f"scale='min({args.max_width},iw)':-2:flags=lanczos"
         palette = f"palettegen=max_colors={args.colors}:stats_mode=full"
         filters = (
-            f"fps={args.fps},{scale},split[base][palette_input];"
+            f"{timing}fps={args.fps},{scale}{hold},split[base][palette_input];"
             f"[palette_input]{palette}[palette];"
             "[base][palette]paletteuse=dither=bayer:bayer_scale=3:diff_mode=rectangle"
         )
@@ -217,12 +280,7 @@ def main() -> None:
             "-hide_banner",
             "-loglevel",
             "error",
-            "-f",
-            "concat",
-            "-safe",
-            "0",
-            "-i",
-            str(manifest),
+            *inputs,
             "-vf",
             filters,
             "-loop",
@@ -261,7 +319,7 @@ def main() -> None:
         json.dumps(
             {
                 "output": str(output),
-                "sourceFrames": len(frames),
+                **details,
                 "encodedFrames": encoded_frames,
                 "width": width,
                 "height": height,
diff --git a/.agents/skills/record-browser-gif/scripts/test_encode_gif.py b/.agents/skills/record-browser-gif/scripts/test_encode_gif.py
new file mode 100644
index 0000000000..3106ef9c07
--- /dev/null
+++ b/.agents/skills/record-browser-gif/scripts/test_encode_gif.py
@@ -0,0 +1,103 @@
+"""Exercise GIF timing and rejection through real ffmpeg/ffprobe subprocesses."""
+
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+SCRIPT = Path(__file__).with_name('encode_gif.py')
+
+
+class EncodeGifTest(unittest.TestCase):
+    def setUp(self):
+        self.temporary = tempfile.TemporaryDirectory(prefix='gif-encoder-test-')
+        self.addCleanup(self.temporary.cleanup)
+        self.root = Path(self.temporary.name)
+        self.video = self.root / 'browser video.webm'
+        self.output = self.root / 'demo.gif'
+        subprocess.run([
+            'ffmpeg', '-v', 'error',
+            '-f', 'lavfi', '-i', 'color=red:s=64x48:r=10:d=2',
+            '-f', 'lavfi', '-i', 'color=lime:s=64x48:r=10:d=2',
+            '-f', 'lavfi', '-i', 'color=blue:s=64x48:r=10:d=2',
+            '-filter_complex', '[0:v][1:v][2:v]concat=n=3:v=1:a=0',
+            '-c:v', 'libvpx', str(self.video),
+        ], check=True, capture_output=True)
+
+    def encode(self, source=None, *options):
+        return subprocess.run([
+            sys.executable, str(SCRIPT), str(source or self.video), str(self.output), *options,
+        ], capture_output=True, text=True)
+
+    def assert_color(self, seconds, channel):
+        result = subprocess.run([
+            'ffmpeg', '-v', 'error', '-i', str(self.output), '-ss', str(seconds),
+            '-frames:v', '1', '-vf', 'scale=1:1', '-f', 'rawvideo', '-pix_fmt', 'rgb24', '-',
+        ], check=True, capture_output=True)
+        pixel = result.stdout
+        self.assertEqual(len(pixel), 3)
+        self.assertGreater(pixel[channel], 200)
+        self.assertTrue(all(value < 40 for index, value in enumerate(pixel) if index != channel))
+
+    def test_video_trim_speed_final_hold_and_palette_order(self):
+        result = self.encode(None, '--start', '1', '--end', '5', '--speed', '2',
+                             '--final-hold', '1', '--max-width', '32')
+        self.assertEqual(result.returncode, 0, result.stderr)
+        summary = json.loads(result.stdout)
+        self.assertAlmostEqual(summary['durationSeconds'], 3, delta=0.2)
+        self.assertEqual((summary['width'], summary['height']), (32, 24))
+        self.assert_color(0.1, 0)
+        self.assert_color(0.8, 1)
+        self.assert_color(2.7, 2)
+
+    def test_video_defaults_keep_full_duration(self):
+        result = self.encode()
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertAlmostEqual(json.loads(result.stdout)['durationSeconds'], 8, delta=0.2)
+        self.assert_color(7.7, 2)
+
+    def test_invalid_video_options_do_not_write_output(self):
+        for options in [
+            ['--start', '-1'], ['--speed', 'nan'], ['--final-hold', 'inf'],
+            ['--start', '3', '--end', '3'], ['--end', '7'],
+            ['--speed', '1000'], ['--durations', '2'], ['--pattern', '*.png'],
+        ]:
+            with self.subTest(options=options):
+                result = self.encode(None, *options)
+                self.assertNotEqual(result.returncode, 0)
+                self.assertIn('error:', result.stderr)
+                self.assertFalse(self.output.exists())
+
+    def test_screenshot_durations_and_video_flag_rejection(self):
+        frames = self.root / 'frames'
+        frames.mkdir()
+        for index, color in enumerate([b'\xff\x00\x00', b'\x00\x00\xff']):
+            (frames / f'{index}.ppm').write_bytes(b'P6\n64 48\n255\n' + color * (64 * 48))
+        rejected = self.encode(frames, '--speed', '1')
+        self.assertNotEqual(rejected.returncode, 0)
+        self.assertIn('require a video file', rejected.stderr)
+        for options in [['--pattern', ''], ['--pattern', '*.ppm', '--durations', ''],
+                        ['--pattern', '*.ppm', '--durations', '1,2,3']]:
+            with self.subTest(options=options):
+                self.assertNotEqual(self.encode(frames, *options).returncode, 0)
+                self.assertFalse(self.output.exists())
+        result = self.encode(frames, '--pattern', '*.ppm', '--durations', '0.5,1.5')
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(json.loads(result.stdout)['sourceFrames'], 2)
+        self.assert_color(0.1, 0)
+        self.assert_color(1.8, 2)
+
+    def test_overwrite_and_size_limit(self):
+        self.output.write_bytes(b'keep')
+        rejected = self.encode()
+        self.assertNotEqual(rejected.returncode, 0)
+        self.assertEqual(self.output.read_bytes(), b'keep')
+        oversized = self.encode(None, '--force', '--max-bytes', '1', '--final-hold', '0.0')
+        self.assertNotEqual(oversized.returncode, 0)
+        self.assertIn('above --max-bytes', oversized.stderr)
+
+
+if __name__ == '__main__':
+    unittest.main()
diff --git a/.github/review-ownership/CODEOWNERS b/.github/review-ownership/CODEOWNERS
new file mode 100644
index 0000000000..5b41121d64
--- /dev/null
+++ b/.github/review-ownership/CODEOWNERS
@@ -0,0 +1,60 @@
+# Custom static-scanner input. Its nested path keeps GitHub from loading it as
+# the repository's native CODEOWNERS file.
+/apps/cli/ @turtle1999
+/apps/web/ @imccyu
+/docs/ @turtle1999
+/native/ @mektpoy
+/patches/ @mektpoy
+/python/ @LegGasai
+/scripts/ @turtle1999
+/vendor/ @turtle1999
+/website/ @LegGasai
+/packages/acp/ @mektpoy
+/packages/api/ @imccyu
+/packages/attachment/ @CreatixChu
+/packages/boot/ @turtle1999
+/packages/bundle/ @turtle1999
+/packages/client/ @imccyu
+/packages/code-runtime/ @Chinesezjc
+/packages/compaction/ @imccyu
+/packages/context/ @turtle1999
+/packages/core/ @tianyicui @turtle1999 @mektpoy
+/packages/credentials/ @mektpoy
+/packages/e2b/ @mektpoy
+/packages/experimental/ @mektpoy
+/packages/extensions/ @mektpoy
+/packages/feedback/ @mektpoy
+/packages/fs/ @mektpoy
+/packages/goal/ @mektpoy
+/packages/guard/ @turtle1999
+/packages/hooks/ @mektpoy
+/packages/host/ @turtle1999
+/packages/identity/ @imccyu
+/packages/interaction/ @imccyu
+/packages/jobs/ @imccyu
+/packages/llm/ @LegGasai
+/packages/lsp/ @mektpoy
+/packages/mcp/ @mektpoy
+/packages/plan/ @mektpoy
+/packages/preset/ @LegGasai @turtle1999
+/packages/runtime-diagnostics/ @mektpoy
+/packages/sandbox/ @mektpoy
+/packages/schedule/ @imccyu
+/packages/sdk/ @mektpoy
+/packages/session/ @tianyicui @turtle1999 @mektpoy
+/packages/session-query/ @mektpoy
+/packages/settings/ @mektpoy
+/packages/shell/ @mektpoy
+/packages/skill/ @mektpoy
+/packages/spill/ @mektpoy
+/packages/storage/ @imccyu
+/packages/subagent/ @Dudu-0223
+/packages/subprocess/ @mektpoy
+/packages/terminal/ @imccyu
+/packages/todo/ @mektpoy
+/packages/typert/ @imccyu
+/packages/util/ @mektpoy
+/packages/web/ @imccyu
+/packages/webhook/ @mektpoy
+/packages/workflow/ @mektpoy
+/packages/workspace/ @imccyu
diff --git a/.github/review-ownership/README.i18n.yaml b/.github/review-ownership/README.i18n.yaml
new file mode 100644
index 0000000000..e9ed0b794d
--- /dev/null
+++ b/.github/review-ownership/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .github/review-ownership/README.md
+README.md: 95dd52595bacb9b2b00bc475966f328b06098a14
+README.zh.md: a20a5f4ae41b5d0418601afa853ac2fbc141cc96
diff --git a/.github/review-ownership/README.md b/.github/review-ownership/README.md
new file mode 100644
index 0000000000..95dd52595b
--- /dev/null
+++ b/.github/review-ownership/README.md
@@ -0,0 +1,53 @@
+# Automated review requests
+
+English | [中文](README.zh.md)
+
+## Summary
+
+The [`request-review` workflow](../workflows/request-review.yml) reads the CODEOWNERS-compatible [ownership map](CODEOWNERS) from the trusted default branch. It prints the complete changed non-test file list, matches those files to owners, and then requests the missing reviewers. The ownership map is outside GitHub's native CODEOWNERS locations, so GitHub does not apply it directly.
+
+## Table of Contents
+
+- [Routing](#routing)
+- [Test exclusion](#test-exclusion)
+- [Security](#security)
+- [Verification](#verification)
+- [Dev Note](#dev-note)
+
+<a id="routing"></a>
+
+## Routing
+
+Non-draft pull requests run the workflow when opened, synchronized, reopened, or marked ready for review. The scanner fetches the complete pull-request file list, evaluates both paths of a rename, and fails instead of routing from a partial list. GitHub exposes at most 3,000 files for this API.
+
+The ownership map accepts explicit absolute directory patterns and individual GitHub users. It rejects wildcards, hidden-directory patterns, teams, and duplicate patterns or owners. Matching follows CODEOWNERS last-match semantics. The scanner prints `Changed code files`, `Excluded test files`, `Owners by changed file`, and `Reviewers to request` before it sends the review request. Unmatched files remain visible in the log. The pull-request author and users who are already requested are omitted.
+
+The policy test measures non-test tracked lines under matched directories and requires `@turtle1999` to own no more than one third of that eligible owned codebase.
+
+<a id="test-exclusion"></a>
+
+## Test exclusion
+
+Review routing excludes the repository's unit, end-to-end, expected-output, snapshot, benchmark, performance, stress, corpus, native, and Python test conventions. This includes `test`, `tests`, `__tests__`, `__snapshots__`, `benches`, and `stress-tests` directories; the top-level `benchmarks` and `snapshots` trees; `packages/test-support`; `scripts/fixtures` and `scripts/snapshots`; recognized test filename suffixes; and Python `test_*.py` or `*_test.py` files.
+
+Test infrastructure that can alter how evidence is produced remains reviewable, including `vitest*.config.ts` and gate implementations under `scripts`. A production file named `test.ts`, `spec.ts`, or `snapshot.ts` is not excluded solely by that name.
+
+<a id="security"></a>
+
+## Security
+
+The write-capable `pull_request_target` job checks out only the repository default branch. It does not check out or execute pull-request code and does not use repository secrets. Pull-request filenames are treated as API data and escaped in logs.
+
+Ownership changes take effect only after they merge into the default branch. This prevents an untrusted pull request from changing the routing program or its owner assignments for its own run.
+
+<a id="verification"></a>
+
+## Verification
+
+Run `pnpm run test:request-review` for ownership parsing, test classification, pagination, logging order, reviewer filtering, and API behavior. [Workflow tests](../../scripts/ci-workflow.spec.ts) pin the trusted checkout, permissions, events, and command. The repository gate graph runs both checks in CI.
+
+<a id="dev-note"></a>
+
+## Dev Note
+
+The [review-routing decision](../../.agents/notes/implemented/process/2026-09-08-trusted-changed-file-review-routing.md) records the security model, test exclusions, and alternatives.
diff --git a/.github/review-ownership/README.zh.md b/.github/review-ownership/README.zh.md
new file mode 100644
index 0000000000..a20a5f4ae4
--- /dev/null
+++ b/.github/review-ownership/README.zh.md
@@ -0,0 +1,53 @@
+# 自动请求代码评审
+
+[English](README.md) | 中文
+
+## 概要
+
+[`request-review` workflow](../workflows/request-review.yml) 从受信任的默认分支读取兼容 CODEOWNERS 格式的[所有权映射](CODEOWNERS)。它先打印完整的非测试变更文件列表，再将这些文件与 owner 匹配，最后请求尚未加入的评审者。所有权映射不在 GitHub 原生 CODEOWNERS 路径中，因此 GitHub 不会直接应用它。
+
+## 目录
+
+- [路由](#routing)
+- [排除测试](#test-exclusion)
+- [安全性](#security)
+- [验证](#verification)
+- [开发说明](#dev-note)
+
+<a id="routing"></a>
+
+## 路由
+
+非草稿 PR 在创建、同步、重新打开或标记为可评审时运行该 workflow。扫描器获取完整的 PR 文件列表，分别检查重命名前后的路径；如果只能取得部分列表，则停止执行，不发出评审请求。GitHub 对此 API 最多公开 3,000 个文件。
+
+所有权映射只接受显式绝对目录模式和 GitHub 个人用户。通配符、隐藏目录模式、团队，以及重复的模式或 owner 都会被拒绝。匹配遵循 CODEOWNERS 的最后一条匹配规则。扫描器先打印 `Changed code files`、`Excluded test files`、`Owners by changed file` 和 `Reviewers to request`，再发送评审请求。未匹配的文件仍显示在日志中。PR 作者和已经收到评审请求的用户会被排除。
+
+策略测试会统计已匹配目录下的非测试跟踪文件行数，并要求 `@turtle1999` 拥有的有效代码库不超过三分之一。
+
+<a id="test-exclusion"></a>
+
+## 排除测试
+
+评审路由会排除仓库中的单元测试、端到端测试、预期输出、快照、基准测试、性能测试、压力测试、语料测试、原生测试和 Python 测试约定。其中包括 `test`、`tests`、`__tests__`、`__snapshots__`、`benches` 和 `stress-tests` 目录，顶层 `benchmarks` 和 `snapshots` 目录树，`packages/test-support`、`scripts/fixtures` 和 `scripts/snapshots`，可识别的测试文件名后缀，以及 Python 的 `test_*.py` 或 `*_test.py` 文件。
+
+能够改变证据生成方式的测试基础设施仍需评审，包括 `vitest*.config.ts` 和 `scripts` 下的门禁实现。生产文件不会仅因名称为 `test.ts`、`spec.ts` 或 `snapshot.ts` 而被排除。
+
+<a id="security"></a>
+
+## 安全性
+
+具备写权限的 `pull_request_target` job 只检出仓库默认分支。它不会检出或执行 PR 代码，也不使用仓库 secret。PR 文件名仅作为 API 数据处理，并在日志中转义。
+
+所有权变更只有合并到默认分支后才会生效。这可以防止不受信任的 PR 为自身的 workflow 运行修改路由程序或 owner 分配。
+
+<a id="verification"></a>
+
+## 验证
+
+运行 `pnpm run test:request-review` 可检查所有权解析、测试分类、分页、日志顺序、评审者过滤和 API 行为。[Workflow 测试](../../scripts/ci-workflow.spec.ts)固定受信任检出、权限、事件和命令。仓库门禁图会在 CI 中运行这两类检查。
+
+<a id="dev-note"></a>
+
+## 开发说明
+
+[评审路由决策](../../.agents/notes/implemented/process/2026-09-08-trusted-changed-file-review-routing.zh.md)记录了安全模型、测试排除规则和备选方案。
diff --git a/.github/review-ownership/request-review.mjs b/.github/review-ownership/request-review.mjs
new file mode 100644
index 0000000000..5d71108abe
--- /dev/null
+++ b/.github/review-ownership/request-review.mjs
@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs'
+import process from 'node:process'
+import { pathToFileURL } from 'node:url'
+
+const API_VERSION = '2026-03-10'
+const MAX_PULL_REQUEST_FILES = 3_000
+const PAGE_SIZE = 100
+const TEST_DIRECTORY_NAMES = new Set(['__snapshots__', '__tests__', 'benches', 'stress-tests', 'test', 'tests'])
+const TEST_FILE_MARKER = /\.(?:bench|corpus|e2e|perf|snapshot|spec|stress|test)\.[^./]+$/u
+const PYTHON_TEST_FILE = /^(?:test_.+|.+_tests?)\.py$/u
+
+/**
+ * Parse the explicit directory subset accepted from the review ownership file.
+ * @param {string} source CODEOWNERS-compatible source text.
+ * @returns {Array<{pattern: string, prefix: string, owners: string[]}>} Ordered ownership rules.
+ */
+export function parseOwnership(source) {
+  const rules = []
+  const patterns = new Set()
+  for (const [index, rawLine] of source.split('\n').entries()) {
+    const line = rawLine.trim()
+    if (!line || line.startsWith('#')) continue
+    const [pattern, ...owners] = line.split(/\s+/u)
+    const location = `ownership line ${index + 1}`
+    if (!/^\/[^*?[\]#!\\]+\/$/u.test(pattern)) {
+      throw new Error(`${location}: expected one explicit absolute directory pattern`)
+    }
+    if (pattern.startsWith('/.')) throw new Error(`${location}: hidden-directory patterns are not allowed`)
+    if (patterns.has(pattern)) throw new Error(`${location}: duplicate pattern ${JSON.stringify(pattern)}`)
+    if (owners.length === 0) throw new Error(`${location}: expected at least one owner`)
+    const normalizedOwners = []
+    const seenOwners = new Set()
+    for (const owner of owners) {
+      if (!/^@[A-Za-z0-9-]+$/u.test(owner)) {
+        throw new Error(`${location}: only individual GitHub users are supported`)
+      }
+      const key = owner.toLowerCase()
+      if (seenOwners.has(key)) throw new Error(`${location}: duplicate owner ${owner}`)
+      seenOwners.add(key)
+      normalizedOwners.push(owner)
+    }
+    patterns.add(pattern)
+    rules.push({ pattern, prefix: pattern.slice(1), owners: normalizedOwners })
+  }
+  if (rules.length === 0) throw new Error('ownership file contains no rules')
+  return rules
+}
+
+/**
+ * Normalize a repository-relative path received from GitHub.
+ * @param {unknown} value GitHub file path.
+ * @returns {string} Slash-normalized repository path.
+ */
+export function normalizeRepositoryPath(value) {
+  if (typeof value !== 'string' || value.length === 0) throw new Error('changed file has no path')
+  const normalized = value.replaceAll('\\', '/').replace(/^\.\/+/, '')
+  if (
+    normalized.startsWith('/')
+    || normalized.includes('\0')
+    || normalized.split('/').some(segment => !segment || segment === '.' || segment === '..')
+  ) {
+    throw new Error(`invalid repository path ${JSON.stringify(value)}`)
+  }
+  return normalized
+}
+
+/**
+ * Decide whether a repository path belongs only to test evidence or test support.
+ * @param {string} value Repository-relative path.
+ * @returns {boolean} Whether reviewer routing must ignore the path.
+ */
+export function isTestPath(value) {
+  const file = normalizeRepositoryPath(value)
+  const segments = file.split('/')
+  if (segments[0] === 'benchmarks' || segments[0] === 'snapshots') return true
+  if (segments[0] === 'packages' && segments[1] === 'test-support') return true
+  if (segments[0] === 'scripts' && (segments[1] === 'fixtures' || segments[1] === 'snapshots')) return true
+  if (segments.some(segment => TEST_DIRECTORY_NAMES.has(segment))) return true
+  const basename = segments.at(-1) ?? ''
+  return TEST_FILE_MARKER.test(basename) || PYTHON_TEST_FILE.test(basename)
+}
+
+/**
+ * Expand changed-file records into reviewable and excluded repository paths.
+ * @param {unknown[]} files Pull-request file records from GitHub.
+ * @returns {{changedCodeFiles: string[], excludedTestFiles: string[]}} Classified paths.
+ */
+export function classifyChangedFiles(files) {
+  const changedCodeFiles = new Set()
+  const excludedTestFiles = new Set()
+  for (const entry of files) {
+    if (!isRecord(entry)) throw new Error('changed-file response contains a non-object entry')
+    const paths = [normalizeRepositoryPath(entry.filename)]
+    if (entry.previous_filename !== undefined) {
+      paths.unshift(normalizeRepositoryPath(entry.previous_filename))
+    }
+    for (const file of paths) {
+      if (isTestPath(file)) excludedTestFiles.add(file)
+      else changedCodeFiles.add(file)
+    }
+  }
+  return {
+    changedCodeFiles: [...changedCodeFiles].sort(),
+    excludedTestFiles: [...excludedTestFiles].sort(),
+  }
+}
+
+/**
+ * Match changed paths to owners with CODEOWNERS last-match semantics.
+ * @param {Array<{prefix: string, owners: string[]}>} rules Ordered ownership rules.
+ * @param {string[]} changedCodeFiles Reviewable repository paths.
+ * @returns {{matches: Array<{file: string, owners: string[]}>, reviewers: string[]}} Routing plan.
+ */
+export function planReviewers(rules, changedCodeFiles) {
+  const matches = []
+  const reviewers = new Map()
+  for (const file of changedCodeFiles) {
+    let owners = []
+    for (const rule of rules) {
+      if (file.startsWith(rule.prefix)) owners = rule.owners
+    }
+    matches.push({ file, owners })
+    for (const owner of owners) reviewers.set(owner.toLowerCase(), owner.slice(1))
+  }
+  return {
+    matches,
+    reviewers: [...reviewers.values()].sort((left, right) => left.localeCompare(right, 'en')),
+  }
+}
+
+/**
+ * Create a repository-scoped GitHub JSON API caller.
+ * @param {{token: string, apiUrl?: string, fetchImpl?: typeof fetch}} options API dependencies.
+ * @returns {(path: string, options?: {method?: string, body?: unknown}) => Promise<unknown>} API caller.
+ */
+export function createGitHubApi({ token, apiUrl = 'https://api.github.com', fetchImpl = globalThis.fetch }) {
+  if (!token) throw new Error('GITHUB_TOKEN is not set')
+  if (typeof fetchImpl !== 'function') throw new Error('fetch is unavailable')
+  const root = apiUrl.replace(/\/+$/u, '')
+  return async (path, { method = 'GET', body } = {}) => {
+    const response = await fetchImpl(`${root}${path}`, {
+      method,
+      headers: {
+        Accept: 'application/vnd.github+json',
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+        'User-Agent': 'deepseek-harness-request-review',
+        'X-GitHub-Api-Version': API_VERSION,
+      },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    })
+    if (!response.ok) {
+      const responseBody = await response.text()
+      throw new Error(`GitHub API ${method} ${path} returned ${response.status}: ${JSON.stringify(responseBody)}`)
+    }
+    if (response.status === 204) return undefined
+    return response.json()
+  }
+}
+
+/**
+ * Fetch the complete pull-request file list or fail before routing a partial list.
+ * @param {(path: string, options?: {method?: string, body?: unknown}) => Promise<unknown>} api GitHub API caller.
+ * @param {string} repository Owner/name repository identifier.
+ * @param {number} pullNumber Pull-request number.
+ * @param {number} expectedCount Pull-request changed-file count.
+ * @returns {Promise<unknown[]>} Complete changed-file records.
+ */
+export async function listPullRequestFiles(api, repository, pullNumber, expectedCount) {
+  if (!Number.isSafeInteger(expectedCount) || expectedCount < 0) {
+    throw new Error('pull request changed_files must be a non-negative integer')
+  }
+  if (expectedCount > MAX_PULL_REQUEST_FILES) {
+    throw new Error(`pull request has ${expectedCount} files; GitHub exposes at most ${MAX_PULL_REQUEST_FILES}`)
+  }
+  const files = []
+  for (let page = 1; files.length < expectedCount; page++) {
+    const response = await api(`/repos/${repository}/pulls/${pullNumber}/files?per_page=${PAGE_SIZE}&page=${page}`)
+    if (!Array.isArray(response) || response.length === 0) {
+      throw new Error(`GitHub returned ${files.length} of ${expectedCount} changed files`)
+    }
+    files.push(...response)
+    if (files.length > expectedCount) {
+      throw new Error(`GitHub returned ${files.length} files but the pull request reports ${expectedCount}`)
+    }
+  }
+  return files
+}
+
+/**
+ * Print changed paths, route owners, and request every missing eligible reviewer.
+ * @param {{event: unknown, ownershipSource: string, api: (path: string, options?: {method?: string, body?: unknown}) => Promise<unknown>, write?: (line: string) => void}} options Runtime inputs.
+ * @returns {Promise<{changedCodeFiles: string[], excludedTestFiles: string[], requestedReviewers: string[]}>} Applied routing result.
+ */
+export async function requestReviews({ event, ownershipSource, api, write = line => process.stdout.write(`${line}\n`) }) {
+  const pull = pullRequestFromEvent(event)
+  write('This is by automated Angry Turtle Cyborg, not a human')
+  if (pull.draft) {
+    write('Draft pull request; reviewer routing is deferred until ready_for_review.')
+    return { changedCodeFiles: [], excludedTestFiles: [], requestedReviewers: [] }
+  }
+
+  const files = await listPullRequestFiles(api, pull.repository, pull.number, pull.changedFileCount)
+  const classified = classifyChangedFiles(files)
+  const plan = planReviewers(parseOwnership(ownershipSource), classified.changedCodeFiles)
+  writeList(write, 'Changed code files', classified.changedCodeFiles.map(file => JSON.stringify(file)))
+  writeList(write, 'Excluded test files', classified.excludedTestFiles.map(file => JSON.stringify(file)))
+  writeList(
+    write,
+    'Owners by changed file',
+    plan.matches.map(({ file, owners }) => `${JSON.stringify(file)}: ${owners.length ? owners.join(' ') : '(none)'}`),
+  )
+
+  const candidates = plan.reviewers.filter(login => login.toLowerCase() !== pull.author.toLowerCase())
+  if (candidates.length === 0) {
+    writeList(write, 'Reviewers to request', [])
+    return { ...classified, requestedReviewers: [] }
+  }
+  const existing = await api(`/repos/${pull.repository}/pulls/${pull.number}/requested_reviewers`)
+  if (!isRecord(existing) || !Array.isArray(existing.users)) {
+    throw new Error('requested-reviewers response has no users array')
+  }
+  const alreadyRequested = new Set(existing.users.map((user) => {
+    if (!isRecord(user) || typeof user.login !== 'string') {
+      throw new Error('requested-reviewers response contains an invalid user')
+    }
+    return user.login.toLowerCase()
+  }))
+  const reviewers = candidates.filter(login => !alreadyRequested.has(login.toLowerCase()))
+  writeList(write, 'Reviewers to request', reviewers.map(login => `@${login}`))
+  if (reviewers.length === 0) return { ...classified, requestedReviewers: [] }
+
+  await api(`/repos/${pull.repository}/pulls/${pull.number}/requested_reviewers`, {
+    method: 'POST',
+    body: { reviewers },
+  })
+  write(`Requested ${reviewers.map(login => `@${login}`).join(' ')}.`)
+  return { ...classified, requestedReviewers: reviewers }
+}
+
+function pullRequestFromEvent(event) {
+  if (!isRecord(event) || !isRecord(event.repository) || typeof event.repository.full_name !== 'string') {
+    throw new Error('event has no repository.full_name')
+  }
+  if (!isRecord(event.pull_request) || !isRecord(event.pull_request.user)) {
+    throw new Error('event has no pull_request')
+  }
+  const { pull_request: pull } = event
+  if (!Number.isSafeInteger(pull.number) || pull.number <= 0) throw new Error('pull request has no valid number')
+  if (typeof pull.draft !== 'boolean') throw new Error('pull request has no draft flag')
+  if (typeof pull.user.login !== 'string' || !pull.user.login) throw new Error('pull request has no author login')
+  return {
+    repository: event.repository.full_name,
+    number: pull.number,
+    draft: pull.draft,
+    author: pull.user.login,
+    changedFileCount: pull.changed_files,
+  }
+}
+
+function writeList(write, title, entries) {
+  write(`${title}:`)
+  if (entries.length === 0) write('- (none)')
+  else for (const entry of entries) write(`- ${entry}`)
+}
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+async function main() {
+  const eventPath = process.env.GITHUB_EVENT_PATH
+  if (!eventPath) throw new Error('GITHUB_EVENT_PATH is not set')
+  const event = JSON.parse(readFileSync(eventPath, 'utf8'))
+  const ownershipSource = readFileSync(new URL('CODEOWNERS', import.meta.url), 'utf8')
+  const api = createGitHubApi({
+    token: process.env.GITHUB_TOKEN ?? '',
+    apiUrl: process.env.GITHUB_API_URL,
+  })
+  await requestReviews({ event, ownershipSource, api })
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    process.stderr.write(`request-review failed: ${error instanceof Error ? error.message : String(error)}\n`)
+    process.exitCode = 1
+  })
+}
diff --git a/.github/review-ownership/request-review.test.mjs b/.github/review-ownership/request-review.test.mjs
new file mode 100644
index 0000000000..79a44d7fd5
--- /dev/null
+++ b/.github/review-ownership/request-review.test.mjs
@@ -0,0 +1,335 @@
+import assert from 'node:assert/strict'
+import { execFileSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import test from 'node:test'
+
+import {
+  classifyChangedFiles,
+  createGitHubApi,
+  isTestPath,
+  listPullRequestFiles,
+  normalizeRepositoryPath,
+  parseOwnership,
+  planReviewers,
+  requestReviews,
+} from './request-review.mjs'
+
+const ownershipSource = readFileSync(new URL('CODEOWNERS', import.meta.url), 'utf8')
+
+const pullRequestEvent = ({ author = 'author', changedFiles = 1, draft = false } = {}) => ({
+  repository: { full_name: 'deepseek-harness/deepseek-harness' },
+  pull_request: {
+    number: 42,
+    draft,
+    changed_files: changedFiles,
+    user: { login: author },
+  },
+})
+
+test('loads the repository ownership policy without test-only directory rules', () => {
+  const rules = parseOwnership(ownershipSource)
+  const ownersByPattern = new Map(rules.map(rule => [rule.pattern, rule.owners]))
+  assert.equal(rules.length, 58)
+  assert.equal(rules.some(rule => rule.pattern === '/benchmarks/'), false)
+  assert.equal(rules.some(rule => rule.pattern === '/snapshots/'), false)
+  assert.equal(rules.some(rule => rule.pattern === '/packages/test-support/'), false)
+  assert.deepEqual(ownersByPattern.get('/apps/cli/'), ['@turtle1999'])
+  assert.deepEqual(ownersByPattern.get('/docs/'), ['@turtle1999'])
+  assert.deepEqual(ownersByPattern.get('/packages/core/'), ['@tianyicui', '@turtle1999', '@mektpoy'])
+  assert.deepEqual(ownersByPattern.get('/packages/llm/'), ['@LegGasai'])
+  assert.deepEqual(ownersByPattern.get('/packages/preset/'), ['@LegGasai', '@turtle1999'])
+  assert.deepEqual(ownersByPattern.get('/packages/session/'), ['@tianyicui', '@turtle1999', '@mektpoy'])
+  assert.deepEqual(ownersByPattern.get('/packages/subagent/'), ['@Dudu-0223'])
+  assert.deepEqual(ownersByPattern.get('/packages/web/'), ['@imccyu'])
+  assert.deepEqual(ownersByPattern.get('/python/'), ['@LegGasai'])
+  assert.deepEqual(ownersByPattern.get('/website/'), ['@LegGasai'])
+  assert.deepEqual(
+    rules.filter(rule => rule.owners.includes('@tianyicui')).map(rule => rule.pattern),
+    ['/packages/core/', '/packages/session/'],
+  )
+  for (const excludedOwner of ['@kermeanx', '@pkh-xht']) {
+    assert.equal(rules.some(rule => rule.owners.some(owner => owner.toLowerCase() === excludedOwner)), false)
+  }
+})
+
+test('keeps turtle below one third of the eligible owned codebase', () => {
+  const rules = parseOwnership(ownershipSource)
+  const trackedFiles = execFileSync('git', ['ls-files', '-z'], { encoding: 'utf8' }).split('\0').filter(Boolean)
+  let ownedLines = 0
+  let turtleLines = 0
+  for (const file of trackedFiles) {
+    if (isTestPath(file)) continue
+    const owners = planReviewers(rules, [file]).matches[0]?.owners ?? []
+    if (owners.length === 0) continue
+    const content = readFileSync(file)
+    const lines = content.length === 0
+      ? 0
+      : content.reduce((count, byte) => count + (byte === 10 ? 1 : 0), 0) + (content.at(-1) === 10 ? 0 : 1)
+    ownedLines += lines
+    if (owners.includes('@turtle1999')) turtleLines += lines
+  }
+  assert.ok(
+    turtleLines * 3 <= ownedLines,
+    `@turtle1999 owns ${turtleLines} of ${ownedLines} eligible owned lines`,
+  )
+})
+
+test('rejects ownership forms the requester cannot apply safely', () => {
+  for (const [source, message] of [
+    ['', /contains no rules/u],
+    ['* @owner\n', /explicit absolute directory/u],
+    ['/.github/ @owner\n', /hidden-directory/u],
+    ['/packages/*/ @owner\n', /explicit absolute directory/u],
+    ['/packages/core/\n', /at least one owner/u],
+    ['/packages/core/ @org/team\n', /individual GitHub users/u],
+    ['/packages/core/ @owner @OWNER\n', /duplicate owner/u],
+    ['/packages/core/ @owner\n/packages/core/ @other\n', /duplicate pattern/u],
+  ]) {
+    assert.throws(() => parseOwnership(source), message)
+  }
+})
+
+test('recognizes every repository test location and filename convention', () => {
+  for (const file of [
+    'apps/cli/tests/args.spec.ts',
+    'apps/cli/tests/harness.ts',
+    'apps/web/stress-tests/reasoning-chunks.stress.ts',
+    'benchmarks/session-open/workload.ts',
+    'native/landlock-run/test/entry.test.js',
+    'packages/core/agent/__tests__/agent.ts',
+    'packages/core/agent/benches/agent.rs',
+    'packages/core/agent/src/agent.compat.spec.ts',
+    'packages/core/agent/src/__snapshots__/agent.ts.snap',
+    'packages/session-query/session-query/tests/test-service.ts',
+    'packages/test-support/session-snapshot/src/index.ts',
+    'python/sdk/src/test_client.py',
+    'python/sdk/src/client_test.py',
+    'scripts/fixtures/translation-prompt/response.txt',
+    'scripts/session-snapshot-corpus.corpus.ts',
+    'scripts/snapshots/translation-prompt-v4/request-response.expected.json',
+    'snapshots/session/headless.snapshot.ts',
+  ]) {
+    assert.equal(isTestPath(file), true, file)
+  }
+})
+
+test('does not confuse production names with tests', () => {
+  for (const file of [
+    'apps/cli/src/testing.ts',
+    'packages/core/agent/src/contest.ts',
+    'packages/session/session-format/src/snapshot.ts',
+    'packages/session/session-format/src/spec.ts',
+    'packages/session/session-format/src/test.ts',
+    'scripts/run-gates.ts',
+    'vitest.config.ts',
+    'vitest.bench.config.ts',
+    'vitest.e2e.config.ts',
+    'vitest.snapshot.config.ts',
+    'vitest.web.perf.config.ts',
+    'website/docs.ts',
+  ]) {
+    assert.equal(isTestPath(file), false, file)
+  }
+})
+
+test('normalizes separators and rejects paths that are not repository-relative', () => {
+  assert.equal(normalizeRepositoryPath('./packages\\core\\agent\\src\\index.ts'), 'packages/core/agent/src/index.ts')
+  for (const file of ['', '/absolute.ts', '../escape.ts', 'packages//empty.ts', 'packages/./same.ts']) {
+    assert.throws(() => normalizeRepositoryPath(file), /path/u, file)
+  }
+})
+
+test('classifies both sides of a rename independently', () => {
+  assert.deepEqual(
+    classifyChangedFiles([
+      {
+        filename: 'packages/core/agent/tests/moved.spec.ts',
+        previous_filename: 'packages/core/agent/src/moved.ts',
+      },
+      {
+        filename: 'packages/client/store/src/restored.ts',
+        previous_filename: 'packages/client/store/tests/restored.spec.ts',
+      },
+    ]),
+    {
+      changedCodeFiles: [
+        'packages/client/store/src/restored.ts',
+        'packages/core/agent/src/moved.ts',
+      ],
+      excludedTestFiles: [
+        'packages/client/store/tests/restored.spec.ts',
+        'packages/core/agent/tests/moved.spec.ts',
+      ],
+    },
+  )
+})
+
+test('uses the last matching ownership rule and keeps unmatched files visible', () => {
+  const rules = parseOwnership('/packages/ @broad\n/packages/core/ @core @second\n')
+  assert.deepEqual(
+    planReviewers(rules, ['AGENTS.md', 'packages/core/agent/src/index.ts', 'packages/fs/fs/src/index.ts']),
+    {
+      matches: [
+        { file: 'AGENTS.md', owners: [] },
+        { file: 'packages/core/agent/src/index.ts', owners: ['@core', '@second'] },
+        { file: 'packages/fs/fs/src/index.ts', owners: ['@broad'] },
+      ],
+      reviewers: ['broad', 'core', 'second'],
+    },
+  )
+})
+
+test('fetches every declared changed file across pages', async () => {
+  const calls = []
+  const pageOne = Array.from({ length: 100 }, (_, index) => ({ filename: `packages/core/file-${index}.ts` }))
+  const pageTwo = [{ filename: 'packages/core/file-100.ts' }]
+  const api = async (path) => {
+    calls.push(path)
+    return calls.length === 1 ? pageOne : pageTwo
+  }
+  const files = await listPullRequestFiles(api, 'owner/repo', 42, 101)
+  assert.equal(files.length, 101)
+  assert.deepEqual(calls, [
+    '/repos/owner/repo/pulls/42/files?per_page=100&page=1',
+    '/repos/owner/repo/pulls/42/files?per_page=100&page=2',
+  ])
+})
+
+test('fails closed when GitHub cannot provide the complete file list', async () => {
+  let calls = 0
+  await assert.rejects(
+    listPullRequestFiles(async () => {
+      calls++
+      return calls === 1 ? [{ filename: 'one.ts' }] : []
+    }, 'owner/repo', 42, 2),
+    /returned 1 of 2/u,
+  )
+  await assert.rejects(
+    listPullRequestFiles(async () => [], 'owner/repo', 42, 3_001),
+    /at most 3000/u,
+  )
+})
+
+test('prints changed code files before requesting missing owners', async () => {
+  const trace = []
+  const files = [
+    { filename: 'packages/core/agent/src/index.ts' },
+    { filename: 'packages/preset/agent-presets/src/index.ts' },
+    { filename: 'packages/client/store/src/index.ts' },
+    { filename: 'packages/subagent/subagent/src/index.ts' },
+    { filename: 'packages/core/agent/tests/index.spec.ts' },
+    { filename: 'AGENTS.md' },
+  ]
+  const api = async (path, options = {}) => {
+    trace.push({ type: 'api', path, options })
+    if (path.endsWith('/files?per_page=100&page=1')) return files
+    if (path.endsWith('/requested_reviewers') && options.method !== 'POST') {
+      return { users: [{ login: 'imccyu' }], teams: [] }
+    }
+    if (path.endsWith('/requested_reviewers') && options.method === 'POST') return {}
+    throw new Error(`unexpected API path ${path}`)
+  }
+
+  const result = await requestReviews({
+    event: pullRequestEvent({ author: 'turtle1999', changedFiles: files.length }),
+    ownershipSource,
+    api,
+    write: line => trace.push({ type: 'log', line }),
+  })
+
+  assert.deepEqual(result, {
+    changedCodeFiles: [
+      'AGENTS.md',
+      'packages/client/store/src/index.ts',
+      'packages/core/agent/src/index.ts',
+      'packages/preset/agent-presets/src/index.ts',
+      'packages/subagent/subagent/src/index.ts',
+    ],
+    excludedTestFiles: ['packages/core/agent/tests/index.spec.ts'],
+    requestedReviewers: ['Dudu-0223', 'LegGasai', 'mektpoy', 'tianyicui'],
+  })
+  assert.equal(trace[0].type, 'log')
+  assert.equal(trace[0].line, 'This is by automated Angry Turtle Cyborg, not a human')
+  const changedHeading = trace.findIndex(item => item.type === 'log' && item.line === 'Changed code files:')
+  const post = trace.findIndex(item => item.type === 'api' && item.options.method === 'POST')
+  assert.ok(changedHeading >= 0 && changedHeading < post)
+  assert.deepEqual(trace[post], {
+    type: 'api',
+    path: '/repos/deepseek-harness/deepseek-harness/pulls/42/requested_reviewers',
+    options: {
+      method: 'POST',
+      body: { reviewers: ['Dudu-0223', 'LegGasai', 'mektpoy', 'tianyicui'] },
+    },
+  })
+})
+
+test('does not request reviewers for a test-only change', async () => {
+  const calls = []
+  const output = []
+  const files = [
+    { filename: 'apps/web/tests/chat.e2e.ts' },
+    { filename: 'packages/core/agent/tests/agent.spec.ts' },
+  ]
+  const result = await requestReviews({
+    event: pullRequestEvent({ changedFiles: files.length }),
+    ownershipSource,
+    api: async (path) => {
+      calls.push(path)
+      return files
+    },
+    write: line => output.push(line),
+  })
+  assert.deepEqual(result, {
+    changedCodeFiles: [],
+    excludedTestFiles: files.map(file => file.filename),
+    requestedReviewers: [],
+  })
+  assert.equal(calls.length, 1)
+  assert.deepEqual(output.slice(0, 4), [
+    'This is by automated Angry Turtle Cyborg, not a human',
+    'Changed code files:',
+    '- (none)',
+    'Excluded test files:',
+  ])
+})
+
+test('defers draft pull requests without reading changed files', async () => {
+  const output = []
+  const result = await requestReviews({
+    event: pullRequestEvent({ draft: true }),
+    ownershipSource,
+    api: async () => assert.fail('draft routing must not call GitHub'),
+    write: line => output.push(line),
+  })
+  assert.deepEqual(result, { changedCodeFiles: [], excludedTestFiles: [], requestedReviewers: [] })
+  assert.deepEqual(output, [
+    'This is by automated Angry Turtle Cyborg, not a human',
+    'Draft pull request; reviewer routing is deferred until ready_for_review.',
+  ])
+})
+
+test('sends authenticated JSON and escapes an API error body', async () => {
+  const requests = []
+  const api = createGitHubApi({
+    token: 'secret',
+    apiUrl: 'https://github.example/api/v3/',
+    fetchImpl: async (url, options) => {
+      requests.push({ url, options })
+      return new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    },
+  })
+  assert.deepEqual(await api('/repos/owner/repo', { method: 'POST', body: { value: 1 } }), { ok: true })
+  assert.equal(requests[0].url, 'https://github.example/api/v3/repos/owner/repo')
+  assert.equal(requests[0].options.headers.Authorization, 'Bearer secret')
+  assert.equal(requests[0].options.headers['X-GitHub-Api-Version'], '2026-03-10')
+  assert.equal(requests[0].options.body, '{"value":1}')
+
+  const failing = createGitHubApi({
+    token: 'secret',
+    fetchImpl: async () => new Response('::error::untrusted\nbody', { status: 422 }),
+  })
+  await assert.rejects(failing('/failure'), /"::error::untrusted\\nbody"/u)
+})
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 0eaa6f6335..4e05b444a4 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -50,6 +50,11 @@ jobs:
       # does not keep burning enterprise runner time on the remaining gates.
       DSH_GATE_FAIL_FAST: '1'
     steps:
+      # Runner cleanup owns tool caches and fixtures, including cancelled runs.
+      - name: Use runner-owned temporary storage
+        run: |
+          echo "TMPDIR=${{ runner.temp }}" >> "$GITHUB_ENV"
+
       # Fetch complete history so the archive gate can read the trusted PR base from a reused shallow checkout.
       - uses: actions/checkout@v6
         with:
@@ -115,6 +120,11 @@ jobs:
       # multi-minute instrumented run.
       DSH_GATE_FAIL_FAST: '1'
     steps:
+      # Runner cleanup owns tool caches and fixtures, including cancelled runs.
+      - name: Use runner-owned temporary storage
+        run: |
+          echo "TMPDIR=${{ runner.temp }}" >> "$GITHUB_ENV"
+
       - uses: actions/checkout@v6
         with:
           persist-credentials: false
@@ -141,9 +151,8 @@ jobs:
           store_path=$(PNPM_CONFIG_STORE_DIR="$store_root" pnpm store path --silent)
           echo "path=$store_path" >> "$GITHUB_OUTPUT"
 
-      # Skipped under failover: the self-hosted VM's persistent pnpm store
-      # already serves warm installs, while restoring the hosted archive
-      # would spend ~52 s pulling ~180 MB into that populated store.
+      # Self-hosted runners reuse the shared persistent pnpm store.
+      # Hosted runners restore the remote cache into their ephemeral store.
       - uses: actions/cache/restore@v4
         if: vars.DSH_CI_FAILOVER_LINUX != 'selfhosted' || github.event.pull_request.user.login == 'dependabot[bot]'
         with:
@@ -235,6 +244,12 @@ jobs:
       # Failover halves snapshot concurrency for the shared 64-core VM.
       DSH_SNAPSHOT_MAX_CONCURRENCY: ${{ vars.DSH_CI_FAILOVER_LINUX == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && '12' || '32' }}
     steps:
+      # Runner cleanup owns tool caches and fixtures, including cancelled runs.
+      - name: Use runner-owned temporary storage
+        run: |
+          echo "TMPDIR=${{ runner.temp }}" >> "$GITHUB_ENV"
+          echo "PLAYWRIGHT_BROWSERS_PATH=${RUNNER_TEMP%/*}/ms-playwright" >> "$GITHUB_ENV"
+
       - uses: actions/checkout@v6
         with:
           persist-credentials: false
@@ -264,8 +279,8 @@ jobs:
       # Pull requests restore the pnpm store and Playwright caches without paying
       # compression and upload on the required path. No master job saves these
       # hosted cache keys, so each restore-keys fallback hits the matching archived
-      # entry until it evicts, after which the store is cold. Skipped under failover
-      # — the self-hosted VM's persistent store is already warm.
+      # entry until it evicts, after which the store is cold. Self-hosted runners
+      # reuse the shared persistent store instead of restoring the remote archive.
       - uses: actions/cache/restore@v4
         if: vars.DSH_CI_FAILOVER_LINUX != 'selfhosted' || github.event.pull_request.user.login == 'dependabot[bot]'
         with:
@@ -274,11 +289,11 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-
 
-      # Skipped under failover: the VM's persistent browser cache is already warm.
+      # Self-hosted runners retain their own browser cache between jobs.
       - uses: actions/cache/restore@v4
         if: vars.DSH_CI_FAILOVER_LINUX != 'selfhosted' || github.event.pull_request.user.login == 'dependabot[bot]'
         with:
-          path: ~/.cache/ms-playwright
+          path: ${{ env.PLAYWRIGHT_BROWSERS_PATH }}
           key: ${{ runner.os }}-playwright-${{ hashFiles('pnpm-lock.yaml') }}
           restore-keys: |
             ${{ runner.os }}-playwright-
diff --git a/.github/workflows/request-review.yml b/.github/workflows/request-review.yml
new file mode 100644
index 0000000000..0d202b3288
--- /dev/null
+++ b/.github/workflows/request-review.yml
@@ -0,0 +1,32 @@
+name: request-review
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: request-review-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  request-review:
+    name: request-review
+    if: ${{ !github.event.pull_request.draft }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      # SECURITY: the write-capable job executes policy from the trusted default
+      # branch and reads pull-request filenames only as API data.
+      - name: Check out trusted review policy
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+      - name: Request reviewers
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: node .github/review-ownership/request-review.mjs
diff --git a/apps/cli/README.i18n.yaml b/apps/cli/README.i18n.yaml
index 405b42e28f..aa5c385a7e 100644
--- a/apps/cli/README.i18n.yaml
+++ b/apps/cli/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write apps/cli/README.md
-README.md: adab66bb1d7ed46039248a57c8722964f5aebd33
-README.zh.md: 4887a67872a569a0a54f0378aaceffe51cdc43c1
+README.md: 2e74ef68cf0b8487083a2e2af0f5175c78ec5212
+README.zh.md: 85a75f4c025e1bfe1461b9ffdaca533d308318ba
diff --git a/apps/cli/README.md b/apps/cli/README.md
index adab66bb1d..2e74ef68cf 100644
--- a/apps/cli/README.md
+++ b/apps/cli/README.md
@@ -9,6 +9,7 @@ The `dsh` command is the sole supported Node application launcher: profiles are
 | Command | Purpose |
 |---|---|
 | `dsh --profile <name>` | Boot the named profile under `$DSH_HOME/profiles/<name>`. |
+| `dsh --profile <name> --from-default-profile <template>` | Create a new custom profile from a shipped template, then boot it. |
 | `dsh --profile acp` | Serve automation clients over ACP stdio until disconnect. |
 | `dsh --profile headless "job"` | Run one fresh persisted session, print the final answer, and exit. |
 | `dsh --profile sdk` | Serve SDK clients over JSON-RPC stdio until shutdown or disconnect. |
@@ -16,7 +17,7 @@ The `dsh` command is the sole supported Node application launcher: profiles are
 | `dsh web` | Alias of `--profile web`. |
 | `dsh plugin --profile <name> <pnpm args>` | Manage a profile's plugins by forwarding to pnpm in the profile directory. |
 
-The invoking directory is the default workspace root. The `web`, `headless`, `sdk`, `sdk-minimal`, and `acp` profiles auto-initialize on first use from shipped templates; any other profile must be created through `dsh plugin`. The `desktop` name is reserved for the Electron-owned profile, so the CLI rejects boot, config-dump, and plugin-management requests for it.
+The invoking directory is the default workspace root. The `web`, `headless`, `sdk`, `sdk-minimal`, and `acp` profiles auto-initialize on first use from shipped templates. Create another profile at an unused, non-shipped name with `--from-default-profile`, or initialize a base-backed profile through `dsh plugin`. The `desktop` name is reserved for the Electron-owned profile, so the CLI rejects boot, config-dump, and plugin-management requests for it.
 
 ## App arguments
 
diff --git a/apps/cli/README.zh.md b/apps/cli/README.zh.md
index 4887a67872..85a75f4c02 100644
--- a/apps/cli/README.zh.md
+++ b/apps/cli/README.zh.md
@@ -9,6 +9,7 @@
 | 命令 | 用途 |
 |---|---|
 | `dsh --profile <name>` | 启动位于 `$DSH_HOME/profiles/<name>` 的指定 profile。 |
+| `dsh --profile <name> --from-default-profile <template>` | 从随附模板创建新的自定义 profile，然后启动它。 |
 | `dsh --profile acp` | 通过 ACP stdio 为自动化 client 提供服务，直至断开连接。 |
 | `dsh --profile headless "job"` | 运行一个全新的持久化会话，打印最终答案并退出。 |
 | `dsh --profile sdk` | 通过 JSON-RPC stdio 为 SDK client 提供服务，直至关闭或断开连接。 |
@@ -16,7 +17,7 @@
 | `dsh web` | `--profile web` 的别名。 |
 | `dsh plugin --profile <name> <pnpm args>` | 通过在 profile 目录中转发给 pnpm 来管理该 profile 的插件。 |
 
-运行命令时所在的目录将作为默认 workspace 根目录。`web`、`headless`、`sdk`、`sdk-minimal` 和 `acp` profile 在首次使用时会从随附模板自动初始化；其他任何 profile 都必须通过 `dsh plugin` 创建。`desktop` 名称保留给 Electron 持有的 profile，因此 CLI 会拒绝针对它的启动、配置 dump 和插件管理请求。
+运行命令时所在的目录将作为默认 workspace 根目录。`web`、`headless`、`sdk`、`sdk-minimal` 和 `acp` profile 在首次使用时会从随附模板自动初始化。使用 `--from-default-profile` 可以基于这些模板之一，在尚未使用的非内置名称处创建其他 profile；通过 `dsh plugin` 则可以初始化一个以 base 为基础的 profile。`desktop` 名称保留给 Electron 持有的 profile，因此 CLI 会拒绝针对它的启动、配置 dump 和插件管理请求。
 
 ## 应用参数
 
diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml
index 77aed3f65b..ae963e570a 100644
--- a/apps/cli/reference/README.i18n.yaml
+++ b/apps/cli/reference/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write apps/cli/reference/README.md
-README.md: 74c47df37903761c3d4b231473ecf9409175679c
-README.zh.md: fc477f9874670d0f18f164227a1b86b7ae538aa7
+README.md: 99ef8310cd1316e9ee4ade55fcac00766ae1e821
+README.zh.md: aa446d539a5b666e7745f459b5a014b22e72f90e
diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md
index 74c47df379..99ef8310cd 100644
--- a/apps/cli/reference/README.md
+++ b/apps/cli/reference/README.md
@@ -12,9 +12,18 @@ Bundle names resolve from the dsh installation first, then from the profile dire
 
 The `web`, `headless`, `sdk`, `sdk-minimal`, and `acp` profiles auto-initialize from shipped templates on first use (`web`: base + web-app with live patches; `headless`: base + headless with startup-only patches; `sdk`: base + sdk-app with startup-only patches; `sdk-minimal`: its standalone bundle with startup-only patches; `acp`: base + acp-app with startup-only patches). Any other missing profile fails loud with a hint to run `dsh plugin --profile <name> add <package>`.
 
+`dsh --profile <name> --from-default-profile <template>` initializes a new custom target from one of those five shipped templates before boot. The target name cannot be a shipped profile name, and its complete profile directory must not exist. The launcher claims that directory exclusively, so residual files and another concurrent creator are rejected without modification. It copies the template's current bundle list and `patchReload` value into a new manifest with empty dependencies and an empty user patch. It does not read the local profile named by `<template>`, copy its dependencies or patch, or persist an inheritance field; later template-list changes do not rewrite the new profile. The in-box bundles named by that copied list still resolve from the current dsh installation. A successful initialization adds no launcher output.
+
+An existing profile rejects `--from-default-profile` without changing or booting it; omit the option to use it. A residual target directory is also preserved and requires a different profile name. An unknown template or a shipped target name fails before creating the target. Unknown-template diagnostics name the valid templates. Initialization is committed before bundle resolution and application boot, so a later failure leaves the new profile on disk and the retry omits the creation option. `--dump-config` and `--dump-default-config` accept the option, initialize the target, print the requested tree, and do not boot it.
+
+```sh
+dsh --profile rescue --from-default-profile web
+dsh --profile rescue
+```
+
 ### App arguments
 
-The launcher's flags come first and end at the first token it does not recognize; everything from there on is handed to the booted profile verbatim through `ctx.cmdlineArgs`, where any injected app plugin may parse it ([`dsh-cmdline`](../../../packages/boot/cmdline/README.md)). `dsh --profile web --port 8080` therefore reaches the web app's `--port`, `dsh --profile web --help` prints that app's help and boots nothing, and `dsh --help` (no profile to hand it to) prints the launcher's own. `-V`/`--version` prints the launcher's version when it appears before the app-argument boundary.
+The launcher's flags come first and end at the first token it does not recognize; everything from there on is handed to the booted profile verbatim through `ctx.cmdlineArgs`, where any injected app plugin may parse it ([`dsh-cmdline`](../../../packages/boot/cmdline/README.md)). `dsh --profile rescue --from-default-profile web --no-open` therefore initializes before handing `--no-open` to Web, `dsh --profile web --port 8080` reaches the web app's `--port`, `dsh --profile web --help` prints that app's help and boots nothing, and `dsh --help` (no profile to hand it to) prints the launcher's own. `-V`/`--version` prints the launcher's version when it appears before the app-argument boundary.
 
 A composition mounts once. An ordinary plugin injects `cmdlineArgs`, parses this app's arguments, and provides what it resolved as a service; each row configured from flags injects that service, and Loader waits for it before evaluating the row's config (`port: !!js ctx.webStartup.port ?? 3080`). A flag therefore beats the value written beside it. This precedence requires the row to retain that expression; a user patch that replaces the whole `config` with literals removes the runtime read. Help and rejected arguments request exit — nonzero for a rejection, 0 for help — without activating rows that depend on the provider's service. In a `patchReload: live` profile, a patch-file edit re-evaluates expressions against services that are still up, so it cannot reset a served port.
 
diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md
index fc477f9874..aa446d539a 100644
--- a/apps/cli/reference/README.zh.md
+++ b/apps/cli/reference/README.zh.md
@@ -4,6 +4,8 @@
 
 本参考定义 profile 启动、web 别名、插件管理和配置 dump 等命令模式。argv 由 [`src/args.ts`](../src/args.ts) 统一解析一次，[`src/bin.ts`](../src/bin.ts) 只会动态导入选中的运行器。
 
+<a id="profile-boot"></a>
+
 ## Profile 启动
 
 `dsh --profile <name>` 启动位于 `$DSH_HOME/profiles/<name>` 的 profile。生效配置树以空根节点为起点，依次叠加 profile manifest（元数据清单）的 `dsh.profile.bundles` 列表中指定的各组合包 patch、profile 自身的 `cordis.patch.yml`、home 级的 `$DSH_HOME/cordis.patch.yml`（这是各 profile 共享的机器本地偏好，因此优先于逐 profile 配置层），以及按 argv 顺序指定的各个 `--patch <path>` 覆盖层。对同一配置行，后应用的层优先。patch 会替换目标行的整个 `config` 值，而不是深度合并其中的键；patch 也可以插入新行。`dsh.profile.patchReload` 可选择 `live` patch 文件监视或 `startup` 单次加载；自定义 profile 省略该值时默认使用 `live`。配置解析、schema 校验、模块解析或插件启动失败时，系统会报告错误并以非零状态退出。收到 SIGINT 或 SIGTERM 时，挂载的根节点会先 dispose（资源释放）再退出。
@@ -12,9 +14,18 @@
 
 `web`、`headless`、`sdk`、`sdk-minimal` 和 `acp` profile 首次使用时会从随附模板自动初始化（`web`：base + web-app，实时应用 patch；`headless`：base + headless，只在启动时应用 patch；`sdk`：base + sdk-app，只在启动时应用 patch；`sdk-minimal`：独立组合包，只在启动时应用 patch；`acp`：base + acp-app，只在启动时应用 patch）。其他缺失的 profile 会显式报错，并提示运行 `dsh plugin --profile <name> add <package>`。
 
+`dsh --profile <name> --from-default-profile <template>` 会在启动前，从上述五个随附模板之一初始化新的自定义目标。目标名称不能是随附 profile 名称，并且完整的目标 profile 目录必须不存在。launcher 会以独占方式领取该目录，因此残留文件和另一个并发创建者都会在不作修改的情况下被拒绝。它把模板当前的 bundle 列表和 `patchReload` 值复制进一份依赖为空、用户 patch 为空的新 manifest。它不会读取 `<template>` 指定的本地同名 profile，不会复制其依赖或 patch，也不会持久化继承字段；模板列表之后的变化不会改写新 profile。复制列表中指名的内置 bundle 仍从当前 dsh 安装目录解析。初始化成功不会增加 launcher 输出。
+
+profile 已经存在时，`--from-default-profile` 会被拒绝，且不会修改或启动它；去掉该选项即可使用它。残留的目标目录同样会被原样保留，此时必须改用另一个 profile 名称。未知模板或随附目标名称会在创建目标之前失败；未知模板的诊断会列出有效模板。初始化在 bundle 解析和应用启动之前提交，因此后续失败仍会把新 profile 留在磁盘上，重试时需要去掉创建选项。`--dump-config` 和 `--dump-default-config` 接受该选项：它们初始化目标并打印所请求的配置树，但不启动应用。
+
+```sh
+dsh --profile rescue --from-default-profile web
+dsh --profile rescue
+```
+
 ### 应用参数
 
-启动器自身的 flag 必须写在最前面，并在遇到第一个无法识别的 token 时结束；从该 token 开始的所有内容都会通过 `ctx.cmdlineArgs` 原样交给已启动的 profile，注入该 profile 的任意应用插件都可以解析这些内容（[`dsh-cmdline`](../../../packages/boot/cmdline/README.zh.md)）。因此，`dsh --profile web --port 8080` 会将 `--port` 交给 web 应用；`dsh --profile web --help` 只打印该应用的帮助信息，不启动应用；`dsh --help` 没有可供交付参数的 profile，因此会打印启动器自身的帮助信息。`-V`/`--version` 位于应用参数边界之前时，会打印启动器的版本。
+启动器自身的 flag 必须写在最前面，并在遇到第一个无法识别的 token 时结束；从该 token 开始的所有内容都会通过 `ctx.cmdlineArgs` 原样交给已启动的 profile，注入该 profile 的任意应用插件都可以解析这些内容（[`dsh-cmdline`](../../../packages/boot/cmdline/README.zh.md)）。因此，`dsh --profile rescue --from-default-profile web --no-open` 会先初始化，再把 `--no-open` 交给 Web；`dsh --profile web --port 8080` 会将 `--port` 交给 web 应用；`dsh --profile web --help` 只打印该应用的帮助信息，不启动应用；`dsh --help` 没有可供交付参数的 profile，因此会打印启动器自身的帮助信息。`-V`/`--version` 位于应用参数边界之前时，会打印启动器的版本。
 
 每套组合只会挂载一次。普通插件注入 `cmdlineArgs`，解析所属应用的参数，并将解析结果作为服务提供。每个从 flag 取值的配置行都会注入该服务；Loader 会等到服务激活后，再对该行的配置求值（`port: !!js ctx.webStartup.port ?? 3080`），因此 flag 的优先级高于配置行中写明的值。要维持这一优先级，配置行必须保留该表达式；如果用户 patch 用字面量替换整个 `config`，也会随之移除运行时读取。帮助参数和被拒绝的参数都会请求退出：参数被拒绝时以非零状态退出，显示帮助时以 0 退出；依赖该提供方服务的配置行不会激活。在 `patchReload: live` profile 中，编辑 patch 文件会根据仍在运行的服务重新计算表达式，因此不会重置当前正在使用的端口。
 
diff --git a/apps/cli/src/args.ts b/apps/cli/src/args.ts
index 1894f073c6..b8e56b79fc 100644
--- a/apps/cli/src/args.ts
+++ b/apps/cli/src/args.ts
@@ -21,6 +21,8 @@ import { Command, CommanderError } from 'commander'
 interface ProfileInvocation {
   mode: 'profile'
   profile: string
+  /** Shipped template used once to initialize a missing profile. */
+  fromDefaultProfile?: string | undefined
   /** Extra patch-list overlays applied after the profile's own layer, in argv order. */
   patches: string[]
   /** Everything after the launcher's own flags, verbatim, for injected app plugins. */
@@ -31,6 +33,8 @@ interface ProfileInvocation {
 interface DumpConfigInvocation {
   mode: 'dump-config'
   profile: string
+  /** Shipped template used once to initialize a missing profile. */
+  fromDefaultProfile?: string | undefined
   /** Omit the profile's user layer and --patch overlays; print bundle layers only. */
   defaultOnly: boolean
   patches: string[]
@@ -52,6 +56,7 @@ interface BootOptions {
   patch?: string[]
   dumpConfig?: boolean
   dumpDefaultConfig?: boolean
+  fromDefaultProfile?: string
 }
 
 /**
@@ -70,6 +75,8 @@ function rejectElectronProfile(program: Command, profile: string): void {
 const HELP_EXAMPLES = `
 Examples:
   dsh --profile web                          boot the web profile (same as: dsh web)
+  dsh --profile rescue --from-default-profile web
+                                             create rescue from the shipped web template, then boot it
   dsh --profile headless "run the tests"     answer one task, print the result, and exit
   dsh --profile tui --patch ./extra.yml      boot a custom profile with one extra overlay
   dsh --profile tui --resume <session>       arguments after the launcher flags reach the app
@@ -89,8 +96,9 @@ Examples:
 function resolveBoot(program: Command, profile: string, options: BootOptions, args: string[]): DshInvocation {
   const patches = options.patch ?? []
   if (patches.includes('')) program.error('error: --patch needs a path')
+  if (options.fromDefaultProfile === '') program.error('error: --from-default-profile needs a name')
   if (options.dumpConfig !== true && options.dumpDefaultConfig !== true) {
-    return { mode: 'profile', profile, patches, args }
+    return { mode: 'profile', profile, fromDefaultProfile: options.fromDefaultProfile, patches, args }
   }
   if (options.dumpConfig === true && options.dumpDefaultConfig === true) {
     program.error('error: --dump-config and --dump-default-config are mutually exclusive')
@@ -105,7 +113,7 @@ function resolveBoot(program: Command, profile: string, options: BootOptions, ar
   if (defaultOnly && patches.length > 0) {
     program.error('error: --dump-default-config prints the bundle layers and takes no --patch')
   }
-  return { mode: 'dump-config', profile, defaultOnly, patches }
+  return { mode: 'dump-config', profile, fromDefaultProfile: options.fromDefaultProfile, defaultOnly, patches }
 }
 
 /**
@@ -135,6 +143,7 @@ export function parseDshArgs(argv: readonly string[], version: string): DshInvoc
     .enablePositionalOptions()
     .argument('[args...]', 'arguments for the booted profile\'s app (see: dsh --profile <name> --help)')
     .option('--profile <name>', 'the profile under $DSH_HOME/profiles to boot')
+    .option('--from-default-profile <name>', 'initialize a new custom profile from a shipped profile template')
     .option('--patch <path>', 'extra patch-list overlay applied after the profile layer (repeatable)', collect)
     .option('--dump-config', 'print the composed profile tree and exit')
     .option('--dump-default-config', 'print the profile tree without its user layer or --patch overlays and exit')
@@ -155,8 +164,11 @@ export function parseDshArgs(argv: readonly string[], version: string): DshInvoc
   const rejectParentOptions = (command: string): void => {
     const parent = program.opts<BootOptions & { profile?: string }>()
     if (parent.profile !== undefined || parent.patch !== undefined
-      || parent.dumpConfig !== undefined || parent.dumpDefaultConfig !== undefined) {
-      program.error(`error: ${command} takes none of parent --profile, --patch, --dump-config, or --dump-default-config`)
+      || parent.dumpConfig !== undefined || parent.dumpDefaultConfig !== undefined
+      || parent.fromDefaultProfile !== undefined) {
+      program.error(
+        `error: ${command} takes none of parent --profile, --from-default-profile, --patch, --dump-config, or --dump-default-config`,
+      )
     }
   }
 
diff --git a/apps/cli/src/bin.ts b/apps/cli/src/bin.ts
index 20038abb5b..15e33b1c95 100644
--- a/apps/cli/src/bin.ts
+++ b/apps/cli/src/bin.ts
@@ -34,6 +34,7 @@ export async function runCli(): Promise<void> {
       await runProfile({
         environment: loadLayeredEnv('dsh'),
         profile: invocation.profile,
+        fromDefaultProfile: invocation.fromDefaultProfile,
         patchFiles: invocation.patches,
         args: invocation.args,
       })
@@ -46,7 +47,12 @@ export async function runCli(): Promise<void> {
     }
     case 'dump-config': {
       const { runDumpConfig } = await import('./dump-config.ts')
-      runDumpConfig(invocation.profile, invocation.defaultOnly, invocation.patches)
+      runDumpConfig(
+        invocation.profile,
+        invocation.defaultOnly,
+        invocation.patches,
+        invocation.fromDefaultProfile,
+      )
       break
     }
     default:
diff --git a/apps/cli/src/dump-config.ts b/apps/cli/src/dump-config.ts
index 1754eb4efd..1e406f1520 100644
--- a/apps/cli/src/dump-config.ts
+++ b/apps/cli/src/dump-config.ts
@@ -26,9 +26,15 @@ const NAME = 'dsh'
  * (the recovery diagnostic for a broken `cordis.patch.yml`, which is then
  * never parsed).
  * @param patches - `--patch` overlay paths, in argv order.
+ * @param fromDefaultProfile - shipped template used once to initialize a missing profile.
  */
-export function runDumpConfig(profile: string, defaultOnly: boolean, patches: readonly string[]): void {
-  const loaded = prepareProfile(profile, !defaultOnly)
+export function runDumpConfig(
+  profile: string,
+  defaultOnly: boolean,
+  patches: readonly string[],
+  fromDefaultProfile?: string,
+): void {
+  const loaded = prepareProfile(profile, !defaultOnly, fromDefaultProfile)
   const layers: ConfigDumpLayer[] = loaded.layers.map(layer => ({
     label: layer.packageName,
     patches: layer.patches,
diff --git a/apps/cli/src/profile-boot.ts b/apps/cli/src/profile-boot.ts
index 1b12218ab5..0715efe1bb 100644
--- a/apps/cli/src/profile-boot.ts
+++ b/apps/cli/src/profile-boot.ts
@@ -11,8 +11,8 @@
  * @module @deepseek-ai/dsh/profile-boot
  */
 
-import { writeFileSync } from 'node:fs'
-import { join, resolve } from 'node:path'
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { FiberState, type Context } from '@deepseek-ai/cordis'
 import type { PatchOptions } from '@deepseek-ai/cordis-plugin-include'
@@ -21,11 +21,14 @@ import {
   boot,
   composeEntries,
   healProfilesModuleFallback,
+  initProfile,
   installFailLoud,
   loadOptionalPatches,
   loadOverlayPatches,
   loadProfile,
   PROFILE_PATCH_FILENAME,
+  PROFILE_TEMPLATES,
+  resolveProfileDir,
   watchUserPatches,
   type Profile,
 } from '@deepseek-ai/dsh-app-boot'
@@ -87,6 +90,69 @@ const PROFILE_ROOT_CONFIG = `# dsh profile root — an empty entry list. The tre
 /** Root config filename inside a profile directory. */
 export const PROFILE_ROOT_FILENAME = 'cordis.yml'
 
+/**
+ * Initialize a missing profile from one shipped template. This copies only
+ * the template's bundle list and patch-reload policy; local state from the
+ * same-named shipped profile is not read, and no inheritance metadata is
+ * persisted. Shipped profile names are reserved, and the target directory is
+ * claimed exclusively so existing or concurrent state is never reused.
+ * @param name - the new profile name.
+ * @param fromDefaultProfile - shipped profile template to copy.
+ * @param home - Harness home containing the profile directory.
+ * @throws when the template is unknown, the target name is shipped, or the target directory exists.
+ */
+export function initializeProfileFromDefault(
+  name: string,
+  fromDefaultProfile: string,
+  home: string = resolveDshHome(),
+): void {
+  const dir = resolveProfileDir(name, home)
+  const template = Object.hasOwn(PROFILE_TEMPLATES, fromDefaultProfile)
+    ? PROFILE_TEMPLATES[fromDefaultProfile]
+    : undefined
+  if (template === undefined) {
+    const expected = Object.keys(PROFILE_TEMPLATES).sort().map(value => JSON.stringify(value)).join(', ')
+    throw new Error(
+      `${NAME}: unknown default profile ${JSON.stringify(fromDefaultProfile)}; expected one of ${expected}`,
+    )
+  }
+  if (Object.hasOwn(PROFILE_TEMPLATES, name)) {
+    throw new Error(
+      `${NAME}: profile ${JSON.stringify(name)} is shipped and cannot be a custom profile target; `
+      + 'omit --from-default-profile to use it',
+    )
+  }
+  mkdirSync(dirname(dir), { recursive: true })
+  try {
+    mkdirSync(dir)
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+    const manifestPath = join(dir, 'package.json')
+    if (existsSync(manifestPath)) {
+      throw new Error(
+        `${NAME}: profile ${JSON.stringify(name)} already exists at ${manifestPath}; `
+        + 'omit --from-default-profile to use it',
+      )
+    }
+    throw new Error(
+      `${NAME}: profile directory ${dir} already exists; choose an unused profile name`,
+    )
+  }
+  try {
+    initProfile(dir, template.bundles, template.patchReload)
+  } catch (error) {
+    try {
+      rmSync(dir, { recursive: true, force: true })
+    } catch (cleanupError) {
+      throw new AggregateError(
+        [error, cleanupError],
+        `${NAME}: profile initialization failed and ${dir} could not be removed`,
+      )
+    }
+    throw error
+  }
+}
+
 /**
  * Resolve the telemetry opt-out switch into its boot patch. ANY non-empty
  * value (including `'0'`/`'false'`) disables: a privacy switch prefers
@@ -114,9 +180,12 @@ export function resolveTelemetryPatch(disabledEnv: string | undefined, hasRow: b
  * the identical base).
  * @param name - the profile name.
  * @param userLayer - `false` skips parsing `cordis.patch.yml` (the default dump).
+ * @param fromDefaultProfile - shipped template used once to initialize a missing profile.
  * @returns the loaded profile.
+ * @throws when explicit initialization names an unknown template or an existing profile.
  */
-export function prepareProfile(name: string, userLayer = true): Profile {
+export function prepareProfile(name: string, userLayer = true, fromDefaultProfile?: string): Profile {
+  if (fromDefaultProfile !== undefined) initializeProfileFromDefault(name, fromDefaultProfile)
   const profile = loadProfile(NAME, name, INSTALL_ANCHOR, undefined, { userLayer })
   writeFileSync(join(profile.dir, PROFILE_ROOT_FILENAME), PROFILE_ROOT_CONFIG)
   return profile
@@ -157,8 +226,9 @@ function allPatches(composed: ComposedProfile): PatchOptions[] {
 async function composeProfile(
   name: string,
   patchFiles: readonly string[],
+  fromDefaultProfile?: string,
 ): Promise<ComposedProfile> {
-  const profile = prepareProfile(name)
+  const profile = prepareProfile(name, true, fromDefaultProfile)
   await healProfilesModuleFallback({ installAnchor: INSTALL_ANCHOR, profile })
   const homePatches = loadOptionalPatches(NAME, homePatchPath()) ?? []
   const overlays = patchFiles.flatMap(file => loadOverlayPatches(NAME, resolve(file)))
@@ -179,6 +249,8 @@ export interface RunProfileOptions {
   environment: LaunchEnvironmentSnapshot
   /** The profile name to boot. */
   profile: string
+  /** Shipped template used once to initialize a missing profile. */
+  fromDefaultProfile?: string | undefined
   /** `--patch` overlay paths, in argv order. */
   patchFiles: readonly string[]
   /** The invocation's inner arguments, handed to the tree through `ctx.cmdlineArgs`. */
@@ -217,7 +289,7 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
     (message) => { process.stderr.write(`${NAME}: ${message}\n`) },
   )
 
-  const composed = await composeProfile(options.profile, options.patchFiles)
+  const composed = await composeProfile(options.profile, options.patchFiles, options.fromDefaultProfile)
   const app: { current?: Context } = {}
   const appReady = createAppReady()
   const shutdown = createProcessShutdown(async () => {
diff --git a/apps/cli/tests/args.spec.ts b/apps/cli/tests/args.spec.ts
index a4ce2668fb..86b8e1b79e 100644
--- a/apps/cli/tests/args.spec.ts
+++ b/apps/cli/tests/args.spec.ts
@@ -25,6 +25,8 @@ describe('parseDshArgs', () => {
     expect(parse(['--profile', 'tui'])).toEqual({ mode: 'profile', profile: 'tui', patches: [], args: [] })
     expect(parse(['--profile', 'tui', '--patch', 'a.yml', '--patch', 'b.yml']))
       .toEqual({ mode: 'profile', profile: 'tui', patches: ['a.yml', 'b.yml'], args: [] })
+    expect(parse(['--profile', 'rescue', '--from-default-profile', 'web']))
+      .toEqual({ mode: 'profile', profile: 'rescue', fromDefaultProfile: 'web', patches: [], args: [] })
     expect(parse(['web'])).toEqual({ mode: 'profile', profile: 'web', patches: [], args: [] })
     expect(parse(['web', '--patch', 'web.yml']))
       .toEqual({ mode: 'profile', profile: 'web', patches: ['web.yml'], args: [] })
@@ -43,6 +45,15 @@ describe('parseDshArgs', () => {
     // Launcher flags placed after that boundary belong to the app too.
     expect(parse(['--profile', 'tui', '--patch', 'a.yml', '--resume', 'b', '--patch', 'late.yml']))
       .toEqual({ mode: 'profile', profile: 'tui', patches: ['a.yml'], args: ['--resume', 'b', '--patch', 'late.yml'] })
+    expect(parse(['--profile', 'rescue', '--resume', 'abc', '--from-default-profile', 'web']))
+      .toEqual({
+        mode: 'profile',
+        profile: 'rescue',
+        patches: [],
+        args: ['--resume', 'abc', '--from-default-profile', 'web'],
+      })
+    expect(parse(['web', '--from-default-profile', 'web']))
+      .toEqual({ mode: 'profile', profile: 'web', patches: [], args: ['--from-default-profile', 'web'] })
   })
 
   it('routes the plugin pnpm forwarder', () => {
@@ -62,6 +73,14 @@ describe('parseDshArgs', () => {
       .toEqual({ mode: 'dump-config', profile: 'web', defaultOnly: false, patches: [] })
     expect(parse(['--profile', 'web', '--dump-default-config']))
       .toEqual({ mode: 'dump-config', profile: 'web', defaultOnly: true, patches: [] })
+    expect(parse(['--profile', 'rescue', '--from-default-profile', 'web', '--dump-config']))
+      .toEqual({
+        mode: 'dump-config',
+        profile: 'rescue',
+        fromDefaultProfile: 'web',
+        defaultOnly: false,
+        patches: [],
+      })
     expect(parse(['--profile', 'tui', '--dump-config', '--patch', 'x.yml']))
       .toEqual({ mode: 'dump-config', profile: 'tui', defaultOnly: false, patches: ['x.yml'] })
     expect(parse(['web', '--dump-config']))
@@ -77,6 +96,8 @@ describe('parseDshArgs', () => {
     expect(exitCode(['-p', 'task'])).toBe(1) // removed
     expect(exitCode(['run', 'task'])).toBe(1) // app-owned task replaced the launcher subcommand
     expect(exitCode(['--profile', ''])).toBe(1)
+    expect(exitCode(['--profile', 'x', '--from-default-profile='])).toBe(1)
+    expect(exitCode(['--profile', 'x', '--from-default-profile'])).toBe(1)
     expect(exitCode(['--profile', 'x', '--patch='])).toBe(1)
     expect(exitCode(['--dump-config'])).toBe(1)
     expect(exitCode(['--profile', 'x', '--dump-config', '--dump-default-config'])).toBe(1)
@@ -102,6 +123,7 @@ describe('parseDshArgs', () => {
     expect(exitCode(['plugin', '--profile', 'desktop', 'add', 'x'])).toBe(1)
     expect(exitCode(['plugin', '--profile', 'Desktop', 'add', 'x'])).toBe(1)
     expect(exitCode(['--profile', 'x', 'plugin', 'add', 'y'])).toBe(1)
+    expect(exitCode(['--from-default-profile', 'web', 'plugin', '--profile', 'x', 'add', 'y'])).toBe(1)
   })
 
   it('keeps its own help for an invocation with no app to hand it to', () => {
diff --git a/apps/cli/tests/built-bin.e2e.ts b/apps/cli/tests/built-bin.e2e.ts
index 1cbbfd9c6d..ef606d49af 100644
--- a/apps/cli/tests/built-bin.e2e.ts
+++ b/apps/cli/tests/built-bin.e2e.ts
@@ -648,6 +648,74 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
     }
   }, SPAWN_TIMEOUT_MS + 30_000)
 
+  it('creates a custom profile from the shipped web template before booting it', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'dsh-from-default-profile-'))
+    try {
+      const created = await runBuiltBin(
+        ['--profile', 'rescue', '--from-default-profile', 'web', '--help'],
+        { DSH_HOME: home, DSH_TELEMETRY_DISABLED: '1' },
+      )
+      expect(created.code).toBe(0)
+      expect(created.stderr).toBe('')
+      expect(created.stdout).toContain('Usage: dsh --profile web')
+
+      const dir = join(home, 'profiles', 'rescue')
+      const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as {
+        dependencies: Record<string, string>
+        dsh: { profile: { bundles: string[]; patchReload: string } }
+      }
+      expect(manifest.dependencies).toEqual({})
+      expect(manifest.dsh.profile).toEqual({
+        bundles: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app'],
+        patchReload: 'live',
+      })
+      expect(readFileSync(join(dir, 'cordis.patch.yml'), 'utf8')).toContain('[]')
+      expect(readFileSync(join(dir, 'pnpm-workspace.yaml'), 'utf8')).toContain('nodeLinker: hoisted')
+
+      const repeated = await runBuiltBin(
+        ['--profile', 'rescue', '--from-default-profile', 'web', '--help'],
+        { DSH_HOME: home, DSH_TELEMETRY_DISABLED: '1' },
+      )
+      expect(repeated.code).toBe(1)
+      expect(repeated.stdout).toBe('')
+      expect(repeated.stderr).toContain('profile "rescue" already exists')
+      expect(repeated.stderr).toContain('omit --from-default-profile to use it')
+
+      const reopened = await runBuiltBin(
+        ['--profile', 'rescue', '--help'],
+        { DSH_HOME: home, DSH_TELEMETRY_DISABLED: '1' },
+      )
+      expect(reopened.code).toBe(0)
+      expect(reopened.stderr).toBe('')
+      expect(reopened.stdout).toContain('Usage: dsh --profile web')
+    } finally {
+      rmSync(home, { recursive: true, force: true })
+    }
+  }, SPAWN_TIMEOUT_MS * 3 + 30_000)
+
+  it('keeps a newly created profile when application boot rejects its arguments', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'dsh-from-default-profile-failed-boot-'))
+    try {
+      const failed = await runBuiltBin(
+        ['--profile', 'rescue', '--from-default-profile', 'web', '--port', 'not-a-number'],
+        { DSH_HOME: home, DSH_TELEMETRY_DISABLED: '1' },
+      )
+      expect(failed.code).toBe(1)
+      expect(failed.stderr).toContain('--port must be a number')
+      expect(existsSync(join(home, 'profiles', 'rescue', 'package.json'))).toBe(true)
+
+      const retried = await runBuiltBin(
+        ['--profile', 'rescue', '--help'],
+        { DSH_HOME: home, DSH_TELEMETRY_DISABLED: '1' },
+      )
+      expect(retried.code).toBe(0)
+      expect(retried.stderr).toBe('')
+      expect(retried.stdout).toContain('Usage: dsh --profile web')
+    } finally {
+      rmSync(home, { recursive: true, force: true })
+    }
+  }, SPAWN_TIMEOUT_MS * 2 + 30_000)
+
   it('uses the launching endpoint and managed credential through the published entry', async () => {
     const apiKey = 'built-home-layer-key'
     const server = await startMockLlmServer({
@@ -955,6 +1023,29 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
       expect(existsSync(join(home, 'profiles', 'node_modules'))).toBe(false)
     }, SPAWN_TIMEOUT_MS + 30_000)
 
+    it('creates a custom profile from a shipped template before printing it', async () => {
+      const { stdout, code, stderr } = await runBuiltBin(
+        ['--profile', 'rescue', '--from-default-profile', 'web', '--dump-default-config'],
+        { DSH_HOME: home },
+      )
+      expect(code).toBe(0)
+      expect(stderr).toBe('')
+      expect(stdout).toContain('# == @deepseek-ai/dsh-web-app')
+      expect(existsSync(join(home, 'profiles', 'rescue', 'package.json'))).toBe(true)
+    }, SPAWN_TIMEOUT_MS + 30_000)
+
+    it('rejects an unknown source before creating the target profile', async () => {
+      const { stdout, code, stderr } = await runBuiltBin(
+        ['--profile', 'rescue', '--from-default-profile', 'unknown', '--dump-default-config'],
+        { DSH_HOME: home },
+      )
+      expect(code).toBe(1)
+      expect(stdout).toBe('')
+      expect(stderr).toContain('unknown default profile "unknown"')
+      expect(stderr).toContain('"web"')
+      expect(existsSync(join(home, 'profiles', 'rescue'))).toBe(false)
+    }, SPAWN_TIMEOUT_MS + 30_000)
+
     it('prints the headless profile without Host or browser layers', async () => {
       const { stdout, code, stderr } = await runBuiltBin(
         ['--profile', 'headless', '--dump-default-config'],
diff --git a/apps/cli/tests/fixtures/initialize-profile-from-default.ts b/apps/cli/tests/fixtures/initialize-profile-from-default.ts
new file mode 100644
index 0000000000..9f9e239337
--- /dev/null
+++ b/apps/cli/tests/fixtures/initialize-profile-from-default.ts
@@ -0,0 +1,18 @@
+/** Synchronize competing source-process profile initialization for the race acceptance test. */
+
+import { existsSync, writeFileSync } from 'node:fs'
+import { setTimeout as delay } from 'node:timers/promises'
+import { initializeProfileFromDefault } from '../../src/profile-boot.ts'
+
+const [home, name, source, ready, gate] = process.argv.slice(2)
+if (home === undefined || name === undefined || source === undefined || ready === undefined || gate === undefined) {
+  throw new Error('profile initialization fixture requires home, name, source, ready, and gate')
+}
+
+writeFileSync(ready, '')
+const deadline = Date.now() + 30_000
+while (!existsSync(gate)) {
+  if (Date.now() >= deadline) throw new Error(`profile initialization fixture timed out waiting for ${gate}`)
+  await delay(20)
+}
+initializeProfileFromDefault(name, source, home)
diff --git a/apps/cli/tests/profile-initialization.spec.ts b/apps/cli/tests/profile-initialization.spec.ts
new file mode 100644
index 0000000000..9c65a34683
--- /dev/null
+++ b/apps/cli/tests/profile-initialization.spec.ts
@@ -0,0 +1,158 @@
+/** One-time custom-profile initialization from shipped templates. */
+
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  initProfile,
+  PROFILE_PATCH_FILENAME,
+  PROFILE_TEMPLATES,
+  readProfileManifest,
+  resolveProfileDir,
+  writeProfileManifest,
+} from '@deepseek-ai/dsh-app-boot'
+import { describe, expect, it } from 'vitest'
+import { execa } from 'execa'
+import { initializeProfileFromDefault } from '../src/profile-boot.ts'
+
+const childEntry = fileURLToPath(new URL('./fixtures/initialize-profile-from-default.ts', import.meta.url))
+const tsxLoader = import.meta.resolve('tsx/esm')
+const CHILD_TIMEOUT_MS = 30_000
+
+/** Wait until a child has reached the shared creation barrier. */
+async function waitForFile(file: string): Promise<void> {
+  const deadline = Date.now() + CHILD_TIMEOUT_MS
+  while (!existsSync(file)) {
+    if (Date.now() >= deadline) throw new Error(`profile initialization marker did not appear: ${file}`)
+    await new Promise(resolve => setTimeout(resolve, 20))
+  }
+}
+
+/** Run one assertion against a private Harness home and remove it afterwards. */
+function withHome(assertion: (home: string) => void): void {
+  const home = mkdtempSync(join(tmpdir(), 'dsh-profile-from-default-'))
+  try {
+    assertion(home)
+  } finally {
+    rmSync(home, { recursive: true, force: true })
+  }
+}
+
+describe('initializeProfileFromDefault', () => {
+  it.each(Object.entries(PROFILE_TEMPLATES))(
+    'copies the %s template metadata into an independent profile',
+    (source, template) => {
+      withHome((home) => {
+        initializeProfileFromDefault('custom', source, home)
+        const dir = resolveProfileDir('custom', home)
+        const manifest = readProfileManifest('test', dir)
+        expect(manifest).toEqual({
+          name: 'dsh-profile-custom',
+          private: true,
+          dependencies: {},
+          dsh: { profile: { bundles: [...template.bundles], patchReload: template.patchReload } },
+        })
+        expect(readFileSync(join(dir, PROFILE_PATCH_FILENAME), 'utf8')).toContain('[]')
+        expect(readFileSync(join(dir, 'pnpm-workspace.yaml'), 'utf8')).toContain('nodeLinker: hoisted')
+      })
+    },
+  )
+
+  it('does not copy the local source profile dependencies or user patch', () => {
+    withHome((home) => {
+      const sourceDir = resolveProfileDir('web', home)
+      initProfile(sourceDir, ['local-bundle'], 'startup')
+      const sourceManifest = readProfileManifest('test', sourceDir)
+      sourceManifest.dependencies = { 'local-bundle': '1.0.0' }
+      writeProfileManifest(sourceDir, sourceManifest)
+      writeFileSync(join(sourceDir, PROFILE_PATCH_FILENAME), '- id: local-only\n  disabled: true\n')
+
+      initializeProfileFromDefault('rescue', 'web', home)
+
+      const targetDir = resolveProfileDir('rescue', home)
+      const target = readProfileManifest('test', targetDir)
+      expect(target.dependencies).toEqual({})
+      expect(target.dsh?.profile).toEqual({
+        bundles: [...PROFILE_TEMPLATES.web!.bundles],
+        patchReload: PROFILE_TEMPLATES.web!.patchReload,
+      })
+      expect(readFileSync(join(targetDir, PROFILE_PATCH_FILENAME), 'utf8')).not.toContain('local-only')
+    })
+  })
+
+  it('rejects an existing target without changing its files', () => {
+    withHome((home) => {
+      const dir = resolveProfileDir('rescue', home)
+      initProfile(dir, ['existing-bundle'], 'startup')
+      writeFileSync(join(dir, PROFILE_PATCH_FILENAME), '- id: existing\n  disabled: true\n')
+      const paths = ['package.json', PROFILE_PATCH_FILENAME, 'pnpm-workspace.yaml'].map(file => join(dir, file))
+      const before = paths.map(path => readFileSync(path))
+
+      expect(() => {
+        initializeProfileFromDefault('rescue', 'web', home)
+      })
+        .toThrow('profile "rescue" already exists')
+      expect(paths.map(path => readFileSync(path))).toEqual(before)
+    })
+  })
+
+  it('rejects a residual target directory without changing its contents', () => {
+    withHome((home) => {
+      const dir = resolveProfileDir('rescue', home)
+      mkdirSync(dir, { recursive: true })
+      const residual = join(dir, PROFILE_PATCH_FILENAME)
+      writeFileSync(residual, '- id: residual\n  disabled: true\n')
+      const before = readFileSync(residual)
+
+      expect(() => {
+        initializeProfileFromDefault('rescue', 'web', home)
+      })
+        .toThrow('profile directory')
+      expect(readFileSync(residual)).toEqual(before)
+      expect(existsSync(join(dir, 'package.json'))).toBe(false)
+    })
+  })
+
+  it.each(Object.keys(PROFILE_TEMPLATES))('rejects shipped target name %s without creating it', (name) => {
+    withHome((home) => {
+      expect(() => {
+        initializeProfileFromDefault(name, 'web', home)
+      })
+        .toThrow(`profile ${JSON.stringify(name)} is shipped`)
+      expect(existsSync(resolveProfileDir(name, home))).toBe(false)
+    })
+  })
+
+  it.each(['unknown', 'toString'])('rejects unknown template %s without creating the target', (source) => {
+    withHome((home) => {
+      expect(() => {
+        initializeProfileFromDefault('rescue', source, home)
+      })
+        .toThrow(`unknown default profile ${JSON.stringify(source)}`)
+      expect(existsSync(resolveProfileDir('rescue', home))).toBe(false)
+    })
+  })
+
+  it('allows only one of two synchronized processes to create the target', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'dsh-profile-from-default-race-'))
+    const gate = join(home, 'start')
+    const ready = [join(home, 'ready-1'), join(home, 'ready-2')]
+    const children = ready.map(marker => execa(
+      process.execPath,
+      ['--import', tsxLoader, childEntry, home, 'rescue', 'web', marker, gate],
+      { reject: false, timeout: CHILD_TIMEOUT_MS },
+    ))
+    try {
+      await Promise.all(ready.map(waitForFile))
+      writeFileSync(gate, '')
+      const results = await Promise.all(children)
+      expect(results.map(result => result.exitCode).sort()).toEqual([0, 1])
+      expect(readProfileManifest('test', resolveProfileDir('rescue', home)).dsh?.profile)
+        .toEqual(PROFILE_TEMPLATES.web)
+    } finally {
+      for (const child of children) child.kill('SIGKILL')
+      rmSync(home, { recursive: true, force: true })
+    }
+  }, CHILD_TIMEOUT_MS + 10_000)
+})
diff --git a/apps/web/package.json b/apps/web/package.json
index df3e0a897a..47946e5b22 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -33,6 +33,7 @@
     "@deepseek-ai/cordis-plugin-group": "workspace:^",
     "@deepseek-ai/dsh-client-modules": "workspace:^",
     "@deepseek-ai/dsh-client-store": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-dockkit": "workspace:^",
     "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-client-web": "workspace:^",
diff --git a/apps/web/tests/built-boot.expected.e2e.ts b/apps/web/tests/built-boot.expected.e2e.ts
index 275cda21d5..d7292382df 100644
--- a/apps/web/tests/built-boot.expected.e2e.ts
+++ b/apps/web/tests/built-boot.expected.e2e.ts
@@ -112,7 +112,7 @@ it('boots the built plugin graph and renders a fixture session end to end', asyn
   fireEvent.click(contextTrigger)
   const contextPanel = await screen.findByRole('dialog', { name: 'of context used' })
   within(contextPanel).getByText('System prompt')
-  within(contextPanel).getByText('Tools')
+  within(contextPanel).getByText('Tool definitions')
   within(contextPanel).getByText('Messages')
 
   // The write/edit turns render a real diff card through the assembled graph
diff --git a/apps/web/tests/command-image-envelope.expected.e2e.ts b/apps/web/tests/command-image-envelope.expected.e2e.ts
index f7da8f088a..565eaa3524 100644
--- a/apps/web/tests/command-image-envelope.expected.e2e.ts
+++ b/apps/web/tests/command-image-envelope.expected.e2e.ts
@@ -21,7 +21,7 @@ async function freshComposer(): Promise<HTMLElement> {
   fireEvent.click(start)
   return await waitFor(() => {
     const surface = document.querySelector<HTMLElement>(
-      '[data-composer-input][data-placeholder="Describe what you want to build... / commands, @ files or sessions"]',
+      '[data-composer-input][data-placeholder="Describe what you want to build, / commands, @ files or sessions"]',
     )
     if (surface === null) throw new Error('composer surface missing')
     return surface
diff --git a/apps/web/tests/details-session-lifecycle.e2e.ts b/apps/web/tests/details-session-lifecycle.e2e.ts
index b903c0c102..239b25f7ef 100644
--- a/apps/web/tests/details-session-lifecycle.e2e.ts
+++ b/apps/web/tests/details-session-lifecycle.e2e.ts
@@ -1,10 +1,8 @@
-// Keyless browser regression for the details column's default visibility and Session ownership.
-// The shipped composition starts closed after selection and reload, retains an explicitly opened width through
-// unselected states, and closes it only when a different Session takes ownership.
-import { readFile } from 'node:fs/promises'
+// Recorded-session Sidebar geometry and per-Session view state through the shipped browser composition.
+import { mkdir, readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
-import type { Browser, Page } from 'playwright'
+import type { Browser, Locator, Page } from 'playwright'
 import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import {
@@ -16,6 +14,8 @@ import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './suppor
 
 const SNAPSHOT_DIR = fileURLToPath(new URL('../../../snapshots/web/details-session-lifecycle', import.meta.url))
 const HANDLES_EXPECTED = join(SNAPSHOT_DIR, 'handles.expected.md')
+const SIDEBAR_EXPECTED = join(SNAPSHOT_DIR, 'sidebar.expected.md')
+const SHOT_DIR = fileURLToPath(new URL('../../../.artifacts/screenshots/0907-sidebar-rules', import.meta.url))
 const FIXTURE = fileURLToPath(new URL('../../../snapshots/web/lifecycle-chrome/session.v2.jsonl', import.meta.url))
 const SEED_FIXTURE = fileURLToPath(new URL('../../../snapshots/web/seeded-history/session.v2.jsonl', import.meta.url))
 const PROMPT = 'Reply with the single word LIGHTHOUSE and stop.'
@@ -64,6 +64,64 @@ async function handleSnapshot(page: Page): Promise<string> {
   ].join('\n').trimEnd()
 }
 
+/** Rendered frame tracks, rounded only to remove browser subpixel allocation. */
+async function columns(page: Page): Promise<number[]> {
+  return await appFrame(page).evaluate(element =>
+    getComputedStyle(element).gridTemplateColumns.split(' ').map(value => Math.round(Number.parseFloat(value))))
+}
+
+/** Tab order and selection inside each docked pane, independent of generated ids. */
+async function paneSnapshot(page: Page) {
+  return await page.locator('[data-rightbar-col] [data-dockkit-pane]').evaluateAll(panes => panes.map(pane => ({
+    active: pane.hasAttribute('data-dockkit-pane-active'),
+    tabs: [...pane.querySelectorAll('[data-dockkit-tab]')].map(tab => ({
+      title: tab.querySelector('[data-dockkit-tab-title]')?.textContent?.trim(),
+      selected: tab.getAttribute('aria-selected') === 'true',
+    })),
+  })))
+}
+
+/** Product-visible geometry, pane state, and expanded Files directories at a settled checkpoint. */
+async function sidebarSnapshot(page: Page) {
+  const geometry = await appFrame(page).evaluate((frame) => {
+    const panel = frame.querySelector<HTMLElement>('[data-sidebar-right-panel]')
+    if (panel === null) throw new Error('Sidebar panel is not mounted')
+    const expanded = panel.hasAttribute('data-sidebar-right-open')
+    const rect = panel.getBoundingClientRect()
+    const style = getComputedStyle(panel)
+    const handle = frame.querySelector('[data-side="rightbar"]')
+    return {
+      viewport: [window.innerWidth, window.innerHeight],
+      columns: getComputedStyle(frame).gridTemplateColumns.split(' ').map(value => Math.round(Number.parseFloat(value))),
+      columnTransition: getComputedStyle(frame).transitionProperty,
+      expanded,
+      mode: panel.getAttribute('data-sidebar-right-panel'),
+      panelContentWidth: expanded ? Math.round(Number.parseFloat(style.width)) : 0,
+      panelOuterWidth: expanded ? Math.round(rect.width) : 0,
+      coversViewport: expanded && rect.x === 0 && rect.y === 0
+        && Math.round(rect.width) === window.innerWidth && Math.round(rect.height) === window.innerHeight,
+      resizeHandleWidth: handle === null ? 0 : Math.round(handle.getBoundingClientRect().width),
+      expandedDirectories: [...panel.querySelectorAll('[data-files-entry="directory"] > button[aria-expanded="true"]')]
+        .map(button => button.textContent?.trim()),
+    }
+  })
+  return { ...geometry, panes: await paneSnapshot(page) }
+}
+
+/** The native pointer gesture used for the left column's width preference. */
+async function dragSidebar(page: Page, target: number): Promise<void> {
+  const grip = await page.locator('[data-side="sidebar"]').boundingBox()
+  if (grip === null) throw new Error('Sidebar resize handle is not rendered')
+  await page.mouse.move(grip.x + grip.width / 2, grip.y + grip.height / 2)
+  await page.mouse.down()
+  try {
+    await page.mouse.move(target, grip.y + grip.height / 2, { steps: 6 })
+  } finally {
+    await page.mouse.up()
+  }
+  await expect.poll(() => sidebarTrack(page)).toBe(target)
+}
+
 describe.skipIf(MODE === 'record')('web e2e: details panel follows the current Session lifecycle', () => {
   let scaffold: WebScaffold
   let browser: Browser
@@ -84,12 +142,18 @@ describe.skipIf(MODE === 'record')('web e2e: details panel follows the current S
   }, 120_000)
 
   afterAll(async () => {
-    await browser?.close()
-    await scaffold?.close()
+    try {
+      await browser?.close()
+    } finally {
+      await scaffold?.close()
+    }
   })
 
-  it('starts and reloads closed, then stays closed across Session ownership changes', async () => {
-    onTestFailed(() => saveFailureShot(page, 'web-e2e-details-session-lifecycle'))
+  it('retains each Session sidebar and applies normal, fullscreen, and capacity-close geometry', async () => {
+    onTestFailed(async () => {
+      await mkdir(SHOT_DIR, { recursive: true })
+      await saveFailureShot(page, `screenshots/0907-sidebar-rules/details-session-lifecycle-${MODE}-${process.pid}`)
+    })
     const settled = scaffold.whenTurnSettled()
     const input = page.locator('[data-composer-input]').first()
     await input.fill(PROMPT)
@@ -125,7 +189,7 @@ describe.skipIf(MODE === 'record')('web e2e: details panel follows the current S
     await expect.poll(() => detailsTrack(page), { timeout: 5_000 }).toBe(0)
     expect(await page.getByText('Details', { exact: true }).isVisible()).toBe(false)
 
-    const original = page.locator('[role=treeitem]').filter({ hasText: 'Reply with the single word' }).first()
+    const original = page.locator('[role="treeitem"][aria-selected]').filter({ hasText: 'Reply with the single word' }).first()
     await original.click()
     await page.getByText('LIGHTHOUSE', { exact: true }).waitFor({ timeout: 15_000 })
     await expect.poll(() => detailsTrack(page), { timeout: 5_000 }).toBe(0)
@@ -133,20 +197,150 @@ describe.skipIf(MODE === 'record')('web e2e: details panel follows the current S
 
     const ungrouped = page.getByText('Ungrouped', { exact: true })
     const ungroupedRow = ungrouped.locator('..').locator('..')
-    const ungroupedSection = ungroupedRow.locator('..')
-    await expect.poll(async () => {
-      if (await ungroupedRow.getAttribute('aria-expanded') !== 'true') {
-        await ungrouped.click()
-        await page.waitForTimeout(50)
-      }
-      return await ungroupedRow.getAttribute('aria-expanded')
-    }, { timeout: 5_000 }).toBe('true')
-    const seeded = ungroupedSection.locator('[role="treeitem"]').nth(1)
+    if (await ungroupedRow.getAttribute('aria-expanded') !== 'true') await ungrouped.click()
+    await expect.poll(() => ungroupedRow.getAttribute('aria-expanded')).toBe('true')
+    // A cold Session's row may still show its cwd until its history loads.
+    const seeded = ungroupedRow.locator('..').locator('[role="treeitem"][aria-selected]')
+    await expect.poll(() => seeded.count()).toBe(1)
     await seeded.click()
     await page.getByText('DONE', { exact: true }).waitFor({ timeout: 15_000 })
     await expect.poll(() => detailsTrack(page), { timeout: 5_000 }).toBe(0)
+
+    const viewport = page.viewportSize()
+    if (viewport === null) throw new Error('expected a fixed viewport')
+    const column = page.locator('[data-rightbar-col]')
+    const panel = column.locator('[data-sidebar-right-panel]')
+    const panes = column.locator('[data-dockkit-pane]')
+    const normalWidth = Math.round(viewport.width * 0.45)
+    const normalColumns = [280, viewport.width - 280 - normalWidth, normalWidth]
+    const checkpoints: string[] = ['# Recorded-session Sidebar states']
+    const checkpoint = async (label: string): Promise<void> => {
+      checkpoints.push(`## ${label}\n\n\`\`\`json\n${JSON.stringify(await sidebarSnapshot(page), null, 2)}\n\`\`\``)
+    }
+    const select = async (row: Locator, reply: string): Promise<void> => {
+      await row.click()
+      await expect.poll(() => row.getAttribute('aria-selected')).toBe('true')
+      await page.getByText(reply, { exact: true }).waitFor({ timeout: 15_000 })
+    }
+    const open = async (): Promise<void> => {
+      await page.locator('[data-sidebar-right-expand]').click()
+      await expect.poll(() => column.locator('[data-sidebar-right-open]').count()).toBe(1)
+      await expect.poll(() => columns(page)).toEqual(normalColumns)
+    }
+    const close = async (): Promise<void> => {
+      await column.locator('[data-sidebar-right-toggle]').click()
+      await expect.poll(() => column.locator('[data-sidebar-right-open]').count()).toBe(0)
+      await expect.poll(() => detailsTrack(page)).toBe(0)
+    }
+
+    await select(original, 'LIGHTHOUSE')
+    await open()
+    // The content-box panel adds its one rendered border pixel outside the
+    // CSS width assigned by the grid solver.
+    await expect.poll(() => sidebarSnapshot(page), { timeout: 5_000 })
+      .toMatchObject({ mode: 'push', panelContentWidth: normalWidth, panelOuterWidth: normalWidth + 1, resizeHandleWidth: 8 })
+    await column.locator('[data-sidebar-right-guide-entry="files"]').click()
+    await column.locator('[data-files-state="tree"]').waitFor({ timeout: 15_000 })
+    await column.locator('[data-dockkit-add-tab]').click()
+    const split = column.locator('[data-dockkit-split-button]').first()
+    await expect.poll(() => split.isDisabled()).toBe(false)
+    await split.click()
+    await expect.poll(() => panes.count()).toBe(2)
+    await panes.first().locator('[data-dockkit-tab]').filter({ hasText: 'Files' }).click()
+    await expect.poll(() => panes.first().locator('[data-files-state="tree"]').count()).toBe(1)
+    const retainedA = await paneSnapshot(page)
+    expect(retainedA.map(pane => pane.tabs.map(tab => tab.title))).toEqual([['Files', 'Start'], ['Start']])
+    await checkpoint('A normal: two panes')
+
+    await column.locator('[data-sidebar-right-mode="fullscreen"]').click()
+    await expect.poll(() => panel.boundingBox()).toEqual({ x: 0, y: 0, ...viewport })
+    expect(await columns(page)).toEqual(normalColumns)
+    expect(await sidebarSnapshot(page)).toMatchObject({ mode: 'fullscreen', resizeHandleWidth: 0, coversViewport: true })
+    expect(await paneSnapshot(page)).toEqual(retainedA)
+    await checkpoint('A manual fullscreen: underlying columns retained')
+
+    // Closing the fullscreen panel exposes Session navigation without changing
+    // its manual mode; reopening after the round trip must restore that mode.
+    await close()
+    expect((await sidebarSnapshot(page)).columnTransition).toBe('none')
+    await checkpoint('A closed with manual fullscreen retained')
+    await select(seeded, 'DONE')
+    await expect.poll(() => detailsTrack(page)).toBe(0)
+    await open()
+    expect(await panel.getAttribute('data-sidebar-right-panel')).toBe('push')
+    await column.locator('[data-sidebar-right-guide-entry="files"]').click()
+    const workspaceDirectory = column.locator('[data-files-entry="directory"] > button').filter({ hasText: /^workspace$/ })
+    await workspaceDirectory.waitFor({ timeout: 15_000 })
+    await workspaceDirectory.click()
+    await expect.poll(() => workspaceDirectory.getAttribute('aria-expanded')).toBe('true')
+    await expect.poll(() => column.locator('[data-files-row="loading"]').count()).toBe(0)
+    expect(await column.locator('[data-files-row="failed"]').count()).toBe(0)
+    const retainedB = await paneSnapshot(page)
+    expect(retainedB.map(pane => pane.tabs.map(tab => tab.title))).toEqual([['Files']])
+    await close()
+    await checkpoint('B closed: independent pane and expanded workspace directory')
+
+    await select(original, 'LIGHTHOUSE')
+    await expect.poll(() => detailsTrack(page)).toBe(0)
+    expect(await panel.getAttribute('data-sidebar-right-panel')).toBe('fullscreen')
+    expect(await paneSnapshot(page)).toEqual(retainedA)
+    await open()
+    await expect.poll(() => panel.boundingBox()).toEqual({ x: 0, y: 0, ...viewport })
+    expect(await paneSnapshot(page)).toEqual(retainedA)
+    await checkpoint('A restored: manual fullscreen, tabs, and panes')
+    await column.locator('[data-sidebar-right-mode="push"]').click()
+    await expect.poll(async () => (await sidebarSnapshot(page)).panelContentWidth, { timeout: 5_000 }).toBe(normalWidth)
+
+    await select(seeded, 'DONE')
+    await expect.poll(() => detailsTrack(page)).toBe(0)
+    expect(await panel.getAttribute('data-sidebar-right-panel')).toBe('push')
+    expect(await paneSnapshot(page)).toEqual(retainedB)
+    await open()
+    await expect.poll(() => workspaceDirectory.getAttribute('aria-expanded')).toBe('true')
+    expect(await paneSnapshot(page)).toEqual(retainedB)
+    await checkpoint('B restored: normal mode and Files directory state')
+    await close()
+    await select(original, 'LIGHTHOUSE')
+    await expect.poll(() => columns(page)).toEqual(normalColumns)
+    expect(await column.locator('[data-sidebar-right-open]').count()).toBe(1)
+    expect(await paneSnapshot(page)).toEqual(retainedA)
+    await checkpoint('A restored: expanded normal panel')
+
+    try {
+      await page.setViewportSize({ width: 1024, height: viewport.height })
+      await expect.poll(() => columns(page)).toEqual([280, 400, 344])
+      await dragSidebar(page, 420)
+      await expect.poll(() => columns(page)).toEqual([420, 604, 0])
+      expect(await column.locator('[data-sidebar-right-open]').count()).toBe(0)
+      expect(await paneSnapshot(page)).toEqual(retainedA)
+      await checkpoint('A capacity-closed: wide left preference protected')
+      await page.setViewportSize(viewport)
+      await expect.poll(() => columns(page)).toEqual([420, viewport.width - 420, 0])
+      expect(await column.locator('[data-sidebar-right-open]').count()).toBe(0)
+      await checkpoint('A widened: remains closed')
+
+      await page.locator('[data-sidebar-right-expand]').click()
+      await expect.poll(() => columns(page)).toEqual([420, viewport.width - 420 - normalWidth, normalWidth])
+      await page.setViewportSize({ width: 767, height: viewport.height })
+      await expect.poll(() => panel.boundingBox()).toEqual({ x: 0, y: 0, width: 767, height: viewport.height })
+      await expect.poll(() => columns(page)).toEqual([56, 711, 0])
+      expect(await sidebarSnapshot(page)).toMatchObject({ mode: 'fullscreen', resizeHandleWidth: 0, coversViewport: true })
+      await checkpoint('A automatic fullscreen at 767px')
+      await column.locator('[data-sidebar-right-mode="push"]').click()
+      await expect.poll(() => column.locator('[data-sidebar-right-open]').count()).toBe(0)
+      await page.setViewportSize(viewport)
+      await expect.poll(() => columns(page)).toEqual([420, viewport.width - 420, 0])
+      expect(await paneSnapshot(page)).toEqual(retainedA)
+      expect(await panel.getAttribute('data-sidebar-right-panel')).toBe('push')
+      expect(await column.locator('[data-sidebar-right-open]').count()).toBe(0)
+      await checkpoint('A automatic fullscreen exited: widening does not reopen')
+    } finally {
+      await page.setViewportSize(viewport)
+    }
+
+    await compareOrRefreshGolden(SIDEBAR_EXPECTED, checkpoints.join('\n\n'), MODE)
     expect(tripwire.pageErrors).toEqual([])
     expect(tripwire.warnings).toEqual([])
-    await assertFixtureInventory(SNAPSHOT_DIR, ['handles.expected.md'])
-  }, 90_000)
+    await assertFixtureInventory(SNAPSHOT_DIR, ['handles.expected.md', 'sidebar.expected.md'])
+  })
 })
diff --git a/apps/web/tests/expected/agent-preset-selection/header.expected.md b/apps/web/tests/expected/agent-preset-selection/header.expected.md
index 9a9f380833..2a59c43dde 100644
--- a/apps/web/tests/expected/agent-preset-selection/header.expected.md
+++ b/apps/web/tests/expected/agent-preset-selection/header.expected.md
@@ -9,3 +9,5 @@
 - button "Session log":
   - text: Session log
   - img
+- button "Open the sidebar":
+  - img
diff --git a/apps/web/tests/expected/clickable-links-gallery/ui.expected.md b/apps/web/tests/expected/clickable-links-gallery/ui.expected.md
index c247f68e74..1bc1752380 100644
--- a/apps/web/tests/expected/clickable-links-gallery/ui.expected.md
+++ b/apps/web/tests/expected/clickable-links-gallery/ui.expected.md
@@ -4,6 +4,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -176,7 +178,6 @@
 - button "Open site/app.js": app.js
 - button "Open src/tokens.css": tokens.css
 - text: + 1 file
-- button "Show in folder"
 - button "Copy":
   - img
 - button "Good response":
@@ -191,7 +192,7 @@
 - text: {{clock}}
 - button "Back to bottom":
   - img
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -201,4 +202,6 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}}
+- button "1 turns 2 steps":
+  - img
+  - text: 1 turns 2 steps
diff --git a/apps/web/tests/expected/github-ready-review/conversation-expanded.expected.md b/apps/web/tests/expected/github-ready-review/conversation-expanded.expected.md
index e5e246ad19..92887b13f2 100644
--- a/apps/web/tests/expected/github-ready-review/conversation-expanded.expected.md
+++ b/apps/web/tests/expected/github-ready-review/conversation-expanded.expected.md
@@ -17,6 +17,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -48,7 +50,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -58,4 +60,6 @@
   - text: github-webhook-review-test/reply
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}}
+- button "1 turns 1 steps":
+  - img
+  - text: 1 turns 1 steps
diff --git a/apps/web/tests/expected/github-ready-review/conversation.expected.md b/apps/web/tests/expected/github-ready-review/conversation.expected.md
index fa6bf3f25c..aa35d67e04 100644
--- a/apps/web/tests/expected/github-ready-review/conversation.expected.md
+++ b/apps/web/tests/expected/github-ready-review/conversation.expected.md
@@ -17,6 +17,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -40,7 +42,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -50,4 +52,6 @@
   - text: github-webhook-review-test/reply
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}}
+- button "1 turns 1 steps":
+  - img
+  - text: 1 turns 1 steps
diff --git a/apps/web/tests/expected/goal-bar/inactive.expected.md b/apps/web/tests/expected/goal-bar/inactive.expected.md
new file mode 100644
index 0000000000..457765ef78
--- /dev/null
+++ b/apps/web/tests/expected/goal-bar/inactive.expected.md
@@ -0,0 +1,8 @@
+- img
+- text: Inactive Goal guard rapid clear clicks
+- button "Resume goal":
+  - img
+- button "Edit goal":
+  - img
+- button "Clear goal":
+  - img
diff --git a/apps/web/tests/expected/goal-command-presentation/ui.expected.md b/apps/web/tests/expected/goal-command-presentation/ui.expected.md
index 432a51de4d..d5fddccca9 100644
--- a/apps/web/tests/expected/goal-command-presentation/ui.expected.md
+++ b/apps/web/tests/expected/goal-command-presentation/ui.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -14,7 +16,7 @@
   - img
   - img
   - text: "goal No goal is currently set. Usage: /goal [<objective>|clear|edit <objective>|pause|resume]"
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
diff --git a/apps/web/tests/expected/markdown-cjk-strong/ui.expected.md b/apps/web/tests/expected/markdown-cjk-strong/ui.expected.md
index c9709a6386..8cccd6e2a7 100644
--- a/apps/web/tests/expected/markdown-cjk-strong/ui.expected.md
+++ b/apps/web/tests/expected/markdown-cjk-strong/ui.expected.md
@@ -4,6 +4,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -48,7 +50,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -58,4 +60,6 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}}
+- button "1 turns 1 steps":
+  - img
+  - text: 1 turns 1 steps
diff --git a/apps/web/tests/expected/markdown-images/ui.expected.md b/apps/web/tests/expected/markdown-images/ui.expected.md
index f26dfd8214..3e00a67cb0 100644
--- a/apps/web/tests/expected/markdown-images/ui.expected.md
+++ b/apps/web/tests/expected/markdown-images/ui.expected.md
@@ -4,6 +4,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -27,7 +29,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -37,4 +39,6 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}}
+- button "1 turns 1 steps":
+  - img
+  - text: 1 turns 1 steps
diff --git a/apps/web/tests/expected/markdown-inline-code-links/ui.expected.md b/apps/web/tests/expected/markdown-inline-code-links/ui.expected.md
index 41424d0ee1..e042455176 100644
--- a/apps/web/tests/expected/markdown-inline-code-links/ui.expected.md
+++ b/apps/web/tests/expected/markdown-inline-code-links/ui.expected.md
@@ -4,6 +4,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -39,7 +41,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -49,4 +51,6 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}}
+- button "1 turns 1 steps":
+  - img
+  - text: 1 turns 1 steps
diff --git a/apps/web/tests/expected/math-rendering/ui.expected.md b/apps/web/tests/expected/math-rendering/ui.expected.md
index 21023fdc64..20e51e6c63 100644
--- a/apps/web/tests/expected/math-rendering/ui.expected.md
+++ b/apps/web/tests/expected/math-rendering/ui.expected.md
@@ -4,6 +4,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -43,7 +45,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -53,4 +55,6 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}}
+- button "1 turns 1 steps":
+  - img
+  - text: 1 turns 1 steps
diff --git a/apps/web/tests/expected/reference-composer/order.expected.md b/apps/web/tests/expected/reference-composer/order.expected.md
index 3ff4bf9c21..7ea2707435 100644
--- a/apps/web/tests/expected/reference-composer/order.expected.md
+++ b/apps/web/tests/expected/reference-composer/order.expected.md
@@ -4,6 +4,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -13,7 +15,7 @@
 - button "Session recall Research notes":
   - img
   - text: Session recall Research notes
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
diff --git a/apps/web/tests/expected/settings-chrome/dialog-en.expected.md b/apps/web/tests/expected/settings-chrome/dialog-en.expected.md
index c47e53bf6c..3121238a25 100644
--- a/apps/web/tests/expected/settings-chrome/dialog-en.expected.md
+++ b/apps/web/tests/expected/settings-chrome/dialog-en.expected.md
@@ -44,7 +44,7 @@
   - button "Compact":
     - text: Compact
     - img
-  - text: Enter behavior while busy Busy only; Cmd/Ctrl+Enter uses the other behavior
+  - text: Send behavior while busy What Enter and the Send button do while the agent is running; Cmd/Ctrl+Enter uses the other behavior
   - button "Queue":
     - text: Queue
     - img
diff --git a/apps/web/tests/expected/settings-chrome/dialog.expected.md b/apps/web/tests/expected/settings-chrome/dialog.expected.md
index 45ad145095..2f620a88d4 100644
--- a/apps/web/tests/expected/settings-chrome/dialog.expected.md
+++ b/apps/web/tests/expected/settings-chrome/dialog.expected.md
@@ -44,7 +44,7 @@
   - button "Compact":
     - text: Compact
     - img
-  - text: 繁忙时 Enter 键行为 仅在智能体运行时生效；Cmd/Ctrl+Enter 使用另一行为
+  - text: 繁忙时的发送行为 智能体运行时 Enter 键和发送按钮的行为；Cmd/Ctrl+Enter 使用另一行为
   - button "排队发送":
     - text: 排队发送
     - img
diff --git a/apps/web/tests/expected/skill-user-invoke/ui-expanded.expected.md b/apps/web/tests/expected/skill-user-invoke/ui-expanded.expected.md
index d55c6b0d35..f14b04d9a9 100644
--- a/apps/web/tests/expected/skill-user-invoke/ui-expanded.expected.md
+++ b/apps/web/tests/expected/skill-user-invoke/ui-expanded.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -40,7 +42,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -51,4 +53,9 @@
   - img
 - button "0% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 0% Input 256 tok · Output 16 tok
+- button "1 turns 1 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 1 steps{{throughput}} tok/s
+- button "272 tok · Cache hit 0%":
+  - img
+  - text: 272 tokCache hit 0%
diff --git a/apps/web/tests/expected/skill-user-invoke/ui.expected.md b/apps/web/tests/expected/skill-user-invoke/ui.expected.md
index 545e0c93b4..e0901950d2 100644
--- a/apps/web/tests/expected/skill-user-invoke/ui.expected.md
+++ b/apps/web/tests/expected/skill-user-invoke/ui.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -32,7 +34,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -43,4 +45,9 @@
   - img
 - button "0% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 0% Input 256 tok · Output 16 tok
+- button "1 turns 1 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 1 steps{{throughput}} tok/s
+- button "272 tok · Cache hit 0%":
+  - img
+  - text: 272 tokCache hit 0%
diff --git a/apps/web/tests/expected/stats-paged-history/ui.expected.md b/apps/web/tests/expected/stats-paged-history/ui.expected.md
index 9354a75fae..6a3f9ecbb6 100644
--- a/apps/web/tests/expected/stats-paged-history/ui.expected.md
+++ b/apps/web/tests/expected/stats-paged-history/ui.expected.md
@@ -4,6 +4,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -459,7 +461,7 @@
 - text: 7/25 {{clock}}
 - button "Back to bottom":
   - img
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -469,4 +471,6 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: 28 turns · 28 steps LLM {{duration}}
+- button "28 turns 28 steps":
+  - img
+  - text: 28 turns 28 steps
diff --git a/apps/web/tests/expected/steer-all/mid-steer.expected.md b/apps/web/tests/expected/steer-all/mid-steer.expected.md
index 1456ffa683..11e83471a3 100644
--- a/apps/web/tests/expected/steer-all/mid-steer.expected.md
+++ b/apps/web/tests/expected/steer-all/mid-steer.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -31,7 +33,7 @@
 - text: "Interjection: include the word ORANGE in your final reply."
 - button "Copy":
   - img
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
diff --git a/apps/web/tests/expected/steer-all/settled-expanded.expected.md b/apps/web/tests/expected/steer-all/settled-expanded.expected.md
index c3399b4739..b1644d07d5 100644
--- a/apps/web/tests/expected/steer-all/settled-expanded.expected.md
+++ b/apps/web/tests/expected/steer-all/settled-expanded.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -50,7 +52,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -61,4 +63,9 @@
   - img
 - button "0% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 0% Input 20 tok · Output 20 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "40 tok · Cache hit 0%":
+  - img
+  - text: 40 tokCache hit 0%
diff --git a/apps/web/tests/expected/steer-all/settled.expected.md b/apps/web/tests/expected/steer-all/settled.expected.md
index cf24996c06..acbaf1b148 100644
--- a/apps/web/tests/expected/steer-all/settled.expected.md
+++ b/apps/web/tests/expected/steer-all/settled.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -38,7 +40,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -49,4 +51,9 @@
   - img
 - button "0% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 0% Input 20 tok · Output 20 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "40 tok · Cache hit 0%":
+  - img
+  - text: 40 tokCache hit 0%
diff --git a/apps/web/tests/feedback-release.e2e.ts b/apps/web/tests/feedback-release.e2e.ts
index e4659aa622..d6df51d270 100644
--- a/apps/web/tests/feedback-release.e2e.ts
+++ b/apps/web/tests/feedback-release.e2e.ts
@@ -267,7 +267,7 @@ describe.each(MODE === 'record' ? ['deepseek-official'] : ['deepseek-official',
     await selectModel('DeepSeek-V4-Flash')
     expect(captured()).toHaveLength(releasedCount)
     await page.getByRole('button', { name: 'New session', exact: true }).last().click()
-    const input = page.locator('[data-composer-input][contenteditable="true"][data-placeholder="Describe what you want to build... / commands, @ files or sessions"]')
+    const input = page.locator('[data-composer-input][contenteditable="true"][data-placeholder="Describe what you want to build, / commands, @ files or sessions"]')
     await input.waitFor({ timeout: 15_000 })
     await input.fill('/feedback Feedback before any model request.')
     expect(captured()).toHaveLength(releasedCount)
diff --git a/apps/web/tests/goal-bar.e2e.ts b/apps/web/tests/goal-bar.e2e.ts
index f9cd46b60c..e1d77f0cb6 100644
--- a/apps/web/tests/goal-bar.e2e.ts
+++ b/apps/web/tests/goal-bar.e2e.ts
@@ -16,6 +16,7 @@ import { newEnglishPage, saveFailureShot } from './support.ts'
 
 const SNAPSHOT_DIR = fileURLToPath(new URL('./expected/goal-bar', import.meta.url))
 const ACTIVE_EXPECTED = join(SNAPSHOT_DIR, 'active.expected.md')
+const INACTIVE_EXPECTED = join(SNAPSHOT_DIR, 'inactive.expected.md')
 const OVERLAY = fileURLToPath(new URL('./goal-bar.overlay.yml', import.meta.url))
 const MODE = webSnapshotMode()
 
@@ -45,16 +46,28 @@ describe('web e2e: goal bar clear convergence', () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-goal-bar-clear'))
     // Startup reuses the fixture workspace's blank session, keeping this
     // command independent of alpha's running replay and pending question.
-    const input = page.locator('[data-composer-input][data-placeholder="Describe what you want to build... / commands, @ files or sessions"]')
+    const input = page.locator('[data-composer-input][data-placeholder="Describe what you want to build, / commands, @ files or sessions"]')
     await input.waitFor({ timeout: 10_000 })
     await input.fill('/goal guard rapid clear clicks')
     await input.press('Enter')
 
     const bar = page.locator('[data-goal-bar]')
     await bar.waitFor({ timeout: 10_000 })
+    await expect.poll(() => bar.getByRole('button', { name: 'Pause goal' }).count(), {
+      timeout: 10_000,
+    }).toBe(1)
     const snapshot = await captureStableAria(page, '[data-goal-bar]', scaffold.workspaceCwd)
     await compareOrRefreshGolden(ACTIVE_EXPECTED, snapshot, MODE)
 
+    await page.evaluate(() => {
+      (globalThis as unknown as { __fxTiming?: { disarmOnlyGoal(): void } }).__fxTiming?.disarmOnlyGoal()
+    })
+    await expect.poll(() => bar.getByRole('button', { name: 'Resume goal' }).count(), {
+      timeout: 10_000,
+    }).toBe(1)
+    const inactive = await captureStableAria(page, '[data-goal-bar]', scaffold.workspaceCwd)
+    await compareOrRefreshGolden(INACTIVE_EXPECTED, inactive, MODE)
+
     const clear = bar.getByRole('button', { name: 'Clear goal' })
     await clear.evaluate((button) => {
       const control = button as HTMLButtonElement
@@ -68,6 +81,6 @@ describe('web e2e: goal bar clear convergence', () => {
   }, 60_000)
 
   it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => {
-    await assertFixtureInventory(SNAPSHOT_DIR, ['active.expected.md'])
+    await assertFixtureInventory(SNAPSHOT_DIR, ['active.expected.md', 'inactive.expected.md'])
   })
 })
diff --git a/apps/web/tests/image-display.expected.e2e.ts b/apps/web/tests/image-display.expected.e2e.ts
index 886421262f..e35486abfe 100644
--- a/apps/web/tests/image-display.expected.e2e.ts
+++ b/apps/web/tests/image-display.expected.e2e.ts
@@ -90,7 +90,7 @@ it('accepts pasted images into the composer rail in order and removes them', asy
   // this assembled lane pins the intake chain over the built graph.
   const textarea = await waitFor(() => {
     const surface = document.querySelector<HTMLElement>(
-      '[data-composer-input][data-placeholder="Describe what you want to build... / commands, @ files or sessions"]',
+      '[data-composer-input][data-placeholder="Describe what you want to build, / commands, @ files or sessions"]',
     )
     if (surface === null) throw new Error('composer surface missing')
     return surface
@@ -161,7 +161,7 @@ it('accepts a whole-page drop under the limits-labeled overlay and refuses an ov
   fireEvent.click(start)
   const textarea = await waitFor(() => {
     const surface = document.querySelector<HTMLElement>(
-      '[data-composer-input][data-placeholder="Describe what you want to build... / commands, @ files or sessions"]',
+      '[data-composer-input][data-placeholder="Describe what you want to build, / commands, @ files or sessions"]',
     )
     if (surface === null) throw new Error('composer surface missing')
     return surface
@@ -216,7 +216,7 @@ it('renders a host dimension rejection with the projected 2000px limit', async (
 
   const textarea = await waitFor(() => {
     const surface = document.querySelector<HTMLElement>(
-      '[data-composer-input][data-placeholder="Describe what you want to build... / commands, @ files or sessions"]',
+      '[data-composer-input][data-placeholder="Describe what you want to build, / commands, @ files or sessions"]',
     )
     if (surface === null) throw new Error('composer surface missing')
     return surface
diff --git a/apps/web/tests/lifecycle-chrome.e2e.ts b/apps/web/tests/lifecycle-chrome.e2e.ts
index 6052ea0a88..282aa0b1a9 100644
--- a/apps/web/tests/lifecycle-chrome.e2e.ts
+++ b/apps/web/tests/lifecycle-chrome.e2e.ts
@@ -222,7 +222,8 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
     ).toBeGreaterThanOrEqual(1)
     await expect.poll(() => page.locator('[role="treeitem"][aria-selected="true"]').count(), { timeout: 10_000 }).toBe(1)
     await expect.poll(() => page.getByText('LIGHTHOUSE', { exact: true }).count(), { timeout: 15_000 }).toBeGreaterThanOrEqual(1)
-    await expect.poll(() => page.getByText('Cache hit 99.5%', { exact: true }).count(), { timeout: 15_000 }).toBe(1)
+    // The usage pill's one label span concatenates the billed total and the cache-hit share.
+    await expect.poll(() => page.getByRole('button', { name: /Cache hit 99\.5%/ }).count(), { timeout: 15_000 }).toBe(1)
     // Host: the session's durable header cwd is the folder the workspace
     // flow created and adopted (<workspaceCwd>/workspace) — the proof the
     // send went through workspace materialization rather than a bare
diff --git a/apps/web/tests/live-interactions.e2e.ts b/apps/web/tests/live-interactions.e2e.ts
index 1001b51cf2..3f6f192507 100644
--- a/apps/web/tests/live-interactions.e2e.ts
+++ b/apps/web/tests/live-interactions.e2e.ts
@@ -166,9 +166,12 @@ describe('web e2e: live-turn interactions (cancel / error / retry)', () => {
 
     const input = page.locator('[data-composer-input]').first()
     await input.fill(RUNNING_DRAFT)
-    const send = page.getByRole('button', { name: 'Send message', exact: true })
+    // The running primary names its delivery: the default busy-state
+    // preference is Queue, so the button reads Queue rather than plain Send.
+    const send = page.getByRole('button', { name: 'Queue message', exact: true })
     await send.waitFor({ timeout: 10_000 })
     expect(await page.getByRole('button', { name: 'Stop generating', exact: true }).count()).toBe(0)
+    expect(await page.getByRole('button', { name: 'Send message', exact: true }).count()).toBe(0)
     const runningDraftSnapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold!.workspaceCwd)
     await compareOrRefreshGolden(RUNNING_DRAFT_EXPECTED, runningDraftSnapshot, MODE)
     await send.click()
diff --git a/apps/web/tests/markdown-wide-table.e2e.ts b/apps/web/tests/markdown-wide-table.e2e.ts
index 44a992b6f1..682aafd7b4 100644
--- a/apps/web/tests/markdown-wide-table.e2e.ts
+++ b/apps/web/tests/markdown-wide-table.e2e.ts
@@ -197,20 +197,13 @@ interface TableStop {
 }
 
 /**
- * Close the details pane so the transcript spans the viewport. Open, it pins
- * the transcript to exactly the message column and every breakout relation
- * would go vacuous.
- * @param target - the page whose pane to close.
+ * Wait for the right column to sit at its rail. Expanded, it would pin the
+ * transcript to exactly the message column and every breakout relation would
+ * go vacuous; the frame's collapse marker is the settled signal.
+ * @param target - the page whose frame to read.
  */
-async function closeDetailsPane(target: Page): Promise<void> {
-  await target.getByRole('button', { name: 'Close details', exact: true }).waitFor({ timeout: 10_000 })
-  await target.evaluate(() => {
-    document.querySelector<HTMLElement>('button[aria-label="Close details"]')?.click()
-  })
-  // Closed details resolve to zero width but never unmount (ui-layout
-  // columns contract), so the settled signal is the frame's collapse marker,
-  // not the button's detachment.
-  await target.waitForSelector('[data-details-collapsed]', { timeout: 5_000 })
+async function awaitRightRail(target: Page): Promise<void> {
+  await target.waitForSelector('[data-rightbar-collapsed]', { timeout: 5_000 })
 }
 
 /**
@@ -265,21 +258,17 @@ describe('web e2e: markdown tables fill the column, wide ones break out and scro
     await sessionRow.waitFor({ timeout: 10_000 })
     await sessionRow.click()
     await page.getByText(TAIL_MARKER, { exact: true }).waitFor({ timeout: 15_000 })
-    // Collapse the sidebar and close the details pane for the whole sweep:
-    // classic-scrollbar platforms (Linux CI) lose ~15px of layout width,
-    // which shifts how much of a narrow viewport the panes leave the
+    // Collapse the sidebar and keep the right column at its rail for the whole
+    // sweep: classic-scrollbar platforms (Linux CI) lose ~15px of layout
+    // width, which shifts how much of a narrow viewport the panes leave the
     // transcript and lands the narrow stop's readings far from the macOS
-    // ones — and the details pane alone pins the transcript to exactly the
-    // message column, which would make every breakout relation vacuous.
-    // With both out of the equation the transcript follows the viewport
-    // identically on every platform, which is what keeps one committed
-    // golden true for all lanes.
+    // ones — and an expanded right column alone pins the transcript to
+    // exactly the message column, which would make every breakout relation
+    // vacuous. With both out of the equation the transcript follows the
+    // viewport identically on every platform, which is what keeps one
+    // committed golden true for all lanes.
     await page.getByRole('button', { name: 'Collapse sidebar', exact: true }).click()
-    // JS click: after the transcript scrolled to its tail, the pane's close
-    // button can sit under the sticky header where a pointer click is
-    // intercepted; the pane itself is scaffolding, not the behavior under
-    // test, so actionability adds nothing here.
-    await closeDetailsPane(page)
+    await awaitRightRail(page)
   }, 180_000)
 
   afterAll(async () => {
@@ -436,7 +425,7 @@ describe('web e2e: markdown tables fill the column, wide ones break out and scro
       await sessionRow.click()
       await hidpiPage.getByText(TAIL_MARKER, { exact: true }).waitFor({ timeout: 15_000 })
       await hidpiPage.getByRole('button', { name: 'Collapse sidebar', exact: true }).click()
-      await closeDetailsPane(hidpiPage)
+      await awaitRightRail(hidpiPage)
       // The pane collapses ease over the layout transition: compare only a
       // settled reading (two consecutive equal wide-wrapper widths).
       let readings: TableReading[] = []
diff --git a/apps/web/tests/math-rendering.e2e.ts b/apps/web/tests/math-rendering.e2e.ts
index 5f5c89ead4..c826d5aff2 100644
--- a/apps/web/tests/math-rendering.e2e.ts
+++ b/apps/web/tests/math-rendering.e2e.ts
@@ -123,7 +123,7 @@ describe('web e2e: settled Markdown math rendering', () => {
     await expect.poll(() => page.locator('.katex-display').count(), { timeout: 10_000 }).toBe(2)
     expect(await page.locator('.katex-error').count()).toBe(0)
     await expect.poll(
-      () => page.getByText('1 turns · 1 steps', { exact: false }).count(),
+      () => page.getByText('1 turns 1 steps', { exact: false }).count(),
       { timeout: 10_000 },
     ).toBe(1)
 
diff --git a/apps/web/tests/navigation-panes.e2e.ts b/apps/web/tests/navigation-panes.e2e.ts
index 0e06e222ee..0d9b32f1df 100644
--- a/apps/web/tests/navigation-panes.e2e.ts
+++ b/apps/web/tests/navigation-panes.e2e.ts
@@ -12,7 +12,7 @@ import { join } from 'node:path'
 import type { Browser, Page, Response } from 'playwright'
 import { chromium } from 'playwright'
 import { strFromU8, unzipSync } from 'fflate'
-import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, onTestFailed, vi } from 'vitest'
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, onTestFailed } from 'vitest'
 import { parseSessionLog } from '@deepseek-ai/dsh-llm-replay'
 import { SESSION_FORMAT_VERSION, type SessionEvent } from '@deepseek-ai/dsh-session'
 import {
@@ -277,13 +277,17 @@ describe('web e2e: navigation & panes over a rich seeded session', () => {
     const exportButton = page.getByRole('button', { name: 'Session log' })
     expect(await exportButton.isDisabled()).toBe(false)
     const header = exportButton.locator('xpath=ancestor::header[1]')
-    const [buttonBox, headerBox] = await Promise.all([
-      exportButton.boundingBox(), header.boundingBox(),
+    // The right Sidebar's expand button holds the header's corner; the export
+    // control sits immediately to its left.
+    const sidebarButton = page.getByRole('button', { name: 'Open the sidebar' })
+    const [buttonBox, sidebarBox, headerBox] = await Promise.all([
+      exportButton.boundingBox(), sidebarButton.boundingBox(), header.boundingBox(),
     ])
-    if (buttonBox === null || headerBox === null) {
+    if (buttonBox === null || sidebarBox === null || headerBox === null) {
       throw new Error('Session Header export geometry is unavailable')
     }
-    expect(headerBox.x + headerBox.width - (buttonBox.x + buttonBox.width)).toBeLessThanOrEqual(32)
+    expect(headerBox.x + headerBox.width - (sidebarBox.x + sidebarBox.width)).toBeLessThanOrEqual(32)
+    expect(sidebarBox.x - (buttonBox.x + buttonBox.width)).toBeLessThanOrEqual(32)
     const responsePromise = page.waitForResponse(response =>
       response.request().method() === 'HEAD'
       && new URL(response.url()).pathname === '/api/session.export', { timeout: 30_000 })
@@ -382,33 +386,33 @@ describe('web e2e: navigation & panes over a rich seeded session', () => {
     await expect.poll(() => page.locator('tr[data-timeline-focus]').count(), { timeout: 10_000 }).toBe(0)
   }, 60_000)
 
-  it.skipIf(MODE === 'record')('bash and file-path rows leave the default details column closed', async () => {
-    onTestFailed(() => saveFailureShot(page, 'web-e2e-navigation-details'))
+  it.skipIf(MODE === 'record')('bash rows leave the right column at its rail; a file link opens the Sidebar', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-navigation-rightbar'))
     await ensureSeedOpen(page)
     const bashRow = page.locator('[data-sample="bash"]').first()
     await expandOwningTurnProcess(page, bashRow)
     await bashRow.waitFor({ timeout: 15_000 })
     const frame = page.locator('[style*="grid-template-columns"]').first()
-    expect(await frame.getAttribute('data-details-collapsed')).toBe('true')
+    expect(await frame.getAttribute('data-rightbar-collapsed')).toBe('true')
     // The row click is the card's expand toggle (unified tool-row
     // interaction); it must not drive layout geometry either way.
     await bashRow.click()
-    await expect.poll(() => frame.getAttribute('data-details-collapsed'), { timeout: 5_000 }).toBe('true')
-    // The card's own controls are outside the summary row and must not open
-    // details either — the expanded terminal card is read in place.
+    await expect.poll(() => frame.getAttribute('data-rightbar-collapsed'), { timeout: 5_000 }).toBe('true')
+    // The card's own controls are outside the summary row and must not expand
+    // the right column either — the expanded terminal card is read in place.
     await page.locator('[data-sample="bash"] ~ div [data-terminal] [class*="_copyButton_"]').first().click()
-    await expect.poll(() => frame.getAttribute('data-details-collapsed'), { timeout: 5_000 }).toBe('true')
-    // Read summaries are host-open file links; they also must not open details.
+    await expect.poll(() => frame.getAttribute('data-rightbar-collapsed'), { timeout: 5_000 }).toBe('true')
+    // Read summaries are file links: one click opens the file as a text-preview
+    // tab in the right Sidebar, which expands to show it beside the guide tab.
     const fileLink = page.locator('[data-variant="read"] button').first()
     await fileLink.waitFor({ timeout: 10_000 })
-    const openPath = vi.spyOn(scaffold.ctx.sessionController, 'openWorkspacePath')
-      .mockResolvedValue({ opened: true })
-    try {
-      await fileLink.click()
-      await expect.poll(() => frame.getAttribute('data-details-collapsed'), { timeout: 5_000 }).toBe('true')
-    } finally {
-      openPath.mockRestore()
-    }
+    await fileLink.click()
+    await expect.poll(() => frame.getAttribute('data-rightbar-collapsed'), { timeout: 5_000 }).toBe(null)
+    const column = page.locator('[data-rightbar-col]')
+    await expect.poll(() => column.locator('[data-dockkit-tab-title]').count(), { timeout: 5_000 }).toBe(2)
+    // Put the column back so later cases start from the default frame.
+    await column.locator('[data-sidebar-right-toggle]').click()
+    await expect.poll(() => frame.getAttribute('data-rightbar-collapsed'), { timeout: 5_000 }).toBe('true')
   }, 60_000)
 
   it.skipIf(MODE === 'record')('renders the bash row as a terminal card in the real browser', async () => {
diff --git a/apps/web/tests/plan-review.e2e.ts b/apps/web/tests/plan-review.e2e.ts
index ff9e3af4ee..b9ae32cec0 100644
--- a/apps/web/tests/plan-review.e2e.ts
+++ b/apps/web/tests/plan-review.e2e.ts
@@ -97,6 +97,10 @@ describe('web e2e: plan review takeover round trip', () => {
     }
 
     await card.getByRole('button', { name: 'Approve' }).click()
+    // Park the pointer: the card unmounts and the ContextMeter ring lands
+    // under the click position, whose 200ms hover delay would arm a tooltip
+    // into the aria captures below.
+    await page.mouse.move(0, 0)
 
     const sessionId = await settled
     if (MODE === 'record') {
diff --git a/apps/web/tests/preview-boot.e2e.ts b/apps/web/tests/preview-boot.e2e.ts
index cea8d401da..6f8d2aab97 100644
--- a/apps/web/tests/preview-boot.e2e.ts
+++ b/apps/web/tests/preview-boot.e2e.ts
@@ -314,7 +314,7 @@ async function bootPreview(origin: string, browser: Browser): Promise<void> {
     const configureLater = page.getByRole('button', { name: 'Configure later' })
     await configureLater.waitFor({ timeout: 30_000 })
     await configureLater.click()
-    await page.locator('[data-composer-input][data-placeholder="Describe what you want to build... / commands, @ files or sessions"]')
+    await page.locator('[data-composer-input][data-placeholder="Describe what you want to build, / commands, @ files or sessions"]')
       .waitFor({ timeout: 30_000 })
 
     const exercised = await page.evaluate(async () => {
diff --git a/apps/web/tests/produced-files.e2e.ts b/apps/web/tests/produced-files.e2e.ts
index 8f10654a4a..1097ed3b1e 100644
--- a/apps/web/tests/produced-files.e2e.ts
+++ b/apps/web/tests/produced-files.e2e.ts
@@ -1,12 +1,12 @@
 // Web e2e scenario: the single-line produced-files summary a finished turn
 // ends with. Cold-seeds ten writes (zero model calls), then verifies the real
-// assembled lane adapts from a coarse width budget and keeps a capability-gated folder handoff.
-// The folder request is intercepted so one real browser click can exercise
-// the full client carrier without launching a native application in CI.
+// assembled lane adapts from a coarse width budget and offers no folder
+// handoff: chips open in the right Sidebar's text preview, which has no
+// directory form, so the row shows nothing rather than a dead button.
 import { fileURLToPath } from 'node:url'
 import type { Browser, Page } from 'playwright'
 import { chromium } from 'playwright'
-import { afterAll, beforeAll, describe, expect, it, onTestFailed, vi } from 'vitest'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import { ToolCallId, createAssistantMessage, createToolResultMessage, createUserMessage } from '@deepseek-ai/dsh-llm'
 import { SESSION_FORMAT_VERSION, Session, SessionId } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-session-title'
@@ -152,24 +152,11 @@ describe('web e2e: a finished turn ends with the files it produced', () => {
     expect(await chips.nth(1).innerText()).toBe('index.html')
     expect(await chips.nth(4).innerText()).toBe('app.ts')
     await expect.poll(() => row.getByText('+ 5 files', { exact: true }).isVisible()).toBe(true)
-    const showFolder = page.getByRole('button', { name: 'Show in folder', exact: true })
-    expect(await showFolder.count()).toBe(1)
+    // Chips open in the right Sidebar's text preview, and a directory is not
+    // something that preview can show, so the row offers no folder action.
+    expect(await page.getByRole('button', { name: /folder/i }).count()).toBe(0)
     expect(await page.getByText('Produced', { exact: true }).count()).toBe(1)
 
-    const openPath = vi.spyOn(scaffold.ctx.sessionController, 'openWorkspacePath')
-      .mockResolvedValue({ opened: true })
-    try {
-      const [response] = await Promise.all([
-        page.waitForResponse(response => new URL(response.url()).pathname === '/api/session/openWorkspacePath'),
-        showFolder.click({ clickCount: 1 }),
-      ])
-      expect(response.status()).toBe(200)
-      expect(openPath).toHaveBeenCalledTimes(1)
-      expect(openPath.mock.calls[0]![0]).toMatchObject({ path: `${scaffold.workspaceCwd}/.` })
-    } finally {
-      openPath.mockRestore()
-    }
-
     const tops = await row.locator(':scope > *:visible').evaluateAll(elements =>
       elements.map(element => element.getBoundingClientRect().top))
     expect(new Set(tops.map(top => Math.round(top))).size).toBe(1)
diff --git a/apps/web/tests/ptc-round.e2e.ts b/apps/web/tests/ptc-round.e2e.ts
index 66ff93de30..f81ba01ef6 100644
--- a/apps/web/tests/ptc-round.e2e.ts
+++ b/apps/web/tests/ptc-round.e2e.ts
@@ -103,7 +103,7 @@ describe('web e2e: PTC mode round renders nested sub-calls', () => {
   }, 60_000)
 
   it.skipIf(MODE === 'record')('expands the nested bash terminal inline before and after reload', async () => {
-    onTestFailed(() => saveFailureShot(page, 'web-e2e-ptc-details'))
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-ptc-rightbar'))
     let liveTerminalAria: string | undefined
     for (const reloaded of [false, true]) {
       if (reloaded) {
@@ -114,7 +114,7 @@ describe('web e2e: PTC mode round renders nested sub-calls', () => {
       }
       const nest = page.locator('[data-subcalls]').first()
       const frame = page.locator('[style*="grid-template-columns"]').first()
-      expect(await frame.getAttribute('data-details-collapsed')).toBe('true')
+      expect(await frame.getAttribute('data-rightbar-collapsed')).toBe('true')
       await expandOwningTurnProcess(page, nest)
       const row = nest.locator('[data-sample="bash"]').first()
       await expect.poll(() => row.getAttribute('data-state')).toBe('ok')
@@ -126,7 +126,7 @@ describe('web e2e: PTC mode round renders nested sub-calls', () => {
       await terminal.getByText('echo CODE_ROUND_OK', { exact: true }).waitFor()
       await terminal.getByText('CODE_ROUND_OK', { exact: true }).waitFor()
       await expect.poll(() => terminal.locator('[data-state]').getAttribute('data-state')).toBe('done')
-      await expect.poll(() => frame.getAttribute('data-details-collapsed'), { timeout: 5_000 }).toBe('true')
+      await expect.poll(() => frame.getAttribute('data-rightbar-collapsed'), { timeout: 5_000 }).toBe('true')
       const aria = await terminal.ariaSnapshot()
       if (reloaded) expect(aria).toBe(liveTerminalAria)
       else liveTerminalAria = aria
diff --git a/apps/web/tests/queue-actions.e2e.ts b/apps/web/tests/queue-actions.e2e.ts
index 2f45d38d37..086bbce416 100644
--- a/apps/web/tests/queue-actions.e2e.ts
+++ b/apps/web/tests/queue-actions.e2e.ts
@@ -222,6 +222,9 @@ describe('web e2e: queue row actions', () => {
     await expect.poll(() => page.getByRole('button', { name: 'Remove queued message' }).count())
       .toBe(2)
 
+    // Stop becomes Send under the pointer; dismiss its hover tooltip before capture.
+    await page.mouse.move(0, 0)
+    await expect.poll(() => page.getByRole('tooltip').filter({ hasText: 'Send message' }).count()).toBe(0)
     const preservedSnapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)
     await compareOrRefreshGolden(PRESERVED_EXPECTED, preservedSnapshot, MODE)
     const expanded = await captureExpandedTurnProcessAria(
diff --git a/apps/web/tests/reference-composer.e2e.ts b/apps/web/tests/reference-composer.e2e.ts
index b9457dd224..39c7786296 100644
--- a/apps/web/tests/reference-composer.e2e.ts
+++ b/apps/web/tests/reference-composer.e2e.ts
@@ -3,11 +3,13 @@
 // and projects each pick as a complete inline range without issuing a model call.
 import { mkdir, writeFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
+import { homedir } from 'node:os'
 import { join } from 'node:path'
 import type { Browser, Locator, Page } from 'playwright'
 import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { abbreviateHomePath } from '@deepseek-ai/dsh-util-workspace-path'
 import {
   SESSION_FORMAT_VERSION,
   Session,
@@ -171,7 +173,10 @@ describe.skipIf(MODE === 'record')('web e2e: file and session references through
     // Session rows are dated from the live Host list, so their age bucket
     // advances while the suite runs.
     const snapshot = await captureStableAria(
-      page, '[role="listbox"]', scaffold.workspaceCwd, { normalizeAge: true },
+      page, '[role="listbox"]', scaffold.workspaceCwd, {
+        normalizeAge: true,
+        replacements: [[abbreviateHomePath(scaffold.workspaceCwd, homedir()), '{{cwd}}']],
+      },
     )
     await compareOrRefreshGolden(MENU_EXPECTED, snapshot, MODE)
     expect(snapshot).toContain('Files & folders')
@@ -218,9 +223,10 @@ describe.skipIf(MODE === 'record')('web e2e: file and session references through
     const input = page.locator('[data-composer-input]').first()
     const menu = page.getByRole('listbox', { name: 'Trigger suggestions' })
 
-    await writeComposerDraft(page, input, '@reference')
+    await writeComposerDraft(page, input, '@reference.txt')
     await expect.poll(() => input.locator('[data-composer-chip]').count()).toBe(0)
-    await menu.getByRole('option', { name: /reference\.txt/ }).click()
+    await expect.poll(() => menu.getByRole('option').allTextContents()).toEqual(['reference.txt'])
+    await menu.getByRole('option', { name: 'reference.txt', exact: true }).click()
     await expect.poll(() => input.locator('[data-composer-chip]').count()).toBe(1)
 
     // The #2813 gesture: collapse the caret to the document start, directly
@@ -248,9 +254,10 @@ describe.skipIf(MODE === 'record')('web e2e: file and session references through
     const input = page.locator('[data-composer-input]').first()
     const menu = page.getByRole('listbox', { name: 'Trigger suggestions' })
 
-    await writeComposerDraft(page, input, '@reference')
+    await writeComposerDraft(page, input, '@reference.txt')
     await expect.poll(() => input.locator('[data-composer-chip]').count()).toBe(0)
-    await menu.getByRole('option', { name: /reference\.txt/ }).click()
+    await expect.poll(() => menu.getByRole('option').allTextContents()).toEqual(['reference.txt'])
+    await menu.getByRole('option', { name: 'reference.txt', exact: true }).click()
     await expect.poll(() => input.locator('[data-composer-chip]').count()).toBe(1)
 
     // First ArrowLeft crosses the trailing space; the second steps across the
@@ -351,6 +358,7 @@ describe.skipIf(MODE === 'record')('web e2e: file and session references through
     // A crumb above the current step re-lists that directory and keeps the
     // header, which now names the step it returned to.
     await writeComposerDraft(page, input, '@folderx/nested')
+    await expect.poll(() => menu.getByRole('option', { name: /child\.txt/ }).count()).toBe(0)
     const nested = menu.getByRole('option', { name: /^nested\// })
     await nested.waitFor()
     await nested.getByRole('button', { name: 'Browse folder' }).click()
diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts
index ba55bd0e02..2b66a6035b 100644
--- a/apps/web/tests/scaffold.ts
+++ b/apps/web/tests/scaffold.ts
@@ -901,6 +901,28 @@ function mapJsonStringValues(value: unknown, map: (value: string) => string): un
   return value
 }
 
+/** Tokenize the browser timezone carried by user message sources. */
+function normalizeClientTimeZones(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(item => normalizeClientTimeZones(item))
+  if (value !== null && typeof value === 'object') {
+    const next = Object.fromEntries(Object.entries(value).map(([key, item]) => [
+      key,
+      normalizeClientTimeZones(item),
+    ]))
+    const source = (next as { source?: unknown }).source
+    if (source !== null && typeof source === 'object'
+      && (source as { kind?: unknown }).kind === 'user'
+      && typeof (source as { clientTimeZone?: unknown }).clientTimeZone === 'string') {
+      return {
+        ...next,
+        source: { ...source, clientTimeZone: '{{clientTimeZone}}' },
+      }
+    }
+    return next
+  }
+  return value
+}
+
 const WEB_PATH_TEXT_BOUNDARY_RE = /[\s<>'"`()\[\]{},;:!?=]/
 const WEB_FILE_URI_PATH_PREFIX_RE = /(?:^|[^a-z0-9+.-])file:\/\/\/?$/i
 
@@ -956,12 +978,12 @@ export function normalizeWebSessionVolatiles(log: string, workspaceCwd?: string)
     }))].sort((left, right) => right.length - left.length)
   return log.split(/\r?\n/).map((line) => {
     if (line.trim() === '') return line
-    const record = mapJsonStringValues(JSON.parse(line), (value) => {
+    const record = normalizeClientTimeZones(mapJsonStringValues(JSON.parse(line), (value) => {
       let normalized = value
         .replace(/Anonymous user: [0-9a-f-]{36}(?=\.$)/gi, 'Anonymous user: {{anonymousUserId}}')
       for (const cwd of cwdSpellings) normalized = replaceWebCwd(normalized, cwd)
       return normalized
-    }) as { type?: unknown; data?: { endpoint?: unknown } }
+    })) as { type?: unknown; data?: { endpoint?: unknown } }
     if (record.type === 'web/deepseek-search-llm-request' && typeof record.data?.endpoint === 'string') {
       record.data.endpoint = '{{webSearchEndpoint}}'
     }
diff --git a/apps/web/tests/seeded-history.e2e.ts b/apps/web/tests/seeded-history.e2e.ts
index 925bb5322b..2f59edc165 100644
--- a/apps/web/tests/seeded-history.e2e.ts
+++ b/apps/web/tests/seeded-history.e2e.ts
@@ -14,7 +14,7 @@ import { readFile, writeFile, mkdir } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import type { Browser, Page } from 'playwright'
 import { chromium } from 'playwright'
-import { afterAll, beforeAll, describe, expect, it, onTestFailed, vi } from 'vitest'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, Message } from '@deepseek-ai/dsh-llm'
 import { deriveEventMessage, SessionId } from '@deepseek-ai/dsh-session'
@@ -38,7 +38,7 @@ const UI_EXPANDED_EXPECTED = fileURLToPath(
 // Command-row goldens over the same conversation after direct host commands.
 const COMMAND_ROW_EXPECTED = fileURLToPath(new URL('../../../snapshots/web/seeded-history/command-row.expected.md', import.meta.url))
 const FEEDBACK_ROW_EXPECTED = fileURLToPath(new URL('../../../snapshots/web/seeded-history/feedback-row.expected.md', import.meta.url))
-const FILE_OPEN_FAILURE_EXPECTED = fileURLToPath(new URL('../../../snapshots/web/seeded-history/file-open-failure.expected.md', import.meta.url))
+const FILE_PREVIEW_EXPECTED = join(SNAPSHOT_DIR, 'file-preview.expected.md')
 const MODE = webSnapshotMode()
 const SEED_ID = 'seeded-history-web-e2e'
 
@@ -190,11 +190,8 @@ describe('web e2e: seeded history renders through cold resume', () => {
 
   beforeAll(async () => {
     scaffold = await launchWebScaffold({})
-    // The workspace-aware flow runs sessions in <workspaceCwd>/workspace
-    // (the composer's default draft name); the read-tool targets must live in
-    // that session cwd. Pre-creating the directory is safe because the picker
-    // adopts an existing directory by path.
-    const sessionCwd = join(scaffold.workspaceCwd, 'workspace')
+    // Composer recording uses a child workspace; seedSession owns the scaffold root.
+    const sessionCwd = MODE === 'record' ? join(scaffold.workspaceCwd, 'workspace') : scaffold.workspaceCwd
     await mkdir(sessionCwd, { recursive: true })
     await writeFile(join(sessionCwd, 'a.txt'), 'alpha\n')
     await writeFile(join(sessionCwd, 'b.txt'), 'beta\n')
@@ -407,56 +404,35 @@ describe('web e2e: seeded history renders through cold resume', () => {
     await expect.poll(() => disclosure.getAttribute('aria-expanded')).toBe('false')
   })
 
-  it.skipIf(MODE === 'record')('file-path tool rows rebuilt from the cold log stay details-inert', async () => {
-    onTestFailed(() => saveFailureShot(page, 'web-e2e-seeded-toolrow'))
-    // Interaction over cold-resumed history: read summaries are host-open
-    // file links (not expand-in-place / not details). Runs after the golden
-    // capture; still zero model calls.
+  it.skipIf(MODE === 'record')('file-path tool rows rebuilt from the cold log open the right Sidebar', async () => {
+    onTestFailed(async () => {
+      await mkdir(fileURLToPath(new URL('../../../.artifacts/screenshots/0907-2205-sidebar', import.meta.url)), { recursive: true })
+      await saveFailureShot(page, `screenshots/0907-2205-sidebar/seeded-toolrow-${process.pid}`)
+    })
+    // Interaction over cold-resumed history: read summaries are file links
+    // that open a text-preview tab in the right Sidebar (not expand-in-place).
+    // Runs after the golden capture; still zero model calls.
     const fileLink = page.locator('[data-variant="read"] button').first()
     await expandOwningTurnProcess(page, fileLink)
     await fileLink.waitFor({ timeout: 10_000 })
     const frame = page.locator('[style*="grid-template-columns"]').first()
-    expect(await frame.getAttribute('data-details-collapsed')).toBe('true')
-    const openPath = vi.spyOn(scaffold.ctx.sessionController, 'openWorkspacePath')
-      .mockResolvedValue({ opened: true })
-    try {
-      await fileLink.click()
-      await expect.poll(() => frame.getAttribute('data-details-collapsed'), { timeout: 5_000 }).toBe('true')
-    } finally {
-      openPath.mockRestore()
-    }
+    expect(await frame.getAttribute('data-rightbar-collapsed')).toBe('true')
+    await fileLink.click()
+    await expect.poll(() => frame.getAttribute('data-rightbar-collapsed'), { timeout: 5_000 }).toBe(null)
+    const column = page.locator('[data-rightbar-col]')
+    await expect.poll(() => column.locator('[data-dockkit-tab-title]').count(), { timeout: 5_000 }).toBe(2)
     // Path label survives from the recorded args (a.txt).
     await expect.poll(() => page.getByText('a.txt', { exact: false }).count(), { timeout: 5_000 }).toBeGreaterThan(0)
-  })
-
-  it.skipIf(MODE === 'record')('a Host open refusal keeps the reason and retries the same path', async () => {
-    onTestFailed(() => saveFailureShot(page, 'web-e2e-seeded-file-open-failure'))
-    const fileLink = page.locator('[data-variant="read"] button').first()
-    await fileLink.waitFor({ timeout: 10_000 })
-    const openPath = vi.spyOn(scaffold.ctx.sessionController, 'openWorkspacePath')
-      .mockRejectedValue(new Error('xdg-open is not available'))
-    try {
-      await fileLink.click()
-      const dialog = page.getByRole('dialog', { name: 'Couldn’t open file' })
-      await dialog.waitFor({ timeout: 5_000 })
-      const snapshot = await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd)
-      await compareOrRefreshGolden(FILE_OPEN_FAILURE_EXPECTED, snapshot, MODE)
-      await expect.poll(() => dialog.innerText(), { timeout: 5_000 })
-        .toContain('path open failed: xdg-open is not available')
-      await page.getByRole('button', { name: 'Retry' }).click()
-      await expect.poll(() => openPath.mock.calls.length, { timeout: 5_000 }).toBe(2)
-      expect(openPath.mock.calls[0]![0]).toEqual(openPath.mock.calls[1]![0])
-      await page.getByRole('button', { name: 'Cancel' }).click()
-      await expect.poll(() => page.getByRole('dialog', { name: 'Couldn’t open file' }).count(), {
-        timeout: 5_000,
-      }).toBe(0)
-    } finally {
-      // Shared page: a leftover mask blocks later cases even when this one fails.
-      if (await page.getByRole('dialog', { name: 'Couldn’t open file' }).count() > 0) {
-        await page.keyboard.press('Escape')
-      }
-      openPath.mockRestore()
-    }
+    const path = column.locator('[data-textpreview-path]')
+    const absolutePath = join(scaffold.workspaceCwd, 'a.txt')
+    await expect.poll(() => path.textContent()).toBe(absolutePath)
+    expect(await path.getAttribute('title')).toBe(absolutePath)
+    await expect.poll(() => column.locator('[data-textpreview-line="1"]').textContent()).toBe('alpha\n')
+    const preview = await captureStableAria(page, '[data-textpreview-state="text"]', scaffold.workspaceCwd)
+    await compareOrRefreshGolden(FILE_PREVIEW_EXPECTED, preview, MODE)
+    // Put the column back so the later goldens see the default frame.
+    await column.locator('[data-sidebar-right-toggle]').click()
+    await expect.poll(() => frame.getAttribute('data-rightbar-collapsed'), { timeout: 5_000 }).toBe('true')
   })
 
   it.skipIf(MODE === 'record')('expands the cold-resumed compact summary', async () => {
@@ -563,7 +539,7 @@ describe('web e2e: seeded history renders through cold resume', () => {
     expect(tripwire.pageErrors).toEqual([])
     expect(tripwire.warnings).toEqual([])
     await assertFixtureInventory(SNAPSHOT_DIR, [
-      'command-row.expected.md', 'feedback-row.expected.md', 'file-open-failure.expected.md',
+      'command-row.expected.md', 'feedback-row.expected.md', 'file-preview.expected.md',
       'session.v2.jsonl', 'ui.expected.md', 'ui-expanded.expected.md',
     ])
   })
diff --git a/apps/web/tests/sidebar-right.e2e.ts b/apps/web/tests/sidebar-right.e2e.ts
new file mode 100644
index 0000000000..69196119d3
--- /dev/null
+++ b/apps/web/tests/sidebar-right.e2e.ts
@@ -0,0 +1,969 @@
+// Keyless assembled-browser coverage for the shipped right Sidebar: the official
+// roster row, the real plugin graph, and one Chromium. No overlay is applied —
+// this scenario proves the surface is in the product's own composition.
+//
+// The frame owns the right column as a track; the Sidebar anchors its panel to
+// the column's edge and slides it in and out. Which of the two presentations
+// draws the panel is a recorded, reversible choice, so this file asserts against
+// the frame's track as much as against the panel itself. The way back in while
+// collapsed is not in the column at all: it is one button in the conversation
+// header, and it leaves when the panel opens.
+//
+// Ordering is the product's own: the hero comes before any session, so the
+// empty right edge is asserted first and the session-bound cases follow in a
+// nested block that seeds one turn.
+//
+// Copy is asserted in English because this page advertises English, which is
+// itself the point: every string in this column now comes from the dictionary,
+// so an English page renders English. The Chinese draft the product ships is
+// asserted, and captured for review, on its own page at the end.
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Browser, Locator, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import { createMessage, createUserMessage } from '@deepseek-ai/dsh-llm'
+import { launchWebScaffold, watchConsole, type WebScaffold } from './scaffold.ts'
+import {
+  connectFreshWorkspace, newEnglishPage, saveFailureShot, ZH_BROWSER_LOCALE,
+} from './support.ts'
+
+/** The produced file the seeded turn writes, and what the preview should show. */
+const SAMPLE_NAME = 'notes.txt'
+const SAMPLE_TEXT = 'produced by the seeded turn\nsecond line\n'
+
+/** Where this batch's accepted product forms are archived. */
+const SHOT_DIR = fileURLToPath(new URL('../../../.artifacts/screenshots/0907-sidebar-rules', import.meta.url))
+
+/** Archive one accepted product form; the batch receipt cites these by name. */
+async function shot(page: Page, name: string): Promise<void> {
+  mkdirSync(SHOT_DIR, { recursive: true })
+  await page.screenshot({ path: `${SHOT_DIR}/${name}.png`, fullPage: true })
+}
+
+/** Centre of a rendered element, in viewport coordinates. */
+async function centre(locator: Locator): Promise<{ x: number; y: number }> {
+  const box = await locator.boundingBox()
+  if (box === null) throw new Error('element is not rendered')
+  return { x: box.x + box.width / 2, y: box.y + box.height / 2 }
+}
+
+/**
+ * Press a tab chip and release it over a point.
+ *
+ * The press stays left of the chip's nested close control. An optional preview
+ * verifies the browser recognized the drop target before the release.
+ */
+async function dragTo(page: Page, tab: Locator, to: { x: number; y: number }, preview?: Locator): Promise<void> {
+  const box = await tab.boundingBox()
+  if (box === null) throw new Error('tab is not rendered')
+  const from = { x: box.x + 6, y: box.y + box.height / 2 }
+  await page.mouse.move(from.x, from.y)
+  await page.mouse.down()
+  try {
+    await page.mouse.move(to.x, to.y, { steps: 8 })
+    await preview?.waitFor({ state: 'visible' })
+  } finally {
+    await page.mouse.up()
+  }
+}
+
+/** Press an element itself and release over a point (no tab-title indirection). */
+async function dragElement(page: Page, handle: Locator, to: { x: number; y: number }): Promise<void> {
+  const from = await centre(handle)
+  await page.mouse.move(from.x, from.y)
+  await page.mouse.down()
+  await page.mouse.move(to.x, to.y, { steps: 8 })
+  await page.mouse.up()
+}
+
+/** A point inside `locator`, offset by fractions of its own box. */
+async function pointIn(locator: Locator, fx: number, fy: number): Promise<{ x: number; y: number }> {
+  const box = await locator.boundingBox()
+  if (box === null) throw new Error('element is not rendered')
+  return { x: box.x + box.width * fx, y: box.y + box.height * fy }
+}
+
+/** Pause the panel's next real transform transition after observing its initial frame geometry. */
+async function holdPanelSlide(panel: Locator) {
+  return await panel.evaluateHandle((node) => {
+    const controller = new AbortController()
+    const state = { animation: null as Animation | null, columnsAtStart: '', dispose: () => { controller.abort() } }
+    node.addEventListener('transitionrun', (event) => {
+      if (event.target !== node || (event as TransitionEvent).propertyName !== 'transform') return
+      const frame = node.closest('[style*="grid-template-columns"]')
+      if (frame === null) throw new Error('panel frame is unavailable')
+      state.columnsAtStart = getComputedStyle(frame).gridTemplateColumns
+      const slide = node.getAnimations().find(animation =>
+        'transitionProperty' in animation && animation.transitionProperty === 'transform')
+      if (slide === undefined || slide.effect === null) throw new Error('panel transform transition is unavailable')
+      slide.pause()
+      slide.currentTime = Number(slide.effect.getComputedTiming().endTime) / 2
+      state.animation = slide
+      controller.abort()
+    }, { signal: controller.signal })
+    return state
+  })
+}
+
+/** The expand button in the conversation header, present only while collapsed. */
+function expandOf(page: Page): Locator {
+  return page.locator('[data-sidebar-right-expand]')
+}
+
+/**
+ * Make sure the panel is open.
+ *
+ * These cases share one page and run in order, so an earlier one may have left
+ * the panel collapsed; a case that needs tabs says so rather than inheriting
+ * whatever the previous one happened to leave. The way in while collapsed is the
+ * header's expand button, which lives in the conversation, not the column.
+ */
+async function ensureExpanded(page: Page, column: Locator): Promise<void> {
+  if (await column.locator('[data-sidebar-right-open]').count() > 0) return
+  await expandOf(page).click()
+  await column.locator('[data-sidebar-right-open]').waitFor({ timeout: 10_000 })
+}
+
+/** Reload the session's transient sidebar state before an independent gesture case. */
+async function resetSidebar(page: Page): Promise<Locator> {
+  await page.reload({ waitUntil: 'load' })
+  const column = page.locator('[data-rightbar-col]')
+  await expandOf(page).waitFor({ timeout: 15_000 })
+  await ensureExpanded(page, column)
+  await expect.poll(async () => await tabTitles(column)).toEqual(['Start'])
+  await width(column)
+  return column
+}
+
+/** Whether the element at the centre of `locator` is the locator's own element or a descendant. */
+async function hitsItself(locator: Locator): Promise<boolean> {
+  const point = await centre(locator)
+  return await locator.evaluate((node, at) => {
+    const hit = document.elementFromPoint(at.x, at.y)
+    return hit !== null && node.contains(hit)
+  }, point)
+}
+
+/**
+ * Float a docked tab the way a user does: drag its chip clear of the docked
+ * surface and release over the conversation.
+ */
+async function floatByDrag(page: Page, tab: Locator): Promise<void> {
+  const surface = page.locator('[data-dockkit-surface]').first()
+  const box = await surface.boundingBox()
+  if (box === null) throw new Error('surface is not rendered')
+  await dragTo(page, tab, { x: box.x - 240, y: box.y + box.height / 2 })
+}
+
+/**
+ * Drag the frame's rightbar handle until the panel is `target` px wide (the
+ * frame clamps to its own range). The handle sits on the panel's left edge, so
+ * widening is a drag to the left.
+ */
+async function setPanelWidth(page: Page, target: number): Promise<void> {
+  const panel = page.locator('[data-sidebar-right-panel]')
+  const handle = page.locator('[data-side="rightbar"]').first()
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const box = await panel.boundingBox()
+    if (box === null) throw new Error('panel is not rendered')
+    const delta = target - box.width
+    if (Math.abs(delta) < 2) return
+    const grip = await centre(handle)
+    await page.mouse.move(grip.x, grip.y)
+    await page.mouse.down()
+    await page.mouse.move(grip.x - delta, grip.y, { steps: 8 })
+    await page.mouse.up()
+    await page.waitForTimeout(300)
+  }
+}
+
+/** Tab titles inside one container, in strip order. */
+async function tabTitles(root: Locator): Promise<string[]> {
+  return await root.locator('[data-dockkit-tab-title]').allInnerTexts()
+}
+
+/**
+ * A rendered width, read once the frame's track transition has settled.
+ *
+ * The frame eases its grid tracks, so a single sample taken right after a
+ * gesture reports a frame of the animation. Column arithmetic is only exact at
+ * rest, so this samples until three consecutive readings agree.
+ */
+async function width(locator: Locator): Promise<number> {
+  let last = Number.NaN
+  let steady = 0
+  for (let attempt = 0; attempt < 80; attempt += 1) {
+    // Layout width, not the visible box: a zero-width track is still an answer.
+    const now = Math.round(await locator.evaluate(node => node.getBoundingClientRect().width))
+    steady = now === last ? steady + 1 : 0
+    if (steady === 2) return now
+    last = now
+    await locator.page().waitForTimeout(50)
+  }
+  throw new Error(`width never settled (last ${last}px)`)
+}
+
+describe('web e2e: shipped right Sidebar', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let tripwire: ReturnType<typeof watchConsole>
+
+  beforeAll(async () => {
+    scaffold = await launchWebScaffold()
+    browser = await chromium.launch()
+    page = await newEnglishPage(browser)
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+  }, 180_000)
+
+  afterAll(async () => {
+    await browser?.close()
+    await scaffold?.close()
+  })
+
+  it('shows nothing on the right while no session keys a surface', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-right-hero'))
+    const frame = page.locator('[class*="frame"]').first()
+    const column = page.locator('[data-rightbar-col]')
+    await column.waitFor({ state: 'attached', timeout: 15_000 })
+
+    // With no session there is no surface: no panel in the column, no expand
+    // button in the header, and no track — the conversation reaches the frame's edge.
+    expect(await frame.getAttribute('data-rightbar-collapsed')).toBe('true')
+    expect(await column.locator('[data-sidebar-right-panel]').count()).toBe(0)
+    expect(await expandOf(page).count()).toBe(0)
+    expect(await width(column)).toBe(0)
+    await shot(page, '01-hero-no-sidebar')
+
+    expect(tripwire.pageErrors).toEqual([])
+    expect(tripwire.warnings).toEqual([])
+  })
+
+  describe('with a settled session', () => {
+    beforeAll(async () => {
+      await connectFreshWorkspace(page, scaffold.workspaceCwd)
+      // A settled session is what keys the surface; seed one turn through the
+      // real append path so the Chat surface is live before the Sidebar is driven.
+      const agent = scaffold.ctx.agents.list()[0]
+      if (agent === undefined) throw new Error('connected workspace did not create an Agent')
+      // The wire parameter is `agentId`; the client passes a session id. If the
+      // scaffold's Agent and Session carry different ids, that mismatch is the
+      // silent lookup failure.
+      expect(String(agent.id)).toBe(String(agent.session.id))
+      agent.session.append('turn/start', { turn: 1 })
+      agent.session.append('user/message', createUserMessage({
+        content: [{ type: 'text', text: 'Show the right sidebar.' }],
+        source: { kind: 'user' },
+      }), { surfaceOp: 'append' })
+      agent.session.append('step/start', { turn: 1, step: 1 })
+      // A successful mutation is what makes the turn tail offer a produced-file
+      // chip — the product's own way into the Sidebar. The file is written for
+      // real because the preview reads it through the workspace endpoint.
+      //
+      // It goes in the SESSION's cwd, not the scaffold's: the endpoint resolves
+      // relative paths against `sandboxPolicy.resolve({session}).workspaceRoot`,
+      // which is the session header's cwd. Writing anywhere else makes the read
+      // fail with workspace-file/not-found, which is the endpoint being right.
+      writeFileSync(join(agent.session.header.cwd ?? scaffold.workspaceCwd, SAMPLE_NAME), SAMPLE_TEXT, 'utf8')
+      agent.session.append('tool/call', {
+        turn: 1,
+        step: 1,
+        callId: 'call-write-1',
+        name: 'write',
+        arguments: JSON.stringify({ file_path: SAMPLE_NAME, content: SAMPLE_TEXT }),
+      } as never)
+      agent.session.append('tool/result', {
+        turn: 1,
+        step: 1,
+        message: {
+          id: 'result-call-write-1',
+          role: 'user',
+          source: { kind: 'tool', callId: 'call-write-1' },
+          content: [{ type: 'tool-result', toolCallId: 'call-write-1', content: [{ type: 'text', text: 'ok' }] }],
+        },
+      } as never, { surfaceOp: 'append' })
+      agent.session.append('assistant/message', {
+        stream: [],
+        turn: 1,
+        step: 1,
+        message: createMessage({
+          role: 'assistant',
+          content: [{ type: 'text', text: 'Ready.' }],
+          source: { kind: 'model', provider: 'fixture', model: 'fixture' },
+        }),
+      }, { surfaceOp: 'append' })
+      agent.session.append('step/end', { turn: 1, step: 1 })
+      agent.session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+      await scaffold.ctx.sessions.flush(agent.session)
+      await page.getByText('Ready.').waitFor({ timeout: 10_000 })
+    }, 120_000)
+
+    it('CONTROL: the old fileReferences namespace answers over the same wire', async () => {
+      const composer = page.locator('textarea, [contenteditable="true"]').first()
+      await composer.click()
+      await composer.pressSequentially('@')
+      // Any candidate list means the agent-scoped lookup and the gateway route
+      // both work in this scaffold; nothing rendered means the wire is the fault.
+      const answered = await page.locator('[data-input-trigger], [role="listbox"], [data-reference-list]')
+        .first().waitFor({ timeout: 10_000 }).then(() => true, () => false)
+      await page.keyboard.press('Escape')
+      // Leave the composer as it was found: these cases share one page, and a
+      // stray '@' rides into every later assertion and screenshot. `fill('')`
+      // does NOT clear this editor — it reported success while the character
+      // stayed — so the reset is a real keystroke, and it is asserted rather
+      // than assumed.
+      await composer.click()
+      await page.keyboard.press('ControlOrMeta+a')
+      await page.keyboard.press('Backspace')
+      await expect.poll(async () => (await composer.innerText()).trim()).toBe('')
+      expect(answered).toBe(true)
+    })
+
+    it('starts collapsed behind a header button and squeezes the conversation when opened', async () => {
+      onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-right'))
+      const frame = page.locator('[class*="frame"]').first()
+      const column = page.locator('[data-rightbar-col]')
+      const conversation = page.locator('[class*="centerCol"]').first()
+      const expand = expandOf(page)
+
+      // Collapsed default: no track, the panel sits off the frame's edge, and
+      // the only way in is the header button — on the same row as the other
+      // header utilities, at its far right.
+      await expand.waitFor({ timeout: 15_000 })
+      expect(await frame.getAttribute('data-rightbar-collapsed')).toBe('true')
+      expect(await column.locator('[data-sidebar-right-open]').count()).toBe(0)
+      const utilities = page.locator('[class*="headerUtilities"]')
+      const expandBox = await expand.boundingBox()
+      const rowBox = await utilities.boundingBox()
+      if (expandBox === null || rowBox === null) throw new Error('header utilities are not rendered')
+      expect(Math.round(expandBox.y + expandBox.height / 2)).toBe(Math.round(rowBox.y + rowBox.height / 2))
+      // Its own corner seat, past the utilities' right edge — not a utility.
+      expect(expandBox.x).toBeGreaterThan(rowBox.x + rowBox.width)
+      const conversationBoxBefore = await conversation.boundingBox()
+      if (conversationBoxBefore === null) throw new Error('conversation is not rendered')
+      // How far the utilities' right edge sits from the conversation's own.
+      const gapBefore = (conversationBoxBefore.x + conversationBoxBefore.width) - (rowBox.x + rowBox.width)
+      const centerBefore = await width(conversation)
+      await shot(page, '02a-collapsed-header-button')
+
+      // Opening squeezes by default: the column takes a track of the panel's
+      // width, the conversation gives up exactly that much room, and the header
+      // button leaves with the panel's arrival.
+      await expand.click()
+      await expect.poll(async () => await frame.getAttribute('data-rightbar-collapsed')).toBe(null)
+      await expect.poll(async () => await column.locator('[data-sidebar-right-open]').count()).toBe(1)
+      const panelWidth = await width(column)
+      expect(panelWidth).toBeGreaterThan(0)
+      expect(await width(conversation)).toBe(centerBefore - panelWidth)
+      await expect.poll(async () => await expand.count()).toBe(0)
+      // The corner keeps its footprint, so the utilities' right edge stays where
+      // it was relative to the conversation's own right edge.
+      expect(await page.locator('[data-sidebar-right-expand-placeholder]').count()).toBe(1)
+      const utilitiesAfter = await utilities.boundingBox()
+      const conversationAfter = await conversation.boundingBox()
+      if (utilitiesAfter === null || conversationAfter === null) throw new Error('header is not rendered')
+      const gapAfter = (conversationAfter.x + conversationAfter.width) - (utilitiesAfter.x + utilitiesAfter.width)
+      expect(Math.round(gapAfter)).toBe(Math.round(gapBefore))
+
+      // The panel is in the column, not over it, and carries the seeded tab —
+      // whose body arrives through the guide type's keyed registration, not from
+      // any dispatch inside the seat. Its two controls sit at the end of the
+      // top-right pane's strip: the panel has no header row of its own.
+      expect(await column.locator('[data-sidebar-right-panel="push"]').count()).toBe(1)
+      const chrome = column.locator('[data-dockkit-strip-chrome]')
+      expect(await chrome.count()).toBe(1)
+      expect(await chrome.locator('[data-sidebar-right-mode]').count()).toBe(1)
+      expect(await chrome.locator('[data-sidebar-right-toggle]').count()).toBe(1)
+
+      // One centre line across the strip: chip text, split, and the two panel
+      // controls all sit at the same height. The add control joins the check
+      // below, once the strip draws it.
+      const centreY = async (selector: string): Promise<number> => {
+        const box = await column.locator(selector).first().boundingBox()
+        if (box === null) throw new Error(`${selector} is not rendered`)
+        return Math.round(box.y + box.height / 2)
+      }
+      const textLine = await centreY('[data-dockkit-tab-title]')
+      for (const selector of ['[data-dockkit-split-button]', '[data-sidebar-right-mode]', '[data-sidebar-right-toggle]']) {
+        expect(await centreY(selector), selector).toBe(textLine)
+      }
+
+      // The guide is unique per pane, so while this pane holds one its strip
+      // offers no add control. Closing it brings the control back, and the
+      // control opens the guide again in that pane.
+      const addTab = column.locator('[data-dockkit-add-tab]')
+      expect(await addTab.count()).toBe(0)
+      await page.getByRole('button', { name: `Open ${SAMPLE_NAME}` }).click()
+      await expect.poll(async () => await tabTitles(column)).toEqual(['Start', SAMPLE_NAME])
+      await column.locator('[data-dockkit-tab-close]').first().click()
+      await expect.poll(async () => await tabTitles(column)).toEqual([SAMPLE_NAME])
+      await expect.poll(async () => await addTab.count()).toBe(1)
+      expect(await centreY('[data-dockkit-add-tab]')).toBe(textLine)
+      await addTab.click()
+      await expect.poll(async () => await tabTitles(column)).toEqual([SAMPLE_NAME, 'Start'])
+      await expect.poll(async () => await column.locator('[data-sidebar-right-guide]').count()).toBe(1)
+      await expect.poll(async () => await addTab.count()).toBe(0)
+      // Back to the seeded shape the cases below start from.
+      await column.locator('[data-dockkit-tab-close]').first().click()
+      await expect.poll(async () => await tabTitles(column)).toEqual(['Start'])
+      await shot(page, '02-squeezed-panel')
+
+      expect(tripwire.pageErrors).toEqual([])
+      expect(tripwire.warnings).toEqual([])
+    })
+
+    it('covers the viewport in fullscreen without changing the underlying columns', async () => {
+      onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-right-mode'))
+      const frame = page.locator('[class*="frame"]').first()
+      const column = page.locator('[data-rightbar-col]')
+      const panel = column.locator('[data-sidebar-right-panel]')
+      const conversation = page.locator('[class*="centerCol"]').first()
+      const squeezed = await width(conversation)
+      const before = await panel.boundingBox()
+      const trackWidth = await width(column)
+
+      await column.locator('[data-sidebar-right-mode="fullscreen"]').click()
+      await expect.poll(async () => await panel.getAttribute('data-sidebar-right-panel')).toBe('fullscreen')
+      expect(await frame.getAttribute('data-rightbar-collapsed')).toBe(null)
+      expect(await width(conversation)).toBe(squeezed)
+      expect(await width(column)).toBe(trackWidth)
+      const viewport = page.viewportSize()
+      if (viewport === null) throw new Error('expected a fixed viewport')
+      await expect.poll(async () => await panel.boundingBox()).toEqual({ x: 0, y: 0, ...viewport })
+      expect(await expandOf(page).count()).toBe(0)
+      expect(await frame.locator('[data-side="rightbar"]').count()).toBe(0)
+      await shot(page, '03-fullscreen-panel')
+
+      await column.locator('[data-sidebar-right-mode="push"]').click()
+      await expect.poll(async () => await panel.getAttribute('data-sidebar-right-panel')).toBe('push')
+      expect(await width(conversation)).toBe(squeezed)
+      expect(await panel.boundingBox()).toEqual(before)
+
+      expect(tripwire.pageErrors).toEqual([])
+      expect(tripwire.warnings).toEqual([])
+    })
+
+    it('keeps the conversation still during fullscreen entry and installs the hidden track without animation', async () => {
+      onTestFailed(() => saveFailureShot(page, 'screenshots/0907-sidebar-rules/sidebar-right-fullscreen-entry'))
+      mkdirSync(SHOT_DIR, { recursive: true })
+      const column = await resetSidebar(page)
+      const frame = page.locator('[class*="frame"]').first()
+      const panel = column.locator('[data-sidebar-right-panel]')
+      const viewport = page.viewportSize()
+      if (viewport === null) throw new Error('expected a fixed viewport')
+      const geometry = () => frame.evaluate(node => ({
+        columns: getComputedStyle(node).gridTemplateColumns,
+        transition: getComputedStyle(node).transitionProperty,
+        handles: [...node.querySelectorAll('[data-side="sidebar"], [data-side="rightbar"]')]
+          .map(handle => getComputedStyle(handle).transitionProperty),
+        animatingGrid: node.getAnimations().some(animation =>
+          'transitionProperty' in animation && animation.transitionProperty === 'grid-template-columns'
+          && animation.playState !== 'finished' && animation.playState !== 'idle'),
+      }))
+      await frame.evaluate(async (node) => { await Promise.allSettled(node.getAnimations().map(animation => animation.finished)) })
+      const normalColumns = (await geometry()).columns
+      await column.locator('[data-sidebar-right-mode="fullscreen"]').click()
+      await expect.poll(() => panel.boundingBox()).toEqual({ x: 0, y: 0, ...viewport })
+      await column.locator('[data-sidebar-right-toggle]').click()
+      await Promise.all([
+        panel.evaluate(async (node) => { await Promise.allSettled(node.getAnimations().map(animation => animation.finished)) }),
+        frame.evaluate(async (node) => { await Promise.allSettled(node.getAnimations().map(animation => animation.finished)) }),
+      ])
+      const closedColumns = (await geometry()).columns
+      expect(closedColumns).not.toBe(normalColumns)
+      await page.emulateMedia({ reducedMotion: 'no-preference' })
+
+      // Pause the real CSS transition at its midpoint so host scheduling cannot
+      // skip the partly covered frame whose underlying width is under test.
+      const held = await holdPanelSlide(panel)
+      try {
+        await expandOf(page).click()
+        await expect.poll(() => held.evaluate(state => state.animation?.playState)).toBe('paused')
+        const entering = await panel.boundingBox()
+        if (entering === null) throw new Error('entering panel is not rendered')
+        expect(entering.x).toBeGreaterThan(0)
+        expect(entering.x).toBeLessThan(viewport.width)
+        expect((await geometry()).columns).toBe(closedColumns)
+        expect((await geometry()).animatingGrid).toBe(false)
+        expect(await frame.getAttribute('data-rightbar-fullscreen')).toBeNull()
+
+        await held.evaluate((state) => { (state.animation as Animation).finish() })
+        await expect.poll(() => frame.getAttribute('data-rightbar-fullscreen')).toBe('true')
+        expect(await panel.boundingBox()).toEqual({ x: 0, y: 0, ...viewport })
+        expect(await geometry()).toEqual({ columns: normalColumns, transition: 'none', handles: ['none'], animatingGrid: false })
+
+        const exit = await holdPanelSlide(panel)
+        try {
+          await column.locator('[data-sidebar-right-toggle]').click()
+          await expect.poll(() => exit.evaluate(state => state.animation?.playState)).toBe('paused')
+          expect(await exit.evaluate(state => state.columnsAtStart)).toBe(closedColumns)
+          const leaving = await panel.boundingBox()
+          if (leaving === null) throw new Error('leaving panel is not rendered')
+          expect(leaving.x).toBeGreaterThan(0)
+          expect(leaving.x).toBeLessThan(viewport.width)
+          expect(await geometry()).toEqual({ columns: closedColumns, transition: 'none', handles: ['none'], animatingGrid: false })
+          await exit.evaluate((state) => { (state.animation as Animation).finish() })
+          expect((await geometry()).columns).toBe(closedColumns)
+        } finally {
+          await exit.evaluate((state) => {
+            state.dispose()
+            if (state.animation?.playState === 'paused') state.animation.finish()
+          })
+          await exit.dispose()
+        }
+
+        await expandOf(page).click()
+        await expect.poll(() => frame.getAttribute('data-rightbar-fullscreen')).toBe('true')
+        await column.locator('[data-sidebar-right-mode="push"]').click()
+        expect((await geometry()).columns).toBe(normalColumns)
+        expect((await geometry()).animatingGrid).toBe(false)
+
+        await page.emulateMedia({ reducedMotion: 'reduce' })
+        await column.locator('[data-sidebar-right-mode="fullscreen"]').click()
+        await column.locator('[data-sidebar-right-toggle]').click()
+        await expect.poll(() => frame.getAttribute('data-rightbar-fullscreen')).toBeNull()
+        await expandOf(page).click()
+        await expect.poll(() => frame.getAttribute('data-rightbar-fullscreen')).toBe('true')
+        expect(await panel.boundingBox()).toEqual({ x: 0, y: 0, ...viewport })
+        expect((await geometry()).columns).toBe(normalColumns)
+        expect((await geometry()).animatingGrid).toBe(false)
+      } finally {
+        await held.evaluate((state) => {
+          state.dispose()
+          if (state.animation?.playState === 'paused') state.animation.finish()
+        })
+        await held.dispose()
+        try {
+          if (await panel.getAttribute('data-sidebar-right-panel') === 'fullscreen'
+            && await panel.getAttribute('data-sidebar-right-open') !== null) {
+            await column.locator('[data-sidebar-right-mode="push"]').click()
+          }
+        } finally {
+          await page.emulateMedia({ reducedMotion: null })
+        }
+      }
+      expect(tripwire.pageErrors).toEqual([])
+      expect(tripwire.warnings).toEqual([])
+    })
+
+    it('keeps a capacity-closed panel closed after widening and uses fullscreen on a narrow viewport', async () => {
+      const viewport = page.viewportSize()
+      if (viewport === null) throw new Error('expected a fixed viewport')
+      const frame = page.locator('[class*="frame"]').first()
+      const column = page.locator('[data-rightbar-col]')
+      const sidebar = page.locator('[class*="sidebarCol"]').first()
+      const panel = column.locator('[data-sidebar-right-panel]')
+      try {
+        await page.setViewportSize({ width: 1024, height: viewport.height })
+        const leftGrip = frame.locator('[data-side="sidebar"]')
+        const grip = await centre(leftGrip)
+        await dragElement(page, leftGrip, { x: 420, y: grip.y })
+        await expect.poll(async () => await width(sidebar)).toBe(420)
+        await expect.poll(async () => await column.locator('[data-sidebar-right-open]').count()).toBe(0)
+        await page.setViewportSize(viewport)
+        await expect.poll(async () => await width(sidebar)).toBe(420)
+        expect(await column.locator('[data-sidebar-right-open]').count()).toBe(0)
+        await expandOf(page).click()
+        await expect.poll(async () => await column.locator('[data-sidebar-right-open]').count()).toBe(1)
+
+        await page.setViewportSize({ width: 767, height: viewport.height })
+        await expect.poll(async () => await panel.getAttribute('data-sidebar-right-panel')).toBe('fullscreen')
+        await expect.poll(async () => await width(panel)).toBe(767)
+        await expect.poll(() => frame.getAttribute('data-rightbar-fullscreen')).toBe('true')
+        expect(await frame.locator('[data-side="rightbar"]').count()).toBe(0)
+        await column.locator('[data-sidebar-right-mode="push"]').click()
+        await expect.poll(async () => await column.locator('[data-sidebar-right-open]').count()).toBe(0)
+        await page.setViewportSize(viewport)
+        await expect.poll(async () => await width(sidebar)).toBe(420)
+        expect(await column.locator('[data-sidebar-right-open]').count()).toBe(0)
+      } finally {
+        await page.setViewportSize(viewport)
+        const grip = await centre(frame.locator('[data-side="sidebar"]'))
+        await dragElement(page, frame.locator('[data-side="sidebar"]'), { x: 280, y: grip.y })
+        await expect.poll(async () => await width(sidebar)).toBe(280)
+        await ensureExpanded(page, column)
+      }
+      expect(tripwire.pageErrors).toEqual([])
+      expect(tripwire.warnings).toEqual([])
+    })
+
+    it('CONTROL: the host endpoint answers when called directly, bypassing the wire', async () => {
+      const files = (scaffold.ctx as unknown as {
+        get(name: string): {
+          read(agent: unknown, path: string, range: object, signal: AbortSignal): Promise<{ text: string; eof: boolean }>
+        } | undefined
+      }).get('workspaceFiles')
+      if (files === undefined) throw new Error('host endpoint is not provided')
+      const agent = scaffold.ctx.agents.list()[0]
+      if (agent === undefined) throw new Error('no Agent to read for')
+
+      // Raced against a timer so a hang reports a verdict instead of stalling
+      // the suite: this case exists to tell host logic apart from the wire.
+      // A page is the file's lines joined by `\n`, without the final terminator.
+      const verdict = await Promise.race([
+        files.read(agent, SAMPLE_NAME, {}, new AbortController().signal)
+          .then(value => ({ kind: 'settled' as const, text: value.text, eof: value.eof }))
+          .catch((error: unknown) => ({ kind: 'threw' as const, text: String(error), eof: false })),
+        new Promise<{ kind: 'hung'; text: string; eof: boolean }>((resolve) => {
+          setTimeout(() => { resolve({ kind: 'hung', text: 'no settlement in 10s', eof: false }) }, 10_000)
+        }),
+      ])
+      expect(verdict).toEqual({ kind: 'settled', text: SAMPLE_TEXT.replace(/\n$/u, ''), eof: true })
+    }, 30_000)
+
+    it('opens content once, splits, and floats it outside the column', async () => {
+      onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-right-content'))
+      const column = page.locator('[data-rightbar-col]')
+      const panes = column.locator('[data-dockkit-pane]')
+      const floats = page.locator('[data-sidebar-right-float-host] [data-dockkit-float]')
+
+      // Observation before action: does the read ever leave the browser? The
+      // assertion states the healthy answer so a failure prints the real one.
+      //
+      // CAVEAT: `sent` is trustworthy — a request frame carries the endpoint
+      // name. `received` is NOT: a response frame carries only its rpc id, so a
+      // zero here means "my filter saw nothing", not "the host never answered".
+      // Correlate by rpc id before drawing any conclusion from it.
+      const wire = { sent: 0, received: 0 }
+      const watch = (payload: string): void => {
+        if (!payload.includes('workspaceFiles')) return
+        wire.sent += 1
+      }
+      page.on('websocket', (ws) => {
+        ws.on('framesent', (frame) => { watch(String(frame.payload)) })
+        ws.on('framereceived', (frame) => {
+          if (String(frame.payload).includes('workspaceFiles')) wire.received += 1
+        })
+      })
+      page.on('request', (request) => {
+        if (request.url().includes('workspaceFiles')) wire.sent += 1
+      })
+
+      // The product's own entry point: the turn tail's produced-file chip. It
+      // reaches the Sidebar through openFile → ctx.sidebarRight.openResource, and the
+      // text type claims the address.
+      const chip = page.getByRole('button', { name: `Open ${SAMPLE_NAME}` })
+      await chip.click()
+      await expect.poll(async () => await tabTitles(column)).toEqual(['Start', SAMPLE_NAME])
+
+      // Opening the same content again focuses rather than duplicating.
+      await panes.first().locator('[data-dockkit-tab]').first().click()
+      await chip.click()
+      await expect.poll(async () => await tabTitles(column)).toEqual(['Start', SAMPLE_NAME])
+
+      // The body arrives through the text type's keyed registration, and its
+      // content came over the wire from the real file.
+      // A real Remote round-trip settles well after the default poll window.
+      await column.locator('[data-textpreview-state="text"]')
+        .waitFor({ timeout: 15_000 })
+        .catch(() => { throw new Error(`preview never settled; wire=${JSON.stringify(wire)}`) })
+      expect(await column.locator('pre').first().innerText()).toContain('produced by the seeded turn')
+      // The whole batch-E chain in one frame: a produced-file chip in the
+      // conversation, the tab it opened, and the file's real content read over
+      // the workspace endpoint.
+      await shot(page, '06-produced-chip-to-preview')
+
+      // The directory scenario's V1 behaviour, asserted in the shipped product:
+      // there is no folder affordance at all. `openFile('.')` would name a
+      // directory, which a text preview correctly refuses, and the native opener
+      // it used to reach is gone — so the row offers nothing rather than a
+      // button that always fails.
+      expect(await page.getByRole('button', { name: /folder/i }).count()).toBe(0)
+
+      // Split, then dock-drag: the kit's gestures drive the store's actions.
+      await panes.first().locator('[data-dockkit-split-button]').click()
+      await expect.poll(async () => await panes.count()).toBe(2)
+      await dragTo(
+        page,
+        column.locator('[data-dockkit-tab]').filter({ hasText: SAMPLE_NAME }).first(),
+        await pointIn(panes.nth(1), 0.5, 0.94),
+      )
+      await expect.poll(async () => await panes.count()).toBe(2)
+
+      await panes.nth(1).locator('[data-dockkit-tab]').filter({ hasText: 'Start' })
+        .locator('[data-dockkit-tab-close]').click()
+      await expect.poll(async () => await tabTitles(panes.nth(1))).toEqual([SAMPLE_NAME])
+
+      // The guide is unique per pane: panes seeded with one offer no
+      // add control; the pane holding only the file is the one that does.
+      const filePane = panes.filter({ has: page.locator('[data-dockkit-tab-title]', { hasText: SAMPLE_NAME }) })
+      await expect.poll(async () => await filePane.locator('[data-dockkit-add-tab]').count()).toBe(1)
+      expect(await column.locator('[data-dockkit-add-tab]').count()).toBe(1)
+
+      // Floating leaves the column entirely, and survives collapsing it. The
+      // pane the tab was alone in goes with it: an emptied pane never stays.
+      const tab = column.locator('[data-dockkit-tab]').filter({ hasText: SAMPLE_NAME }).first()
+      await floatByDrag(page, tab)
+      await expect.poll(async () => await floats.count()).toBe(1)
+      expect(await column.locator('[data-dockkit-float]').count()).toBe(0)
+      await expect.poll(async () => await panes.count()).toBe(1)
+      await shot(page, '04-split-and-float')
+
+      await column.locator('[data-sidebar-right-toggle]').click()
+      await expect.poll(async () => await column.locator('[data-sidebar-right-open]').count()).toBe(0)
+      expect(await floats.count()).toBe(1)
+
+      expect(tripwire.pageErrors).toEqual([])
+      expect(tripwire.warnings).toEqual([])
+    })
+
+    // §9.2 (an explicit second copy of the same content) has no control on the
+    // panel by product decision, and copy has no service method yet:
+    // `duplicateTab` is a store/kit intent only, which service.client.spec.ts covers.
+
+    it('keeps each session\'s surface to itself, and restores it on return', async () => {
+      const fx = await newEnglishPage(browser)
+      const fxTripwire = watchConsole(fx)
+      onTestFailed(() => saveFailureShot(fx, 'web-e2e-sidebar-right-sessions'))
+      try {
+        await fx.goto(scaffold.authenticatedUrl, { waitUntil: 'load' })
+        const settled = fx.getByRole('treeitem', { name: /Show the right sidebar\./u }).first()
+        await settled.click()
+        await expect.poll(async () => await settled.getAttribute('aria-selected')).toBe('true')
+        const frame = fx.locator('[class*="frame"]').first()
+        const column = fx.locator('[data-rightbar-col]')
+        await ensureExpanded(fx, column)
+        await width(column)
+        await fx.getByRole('button', { name: `Open ${SAMPLE_NAME}` }).click()
+        await column.locator('[data-textpreview-state="text"]').waitFor({ timeout: 15_000 })
+        const wrap = column.locator('[data-textpreview-tool="wrap"]')
+        expect(await wrap.getAttribute('aria-pressed')).toBe('true')
+        await wrap.click()
+        await expect.poll(async () => await wrap.getAttribute('aria-pressed')).toBe('false')
+        await column.locator('[data-dockkit-split-button]').first().click()
+        const panes = column.locator('[data-dockkit-pane]')
+        await expect.poll(async () => await panes.count()).toBe(2)
+        const records = async (): Promise<{ panes: string[]; tabs: string[]; titles: string[] }> => ({
+          panes: await panes.evaluateAll(nodes => nodes.map(node => node.getAttribute('data-dockkit-pane')!)),
+          tabs: await column.locator('[data-dockkit-tab]').evaluateAll(nodes => nodes.map(node => node.getAttribute('data-dockkit-tab')!)),
+          titles: await tabTitles(column),
+        })
+        const before = await records()
+
+        // The real New Session action selects a distinct blank Session; its
+        // collapsed surface must not inherit the settled Session's tabs.
+        await fx.getByRole('button', { name: 'New session', exact: true }).last().click()
+        await expect.poll(async () => await settled.getAttribute('aria-selected')).toBe('false')
+        await expect.poll(async () => await frame.getAttribute('data-rightbar-collapsed')).toBe('true')
+        expect(await column.locator('[data-sidebar-right-open]').count()).toBe(0)
+        expect(await column.locator('[data-textpreview-state="text"]').count()).toBe(0)
+
+        await settled.click()
+        await expect.poll(async () => await settled.getAttribute('aria-selected')).toBe('true')
+        await expect.poll(records, { timeout: 15_000 }).toEqual(before)
+        expect(await column.locator('[data-sidebar-right-open]').count()).toBe(1)
+        expect(await wrap.getAttribute('aria-pressed')).toBe('false')
+        expect(await column.locator('pre').first().innerText()).toContain('produced by the seeded turn')
+        expect(fxTripwire.pageErrors).toEqual([])
+        expect(fxTripwire.warnings).toEqual([])
+      } finally {
+        await fx.close()
+      }
+    }, 120_000)
+
+    it('§9.3/§9.4 runs the whole pointer chain in a real browser', async () => {
+      onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-right-gestures'))
+      const column = await resetSidebar(page)
+      const panes = column.locator('[data-dockkit-pane]')
+      const floats = page.locator('[data-sidebar-right-float-host] [data-dockkit-float]')
+
+      // Chromium cancels pointer capture if a render replaces the pressed
+      // element; jsdom cannot establish that the whole gesture survives.
+
+      // 1. Reorder inside one strip: drop the last tab left of its neighbours.
+      //    The first pane needs two tabs for this — and for the move below to
+      //    leave it standing, since a pane emptied by a move is dropped.
+      const first = panes.first()
+      const strip = first.locator('[data-dockkit-strip]')
+      await page.getByRole('button', { name: `Open ${SAMPLE_NAME}` }).click()
+      await expect.poll(async () => await tabTitles(first)).toEqual(['Start', SAMPLE_NAME])
+      const order = await tabTitles(first)
+      // The insertion index is measured against chip midpoints, not strip width.
+      await dragTo(page, first.locator('[data-dockkit-tab]').last(),
+        await pointIn(first.locator('[data-dockkit-tab]').first(), 0.25, 0.5),
+        strip.locator('[data-dockkit-caret="0"]'))
+      await expect.poll(async () => await tabTitles(first)).toEqual([...order].reverse())
+
+      // 2. Cross-pane move into a second pane: the tab leaves one pane's strip
+      //    for another's.
+      if (await panes.count() < 2) {
+        await first.locator('[data-dockkit-split-button]').click()
+        await expect.poll(async () => await panes.count()).toBe(2)
+      }
+      const moving = first.locator('[data-dockkit-tab]').first()
+      const title = await moving.locator('[data-dockkit-tab-title]').innerText()
+      await dragTo(page, moving, await pointIn(panes.nth(1), 0.5, 0.5))
+      await expect.poll(async () => await tabTitles(panes.nth(1))).toContain(title)
+
+      const splitButtons = column.locator('[data-dockkit-split-button]')
+      await expect.poll(async () => await splitButtons.count()).toBe(0)
+      expect(await panes.count()).toBe(2)
+      await setPanelWidth(page, 560)
+      await expect.poll(async () => await splitButtons.count()).toBe(0)
+
+      const outer = column.locator('[data-dockkit-divider]').first()
+      const before = await width(panes.last())
+      const grip = await centre(outer)
+      await dragElement(page, outer, { x: grip.x - 100, y: grip.y })
+      await expect.poll(async () => await width(panes.last())).toBeGreaterThan(before)
+      await dragElement(page, outer, { x: 0, y: grip.y })
+      const ratio = async (): Promise<number> => {
+        const left = await width(panes.first())
+        const right = await width(panes.last())
+        return left / (left + right)
+      }
+      await expect.poll(ratio).toBeCloseTo(0.2, 2)
+      const surfaceBox = await column.locator('[data-dockkit-surface]').boundingBox()
+      if (surfaceBox === null) throw new Error('surface is not rendered')
+      await dragElement(page, outer, { x: surfaceBox.x + surfaceBox.width / 2, y: grip.y })
+      await expect.poll(ratio).toBeCloseTo(0.5, 2)
+      expect(await panes.count()).toBe(2)
+      expect(await splitButtons.count()).toBe(0)
+
+      // 5. Two floats coexist, and one of them moves. Both leave the widest
+      //    pane; a pane emptied by the first float is merged away, so the
+      //    second one comes from whichever pane is widest by then.
+      const floatOne = panes.last().locator('[data-dockkit-tab]').first()
+      await floatByDrag(page, floatOne)
+      await expect.poll(async () => await floats.count()).toBe(1)
+      const box = await floats.first().boundingBox()
+      if (box === null) throw new Error('float is not rendered')
+      await dragElement(page, floats.first().locator('[data-dockkit-float-grip]'), { x: box.x + 140, y: box.y + 90 })
+      await expect.poll(async () => (await floats.first().boundingBox())?.x ?? box.x).not.toBe(box.x)
+
+      const second = panes.last().locator('[data-dockkit-tab]').first()
+      await floatByDrag(page, second)
+      await expect.poll(async () => await floats.count()).toBe(2)
+
+      // 6. Dock one back: the docked tree takes it, the other float stays. Dock
+      //    the TOPMOST float — floats render bottom-to-top, so the newest one
+      //    covers the older one's controls and would intercept the click.
+      await floats.last().locator('[data-dockkit-float-dock]').click()
+      await expect.poll(async () => await floats.count()).toBe(1)
+
+      expect(tripwire.pageErrors).toEqual([])
+      expect(tripwire.warnings).toEqual([])
+    }, 90_000)
+
+    it('drops a pane whose last tab closes, and reseeds the guide when none is left', async () => {
+      onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-right-settle'))
+      const column = await resetSidebar(page)
+      const panes = column.locator('[data-dockkit-pane]')
+      await panes.first().locator('[data-dockkit-split-button]').click()
+      await expect.poll(async () => await panes.count()).toBe(2)
+      const closeAllIn = async (pane: Locator): Promise<void> => {
+        const tabs = await pane.locator('[data-dockkit-tab]').count()
+        for (let i = 0; i < tabs; i += 1) {
+          await pane.locator('[data-dockkit-tab-close]').first().click()
+        }
+      }
+
+      // Closing a pane's last tab drops the pane: there is no separate
+      // "close pane" gesture, and none is needed.
+      let count = await panes.count()
+      expect(count).toBeGreaterThan(1)
+      while (count > 1) {
+        await closeAllIn(panes.nth(count - 1))
+        await expect.poll(async () => await panes.count()).toBe(count - 1)
+        count -= 1
+      }
+
+      // The last pane cannot be dropped, so closing everything in it reseeds
+      // the guide: the surface always has one tab to look at.
+      await closeAllIn(panes.first())
+      await expect.poll(async () => await tabTitles(column)).toEqual(['Start'])
+      expect(await column.locator('[data-sidebar-right-guide]').count()).toBe(1)
+
+      expect(tripwire.pageErrors).toEqual([])
+      expect(tripwire.warnings).toEqual([])
+    }, 90_000)
+
+    it('§9.7 returns to the default surface after a reload', async () => {
+      onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-right-reload'))
+      await page.reload({ waitUntil: 'load' })
+      await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+      const frame = page.locator('[class*="frame"]').first()
+      const column = page.locator('[data-rightbar-col]')
+      await column.waitFor({ state: 'attached', timeout: 15_000 })
+      // The surface is view state, not durable session data: a reload zeroes it
+      // back to the collapsed default. Expected behaviour, not a defect.
+      await expect.poll(async () => await frame.getAttribute('data-rightbar-collapsed')).toBe('true')
+      await expect.poll(async () => await expandOf(page).count()).toBe(1)
+      expect(await column.locator('[data-sidebar-right-open]').count()).toBe(0)
+    })
+
+    it('opens a context menu on right-click that the strip cannot clip', async () => {
+      onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-right-menu'))
+      const column = page.locator('[data-rightbar-col]')
+
+      await ensureExpanded(page, column)
+      await expect.poll(async () => await column.locator('[data-dockkit-tab]').count()).toBeGreaterThan(0)
+      // No "more" control on the chip: the chip carries its close, and the menu
+      // is the secondary press.
+      expect(await column.locator('[data-dockkit-tab-more]').count()).toBe(0)
+      await column.locator('[data-dockkit-tab]').first().click({ button: 'right' })
+      const menu = page.locator('[data-dockkit-tab-menu]')
+      await expect.poll(async () => await menu.count()).toBe(1)
+
+      // The kit's one item; the extension seat is declared and rendered, and
+      // with no registrant it contributes nothing, which is what "declared, not
+      // speculative" looks like from the outside.
+      await expect.poll(async () => await menu.getByRole('menuitem').allInnerTexts()).toEqual(['Close'])
+      // The menu hangs below the strip that clips its overflow. Its pixels are
+      // its own: a hit test at its centre lands on it, not on whatever the
+      // strip would have shown through a clipped box.
+      expect(await hitsItself(menu)).toBe(true)
+      const box = await menu.boundingBox()
+      const viewport = page.viewportSize()
+      if (box === null || viewport === null) throw new Error('menu or viewport is not measurable')
+      expect(box.x).toBeGreaterThanOrEqual(0)
+      expect(box.x + box.width).toBeLessThanOrEqual(viewport.width)
+      await page.keyboard.press('Escape')
+
+      expect(tripwire.pageErrors).toEqual([])
+      expect(tripwire.warnings).toEqual([])
+    })
+
+    // The product ships Chinese; the cases above advertise English so their role
+    // locators stay stable. This is the other half of the same seam, and the
+    // screenshot it takes is what the copy draft gets reviewed from. It lives in
+    // this block because a settled session is its precondition too — a case that
+    // depends on a sibling block's setup passes only in the right order.
+    it('renders the shipped Chinese copy on a Chinese page', async () => {
+      const zhPage = await browser.newPage({ viewport: { width: 1680, height: 1000 }, locale: ZH_BROWSER_LOCALE })
+      const zhTripwire = watchConsole(zhPage)
+      onTestFailed(() => saveFailureShot(zhPage, 'web-e2e-sidebar-right-zh'))
+      try {
+        await zhPage.goto(scaffold.authenticatedUrl, { waitUntil: 'load' })
+        await zhPage.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+        // A fresh page opens the workspace on a blank session's hero, which has
+        // no session header and so no expand button. The settled session is the
+        // second row of the tree; pick it the way a user would.
+        await zhPage.getByRole('treeitem', { name: /Show the right sidebar\./u }).first().click()
+        const column = zhPage.locator('[data-rightbar-col]')
+        await expandOf(zhPage).waitFor({ timeout: 20_000 })
+        await expandOf(zhPage).click()
+
+        const guide = column.locator('[data-sidebar-right-guide]')
+        await expect.poll(async () => await guide.count()).toBe(1)
+        // Wait for the track, not just the panel: the copy is only legible once
+        // the column has the width, and a screenshot taken mid-transition reads
+        // as a layout defect that is not there.
+        expect(await width(column)).toBeGreaterThan(300)
+        await expect.poll(async () => await tabTitles(column)).toEqual(['开始'])
+        await expect.poll(async () => await guide.locator('p').first().innerText())
+          .toBe('侧栏用来放你想一直看着的东西。')
+        await shot(zhPage, '05-guide-copy-zh')
+
+        expect(zhTripwire.pageErrors).toEqual([])
+        expect(zhTripwire.warnings).toEqual([])
+      } finally {
+        await zhPage.close()
+      }
+    }, 120_000)
+  })
+})
diff --git a/apps/web/tests/snapshots/streaming-fence-highlight/mid-stream.expected.md b/apps/web/tests/snapshots/streaming-fence-highlight/mid-stream.expected.md
index fec0614de5..1ca602fbd7 100644
--- a/apps/web/tests/snapshots/streaming-fence-highlight/mid-stream.expected.md
+++ b/apps/web/tests/snapshots/streaming-fence-highlight/mid-stream.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -24,7 +26,7 @@
 - button "Copy"
 - code: "const first: number = 1 const second = \"two\" let tail"
 - status: Deep diving...
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
diff --git a/apps/web/tests/startup-auto-selection.e2e.ts b/apps/web/tests/startup-auto-selection.e2e.ts
index 1404402b4f..613eb4a7d0 100644
--- a/apps/web/tests/startup-auto-selection.e2e.ts
+++ b/apps/web/tests/startup-auto-selection.e2e.ts
@@ -42,7 +42,9 @@ describe('web e2e: startup auto-selection', () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-first-workspace-stable-tree'))
     await page.locator(`${ROOT_PHASE}[data-phase="hero"]`).waitFor({ timeout: 15_000 })
     const headline = page.getByText('Into the Unknown', { exact: true })
-    const fishHitbox = headline.locator('xpath=preceding-sibling::span[1]')
+    // The headline text sits in its own span inside the title group; the fish
+    // hitbox precedes the group, not the text span.
+    const fishHitbox = headline.locator('xpath=../preceding-sibling::span[1]')
     const fish = fishHitbox.locator('svg')
     expect(await fish.evaluate(node => getComputedStyle(node).color))
       .toBe(await headline.evaluate(node => getComputedStyle(node).color))
@@ -130,7 +132,7 @@ describe('web e2e: startup auto-selection', () => {
       expect(await page.locator('[data-composer-input]').first().isVisible()).toBe(true)
 
       releaseOpening()
-      await page.locator('[data-composer-input][contenteditable="true"][data-placeholder="Describe what you want to build... / commands, @ files or sessions"]')
+      await page.locator('[data-composer-input][contenteditable="true"][data-placeholder="Describe what you want to build, / commands, @ files or sessions"]')
         .waitFor({ timeout: 15_000 })
       acknowledgeReloadConnectionLoss(tripwire, warningsBefore)
 
diff --git a/apps/web/tests/stats-paged-history.e2e.ts b/apps/web/tests/stats-paged-history.e2e.ts
index 6e6174232c..45e5d3de2d 100644
--- a/apps/web/tests/stats-paged-history.e2e.ts
+++ b/apps/web/tests/stats-paged-history.e2e.ts
@@ -23,7 +23,7 @@ const SEED_ID = 'stats-paged-history-web-e2e'
 
 /** Turn count: 2 surface messages per turn, so 28 turns overflow one 50-message page. */
 const TURNS = 28
-const FULL_COUNTS = `${TURNS} turns · ${TURNS} steps`
+const FULL_COUNTS = `${TURNS} turns ${TURNS} steps`
 
 /**
  * Generate the seed: TURNS closed single-step turns of one short user prompt
diff --git a/apps/web/tests/subagent-conversation.e2e.ts b/apps/web/tests/subagent-conversation.e2e.ts
index d9b66749de..54e9960836 100644
--- a/apps/web/tests/subagent-conversation.e2e.ts
+++ b/apps/web/tests/subagent-conversation.e2e.ts
@@ -423,7 +423,7 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
       expect(await page.locator('[data-composer-seat]').evaluate(element =>
         getComputedStyle(element).visibility)).toBe('hidden')
       releaseCatalog()
-      const input = page.getByRole('textbox', { name: 'Message or run a task... / commands, @ files or sessions' })
+      const input = page.getByRole('textbox', { name: 'Message or run a task, / commands, @ files or sessions' })
       await input.waitFor({ timeout: 15_000 })
       await expect.poll(() => input.isEnabled(), { timeout: 15_000 }).toBe(true)
       acknowledgeReloadConnectionLoss(tripwire, warningStart)
@@ -447,7 +447,7 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
         resolveEnded()
       })
     })
-    const input = page.getByRole('textbox', { name: 'Message or run a task... / commands, @ files or sessions' })
+    const input = page.getByRole('textbox', { name: 'Message or run a task, / commands, @ files or sessions' })
     await input.fill(FOLLOWUP)
     await input.press('Enter')
     await expect.poll(
@@ -537,7 +537,7 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
       .click()
     await page.getByRole('button', { name: '3 subagents' }).hover()
     await page.getByRole('treeitem', { name: new RegExp(LABEL) }).click()
-    await page.getByRole('textbox', { name: 'Message or run a task... / commands, @ files or sessions' }).waitFor()
+    await page.getByRole('textbox', { name: 'Message or run a task, / commands, @ files or sessions' }).waitFor()
     const forkResponse = page.waitForResponse(response =>
       new URL(response.url()).pathname === '/api/session/fork')
     await page.getByRole('button', { name: 'Branch into a new conversation' }).last().click()
diff --git a/apps/web/tests/subagent-interrupt-ui.e2e.ts b/apps/web/tests/subagent-interrupt-ui.e2e.ts
index 8898c6943b..ba14833ef4 100644
--- a/apps/web/tests/subagent-interrupt-ui.e2e.ts
+++ b/apps/web/tests/subagent-interrupt-ui.e2e.ts
@@ -279,10 +279,12 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
     expect(await input.isDisabled()).toBe(false)
 
     // Queue a follow-up through Send while independent Stop remains available.
+    // The running child's Send names its delivery like an ordinary session:
+    // the default busy-state preference is Queue.
     const promptResponse = page.waitForResponse(response =>
       new URL(response.url()).pathname === '/api/subagents/prompt')
     await input.fill(FOLLOWUP)
-    await page.getByRole('button', { name: 'Send message' }).click()
+    await page.getByRole('button', { name: 'Queue message' }).click()
     expect(((await (await promptResponse).json()) as { result: { ok: boolean } }).result)
       .toMatchObject({ ok: true })
 
diff --git a/apps/web/tests/support.ts b/apps/web/tests/support.ts
index 99032e7dfa..63486fe752 100644
--- a/apps/web/tests/support.ts
+++ b/apps/web/tests/support.ts
@@ -113,7 +113,7 @@ export async function connectFreshWorkspace(page: Page, root: string, name = 'wo
   await dialog.getByRole('button', { name: 'Open', exact: true }).click()
   // The pick connected the workspace: the blank session's live composer
   // replaces the locked placeholder and enables.
-  await page.locator('[data-composer-input][contenteditable="true"][data-placeholder="Describe what you want to build... / commands, @ files or sessions"]')
+  await page.locator('[data-composer-input][contenteditable="true"][data-placeholder="Describe what you want to build, / commands, @ files or sessions"]')
     .waitFor({ timeout: 15_000 })
 }
 
@@ -136,7 +136,7 @@ export async function connectFreshWorkspaceZh(page: Page, root: string, name = '
   await pathInput.fill(join(root, name))
   await pathInput.press('Enter')
   await dialog.getByRole('button', { name: '打开', exact: true }).click()
-  await page.locator('[data-composer-input][contenteditable="true"][data-placeholder="描述你想要构建的内容… / 调用指令 @ 文件或对话"]')
+  await page.locator('[data-composer-input][contenteditable="true"][data-placeholder="描述你想要构建的内容, / 调用指令, @ 文件或对话"]')
     .waitFor({ timeout: 15_000 })
 }
 
diff --git a/apps/web/tests/workspace-management.e2e.ts b/apps/web/tests/workspace-management.e2e.ts
index 382e549ddf..d591dbe3b0 100644
--- a/apps/web/tests/workspace-management.e2e.ts
+++ b/apps/web/tests/workspace-management.e2e.ts
@@ -42,6 +42,8 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
   let browser: Browser
   let page: Page
   let tripwire: ReturnType<typeof watchConsole>
+  let holdAttachment = false
+  let releaseAttachment: (() => void) | undefined
 
   /**
    * Raise the region header's directory dialog and drive it to a directory via
@@ -124,6 +126,22 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
     await seedSession(scaffold, await readFile(SEED, 'utf8'), SEED_ID)
     browser = await chromium.launch()
     page = await newEnglishPage(browser)
+    await page.routeWebSocket('**/api/remote.mux', (route) => {
+      const server = route.connectToServer()
+      server.onMessage((message) => {
+        const frame = JSON.parse(String(message)) as {
+          type: string
+          value?: { type: string; workspace?: { sessionIds: string[] } }
+        }
+        if (holdAttachment && frame.type === 'item' && frame.value?.type === 'upsert'
+          && frame.value.workspace?.sessionIds.includes(SEED_ID) === true) {
+          holdAttachment = false
+          releaseAttachment = () => { route.send(message) }
+          return
+        }
+        route.send(message)
+      })
+    })
     tripwire = watchConsole(page)
     await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' })
     await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
@@ -131,6 +149,7 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
 
   afterAll(async () => {
     await browser?.close()
+    releaseAttachment = undefined
     await scaffold?.close()
   })
 
@@ -211,6 +230,7 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
     await adoptDirectory(scaffold.workspaceCwd, { waitForAgent: true })
     const workspace = await scaffold.ctx.workspaceRegistry.resolveByPath(scaffold.workspaceCwd)
     if (workspace === undefined) throw new Error('GUI did not register the existing project directory')
+    holdAttachment = true
     await workspace.attachSession(SessionId(SEED_ID))
     const header = (await scaffold.ctx.sessionPersistence.list())
       .map(snapshot => snapshot.header)
@@ -220,23 +240,25 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
     expect(await readFile(join(scaffold.workspaceCwd, 'workspace', 'a.txt'), 'utf8')).toBe('alpha\n')
     await stat(seededLogPath)
 
-    // Open the seeded (first/accounted) Session so deletion must preserve the
-    // current selection while it moves into Ungrouped.
+    // The attachment stream can lag the Host commit while New Session is
+    // already visible. A row count or position cannot identify the seed.
     const groupRow = page.locator('[role="treeitem"]').filter({ hasText: workspace.title }).first()
     await groupRow.waitFor({ timeout: 10_000 })
     // The header row is wrapped by its HoverCard anchor span, so the section
     // is the nearest groupSection ancestor, not the immediate parent.
     const groupSection = groupRow.locator('xpath=ancestor::*[contains(@class, "groupSection")][1]')
-    await expect.poll(async () => {
-      const count = await groupSection.locator('[role="treeitem"]').count()
-      if (count < 2 && await groupRow.getAttribute('aria-expanded') !== 'true') {
-        await groupRow.click()
-        await page.waitForTimeout(50)
-      }
-      return await groupSection.locator('[role="treeitem"]').count()
-    }, { timeout: 10_000 }).toBeGreaterThanOrEqual(2)
-    const seededRow = groupSection.locator('[role="treeitem"]').nth(1)
-    await seededRow.click()
+    if (await groupRow.getAttribute('aria-expanded') !== 'true') await groupRow.click()
+    const blankRow = groupSection.getByRole('treeitem', { name: 'New Session', exact: true })
+    await expect.poll(() => blankRow.getAttribute('aria-selected'), { timeout: 10_000 }).toBe('true')
+    // The seed is this account's only non-blank Session; its title changes on resume.
+    const seededRow = groupSection.locator('[role="treeitem"][aria-selected]')
+      .filter({ hasNot: page.getByText('New Session', { exact: true }) })
+    await expect.poll(() => releaseAttachment, { timeout: 10_000 }).toBeDefined()
+    expect(await seededRow.count()).toBe(0)
+    const deliverAttachment = releaseAttachment!
+    releaseAttachment = undefined
+    deliverAttachment()
+    await seededRow.click({ timeout: 10_000 })
     await expect.poll(() => seededRow.getAttribute('aria-selected'), { timeout: 10_000 }).toBe('true')
 
     await clickHoverAction(groupRow, `Workspace actions for ${workspace.title}`)
@@ -463,9 +485,8 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
   }, 60_000)
 
   /**
-   * Expand Ungrouped and return its seeded session row. The only visible child
-   * is the non-blank persisted Session; the blank Session created while
-   * adopting the Workspace stays hidden.
+   * Expand Ungrouped and return its only non-blank session row. A selected
+   * blank Session from a deleted Workspace may also be visible, without actions.
    * @returns the session row locator, already present.
    */
   async function seededSessionRow() {
@@ -480,9 +501,11 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
       }
       return await ungroupedRow.getAttribute('aria-expanded')
     }, { timeout: 5_000 }).toBe('true')
-    const row = ungroupedSection.locator('[role="treeitem"]').nth(1)
-    await row.waitFor({ timeout: 10_000 })
-    return row
+    // CSS includes the actions button while it is hidden until row hover.
+    const rows = ungroupedSection.locator('[role="treeitem"]')
+      .filter({ has: page.locator('button[aria-label^="Session actions for "]') })
+    await expect.poll(() => rows.count(), { timeout: 10_000 }).toBe(1)
+    return rows.first()
   }
 
   it('shows the session hover card after a dwell on the row', async () => {
@@ -552,26 +575,13 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
 
   it('archives the seeded session from its row menu, hiding it durably across reload', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-ws-archive'))
-    // The seeded session lives under Ungrouped (expanded by the hover-card
-    // test's gesture; converge again for order independence).
-    const ungroupedRow = page.getByText('Ungrouped', { exact: true }).locator('..').locator('..')
-    const ungroupedSection = ungroupedRow.locator('..')
-    await expect.poll(async () => {
-      if (await ungroupedRow.getAttribute('aria-expanded') !== 'true') {
-        await page.getByText('Ungrouped', { exact: true }).click()
-        await page.waitForTimeout(50)
-      }
-      return await ungroupedRow.getAttribute('aria-expanded')
-    }, { timeout: 5_000 }).toBe('true')
-    // Anchor on session rows (the rows carrying a session actions button),
-    // not a positional index, and assert the single-stray assumption loudly
-    // so a fixture gaining a second stray fails here instead of archiving
-    // the wrong row. CSS attribute match, not getByRole: the button is
-    // display:none until its row hovers, and role queries skip hidden nodes.
-    const sessionRows = ungroupedSection.locator('[role="treeitem"]')
-      .filter({ has: page.locator('button[aria-label^="Session actions for "]') })
-    await expect.poll(() => sessionRows.count(), { timeout: 10_000 }).toBe(1)
-    const sessionRow = sessionRows.first()
+    const sessionRow = await seededSessionRow()
+    // Selecting the seed hides any blank stray left by Workspace deletion,
+    // so archiving this last visible Ungrouped Session must remove the bucket.
+    await sessionRow.click()
+    await expect.poll(() => sessionRow.getAttribute('aria-selected'), { timeout: 10_000 }).toBe('true')
+    const ungroupedSection = page.getByText('Ungrouped', { exact: true }).locator('..').locator('..').locator('..')
+    await expect.poll(() => ungroupedSection.locator('[role="treeitem"]').count(), { timeout: 10_000 }).toBe(2)
     const rowTitle = await sessionRow.locator('[class*="title"]').innerText()
     // Row menu: hover reveals the actions button; Archive session commits
     // without a confirmation dialog (non-destructive: log + accounting stay).
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index 17c8670403..cdfc17fae0 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -87,6 +87,7 @@
     "tests/feedback-command.e2e.ts",
     "tests/feedback-release.e2e.ts",
     "tests/agent-team-panel.e2e.ts",
+    "tests/sidebar-right.e2e.ts",
     "tests/startup-auto-selection.e2e.ts",
     "tests/produced-files.e2e.ts",
     "tests/produced-file-mentions.e2e.ts",
diff --git a/docs/capability-seams.i18n.yaml b/docs/capability-seams.i18n.yaml
index 93823b7b78..c370fbef7f 100644
--- a/docs/capability-seams.i18n.yaml
+++ b/docs/capability-seams.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/capability-seams.md
-capability-seams.md: fd27d61959fbc53589c1345cfb9cc9bc0acbb161
-capability-seams.zh.md: 6fb09b90df6656c6b57f69afd0c76ef39baf5510
+capability-seams.md: a47ec285e248c4d969e49bc941d5c93faef7b65e
+capability-seams.zh.md: 42e7105611f21f74ee0d8088e06e5c7007af9376
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index fd27d61959..a47ec285e2 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -44,6 +44,8 @@ flowchart LR
   pkg_api_settings_controller["api-settings-controller"]
   svc_credentialsController["ctx.credentialsController<br/>Host credential-surface Remote controller"]
   svc_settingsController["ctx.settingsController<br/>Host settings-surface Remote controller"]
+  pkg_api_workspace_files["api-workspace-files"]
+  svc_workspaceFiles["ctx.workspaceFiles<br/>Host workspace file Remote service"]
   pkg_api_workspace_controller["api-workspace-controller"]
   svc_workspaceController["ctx.workspaceController<br/>Host Workspace Remote controller"]
   svc_directoryPickerController["ctx.directoryPickerController<br/>Host directory-picking Remote controller"]
@@ -232,6 +234,7 @@ flowchart LR
   pkg_api_settings_controller --> svc_settingsController
   pkg_api_workspace_controller --> svc_directoryPickerController
   pkg_api_workspace_controller --> svc_workspaceController
+  pkg_api_workspace_files --> svc_workspaceFiles
   pkg_attachment --> svc_attachments
   pkg_attachment_local --> svc_attachments
   pkg_authorization --> svc_authorization
@@ -480,6 +483,7 @@ flowchart LR
 | `ctx.sessionSkillCatalog` | `core` | [`api-session-controller`](../packages/api/session-controller) | - | - | - | Lists the Session composition's user-invocable skills without activating a cold Agent. |
 | `ctx.credentialsController` | `core` | [`api-settings-controller`](../packages/api/settings-controller) | - | - | - | Projects the credential-reference seam onto the generated Remote namespace: batch fan-out, view projection, and refusal mapping live here, not on the seam Definition. |
 | `ctx.settingsController` | `core` | [`api-settings-controller`](../packages/api/settings-controller) | - | - | - | Projects the user-settings seam onto the generated Remote namespace: the read is always redacted and every refusal is classified here, not on the seam Definition. |
+| `ctx.workspaceFiles` | `core` | [`api-workspace-files`](../packages/api/workspace-files) | - | - | - | Serves stat, paged text, byte windows, directory listings, and the change feed for files inside a Session's workspace root, confined by lstat, containment, and a stat re-check. |
 | `ctx.workspaceController` | `core` | [`api-workspace-controller`](../packages/api/workspace-controller) | - | - | - | Owns Workspace commands and reconnect-safe Workspace state delivery through the generated Remote namespace. |
 | `ctx.directoryPickerController` | `core` | [`api-workspace-controller`](../packages/api/workspace-controller) | - | - | - | Carries the picking seam onto the wire: capability gating, cancellation, and the seam-coded failures a browser directory flow discriminates on. |
 | `ctx.invariants` | `core` | [`invariants`](../packages/runtime-diagnostics/invariants) | - | [`session`](../packages/core/session), [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`agent-loop`](../packages/core/agent-loop) | - | Companion subpaths register owner-local checks; the service owns selection, uniqueness, child fibers, and package-attributed failures. |
diff --git a/docs/capability-seams.zh.md b/docs/capability-seams.zh.md
index 6fb09b90df..42e7105611 100644
--- a/docs/capability-seams.zh.md
+++ b/docs/capability-seams.zh.md
@@ -46,6 +46,8 @@ flowchart LR
   pkg_api_settings_controller["api-settings-controller"]
   svc_credentialsController["ctx.credentialsController<br/>Host credential-surface Remote controller"]
   svc_settingsController["ctx.settingsController<br/>Host settings-surface Remote controller"]
+  pkg_api_workspace_files["api-workspace-files"]
+  svc_workspaceFiles["ctx.workspaceFiles<br/>Host workspace file Remote service"]
   pkg_api_workspace_controller["api-workspace-controller"]
   svc_workspaceController["ctx.workspaceController<br/>Host Workspace Remote controller"]
   svc_directoryPickerController["ctx.directoryPickerController<br/>Host directory-picking Remote controller"]
@@ -234,6 +236,7 @@ flowchart LR
   pkg_api_settings_controller --> svc_settingsController
   pkg_api_workspace_controller --> svc_directoryPickerController
   pkg_api_workspace_controller --> svc_workspaceController
+  pkg_api_workspace_files --> svc_workspaceFiles
   pkg_attachment --> svc_attachments
   pkg_attachment_local --> svc_attachments
   pkg_authorization --> svc_authorization
@@ -482,6 +485,7 @@ flowchart LR
 | `ctx.sessionSkillCatalog` | `core` | [`api-session-controller`](../packages/api/session-controller) | - | - | - | 在不激活冷 Agent 的前提下列出 Session 组合中允许用户调用的 skill。 |
 | `ctx.credentialsController` | `core` | [`api-settings-controller`](../packages/api/settings-controller) | - | - | - | 把凭据引用 seam 投影到生成的 Remote namespace：批量扇出、视图投影与拒绝映射都在这里，而不在 seam Definition 上。 |
 | `ctx.settingsController` | `core` | [`api-settings-controller`](../packages/api/settings-controller) | - | - | - | 把用户设置 seam 投影到生成的 Remote namespace：读取一律脱敏，所有拒绝在这里分类，而不在 seam Definition 上。 |
+| `ctx.workspaceFiles` | `core` | [`api-workspace-files`](../packages/api/workspace-files) | - | - | - | 为会话工作区根内的文件提供 stat、分页文本、字节窗口、目录列举与变更流，经 lstat、包含关系与 stat 重检限定。 |
 | `ctx.workspaceController` | `core` | [`api-workspace-controller`](../packages/api/workspace-controller) | - | - | - | 通过生成的 Remote namespace 负责 Workspace 命令和可在重连后收敛的 Workspace 状态投递。 |
 | `ctx.directoryPickerController` | `core` | [`api-workspace-controller`](../packages/api/workspace-controller) | - | - | - | 把选目录 seam 送上线：能力门禁、取消传播，以及浏览器目录流程用于分支判断的 seam 错误码。 |
 | `ctx.invariants` | `core` | [`invariants`](../packages/runtime-diagnostics/invariants) | - | [`session`](../packages/core/session), [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`agent-loop`](../packages/core/agent-loop) | - | 配套子路径注册所属包本地的检查；该服务负责选择、唯一性、子 fiber，以及标明所属包的失败。 |
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 933ebbaa13..d52edac87b 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/config-catalog.md
-config-catalog.md: 32644b4782cc424835f9e303fff5f30ce95cd14f
-config-catalog.zh.md: 24dc4a3cb7acc1b793d25e5ac3cafc1b5e86e14a
+config-catalog.md: 12e308b54e0a3cded9ef06f2963a3b6fb3c993b8
+config-catalog.zh.md: 42ea196d28ea8e628e31a235ef71760ece18f6ab
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 32644b4782..12e308b54e 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -229,6 +229,32 @@ export interface Config {
 
 Source: [`packages/api/settings-controller/src/index.ts:36`](../packages/api/settings-controller/src/index.ts)
 
+<a id="deepseek-aidsh-api-workspace-files"></a>
+
+## `@deepseek-ai/dsh-api-workspace-files`
+
+Requires: `fs` · `sandboxPolicy` · `typert`
+
+```ts config-catalog
+/** Deployment caps on one page or one listing. */
+export interface Config {
+  /**
+   * Inclusive byte cap on one page's text and on one byte window.
+   *
+   * A page above this fails; it is not shortened, because a silently cut page
+   * reads as the whole page. A byte window asking for more is refused the same
+   * way. The file itself has no size cap: a caller pages through it.
+   */
+  readonly maxBytes: number
+  /** Default and largest page size in lines; a request asking for more is refused. */
+  readonly maxLines: number
+  /** Cap on returned directory entries; the rest is dropped and reported cut. */
+  readonly maxEntries: number
+}
+```
+
+Source: [`packages/api/workspace-files/src/index.ts:57`](../packages/api/workspace-files/src/index.ts)
+
 <a id="deepseek-aidsh-attachment-local"></a>
 
 ## `@deepseek-ai/dsh-attachment-local`
@@ -744,7 +770,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/fs/fs-local/src/index.ts:41`](../packages/fs/fs-local/src/index.ts)
+Source: [`packages/fs/fs-local/src/index.ts:42`](../packages/fs/fs-local/src/index.ts)
 
 <a id="deepseek-aidsh-fs-sandbox"></a>
 
@@ -3398,6 +3424,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-client-file-upload` — requires `agents` · `attachments` · `commands` · `connection` ([`packages/client/file-upload/src/index.ts`](../packages/client/file-upload/src/index.ts))
 - `@deepseek-ai/dsh-client-locale` ([`packages/client/locale/src/index.ts`](../packages/client/locale/src/index.ts))
 - `@deepseek-ai/dsh-client-modules` — requires `loader` ([`packages/client/modules/src/index.ts`](../packages/client/modules/src/index.ts))
+- `@deepseek-ai/dsh-client-resources` ([`packages/client/resources/src/index.ts`](../packages/client/resources/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-agent-preset` ([`packages/client/ui-agent-preset/src/index.ts`](../packages/client/ui-agent-preset/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-approval` ([`packages/client/ui-approval/src/index.ts`](../packages/client/ui-approval/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-attachment` ([`packages/client/ui-attachment/src/index.ts`](../packages/client/ui-attachment/src/index.ts))
@@ -3428,6 +3455,9 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-client-ui-settings-plugin-inventory` ([`packages/client/ui-settings-plugin-inventory/src/index.ts`](../packages/client/ui-settings-plugin-inventory/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-settings-plugins` ([`packages/client/ui-settings-plugins/src/index.ts`](../packages/client/ui-settings-plugins/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-sidebar-files` ([`packages/client/ui-sidebar-files/src/index.ts`](../packages/client/ui-sidebar-files/src/index.ts))
+- `@deepseek-ai/dsh-client-ui-sidebar-right` ([`packages/client/ui-sidebar-right/src/index.ts`](../packages/client/ui-sidebar-right/src/index.ts))
+- `@deepseek-ai/dsh-client-ui-sidebar-textpreview` ([`packages/client/ui-sidebar-textpreview/src/index.ts`](../packages/client/ui-sidebar-textpreview/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-skill` ([`packages/client/ui-skill/src/index.ts`](../packages/client/ui-skill/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-subagent` ([`packages/client/ui-subagent/src/index.ts`](../packages/client/ui-subagent/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-theme` ([`packages/client/ui-theme/src/index.ts`](../packages/client/ui-theme/src/index.ts))
@@ -3503,6 +3533,7 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 - `@deepseek-ai/dsh-brand` ([`packages/util/brand/src/index.ts`](../packages/util/brand/src/index.ts))
 - `@deepseek-ai/dsh-client-store` ([`packages/client/store/src/index.ts`](../packages/client/store/src/index.ts))
 - `@deepseek-ai/dsh-client-test-runtime` ([`packages/test-support/client-runtime/src/index.ts`](../packages/test-support/client-runtime/src/index.ts))
+- `@deepseek-ai/dsh-client-ui-dockkit` ([`packages/client/ui-dockkit/src/index.ts`](../packages/client/ui-dockkit/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-primitives` ([`packages/client/ui-primitives/src/index.ts`](../packages/client/ui-primitives/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-slots` ([`packages/client/ui-slots/src/index.ts`](../packages/client/ui-slots/src/index.ts))
 - `@deepseek-ai/dsh-client-web` ([`packages/client/web/src/index.ts`](../packages/client/web/src/index.ts))
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 24dc4a3cb7..42ea196d28 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -231,6 +231,32 @@ export interface Config {
 
 来源：[`packages/api/settings-controller/src/index.ts:36`](../packages/api/settings-controller/src/index.ts)
 
+<a id="deepseek-aidsh-api-workspace-files"></a>
+
+## `@deepseek-ai/dsh-api-workspace-files`
+
+Requires: `fs` · `sandboxPolicy` · `typert`
+
+```ts config-catalog
+/** Deployment caps on one page or one listing. */
+export interface Config {
+  /**
+   * Inclusive byte cap on one page's text and on one byte window.
+   *
+   * A page above this fails; it is not shortened, because a silently cut page
+   * reads as the whole page. A byte window asking for more is refused the same
+   * way. The file itself has no size cap: a caller pages through it.
+   */
+  readonly maxBytes: number
+  /** Default and largest page size in lines; a request asking for more is refused. */
+  readonly maxLines: number
+  /** Cap on returned directory entries; the rest is dropped and reported cut. */
+  readonly maxEntries: number
+}
+```
+
+来源：[`packages/api/workspace-files/src/index.ts:57`](../packages/api/workspace-files/src/index.ts)
+
 <a id="deepseek-aidsh-attachment-local"></a>
 
 ## `@deepseek-ai/dsh-attachment-local`
@@ -3400,6 +3426,7 @@ export interface Config {
 - `@deepseek-ai/dsh-client-file-upload` — 需要 `agents` · `attachments` · `commands` · `connection`（[`packages/client/file-upload/src/index.ts`](../packages/client/file-upload/src/index.ts)）
 - `@deepseek-ai/dsh-client-locale`（[`packages/client/locale/src/index.ts`](../packages/client/locale/src/index.ts)）
 - `@deepseek-ai/dsh-client-modules` — 需要 `loader`（[`packages/client/modules/src/index.ts`](../packages/client/modules/src/index.ts)）
+- `@deepseek-ai/dsh-client-resources`（[`packages/client/resources/src/index.ts`](../packages/client/resources/src/index.ts)）
 - `@deepseek-ai/dsh-client-ui-agent-preset`（[`packages/client/ui-agent-preset/src/index.ts`](../packages/client/ui-agent-preset/src/index.ts)）
 - `@deepseek-ai/dsh-client-ui-approval`（[`packages/client/ui-approval/src/index.ts`](../packages/client/ui-approval/src/index.ts)）
 - `@deepseek-ai/dsh-client-ui-attachment`（[`packages/client/ui-attachment/src/index.ts`](../packages/client/ui-attachment/src/index.ts)）
@@ -3430,6 +3457,9 @@ export interface Config {
 - `@deepseek-ai/dsh-client-ui-settings-plugin-inventory`（[`packages/client/ui-settings-plugin-inventory/src/index.ts`](../packages/client/ui-settings-plugin-inventory/src/index.ts)）
 - `@deepseek-ai/dsh-client-ui-settings-plugins`（[`packages/client/ui-settings-plugins/src/index.ts`](../packages/client/ui-settings-plugins/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-sidebar-files`（[`packages/client/ui-sidebar-files/src/index.ts`](../packages/client/ui-sidebar-files/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-sidebar-right`（[`packages/client/ui-sidebar-right/src/index.ts`](../packages/client/ui-sidebar-right/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-sidebar-textpreview`（[`packages/client/ui-sidebar-textpreview/src/index.ts`](../packages/client/ui-sidebar-textpreview/src/index.ts)）
 - `@deepseek-ai/dsh-client-ui-skill`（[`packages/client/ui-skill/src/index.ts`](../packages/client/ui-skill/src/index.ts)）
 - `@deepseek-ai/dsh-client-ui-subagent`（[`packages/client/ui-subagent/src/index.ts`](../packages/client/ui-subagent/src/index.ts)）
 - `@deepseek-ai/dsh-client-ui-theme`（[`packages/client/ui-theme/src/index.ts`](../packages/client/ui-theme/src/index.ts)）
@@ -3504,6 +3534,7 @@ export interface Config {
 - `@deepseek-ai/dsh-brand`（[`packages/util/brand/src/index.ts`](../packages/util/brand/src/index.ts)）
 - `@deepseek-ai/dsh-client-store`（[`packages/client/store/src/index.ts`](../packages/client/store/src/index.ts)）
 - `@deepseek-ai/dsh-client-test-runtime`（[`packages/test-support/client-runtime/src/index.ts`](../packages/test-support/client-runtime/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-dockkit`（[`packages/client/ui-dockkit/src/index.ts`](../packages/client/ui-dockkit/src/index.ts)）
 - `@deepseek-ai/dsh-client-ui-primitives`（[`packages/client/ui-primitives/src/index.ts`](../packages/client/ui-primitives/src/index.ts)）
 - `@deepseek-ai/dsh-client-ui-slots`（[`packages/client/ui-slots/src/index.ts`](../packages/client/ui-slots/src/index.ts)）
 - `@deepseek-ai/dsh-client-web`（[`packages/client/web/src/index.ts`](../packages/client/web/src/index.ts)）
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 71b047fa7a..8959b05a1d 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
-development.md: 37028720ff2487a81caecb8b2e2c6e5bc26b2df5
-development.zh.md: 01e3e88605cb4f9ea0b14df4a0099f436c48c5e9
+development.md: ce8f1e7746562e696c96e6359ec9fcfde596d6e2
+development.zh.md: 85e95946dfd7210201f0807880d5ed1a92859356
diff --git a/docs/development.md b/docs/development.md
index 37028720ff..ce8f1e7746 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -13,6 +13,14 @@ The setup tutorial takes a new contributor from prerequisites to a checked check
 - Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.
 - Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.
 
+### Windows and WSL 2
+
+On Windows, you can develop with native tools or use WSL 2 for a Linux environment. WSL 2 is useful for verifying Linux behavior and for using Linux toolchains when native dependency compilation or filesystem permissions obstruct Windows development. Each environment needs its own runtime, build tools, and permissions; WSL is optional.
+
+Keep the checkout, installed dependencies, and toolchain in the same operating system environment. For WSL 2, store the checkout in the Linux filesystem; for native Windows tools, use the Windows filesystem. Accessing files across the two filesystems adds overhead to I/O-intensive operations such as Git, dependency installation, and builds. See Microsoft's [file storage and performance guidance](https://learn.microsoft.com/en-us/windows/wsl/filesystems#file-storage-and-performance-across-file-systems).
+
+Install dependencies separately in each environment because native binaries and links can differ between operating systems. Test results apply to the environment where the tests ran; Windows-specific behavior still needs native Windows validation.
+
 ### First-time setup
 
 Install dependencies from the repo root:
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 01e3e88605..85e95946df 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -15,6 +15,14 @@
 - Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。
 - 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。
 
+### Windows 与 WSL 2
+
+在 Windows 上，可以使用原生工具开发，也可以通过 WSL 2 使用 Linux 环境。WSL 2 既可用于验证 Linux 行为，也可在原生依赖编译或文件系统权限阻碍 Windows 开发时提供使用 Linux 工具链的途径。每种环境都需要准备相应的运行时、编译工具和权限；WSL 是可选项。
+
+将检出目录、已安装的依赖和工具链放在同一操作系统环境中。使用 WSL 2 时，将检出目录放在 Linux 文件系统中；使用 Windows 原生工具时，则使用 Windows 文件系统。跨两种文件系统访问会给 Git、依赖安装和构建等 I/O 密集型操作增加开销。参见微软的[文件存储与性能指南](https://learn.microsoft.com/en-us/windows/wsl/filesystems#file-storage-and-performance-across-file-systems)。
+
+在每种环境中分别安装依赖，因为不同操作系统使用的原生二进制和链接可能不同。测试结果适用于执行测试的环境；Windows 特有行为仍需在原生 Windows 上验证。
+
 ### 首次搭建
 
 在仓库根目录安装依赖：
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index df5d25aa81..dcb4c44e45 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/event-producer-consumer.md
-event-producer-consumer.md: edf5ea33526afb46e941314852dea653105fb748
-event-producer-consumer.zh.md: f7d96a94eef611817e9a9c0c2dcc93d62ea3a178
+event-producer-consumer.md: 99811d1dac8b51e96544eea95b1d67379cc15f14
+event-producer-consumer.zh.md: 68ea7460eeb2192b6d8d5195fec1254c457e7c16
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index edf5ea3352..99811d1dac 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -22,11 +22,11 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:316`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `agent-team`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:277`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` |
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:387`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:586`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:566`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:593`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:572`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:579`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:591`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:571`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:598`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:577`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:584`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` |
 | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
 | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:87`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` |
@@ -41,8 +41,9 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace), `workspace-controller` |
 | `feedback/committed` | `parallel` | [`packages/feedback/message-feedback/src/index.ts:57`](../packages/feedback/message-feedback/src/index.ts) | [`message-feedback`](../packages/feedback/message-feedback) (`parallel`) | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) |
-| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:76`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem) |
+| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:76`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem), `workspace-files` |
 | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:58`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) |
+| `goal/activation-changed` | `emit` | [`packages/goal/goal/src/types.ts:150`](../packages/goal/goal/src/types.ts) | [`goal`](../packages/goal/goal) (`emit`) | `remotes` |
 | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-round-driver`](../packages/goal/goal-round-driver) |
 | `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/types.ts:23`](../packages/llm/llm/src/types.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`llm`](../packages/llm/llm), `remotes` |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:71`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/test-support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index f7d96a94ee..68ea7460ee 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -24,11 +24,11 @@
 | `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:316`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `agent-team`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:277`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` |
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:387`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:586`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:566`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:593`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:572`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:579`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:591`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:571`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:598`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:577`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:584`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` |
 | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
 | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:87`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` |
@@ -43,8 +43,9 @@
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace), `workspace-controller` |
 | `feedback/committed` | `parallel` | [`packages/feedback/message-feedback/src/index.ts:57`](../packages/feedback/message-feedback/src/index.ts) | [`message-feedback`](../packages/feedback/message-feedback) (`parallel`) | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) |
-| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:76`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem) |
+| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:76`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem), `workspace-files` |
 | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:58`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) |
+| `goal/activation-changed` | `emit` | [`packages/goal/goal/src/types.ts:150`](../packages/goal/goal/src/types.ts) | [`goal`](../packages/goal/goal) (`emit`) | `remotes` |
 | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-round-driver`](../packages/goal/goal-round-driver) |
 | `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/types.ts:23`](../packages/llm/llm/src/types.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`llm`](../packages/llm/llm), `remotes` |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:71`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/test-support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml
index c59e8ddf45..7789f3c308 100644
--- a/docs/module-graph.i18n.yaml
+++ b/docs/module-graph.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/module-graph.md
-module-graph.md: 2c31c50117cc6caabccdcb8fdf6afc9a160fe4dd
-module-graph.zh.md: d41df4241163ca9b17e47c62051a891e45e131e0
+module-graph.md: ecb72f02bc7a27a75318e8abf56c20f9915831ea
+module-graph.zh.md: 5c94c866d10e81948dd69089210cd4b08ded7531
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 2c31c50117..ecb72f02bc 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -114,6 +114,7 @@ flowchart TD
     pkg_api_session_controller["api-session-controller"]
     pkg_api_settings_controller["api-settings-controller"]
     pkg_api_workspace_controller["api-workspace-controller"]
+    pkg_api_workspace_files["api-workspace-files"]
   end
   subgraph group_attachment["packages/attachment"]
     pkg_attachment["attachment"]
@@ -137,6 +138,7 @@ flowchart TD
     pkg_client_hmr["client-hmr"]
     pkg_client_locale["client-locale"]
     pkg_client_modules["client-modules"]
+    pkg_client_resources["client-resources"]
     pkg_client_store["client-store"]
     pkg_client_ui_agent_preset["client-ui-agent-preset"]
     pkg_client_ui_approval["client-ui-approval"]
@@ -148,6 +150,7 @@ flowchart TD
     pkg_client_ui_deliverables["client-ui-deliverables"]
     pkg_client_ui_directory_picker_browse["client-ui-directory-picker-browse"]
     pkg_client_ui_directory_picker_native["client-ui-directory-picker-native"]
+    pkg_client_ui_dockkit["client-ui-dockkit"]
     pkg_client_ui_goal["client-ui-goal"]
     pkg_client_ui_input_trigger["client-ui-input-trigger"]
     pkg_client_ui_jobs["client-ui-jobs"]
@@ -168,6 +171,9 @@ flowchart TD
     pkg_client_ui_settings_plugin_inventory["client-ui-settings-plugin-inventory"]
     pkg_client_ui_settings_plugins["client-ui-settings-plugins"]
     pkg_client_ui_sidebar["client-ui-sidebar"]
+    pkg_client_ui_sidebar_files["client-ui-sidebar-files"]
+    pkg_client_ui_sidebar_right["client-ui-sidebar-right"]
+    pkg_client_ui_sidebar_textpreview["client-ui-sidebar-textpreview"]
     pkg_client_ui_skill["client-ui-skill"]
     pkg_client_ui_slots["client-ui-slots"]
     pkg_client_ui_subagent["client-ui-subagent"]
@@ -1179,6 +1185,7 @@ flowchart TD
 | [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions) | `llm` | — |
 | [`llm`](../packages/llm/llm) | `llm` | — |
 | [`api-gateway`](../packages/api/gateway) | `api` | — |
+| [`api-workspace-files`](../packages/api/workspace-files) | `api` | — |
 | [`cmdline`](../packages/boot/cmdline) | `boot` | — |
 | [`acp-app`](../packages/bundle/acp-app) | `bundle` | — |
 | [`base`](../packages/bundle/base) | `bundle` | — |
@@ -1188,6 +1195,7 @@ flowchart TD
 | [`client-hmr`](../packages/client/hmr) | `client` | — |
 | [`client-locale`](../packages/client/locale) | `client` | — |
 | [`client-modules`](../packages/client/modules) | `client` | — |
+| [`client-resources`](../packages/client/resources) | `client` | — |
 | [`client-store`](../packages/client/store) | `client` | — |
 | [`client-ui-agent-preset`](../packages/client/ui-agent-preset) | `client` | — |
 | [`client-ui-approval`](../packages/client/ui-approval) | `client` | — |
@@ -1199,6 +1207,7 @@ flowchart TD
 | [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | — |
 | [`client-ui-directory-picker-browse`](../packages/client/ui-directory-picker-browse) | `client` | — |
 | [`client-ui-directory-picker-native`](../packages/client/ui-directory-picker-native) | `client` | — |
+| [`client-ui-dockkit`](../packages/client/ui-dockkit) | `client` | — |
 | [`client-ui-goal`](../packages/client/ui-goal) | `client` | — |
 | [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | — |
 | [`client-ui-jobs`](../packages/client/ui-jobs) | `client` | — |
@@ -1219,6 +1228,9 @@ flowchart TD
 | [`client-ui-settings-plugin-inventory`](../packages/client/ui-settings-plugin-inventory) | `client` | — |
 | [`client-ui-settings-plugins`](../packages/client/ui-settings-plugins) | `client` | — |
 | [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | — |
+| [`client-ui-sidebar-files`](../packages/client/ui-sidebar-files) | `client` | — |
+| [`client-ui-sidebar-right`](../packages/client/ui-sidebar-right) | `client` | — |
+| [`client-ui-sidebar-textpreview`](../packages/client/ui-sidebar-textpreview) | `client` | — |
 | [`client-ui-skill`](../packages/client/ui-skill) | `client` | — |
 | [`client-ui-slots`](../packages/client/ui-slots) | `client` | — |
 | [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | — |
diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md
index d41df42411..5c94c866d1 100644
--- a/docs/module-graph.zh.md
+++ b/docs/module-graph.zh.md
@@ -116,6 +116,7 @@ flowchart TD
     pkg_api_session_controller["api-session-controller"]
     pkg_api_settings_controller["api-settings-controller"]
     pkg_api_workspace_controller["api-workspace-controller"]
+    pkg_api_workspace_files["api-workspace-files"]
   end
   subgraph group_attachment["packages/attachment"]
     pkg_attachment["attachment"]
@@ -139,6 +140,7 @@ flowchart TD
     pkg_client_hmr["client-hmr"]
     pkg_client_locale["client-locale"]
     pkg_client_modules["client-modules"]
+    pkg_client_resources["client-resources"]
     pkg_client_store["client-store"]
     pkg_client_ui_agent_preset["client-ui-agent-preset"]
     pkg_client_ui_approval["client-ui-approval"]
@@ -150,6 +152,7 @@ flowchart TD
     pkg_client_ui_deliverables["client-ui-deliverables"]
     pkg_client_ui_directory_picker_browse["client-ui-directory-picker-browse"]
     pkg_client_ui_directory_picker_native["client-ui-directory-picker-native"]
+    pkg_client_ui_dockkit["client-ui-dockkit"]
     pkg_client_ui_goal["client-ui-goal"]
     pkg_client_ui_input_trigger["client-ui-input-trigger"]
     pkg_client_ui_jobs["client-ui-jobs"]
@@ -170,6 +173,9 @@ flowchart TD
     pkg_client_ui_settings_plugin_inventory["client-ui-settings-plugin-inventory"]
     pkg_client_ui_settings_plugins["client-ui-settings-plugins"]
     pkg_client_ui_sidebar["client-ui-sidebar"]
+    pkg_client_ui_sidebar_files["client-ui-sidebar-files"]
+    pkg_client_ui_sidebar_right["client-ui-sidebar-right"]
+    pkg_client_ui_sidebar_textpreview["client-ui-sidebar-textpreview"]
     pkg_client_ui_skill["client-ui-skill"]
     pkg_client_ui_slots["client-ui-slots"]
     pkg_client_ui_subagent["client-ui-subagent"]
@@ -1181,6 +1187,7 @@ flowchart TD
 | [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions) | `llm` | — |
 | [`llm`](../packages/llm/llm) | `llm` | — |
 | [`api-gateway`](../packages/api/gateway) | `api` | — |
+| [`api-workspace-files`](../packages/api/workspace-files) | `api` | — |
 | [`cmdline`](../packages/boot/cmdline) | `boot` | — |
 | [`acp-app`](../packages/bundle/acp-app) | `bundle` | — |
 | [`base`](../packages/bundle/base) | `bundle` | — |
@@ -1190,6 +1197,7 @@ flowchart TD
 | [`client-hmr`](../packages/client/hmr) | `client` | — |
 | [`client-locale`](../packages/client/locale) | `client` | — |
 | [`client-modules`](../packages/client/modules) | `client` | — |
+| [`client-resources`](../packages/client/resources) | `client` | — |
 | [`client-store`](../packages/client/store) | `client` | — |
 | [`client-ui-agent-preset`](../packages/client/ui-agent-preset) | `client` | — |
 | [`client-ui-approval`](../packages/client/ui-approval) | `client` | — |
@@ -1201,6 +1209,7 @@ flowchart TD
 | [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | — |
 | [`client-ui-directory-picker-browse`](../packages/client/ui-directory-picker-browse) | `client` | — |
 | [`client-ui-directory-picker-native`](../packages/client/ui-directory-picker-native) | `client` | — |
+| [`client-ui-dockkit`](../packages/client/ui-dockkit) | `client` | — |
 | [`client-ui-goal`](../packages/client/ui-goal) | `client` | — |
 | [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | — |
 | [`client-ui-jobs`](../packages/client/ui-jobs) | `client` | — |
@@ -1221,6 +1230,9 @@ flowchart TD
 | [`client-ui-settings-plugin-inventory`](../packages/client/ui-settings-plugin-inventory) | `client` | — |
 | [`client-ui-settings-plugins`](../packages/client/ui-settings-plugins) | `client` | — |
 | [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | — |
+| [`client-ui-sidebar-files`](../packages/client/ui-sidebar-files) | `client` | — |
+| [`client-ui-sidebar-right`](../packages/client/ui-sidebar-right) | `client` | — |
+| [`client-ui-sidebar-textpreview`](../packages/client/ui-sidebar-textpreview) | `client` | — |
 | [`client-ui-skill`](../packages/client/ui-skill) | `client` | — |
 | [`client-ui-slots`](../packages/client/ui-slots) | `client` | — |
 | [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | — |
diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml
index 9176b4e312..a39cbcf162 100644
--- a/docs/subsystems/README.i18n.yaml
+++ b/docs/subsystems/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/README.md
-README.md: 7ead36412136b00eb284897bb1114ead7d4d96d4
-README.zh.md: bc7500c00d5bb68cb7d4bf607e3d3a58bd2c55cc
+README.md: 9afbdda338ed797279b719eaf577be45a84349e2
+README.zh.md: ee3c89830a76bc1cddb83e0a50507f3e4439800d
diff --git a/docs/subsystems/README.md b/docs/subsystems/README.md
index 7ead364121..9afbdda338 100644
--- a/docs/subsystems/README.md
+++ b/docs/subsystems/README.md
@@ -54,6 +54,8 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures
 | [web-client.md](web-client.md) | the browser architecture: boot, Remote communication, paired Client models, UI adapters, Conversation assembly, Slots, and reconnect semantics |
 | [client-modules.md](client-modules.md) | the web plugin table: `dsh.client` declarations, `WebBootGraph` wire composition, the bundle route and index tap |
 | [slots.md](slots.md) | typed Web UI composition: declaration ownership, cardinality and scope, framework and feature injection, props derivation, and the shipped hierarchy |
+| [client-resources.md](client-resources.md) | the client resource model: `dsh-resource://<type>/…` addresses, protocol providers and `ResourceProtocolMap`, the `useResource` global hook and its states, pins and release |
+| [sidebar-right.md](sidebar-right.md) | the right Sidebar: resource and navigation addresses, tab-type registration and routing, the `ctx.sidebarRight` navigation service, the pane-tab slots and owner props, the resource model, and the Workspace Files service |
 | [conversation.md](conversation.md) | target-neutral Session-event assembly: Context identity, Location data, replay paths, view builders, and target-owned render nodes |
 | [session-projection.md](session-projection.md) | the projection seam: `SessionProjectionMap`, the pure `ProjectionDefinition` unit, `ProjectionSnapshot`'s consistent cut, the change feed |
 | [session-telemetry.md](session-telemetry.md) | the outbound session-reporting capability seam: `SessionTelemetryRecord`/`SessionTelemetrySeverity`, the `SessionTelemetrySink` contract, and the `session-telemetry/record` redact waterfall |
diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md
index bc7500c00d..ee3c89830a 100644
--- a/docs/subsystems/README.zh.md
+++ b/docs/subsystems/README.zh.md
@@ -54,6 +54,8 @@
 | [web-client.md](web-client.zh.md) | 浏览器架构：启动、Remote 通信、配对的 Client model、UI adapter、Conversation 组装、Slots 与重连语义 |
 | [client-modules.md](client-modules.zh.md) | Web 插件表：`dsh.client` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
 | [slots.md](slots.zh.md) | 类型化 Web UI 组合：声明所有权、cardinality 与 scope、框架与功能注入、props 推导及当前层级 |
+| [client-resources.md](client-resources.zh.md) | 客户端资源模型：`dsh-resource://<type>/…` 地址、协议提供方与 `ResourceProtocolMap`、`useResource` 全局 hook 及其状态、钉住与释放 |
+| [sidebar-right.md](sidebar-right.zh.md) | 右侧 Sidebar：资源地址与导航地址、tab 类型注册与路由、`ctx.sidebarRight` 导航服务、pane-tab slot 与 owner props、资源模型及 Workspace Files 服务 |
 | [conversation.md](conversation.zh.md) | target-neutral Session event 组装：Context identity、Location data、replay 路径、view builder 与 target 自有 render node |
 | [session-projection.md](session-projection.zh.md) | 投影 seam：`SessionProjectionMap`、纯函数 `ProjectionDefinition` 单元、`ProjectionSnapshot` 的一致切面、变更馈送 |
 | [session-telemetry.md](session-telemetry.zh.md) | 对外会话上报能力 seam：`SessionTelemetryRecord`/`SessionTelemetrySeverity`、`SessionTelemetrySink` 约定和 `session-telemetry/record` 脱敏 waterfall |
diff --git a/docs/subsystems/client-resources.i18n.yaml b/docs/subsystems/client-resources.i18n.yaml
new file mode 100644
index 0000000000..e1267b8d56
--- /dev/null
+++ b/docs/subsystems/client-resources.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/subsystems/client-resources.md
+client-resources.md: a1643e61779e5c19450c7e1688b0ce7fcfbee786
+client-resources.zh.md: 418c9aef91a58a85ff8102617074a38813c5f94b
diff --git a/docs/subsystems/client-resources.md b/docs/subsystems/client-resources.md
new file mode 100644
index 0000000000..a1643e6177
--- /dev/null
+++ b/docs/subsystems/client-resources.md
@@ -0,0 +1,94 @@
+# Client Resources
+
+English | [中文](client-resources.zh.md)
+
+The client resource model turns an address into live data for any Web Client component. [`dsh-client-resources`](../../packages/client/resources/README.md) provides the `ctx.resources` service and the `useResource` global standard hook; a package that owns a kind of content registers one **provider** for its **protocol**, and a component reads the content's current state by **address** without importing the owner's runtime. The right Sidebar's tabs are the model's first consumer ([Right Sidebar](sidebar-right.md)); the decision record is the [client resource model Agent Note](../../.agents/notes/implemented/architecture/2026-09-05-client-resource-model.md).
+
+This page is the developer reference: how to write an address, how to register a provider, how to read a resource, what the states and failures mean, and how the model holds and releases a resource.
+
+## Addresses
+
+A resource address is a `dsh-resource://<type>/…` URL. The host names the protocol and must be a key of `ResourceProtocolMap`; the path is the protocol's own, and its owner percent-encodes each segment. A protocol that needs a scope puts it in the path: the `file` protocol's addresses read `dsh-resource://file/session/<sessionId>/<path relative to that session's workspace root>` or `dsh-resource://file/absolute/<absolute path without its leading />`, built with `fileAddressFor(sessionId, cwd, path)` and read back with `parseFileAddress(address)` from [`dsh-util-workspace-path`](../../packages/util/workspace-path/README.md). The model itself reads only the scheme and the host: `protocolOf(address)` returns the lower-cased host of a `dsh-resource://` URL and `undefined` for anything else. Addresses under any other scheme — the Sidebar's `sidebar://guide` — name no resource and read as `none`.
+
+| Address | Protocol key | Reads as |
+|---|---|---|
+| `dsh-resource://file/session/s1/notes/a.md` | `file` | the metadata of `notes/a.md` under session `s1`'s workspace root, when the `file` provider is registered |
+| `dsh-resource://file/absolute/home/me/notes.md` | `file` | the metadata of that absolute path, read through the current session and confined to its workspace |
+| `DSH-RESOURCE://File/session/s1/a` | `file` | a distinct record: addresses compare as strings, and `openResource` accepts only the canonical lower-case spelling that `fileAddressFor` emits |
+| `sidebar://guide` | — | `none`: a navigation address |
+| `/home/me/notes.md` | — | `none`: not a URL |
+
+## Registering a provider
+
+The owner of a protocol declares its value type on `ResourceProtocolMap` and registers one provider inside its own `ctx.effect`, so the protocol lives exactly as long as the plugin ([provide a protocol](../../packages/client/resources/README.md#provide-a-protocol)). `open(address, { signal })` returns a stream of `RemoteResult` frames — the current state first, then one frame per change — and must stop when `signal` aborts. A failure is an `ok: false` frame carrying a `RemoteFailure`; a throw inside the stream is a programming error and is not caught. `reload(address)` is optional and asks the open stream for a fresh frame.
+
+```ts ignore-check
+import type { Context } from '@deepseek-ai/cordis'
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
+import type {} from '@deepseek-ai/dsh-client-resources/client'
+
+interface NoteView { readonly title: string; readonly updatedAt: string }
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface ResourceProtocolMap { note: NoteView }
+}
+
+export const inject = ['resources', 'remote']
+
+export function apply(ctx: Context): void {
+  ctx.effect(() => ctx.resources.register<'note'>({
+    protocol: 'note',
+    async *open(address, { signal }): AsyncIterable<RemoteResult<NoteView>> {
+      const id = new URL(address).pathname.slice(1)
+      yield await ctx.remote.notes.read(id, signal)
+      for await (const change of ctx.remote.notes.follow(id, signal)) yield change
+    },
+    reload(address) { ctx.remote.notes.requestReread(new URL(address).pathname.slice(1)) },
+  }), 'my-notes: note resource provider')
+}
+```
+
+A protocol has exactly one provider; a second registration throws. Registering while addresses of the protocol are already held opens their streams at once; disposing the provider ends those streams and the addresses read `none` until a provider returns.
+
+## Reading a resource
+
+Every slot component receives `useResource` in its props, whatever its scope ([Slots](slots.md)). `useResource<P>(address)` names the protocol as the type argument and returns the address's current snapshot; subscribing is what holds the resource open, and a component that mounts while another holder keeps the resource alive reads the latest value at once without reopening the stream ([read a resource](../../packages/client/resources/README.md#read-a-resource)).
+
+| `status` | Meaning | `value` | `failure` |
+|---|---|---|---|
+| `none` | No provider is registered for the address's protocol, or the address is not a resource address | `undefined` | `undefined` |
+| `loading` | The provider's stream is open and has not yielded yet | `undefined` | `undefined` |
+| `live` | The latest frame succeeded | the latest `ok` value | `undefined` |
+| `failed` | The latest frame reported a failure | the last `ok` value, kept | the frame's `RemoteFailure` |
+
+`reload()` asks the provider for a fresh frame and is a no-op when the protocol has no provider or the provider has no `reload`; the function is reference-stable per address, so a body may hold it.
+
+```tsx ignore-check
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type {} from '@deepseek-ai/dsh-api-workspace-files/client'
+
+type Props = PropsRuntime<'sidebar.right.pane.tab'>
+
+export function FileHeader({ tab, useResource, t }: Props) {
+  const meta = useResource<'file'>(tab.contentId)
+  if (meta.status === 'failed') return <p role="alert">{t('failed', { code: meta.failure.code })}</p>
+  return (
+    <header>
+      {tab.title}
+      {meta.value?.changed && <button type="button" onClick={meta.reload}>{t('reload')}</button>}
+    </header>
+  )
+}
+```
+
+A consumer presents `failed` itself: the model keeps the last value beside the failure so a body can show stale content with a notice rather than a blank, and the next `ok` frame clears the failure. Nothing in the model produces user-visible text.
+
+## Holding and releasing
+
+A resource is alive while it has a holder: a subscribed `useResource`, or a pin. `ctx.resources.pin(address, signal)` keeps a resource open without subscribing until `signal` aborts, and an already-aborted signal pins nothing; the right Sidebar pins every open tab record's address for the record's life, so switching tabs unmounts a body without closing its stream. The first holder opens the provider's stream; the last release aborts it, discards the value, and returns the snapshot to `loading` (provider present) or `none` (absent). A frame the provider yields after that release is dropped, and the iterator is returned. `ctx.resources.source(address)` is the bare observable behind the hook, reference-stable per address, for callers outside React; reading its snapshot does not hold the resource ([lifecycle](../../packages/client/resources/README.md#lifecycle)).
+
+Streams carry metadata, not content. The `file` provider's value is `{ absolutePath, version, bytes?, changed }`: `absolutePath`, `version`, and `bytes` from the Host's `stat`, `changed` raised when the Host reports an agent write and cleared by `reload`. A consumer reads the file's text itself, by page, through the Workspace Files Remote namespace ([`dsh-api-workspace-files`](../../packages/api/workspace-files/README.md)).
+
+## Limits
+
+Records live for the page lifetime: an address's record stays after its last holder leaves, holding no stream and no value, so memory grows with the number of distinct addresses ever read. A provider that ignores `signal` keeps running until its next frame. The failure type is the Remote face's `RemoteFailure`, so a provider whose source is not a Remote call mints one. A misspelled protocol or a malformed address reads as `none` with no other diagnostic.
diff --git a/docs/subsystems/client-resources.zh.md b/docs/subsystems/client-resources.zh.md
new file mode 100644
index 0000000000..418c9aef91
--- /dev/null
+++ b/docs/subsystems/client-resources.zh.md
@@ -0,0 +1,94 @@
+# 客户端资源
+
+[English](client-resources.md) | 中文
+
+客户端资源模型把一个地址变成任何 Web Client 组件都能读的活数据。[`dsh-client-resources`](../../packages/client/resources/README.zh.md) 提供 `ctx.resources` 服务与 `useResource` 全局标准 hook；拥有某类内容的包为它的**协议**注册一个**提供方**，组件按**地址**读取该内容的当前状态，而无需引用拥有者的运行时。右侧 Sidebar 的 tab 是这个模型的第一个消费方（[右侧 Sidebar](sidebar-right.zh.md)）；决策记录见 [客户端资源模型 Agent Note](../../.agents/notes/implemented/architecture/2026-09-05-client-resource-model.zh.md)。
+
+本页是面向开发者的参考：地址怎么写、提供方怎么注册、资源怎么读、状态与失败各是什么意思、模型怎样持有与释放一份资源。
+
+## 地址
+
+资源地址是 `dsh-resource://<type>/…` 形式的 URL。host 命名协议，必须是 `ResourceProtocolMap` 的键；路径归协议自己，由其拥有者逐段做百分号编码。需要作用域的协议把作用域放进路径：`file` 协议的地址形如 `dsh-resource://file/session/<sessionId>/<相对该会话工作区根的路径>` 或 `dsh-resource://file/absolute/<去掉前导 / 的绝对路径>`，用 [`dsh-util-workspace-path`](../../packages/util/workspace-path/README.zh.md) 的 `fileAddressFor(sessionId, cwd, path)` 构造、`parseFileAddress(address)` 读回。模型本身只读 scheme 与 host：`protocolOf(address)` 对 `dsh-resource://` URL 返回小写 host，对其它任何字串返回 `undefined`。其它 scheme 下的地址——Sidebar 的 `sidebar://guide`——不指向资源，读作 `none`。
+
+| 地址 | 协议键 | 读作 |
+|---|---|---|
+| `dsh-resource://file/session/s1/notes/a.md` | `file` | 会话 `s1` 工作区根下 `notes/a.md` 的元数据（`file` 提供方已注册时） |
+| `dsh-resource://file/absolute/home/me/notes.md` | `file` | 该绝对路径的元数据，经当前会话读取、受其工作区限制 |
+| `DSH-RESOURCE://File/session/s1/a` | `file` | 另一份记录：地址按字符串比较，`openResource` 只接受 `fileAddressFor` 生成的规范小写拼写 |
+| `sidebar://guide` | — | `none`：导航地址 |
+| `/home/me/notes.md` | — | `none`：不是 URL |
+
+## 注册提供方
+
+协议拥有者在 `ResourceProtocolMap` 上声明其值类型，并在自己的 `ctx.effect` 里注册一个提供方，使协议与插件同寿（[提供协议](../../packages/client/resources/README.zh.md#provide-a-protocol)）。`open(address, { signal })` 返回一条 `RemoteResult` 帧流——首帧是当前状态，之后每次变化一帧——并且必须在 `signal` 中止时停下。失败是携带 `RemoteFailure` 的 `ok: false` 帧；流里抛出是编程错误，不会被捕获。`reload(address)` 可选，请已打开的流给一个新帧。
+
+```ts ignore-check
+import type { Context } from '@deepseek-ai/cordis'
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
+import type {} from '@deepseek-ai/dsh-client-resources/client'
+
+interface NoteView { readonly title: string; readonly updatedAt: string }
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface ResourceProtocolMap { note: NoteView }
+}
+
+export const inject = ['resources', 'remote']
+
+export function apply(ctx: Context): void {
+  ctx.effect(() => ctx.resources.register<'note'>({
+    protocol: 'note',
+    async *open(address, { signal }): AsyncIterable<RemoteResult<NoteView>> {
+      const id = new URL(address).pathname.slice(1)
+      yield await ctx.remote.notes.read(id, signal)
+      for await (const change of ctx.remote.notes.follow(id, signal)) yield change
+    },
+    reload(address) { ctx.remote.notes.requestReread(new URL(address).pathname.slice(1)) },
+  }), 'my-notes: note resource provider')
+}
+```
+
+一个协议恰有一个提供方；第二次注册抛错。注册时若该协议的地址已被持有，则立刻打开它们的流；提供方 dispose 时结束这些流，地址读作 `none` 直到提供方回来。
+
+## 读取资源
+
+每个 slot 组件不论作用域都在 props 上收到 `useResource`（[Slots](slots.zh.md)）。`useResource<P>(address)` 以类型参数命名协议，返回该地址的当前快照；订阅就是持有资源的方式，另一个持有者让资源存活时，新挂载的组件立刻读到最新值而不重开流（[读取资源](../../packages/client/resources/README.zh.md#read-a-resource)）。
+
+| `status` | 含义 | `value` | `failure` |
+|---|---|---|---|
+| `none` | 地址的协议没有注册提供方，或地址不是资源地址 | `undefined` | `undefined` |
+| `loading` | 提供方的流已打开、尚未产出 | `undefined` | `undefined` |
+| `live` | 最新一帧成功 | 最新的 `ok` 值 | `undefined` |
+| `failed` | 最新一帧报告了失败 | 保留的上一个 `ok` 值 | 该帧的 `RemoteFailure` |
+
+`reload()` 请提供方给一个新帧，协议没有提供方或提供方没有 `reload` 时是空操作；该函数按地址引用稳定，正文可以长期持有。
+
+```tsx ignore-check
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type {} from '@deepseek-ai/dsh-api-workspace-files/client'
+
+type Props = PropsRuntime<'sidebar.right.pane.tab'>
+
+export function FileHeader({ tab, useResource, t }: Props) {
+  const meta = useResource<'file'>(tab.contentId)
+  if (meta.status === 'failed') return <p role="alert">{t('failed', { code: meta.failure.code })}</p>
+  return (
+    <header>
+      {tab.title}
+      {meta.value?.changed && <button type="button" onClick={meta.reload}>{t('reload')}</button>}
+    </header>
+  )
+}
+```
+
+`failed` 由消费方自己呈现：模型把最后一个值留在失败旁，正文可以带提示显示旧内容而不是一片空白，下一个 `ok` 帧会清除失败。模型本身不产生任何用户可见文案。
+
+## 持有与释放
+
+资源有持有者就存活：一个订阅中的 `useResource`，或一次钉住。`ctx.resources.pin(address, signal)` 在不订阅的情况下让资源保持打开直到 `signal` 中止，已中止的信号什么也不钉；右侧 Sidebar 在每条打开的 tab 记录存续期内钉住其地址，因此切 tab 卸载正文不关流。第一个持有者打开提供方的流；最后一个释放时中止它、丢弃值，并把快照回到 `loading`（有提供方）或 `none`（没有）。提供方在这次释放之后产出的帧被丢弃，迭代器被归还。`ctx.resources.source(address)` 是 hook 背后的裸 observable，按地址引用稳定，供 React 之外的调用方使用；只读它的快照不算持有（[生命周期](../../packages/client/resources/README.zh.md#lifecycle)）。
+
+流只推元数据不推内容。`file` 提供方的值是 `{ absolutePath, version, bytes?, changed }`：`absolutePath`、`version` 与 `bytes` 来自 Host 的 `stat`，`changed` 在 Host 报告 agent 写入时置起、由 `reload` 清除。消费方自己经 Workspace Files Remote 命名空间按页读文件文本（[`dsh-api-workspace-files`](../../packages/api/workspace-files/README.zh.md)）。
+
+## 限制
+
+记录在页面存续期内保留：地址的记录在最后一个持有者离开后仍留着，不持有流也不持有值，因此内存随读过的不同地址数增长。忽略 `signal` 的提供方会一直跑到它的下一帧。失败类型是 Remote 面的 `RemoteFailure`，来源不是 Remote 调用的提供方得自己铸一个。拼错的协议或畸形的地址读作 `none`，没有别的诊断。
diff --git a/docs/subsystems/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
index 7b592e60fa..e73eb155fd 100644
--- a/docs/subsystems/filesystem.i18n.yaml
+++ b/docs/subsystems/filesystem.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/filesystem.md
-filesystem.md: 06fb92f453f8a09f87aee817ab56ef147be9a91f
-filesystem.zh.md: ea5b6f7a0d6f45b0d7960298ea10417c0b6c2dd3
+filesystem.md: c93d5e250860c19ab41f133848f5038b78f1bd57
+filesystem.zh.md: e9011d35b9a52fd42439a23e78fe4bff7ae41c11
diff --git a/docs/subsystems/filesystem.md b/docs/subsystems/filesystem.md
index 06fb92f453..c93d5e2508 100644
--- a/docs/subsystems/filesystem.md
+++ b/docs/subsystems/filesystem.md
@@ -396,6 +396,21 @@ abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterab
  */
 abstract readBytes(target: FsTarget, signal: AbortSignal | undefined, maxBytes: number): Promise<Uint8Array>
 
+/**
+ * Read one byte window of the regular file as raw bytes with no decoding or
+ * binary rejection: the bytes at `[offset, offset + length)`, shorter when
+ * the file ends inside the window and empty when `offset` lies at or past
+ * its end. The window is the bound here, not the file: a backend transfers
+ * at most `length` bytes of content beyond the prefix it skips to reach
+ * `offset` and never buffers the whole file, so the caller's cap on `length`
+ * is the guard against unbounded buffering.
+ * @param target - the resolved target to read.
+ * @param range - `offset`, the 0-based first byte, and `length`, the largest byte count; both non-negative integers.
+ * @param signal - aborts the read.
+ * @returns the window's bytes, at most `length` long.
+ */
+abstract readByteRange(target: FsTarget, range: { offset: number; length: number }, signal?: AbortSignal): Promise<Uint8Array>
+
 /**
  * List direct children of a directory in stable name order. Returns resolved
  * child targets plus cheap metadata only; never reads file contents.
diff --git a/docs/subsystems/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
index ea5b6f7a0d..e9011d35b9 100644
--- a/docs/subsystems/filesystem.zh.md
+++ b/docs/subsystems/filesystem.zh.md
@@ -396,6 +396,21 @@ abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterab
  */
 abstract readBytes(target: FsTarget, signal: AbortSignal | undefined, maxBytes: number): Promise<Uint8Array>
 
+/**
+ * Read one byte window of the regular file as raw bytes with no decoding or
+ * binary rejection: the bytes at `[offset, offset + length)`, shorter when
+ * the file ends inside the window and empty when `offset` lies at or past
+ * its end. The window is the bound here, not the file: a backend transfers
+ * at most `length` bytes of content beyond the prefix it skips to reach
+ * `offset` and never buffers the whole file, so the caller's cap on `length`
+ * is the guard against unbounded buffering.
+ * @param target - the resolved target to read.
+ * @param range - `offset`, the 0-based first byte, and `length`, the largest byte count; both non-negative integers.
+ * @param signal - aborts the read.
+ * @returns the window's bytes, at most `length` long.
+ */
+abstract readByteRange(target: FsTarget, range: { offset: number; length: number }, signal?: AbortSignal): Promise<Uint8Array>
+
 /**
  * List direct children of a directory in stable name order. Returns resolved
  * child targets plus cheap metadata only; never reads file contents.
diff --git a/docs/subsystems/goal.i18n.yaml b/docs/subsystems/goal.i18n.yaml
index 892090270e..9d5cdf725f 100644
--- a/docs/subsystems/goal.i18n.yaml
+++ b/docs/subsystems/goal.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/goal.md
-goal.md: 2fffebffa97221f0234750402bc6cb6361facec8
-goal.zh.md: f3d4b41204a303a49f059056864e2e56b1786475
+goal.md: ca49f0cd4f0ae65917e3dbc4e001d74d0f96d080
+goal.zh.md: 4567f327a950979ac5f0251bdc7f6dc9a619757c
diff --git a/docs/subsystems/goal.md b/docs/subsystems/goal.md
index 2fffebffa9..ca49f0cd4f 100644
--- a/docs/subsystems/goal.md
+++ b/docs/subsystems/goal.md
@@ -69,6 +69,25 @@ interface GoalView extends GoalSnapshot {
 }
 ```
 
+The service also publishes process-local activation edges without changing durable state; clients consume this event for live status.
+
+```ts type-equiv
+/** Live process-local activation update forwarded to UI clients. */
+interface GoalActivationChanged {
+  /** Session whose live goal activation changed. */
+  readonly sessionId: SessionId
+  /** Current exact activation, absent when no goal is current. */
+  readonly goal?: {
+    /** Exact current goal identity. */
+    readonly id: GoalId
+    /** Exact current goal revision. */
+    readonly revision: number
+    /** Current process-local continuation state. */
+    readonly activation: GoalActivation
+  }
+}
+```
+
 ## Durable changes
 
 Every mutation is a durable `goal/change` session event whose payload is either a complete post-mutation snapshot or a clear tombstone. The strict fold and persisted projection derive lifecycle state only from these events; inbox mutations do not affect goal state.
@@ -165,7 +184,7 @@ Goal service (`ctx.goals`) backed exclusively by the owning session log.
  * @returns a fresh view or `undefined` when no goal is current.
  * @throws {@link GoalError} when the agent is not the registry's live instance.
  */
-get(agent: Agent): GoalView | undefined
+@Remote('get') get(agent: Agent): GoalView | undefined
 
 /**
  * Remove process-local continuation authority without changing durable goal
@@ -253,6 +272,23 @@ Source: [`packages/goal/goal/src/index.ts`](../../packages/goal/goal/src/index.t
 
 ### `goal/*` events
 
+<a id="goalactivation-changed--emit"></a>
+
+#### `goal/activation-changed` — emit
+
+Process-local goal activation changed for one session.
+
+```ts cordis-catalog
+/**
+ * Process-local goal activation changed for one session.
+ * @mode emit
+ * @param payload - session id and the exact current goal activation, or no goal after a clear.
+ */
+'goal/activation-changed'(payload: GoalActivationChanged): void
+```
+
+Source: [`packages/goal/goal/src/types.ts`](../../packages/goal/goal/src/types.ts)
+
 <a id="goalchanged--emit"></a>
 
 #### `goal/changed` — emit
diff --git a/docs/subsystems/goal.zh.md b/docs/subsystems/goal.zh.md
index f3d4b41204..4567f327a9 100644
--- a/docs/subsystems/goal.zh.md
+++ b/docs/subsystems/goal.zh.md
@@ -69,6 +69,25 @@ interface GoalView extends GoalSnapshot {
 }
 ```
 
+服务还会在不改变持久状态的情况下发布进程本地 activation 边沿；客户端消费该事件获得实时状态。
+
+```ts type-equiv
+/** Live process-local activation update forwarded to UI clients. */
+interface GoalActivationChanged {
+  /** Session whose live goal activation changed. */
+  readonly sessionId: SessionId
+  /** Current exact activation, absent when no goal is current. */
+  readonly goal?: {
+    /** Exact current goal identity. */
+    readonly id: GoalId
+    /** Exact current goal revision. */
+    readonly revision: number
+    /** Current process-local continuation state. */
+    readonly activation: GoalActivation
+  }
+}
+```
+
 ## 持久变更
 
 每次变更都是持久的 `goal/change` 会话事件，其载荷要么是变更后的完整快照，要么是清除墓碑。严格折叠与持久投影只从这些事件派生生命周期状态；inbox 变更不会影响 goal 状态。
@@ -165,7 +184,7 @@ Goal service (`ctx.goals`) backed exclusively by the owning session log.
  * @returns a fresh view or `undefined` when no goal is current.
  * @throws {@link GoalError} when the agent is not the registry's live instance.
  */
-get(agent: Agent): GoalView | undefined
+@Remote('get') get(agent: Agent): GoalView | undefined
 
 /**
  * Remove process-local continuation authority without changing durable goal
@@ -253,6 +272,23 @@ Source: [`packages/goal/goal/src/index.ts`](../../packages/goal/goal/src/index.t
 
 ### `goal/*` events
 
+<a id="goalactivation-changed--emit"></a>
+
+#### `goal/activation-changed` — emit
+
+Process-local goal activation changed for one session.
+
+```ts cordis-catalog
+/**
+ * Process-local goal activation changed for one session.
+ * @mode emit
+ * @param payload - session id and the exact current goal activation, or no goal after a clear.
+ */
+'goal/activation-changed'(payload: GoalActivationChanged): void
+```
+
+Source: [`packages/goal/goal/src/types.ts`](../../packages/goal/goal/src/types.ts)
+
 <a id="goalchanged--emit"></a>
 
 #### `goal/changed` — emit
diff --git a/docs/subsystems/sidebar-right.i18n.yaml b/docs/subsystems/sidebar-right.i18n.yaml
new file mode 100644
index 0000000000..1b16e2a532
--- /dev/null
+++ b/docs/subsystems/sidebar-right.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/subsystems/sidebar-right.md
+sidebar-right.md: db4103a282287d8ea163d66b19efec27e0a0630f
+sidebar-right.zh.md: 1cb0b1e67e99acd7cb6aa12272cd57a5fdd207e0
diff --git a/docs/subsystems/sidebar-right.md b/docs/subsystems/sidebar-right.md
new file mode 100644
index 0000000000..db4103a282
--- /dev/null
+++ b/docs/subsystems/sidebar-right.md
@@ -0,0 +1,137 @@
+# Right Sidebar
+
+English | [中文](sidebar-right.zh.md)
+
+The right Sidebar is the Web Client's per-Session docking surface: a column of panes and tabs beside the conversation in which addressed content — a workspace file, a directory tree, the product's own pages — opens, splits, floats, and closes. [`dsh-client-ui-sidebar-right`](../../packages/client/ui-sidebar-right/README.md) owns the surface, the tab-type registry, and the navigation service; [`dsh-client-ui-dockkit`](../../packages/client/ui-dockkit/README.md) is its internal layout engine; [`dsh-client-resources`](../../packages/client/resources/README.md) turns addresses into live values for any component; [`dsh-api-workspace-files`](../../packages/api/workspace-files/README.md) provides both the Host workspace service and the Client `file` resource provider.
+
+This page is the reference for the subsystem's contracts: addresses, tab-type registration, the navigation service, the extension slots and their owner props, the resource model, the Workspace Files service, the shipped types, and what is deliberately not built. How the layout engine, the frame, and the surface fit together is in the [Agent Note](../../.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.md); slot mechanics are in the [Slots reference](slots.md).
+
+## Position and ownership
+
+One docking surface exists per Session, held in a session-scoped slot store and drawn by the `rightbar` seat; a reload returns every session to the collapsed default, and switching sessions keeps each surface where it was ([state](../../packages/client/ui-sidebar-right/README.md#state)). The surface's every change is one recorded history entry computed by the kit's pure planners; a docked pane never stays empty, and the last pane reseeds the guide tab.
+
+A tab type is two registrations that share one `kind`: a static definition in `ctx.sidebarRightTabs` saying which addresses the type opens, and a keyed slot registration supplying its body. The framework injects `useTabInfo()` for live Sidebar, pane and tab information; each type keeps its own state in its slot store. Packages import each other's declarations only as types.
+
+| Package | Role |
+|---|---|
+| [`client/ui-sidebar-right`](../../packages/client/ui-sidebar-right/README.md) | The panel and rail seats, the layout store, `ctx.sidebarRightTabs`, `ctx.sidebarRight`, the Tab domain, the guide type |
+| [`client/ui-dockkit`](../../packages/client/ui-dockkit/README.md) | Pure layout engine and React surface; an internal dependency of `ui-sidebar-right`, not a stable interface |
+| [`client/resources`](../../packages/client/resources/README.md) | `ctx.resources`, `useResource`, the protocol → value roster `ResourceProtocolMap` |
+| [`api/workspace-files`](../../packages/api/workspace-files/README.md) | Host `ctx.workspaceFiles`, the `workspaceFiles` Remote namespace, and the Client `file` resource provider |
+| [`util/workspace-path`](../../packages/util/workspace-path/README.md) | The file address grammar: `fileAddressFor`, `parseFileAddress` |
+| [`client/ui-sidebar-textpreview`](../../packages/client/ui-sidebar-textpreview/README.md), [`client/ui-sidebar-files`](../../packages/client/ui-sidebar-files/README.md) | The shipped `text` and `files` types |
+
+## Addresses
+
+Every tab is opened by an address string, and the address is the tab's content identity. Two families exist.
+
+A **resource address** is a `dsh-resource://<type>/…` URL. The host names the resource protocol — the key of `ResourceProtocolMap` — and everything after it is the protocol's own path; one scheme serves every protocol, so adding a protocol adds a host, never a scheme. The `file` protocol's path opens with its scope: `session/<sessionId>` followed by the path relative to that session's workspace root (`dsh-resource://file/session/abc/src/notes.txt`), or `absolute` followed by the absolute path with its leading `/` dropped (`dsh-resource://file/absolute/home/ys/notes.txt`, `dsh-resource://file/absolute/C:/x/y.txt` on Windows). Every id and path segment is component-encoded, with `:` kept literal for drive letters. `fileAddressFor(sessionId, cwd, path)` builds one — a relative path or an absolute path inside the workspace becomes `session`-relative, any other absolute path becomes `absolute` — and `parseFileAddress(address)` reads it back or returns `undefined` ([grammar](../../packages/util/workspace-path/README.md)).
+
+A **page address** is what the Sidebar records for a tab opened by kind rather than by resource: `sidebar://<kind>`, written by the Sidebar itself when `openTab(kind)` runs. Callers never build one — the guide and the file tree are opened as `openTab('guide')` and `openTab('files')` — and no other navigation address exists ([not built](#not-built)).
+
+Tab identity is the pair `(kind, address)`: the registry's claim uses the address verbatim as the record's `contentId`, so opening the same address through the same type finds the existing tab, and the same address through two types is two tabs.
+
+## Tab-type registration
+
+`ctx.sidebarRightTabs.register(definition)` registers one implementation of a type for the caller's lifetime and returns the disposer; the caller holds it inside its own `ctx.effect`, so an implementation lives exactly as long as the plugin that contributed it, and a second registration of the same `id` throws ([extension seats](../../packages/client/ui-sidebar-right/README.md#extension-seats)). The definition is static: no runtime hook, nothing per tab or per session.
+
+| Field | Meaning |
+|---|---|
+| `id` | The implementation's identity, unique across every registration; a package name is the natural value (`@deepseek-ai/dsh-client-ui-sidebar-files`). It is the key the body and title register under. |
+| `kind` | The type's discriminator: what its tabs are, and what `openTab` names. Not unique — an extension may take over a builtin's kind. The shipped kinds are `guide`, `text`, `files`. |
+| `patterns` | Optional resource-address globs the type recognizes; a page type opened by kind omits them. A pattern containing `:` matches the whole address (`dsh-resource://file/**`); one without matches the URL's path at any depth (`*.md`), and an address that is not a URL matches no such pattern. Matching is case-insensitive and does not hide dotfiles; the syntax is picomatch's POSIX dialect. |
+| `priority` | One of three literal bands: `extension` (the default and the highest: a type from outside the product outranks every shipped viewer), `builtin` (types shipped with the product), `fallback` (plain-content viewers anything more specific should beat). |
+| `canOpen(address)` | Optional synchronous veto of a glob match; it runs on every routing decision. |
+| `title(address)` | The chip's text, captured into the layout record when the tab opens and never rewritten. |
+| `guide` | Optional entry boxes for the guide page: `{ order, title(), description(), icon? }`. Picking a box opens the contributing type as a page; omit to stay off the page. |
+
+Routing is a ranked claim. `candidates(address)` ranks the types whose patterns match and whose `canOpen` does not veto: by band, then by the length of the longest matched pattern, then by registration order. `claim(address, kind?)` picks the first candidate, or the named `kind` outright — its globs are skipped, its `canOpen` still applies — and returns `{ kind, contentId: address, title }`. An address no type claims throws: it is a wiring mistake, not a user error.
+
+One `kind` may carry one `builtin` and one `extension` registration at the same time. The extension is the one in force for claims, `get(kind)`, `openTab(kind)`, and the guide page, and the seat finds a tab's body and title under the definition in force's `id`, so no slot priority is involved; when the extension unregisters, the builtin resumes. Every other collision on a kind, and every duplicate `id`, throws.
+
+```ts ignore-check
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-client-ui-sidebar-right/client'
+
+export const inject = ['sidebarRightTabs', 'slots']
+
+export function apply(ctx: Context): void {
+  ctx.effect(() => ctx.sidebarRightTabs.register({
+    id: '@acme/dsh-client-ui-image',
+    kind: 'image',
+    patterns: ['*.png', '*.jpg', '*.gif', '*.svg'],
+    canOpen: address => address.startsWith('dsh-resource://file/'),
+    title: address => address.slice(address.lastIndexOf('/') + 1),
+  }), 'image type')
+  ctx.effect(() => ctx.slots.inject('sidebar.right.pane.tab', () => ctx.slots.register(
+    { name: 'sidebar.right.pane.tab', key: '@acme/dsh-client-ui-image' },
+    ImageBody,
+  )), 'image body')
+}
+```
+
+## Navigation: `ctx.sidebarRight`
+
+Two opens are the navigation controller, and every way into the column calls one of them: `openResource(address, options?)` for a `dsh-resource://` address — the conversation's file links, a tool row's line reference, a file tree's rows — and `openTab(kind, options?)` for a page — the strip's add control, a guide entry box. Both run four steps as one history entry — claim (the registry ranks the resource's types, or the named `kind`'s implementation in force answers); focus a tab already showing the same `(kind, address)`; otherwise seat a new tab; expand the column — and then record the navigation in the Tab domain ([service](../../packages/client/ui-sidebar-right/README.md#ctxsidebarright)). Content the user cannot see is not opened, so a collapsed column expands in the same step. `openResource` throws for an address outside `dsh-resource://` or one no type claims; `openTab` throws for a kind nothing registered: both are wiring mistakes, not user errors.
+
+| Option | Meaning |
+|---|---|
+| `paneId` | Land a new tab in this pane; default is the active docked pane (the first docked pane while a floating pane is active). |
+| `replaceTab` | Take this tab's pane and strip slot, closing it in the same step; a floating tab lends no place, so the new tab lands as if unplaced. |
+| `revealIfOpened` | Default `true`: a tab already showing the same `(kind, address)` is focused and handed `params`. `false` opens another tab regardless. |
+| `kind` (`openResource` only) | Name the opening type instead of ranking claims; its implementation in force opens the address, and its `canOpen` still applies. |
+| `params` | Navigation parameters for the body, delivered as `navigation.params`. `openResource` types them by resource type through the merge-extensible `SidebarRightResourceParamsMap` (the text preview declares `{ line?: number }`); `openTab<K>` types them by kind through `SidebarRightTabParamsMap`, `undefined` for a kind that declares none; a body reads `SidebarRightNavigationParams`, the union of both. Values are JSON-shaped by convention and not validated at run time. |
+
+Placement is the caller's option, never a type's property. The conversation calls `openResource(fileAddressFor(sessionId, cwd, path))` and, from a `read` tool row, adds `{ params: { line } }` from the call's 1-based `offset`; a guide entry box calls `tab.actions.openTab(entry.kind, { replaceTab: true })`; a file-tree row calls `tab.actions.openResource(address)`; the strip's add control calls `openTab('guide', { paneId, revealIfOpened: false })`.
+
+`close(tabId)` closes a tab; `active()` returns the active pane's active tab; `isExpanded()` and `toggleExpanded()` read and flip the column, the flip recorded in the sequence. Reads answer for the no-Session case with `undefined` or `false`; writes need a mounted Session surface and throw without one rather than write into a surface nobody draws.
+
+`focus(tabId)` makes a tab its pane's active tab; `split(paneId?)` splits the active docked pane, or the named one, and returns the new pane's id — or `undefined`, recording nothing, when the pane budget or the column's width forbids a split; `float(tabId, rect?)` lifts a tab into a floating pane; `dock(paneId)` returns a floating pane to the docked area. All four run the store's existing actions and record one history entry each; a target that does not exist or is already in the requested state is a no-op, and like `open` they throw without a mounted Session surface. `TabId`, `PaneId`, `TabRecord`, and `FloatRect` are re-exported from the package's `/client` entry so a caller needs no dockkit import.
+
+## Slots and owner props
+
+The subsystem declares four slots; a tab type registers into the first, optionally the second, and any package into the others ([hierarchy](slots.md)).
+
+| Slot | Cardinality | Purpose |
+|---|---|---|
+| `sidebar.right.pane.tab` | keyed by the definition's `id`, Session scope | One tab's body. The seat dispatches a tab to the `id` of its kind's implementation in force, so the registrant receives every tab of its kind, docked or floating. A kind whose implementation registered no body renders the owner's "nothing can view this" notice. |
+| `sidebar.right.pane.tab.title` | keyed by the definition's `id`, Session scope | The chip's title, with the same owner share as the body. Optional: without an entry the chip shows the `title(address)` text captured at open time; a type with a live title reads its own store here. |
+| `sidebar.right.tab.guide` | chain, Session scope | Replaces the guide tab's contents without replacing the tab; the first non-declining entry takes the body, otherwise the shipped guide renders. |
+| `sidebar.right.tab.menu.item` | list, Session scope | Content-level actions appended after the kit's own layout actions. An item that acts must call the owner's `dismiss()`. |
+
+A body, title and guide replacement receive the framework-injected `useTabInfo()`. It returns `{ sidebar, panel, tab }`: `sidebar` holds `expanded` and `fullscreen`, `panel.id` names the containing pane, and `tab` contains its record fields plus `visible`, `navigation`, `signal`, and `actions`. Docked bodies are visible only while expanded and active; docked titles need only expansion; floats stay visible. `signal` aborts when the record disappears or the plugin unloads, not on hiding or Session switching. `tab.actions` provides `openResource`, `openTab`, and `close`, bound to the tab's own Session. Open placement defaults to its current pane; `revealIfOpened` defaults to `true`, and `replaceTab: true` replaces this record in the same history entry. Menu entries retain plain `tab` and `dismiss` owner parameters.
+
+`navigation.revision` increments on every navigation to the tab whether or not `params` changed, so a body can act on "navigated again" alone; it is `1` for a tab opened by address and `0` for a record nobody opened by address — a seeded guide, or a tab restored by undo. The Tab domain holds one occurrence per open record: a record that appears is pinned in the resource model, so switching tabs unmounts a body without dropping its content; a record that vanishes is aborted and dropped; a record restored by undo is a new occurrence ([Tab domain](../../packages/client/ui-sidebar-right/README.md#the-tab-domain)).
+
+## Resource model
+
+The model is documented in [Client Resources](client-resources.md); this section states what the Sidebar relies on. A resource is one address, and a resource address is a `dsh-resource://<type>/…` URL whose lower-cased host is the protocol key. The protocol's owning client package registers one provider with `ctx.resources.register(provider)` for its own lifetime; a second provider for the same protocol throws ([provide a protocol](../../packages/client/resources/README.md#provide-a-protocol)). A provider is `{ protocol, open(address, { signal }), reload?(address) }`: `open` yields `RemoteResult` frames — the current state first, one frame per later change — and stops when `signal` aborts; a failure is an `{ ok: false, error }` frame, never a throw, and a throw inside the stream is a programming error the model does not catch.
+
+`useResource<P>(address)` is a global standard prop on every slot component, whatever its scope. It returns `{ status, value, failure, reload }`: `none` when the address's protocol has no provider or the address is not a resource address (`sidebar://guide` names no resource), `loading` until the first frame, `live` with the latest `ok` value, `failed` with the latest frame's failure beside the last value. `reload()` asks the provider for a fresh frame and is a no-op without one ([read a resource](../../packages/client/resources/README.md#read-a-resource)).
+
+A resource stays open while it has a holder — a subscribed `useResource` or a `ctx.resources.pin(address, signal)`; the first holder opens the provider's stream, later holders share it and read the latest value at once, and the last release aborts the stream and discards the value. Streams carry metadata, not content: the `file` value is `{ absolutePath, version, bytes?, changed }`, and a consumer reads file text itself, by page, through the Workspace Files service ([lifecycle](../../packages/client/resources/README.md#lifecycle)).
+
+## Workspace Files
+
+The Host `ctx.workspaceFiles` service and the generated `workspaceFiles` Remote namespace answer for files inside the addressed Session's workspace root: `stat(path)` returns `{ absolutePath, version, bytes? }`; `read(path, { offset?, limit? })` returns one page of lines (`offset` 1-based, `limit` capped by the configured page size) as `{ …stat, offset, text, eof }`; `readBytes(path, { offset?, length? })` returns one raw byte window (`offset` 0-based, `length` capped by the configured byte limit) as base64 `{ …stat, offset, data, eof }` with no text decoding; `list(path)` returns a directory's direct children (`name`, `type: 'file' | 'directory' | 'other'`, `size?`) cut to the configured cap with `truncated` set; `changes()` yields `{ kind: 'ready' }` once subscribed, then `{ kind: 'change', change }` frames whose payload is `{ absolutePath, version }` or `{ absolutePath, absent: true }` ([README](../../packages/api/workspace-files/README.md#use-this-package)). Every call passes the same four gates — the path is inside the workspace root, symlinks are refused, page, window, and entry caps hold, `read`'s text is UTF-8 — and fails with a `workspace-file/*` error code otherwise ([failures](../../packages/api/workspace-files/README.md)).
+
+[`dsh-api-workspace-files`](../../packages/api/workspace-files/README.md) registers the `file` provider and declares `ResourceProtocolMap.file`. It sends a Session address's relative path unchanged to the Host and binds change filtering to the first successful `stat.absolutePath`. It waits for the Host's `ready` frame before stat, retaining changes delivered during that read. An absolute address uses the current Session; only its absence produces Client `workspace-file/unknown-workspace`. No Client `cwd` is required.
+
+## Shipped types
+
+- **`guide`** — `builtin`, opened as `openTab('guide')`. A centred title, one line, and one entry box per `guide` entry the registered types contributed, in `order`; picking a box opens the contributing type as a page in the guide tab's place. A pane holds at most one guide tab, every new pane is seeded with one, and the strip's add control appears only while its pane has none ([guide](../../packages/client/ui-sidebar-right/README.md#the-guide)).
+- **`text`** — `fallback`, `dsh-resource://file/**`. Reads metadata through `useResource<'file'>` and the file's lines by page through `read`; honours `params.line` on every navigation; keeps pages, scroll, and wrap in its own store ([README](../../packages/client/ui-sidebar-textpreview/README.md)).
+- **`files`** — `builtin`, opened as `openTab('files')`. The workspace directory tree, listed lazily through `list`, opening a file with `tab.actions.openResource(fileAddressFor(sessionId, root, path))` into its own pane ([README](../../packages/client/ui-sidebar-files/README.md)).
+
+<a id="not-built"></a>
+## Not built
+
+- Persistence: layout state is memory-only; a reload starts every session collapsed, and no session's tabs are visible from another.
+- A read-only layout snapshot or subscription on `ctx.sidebarRight`: the service exposes operations only, and dockkit's `LayoutState`/`LayoutOp` are internal.
+- A capability-discovery array (`features`) on the service.
+- An `option` priority band: nothing lists a type without letting it claim.
+- Retitling a record: `title(address)` is captured once; a live chip comes from the title slot, not from the record.
+- Naming an implementation when opening: `openResource` names a kind at most, and the kind's implementation in force answers.
+- An address lookup on the service (`find`): a caller opens with `revealIfOpened` and lets the surface de-duplicate.
+- Navigation addresses beyond the Sidebar's own `sidebar://<kind>` bookkeeping; their grammar waits for the navigation controller as a whole.
+- A user-facing undo, a content navigation stack, tab icons, and closing restrictions ([deferred](../../.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.md#deferred)).
diff --git a/docs/subsystems/sidebar-right.zh.md b/docs/subsystems/sidebar-right.zh.md
new file mode 100644
index 0000000000..1cb0b1e67e
--- /dev/null
+++ b/docs/subsystems/sidebar-right.zh.md
@@ -0,0 +1,137 @@
+# 右侧 Sidebar
+
+[English](sidebar-right.md) | 中文
+
+右侧 Sidebar 是 Web Client 里每个会话一份的停靠面：会话区旁的一列 pane 与 tab，按地址寻址的内容——工作区文件、目录树、产品自带页面——在这里打开、分栏、浮出、关闭。[`dsh-client-ui-sidebar-right`](../../packages/client/ui-sidebar-right/README.zh.md) 拥有这个面、tab 类型注册表与导航服务；[`dsh-client-ui-dockkit`](../../packages/client/ui-dockkit/README.zh.md) 是它内部的布局引擎；[`dsh-client-resources`](../../packages/client/resources/README.zh.md) 把地址变成任何组件都能读的活数据；[`dsh-api-workspace-files`](../../packages/api/workspace-files/README.zh.md) 同时提供 Host 工作区文件服务与 Client `file` 资源提供者。
+
+本页是该子系统契约的参考：地址、tab 类型注册、导航服务、扩展 slot 与其 owner props、资源模型、Workspace Files 服务、内置类型，以及明确不做的事。布局引擎、frame 与停靠面如何拼在一起见 [Agent Note](../../.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md)；slot 机制见 [Slots 参考](slots.zh.md)。
+
+## 定位与归属
+
+每个会话恰有一个停靠面，保存在会话作用域的 slot store 里、由 `rightbar` 席位绘制；刷新页面后每个会话回到折叠的默认态，切换会话时各自的面保持原状（[状态](../../packages/client/ui-sidebar-right/README.zh.md#state)）。面的每一次变化都是 kit 纯规划器算出的一条历史记录；停靠的 pane 从不空着，最后一个 pane 会重新种入引导 tab。
+
+一个 tab 类型是共用一个 `kind` 的两次注册：在 `ctx.sidebarRightTabs` 里的静态定义说明该类型打开哪些地址，一次 keyed slot 注册提供它的正文。框架注入 `useTabInfo()` 以读取 Sidebar、窗格和标签的实时信息；各类型把自身状态放在 slot store 里。各包之间只以类型形式引用彼此的声明。
+
+| 包 | 职责 |
+|---|---|
+| [`client/ui-sidebar-right`](../../packages/client/ui-sidebar-right/README.zh.md) | 面板与栏席位、布局 store、`ctx.sidebarRightTabs`、`ctx.sidebarRight`、Tab 域、引导类型 |
+| [`client/ui-dockkit`](../../packages/client/ui-dockkit/README.zh.md) | 纯布局引擎与 React 面；`ui-sidebar-right` 的内部依赖，不是稳定接口 |
+| [`client/resources`](../../packages/client/resources/README.zh.md) | `ctx.resources`、`useResource`、协议 → 值类型的花名册 `ResourceProtocolMap` |
+| [`api/workspace-files`](../../packages/api/workspace-files/README.zh.md) | Host `ctx.workspaceFiles`、`workspaceFiles` Remote 命名空间与 Client `file` 资源提供者 |
+| [`util/workspace-path`](../../packages/util/workspace-path/README.zh.md) | 文件地址语法：`fileAddressFor`、`parseFileAddress` |
+| [`client/ui-sidebar-textpreview`](../../packages/client/ui-sidebar-textpreview/README.zh.md)、[`client/ui-sidebar-files`](../../packages/client/ui-sidebar-files/README.zh.md) | 内置的 `text` 与 `files` 类型 |
+
+## 地址
+
+每个 tab 都由一个地址字串打开，地址就是 tab 的内容身份。地址分两族。
+
+**资源地址**是 `dsh-resource://<type>/…` 形式的 URL。host 命名资源协议——即 `ResourceProtocolMap` 的键——其后是该协议自己的路径；所有协议共用一个 scheme，新增协议只新增 host、不新增 scheme。`file` 协议的路径以其作用域开头：`session/<sessionId>` 后接相对该会话工作区根的路径（`dsh-resource://file/session/abc/src/notes.txt`），或 `absolute` 后接去掉前导 `/` 的绝对路径（`dsh-resource://file/absolute/home/ys/notes.txt`，Windows 上为 `dsh-resource://file/absolute/C:/x/y.txt`）。id 与每一段路径都做组件编码，盘符的 `:` 保留原样。`fileAddressFor(sessionId, cwd, path)` 构造地址——相对路径或工作区内的绝对路径成为 `session` 相对地址，其他绝对路径成为 `absolute` 地址——`parseFileAddress(address)` 读回各部分或返回 `undefined`（[语法](../../packages/util/workspace-path/README.zh.md)）。
+
+**页面地址**是 Sidebar 为按 kind（而非按资源）打开的 tab 记下的地址：`sidebar://<kind>`，由 Sidebar 自己在 `openTab(kind)` 运行时写入。调用方从不拼它——引导页与文件树以 `openTab('guide')`、`openTab('files')` 打开——此外不存在任何导航地址（[不做](#not-built)）。
+
+tab 身份是 `(kind, address)` 二元组：注册表的认领把地址原文用作记录的 `contentId`，因此同一地址经同一类型再次打开会找到已有 tab，同一地址经两个类型打开则是两个 tab。
+
+## Tab 类型注册
+
+`ctx.sidebarRightTabs.register(definition)` 在调用方的生命周期内注册一个类型的一份实现并返回注销器；调用方把它放在自己的 `ctx.effect` 里，因此实现与贡献它的插件同寿，同一 `id` 的第二次注册抛错（[扩展席位](../../packages/client/ui-sidebar-right/README.zh.md#extension-seats)）。定义是静态的：没有运行时 hook，没有按 tab 或按会话的东西。
+
+| 字段 | 含义 |
+|---|---|
+| `id` | 该实现的身份，在所有注册中唯一；包名是自然取值（`@deepseek-ai/dsh-client-ui-sidebar-files`）。正文与标题坑位按它注册。 |
+| `kind` | 类型的判别名：它的 tab 是什么，也是 `openTab` 点名的对象。不唯一——extension 可以接管 builtin 的 kind。内置 kind 为 `guide`、`text`、`files`。 |
+| `patterns` | 可选的资源地址 glob；按 kind 打开的页面类型省略。含 `:` 的模式匹配整个地址（`dsh-resource://file/**`）；不含的匹配 URL 的路径部分且任意深度都中（`*.md`），不是 URL 的地址不会命中此类模式。匹配不分大小写、不隐藏 dotfile；语法为 picomatch 的 POSIX 方言。 |
+| `priority` | 三档字面量之一：`extension`（缺省且最高：产品之外的类型压过所有内置查看器）、`builtin`（随产品发布的类型）、`fallback`（任何更具体的类型都应压过的纯内容查看器）。 |
+| `canOpen(address)` | 可选的同步否决，对 glob 命中生效；每次路由决策都会调用。 |
+| `title(address)` | chip 文本，在 tab 打开时捕获进布局记录，之后不再改写。 |
+| `guide` | 可选的引导页入口框：`{ order, title(), description(), icon? }`。点一框即把贡献它的类型作为页面打开；省略即不上引导页。 |
+
+路由是一次排序认领。`candidates(address)` 对模式命中且未被 `canOpen` 否决的类型排序：先按档，再按最长命中模式的长度，最后按注册顺序。`claim(address, kind?)` 取第一个候选，或直接用点名的 `kind`——跳过它的 glob，但 `canOpen` 仍生效——返回 `{ kind, contentId: address, title }`。没有任何类型认领的地址会抛错：这是接线错误，不是用户错误。
+
+同一个 `kind` 可同时携带一个 `builtin` 与一个 `extension` 注册。extension 在认领、`get(kind)`、`openTab(kind)` 与引导页上生效，席位按生效定义的 `id` 找 tab 的正文与标题，不涉及任何 slot 优先级；extension 注销后 builtin 恢复。kind 上的其它任何撞名以及任何重复的 `id` 都抛错。
+
+```ts ignore-check
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-client-ui-sidebar-right/client'
+
+export const inject = ['sidebarRightTabs', 'slots']
+
+export function apply(ctx: Context): void {
+  ctx.effect(() => ctx.sidebarRightTabs.register({
+    id: '@acme/dsh-client-ui-image',
+    kind: 'image',
+    patterns: ['*.png', '*.jpg', '*.gif', '*.svg'],
+    canOpen: address => address.startsWith('dsh-resource://file/'),
+    title: address => address.slice(address.lastIndexOf('/') + 1),
+  }), 'image type')
+  ctx.effect(() => ctx.slots.inject('sidebar.right.pane.tab', () => ctx.slots.register(
+    { name: 'sidebar.right.pane.tab', key: '@acme/dsh-client-ui-image' },
+    ImageBody,
+  )), 'image body')
+}
+```
+
+## 导航：`ctx.sidebarRight`
+
+两种打开构成导航控制器，进入这一列的每条路都调用其一：`openResource(address, options?)` 打开 `dsh-resource://` 地址——会话区的文件链接、工具行的行号引用、文件树的行；`openTab(kind, options?)` 打开页面——tab 条的新增控件、引导页入口框。两者都以一条历史记录走完四步——认领（注册表为资源排候选，或点名 `kind` 的生效实现应答）；聚焦已显示同一 `(kind, address)` 的 tab；否则落一个新 tab；展开这一列——然后把导航记入 Tab 域（[服务](../../packages/client/ui-sidebar-right/README.zh.md#ctxsidebarright)）。用户看不见的内容不算打开，所以折叠的列会在同一步展开。`openResource` 对 `dsh-resource://` 之外的地址或无人认领的地址抛错；`openTab` 对无人注册的 kind 抛错：二者都是接线错误，不是用户错误。
+
+| 选项 | 含义 |
+|---|---|
+| `paneId` | 新 tab 落到这个 pane；缺省为活动的停靠 pane（活动的是浮窗时取第一个停靠 pane）。 |
+| `replaceTab` | 占用这个 tab 的 pane 与条上位置，并在同一步关闭它；浮窗里的 tab 让不出位置，新 tab 按未指定位置落位。 |
+| `revealIfOpened` | 缺省 `true`：已显示同一 `(kind, address)` 的 tab 被聚焦并收到 `params`。`false` 则无论如何再开一个。 |
+| `kind`（仅 `openResource`） | 点名打开类型而不排候选；该 kind 的生效实现打开地址，它的 `canOpen` 仍生效。 |
+| `params` | 给正文的导航参数，作为 `navigation.params` 送达。`openResource` 按资源类型经声明合并表 `SidebarRightResourceParamsMap` 定型（文本预览声明 `{ line?: number }`）；`openTab<K>` 按 kind 经 `SidebarRightTabParamsMap` 定型，未声明的 kind 为 `undefined`；正文读到的是二者联合 `SidebarRightNavigationParams`。值按约定为 JSON 形状，运行时不校验。 |
+
+落位是调用方的选项，从不是类型的属性。会话区调 `openResource(fileAddressFor(sessionId, cwd, path))`，`read` 工具行另加 `{ params: { line } }`（来自调用的 1 起 `offset`）；引导页入口框调 `tab.actions.openTab(entry.kind, { replaceTab: true })`；文件树的行调 `tab.actions.openResource(address)`；tab 条的新增控件调 `openTab('guide', { paneId, revealIfOpened: false })`。
+
+`close(tabId)` 关闭一个 tab；`active()` 返回活动 pane 的活动 tab；`isExpanded()` 与 `toggleExpanded()` 读取与翻转这一列，翻转记入序列。无会话时读操作返回 `undefined` 或 `false`；写操作需要已挂载的会话面，没有时抛错而不是写进没人绘制的面。
+
+`focus(tabId)` 让一个 tab 成为其 pane 的活动 tab；`split(paneId?)` 分割活动的停靠 pane 或点名的 pane，返回新 pane 的 id——pane 数预算或列宽不允许时返回 `undefined` 且不记账；`float(tabId, rect?)` 把一个 tab 浮出为浮窗 pane；`dock(paneId)` 把浮窗 pane 收回停靠区。四者都走 store 既有动作、各记一条历史；目标不存在或已处于目标状态时是空操作，与 `open` 一样在没有已挂载会话面时抛错。`TabId`、`PaneId`、`TabRecord`、`FloatRect` 自本包 `/client` 入口再导出，调用方无需引 dockkit。
+
+## Slot 与 owner props
+
+本子系统声明四个 slot；tab 类型注册进第一个，可选地注册第二个，任何包都可注册进其余两个（[层级](slots.zh.md)）。
+
+| Slot | Cardinality | 用途 |
+|---|---|---|
+| `sidebar.right.pane.tab` | 按定义的 `id` keyed，会话作用域 | 一个 tab 的正文。席位把 tab 分发到其 kind 生效实现的 `id`，因此注册者收到该 kind 的每个 tab，停靠或浮窗。实现没有注册正文的 kind 渲染 owner 的「无法查看此内容」提示。 |
+| `sidebar.right.pane.tab.title` | 按定义的 `id` keyed，会话作用域 | chip 的标题，owner share 与正文相同。可选：没有条目时 chip 显示打开时捕获的 `title(address)` 文本；有活标题的类型在此读自己的 store。 |
+| `sidebar.right.tab.guide` | chain，会话作用域 | 替换引导 tab 的内容而不替换 tab；第一个不拒绝的条目接管正文，否则渲染自带引导。 |
+| `sidebar.right.tab.menu.item` | list，会话作用域 | 追加在 kit 自身布局动作之后的内容级动作。执行了动作的条目必须调用 owner 的 `dismiss()`。 |
+
+正文、标题与引导页替换项接收框架注入的 `useTabInfo()`。它返回 `{ sidebar, panel, tab }`：`sidebar` 包含 `expanded` 与 `fullscreen`，`panel.id` 标识所属窗格，`tab` 包含记录字段以及 `visible`、`navigation`、`signal` 和 `actions`。停靠正文仅在展开且活跃时可见；停靠标题只要求展开；浮窗保持可见。`signal` 在记录消失或插件卸载时中止，不因隐藏或切换 Session 而中止。`tab.actions` 提供绑定到标签所属 Session 的 `openResource`、`openTab` 与 `close`。打开位置缺省为当前所属窗格；`revealIfOpened` 缺省为 `true`，`replaceTab: true` 在同一历史项中替换本记录。菜单项保留普通的 `tab` 与 `dismiss` owner 参数。
+
+`navigation.revision` 在每次导航到该 tab 时递增，`params` 不变也递增，正文可仅凭「又被导航了」行动；按地址打开的 tab 为 `1`，没有人按地址打开的记录——种入的引导、撤销恢复的 tab——为 `0`。Tab 域为每条打开的记录保有一个 occurrence：记录出现即在资源模型里钉住，因此切换 tab 卸载正文也不丢内容；记录消失即中止并丢弃；撤销恢复的记录是新的 occurrence（[Tab 域](../../packages/client/ui-sidebar-right/README.zh.md#the-tab-domain)）。
+
+## 资源模型
+
+模型本身见[客户端资源](client-resources.zh.md)；本节只写 Sidebar 依赖的部分。一份资源是一个地址，资源地址是 `dsh-resource://<type>/…` 形式的 URL，小写 host 即协议键。协议所属的客户端包用 `ctx.resources.register(provider)` 在自身生命周期内注册唯一的提供方；同一协议的第二个提供方抛错（[提供协议](../../packages/client/resources/README.zh.md#provide-a-protocol)）。提供方是 `{ protocol, open(address, { signal }), reload?(address) }`：`open` 产出 `RemoteResult` 帧——首帧是当前状态，之后每次变化一帧——并在 `signal` 中止时停下；失败是 `{ ok: false, error }` 帧而不是抛错，流里抛出的东西是编程错误，模型不捕获。
+
+`useResource<P>(address)` 是每个 slot 组件都有的全局标准 prop，不论作用域。它返回 `{ status, value, failure, reload }`：地址协议没有提供方或地址不是资源地址（`sidebar://guide` 不指向资源）时为 `none`，首帧之前为 `loading`，`live` 携带最新 `ok` 值，`failed` 在最后一个值旁携带最新帧的失败。`reload()` 请提供方给一个新帧，没有提供方时是空操作（[读取资源](../../packages/client/resources/README.zh.md#read-a-resource)）。
+
+资源有持有者就保持打开——订阅中的 `useResource` 或一次 `ctx.resources.pin(address, signal)`；第一个持有者打开提供方的流，之后的持有者共享它并立刻读到最新值，最后一个释放时中止流并丢弃值。流只推元数据不推内容：`file` 的值是 `{ absolutePath, version, bytes?, changed }`，消费方自己经 Workspace Files 服务按页读文件文本（[生命周期](../../packages/client/resources/README.zh.md#lifecycle)）。
+
+## Workspace Files
+
+Host 的 `ctx.workspaceFiles` 服务与生成的 `workspaceFiles` Remote 命名空间负责所寻址会话工作区根之内的文件：`stat(path)` 返回 `{ absolutePath, version, bytes? }`；`read(path, { offset?, limit? })` 返回一页行（`offset` 1 起，`limit` 受配置页长限制），形如 `{ …stat, offset, text, eof }`；`readBytes(path, { offset?, length? })` 返回一个原始字节窗口（`offset` 0 起，`length` 受配置字节上限限制），形如 base64 的 `{ …stat, offset, data, eof }`、不做文本解码；`list(path)` 返回目录的直接子项（`name`、`type: 'file' | 'directory' | 'other'`、`size?`），按配置上限截断并置 `truncated`；`changes()` 在订阅就绪后产出 `{ kind: 'ready' }`，随后产出 `{ kind: 'change', change }` 帧，其载荷为 `{ absolutePath, version }` 或 `{ absolutePath, absent: true }`（[README](../../packages/api/workspace-files/README.zh.md#use-this-package)）。每次调用都过同样四关——路径在工作区根内、拒绝符号链接、页、窗口与条目上限、`read` 的 UTF-8 文本——否则以 `workspace-file/*` 错误码失败（[失败](../../packages/api/workspace-files/README.zh.md)）。
+
+[`dsh-api-workspace-files`](../../packages/api/workspace-files/README.zh.md) 注册 `file` 提供方并声明 `ResourceProtocolMap.file`。它把 Session 地址的相对路径原样发送给 Host，按首次成功的 `stat.absolutePath` 绑定变更过滤。它在 stat 前等待 Host 的 `ready` 帧，并保留读取期间到达的变更。绝对地址使用当前 Session；只有缺少当前 Session 时才产生 Client `workspace-file/unknown-workspace`。Client 不需要 `cwd`。
+
+## 内置类型
+
+- **`guide`**——`builtin`，以 `openTab('guide')` 打开。居中标题、一行说明，以及已注册类型贡献的每个 `guide` 入口一框、按 `order` 排列；点一框即在引导 tab 的位置把贡献它的类型作为页面打开。每个 pane 最多一个引导 tab，每个新 pane 都种入一个，tab 条的新增控件只在本 pane 没有引导时出现（[引导](../../packages/client/ui-sidebar-right/README.zh.md#the-guide)）。
+- **`text`**——`fallback`，`dsh-resource://file/**`。经 `useResource<'file'>` 读元数据、经 `read` 按页读文件行；每次导航都响应 `params.line`；页、滚动与换行放在自己的 store 里（[README](../../packages/client/ui-sidebar-textpreview/README.zh.md)）。
+- **`files`**——`builtin`，以 `openTab('files')` 打开。工作区目录树，经 `list` 懒加载，用 `tab.actions.openResource(fileAddressFor(sessionId, root, path))` 在自己所在 pane 打开文件（[README](../../packages/client/ui-sidebar-files/README.zh.md)）。
+
+<a id="not-built"></a>
+## 不做
+
+- 持久化：布局状态只在内存里；刷新后每个会话从折叠开始，任何会话的 tab 都不会出现在另一个会话里。
+- `ctx.sidebarRight` 上的只读布局快照或订阅：服务只暴露操作，dockkit 的 `LayoutState`/`LayoutOp` 是内部的。
+- 服务上的能力探测数组（`features`）。
+- `option` 优先级档：没有「只列出、不许认领」的类型。
+- 改写记录的标题：`title(address)` 只捕获一次；活的 chip 来自标题 slot，而不是记录。
+- 打开时点名某个实现：`openResource` 最多点名一个 kind，由该 kind 的生效实现应答。
+- 服务上的地址查找（`find`）：调用方用 `revealIfOpened` 打开，由停靠面去重。
+- Sidebar 自身 `sidebar://<kind>` 记账之外的导航地址；其语法等导航控制器整体做时再定。
+- 面向用户的撤销、内容导航栈、tab 图标与关闭限制（[暂缓](../../.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md#deferred)）。
diff --git a/docs/subsystems/slots.i18n.yaml b/docs/subsystems/slots.i18n.yaml
index 1c96cdce9a..49925a9aa5 100644
--- a/docs/subsystems/slots.i18n.yaml
+++ b/docs/subsystems/slots.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/slots.md
-slots.md: a37374ff11f9d460a2566a7a30f8318e69cbfa0b
-slots.zh.md: 09329b1f299f4912490f888efa3146ec0ce11e28
+slots.md: 136607b035c4a40c8ab96d6bf933e6b5c8a925bf
+slots.zh.md: b3a54048f5df20ad3ef271aea868ce15d5e18bce
diff --git a/docs/subsystems/slots.md b/docs/subsystems/slots.md
index a37374ff11..136607b035 100644
--- a/docs/subsystems/slots.md
+++ b/docs/subsystems/slots.md
@@ -142,7 +142,8 @@ root
 │  ├─ conversation.session.header
 │  │  ├─ conversation.session.header.lineage
 │  │  ├─ conversation.session.header.actions
-│  │  └─ conversation.session.header.utilities
+│  │  ├─ conversation.session.header.utilities
+│  │  └─ conversation.session.header.corner
 │  ├─ conversation.composer
 │  │  └─ conversation.approval.detail
 │  ├─ conversation.composer.bar
@@ -158,8 +159,11 @@ root
 │  ├─ conversation.hero.workspace
 │  │  └─ conversation.hero.workspace.directoryFlow
 │  └─ conversation.hero.agentPreset
-├─ details
-│  └─ conversation.details.tool
+├─ rightbar
+│  ├─ sidebar.right.pane.tab
+│  │  └─ sidebar.right.tab.guide
+│  ├─ sidebar.right.pane.tab.title
+│  └─ sidebar.right.tab.menu.item
 └─ shell.overlay
 ```
 
diff --git a/docs/subsystems/slots.zh.md b/docs/subsystems/slots.zh.md
index 09329b1f29..b3a54048f5 100644
--- a/docs/subsystems/slots.zh.md
+++ b/docs/subsystems/slots.zh.md
@@ -142,7 +142,8 @@ root
 │  ├─ conversation.session.header
 │  │  ├─ conversation.session.header.lineage
 │  │  ├─ conversation.session.header.actions
-│  │  └─ conversation.session.header.utilities
+│  │  ├─ conversation.session.header.utilities
+│  │  └─ conversation.session.header.corner
 │  ├─ conversation.composer
 │  │  └─ conversation.approval.detail
 │  ├─ conversation.composer.bar
@@ -158,8 +159,11 @@ root
 │  ├─ conversation.hero.workspace
 │  │  └─ conversation.hero.workspace.directoryFlow
 │  └─ conversation.hero.agentPreset
-├─ details
-│  └─ conversation.details.tool
+├─ rightbar
+│  ├─ sidebar.right.pane.tab
+│  │  └─ sidebar.right.tab.guide
+│  ├─ sidebar.right.pane.tab.title
+│  └─ sidebar.right.tab.menu.item
 └─ shell.overlay
 ```
 
diff --git a/docs/subsystems/workspace.i18n.yaml b/docs/subsystems/workspace.i18n.yaml
index b901856ad2..77fbb01e39 100644
--- a/docs/subsystems/workspace.i18n.yaml
+++ b/docs/subsystems/workspace.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/workspace.md
-workspace.md: a66d9d94b02ec98d4197862f8e86e6ec027fda6c
-workspace.zh.md: 46883ccd3c9cd3b3cbd8c91afe4c6d7e85449cbf
+workspace.md: 3e54ef3d0a2339d50fbc8a4132b91d7f82701321
+workspace.zh.md: a9b8375f388538a3588a84f2d71e47b89ddc679a
diff --git a/docs/subsystems/workspace.md b/docs/subsystems/workspace.md
index a66d9d94b0..3e54ef3d0a 100644
--- a/docs/subsystems/workspace.md
+++ b/docs/subsystems/workspace.md
@@ -242,6 +242,68 @@ Host service backing the generated `ctx.remote.workspace` namespace.
 
 Source: [`packages/api/workspace-controller/src/index.ts`](../../packages/api/workspace-controller/src/index.ts)
 
+<a id="ctxworkspacefiles--workspacefiles"></a>
+
+### `ctx.workspaceFiles` — `WorkspaceFiles`
+
+Host Remote service over the composed filesystem, confined to one workspace.
+
+```ts cordis-catalog
+/**
+ * Read one page of lines from a UTF-8 text file inside the Agent's workspace.
+ * @param agent - target Agent resolved from the Session identity on the wire.
+ * @param path - workspace path, absolute or relative to the workspace root.
+ * @param range - the line window; omitted fields take the page defaults.
+ * @param signal - caller cancellation.
+ * @returns the page, the file's version at the stat before it, and whether it reaches the last line.
+ */
+@Remote async read(agent: Agent, path: string, range: WorkspaceFileRange, signal: AbortSignal): Promise<WorkspaceFileText>
+
+/**
+ * Read one byte window of a regular file inside the Agent's workspace: raw
+ * bytes, no text decoding and no binary rejection.
+ * @param agent - target Agent resolved from the Session identity on the wire.
+ * @param path - workspace path, absolute or relative to the workspace root.
+ * @param range - the byte window; omitted fields take the window defaults.
+ * @param signal - caller cancellation.
+ * @returns the window in base64, the file's version and size at the stat before it, and whether it reaches the last byte.
+ */
+@Remote async readBytes(agent: Agent, path: string, range: WorkspaceByteRange, signal: AbortSignal): Promise<WorkspaceFileBytes>
+
+/**
+ * Report one regular file's identity, version, and size without its content.
+ * @param agent - target Agent resolved from the Session identity on the wire.
+ * @param path - workspace path, absolute or relative to the workspace root.
+ * @param signal - caller cancellation.
+ * @returns the file's absolute path, current version, and byte size.
+ */
+@Remote async stat(agent: Agent, path: string, signal: AbortSignal): Promise<WorkspaceFileStat>
+
+/**
+ * List the direct children of one directory inside the Agent's workspace.
+ * @param agent - target Agent resolved from the Session identity on the wire.
+ * @param path - workspace path, absolute or relative to the workspace root.
+ * @param signal - caller cancellation.
+ * @returns the directory's children in the backend's stable name order, bounded by the entry cap.
+ */
+@Remote async list(agent: Agent, path: string, signal: AbortSignal): Promise<WorkspaceDirectoryListing>
+
+/**
+ * Stream every `fs/observed` observation of a file inside the Agent's
+ * workspace. Only Agent filesystem operations report here; the OS is not
+ * watched.
+ * @param agent - target Agent resolved from the Session identity on the wire.
+ * @param signal - generation cancellation.
+ * @returns `ready` once the Host observation queue is active and the workspace
+ *   root is resolved, then queued and live observations in emission order.
+ */
+@Remote({ mode: 'stream' }) changes(agent: Agent, signal: AbortSignal): AsyncIterable<WorkspaceFileWatchFrame>
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/api/workspace-files/src/index.ts`](../../packages/api/workspace-files/src/index.ts)
+
 <a id="ctxworkspaceregistry--workspaceregistry"></a>
 
 ### `ctx.workspaceRegistry` — `WorkspaceRegistry`
diff --git a/docs/subsystems/workspace.zh.md b/docs/subsystems/workspace.zh.md
index 46883ccd3c..a9b8375f38 100644
--- a/docs/subsystems/workspace.zh.md
+++ b/docs/subsystems/workspace.zh.md
@@ -242,6 +242,68 @@ Host service backing the generated `ctx.remote.workspace` namespace.
 
 Source: [`packages/api/workspace-controller/src/index.ts`](../../packages/api/workspace-controller/src/index.ts)
 
+<a id="ctxworkspacefiles--workspacefiles"></a>
+
+### `ctx.workspaceFiles` — `WorkspaceFiles`
+
+Host Remote service over the composed filesystem, confined to one workspace.
+
+```ts cordis-catalog
+/**
+ * Read one page of lines from a UTF-8 text file inside the Agent's workspace.
+ * @param agent - target Agent resolved from the Session identity on the wire.
+ * @param path - workspace path, absolute or relative to the workspace root.
+ * @param range - the line window; omitted fields take the page defaults.
+ * @param signal - caller cancellation.
+ * @returns the page, the file's version at the stat before it, and whether it reaches the last line.
+ */
+@Remote async read(agent: Agent, path: string, range: WorkspaceFileRange, signal: AbortSignal): Promise<WorkspaceFileText>
+
+/**
+ * Read one byte window of a regular file inside the Agent's workspace: raw
+ * bytes, no text decoding and no binary rejection.
+ * @param agent - target Agent resolved from the Session identity on the wire.
+ * @param path - workspace path, absolute or relative to the workspace root.
+ * @param range - the byte window; omitted fields take the window defaults.
+ * @param signal - caller cancellation.
+ * @returns the window in base64, the file's version and size at the stat before it, and whether it reaches the last byte.
+ */
+@Remote async readBytes(agent: Agent, path: string, range: WorkspaceByteRange, signal: AbortSignal): Promise<WorkspaceFileBytes>
+
+/**
+ * Report one regular file's identity, version, and size without its content.
+ * @param agent - target Agent resolved from the Session identity on the wire.
+ * @param path - workspace path, absolute or relative to the workspace root.
+ * @param signal - caller cancellation.
+ * @returns the file's absolute path, current version, and byte size.
+ */
+@Remote async stat(agent: Agent, path: string, signal: AbortSignal): Promise<WorkspaceFileStat>
+
+/**
+ * List the direct children of one directory inside the Agent's workspace.
+ * @param agent - target Agent resolved from the Session identity on the wire.
+ * @param path - workspace path, absolute or relative to the workspace root.
+ * @param signal - caller cancellation.
+ * @returns the directory's children in the backend's stable name order, bounded by the entry cap.
+ */
+@Remote async list(agent: Agent, path: string, signal: AbortSignal): Promise<WorkspaceDirectoryListing>
+
+/**
+ * Stream every `fs/observed` observation of a file inside the Agent's
+ * workspace. Only Agent filesystem operations report here; the OS is not
+ * watched.
+ * @param agent - target Agent resolved from the Session identity on the wire.
+ * @param signal - generation cancellation.
+ * @returns `ready` once the Host observation queue is active and the workspace
+ *   root is resolved, then queued and live observations in emission order.
+ */
+@Remote({ mode: 'stream' }) changes(agent: Agent, signal: AbortSignal): AsyncIterable<WorkspaceFileWatchFrame>
+```
+
+Types: [Agent](core.zh.md)
+
+Source: [`packages/api/workspace-files/src/index.ts`](../../packages/api/workspace-files/src/index.ts)
+
 <a id="ctxworkspaceregistry--workspaceregistry"></a>
 
 ### `ctx.workspaceRegistry` — `WorkspaceRegistry`
diff --git a/docs/user/develop/basic/publish.i18n.yaml b/docs/user/develop/basic/publish.i18n.yaml
index 99f24a191b..46d965c16c 100644
--- a/docs/user/develop/basic/publish.i18n.yaml
+++ b/docs/user/develop/basic/publish.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/basic/publish.md
-publish.md: 89a28e2e44a5171a3f5c48c003f5af5ec2e9e750
-publish.zh.md: 590fee6f035af3009e25bf3669ba4321951f7d07
+publish.md: 58abad728d5f684a72d855b77821a26a725de53f
+publish.zh.md: dbb49c0cd0e5ca26e42d17d94acb5f1601a27d15
diff --git a/docs/user/develop/basic/publish.md b/docs/user/develop/basic/publish.md
index 89a28e2e44..58abad728d 100644
--- a/docs/user/develop/basic/publish.md
+++ b/docs/user/develop/basic/publish.md
@@ -70,7 +70,7 @@ A profile directory holds two files:
 - `package.json` — the profile's out-of-tree plugin dependencies (managed by pnpm) plus the `dsh.profile` manifest with its ordered `bundles` list.
 - `cordis.patch.yml` — the user's own patch layer, applied after every bundle layer.
 
-You never write a profile manifest by hand: `dsh plugin` creates and maintains it. The next section shows the result.
+You never write a profile manifest by hand: `dsh --profile <name> --from-default-profile <template>` can create one from a shipped application template, while `dsh plugin` creates a base-backed profile and maintains its installed bundle list. The [CLI behavior reference](../../../../apps/cli/reference/README.md#profile-boot) owns the creation rules; the next section shows the plugin path.
 
 ## Install into a profile
 
diff --git a/docs/user/develop/basic/publish.zh.md b/docs/user/develop/basic/publish.zh.md
index 590fee6f03..dbb49c0cd0 100644
--- a/docs/user/develop/basic/publish.zh.md
+++ b/docs/user/develop/basic/publish.zh.md
@@ -70,7 +70,7 @@ profile 目录包含两个文件：
 - `package.json` — profile 的树外插件依赖（由 pnpm 管理），加上 `dsh.profile` manifest 及其有序的 `bundles` 列表。
 - `cordis.patch.yml` — 用户自己的 patch 层，在每个组合包层之后应用。
 
-profile manifest 从不需要手写：`dsh plugin` 负责创建和维护它。下一节展示其结果。
+profile manifest 从不需要手写：`dsh --profile <name> --from-default-profile <template>` 可以从随附应用模板创建 profile，`dsh plugin` 则创建一个以 base 为基础的 profile，并维护其中已安装的 bundle 列表。创建规则以 [CLI（命令行界面）行为参考](../../../../apps/cli/reference/README.zh.md#profile-boot)为准；下一节展示插件路径。
 
 ## 安装进 profile
 
diff --git a/package.json b/package.json
index 422cce1ce6..20d0c93390 100644
--- a/package.json
+++ b/package.json
@@ -57,6 +57,7 @@
     "test:expected": "vitest run --config vitest.expected.config.ts",
     "test:expected:refresh": "DSH_SNAPSHOT=refresh vitest run --config vitest.expected.config.ts",
     "test:issue-management": "node .github/issue-management/policy.test.mjs",
+    "test:request-review": "node --test .github/review-ownership/request-review.test.mjs",
     "test:snapshot": "vitest run --config vitest.snapshot.config.ts",
     "test:snapshot:record": "DSH_SNAPSHOT=record vitest run --config vitest.snapshot.config.ts --update",
     "test:snapshot:refresh": "DSH_SNAPSHOT=refresh vitest run --config vitest.snapshot.config.ts",
diff --git a/packages/api/README.i18n.yaml b/packages/api/README.i18n.yaml
index c47c67f406..ce98751e3d 100644
--- a/packages/api/README.i18n.yaml
+++ b/packages/api/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/api/README.md
-README.md: b4d8ddd84baa411a2675c95dda1701937e06fe6d
-README.zh.md: 5dff7a59219a539c75d7ab85d293cd5b389018ec
+README.md: 20455e6b5622ffd6e826b1d4b427838f96f6610f
+README.zh.md: 0294b1823e6a09cae4591b4c6081a546d8d60494
diff --git a/packages/api/README.md b/packages/api/README.md
index b4d8ddd84b..20455e6b56 100644
--- a/packages/api/README.md
+++ b/packages/api/README.md
@@ -31,6 +31,7 @@ The packages below provide the Remote layer; the package READMEs own the exhaust
 | [`session-controller/`](session-controller/README.md) | Owns Session commands, history streams, live control state, and Agent/Session identity policy. | `ctx.sessionController` / `ctx.remote.session` |
 | [`settings-controller/`](settings-controller/README.md) | Owns the configuration-surface reads and writes over the settings-domain seams. | `ctx.settingsController`, `ctx.credentialsController` / `ctx.remote.settings`, `ctx.remote.credentials` |
 | [`workspace-controller/`](workspace-controller/README.md) | Owns Workspace mutations and the complete Client Workspace projection. | `ctx.workspaceController` / `ctx.remote.workspace` |
+| [`workspace-files/`](workspace-files/README.md) | Owns bounded workspace file access — `stat`, paged `read`, `list`, and the agent-write `changes` feed — and the Client `file` resource provider over it. | `ctx.workspaceFiles` / `ctx.remote.workspaceFiles` |
 
 Remote calls run Client → Host over the application's shared Connection. API Gateway owns Remote transport, while the controller packages own Session, configuration-surface, and Workspace behavior. Feature packages register exact Connection Fetch routes for responses that do not fit Remote invocation, such as streamed downloads.
 
diff --git a/packages/api/README.zh.md b/packages/api/README.zh.md
index 5dff7a5921..0294b1823e 100644
--- a/packages/api/README.zh.md
+++ b/packages/api/README.zh.md
@@ -31,6 +31,7 @@ kind: "package-group"
 | [`session-controller/`](session-controller/README.zh.md) | 拥有 Session 命令、历史 stream、实时控制状态与 Agent/Session 身份策略。 | `ctx.sessionController` / `ctx.remote.session` |
 | [`settings-controller/`](settings-controller/README.zh.md) | 拥有 settings 域各 seam 之上的配置界面读写。 | `ctx.settingsController`、`ctx.credentialsController` / `ctx.remote.settings`、`ctx.remote.credentials` |
 | [`workspace-controller/`](workspace-controller/README.zh.md) | 拥有 Workspace 变更与完整 Client Workspace 投影。 | `ctx.workspaceController` / `ctx.remote.workspace` |
+| [`workspace-files/`](workspace-files/README.zh.md) | 拥有有界的工作区文件访问——`stat`、分页 `read`、`list` 与 agent 写入的 `changes` 流——以及其上的 Client `file` 资源提供者。 | `ctx.workspaceFiles` / `ctx.remote.workspaceFiles` |
 
 Remote 调用沿 Client → Host 方向运行在应用共享的 Connection 之上。API Gateway 拥有 Remote 传输，各 controller 包分别拥有 Session、配置界面与 Workspace 行为。流式下载等不适合 Remote 调用的响应由功能包注册精确的 Connection Fetch 路由。
 
diff --git a/packages/api/remotes/package.json b/packages/api/remotes/package.json
index f4540fdc25..3cfba6343d 100644
--- a/packages/api/remotes/package.json
+++ b/packages/api/remotes/package.json
@@ -82,6 +82,7 @@
     "@deepseek-ai/dsh-typert-protocol": "workspace:^",
     "@deepseek-ai/dsh-scope": "workspace:^",
     "@deepseek-ai/dsh-api-session-controller": "workspace:^",
+    "@deepseek-ai/dsh-api-workspace-files": "workspace:^",
     "zod": "^4.4.3"
   }
 }
diff --git a/packages/api/remotes/src/client/index.ts b/packages/api/remotes/src/client/index.ts
index cc917458dc..bc93c25cca 100644
--- a/packages/api/remotes/src/client/index.ts
+++ b/packages/api/remotes/src/client/index.ts
@@ -14,6 +14,7 @@ import sessionReferencesRemote from '@deepseek-ai/dsh-session-reference/remote'
 import subagentsRemote from '@deepseek-ai/dsh-subagent/remote'
 import sessionRemote from '@deepseek-ai/dsh-api-session-controller/remote'
 import workspaceRemote from '@deepseek-ai/dsh-api-workspace-controller/remote'
+import workspaceFilesRemote from '@deepseek-ai/dsh-api-workspace-files/remote'
 import type { ClientRemote } from '@deepseek-ai/dsh-api-gateway/client'
 
 export type { ClientRemote } from '@deepseek-ai/dsh-api-gateway/client'
@@ -33,6 +34,8 @@ export type {} from '@deepseek-ai/dsh-api-session-controller/remote'
 export type * from '@deepseek-ai/dsh-api-session-controller/types'
 export type {} from '@deepseek-ai/dsh-api-workspace-controller/remote'
 export type * from '@deepseek-ai/dsh-api-workspace-controller/types'
+export type {} from '@deepseek-ai/dsh-api-workspace-files/remote'
+export type * from '@deepseek-ai/dsh-api-workspace-files/types'
 export type { SessionJob as JobView } from '@deepseek-ai/dsh-api-session-controller/types'
 // The forwarded-event allowlist's selection seat: without it in the consumer's
 // compilation face `TypertRemoteEvent` is `never` and every `$on` call fails.
@@ -148,7 +151,7 @@ export async function apply(ctx: Context): Promise<() => Promise<void>> {
     for (const contribution of [
       agentPresetsRemote, commandsRemote, settingsControllerRemote, goalsRemote, llmRemote, dynamicRemote,
       pluginInventoryRemote, messageFeedbackRemote, fileUploadsRemote, sessionReferencesRemote,
-      subagentsRemote, sessionRemote, workspaceRemote,
+      subagentsRemote, sessionRemote, workspaceRemote, workspaceFilesRemote,
     ]) {
       disposers.push(await ctx.remote.$mount(contribution))
     }
diff --git a/packages/api/remotes/src/index.ts b/packages/api/remotes/src/index.ts
index 5a11bae49d..63b87bd0c5 100644
--- a/packages/api/remotes/src/index.ts
+++ b/packages/api/remotes/src/index.ts
@@ -20,6 +20,7 @@ import { API_REMOTE_FORWARDED_EVENTS } from './remote-events.ts'
 import type {} from '@deepseek-ai/dsh-commands/types'
 import type {} from '@deepseek-ai/dsh-cordis-host-runner/types'
 import type {} from '@deepseek-ai/dsh-credentials/types'
+import type {} from '@deepseek-ai/dsh-goal/types'
 import type {} from '@deepseek-ai/dsh-llm/types'
 import type {} from '@deepseek-ai/dsh-agent-presets/types'
 import type {} from '@deepseek-ai/dsh-settings/types'
diff --git a/packages/api/remotes/src/remote-events.ts b/packages/api/remotes/src/remote-events.ts
index 815a7b66a0..3147e7d3bc 100644
--- a/packages/api/remotes/src/remote-events.ts
+++ b/packages/api/remotes/src/remote-events.ts
@@ -23,6 +23,7 @@ export const API_REMOTE_FORWARDED_EVENTS = [
   { event: 'api-session/status', mode: 'emit' },
   { event: 'commands/change', mode: 'emit' },
   { event: 'credentials/reference-updated', mode: 'emit' },
+  { event: 'goal/activation-changed', mode: 'emit' },
   { event: 'cordis/request-run', mode: 'emit' },
   { event: 'cordis/request-run-resolved', mode: 'emit' },
   { event: 'cordis/dynamic-package', mode: 'emit' },
diff --git a/packages/api/remotes/tests/remote-events.host.spec.ts b/packages/api/remotes/tests/remote-events.host.spec.ts
index 1d2e8c235d..2e6b0ed7e1 100644
--- a/packages/api/remotes/tests/remote-events.host.spec.ts
+++ b/packages/api/remotes/tests/remote-events.host.spec.ts
@@ -104,6 +104,25 @@ describe('Remote event Host source', () => {
       value: { event: 'settings/document-updated', args: ['ui-theme', 1] },
     })
 
+    emitRaw(ctx, 'goal/activation-changed', [{
+      sessionId: 'session-1',
+      goal: { id: 'goal-1', revision: 1, activation: 'disarmed' },
+    }])
+    await expect(first.next()).resolves.toEqual({
+      done: false,
+      value: {
+        event: 'goal/activation-changed',
+        args: [{ sessionId: 'session-1', goal: { id: 'goal-1', revision: 1, activation: 'disarmed' } }],
+      },
+    })
+    await expect(second.next()).resolves.toEqual({
+      done: false,
+      value: {
+        event: 'goal/activation-changed',
+        args: [{ sessionId: 'session-1', goal: { id: 'goal-1', revision: 1, activation: 'disarmed' } }],
+      },
+    })
+
     const firstDone = first.next()
     firstAbort.abort(new Error('first Client disconnected'))
     emitRaw(ctx, 'commands/change', [])
diff --git a/packages/api/remotes/tsconfig.client.json b/packages/api/remotes/tsconfig.client.json
index 2be76de65a..589d5e92bd 100644
--- a/packages/api/remotes/tsconfig.client.json
+++ b/packages/api/remotes/tsconfig.client.json
@@ -25,7 +25,6 @@
     },
     {
       "path": "../../credentials/credentials"
-
     },
     {
       "path": "../../context/file-reference"
@@ -69,6 +68,9 @@
     {
       "path": "../session-controller/tsconfig.client.json"
     },
+    {
+      "path": "../workspace-files/tsconfig.client.json"
+    },
     {
       "path": "../settings-controller"
     },
diff --git a/packages/api/remotes/tsconfig.host.json b/packages/api/remotes/tsconfig.host.json
index c91c11baa2..99a3e5cc75 100644
--- a/packages/api/remotes/tsconfig.host.json
+++ b/packages/api/remotes/tsconfig.host.json
@@ -29,6 +29,9 @@
     {
       "path": "../../llm/llm"
     },
+    {
+      "path": "../../goal/goal"
+    },
     {
       "path": "../../preset/agent-presets"
     },
@@ -56,6 +59,9 @@
     {
       "path": "../session-controller/tsconfig.host.json"
     },
+    {
+      "path": "../workspace-files/tsconfig.host.json"
+    },
     {
       "path": "../workspace-controller/tsconfig.host.json"
     },
diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml
index 981e5f12ca..47da2a25c0 100644
--- a/packages/api/session-controller/README.i18n.yaml
+++ b/packages/api/session-controller/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/api/session-controller/README.md
-README.md: 6b56c4976b5ca66fbdbdb274bdf5bf8f38d52b1d
-README.zh.md: a9c53d37371e3280c5bc0ae21a93a511036a810d
+README.md: 8f7de90c2029117296bca02ce13dc5e769471434
+README.zh.md: b99589c4d7ed0a0105874bcbbd37dfd03927918d
diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md
index 6b56c4976b..8f7de90c20 100644
--- a/packages/api/session-controller/README.md
+++ b/packages/api/session-controller/README.md
@@ -25,7 +25,7 @@ English | [中文](README.zh.md)
 
 History pages and follow opening snapshots carry one `{ type: 'event', event: SessionWireEvent }` record per durable Session event. The Client retains each accepted record as one durable `SessionEventLikeEntry`; Assistant token boundaries remain inside the compact stream on `assistant/message` or `assistant/attempt`. Tool arguments, result content, failures, and `tool/result.data.meta` pass through unchanged; the controller does not resolve a Tool definition, run a presenter, or attach UI data.
 
-Each endpoint states its activation policy. List reads only stored headers and projection-cache rows: it never calls per-session stat or opens a cold Session body. A current-format cache identity may supply every list hint; a lifecycle-matching predecessor cache may supply only its version-compatible title as a stale display fact, never as an authoritative fold seed. Search, attachment, history pages, log following, skill discovery, and workspace-path opening can inspect persistence without activating an Agent; `canOpenWorkspacePath()` reports native-opening availability without addressing a Session. Queue mutation and cancellation require live state; model, rename, prompt, and file-reference operations may resolve or resume an ordinary Session. Prompt admission consumes opaque receipts from the injected [`fileUploads`](../../client/file-upload/README.md) Host service and resolves every same-Agent receipt before sending the complete ordered content list through `ctx.attachments`. Prompt retries whose `requestId` is already queued or logged return the original acceptance without inserting another message. Create and fork are the only operations that create a new Agent directly. The service applies one preset-aware resume policy and subagent ownership fence to its own methods and to the Typert Agent and Session lookups used by other Remote namespaces. Queue mutation has one narrow exception: a live child whose current projected identity is continuable and comes from its own non-seed suffix accepts the ordinary Edit, Remove, and QueueDock Steer actions across both inbox destinations. One-shot, missing, unknown, corrupt, seed-only, or cold children remain rejected without resume. The skill catalog uses a live Agent when present or the recorded preset's standing scope when cold, so listing never starts an Agent.
+Each endpoint states its activation policy. List reads only stored headers and projection-cache rows: it never calls per-session stat or opens a cold Session body. A current-format cache identity may supply every list hint; a lifecycle-matching predecessor cache may supply only its version-compatible title as a stale display fact, never as an authoritative fold seed. Search, attachment, history pages, log following, skill discovery, and workspace-path opening can inspect persistence without activating an Agent; `canOpenWorkspacePath()` reports native-opening availability without addressing a Session. Queue mutation and cancellation require live state; model, rename, prompt, and file-reference operations may resolve or resume an ordinary Session. Prompt rejects content with neither non-whitespace text nor an attachment before resolving the Agent or appending Session events; queue edits accept only non-empty text content. Prompt admission consumes opaque receipts from the injected [`fileUploads`](../../client/file-upload/README.md) Host service and resolves every same-Agent receipt before sending the complete ordered content list through `ctx.attachments`. Prompt retries whose `requestId` is already queued or logged return the original acceptance without inserting another message. Create and fork are the only operations that create a new Agent directly. The service applies one preset-aware resume policy and subagent ownership fence to its own methods and to the Typert Agent and Session lookups used by other Remote namespaces. Queue mutation has one narrow exception: a live child whose current projected identity is continuable and comes from its own non-seed suffix accepts the ordinary Edit, Remove, and QueueDock Steer actions across both inbox destinations. One-shot, missing, unknown, corrupt, seed-only, or cold children remain rejected without resume. The skill catalog uses a live Agent when present or the recorded preset's standing scope when cold, so listing never starts an Agent.
 
 The Client adapter exposes `SessionEventStream`, a Gateway `RemoteJournalStream` bound to one ordinary or direct-subagent address. It opens follow before the initial page, publishes only contiguous `replace`, `prepend`, `append`, and `settle-assistant` changes, and repairs reconnect or sequence gaps through a tail page. Backwards paging has two verbs: `loadOlder()` pulls one 50-message page, and `loadThrough(seq)` — the turn-jump loader — loops 200-message pages until the window covers the target seq, lowering a shared target on repeated calls, stopping on a page that makes no progress, and reporting busy through the same `loadingOlder` snapshot bit. The Web adapter explicitly opts into cursorless Assistant frames: each opening carries the active attempt's `startedAfterSeq`, `nextIndex`, and compact stream, and every stream member becomes a Client-only `assistant/live-chunk` entry ordered between durable cursors. The Host captures a follower-local arrival ordinal with that baseline and suppresses buffered frames at or before the cut; a replacement Agent may restart frame revision at one. A durable `assistant/message` or `assistant/attempt` arriving after an active opening stays staged only when its seq follows `startedAfterSeq` and its Turn and Step match; the matching end type, seq, and index publishes one named settlement delta that retires the attempt's transient rows and adds the durable entry while earlier same-step retries remain visible. Revision, dense-index, or settlement gaps for a known attempt reopen follow, while a controller that missed the start ignores unknown-attempt frames and publishes their durable settlement normally. An abandoned end publishes a settlement delta without a durable entry so its transient rows retire immediately. A durable gap-repair page has no Assistant baseline, so its held notification reopens follow once for a paired page and baseline. Every history record covers exactly its event seq. A business, persistence, or unresolved continuity failure terminates the stream, while only physical carrier loss selects automatic resumption. `SessionControlStream` is a Gateway `RemoteSnapshotStream`; every generation opens with a complete process-local baseline, so reconnect replaces queue, jobs, and projection state instead of treating transient values as durable events. For each inbox change, the Host publishes the projection frame first and derives the queue replacement from that same validated post-fold value, so listener registration order cannot produce a stale queue frame.Client Agent contexts provide the identity used by the independent [`fileUpload`](../../client/file-upload/README.md) service; Session objects expose lifecycle, prompt, queue, and history operations rather than file transfer.
 
diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md
index a9c53d3737..b99589c4d7 100644
--- a/packages/api/session-controller/README.zh.md
+++ b/packages/api/session-controller/README.zh.md
@@ -25,7 +25,7 @@ kind: "package-reference"
 
 历史页与 follow opening snapshot 为每个持久 Session event 携带一条 `{ type: 'event', event: SessionWireEvent }` record。Client 把每条已接受 record 保留为一个持久 `SessionEventLikeEntry`；Assistant token 边界保留在 `assistant/message` 或 `assistant/attempt` 的紧凑 stream 内。工具参数、结果内容、失败信息和 `tool/result.data.meta` 原样通过；controller 不解析 Tool definition、不运行 presenter，也不附加 UI 数据。
 
-每个 endpoint 都声明自己的激活策略。列表只读取持久化 header 与 projection cache row，绝不调用逐 Session stat 或打开冷 Session body。当前格式 cache identity 可以提供全部列表 hint；生命周期匹配的 predecessor cache 只能提供版本兼容的 title，作为可能过时的展示事实，绝不能作为权威 fold seed。搜索、附件、历史页、日志跟随、skill 发现和工作区路径打开可以在不激活 Agent 的情况下检查 persistence；`canOpenWorkspacePath()` 无需指定 Session 即可报告原生打开能力。queue 变更与取消要求 live 状态；模型、重命名、prompt 和文件引用操作可以解析或恢复普通 Session。prompt 准入从注入的 [`fileUploads`](../../client/file-upload/README.zh.md) Host 服务取得不透明凭证，在把完整有序内容列表交给 `ctx.attachments` 前解析每个属于同一 Agent 的凭证。`requestId` 已进入 queue 或日志时，prompt 重试直接返回原来的接受结果，不会重复插入消息。只有 create 与 fork 会直接创建新 Agent。该服务把同一套感知 preset 的恢复策略和 subagent ownership fence 同时用于自身方法，以及其他 Remote namespace 使用的 Typert Agent 与 Session lookup。Queue 变更只有一个狭窄例外：当前 projection identity 为 continuable 且来自自身非 seed suffix 的在线 child，可以在两个 inbox 目标上使用普通 Edit、Remove 与 QueueDock Steer action。One-shot、缺失、未知、损坏、仅含 seed identity 或冷 child 继续被拒绝，且不会恢复。skill 目录优先使用已有 live Agent，否则使用所记录 preset 的常驻 scope，因此列表查询绝不会启动 Agent。
+每个 endpoint 都声明自己的激活策略。列表只读取持久化 header 与 projection cache row，绝不调用逐 Session stat 或打开冷 Session body。当前格式 cache identity 可以提供全部列表 hint；生命周期匹配的 predecessor cache 只能提供版本兼容的 title，作为可能过时的展示事实，绝不能作为权威 fold seed。搜索、附件、历史页、日志跟随、skill 发现和工作区路径打开可以在不激活 Agent 的情况下检查 persistence；`canOpenWorkspacePath()` 无需指定 Session 即可报告原生打开能力。queue 变更与取消要求 live 状态；模型、重命名、prompt 和文件引用操作可以解析或恢复普通 Session。prompt 会在解析 Agent 或追加 Session event 前，拒绝既没有非空白文本也没有附件的 content；queue edit 只接受非空文本 content。prompt 准入从注入的 [`fileUploads`](../../client/file-upload/README.zh.md) Host 服务取得不透明凭证，在把完整有序内容列表交给 `ctx.attachments` 前解析每个属于同一 Agent 的凭证。`requestId` 已进入 queue 或日志时，prompt 重试直接返回原来的接受结果，不会重复插入消息。只有 create 与 fork 会直接创建新 Agent。该服务把同一套感知 preset 的恢复策略和 subagent ownership fence 同时用于自身方法，以及其他 Remote namespace 使用的 Typert Agent 与 Session lookup。Queue 变更只有一个狭窄例外：当前 projection identity 为 continuable 且来自自身非 seed suffix 的在线 child，可以在两个 inbox 目标上使用普通 Edit、Remove 与 QueueDock Steer action。One-shot、缺失、未知、损坏、仅含 seed identity 或冷 child 继续被拒绝，且不会恢复。skill 目录优先使用已有 live Agent，否则使用所记录 preset 的常驻 scope，因此列表查询绝不会启动 Agent。
 
 Client adapter 提供 `SessionEventStream`，即绑定到一个普通 Session 或 direct subagent address 的 Gateway `RemoteJournalStream`。它在读取首个 page 前打开 follow，只发布连续的 `replace`、`prepend`、`append` 与 `settle-assistant` 变更，并通过 tail page 修复重连或 seq 缺口。向后分页有两个动词：`loadOlder()` 拉一页 50 条 message，而 `loadThrough(seq)`——轮次跳转加载器——按 200 条 message 一页循环拉取直到窗口覆盖目标 seq，重复调用会下调共享目标，遇到无进展的页即停止，忙碌状态复用同一个 `loadingOlder` 快照位。Web adapter 显式选择接收无 cursor 的 Assistant frame：每个 opening 携带活跃 attempt 的 `startedAfterSeq`、`nextIndex` 与紧凑 stream，每个 stream member 都成为排在持久 cursor 之间的 Client-only `assistant/live-chunk` 条目。Host 会随该 baseline 捕获 follower 本地到达序号，并抑制该 cut 及之前的 buffered frame；replacement Agent 可以从 revision 一重新开始。活跃 opening 之后到达的持久 `assistant/message` 或 `assistant/attempt` 只有在其 seq 晚于 `startedAfterSeq` 且 Turn 与 Step 匹配时才会保持暂存；匹配的 end type、seq 与 index 会发布一个具名 settlement delta，删除该 attempt 的瞬态 row、加入持久条目，并保留同一步骤中更早的 retry。已知 attempt 的 revision、密集 index 或 settlement 缺口会重新打开 follow；若 controller 错过 start，则忽略 unknown-attempt frame，并正常发布其持久 settlement。Abandoned end 会发布不含持久条目的 settlement delta，使瞬态 row 立即退出。持久缺口修复 page 不携带 Assistant baseline，因此 held notification 会重新打开 follow 一次，以取得配对的 page 与 baseline。每条历史 record 只覆盖自身的 event seq。业务、persistence 或无法恢复的连续性错误会终止 stream，只有物理载体断开才触发自动恢复。`SessionControlStream` 是 Gateway `RemoteSnapshotStream`；每代都以完整的进程本地 baseline 开始，因此重连会替换 queue、jobs 和 projection 状态，而不会把瞬态值当作 durable event。每次 inbox 变更时，Host 会先发布 projection frame，再从同一份已校验的折叠后值派生 queue replacement，因此监听器注册顺序不会产生陈旧的 queue frame。Client Agent context 提供独立 [`fileUpload`](../../client/file-upload/README.zh.md) 服务使用的身份；Session 对象提供生命周期、prompt、queue 与历史操作，不提供文件传输。
 
diff --git a/packages/api/session-controller/src/commands.ts b/packages/api/session-controller/src/commands.ts
index f3fa473e6c..35fc113408 100644
--- a/packages/api/session-controller/src/commands.ts
+++ b/packages/api/session-controller/src/commands.ts
@@ -58,6 +58,14 @@ interface SessionReadState {
   readonly events: readonly SessionEvent[]
 }
 
+type PromptContentCandidate =
+  | SessionPromptRequest['content'][number]
+  | Extract<SessionUpdateQueueRequest['action'], { readonly kind: 'edit' }>['content'][number]
+
+function hasPromptContent(content: readonly PromptContentCandidate[]): boolean {
+  return content.some(part => part.type !== 'text' || part.text.trim().length > 0)
+}
+
 /** Implements Session business commands delegated by the Session Controller Remote service. */
 export class SessionCommandController {
   /**
@@ -287,11 +295,18 @@ export class SessionCommandController {
   }
 
   /**
-   * Admit one browser prompt after explicit Agent resume and image validation.
+   * Reject empty content, then admit one prompt after Agent and attachment validation.
    * @param request - Session identity, prompt content, source metadata, and delivery mode.
    * @returns acknowledgement that the Agent accepted the prompt.
    */
   async prompt(request: SessionPromptRequest): Promise<SessionPromptValue> {
+    if (!hasPromptContent(request.content)) {
+      throw new RemoteError(
+        'gateway/bad-request',
+        'prompt content must include non-whitespace text or an attachment',
+        {},
+      )
+    }
     const clientTimeZone = request.clientTimeZone === undefined
       ? undefined
       : canonicalClientTimeZone(request.clientTimeZone)
@@ -407,13 +422,21 @@ export class SessionCommandController {
    * @returns acknowledgement that the queue mutation was applied.
    */
   updateQueue(request: SessionUpdateQueueRequest): SessionUpdateQueueValue {
-    if (request.action.kind === 'edit'
-      && request.action.content.some(block => block.type !== 'text')) {
-      throw new RemoteError(
-        'session/attachment-invalid',
-        'queue edits accept text content only',
-        { reason: 'QUEUE_EDIT_NON_TEXT' },
-      )
+    if (request.action.kind === 'edit') {
+      if (request.action.content.some(block => block.type !== 'text')) {
+        throw new RemoteError(
+          'session/attachment-invalid',
+          'queue edits accept text content only',
+          { reason: 'QUEUE_EDIT_NON_TEXT' },
+        )
+      }
+      if (!hasPromptContent(request.action.content)) {
+        throw new RemoteError(
+          'gateway/bad-request',
+          'queue edit content must include non-whitespace text',
+          {},
+        )
+      }
     }
     const agent = this.ctx.agents.get(request.sessionId)
     if (agent === undefined) {
diff --git a/packages/api/session-controller/src/types.ts b/packages/api/session-controller/src/types.ts
index f421660088..9444fc694d 100644
--- a/packages/api/session-controller/src/types.ts
+++ b/packages/api/session-controller/src/types.ts
@@ -151,7 +151,11 @@ export interface ModelCatalog {
 
 /** One client-requested mutation of a still-pending queue item. */
 export type QueueAction =
-  | { readonly kind: 'edit'; readonly content: readonly ContentBlock[] }
+  | {
+    readonly kind: 'edit'
+    /** Non-empty text-only replacement content. */
+    readonly content: readonly ContentBlock[]
+  }
   | { readonly kind: 'remove' }
   | { readonly kind: 'steer' }
 
@@ -308,6 +312,7 @@ export interface SessionPromptRequest {
   readonly requestId: SessionRequestId
   readonly sessionId: SessionId
   readonly mode: 'queue' | 'steer'
+  /** At least one non-whitespace text part or attachment. */
   readonly content: readonly PromptContentPart[]
   readonly clientTimeZone?: string
 }
diff --git a/packages/api/session-controller/tests/commands-queue-attachment.host.spec.ts b/packages/api/session-controller/tests/commands-queue-attachment.host.spec.ts
index e96a3b128b..6cdf3702f9 100644
--- a/packages/api/session-controller/tests/commands-queue-attachment.host.spec.ts
+++ b/packages/api/session-controller/tests/commands-queue-attachment.host.spec.ts
@@ -133,6 +133,14 @@ describe('Session queue commands', () => {
         }],
       },
     })), 'session/attachment-invalid')
+    for (const content of [[], [{ type: 'text' as const, text: ' \t\n' }]]) {
+      await expectFailure(Promise.resolve().then(() => controller.updateQueue({
+        sessionId: agent.id,
+        itemId: queued.id,
+        action: { kind: 'edit', content },
+      })), 'gateway/bad-request')
+    }
+    expect(inbox.nextTurn[0]?.content).toEqual([{ type: 'text', text: 'queued' }])
     await expectFailure(Promise.resolve().then(() => controller.updateQueue({
       sessionId: SessionId('missing'), itemId: queued.id, action: { kind: 'remove' },
     })), 'session/queue-item-not-found')
diff --git a/packages/api/session-controller/tests/session-cold.host.spec.ts b/packages/api/session-controller/tests/session-cold.host.spec.ts
index 088fefad1c..eaca25062f 100644
--- a/packages/api/session-controller/tests/session-cold.host.spec.ts
+++ b/packages/api/session-controller/tests/session-cold.host.spec.ts
@@ -17,6 +17,7 @@ import { snapshotSubagentDescriptor } from '@deepseek-ai/dsh-subagent'
 import { createInboxStub } from '@deepseek-ai/dsh-agent-loop-testkit'
 import type { Agent, Inbox } from '@deepseek-ai/dsh-agent'
 import type { SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import AttachmentStore from '@deepseek-ai/dsh-attachment'
 import type { SessionPromptRequest, SessionRequestId } from '../src/types.ts'
 import {
   SessionPersistenceRevision,
@@ -678,6 +679,101 @@ describe('degenerate composition (no persistence, no factory)', () => {
 })
 
 describe('sessions.prompt synchronous rejection', () => {
+  it('rejects content without non-whitespace text or an attachment before delivery or Session events', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    const session = ctx.sessions.create(sid('session-empty-prompt'))
+    const followup = vi.fn()
+    const steer = vi.fn()
+    ctx.agents.register({
+      id: session.id,
+      session,
+      inbox: inboxFor(),
+      status: 'idle',
+      ctx,
+      followup,
+      steer,
+    } as unknown as Agent)
+    const savedImage = {
+      attachmentId: 'accepted-image',
+      mediaType: 'image/png' as const,
+      bytes: 1,
+      width: 1,
+      height: 1,
+    }
+    const saveImages = vi.fn(() => Promise.resolve([savedImage]))
+    ctx.provide('attachments', Object.setPrototypeOf(
+      { saveImages },
+      AttachmentStore.prototype,
+    ) as never)
+    ctx.provide('llm', {
+      listProviders: () => [{ id: 'p', name: 'Provider' }],
+      resolveModelInfo: () => Promise.resolve({
+        provider: 'p', id: 'm', name: 'Model', inputModalities: ['text', 'image'],
+      }),
+    } as never)
+    const remote = createSessionTestRemote(ctx, {
+      defaultModelSelection: () => ({ provider: 'p', model: 'm' }),
+      cwd: '/tmp',
+    })
+    const initialEvents = session.snapshotEvents()
+    const rejectedContent: readonly SessionPromptRequest['content'][] = [
+      [],
+      [{ type: 'text', text: '' }],
+      [{ type: 'text', text: ' \t\n' }, { type: 'text', text: '' }],
+    ]
+
+    for (const [index, content] of rejectedContent.entries()) {
+      const response = await remote.prompt(promptRequest({
+        sessionId: session.id,
+        mode: index === 1 ? 'steer' : 'queue',
+        content,
+      }))
+      expect(response).toMatchObject({
+        ok: false,
+        error: {
+          code: 'gateway/bad-request',
+          message: 'prompt content must include non-whitespace text or an attachment',
+          details: {},
+        },
+      })
+    }
+    expect(followup).not.toHaveBeenCalled()
+    expect(steer).not.toHaveBeenCalled()
+    expect(session.snapshotEvents()).toEqual(initialEvents)
+
+    const queued = await remote.prompt(promptRequest({
+      sessionId: session.id,
+      mode: 'queue',
+      content: [{ type: 'text', text: ' queued ' }],
+    }))
+    const steered = await remote.prompt(promptRequest({
+      sessionId: session.id,
+      mode: 'steer',
+      content: [{ type: 'text', text: 'steered' }],
+    }))
+    const imageQueued = await remote.prompt(promptRequest({
+      sessionId: session.id,
+      mode: 'queue',
+      content: [{ type: 'image', mediaType: 'image/png', data: 'AQ==' }],
+    }))
+    expect(queued).toMatchObject({ ok: true, value: { accepted: true } })
+    expect(steered).toMatchObject({ ok: true, value: { accepted: true } })
+    expect(imageQueued).toMatchObject({ ok: true, value: { accepted: true } })
+    expect(followup).toHaveBeenCalledWith(expect.objectContaining({
+      content: [{ type: 'text', text: ' queued ' }],
+    }))
+    expect(steer).toHaveBeenCalledWith(expect.objectContaining({
+      content: [{ type: 'text', text: 'steered' }],
+    }))
+    expect(saveImages).toHaveBeenCalledOnce()
+    expect(followup).toHaveBeenCalledWith(expect.objectContaining({
+      content: [{ type: 'image', attachment: savedImage }],
+    }))
+    await ctx.fiber.dispose()
+  })
+
   it('maps a synchronous send throw (disposed/invalid input) to agent-busy with the reason attached', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
diff --git a/packages/api/workspace-files/README.i18n.yaml b/packages/api/workspace-files/README.i18n.yaml
new file mode 100644
index 0000000000..80c6207706
--- /dev/null
+++ b/packages/api/workspace-files/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/api/workspace-files/README.md
+README.md: f7442845bc3c592bee0c59817a72ad07c8c91a2a
+README.zh.md: 4acd022335ee7c276aca00d66e177c19b060df0a
diff --git a/packages/api/workspace-files/README.md b/packages/api/workspace-files/README.md
new file mode 100644
index 0000000000..f7442845bc
--- /dev/null
+++ b/packages/api/workspace-files/README.md
@@ -0,0 +1,154 @@
+---
+description: "Workspace file service for the web GUI: paged read, byte windows, stat, directory listing, and the Agent-write change feed inside the Session workspace root, exposed as the workspaceFiles Remote namespace."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-api-workspace-files
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`@deepseek-ai/dsh-api-workspace-files` owns the Host `ctx.workspaceFiles` service and the generated Client `workspaceFiles` Remote namespace: `read` returns one page of lines from a UTF-8 text file, `readBytes` returns one window of raw bytes from any regular file, `stat` returns a file's version and size without its content, `list` returns one directory's direct children, and `changes` streams every filesystem observation an Agent makes inside the Session's workspace root. All five run over the composed `ctx.fs` and confine themselves to the workspace root the sandbox policy resolves for the addressed Session; the filesystem backend's own cwd never decides. Client packages reach the namespace through the [`api-remotes`](../../api/remotes/README.md) assembly. The package's `./client` export registers the `file` resource provider that turns `stat` and `changes` into live file metadata for `useResource<'file'>`; the Sidebar's file tree tab lists directories through `list`.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount the package beside `dsh-fs`, `dsh-sandbox-policy`, and the Typert Gateway; the bundle does so right after the Session Controller. Every method takes the Session identity on the wire, so a Client calls `remote.workspaceFiles.read(agent, path, range, signal)`, `stat(agent, path, signal)`, `readBytes(agent, path, range, signal)`, `list(agent, path, signal)`, or `changes(agent, signal)` and never names a root itself.
+
+| Method | Returns | Purpose |
+|---|---|---|
+| `stat(path)` | `WorkspaceFileStat { absolutePath, version, bytes? }` | Identity, version, and size of one regular file, without content |
+| `read(path, { offset?, limit? })` | `WorkspaceFileText` = stat + `{ offset, text, lines, eof }` | One window of lines from a UTF-8 text file; `lines` counts them, so one empty line and a page past the end read differently |
+| `readBytes(path, { offset?, length? })` | `WorkspaceFileBytes` = stat + `{ offset, data, eof }` | One window of raw bytes from any regular file, base64-encoded |
+| `list(path)` | `WorkspaceDirectoryListing { path, entries, truncated }` | Direct children of one directory |
+| `changes()` | stream of `WorkspaceFileWatchFrame` | Subscription readiness, then Agent observations inside the workspace root |
+
+### Addressing and paths
+
+`read`, `stat`, and `list` accept a workspace path that is absolute or relative to the Session's workspace root. Two path vocabularies leave the service, and each method uses exactly one: `read`, `stat`, and `changes` report a file as its absolute path in the filesystem's execution world, symlinks resolved (`WorkspaceFileStat.absolutePath`, `WorkspaceFileChange.absolutePath`), because their consumer is the Client resource system, which follows changes by that path; `list` reports the listed directory as a workspace path relative to the root — empty for the root itself — because its consumer is a tree rooted there, and a child's path is that value joined with the entry name by `/`.
+
+### Pages
+
+`read` returns one line window, never the whole file. `range.offset` is the 1-based first line and defaults to 1; `range.limit` is the largest number of lines on the page and defaults to `maxLines`, which it may not exceed — a larger limit, or an offset or limit that is not a positive integer, is a `gateway/bad-request`. Lines end at `\n`, and a final `\n` terminates the last line rather than starting an empty one, so a two-line file has two lines. The page's `text` joins its lines with `\n` and carries no terminator after the last; `eof` is true when the page includes the file's last line, and an offset past the end returns an empty page with `eof` true. Every page also carries the file's `version` from the stat that preceded it, so a consumer can tell a fresh page from a stale one, and `bytes`, the complete file's size when the backend reports it. The service reads the file only up to the first character past the page, so a very large file costs one page of memory per request.
+
+### Byte windows
+
+`read` pages by lines and never by bytes; a byte window is `readBytes`. `range.offset` is the 0-based first byte and defaults to 0; `range.length` is the largest number of bytes in the window and defaults to `maxBytes`, which it may not exceed — a longer window fails with `too-large` instead of arriving shortened, and an offset or length that is not an integer in range is a `gateway/bad-request`. The window comes back as base64 `data`, shorter than `length` at the end of the file and empty at or past it; `eof` is true when the window includes the file's last byte. Nothing is decoded and nothing is refused as binary, so an image or a NUL-laden file reads where `read` fails with `not-text`. The same `version` and `bytes` ride along as on a page.
+
+### The four gates
+
+Every read, stat, and listing passes four gates in this order. First, `lstat` inspects the path itself before anything follows it: a symlink, wherever it points, fails `read` and `stat` with `not-regular-file` and `list` with `not-directory`, each carrying the entry's `kind`. Second, containment: the path resolves to a target and `ctx.fs.contains(root, target)` decides, so a `..` traversal or an absolute path outside the root fails with `outside-workspace` — never a string-prefix comparison, which cannot see a realpath that leaves the root. Third, the caps: a page whose text exceeds `maxBytes` fails with `too-large` instead of arriving shortened — the file itself has no size cap — while `maxEntries` cuts a listing and sets `truncated`. Fourth, text: content that is not UTF-8 up to the end of the page, or a page that carries a NUL byte, fails with `not-text`; bytes past the page are not inspected. A missing path fails with `not-found`; an empty path is a `gateway/bad-request`.
+
+### The change feed
+
+`changes` is a `stream` Remote. A generation registers its observation queue and resolves the Session workspace root before yielding `{ kind: 'ready' }`. It then yields `{ kind: 'change', change }`, where `change` is `{ absolutePath, version }` for a present file or `{ absolutePath, absent: true }` for one observed gone. The source is `fs/observed`, filtered to targets inside that root; the operating system is not watched. Observations after the generation's first pull are queued, including while the root resolves. The generation ends on cancellation or plugin disposal.
+
+### Configuration
+
+| Field | Default | Meaning |
+|---|---|---|
+| `maxBytes` | `2097152` (2 MiB) | Inclusive byte cap on one page's text and on one byte window; a larger page or window fails |
+| `maxLines` | `5000` | Default and largest page size in lines; a larger `limit` is refused |
+| `maxEntries` | `2000` | Cap on returned directory entries; the rest is dropped and reported cut |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-api-workspace-files) is the exhaustive source for every accepted field and its JSDoc.
+
+### Failures
+
+Each failure is one `RemoteError` code with typed details, declared in [`src/types.ts`](src/types.ts): `workspace-file/not-found`, `workspace-file/outside-workspace`, `workspace-file/too-large` (with `limit`, the page and window cap), `workspace-file/not-text`, `workspace-file/not-regular-file` (`kind`: `directory`, `symlink`, or `other`), and `workspace-file/not-directory` (`kind`: `file`, `symlink`, or `other`). Callers branch on the code, never on message text.
+
+### Client file resources
+
+The browser export registers the `file` provider into `ctx.resources` and requires `resources`, `remote`, `remote.workspaceFiles`, and `sessions`. The bundle's single `workspace-files` row supplies both faces; the Client has no separate configuration. A component follows a file through its standard `useResource<'file'>(address)` prop and reads `{ absolutePath, version, bytes?, changed }`; content is fetched separately through the paged methods.
+
+A `session/<sessionId>/<path>` resource address sends its relative path unchanged to the Host, which resolves and confines it against that Session's workspace root; the Client needs no Session `cwd`. An `absolute/<path>` address reads through the current Session. Both use the `dsh-resource://file/` grammar in [workspace-path](../../util/workspace-path/README.md). An absolute address without a current Session produces `workspace-file/unknown-workspace`; an unsupported address produces `workspace-file/unsupported-address`. These Client failures end the stream and make reload a no-op.
+
+The provider waits for the Host's `ready` frame before its first `stat`, queues changes during the read, then binds the follower to `stat.absolutePath`. Both queued and live changes match that Host-returned path. A new write version raises `changed` while retaining the last byte size; duplicate versions are ignored. An absent notice or reload re-stats the file. A failed stat keeps the address followed; a later write or reload can recover it, and any Session write can trigger a retry before the first successful path binding. Reload clears `changed`; a Host-triggered re-stat keeps it raised. Frames are `RemoteResult` values, and programming exceptions remain uncaught.
+
+One supervised `changes` stream serves every followed file in a Session. Followers match absolute paths with backslashes normalized to slashes. Carrier loss reconnects through the Gateway supervisor; a Host-ended or terminally failed feed ends its followers and leaves their last metadata readable until reopened. The last follower leaving disposes the stream, a successor waits for that disposal, and plugin teardown awaits all pending closes. The provider declares `ResourceProtocolMap.file`; the text preview declares its Sidebar line-navigation parameters.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+### Design concept
+
+Reads through `ctx.fs` are deliberately unconfined — the sandboxing backend fences writes and edits only — so every constraint here is the service's own. A page is cut from `streamText`, which decodes and rejects non-UTF-8 chunk by chunk: the cutter counts lines before the window without keeping them, admits each in-window segment against the byte cap before buffering it, and returns at the first character past the window, so neither a huge file nor one giant line can hold more than a page in memory; the NUL scan then runs on the page. One `stat` before the stream names the version and size the page reports. The path gate runs before containment on purpose: `lstat` is path-shaped and sees the link, while `resolve` follows it; the price is that an entry outside the root reports its own kind before its position.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | `WorkspaceFiles`: the `workspaceFiles` service and Remote namespace, `Config`, the gates, the page cutter, `read`, `readBytes`, `stat`, `list` |
+| [`src/changes.ts`](src/changes.ts) | `WorkspaceChangeFeed`: `fs/observed` subscription and one queue per open `changes` generation |
+| [`src/types.ts`](src/types.ts) | Wire types and the `RemoteErrorDetailsMap` codes, published as `./types` for Client packages |
+| [`src/client/index.ts`](src/client/index.ts), [`provider.ts`](src/client/provider.ts), [`change-feed.ts`](src/client/change-feed.ts) | Browser plugin, file metadata, and per-Session change feed |
+| [`src/client/types.ts`](src/client/types.ts), [`remote.ts`](src/client/remote.ts) | Resource values, parameters, Client error codes, and generated Remote types |
+| — | No runtime invariant companion is published; every Host answer is derived from `ctx.fs` and the sandbox policy at call time. |
+
+Typert generates the Host and Client Remote artifacts exposed by `./typert` and `./remote`.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Filesystem capability](../../fs/fs/README.md) — the `ctx.fs` contract this service reads through, including `fs/observed` and `readByteRange`.
+- [Sandbox policy](../../sandbox/sandbox-policy/README.md) — where the Session's workspace root comes from.
+- [Remote assembly](../../api/remotes/README.md) — how Client packages reach the `workspaceFiles` namespace.
+- [Client resources](../../client/resources/README.md) — the resource model, `useResource`, pins, and provider lifetime.
+- [Workspace path helpers](../../util/workspace-path/README.md) — `fileAddressFor` and `parseFileAddress`, the `dsh-resource://file/…` address grammar both ends share.
+- [Sidebar text preview](../../client/ui-sidebar-textpreview/README.md) — the tab type that follows a file through the `file` provider and reads its pages.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as this package registers no tool, contributes no prompt section, and appends no session event.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Agent writes only** — `changes` relays `fs/observed` emissions; a file changed by a subprocess, a shell command, or the user's editor produces no frame.
+- **Kind before position** — an entry outside the workspace whose type already disqualifies it reports `not-regular-file` or `not-directory`, not `outside-workspace`, because the path gate precedes containment.
+- **No total line count** — a page reports `eof`, not how many lines follow; a consumer that needs the total pages to the end or estimates from `bytes`.
+- **One giant line has no page** — a single line above `maxBytes` fails `too-large` at every window that includes it, because pages are cut by lines, not bytes.
+- **Version precedes content** — the `version` on a page is the stat's, taken before the stream; a write landing between the two leaves the page one version behind, which the next `changes` frame reports.
+- **Unbounded generation queue** — a `changes` generation buffers every contained observation until its consumer pulls; a stalled consumer grows Host memory for the life of the stream.
+- **`maxEntries` bounds the answer, not the listing** — `list` asks `ctx.fs.listDir` for every child and cuts the array afterwards, so a directory far above the cap still costs the Host the whole listing (on `fs-local`, one stat per child); bounding that work needs a limit on the filesystem seam's `listDir`.
+- **Dead feeds retain metadata** — after the Host ends `changes` or the stream fails terminally, open values retain their last state until reopened; reload does not reopen the stream.
+- **Reload is shared by path** — a reload re-stats every follower of that absolute path in the Session and clears their `changed` flags, including readers that did not reload their content. Per-record reload delivery remains deferred.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>
diff --git a/packages/api/workspace-files/README.zh.md b/packages/api/workspace-files/README.zh.md
new file mode 100644
index 0000000000..4acd022335
--- /dev/null
+++ b/packages/api/workspace-files/README.zh.md
@@ -0,0 +1,154 @@
+---
+description: "面向 Web GUI 的工作区文件服务：在 Session 工作区根内做分页读取、字节窗口、stat、目录列举与 Agent 写入变更流，以 workspaceFiles Remote 命名空间暴露。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-api-workspace-files
+
+[English](README.md) | 中文
+
+## 概述
+
+`@deepseek-ai/dsh-api-workspace-files` 拥有 Host 侧 `ctx.workspaceFiles` 服务与生成的 Client 侧 `workspaceFiles` Remote 命名空间：`read` 返回一个 UTF-8 文本文件的一页行，`readBytes` 返回任意普通文件的一个原始字节窗口，`stat` 返回文件的版本与大小而不带内容，`list` 返回一个目录的直接子项，`changes` 流式推送 Agent 在 Session 工作区根内做出的每一次文件系统观察。五者都经组合后的 `ctx.fs` 运行，并把自己限定在沙箱策略为被寻址 Session 解析出的工作区根内；文件系统后端自己的 cwd 从不参与判定。Client 包经 [`api-remotes`](../../api/remotes/README.zh.md) 装配触达该命名空间。本包的 `./client` 导出注册 `file` 资源提供者，把 `stat` 与 `changes` 变成 `useResource<'file'>` 的实时文件元数据；Sidebar 的文件树 tab 经 `list` 列举目录。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+把本包与 `dsh-fs`、`dsh-sandbox-policy` 和 Typert Gateway 一起挂载；bundle 把它紧随 Session Controller 之后挂载。每个方法都在线路上携带 Session 身份，Client 调用 `remote.workspaceFiles.read(agent, path, range, signal)`、`stat(agent, path, signal)`、`list(agent, path, signal)` 或 `changes(agent, signal)`，从不自己指定根。
+
+| 方法 | 返回 | 用途 |
+|---|---|---|
+| `stat(path)` | `WorkspaceFileStat { absolutePath, version, bytes? }` | 一个普通文件的身份、版本与大小，不含内容 |
+| `read(path, { offset?, limit? })` | `WorkspaceFileText` = stat + `{ offset, text, lines, eof }` | UTF-8 文本文件的一个行窗口；`lines` 计行数，使单个空行与越过文件末尾的页可区分 |
+| `readBytes(path, { offset?, length? })` | `WorkspaceFileBytes` = stat + `{ offset, data, eof }` | 任意普通文件的一个原始字节窗口，base64 编码 |
+| `list(path)` | `WorkspaceDirectoryListing { path, entries, truncated }` | 一个目录的直接子项 |
+| `changes()` | `WorkspaceFileWatchFrame` 流 | 订阅就绪确认，随后为工作区根内的 Agent 观察 |
+
+### 寻址与路径
+
+`read`、`stat` 与 `list` 接受工作区路径，可以是绝对路径，也可以是相对于 Session 工作区根的路径。离开服务的路径词汇有两套，每个方法只用其中一套：`read`、`stat` 与 `changes` 以文件系统执行环境中的绝对路径报告文件，符号链接已解析（`WorkspaceFileStat.absolutePath`、`WorkspaceFileChange.absolutePath`），因为其消费方是 Client 资源系统，它按这条路径跟随变更；`list` 以相对于根的工作区路径报告被列举目录——根自身为空串——因为其消费方是一棵以根为起点的树，子项路径就是该值与条目名以 `/` 连接。
+
+### 分页
+
+`read` 返回一个行窗口，绝不返回整个文件。`range.offset` 是 1 起算的首行，缺省为 1；`range.limit` 是该页最多的行数，缺省为 `maxLines` 且不得超过它——更大的 limit，或不是正整数的 offset / limit，都是 `gateway/bad-request`。行以 `\n` 结束，末尾的 `\n` 是最后一行的终止符而不是再起一空行，所以两行文件就是两行。页的 `text` 以 `\n` 连接各行，最后一行之后不带终止符；`eof` 在该页含文件最后一行时为 true，offset 越过末尾则返回空页且 `eof` 为 true。每页还带上前置 stat 得到的文件 `version`，消费方据此分辨新页与旧页，以及 `bytes`——后端能报告时的整文件大小。服务只把文件读到该页之后的第一个字符为止，所以再大的文件每次请求也只占一页内存。
+
+### 字节窗口
+
+`read` 按行分页，绝不按字节；字节窗口走 `readBytes`。`range.offset` 是 0 起算的首字节，缺省为 0；`range.length` 是窗口最多的字节数，缺省为 `maxBytes` 且不得超过它——更长的窗口以 `too-large` 失败而不是被截短，不是整数或越界的 offset / length 则是 `gateway/bad-request`。窗口以 base64 的 `data` 返回，到文件末尾时短于 `length`，位于或越过末尾时为空；窗口含文件最后一个字节时 `eof` 为 true。不做任何解码，也不按二进制拒绝，因此图片或含 NUL 的文件在 `read` 以 `not-text` 失败之处仍可读出。与页一样附带同一 `version` 与 `bytes`。
+
+### 四道关
+
+每次读取、stat 与列举依次过四道关。第一，`lstat` 在跟随任何东西之前检查路径本身：符号链接不论指向哪里，`read` 与 `stat` 都以 `not-regular-file`、`list` 都以 `not-directory` 拒绝，并带上条目的 `kind`。第二，包含判定：路径解析为目标后由 `ctx.fs.contains(root, target)` 裁决，所以 `..` 上溯或根外绝对路径都以 `outside-workspace` 失败——绝不做字符串前缀比较，那看不见离开根的 realpath。第三，上限：文本超过 `maxBytes` 的页以 `too-large` 失败而不是被截短送达——文件本身没有大小上限——`maxEntries` 则截断列举并置 `truncated`。第四，文本：到该页末尾为止非 UTF-8 的内容，或含 NUL 字节的页，以 `not-text` 失败；页之后的字节不检查。路径不存在以 `not-found` 失败；空路径是 `gateway/bad-request`。
+
+### 变更流
+
+`changes` 是 `stream` 模式的 Remote。一代流注册观察队列并解析 Session 工作区根之后，才产出 `{ kind: 'ready' }`。随后产出 `{ kind: 'change', change }`，其中 `change` 对存在的文件为 `{ absolutePath, version }`，对被观察到已消失的文件为 `{ absolutePath, absent: true }`。来源是按该根内目标过滤的 `fs/observed`；操作系统并未被监视。一代流首次拉取后的观察都会排队，包括解析根期间的观察。流在取消或插件释放时结束。
+
+### 配置
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `maxBytes` | `2097152`（2 MiB） | 单页文本与单个字节窗口的字节上限（含）；更大的页或窗口失败 |
+| `maxLines` | `5000` | 页大小的缺省值与上限（行）；更大的 `limit` 被拒绝 |
+| `maxEntries` | `2000` | 返回目录条目数上限；其余丢弃并报告截断 |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-api-workspace-files)是每个可接受字段及其 JSDoc 的完备来源。
+
+### 失败
+
+每种失败都是一个带类型化 details 的 `RemoteError` 代码，声明于 [`src/types.ts`](src/types.ts)：`workspace-file/not-found`、`workspace-file/outside-workspace`、`workspace-file/too-large`（带 `limit`，即页与窗口上限）、`workspace-file/not-text`、`workspace-file/not-regular-file`（`kind` 为 `directory`、`symlink` 或 `other`）以及 `workspace-file/not-directory`（`kind` 为 `file`、`symlink` 或 `other`）。调用方按代码分支，绝不按消息文本。
+
+### Client 文件资源
+
+浏览器导出向 `ctx.resources` 注册 `file` 提供者，要求 `resources`、`remote`、`remote.workspaceFiles` 和 `sessions` 在场。bundle 中单个 `workspace-files` 条目供应两面；Client 没有单独配置。组件经标准 prop `useResource<'file'>(address)` 跟随文件，读取 `{ absolutePath, version, bytes?, changed }`；内容通过分页方法另行获取。
+
+`session/<sessionId>/<path>` 资源地址把相对路径原样发送给 Host，由 Host 按该 Session 的工作区根解析并检查包含关系；Client 不需要 Session `cwd`。`absolute/<path>` 地址经当前 Session 读取。两者都使用[workspace-path](../../util/workspace-path/README.zh.md)规定的 `dsh-resource://file/` 语法。没有当前 Session 的绝对地址产生 `workspace-file/unknown-workspace`；不支持的地址产生 `workspace-file/unsupported-address`。这些 Client 失败会结束流，并使刷新无动作。
+
+提供者等到 Host 的 `ready` 帧后才发首次 `stat`，读取期间将变更排队，随后将跟随者绑定到 `stat.absolutePath`。排队与实时变更都按该 Host 返回路径匹配。新的写入版本置 `changed`，并保留最近的字节大小；重复版本被忽略。消失通知或刷新会重新 stat 文件。stat 失败后仍跟随地址，后续写入或刷新可使其恢复；首次成功绑定路径前，Session 内任何写入都可触发重试。刷新清除 `changed`，由 Host 触发的重新 stat 保留标记。帧是 `RemoteResult` 值，编程异常不被捕获。
+
+每个 Session 的所有被跟随文件共用一条受监督的 `changes` 流。跟随者按反斜杠归一为斜杠的绝对路径匹配。载体掉线由 Gateway 监督器重连；Host 结束或终态失败的流会结束其跟随者，最后的元数据仍可读取，直到重新打开。最后一个跟随者离开时释放流，后继流等待该释放完成，插件拆除等待所有在途关闭。提供者声明 `ResourceProtocolMap.file`；文本预览声明其 Sidebar 行号导航参数。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现内幕——点击展开</summary>
+
+### 设计概念
+
+经 `ctx.fs` 的读取是有意不加限制的——沙箱后端只围栏写与编辑——所以这里的每条约束都是服务自己的。页从 `streamText` 切出，后者逐块解码并拒绝非 UTF-8：切页器对窗口之前的行只计数不保留，对窗口内的每个片段先按字节上限验收再缓冲，并在窗口之后的第一个字符处返回，所以无论多大的文件或多长的单行都不会在内存里超过一页；随后在该页上做 NUL 扫描。流之前的一次 `stat` 给出页所报告的版本与大小。路径关有意先于包含判定：`lstat` 面向路径、看得见链接，而 `resolve` 会跟随它；代价是根外条目会先报告自己的类型再报告位置。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | `WorkspaceFiles`：`workspaceFiles` 服务与 Remote 命名空间、`Config`、四道关、切页器、`read`、`readBytes`、`stat`、`list` |
+| [`src/changes.ts`](src/changes.ts) | `WorkspaceChangeFeed`：`fs/observed` 订阅与每个打开的 `changes` generation 各一条队列 |
+| [`src/types.ts`](src/types.ts) | 线路类型与 `RemoteErrorDetailsMap` 错误码，以 `./types` 发布给 Client 包 |
+| [`src/client/index.ts`](src/client/index.ts)、[`provider.ts`](src/client/provider.ts)、[`change-feed.ts`](src/client/change-feed.ts) | 浏览器插件、文件元数据与每 Session 变更流 |
+| [`src/client/types.ts`](src/client/types.ts)、[`remote.ts`](src/client/remote.ts) | 资源值、参数、Client 错误码与生成的 Remote 类型 |
+| — | 不发布运行时 invariant 伴生件；每个 Host 答案都在调用时由 `ctx.fs` 与沙箱策略推导。 |
+
+Typert 生成 `./typert` 与 `./remote` 暴露的 Host 与 Client Remote 产物。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [文件系统能力](../../fs/fs/README.zh.md)——本服务经由读取的 `ctx.fs` 契约，含 `fs/observed` 与 `readByteRange`。
+- [沙箱策略](../../sandbox/sandbox-policy/README.zh.md)——Session 工作区根的来源。
+- [Remote 装配](../../api/remotes/README.zh.md)——Client 包如何触达 `workspaceFiles` 命名空间。
+- [Client 资源](../../client/resources/README.zh.md)——资源模型、`useResource`、pin 与提供者生命周期。
+- [工作区路径辅助](../../util/workspace-path/README.zh.md)——`fileAddressFor` 与 `parseFileAddress`，两端共享的 `dsh-resource://file/…` 地址语法。
+- [Sidebar 文本预览](../../client/ui-sidebar-textpreview/README.zh.md)——经 `file` 提供者跟随文件并读取其页的 tab 类型。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，本包不注册任何工具、不贡献提示词章节、不追加任何会话事件。
+
+#### KV Cache 影响
+
+无；本包既不装配也不发送提供方请求。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **仅覆盖 Agent 写入**——`changes` 转发 `fs/observed` 的发射；子进程、shell 命令或用户编辑器改动的文件不产生任何帧。
+- **类型先于位置**——根外条目若类型本身就不合格，报告的是 `not-regular-file` 或 `not-directory` 而非 `outside-workspace`，因为路径关先于包含判定。
+- **没有总行数**——页只报告 `eof`，不报告后面还有多少行；需要总数的消费方要翻到末尾或按 `bytes` 估算。
+- **超长单行没有页**——超过 `maxBytes` 的单行在包含它的每个窗口都以 `too-large` 失败，因为页按行而非按字节切。
+- **版本先于内容**——页上的 `version` 来自流之前的 stat；两者之间落地的写入会让该页落后一个版本，下一帧 `changes` 会报告它。
+- **generation 队列无界**——一个 `changes` generation 会缓冲每一条被包含的观察直到消费方 pull；停滞的消费方会在流的生命期内持续增长 Host 内存。
+- **`maxEntries` 限制的是答案，不是列举**——`list` 让 `ctx.fs.listDir` 列出全部子项后再截断数组，远超上限的目录仍让 Host 付出整个列举的代价（`fs-local` 上每个子项一次 stat）；要限制这份工作，需要文件系统 seam 的 `listDir` 支持上限。
+- **失效流保留元数据**——Host 结束 `changes` 或流终态失败后，已打开的值保持最后已知状态，直到重新打开；刷新不会重开流。
+- **刷新按路径共享**——同一会话中，一次刷新会重新 stat 此绝对路径的全部跟随者并清除其 `changed` 标记，包括没有重读内容的其它读者。按记录投递刷新仍是延期工作。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文——点击展开</summary>
+
+无。
+
+</details>
diff --git a/packages/api/workspace-files/package.json b/packages/api/workspace-files/package.json
new file mode 100644
index 0000000000..b51b6e9594
--- /dev/null
+++ b/packages/api/workspace-files/package.json
@@ -0,0 +1,86 @@
+{
+  "name": "@deepseek-ai/dsh-api-workspace-files",
+  "description": "Workspace file service and Client resource provider: bounded reads, directory listing, and live metadata over the workspaceFiles Remote namespace",
+  "version": "0.1.3-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/api/workspace-files"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./typert": {
+      "types": "./lib/typert.host.d.ts",
+      "default": "./lib/typert.host.js"
+    },
+    "./remote": {
+      "types": "./lib/typert.remote-client.d.ts",
+      "default": "./lib/typert.remote-client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-api-gateway",
+        "@deepseek-ai/dsh-api-session-controller",
+        "@deepseek-ai/dsh-client-resources"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/dsh-deque": "workspace:^",
+    "@deepseek-ai/dsh-typert-protocol": "workspace:^",
+    "@deepseek-ai/schemastery": "workspace:^",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "workspace:^"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-api-gateway": "workspace:^",
+    "@deepseek-ai/dsh-api-session-controller": "workspace:^",
+    "@deepseek-ai/dsh-client-resources": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-fs": "workspace:^",
+    "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-util-workspace-path": "workspace:^"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts",
+    "lib/typert.host.js",
+    "lib/typert.host.d.ts",
+    "lib/typert.remote-client.js",
+    "lib/typert.remote-client.d.ts"
+  ]
+}
diff --git a/packages/api/workspace-files/src/changes.ts b/packages/api/workspace-files/src/changes.ts
new file mode 100644
index 0000000000..6a1bd7a864
--- /dev/null
+++ b/packages/api/workspace-files/src/changes.ts
@@ -0,0 +1,113 @@
+/**
+ * Producer of the `changes` stream: every `fs/observed` emission whose target
+ * lies inside a generation's workspace root becomes one frame of that
+ * generation. Observations are emitted by tools after their own filesystem
+ * operation, so the feed covers Agent writes only; the OS is not watched.
+ * Each generation acknowledges its observation queue and resolved workspace
+ * root with `ready` before emitting any queued or live changes.
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { Deque } from '@deepseek-ai/dsh-deque'
+import type { FsObservation, FsTarget } from '@deepseek-ai/dsh-fs'
+import type { WorkspaceFileWatchFrame } from './types.ts'
+
+/** One `fs/observed` emission as received, before any generation filters it. */
+type Observed = readonly [target: FsTarget, observation: FsObservation]
+
+/** Owns `fs/observed` observation and every open `changes` generation. */
+export class WorkspaceChangeFeed {
+  private readonly followers = new Set<ChangeFollower>()
+
+  /** @param ctx - Host context carrying the filesystem the observations come from. */
+  constructor(private readonly ctx: Context) {
+    ctx.on('fs/observed', (target, observation) => {
+      for (const follower of this.followers) follower.push([target, observation])
+    })
+    ctx.effect(() => () => {
+      for (const follower of this.followers) follower.close()
+      this.followers.clear()
+    }, 'workspace-files.changes')
+  }
+
+  /**
+   * Open one generation reporting observations inside `workspaceRoot`.
+   * @param workspaceRoot - the session's workspace root path.
+   * @param signal - generation cancellation.
+   * @returns `ready` after observation is active and the root resolves, then
+   *   observations made after the generation was first pulled, in emission order.
+   */
+  async *follow(workspaceRoot: string, signal: AbortSignal): AsyncIterable<WorkspaceFileWatchFrame> {
+    signal.throwIfAborted()
+    // Registered before the root resolves, so nothing observed while it does is
+    // missed; the root only filters at drain time.
+    const follower = new ChangeFollower()
+    this.followers.add(follower)
+    try {
+      // Under the generation's signal, so a consumer leaving mid-resolve on a slow
+      // backend releases the follower now rather than when the resolve settles;
+      // a rejection the abort caused is the quiet end every other abort takes here.
+      const root = await this.ctx.fs.resolve(workspaceRoot, { signal }).catch((error: unknown) => {
+        if (signal.aborted) return undefined
+        throw error
+      })
+      if (root === undefined || signal.aborted || follower.isClosed) return
+      yield { kind: 'ready' }
+      for await (const [target, observation] of follower.read(signal)) {
+        if (!this.ctx.fs.contains(root, target)) continue
+        const absolutePath = this.ctx.fs.processPath(target)
+        yield {
+          kind: 'change',
+          change: observation.kind === 'present'
+            ? { absolutePath, version: observation.version }
+            : { absolutePath, absent: true },
+        }
+      }
+    } finally {
+      this.followers.delete(follower)
+      follower.close()
+    }
+  }
+}
+
+/** One generation's queue: observations wait here until its consumer pulls them. */
+class ChangeFollower {
+  private readonly queue = new Deque<Observed>()
+  private wake: (() => void) | undefined
+  private closed = false
+
+  /** Whether the generation was closed while its workspace root resolved. */
+  get isClosed(): boolean {
+    return this.closed
+  }
+
+  push(observed: Observed): void {
+    this.queue.pushBack(observed)
+    this.wake?.()
+  }
+
+  close(): void {
+    this.closed = true
+    this.wake?.()
+  }
+
+  /** Drain until closed or aborted; anything still queued then is dropped with the generation. */
+  async *read(signal: AbortSignal): AsyncIterable<Observed> {
+    const abort = (): void => { this.close() }
+    signal.addEventListener('abort', abort, { once: true })
+    if (signal.aborted) abort()
+    try {
+      while (!this.closed) {
+        const observed = this.queue.popFront()
+        if (observed !== undefined) {
+          yield observed
+          continue
+        }
+        await new Promise<void>((resolve) => { this.wake = resolve })
+        this.wake = undefined
+      }
+    } finally {
+      signal.removeEventListener('abort', abort)
+    }
+  }
+}
diff --git a/packages/api/workspace-files/src/client/change-feed.ts b/packages/api/workspace-files/src/client/change-feed.ts
new file mode 100644
index 0000000000..cc587d5f1f
--- /dev/null
+++ b/packages/api/workspace-files/src/client/change-feed.ts
@@ -0,0 +1,318 @@
+/**
+ * One Host `changes` subscription per session, fanned out to the open files of
+ * that session.
+ *
+ * The Host reports every agent write in a session on one stream; each open file
+ * wants only its own. The feed opens the session stream when the first follower
+ * arrives, hands each frame to the followers of its path, and disposes the
+ * stream when the last follower leaves. A follower buffers session changes
+ * until `stat` supplies its Host absolute path, then filters queued and live
+ * frames by that path, with `\\` normalized to `/`. Resource addresses identify
+ * reload requests; they never determine a notification path.
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { WorkspaceFileChange, WorkspaceFileWatchFrame } from '../types.ts'
+import type { SupervisedStream, WorkspaceFilesRemote } from './remote.ts'
+import type { WorkspaceFileEdit, WorkspaceFileNotice } from './types.ts'
+
+/**
+ * The follower key of one absolute path.
+ * @param path - an absolute path from a Host stat or change frame.
+ * @returns the path with `\\` normalized to `/`.
+ */
+function keyOf(path: string): string {
+  return path.replace(/\\/g, '/')
+}
+
+/** Notices of one follower, delivered in order and pulled by its consumer. */
+class Follower implements AsyncIterable<WorkspaceFileNotice> {
+  private readonly pending: Array<{ readonly key: string | undefined; readonly notice: WorkspaceFileNotice }> = []
+  private readonly started = Promise.withResolvers<boolean>()
+  private wake: (() => void) | undefined
+  private ended = false
+  private hostKey: string | undefined
+
+  /**
+   * Resolves true after the Host acknowledges its subscription, or false if
+   * this follower ends before acknowledgement.
+   */
+  readonly ready = this.started.promise
+
+  /**
+   * @param address - resource address used for reload lookup.
+   * @param leave - unregisters this follower and its abort listener.
+   */
+  constructor(readonly address: string, private readonly leave: () => void) {}
+
+  /** The normalized Host path, absent until a successful stat. */
+  get key(): string | undefined {
+    return this.hostKey
+  }
+
+  /**
+   * Select the Host path for queued and future changes.
+   * @param absolutePath - the successful stat's absolute path.
+   */
+  bind(absolutePath: string): void {
+    this.hostKey = keyOf(absolutePath)
+  }
+
+  /** The Host acknowledged an active subscription and resolved workspace root. */
+  start(): void {
+    this.started.resolve(true)
+  }
+
+  /**
+   * Queue one notice.
+   * @param notice - what the consumer receives next.
+   * @param key - normalized Host path for a change; absent for a reload.
+   */
+  push(notice: WorkspaceFileNotice, key?: string): void {
+    this.pending.push({ key, notice })
+    this.wake?.()
+  }
+
+  /** Deliver what is queued, then finish. */
+  end(): void {
+    this.ended = true
+    this.started.resolve(false)
+    this.wake?.()
+  }
+
+  /** Unregister even when the consumer has not started pulling notices. */
+  dispose(): void {
+    this.leave()
+  }
+
+  /** @inheritdoc */
+  async *[Symbol.asyncIterator](): AsyncIterator<WorkspaceFileNotice> {
+    try {
+      while (true) {
+        const next = this.pending.shift()
+        if (next !== undefined) {
+          if (next.key === undefined || this.hostKey === undefined || next.key === this.hostKey) yield next.notice
+          continue
+        }
+        if (this.ended) return
+        await new Promise<void>((resolve) => { this.wake = resolve })
+        this.wake = undefined
+      }
+    } finally {
+      this.dispose()
+    }
+  }
+}
+
+/** The stream and followers of one session. */
+class SessionFeed {
+  private readonly followers = new Set<Follower>()
+  private readonly stream: SupervisedStream<WorkspaceFileWatchFrame>
+  private closed = false
+  private started = false
+
+  /**
+   * @param remote - the Remote face carrying `workspaceFiles.changes`.
+   * @param sessionId - the session whose writes this feed follows.
+   * @param after - the previous feed of this session still closing, if any; the stream opens once it has settled.
+   * @param onClose - called once when the stream is gone, whatever the cause, with the dispose that is closing it.
+   */
+  constructor(
+    remote: WorkspaceFilesRemote,
+    sessionId: SessionId,
+    after: Promise<void> | undefined,
+    private readonly onClose: (closed: Promise<void>) => void,
+  ) {
+    this.stream = remote.$stream<WorkspaceFileWatchFrame>({
+      name: `workspace file changes of ${sessionId}`,
+      // A predecessor still closing finishes first, so one session never has
+      // two Host streams open at once.
+      open: (signal) => {
+        this.started = false
+        return openAfter(after, () => remote.workspaceFiles.changes(sessionId, signal))
+      },
+      // A normal end means the Host closed the session's feed: the session is
+      // gone or the Host is shutting down, so there is nothing to reopen.
+      ended: () => new Error(`workspace file changes of ${sessionId} ended`),
+    })
+    void this.pump()
+  }
+
+  /**
+   * Register one resource address before its Host path is known.
+   * @param follower - receives changes and binds its path after stat.
+   */
+  add(follower: Follower): void {
+    this.followers.add(follower)
+    if (this.started) follower.start()
+  }
+
+  /**
+   * Unregister one follower; the last one leaving disposes the stream.
+   * @param follower - the follower to drop.
+   */
+  remove(follower: Follower): void {
+    this.followers.delete(follower)
+    if (this.followers.size === 0) this.close()
+  }
+
+  /**
+   * Reload an address and every follower bound to the same Host path.
+   * @param address - the resource address requesting a reload.
+   */
+  requestRestat(address: string): void {
+    const keys = new Set<string>()
+    for (const follower of this.followers) {
+      if (follower.address === address && follower.key !== undefined) keys.add(follower.key)
+    }
+    for (const follower of this.followers) {
+      if (follower.address === address || (follower.key !== undefined && keys.has(follower.key))) {
+        follower.push({ kind: 'restat' })
+      }
+    }
+  }
+
+  private async pump(): Promise<void> {
+    try {
+      for await (const item of this.stream) {
+        const frame = item.value
+        switch (frame.kind) {
+          case 'ready':
+            item.accept()
+            this.started = true
+            for (const follower of this.followers) follower.start()
+            break
+          case 'change': {
+            const key = keyOf(frame.change.absolutePath)
+            const notice = editOf(frame.change)
+            for (const follower of this.followers) follower.push(notice, key)
+            break
+          }
+          default:
+            assertNever(frame)
+        }
+      }
+    } catch {
+      // A terminal stream failure or the Host's end: followers end quietly
+      // below, and the metadata they hold stays the last known.
+    } finally {
+      this.close()
+    }
+  }
+
+  private close(): void {
+    if (this.closed) return
+    this.closed = true
+    const closed = this.stream.dispose()
+    for (const follower of this.followers) follower.end()
+    this.followers.clear()
+    this.onClose(closed)
+  }
+}
+
+/**
+ * Open a Host stream once a predecessor has finished closing.
+ * @param after - the predecessor's dispose, or nothing to wait for.
+ * @param open - opens the stream.
+ * @returns the stream's items.
+ */
+async function* openAfter<T>(after: Promise<void> | undefined, open: () => AsyncIterable<T>): AsyncIterable<T> {
+  await after
+  yield* open()
+}
+
+/**
+ * The write one Host frame reports.
+ * @param frame - the Host frame.
+ * @returns the edit notice followers receive.
+ */
+function editOf(frame: WorkspaceFileChange): WorkspaceFileEdit {
+  return 'absent' in frame ? { kind: 'absent' } : { kind: 'changed', version: frame.version }
+}
+
+function assertNever(frame: never): never {
+  throw new Error(`Unexpected workspace file watch frame: ${JSON.stringify(frame)}`)
+}
+
+/**
+ * Per-session fan-out of the Host's workspace file change stream.
+ *
+ * Owned by the provider; one instance serves every session of the Client.
+ */
+export class ChangeFeed {
+  /** Live feeds only: a feed removes itself when its stream closes. */
+  private readonly sessions = new Map<SessionId, SessionFeed>()
+  /** Streams still closing, by session: the session's next feed opens after its predecessor has settled. */
+  private readonly closing = new Map<SessionId, Promise<void>>()
+
+  /**
+   * @param remote - the Remote face carrying `$stream` and `workspaceFiles.changes`.
+   */
+  constructor(private readonly remote: WorkspaceFilesRemote) {}
+
+  /**
+   * Follow one resource address in one session before its Host path is known.
+   *
+   * The follower is registered on call, not on first pull. Changes delivered
+   * to this Client are queued while stat is pending. The first follower starts
+   * the session's local `changes` call. The iterable ends
+   * when `signal` aborts or when the session stream is gone; ending it early
+   * (`break`, `return`) unregisters the follower as well, and the last follower
+   * of a session disposes its stream. Await a true `ready` result before stat
+   * so the Host subscription is active, then bind each stat's absolute path. Until binding,
+   * any session write can trigger a retry; after binding, only matching queued
+   * and live changes pass.
+   * @param sessionId - the session whose workspace holds the file.
+   * @param address - the resource address, used only for reload lookup.
+   * @param signal - ends the follow.
+   * @returns a single-consumer subscription with Host-path binding and explicit disposal.
+   */
+  follow(sessionId: SessionId, address: string, signal: AbortSignal): Follower {
+    const feed = signal.aborted ? undefined : this.feedOf(sessionId)
+    const leave = (): void => {
+      signal.removeEventListener('abort', leave)
+      follower.end()
+      feed?.remove(follower)
+    }
+    const follower = new Follower(address, leave)
+    if (feed === undefined) {
+      follower.end()
+    } else {
+      feed.add(follower)
+      signal.addEventListener('abort', leave, { once: true })
+    }
+    return follower
+  }
+
+  /**
+   * Ask an address and its same-session Host-path peers to `stat` again.
+   * @param sessionId - the session whose workspace holds the file.
+   * @param address - the resource address requesting a reload.
+   */
+  requestRestat(sessionId: SessionId, address: string): void {
+    this.sessions.get(sessionId)?.requestRestat(address)
+  }
+
+  /**
+   * Wait for every stream that is still closing, so an owner tearing down
+   * leaves no Host stream behind.
+   * @returns resolves once no stream of this feed is closing.
+   */
+  async settle(): Promise<void> {
+    await Promise.all(this.closing.values())
+  }
+
+  private feedOf(sessionId: SessionId): SessionFeed {
+    const existing = this.sessions.get(sessionId)
+    if (existing !== undefined) return existing
+    const feed = new SessionFeed(this.remote, sessionId, this.closing.get(sessionId), (closed) => {
+      this.sessions.delete(sessionId)
+      // A dispose that rejects is still a settled close: nothing remains to wait for.
+      const tracked: Promise<void> = closed.then(() => undefined, () => undefined).then(() => {
+        if (this.closing.get(sessionId) === tracked) this.closing.delete(sessionId)
+      })
+      this.closing.set(sessionId, tracked)
+    })
+    this.sessions.set(sessionId, feed)
+    return feed
+  }
+}
diff --git a/packages/api/workspace-files/src/client/index.ts b/packages/api/workspace-files/src/client/index.ts
new file mode 100644
index 0000000000..418cd5fcf5
--- /dev/null
+++ b/packages/api/workspace-files/src/client/index.ts
@@ -0,0 +1,42 @@
+/**
+ * Browser half: the `file` resource provider over `remote.workspaceFiles`.
+ *
+ * `types.ts` is what the protocol publishes, `change-feed.ts` shares one Host
+ * `changes` stream per session, `provider.ts` turns it and `stat` into a value
+ * stream, and this module only wires them into `ctx.resources`.
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-api-gateway/client'
+// The `sessions` service face supplies the current Session for absolute addresses.
+import type {} from '@deepseek-ai/dsh-api-session-controller/client'
+import type {} from '@deepseek-ai/dsh-client-resources/client'
+import { ChangeFeed } from './change-feed.ts'
+import { createFileResourceProvider, type SessionLookup } from './provider.ts'
+
+export type { SessionLookup } from './provider.ts'
+export type { WorkspaceFileParams, WorkspaceFileResource } from './types.ts'
+
+/** Required browser services: the resource model, the Remote carrier and its namespace, and the Session list. */
+export const inject = ['resources', 'remote', 'remote.workspaceFiles', 'sessions']
+
+/**
+ * Client plugin body: register the `file` provider for this plugin's lifetime.
+ * @param ctx - client root context carrying `resources`, the Remote face, and `sessions`.
+ */
+export function apply(ctx: ClientContext): void {
+  // The current Session changes with navigation; absolute addresses read it on demand.
+  const sessions: SessionLookup = {
+    current: () => ctx.sessions.list.getSnapshot().current,
+  }
+  const changes = new ChangeFeed(ctx.remote)
+  const provider = createFileResourceProvider(ctx.remote, changes, sessions)
+  ctx.effect(() => {
+    const release = ctx.resources.register(provider)
+    // Teardown waits for every session stream still closing, so the plugin
+    // leaves no Host stream behind.
+    return async () => {
+      release()
+      await changes.settle()
+    }
+  }, 'workspace-files: file resource provider')
+}
diff --git a/packages/api/workspace-files/src/client/provider.ts b/packages/api/workspace-files/src/client/provider.ts
new file mode 100644
index 0000000000..0010ad9d3c
--- /dev/null
+++ b/packages/api/workspace-files/src/client/provider.ts
@@ -0,0 +1,181 @@
+/**
+ * The `file` protocol's provider: a workspace file's metadata as a stream of
+ * `RemoteResult` frames.
+ *
+ * An address names the file in one of two scopes. A `session` address,
+ * `dsh-resource://file/session/<sessionId>/<path>`, carries a path relative to
+ * that Session's workspace root: the Host receives the relative path as-is and
+ * resolves it against the root it holds. Only the Host's `stat.absolutePath`
+ * selects the change-feed key; no Client Session summary is needed.
+ * An `absolute` address, `dsh-resource://file/absolute/<path>`, carries no
+ * Session and is read through the Session on screen. An address neither scope
+ * resolves yields one failure frame — `workspace-file/unsupported-address` for
+ * a string outside the grammar, `workspace-file/unknown-workspace` when the
+ * absolute address has no current Session — and ends.
+ *
+ * The first frame is the file's `stat`; every Host-reported write yields the
+ * metadata flagged `changed`; a reported disappearance, or a write while the
+ * last stat had failed, runs `stat` again and flags what it finds; a reload
+ * runs `stat` again and clears the flag. Failures travel as `ok: false` frames, never as thrown errors: the
+ * Remote face does not reject, and anything thrown inside the stream is a
+ * programming error the resource model lets surface. A failed stat does not end
+ * the stream: the next write or reload stats again. One {@link ChangeFeed}
+ * serves every open file of the Client.
+ */
+import type { ResourceProvider } from '@deepseek-ai/dsh-client-resources/client'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
+import { parseFileAddress } from '@deepseek-ai/dsh-util-workspace-path'
+import type { WorkspaceFileStat } from '../types.ts'
+import type { ChangeFeed } from './change-feed.ts'
+import type { WorkspaceFilesRemote } from './remote.ts'
+import type { WorkspaceFileResource } from './types.ts'
+
+/** The current Session used to authorize an absolute address. */
+export interface SessionLookup {
+  /**
+   * The Session on screen, which an `absolute` address is read through.
+   * @returns its id, or `undefined` while no Session is current.
+   */
+  current(): SessionId | undefined
+}
+
+/** The Session and unmodified path submitted to the Host. */
+interface HostFile {
+  readonly sessionId: SessionId
+  /** The path the Host receives: workspace-relative for a `session` address, absolute for an `absolute` one. */
+  readonly path: string
+}
+
+/**
+ * Build the `file` provider over one Remote face, one change feed, and the Client's Session list.
+ * @param remote - the Remote face carrying `workspaceFiles.stat`.
+ * @param changes - the per-session change fan-out.
+ * @param sessions - the current Session, read for absolute addresses on every open and reload.
+ * @returns the provider to register into `ctx.resources`.
+ */
+export function createFileResourceProvider(
+  remote: WorkspaceFilesRemote,
+  changes: ChangeFeed,
+  sessions: SessionLookup,
+): ResourceProvider<'file'> {
+  return {
+    protocol: 'file',
+    async *open(address, { signal }): AsyncIterable<RemoteResult<WorkspaceFileResource>> {
+      const resolved = resolve(address, sessions)
+      if (!resolved.ok) {
+        yield resolved
+        return
+      }
+      const { sessionId, path } = resolved.value
+      // Queue changes delivered to this Client while stat is pending.
+      const notices = changes.follow(sessionId, address, signal)
+      const stat = (): Promise<RemoteResult<WorkspaceFileStat>> => remote.workspaceFiles.stat(sessionId, path, signal)
+      // Read through a call: a plain `signal.aborted` is narrowed to `false` by
+      // the first check and would read as always-false after the later awaits.
+      const aborted = (): boolean => signal.aborted
+      // Undefined while the last stat failed: the follow is on the address, not
+      // on the file, so a write or a reload can still bring the file live.
+      let current: WorkspaceFileResource | undefined
+      try {
+        if (!await notices.ready || aborted()) return
+        const first = await stat()
+        if (aborted()) return
+        if (first.ok) {
+          notices.bind(first.value.absolutePath)
+          current = metadataOf(first.value, false)
+          yield { ok: true, value: current }
+        } else {
+          yield first
+        }
+        for await (const notice of notices) {
+          if (current === undefined) {
+            // Still gone: nothing new to report.
+            if (notice.kind === 'absent') continue
+          } else if (notice.kind === 'changed') {
+            // Frames report observations: holding this version already means the
+            // consumer learns nothing new.
+            if (notice.version === current.version) continue
+            current = { ...current, version: notice.version, changed: true }
+            yield { ok: true, value: current }
+            continue
+          }
+          // A Host notice may mean stale content; only a reload clears the flag.
+          const again = await stat()
+          if (aborted()) return
+          if (!again.ok) {
+            current = undefined
+            yield again
+            continue
+          }
+          notices.bind(again.value.absolutePath)
+          current = metadataOf(again.value, notice.kind !== 'restat')
+          yield { ok: true, value: current }
+        }
+      } finally {
+        notices.dispose()
+      }
+    },
+    reload(address) {
+      const resolved = resolve(address, sessions)
+      if (resolved.ok) changes.requestRestat(resolved.value.sessionId, address)
+    },
+  }
+}
+
+/**
+ * Resolve one address to the Host call it stands for, or to the failure frame it earns.
+ * @param address - the full address, scheme included.
+ * @param sessions - the Client's Session list.
+ * @returns the Host file, or the `unsupported-address` / `unknown-workspace` failure.
+ */
+function resolve(address: string, sessions: SessionLookup): RemoteResult<HostFile> {
+  const parsed = parseFileAddress(address)
+  if (parsed === undefined) return { ok: false, error: unsupportedAddress(address) }
+  if (parsed.scope === 'session') {
+    // The address is a string boundary: its id segment is the Session id it names.
+    const sessionId = parsed.sessionId as SessionId
+    return { ok: true, value: { sessionId, path: parsed.path } }
+  }
+  const sessionId = sessions.current()
+  if (sessionId === undefined) return { ok: false, error: unknownWorkspace(address) }
+  return { ok: true, value: { sessionId, path: parsed.path } }
+}
+
+/**
+ * The failure frame's error for an address this provider does not serve.
+ * @param address - the offending address.
+ * @returns the typed error.
+ */
+function unsupportedAddress(address: string): RemoteError<'workspace-file/unsupported-address'> {
+  return new RemoteError(
+    'workspace-file/unsupported-address',
+    `${address} is not a dsh-resource://file/session/<sessionId>/<path> or dsh-resource://file/absolute/<path> address`,
+    { address },
+  )
+}
+
+/**
+ * The failure frame's error for an absolute address with no current Session.
+ * @param address - the offending address.
+ * @returns the typed error.
+ */
+function unknownWorkspace(address: string): RemoteError<'workspace-file/unknown-workspace'> {
+  return new RemoteError(
+    'workspace-file/unknown-workspace',
+    `${address} requires a current Session`,
+    { address },
+  )
+}
+
+/**
+ * The resource value one `stat` result amounts to.
+ * @param stat - what the Host reported.
+ * @param changed - whether the consumer's content may be stale: `true` after a
+ *   Host notice prompted the stat, `false` for the opening stat and a reload's.
+ * @returns the metadata frame value.
+ */
+function metadataOf(stat: WorkspaceFileStat, changed: boolean): WorkspaceFileResource {
+  return { absolutePath: stat.absolutePath, version: stat.version, changed, ...(stat.bytes === undefined ? {} : { bytes: stat.bytes }) }
+}
diff --git a/packages/api/workspace-files/src/client/remote.ts b/packages/api/workspace-files/src/client/remote.ts
new file mode 100644
index 0000000000..d1be9c197a
--- /dev/null
+++ b/packages/api/workspace-files/src/client/remote.ts
@@ -0,0 +1,50 @@
+/**
+ * The slice of the Client Remote this package calls: the generated
+ * `workspaceFiles` methods by name, and the stream supervisor structurally, so
+ * the feed and the provider are testable against a scripted face.
+ */
+import type { ClientRemote } from '@deepseek-ai/dsh-api-gateway/client'
+// Merges the generated `workspaceFiles` namespace into the Remote face.
+import type {} from '@deepseek-ai/dsh-api-workspace-files/remote'
+
+/** One item of a supervised stream; `accept` marks the delivering generation as healthy. */
+export interface SupervisedStreamItem<Item> {
+  /** The decoded frame. */
+  readonly value: Item
+  /** Reset the reconnect backoff: this generation is delivering. */
+  accept(): void
+}
+
+/** A reconnecting single-consumer stream the Remote supervises. */
+export interface SupervisedStream<Item> extends AsyncIterable<SupervisedStreamItem<Item>> {
+  /**
+   * Stop the stream for good.
+   * @returns once the active generation and the consumer iterator are closed.
+   */
+  dispose(): Promise<void>
+}
+
+/** What one supervised stream needs from its owner. */
+export interface SupervisedStreamOptions<Item> {
+  /** Diagnostic owner name. */
+  readonly name: string
+  /** Open one physical generation; `signal` aborts it. */
+  readonly open: (signal: AbortSignal) => AsyncIterable<Item>
+  /** The error a generation's normal end amounts to; a carrier error asks for a reopen, anything else is terminal. */
+  readonly ended: (accepted: boolean) => Error
+}
+
+/** The `workspaceFiles` namespace methods this package calls, as the generated Remote declares them. */
+export type WorkspaceFilesNamespace = Pick<ClientRemote['workspaceFiles'], 'stat' | 'changes'>
+
+/** The Client Remote as this package sees it. */
+export interface WorkspaceFilesRemote {
+  /**
+   * Create one reconnecting stream.
+   * @param options - opener and end classification.
+   * @returns the supervised stream, unstarted until iterated.
+   */
+  $stream<Item>(options: SupervisedStreamOptions<Item>): SupervisedStream<Item>
+  /** The `workspaceFiles` namespace. */
+  readonly workspaceFiles: WorkspaceFilesNamespace
+}
diff --git a/packages/api/workspace-files/src/client/types.ts b/packages/api/workspace-files/src/client/types.ts
new file mode 100644
index 0000000000..606e1164b3
--- /dev/null
+++ b/packages/api/workspace-files/src/client/types.ts
@@ -0,0 +1,68 @@
+/**
+ * The `file` protocol's resource metadata, navigation params, Client errors,
+ * and internal change-feed notices.
+ */
+// Bring the base `ResourceProtocolMap` declaration into this program so the
+// augmentation below merges into it instead of declaring a second interface.
+import type {} from '@deepseek-ai/dsh-client-resources/client'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface ResourceProtocolMap {
+    /**
+     * One workspace file's metadata, addressed as
+     * `dsh-resource://file/session/<sessionId>/<workspace-relative path>` or
+     * `dsh-resource://file/absolute/<absolute path>`.
+     */
+    file: WorkspaceFileResource
+  }
+}
+
+/** What a `file` tab is asked to reveal on open or navigation; JSON-shaped. */
+export interface WorkspaceFileParams {
+  /** 1-based line to scroll into view; absent leaves the position alone. */
+  readonly line?: number
+}
+
+declare module '@deepseek-ai/dsh-typert-protocol' {
+  interface RemoteErrorDetailsMap {
+    /**
+     * The address is not a `dsh-resource://file/` address in a scope the
+     * provider serves: `session/<sessionId>/<workspace-relative path>` or
+     * `absolute/<absolute path>`. Raised by the Client provider; the Host never
+     * emits it.
+     */
+    'workspace-file/unsupported-address': { readonly address: string }
+    /**
+     * An `absolute` address has no current Session to authorize its Host call.
+     * Raised by the Client provider; the Host never emits it. Session addresses
+     * are resolved by the Host without a Client Session summary.
+     */
+    'workspace-file/unknown-workspace': { readonly address: string }
+  }
+}
+
+/**
+ * One workspace file as the resource model carries it: metadata only.
+ *
+ * The stream reports that the file moved on; it never carries content. A
+ * consumer reads the text itself, by page, and uses `version` and `changed` to
+ * know when its pages are stale.
+ */
+export interface WorkspaceFileResource {
+  /** Absolute path in the Host filesystem, as returned by the last successful stat. */
+  readonly absolutePath: string
+  /** The Host's latest report of the file's version: from `stat` first, then from each reported write. */
+  readonly version: string
+  /** Byte size as of the last `stat`, when the backend reports it. */
+  readonly bytes?: number
+  /** The Host reported a write after the last `stat`; a reload (`stat` again) clears it. */
+  readonly changed: boolean
+}
+
+/** One Host-reported write inside the session's workspace. */
+export type WorkspaceFileEdit =
+  | { readonly kind: 'changed'; readonly version: string }
+  | { readonly kind: 'absent' }
+
+/** What one follower of a path receives: a Host write, or a local request to `stat` again. */
+export type WorkspaceFileNotice = WorkspaceFileEdit | { readonly kind: 'restat' }
diff --git a/packages/api/workspace-files/src/index.ts b/packages/api/workspace-files/src/index.ts
new file mode 100644
index 0000000000..42dfb13bc1
--- /dev/null
+++ b/packages/api/workspace-files/src/index.ts
@@ -0,0 +1,400 @@
+/**
+ * Workspace file service: paged text reads, byte-window reads, stats, directory
+ * listings, and the agent-write change feed inside one session's workspace
+ * root, exposed as the `workspaceFiles` Remote namespace.
+ *
+ * Reads through `ctx.fs` are deliberately unconfined — the sandboxing backend
+ * fences writes and edits only, and says so. Every constraint this service
+ * needs is therefore its own, and there are four:
+ *
+ * 1. The path is authorized by containment in the session's workspace root.
+ * 2. Containment is decided by {@link FileSystem.contains}, never by comparing
+ *    path strings: `resolve` realpaths, so a prefix test cannot see a symlink
+ *    that leaves the root. `lstat` rejects a link before that follow happens.
+ * 3. Every cap is validated Config, changeable per deployment. A page is cut by
+ *    lines and refused, not shortened, when its bytes exceed the byte cap; a
+ *    listing is cut by entries and says so.
+ * 4. Failures are one `RemoteError` per reason, declared in `./types`.
+ *
+ * A page is cut from `streamText`, which decodes and rejects non-UTF-8 as it
+ * goes, so the file is read only up to the first character past the page and
+ * never held whole in memory; the NUL scan runs on the page itself.
+ *
+ * This is NOT modelled on `session.openWorkspacePath`. That endpoint hands a
+ * path to the local opener and leaves the effect on the machine; this one sends
+ * file content across the wire, which is a different level of exposure.
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type {} from '@deepseek-ai/dsh-fs'
+import type { FsDirEntry, FsInfo, FsPathInfo, FsTarget } from '@deepseek-ai/dsh-fs'
+import type {} from '@deepseek-ai/dsh-sandbox-policy'
+import { Remote, RemoteError, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
+import { WorkspaceChangeFeed } from './changes.ts'
+import type {
+  WorkspaceByteRange,
+  WorkspaceDirectoryEntry,
+  WorkspaceDirectoryListing,
+  WorkspaceFileBytes,
+  WorkspaceFileRange,
+  WorkspaceFileStat,
+  WorkspaceFileText,
+  WorkspaceFileWatchFrame,
+} from './types.ts'
+
+export type * from './types.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** Host owner of the `workspaceFiles` Remote namespace. */
+    workspaceFiles: WorkspaceFiles
+  }
+}
+
+/** Deployment caps on one page or one listing. */
+export interface Config {
+  /**
+   * Inclusive byte cap on one page's text and on one byte window.
+   *
+   * A page above this fails; it is not shortened, because a silently cut page
+   * reads as the whole page. A byte window asking for more is refused the same
+   * way. The file itself has no size cap: a caller pages through it.
+   */
+  readonly maxBytes: number
+  /** Default and largest page size in lines; a request asking for more is refused. */
+  readonly maxLines: number
+  /** Cap on returned directory entries; the rest is dropped and reported cut. */
+  readonly maxEntries: number
+}
+
+/** One page cut from a decoded text stream. */
+interface Page {
+  readonly text: string
+  /** Lines in `text`; `0` for a page past the last line. */
+  readonly lines: number
+  readonly eof: boolean
+}
+
+/** The byte text never carries: its presence marks a page as binary. */
+const NUL = String.fromCharCode(0)
+
+/** Refuse anything the wire schema admits as a number but a window cannot use: only safe integers index a file. */
+function integerAtLeast(value: number, min: number, name: string): number {
+  if (!Number.isSafeInteger(value) || value < min) {
+    throw new RemoteError('gateway/bad-request', `${name} must be a safe integer of at least ${min}`, {})
+  }
+  return value
+}
+
+/**
+ * Cut lines `offset` through `offset + limit - 1` from decoded chunks, stopping
+ * at the first character past the page so the rest of the file is never read.
+ * Lines before the page are counted, not kept, and the page is refused the
+ * moment its bytes exceed `maxBytes`, so one giant line cannot grow memory past
+ * the cap either.
+ */
+async function cutPage(
+  chunks: AsyncIterable<string>,
+  offset: number,
+  limit: number,
+  maxBytes: number,
+  path: string,
+): Promise<Page> {
+  const last = offset + limit - 1
+  const lines: string[] = []
+  let current = ''
+  let bytes = 0
+  let lineNumber = 1
+  const admit = (size: number): void => {
+    bytes += size
+    if (bytes > maxBytes) {
+      throw new RemoteError(
+        'workspace-file/too-large',
+        `lines ${offset}-${last} of "${path}" exceed the ${maxBytes} byte cap`,
+        { path, limit: maxBytes },
+      )
+    }
+  }
+  const complete = (): void => {
+    if (lines.length > 0) admit(1)
+    lines.push(current)
+    current = ''
+  }
+  for await (const chunk of chunks) {
+    let position = 0
+    while (position < chunk.length) {
+      if (lineNumber > last) return { text: lines.join('\n'), lines: lines.length, eof: false }
+      const newline = chunk.indexOf('\n', position)
+      const segment = newline === -1 ? chunk.slice(position) : chunk.slice(position, newline)
+      if (lineNumber >= offset) {
+        admit(Buffer.byteLength(segment, 'utf8'))
+        current += segment
+      }
+      if (newline === -1) break
+      if (lineNumber >= offset) complete()
+      lineNumber += 1
+      position = newline + 1
+    }
+  }
+  // Only an in-page line can be pending here: earlier lines were never kept,
+  // and a character past the page returned above.
+  if (current.length > 0) complete()
+  return { text: lines.join('\n'), lines: lines.length, eof: true }
+}
+
+/**
+ * Workspace path of `target` relative to `root`, derived from the two canonical
+ * `file:` URIs so the answer is `/`-joined on every platform. Empty for the root.
+ */
+function workspacePathOf(rootUrl: string, targetUrl: string): string {
+  const root = new URL(rootUrl).pathname.replace(/\/+$/, '')
+  const target = new URL(targetUrl).pathname
+  if (target === root) return ''
+  return target.slice(root.length + 1).split('/').map(decodeURIComponent).join('/')
+}
+
+/** Strip the resolved child target: the wire carries names and metadata only. */
+function directoryEntry(child: FsDirEntry): WorkspaceDirectoryEntry {
+  return {
+    name: child.name,
+    type: child.type,
+    ...child.size === undefined ? {} : { size: child.size },
+  }
+}
+
+/** Host Remote service over the composed filesystem, confined to one workspace. */
+export class WorkspaceFiles extends TypertRemoteService {
+  static inject = ['fs', 'sandboxPolicy', 'typert']
+
+  static Config: z<Config> = z.object({
+    maxBytes: z.number().step(1).min(1).default(2 * 1024 * 1024),
+    maxLines: z.number().step(1).min(1).default(5000),
+    maxEntries: z.number().step(1).min(1).default(2000),
+  })
+
+  private readonly feed: WorkspaceChangeFeed
+
+  /**
+   * @param ctx - Host context carrying the filesystem and the sandbox policy.
+   * @param config - deployment caps on one page or one listing.
+   */
+  constructor(ctx: Context, private readonly config: Config) {
+    super(ctx, 'workspaceFiles')
+    this.feed = new WorkspaceChangeFeed(ctx)
+  }
+
+  /**
+   * Read one page of lines from a UTF-8 text file inside the Agent's workspace.
+   * @param agent - target Agent resolved from the Session identity on the wire.
+   * @param path - workspace path, absolute or relative to the workspace root.
+   * @param range - the line window; omitted fields take the page defaults.
+   * @param signal - caller cancellation.
+   * @returns the page, the file's version at the stat before it, and whether it reaches the last line.
+   */
+  @Remote
+  async read(agent: Agent, path: string, range: WorkspaceFileRange, signal: AbortSignal): Promise<WorkspaceFileText> {
+    const { offset, limit } = this.resolvePage(range)
+    const { target, info } = await this.locateFile(agent, path, signal)
+    const page = await this.cutPage(target, offset, limit, signal, path)
+    if (page.text.includes(NUL)) {
+      throw new RemoteError('workspace-file/not-text', `"${path}" contains NUL bytes`, { path })
+    }
+    return { ...this.statOf(target, info), offset, text: page.text, lines: page.lines, eof: page.eof }
+  }
+
+  /**
+   * Read one byte window of a regular file inside the Agent's workspace: raw
+   * bytes, no text decoding and no binary rejection.
+   * @param agent - target Agent resolved from the Session identity on the wire.
+   * @param path - workspace path, absolute or relative to the workspace root.
+   * @param range - the byte window; omitted fields take the window defaults.
+   * @param signal - caller cancellation.
+   * @returns the window in base64, the file's version and size at the stat before it, and whether it reaches the last byte.
+   */
+  @Remote
+  async readBytes(agent: Agent, path: string, range: WorkspaceByteRange, signal: AbortSignal): Promise<WorkspaceFileBytes> {
+    const { offset, length } = this.resolveWindow(range, path)
+    const { target, info } = await this.locateFile(agent, path, signal)
+    const data = await this.ctx.fs.readByteRange(target, { offset, length }, signal)
+    const eof = info.size === undefined ? data.length < length : offset + data.length >= info.size
+    return { ...this.statOf(target, info), offset, data: Buffer.from(data).toString('base64'), eof }
+  }
+
+  /**
+   * Report one regular file's identity, version, and size without its content.
+   * @param agent - target Agent resolved from the Session identity on the wire.
+   * @param path - workspace path, absolute or relative to the workspace root.
+   * @param signal - caller cancellation.
+   * @returns the file's absolute path, current version, and byte size.
+   */
+  @Remote
+  async stat(agent: Agent, path: string, signal: AbortSignal): Promise<WorkspaceFileStat> {
+    const { target, info } = await this.locateFile(agent, path, signal)
+    return this.statOf(target, info)
+  }
+
+  /**
+   * List the direct children of one directory inside the Agent's workspace.
+   * @param agent - target Agent resolved from the Session identity on the wire.
+   * @param path - workspace path, absolute or relative to the workspace root.
+   * @param signal - caller cancellation.
+   * @returns the directory's children in the backend's stable name order, bounded by the entry cap.
+   */
+  @Remote
+  async list(agent: Agent, path: string, signal: AbortSignal): Promise<WorkspaceDirectoryListing> {
+    const { root, workspaceRoot, entry } = await this.inspect(agent, path, signal)
+    if (entry.type !== 'directory') {
+      throw new RemoteError(
+        'workspace-file/not-directory',
+        `"${path}" is a ${entry.type}`,
+        { path, kind: entry.type },
+      )
+    }
+    const target = await this.confine(root, workspaceRoot, path, signal)
+    const children = await this.ctx.fs.listDir(target, signal)
+    return {
+      path: workspacePathOf(this.ctx.fs.fileUrl(root), this.ctx.fs.fileUrl(target)),
+      entries: children.slice(0, this.config.maxEntries).map(directoryEntry),
+      truncated: children.length > this.config.maxEntries,
+    }
+  }
+
+  /**
+   * Stream every `fs/observed` observation of a file inside the Agent's
+   * workspace. Only Agent filesystem operations report here; the OS is not
+   * watched.
+   * @param agent - target Agent resolved from the Session identity on the wire.
+   * @param signal - generation cancellation.
+   * @returns `ready` once the Host observation queue is active and the workspace
+   *   root is resolved, then queued and live observations in emission order.
+   */
+  @Remote({ mode: 'stream' })
+  changes(agent: Agent, signal: AbortSignal): AsyncIterable<WorkspaceFileWatchFrame> {
+    return this.feed.follow(this.workspaceRootOf(agent), signal)
+  }
+
+  /** Apply the page defaults and caps here, so the request never carries them implicitly. */
+  private resolvePage(range: WorkspaceFileRange): { offset: number; limit: number } {
+    const offset = range.offset === undefined ? 1 : integerAtLeast(range.offset, 1, 'offset')
+    const limit = range.limit === undefined ? this.config.maxLines : integerAtLeast(range.limit, 1, 'limit')
+    if (limit > this.config.maxLines) {
+      throw new RemoteError('gateway/bad-request', `limit must be at most ${this.config.maxLines}`, {})
+    }
+    return { offset, limit }
+  }
+
+  /** Apply the byte-window defaults and cap; a window above the cap is refused, not shortened. */
+  private resolveWindow(range: WorkspaceByteRange, path: string): { offset: number; length: number } {
+    const offset = range.offset === undefined ? 0 : integerAtLeast(range.offset, 0, 'offset')
+    const length = range.length === undefined ? this.config.maxBytes : integerAtLeast(range.length, 1, 'length')
+    if (offset + length > Number.MAX_SAFE_INTEGER) {
+      throw new RemoteError('gateway/bad-request', 'offset plus length must stay a safe integer', {})
+    }
+    if (length > this.config.maxBytes) {
+      throw new RemoteError(
+        'workspace-file/too-large',
+        `${length} bytes of "${path}" exceed the ${this.config.maxBytes} byte cap`,
+        { path, limit: this.config.maxBytes },
+      )
+    }
+    return { offset, length }
+  }
+
+
+  /**
+   * The workspace root comes from the policy, not from the backend's own cwd
+   * default: the `minimal` preset shadows the host provider with a bare
+   * `fs-local` whose cwd differs, and resolving explicitly makes the answer
+   * the same whichever instance answers.
+   */
+  private workspaceRootOf(agent: Agent): string {
+    return this.ctx.sandboxPolicy.resolve({ session: agent.session }).workspaceRoot
+  }
+
+  /**
+   * Gates 1 and 2 up to the point where the path's own type is known. The
+   * path is inspected before containment is decided, so a caller learns whether
+   * an outside path exists and what kind it is before `outside-workspace`
+   * refuses it; the caller is the Session's own owner, who can read the Host
+   * through the Agent anyway, and the accepted cost buys one `lstat` gate for
+   * every method instead of two resolution orders.
+   */
+  private async inspect(
+    agent: Agent,
+    path: string,
+    signal: AbortSignal,
+  ): Promise<{ root: FsTarget; workspaceRoot: string; entry: FsPathInfo }> {
+    if (path.length === 0) throw new RemoteError('gateway/bad-request', 'path is required', {})
+    const workspaceRoot = this.workspaceRootOf(agent)
+    const root = await this.ctx.fs.resolve(workspaceRoot, { signal })
+    // Gate on the path itself before anything follows it.
+    const entry = await this.ctx.fs.lstat(path, { cwd: workspaceRoot }, signal)
+    if (entry === undefined) {
+      throw new RemoteError('workspace-file/not-found', `no entry at "${path}"`, { path })
+    }
+    return { root, workspaceRoot, entry }
+  }
+
+  /** Resolve an inspected path and refuse it unless the workspace contains it. */
+  private async confine(root: FsTarget, workspaceRoot: string, path: string, signal: AbortSignal): Promise<FsTarget> {
+    const target = await this.ctx.fs.resolve(path, { cwd: workspaceRoot, signal })
+    if (!this.ctx.fs.contains(root, target)) {
+      throw new RemoteError('workspace-file/outside-workspace', `"${path}" is outside the workspace`, { path })
+    }
+    return target
+  }
+
+  /**
+   * All gates for a regular file, ending in the one stat that names its version
+   * and size. The stat re-checks what `lstat` saw: the file may have gone or
+   * changed kind in between.
+   */
+  private async locateFile(agent: Agent, path: string, signal: AbortSignal): Promise<{ target: FsTarget; info: FsInfo }> {
+    const { root, workspaceRoot, entry } = await this.inspect(agent, path, signal)
+    if (entry.type !== 'file') {
+      throw new RemoteError('workspace-file/not-regular-file', `"${path}" is a ${entry.type}`, { path, kind: entry.type })
+    }
+    const target = await this.confine(root, workspaceRoot, path, signal)
+    const info = await this.ctx.fs.stat(target, signal)
+    if (info === undefined) {
+      throw new RemoteError('workspace-file/not-found', `no entry at "${path}"`, { path })
+    }
+    if (info.type !== 'file') {
+      throw new RemoteError('workspace-file/not-regular-file', `"${path}" is a ${info.type}`, { path, kind: info.type })
+    }
+    return { target, info }
+  }
+
+  private statOf(target: FsTarget, info: FsInfo): WorkspaceFileStat {
+    return {
+      absolutePath: this.ctx.fs.processPath(target),
+      version: info.version,
+      ...info.size === undefined ? {} : { bytes: info.size },
+    }
+  }
+
+  /** Stream the file as text and cut the page, classifying the backend's non-text refusal. */
+  private async cutPage(target: FsTarget, offset: number, limit: number, signal: AbortSignal, path: string): Promise<Page> {
+    try {
+      return await cutPage(await this.ctx.fs.streamText(target, signal), offset, limit, this.config.maxBytes, path)
+    } catch (error: unknown) {
+      if (isNotTextRefusal(error)) {
+        throw new RemoteError('workspace-file/not-text', `"${path}" is not UTF-8 text`, { path }, { cause: error })
+      }
+      throw error
+    }
+  }
+}
+
+/**
+ * The backend's non-text refusal, recognized by its code alone: the error class
+ * belongs to whichever `dsh-fs` instance the provider loaded, so no class
+ * identity is shared across the package boundary.
+ */
+function isNotTextRefusal(error: unknown): boolean {
+  return typeof error === 'object' && error !== null && 'code' in error && error.code === 'FS_NOT_TEXT'
+}
+
+export default WorkspaceFiles
diff --git a/packages/api/workspace-files/src/types.ts b/packages/api/workspace-files/src/types.ts
new file mode 100644
index 0000000000..83aad4841f
--- /dev/null
+++ b/packages/api/workspace-files/src/types.ts
@@ -0,0 +1,166 @@
+/**
+ * Wire types of the `workspaceFiles` Remote namespace. Types only: generated
+ * Remote clients consume this module without Host runtime code.
+ *
+ * Two path vocabularies leave here, and each method uses exactly one:
+ *
+ * - `read`, `readBytes`, `stat`, and `changes` name a file by its absolute path in the
+ *   filesystem's execution world, because their consumer is the Client
+ *   resource system, whose `dsh-resource://file/session/<id>/<path>` address carries that
+ *   same path.
+ * - `list` speaks workspace paths — the same syntax its `path` argument accepts —
+ *   because its consumer is a tree rooted at the workspace root.
+ *
+ * @module @deepseek-ai/dsh-api-workspace-files/types
+ */
+
+// Import the protocol module so the declaration at the end of this file
+// augments its error map rather than defining an unrelated ambient module.
+import type {} from '@deepseek-ai/dsh-typert-protocol'
+
+/** Identity and freshness of one workspace file, without its content. */
+export interface WorkspaceFileStat {
+  /**
+   * Absolute path of the file in the filesystem's execution world, symlinks
+   * resolved: `/`-separated on POSIX, drive-rooted with the platform separator
+   * on Windows. What a `dsh-resource://file/absolute/…` address carries, and
+   * what a `dsh-resource://file/session/<sessionId>/…` address's
+   * workspace-relative path resolves to against that Session's root.
+   */
+  readonly absolutePath: string
+  /** Opaque freshness token at the time of the stat; never parsed. */
+  readonly version: string
+  /** Byte size of the complete file, when the backend reports it. */
+  readonly bytes?: number
+}
+
+/**
+ * The line window one `read` returns. Lines are 1-based and end at `\n`; a
+ * final `\n` terminates the last line rather than starting an empty one.
+ */
+export interface WorkspaceFileRange {
+  /** First line of the page. Defaults to 1. */
+  readonly offset?: number
+  /** Largest number of lines on the page. Defaults to, and may not exceed, the configured `maxLines`. */
+  readonly limit?: number
+}
+
+/** One page of a workspace text file as a Client reads it. */
+export interface WorkspaceFileText extends WorkspaceFileStat {
+  /** First line of the page, as requested. */
+  readonly offset: number
+  /**
+   * The page's lines joined by `\n`, without a terminator after the last one.
+   * Empty for a page past the file's last line and for a page holding one
+   * empty line; `lines` tells them apart.
+   */
+  readonly text: string
+  /** How many lines the page holds; `0` when `offset` lies past the file's last line. */
+  readonly lines: number
+  /** Whether the page includes the file's last line. */
+  readonly eof: boolean
+}
+
+/** The byte window one `readBytes` returns. Offsets are 0-based. */
+export interface WorkspaceByteRange {
+  /** First byte of the window. Defaults to 0. */
+  readonly offset?: number
+  /** Largest number of bytes in the window. Defaults to, and may not exceed, the configured `maxBytes`. */
+  readonly length?: number
+}
+
+/**
+ * One byte window of a workspace file as a Client reads it: raw bytes, no text
+ * decoding and no binary rejection. `bytes` is the complete file's size.
+ */
+export interface WorkspaceFileBytes extends WorkspaceFileStat {
+  /** First byte of the window, as requested. */
+  readonly offset: number
+  /** The window's bytes in base64; empty when `offset` lies at or past the file's end. */
+  readonly data: string
+  /** Whether the window includes the file's last byte. */
+  readonly eof: boolean
+}
+
+/** One direct child of a listed workspace directory. */
+export interface WorkspaceDirectoryEntry {
+  /** Basename inside the listed directory. */
+  readonly name: string
+  /**
+   * What the child resolves to. A symlink reports the type of its destination,
+   * and `other` covers everything that is neither a regular file nor a
+   * directory; `read` still refuses a symlink, so `file` here is a listing fact,
+   * not a promise that the content is readable.
+   */
+  readonly type: 'file' | 'directory' | 'other'
+  /** Byte size, present only for a regular file whose backend reports it. */
+  readonly size?: number
+}
+
+/** Direct children of one workspace directory. */
+export interface WorkspaceDirectoryListing {
+  /**
+   * The listed directory as a workspace path, relative to the workspace root
+   * and empty for the root itself. A child's path is this value joined with
+   * {@link WorkspaceDirectoryEntry.name} by `/`.
+   */
+  readonly path: string
+  /**
+   * Direct children in the backend's stable name order, cut to the configured
+   * entry cap. Presentation order is the caller's choice.
+   */
+  readonly entries: readonly WorkspaceDirectoryEntry[]
+  /** Whether the entry cap dropped children from {@link entries}. */
+  readonly truncated: boolean
+}
+
+/**
+ * One observation of a workspace file made by an Agent's own filesystem
+ * operation. Frames report observations, not deltas: a consumer already holding
+ * `version` learns nothing new from the frame and can ignore it.
+ */
+export type WorkspaceFileChange =
+  | {
+    /** Absolute path of the observed file, in the same form as {@link WorkspaceFileStat.absolutePath}. */
+    readonly absolutePath: string
+    /** Opaque freshness token after the observed operation; never parsed. */
+    readonly version: string
+  }
+  | {
+    /** Absolute path of the observed file, in the same form as {@link WorkspaceFileStat.absolutePath}. */
+    readonly absolutePath: string
+    /** The file was observed to be gone. */
+    readonly absent: true
+  }
+
+/**
+ * One frame of a workspace file watch generation. `ready` confirms that the
+ * Host is observing filesystem operations and has resolved the workspace
+ * root; observations queued during that resolution follow as `change` frames.
+ */
+export type WorkspaceFileWatchFrame =
+  | { readonly kind: 'ready' }
+  | { readonly kind: 'change'; readonly change: WorkspaceFileChange }
+
+declare module '@deepseek-ai/dsh-typert-protocol' {
+  interface RemoteErrorDetailsMap {
+    /** No entry exists at that path inside the workspace. */
+    'workspace-file/not-found': { readonly path: string }
+    /** The path resolves outside the session's workspace root. */
+    'workspace-file/outside-workspace': { readonly path: string }
+    /** The requested page exceeds the configured byte cap; nothing is returned. */
+    'workspace-file/too-large': { readonly path: string; readonly limit: number }
+    /** The content read so far is not decodable UTF-8 text, or the page carries NUL bytes. */
+    'workspace-file/not-text': { readonly path: string }
+    /** The path is not a regular file, so it has no text to read. */
+    'workspace-file/not-regular-file': {
+      readonly path: string
+      readonly kind: 'directory' | 'symlink' | 'other'
+    }
+    /** The path is not a directory, so it has no children to list. */
+    'workspace-file/not-directory': {
+      readonly path: string
+      readonly kind: 'file' | 'symlink' | 'other'
+    }
+  }
+}
diff --git a/packages/api/workspace-files/tests/apply.client.spec.ts b/packages/api/workspace-files/tests/apply.client.spec.ts
new file mode 100644
index 0000000000..5153814358
--- /dev/null
+++ b/packages/api/workspace-files/tests/apply.client.spec.ts
@@ -0,0 +1,61 @@
+/**
+ * The plugin body: one `file` provider registered into `ctx.resources` for the
+ * fiber's lifetime, reading through `ctx.remote` and resolving addresses
+ * authorizing absolute addresses through the current `ctx.sessions` entry.
+ */
+import { Context } from '@deepseek-ai/cordis'
+import type { ResourceProvider } from '@deepseek-ai/dsh-client-resources/client'
+import { absoluteFileAddress, sessionFileAddress } from '@deepseek-ai/dsh-util-workspace-path'
+import { describe, expect, it, onTestFinished } from 'vitest'
+import { apply, inject } from '../src/client/index.ts'
+import { FakeRemote, settle } from './fake-remote.client.ts'
+
+describe('workspace-files client apply', () => {
+  it('registers the file provider over ctx.remote and ctx.sessions, and unregisters it with the fiber', async () => {
+    const ctx = new Context()
+    const remote = new FakeRemote()
+    const controller = new AbortController()
+    const pulls: Array<Promise<unknown>> = []
+    ctx.provide('remote', remote as never)
+    ctx.provide('remote.workspaceFiles', remote.workspaceFiles as never)
+    // No Session summary or cwd is available; only absolute addresses need current.
+    ctx.provide('sessions', {
+      list: { getSnapshot: () => ({ byId: {}, current: 's1' }) },
+    } as never)
+    const registered: Array<ResourceProvider<'file'>> = []
+    let released = 0
+    ctx.provide('resources', {
+      register: (provider: ResourceProvider<'file'>) => {
+        registered.push(provider)
+        return () => {
+          released++
+          controller.abort()
+          for (const request of remote.stats) {
+            request.resolve({ ok: true, value: { absolutePath: '/host/late-stat', version: 'v0' } })
+          }
+        }
+      },
+    } as never)
+    const fiber = ctx.plugin({ inject: [...inject], apply })
+    onTestFinished(async () => {
+      await fiber.dispose()
+      await Promise.all(pulls)
+    })
+    await fiber.await()
+
+    expect(registered.map(provider => provider.protocol)).toEqual(['file'])
+    const signal = controller.signal
+    // A session address reaches the Host as its relative path; an absolute one
+    // is read through the current Session with its absolute path.
+    pulls.push(registered[0]!.open(sessionFileAddress('s1', 'a.txt'), { signal })[Symbol.asyncIterator]().next())
+    pulls.push(registered[0]!.open(absoluteFileAddress('/etc/hosts'), { signal })[Symbol.asyncIterator]().next())
+    await settle()
+    expect(remote.stats.map(pending => [pending.sessionId, pending.path])).toEqual([['s1', 'a.txt'], ['s1', '/etc/hosts']])
+    expect(remote.opened).toHaveLength(1)
+
+    await fiber.dispose()
+    await Promise.all(pulls)
+    expect(released).toBe(1)
+    expect(remote.opened[0]!.source.aborted).toBe(true)
+  })
+})
diff --git a/packages/api/workspace-files/tests/change-feed.client.spec.ts b/packages/api/workspace-files/tests/change-feed.client.spec.ts
new file mode 100644
index 0000000000..9fe3ed4c73
--- /dev/null
+++ b/packages/api/workspace-files/tests/change-feed.client.spec.ts
@@ -0,0 +1,289 @@
+/**
+ * The change feed's promises: one Host stream per session, delivery by absolute
+ * path, local stat requests, and a follower's life bounded by its signal or by
+ * the stream's end.
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { describe, expect, it } from 'vitest'
+import { ChangeFeed } from '../src/client/change-feed.ts'
+import type { WorkspaceFileWatchFrame } from '../src/types.ts'
+import { FakeRemote, peek, settle } from './fake-remote.client.ts'
+
+const S1 = 's1' as SessionId
+const S2 = 's2' as SessionId
+
+function harness() {
+  const remote = new FakeRemote()
+  const feed = new ChangeFeed(remote)
+  const follow = (sessionId: SessionId, path: string, controller = new AbortController()) => {
+    const follower = feed.follow(sessionId, path, controller.signal)
+    follower.bind(path)
+    return { it: follower[Symbol.asyncIterator](), controller }
+  }
+  return { remote, feed, follow }
+}
+
+describe('ChangeFeed — one Host stream per session', () => {
+  it('starts a later follower from the existing session acknowledgement without opening another stream', async () => {
+    const { remote, feed } = harness()
+    const controller = new AbortController()
+    const first = feed.follow(S1, 'first-resource', controller.signal)
+    try {
+      await expect(first.ready).resolves.toBe(true)
+      const second = feed.follow(S1, 'second-resource', controller.signal)
+      await expect(second.ready).resolves.toBe(true)
+      expect(remote.calls).toEqual(['changes', 'accept'])
+      expect(remote.opened).toHaveLength(1)
+
+      second.bind('/w/second.txt')
+      const iterator = second[Symbol.asyncIterator]()
+      await remote.opened[0]!.source.deliver({
+        kind: 'change', change: { absolutePath: '/w/second.txt', version: 'v1' },
+      })
+      await expect(iterator.next()).resolves.toEqual({ done: false, value: { kind: 'changed', version: 'v1' } })
+      controller.abort()
+      await expect(iterator.next()).resolves.toEqual({ done: true, value: undefined })
+      await feed.settle()
+      expect(remote.disposed).toEqual(['workspace file changes of s1'])
+    } finally {
+      controller.abort()
+      await feed.settle()
+    }
+  })
+
+  it('shares one stream among the followers of a session and opens another per session', async () => {
+    const { remote, follow } = harness()
+    follow(S1, '/w/a.txt')
+    follow(S1, '/w/b.txt')
+    await settle()
+    expect(remote.opened.map(o => o.sessionId)).toEqual([S1])
+    follow(S2, '/w/a.txt')
+    await settle()
+    expect(remote.opened.map(o => o.sessionId)).toEqual([S1, S2])
+  })
+
+  it('disposes the session stream when its last follower leaves and reopens for the next', async () => {
+    const { remote, follow } = harness()
+    const a = follow(S1, '/w/a.txt')
+    const b = follow(S1, '/w/b.txt')
+    await settle()
+    a.controller.abort()
+    await settle()
+    expect(remote.disposed).toEqual([])
+    b.controller.abort()
+    await settle()
+    expect(remote.disposed).toEqual(['workspace file changes of s1'])
+    expect(remote.opened[0]!.source.aborted).toBe(true)
+    follow(S1, '/w/c.txt')
+    await settle()
+    expect(remote.opened).toHaveLength(2)
+  })
+
+  it('opens the next stream of a session only after the previous dispose settled, and settle() waits for it', async () => {
+    const { remote, feed, follow } = harness()
+    let release!: () => void
+    remote.disposeGate = new Promise<void>((resolve) => { release = resolve })
+    const a = follow(S1, '/w/a.txt')
+    await settle()
+    a.controller.abort()
+    await settle()
+    expect(remote.disposed).toEqual(['workspace file changes of s1'])
+    // The next follower registers at once, but its Host stream waits for the close.
+    follow(S1, '/w/b.txt')
+    await settle()
+    expect(remote.opened).toHaveLength(1)
+    let settled = false
+    void feed.settle().then(() => { settled = true })
+    await settle()
+    expect(settled).toBe(false)
+    release()
+    await settle()
+    expect(remote.opened).toHaveLength(2)
+    expect(settled).toBe(true)
+    // Nothing left closing: settle() resolves at once.
+    await feed.settle()
+  })
+
+  it('keeps waiting for the newest close when two closes of one session overlap', async () => {
+    const { remote, feed, follow } = harness()
+    let release!: () => void
+    remote.disposeGate = new Promise<void>((resolve) => { release = resolve })
+    const a = follow(S1, '/w/a.txt')
+    await settle()
+    a.controller.abort()
+    await settle()
+    // The second feed waits for the first close, then its only follower leaves too.
+    const b = follow(S1, '/w/b.txt')
+    await settle()
+    b.controller.abort()
+    await settle()
+    let settled = false
+    void feed.settle().then(() => { settled = true })
+    release()
+    await settle()
+    await settle()
+    expect(settled).toBe(true)
+    expect(remote.disposed).toHaveLength(2)
+    follow(S1, '/w/c.txt')
+    await settle()
+    expect(remote.opened).toHaveLength(3)
+  })
+
+  it('treats a dispose that rejects as settled, so the next stream still opens', async () => {
+    const { remote, feed, follow } = harness()
+    // Rejected only once dispose() has taken the gate, so the rejection always has a handler.
+    let fail!: (error: Error) => void
+    remote.disposeGate = new Promise<void>((_resolve, reject) => { fail = reject })
+    const a = follow(S1, '/w/a.txt')
+    await settle()
+    a.controller.abort()
+    await settle()
+    follow(S1, '/w/b.txt')
+    await settle()
+    expect(remote.opened).toHaveLength(1)
+    fail(new Error('carrier gone'))
+    await settle()
+    expect(remote.opened).toHaveLength(2)
+    await feed.settle()
+  })
+})
+
+describe('ChangeFeed — delivery', () => {
+  it('routes a frame to the followers of its path, whichever separator the Host spells', async () => {
+    const { remote, follow } = harness()
+    // A stat and a change frame may spell the same Host path with different separators.
+    const mine = follow(S1, 'C:/w/a b.txt')
+    const twin = follow(S1, 'C:/w/a b.txt')
+    const other = follow(S1, 'C:/w/other.txt')
+    await settle()
+    const source = remote.opened[0]!.source
+    source.push({ kind: 'change', change: { absolutePath: 'C:/w/a b.txt', version: 'v1' } })
+    source.push({ kind: 'change', change: { absolutePath: 'C:\\w\\a b.txt', absent: true } })
+    await expect(mine.it.next()).resolves.toEqual({ done: false, value: { kind: 'changed', version: 'v1' } })
+    await expect(mine.it.next()).resolves.toEqual({ done: false, value: { kind: 'absent' } })
+    await expect(twin.it.next()).resolves.toEqual({ done: false, value: { kind: 'changed', version: 'v1' } })
+    await expect(peek(other.it)).resolves.toBe('silent')
+    // One follower of a path leaving does not silence the other.
+    mine.controller.abort()
+    await settle()
+    source.push({ kind: 'change', change: { absolutePath: 'C:/w/a b.txt', version: 'v2' } })
+    await expect(twin.it.next()).resolves.toEqual({ done: false, value: { kind: 'absent' } })
+    await expect(twin.it.next()).resolves.toEqual({ done: false, value: { kind: 'changed', version: 'v2' } })
+  })
+
+  it('queues frames reported before the consumer starts pulling', async () => {
+    const { remote, follow } = harness()
+    const mine = follow(S1, '/w/a.txt')
+    await settle()
+    remote.opened[0]!.source.push({ kind: 'change', change: { absolutePath: '/w/a.txt', version: 'v1' } })
+    await settle()
+    await expect(mine.it.next()).resolves.toEqual({ done: false, value: { kind: 'changed', version: 'v1' } })
+  })
+
+  it('keeps sessions apart', async () => {
+    const { remote, follow } = harness()
+    const one = follow(S1, '/w/a.txt')
+    const two = follow(S2, '/w/a.txt')
+    await settle()
+    remote.opened[1]!.source.push({ kind: 'change', change: { absolutePath: '/w/a.txt', version: 'v2' } })
+    await expect(two.it.next()).resolves.toEqual({ done: false, value: { kind: 'changed', version: 'v2' } })
+    await expect(peek(one.it)).resolves.toBe('silent')
+  })
+
+  it('hands a stat request to the followers of that path only', async () => {
+    const { feed, follow } = harness()
+    const mine = follow(S1, '/w/a.txt')
+    const other = follow(S1, '/w/b.txt')
+    await settle()
+    feed.requestRestat(S1, '/w/a.txt')
+    feed.requestRestat(S2, '/w/a.txt')
+    feed.requestRestat(S1, '/w/nobody.txt')
+    await expect(mine.it.next()).resolves.toEqual({ done: false, value: { kind: 'restat' } })
+    await expect(peek(other.it)).resolves.toBe('silent')
+  })
+})
+
+describe('ChangeFeed — a follower ends', () => {
+  it('ends every follower and disposes the session stream for an unknown wire frame kind', async () => {
+    const { remote, feed } = harness()
+    const controller = new AbortController()
+    const first = feed.follow(S1, 'first-resource', controller.signal)
+    const second = feed.follow(S1, 'second-resource', controller.signal)
+    const firstIterator = first[Symbol.asyncIterator]()
+    const secondIterator = second[Symbol.asyncIterator]()
+    try {
+      await expect(Promise.all([first.ready, second.ready])).resolves.toEqual([true, true])
+      const endings = Promise.all([firstIterator.next(), secondIterator.next()])
+      const source = remote.opened[0]!.source
+      // The Remote double supplies decoded wire data, including an unknown protocol tag.
+      const wireFrame: unknown = JSON.parse('{"kind":"future-frame"}')
+      source.push(wireFrame as WorkspaceFileWatchFrame)
+      await expect(endings).resolves.toEqual([
+        { done: true, value: undefined },
+        { done: true, value: undefined },
+      ])
+      await feed.settle()
+      expect(source.aborted).toBe(true)
+      expect(remote.disposed).toEqual(['workspace file changes of s1'])
+      expect(remote.opened).toHaveLength(1)
+    } finally {
+      controller.abort()
+      await Promise.all([firstIterator.return?.(), secondIterator.return?.()])
+      await feed.settle()
+    }
+  })
+
+  it('ends on its signal and drops nothing queued before it', async () => {
+    const { remote, follow } = harness()
+    const mine = follow(S1, '/w/a.txt')
+    await settle()
+    remote.opened[0]!.source.push({ kind: 'change', change: { absolutePath: '/w/a.txt', version: 'v1' } })
+    await settle()
+    mine.controller.abort()
+    await expect(mine.it.next()).resolves.toEqual({ done: false, value: { kind: 'changed', version: 'v1' } })
+    await expect(mine.it.next()).resolves.toEqual({ done: true, value: undefined })
+  })
+
+  it('is empty when the signal is already aborted, without opening a stream', async () => {
+    const { remote, feed } = harness()
+    const controller = new AbortController()
+    controller.abort()
+    const it = feed.follow(S1, '/w/a.txt', controller.signal)[Symbol.asyncIterator]()
+    await expect(it.next()).resolves.toEqual({ done: true, value: undefined })
+    await settle()
+    expect(remote.opened).toEqual([])
+  })
+
+  it('unregisters when the consumer breaks out after a notice', async () => {
+    const { remote, follow } = harness()
+    const mine = follow(S1, '/w/a.txt')
+    await settle()
+    remote.opened[0]!.source.push({ kind: 'change', change: { absolutePath: '/w/a.txt', version: 'v1' } })
+    await mine.it.next()
+    await mine.it.return?.()
+    await settle()
+    expect(remote.disposed).toEqual(['workspace file changes of s1'])
+  })
+
+  it('ends every follower when the Host closes the session stream', async () => {
+    const { remote, follow } = harness()
+    const a = follow(S1, '/w/a.txt')
+    const b = follow(S1, '/w/b.txt')
+    await settle()
+    remote.opened[0]!.source.end()
+    await expect(a.it.next()).resolves.toEqual({ done: true, value: undefined })
+    await expect(b.it.next()).resolves.toEqual({ done: true, value: undefined })
+    // The next follower starts a fresh stream rather than joining the dead one.
+    follow(S1, '/w/c.txt')
+    await settle()
+    expect(remote.opened).toHaveLength(2)
+  })
+
+  it('ends every follower when the session stream fails', async () => {
+    const { remote, follow } = harness()
+    const a = follow(S1, '/w/a.txt')
+    await settle()
+    remote.opened[0]!.source.fail(new Error('carrier gone for good'))
+    await expect(a.it.next()).resolves.toEqual({ done: true, value: undefined })
+  })
+})
diff --git a/packages/api/workspace-files/tests/changes.spec.ts b/packages/api/workspace-files/tests/changes.spec.ts
new file mode 100644
index 0000000000..452dbaabee
--- /dev/null
+++ b/packages/api/workspace-files/tests/changes.spec.ts
@@ -0,0 +1,289 @@
+/** The `changes` stream: driven by `fs/observed`, filtered by the workspace root, ended by its signal. */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { join } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import type { FsObservation } from '@deepseek-ai/dsh-fs'
+import { FsVersion } from '@deepseek-ai/dsh-fs'
+import { WorkspaceFiles } from '../src/index.ts'
+import type { WorkspaceFileWatchFrame } from '../src/types.ts'
+import { agent, openWorkspace, type Harness } from './harness.ts'
+
+let harness: Harness
+const closeStreams: Array<() => Promise<unknown>> = []
+
+beforeEach(async () => {
+  harness = await openWorkspace('dsh-workspace-files-changes-')
+})
+
+afterEach(async () => {
+  try {
+    for (const close of closeStreams.splice(0)) await close()
+    await harness.dispose()
+  } finally {
+    vi.restoreAllMocks()
+  }
+})
+
+/** Emit one observation for `path` the way a tool does after touching it. */
+async function observe(path: string, observation: FsObservation): Promise<string> {
+  const target = await harness.ctx.fs.resolve(path)
+  harness.ctx.emit('fs/observed', target, observation, undefined)
+  return harness.ctx.fs.processPath(target)
+}
+
+const present = (version: string): FsObservation => ({ kind: 'present', version: FsVersion(version) })
+
+/** Own one generation through abort and iterator completion, including failed assertions. */
+function open(
+  service: WorkspaceFiles,
+  controller = new AbortController(),
+): { next(): Promise<IteratorResult<WorkspaceFileWatchFrame>>; controller: AbortController } {
+  const iterator = service.changes(agent, controller.signal)[Symbol.asyncIterator]()
+  closeStreams.push(async () => {
+    controller.abort()
+    await iterator.return?.()
+  })
+  return { next: () => iterator.next(), controller }
+}
+
+describe('workspaceFiles.changes — frames', () => {
+  it('acknowledges the resolved root before draining observations queued during root resolution', async () => {
+    const service = harness.endpoint()
+    const fs = harness.ctx.fs
+    const original = fs.resolve.bind(fs)
+    const root = await original(harness.workspace)
+    const entered = Promise.withResolvers<AbortSignal | undefined>()
+    const release = Promise.withResolvers<undefined>()
+    vi.spyOn(fs, 'resolve').mockImplementation(async (path, opts) => {
+      if (path !== harness.workspace) return original(path, opts)
+      entered.resolve(opts?.signal)
+      await release.promise
+      opts?.signal?.throwIfAborted()
+      return root
+    })
+    const stream = open(service)
+    const first = stream.next()
+    let acknowledged = false
+    void first.then(() => { acknowledged = true })
+    try {
+      expect(await entered.promise).toBe(stream.controller.signal)
+      const a = await observe(join(harness.workspace, 'early-a.txt'), present('a1'))
+      await observe(join(harness.outside, 'secret.txt'), present('outside'))
+      const b = await observe(join(harness.workspace, 'early-b.txt'), { kind: 'absent' })
+      expect(acknowledged).toBe(false)
+      release.resolve(undefined)
+      await expect(first).resolves.toEqual({ done: false, value: { kind: 'ready' } })
+      await expect(stream.next()).resolves.toEqual({
+        done: false, value: { kind: 'change', change: { absolutePath: a, version: 'a1' } },
+      })
+      await expect(stream.next()).resolves.toEqual({
+        done: false, value: { kind: 'change', change: { absolutePath: b, absent: true } },
+      })
+    } finally {
+      release.resolve(undefined)
+    }
+  })
+
+  it('reports a present observation inside the workspace as its absolute path and version', async () => {
+    const stream = open(harness.endpoint())
+    await expect(stream.next()).resolves.toEqual({ done: false, value: { kind: 'ready' } })
+    const pending = stream.next()
+    const absolutePath = await observe(join(harness.workspace, 'a.txt'), present('v1'))
+    expect(await pending).toEqual({ done: false, value: { kind: 'change', change: { absolutePath, version: 'v1' } } })
+    expect(absolutePath).toBe(harness.ctx.fs.processPath(await harness.ctx.fs.resolve(join(harness.workspace, 'a.txt'))))
+  })
+
+  it('reports an absent observation as absent', async () => {
+    const stream = open(harness.endpoint())
+    await expect(stream.next()).resolves.toEqual({ done: false, value: { kind: 'ready' } })
+    const pending = stream.next()
+    const absolutePath = await observe(join(harness.workspace, 'gone.txt'), { kind: 'absent' })
+    expect(await pending).toEqual({ done: false, value: { kind: 'change', change: { absolutePath, absent: true } } })
+  })
+
+  it('drops observations outside the workspace root', async () => {
+    const stream = open(harness.endpoint())
+    await expect(stream.next()).resolves.toEqual({ done: false, value: { kind: 'ready' } })
+    const pending = stream.next()
+    await observe(join(harness.outside, 'secret.txt'), present('v1'))
+    const absolutePath = await observe(join(harness.workspace, 'seen.txt'), present('v2'))
+    expect(await pending).toEqual({ done: false, value: { kind: 'change', change: { absolutePath, version: 'v2' } } })
+  })
+
+  it('queues observations made faster than they are pulled, in emission order', async () => {
+    const stream = open(harness.endpoint())
+    await expect(stream.next()).resolves.toEqual({ done: false, value: { kind: 'ready' } })
+    const first = stream.next()
+    const a = await observe(join(harness.workspace, 'a.txt'), present('a1'))
+    const b = await observe(join(harness.workspace, 'b.txt'), present('b1'))
+    expect(await first).toEqual({ done: false, value: { kind: 'change', change: { absolutePath: a, version: 'a1' } } })
+    expect(await stream.next()).toEqual({ done: false, value: { kind: 'change', change: { absolutePath: b, version: 'b1' } } })
+  })
+
+  it('serves every open generation independently', async () => {
+    const service = harness.endpoint()
+    const one = open(service)
+    const two = open(service)
+    await expect(one.next()).resolves.toEqual({ done: false, value: { kind: 'ready' } })
+    await expect(two.next()).resolves.toEqual({ done: false, value: { kind: 'ready' } })
+    const firstOfOne = one.next()
+    const firstOfTwo = two.next()
+    const absolutePath = await observe(join(harness.workspace, 'a.txt'), present('v1'))
+    expect(await firstOfOne).toEqual({ done: false, value: { kind: 'change', change: { absolutePath, version: 'v1' } } })
+    expect(await firstOfTwo).toEqual({ done: false, value: { kind: 'change', change: { absolutePath, version: 'v1' } } })
+  })
+})
+
+describe('workspaceFiles.changes — ending', () => {
+  it('does not acknowledge a subscription disposed while its workspace root is resolving', async () => {
+    const fs = harness.ctx.fs
+    const original = fs.resolve.bind(fs)
+    const root = await original(harness.workspace)
+    const entered = Promise.withResolvers<undefined>()
+    const release = Promise.withResolvers<undefined>()
+    vi.spyOn(fs, 'resolve').mockImplementation(async (path, opts) => {
+      if (path !== harness.workspace) return original(path, opts)
+      entered.resolve(undefined)
+      await release.promise
+      return root
+    })
+    let service: WorkspaceFiles | undefined
+    const fiber = await harness.ctx.plugin(Object.assign((ctx: Context) => {
+      service = new WorkspaceFiles(ctx, { maxBytes: 1, maxLines: 1, maxEntries: 1 })
+    }, { inject: ['fs', 'sandboxPolicy'] }))
+    try {
+      if (service === undefined) throw new Error('plugin body did not run')
+      const stream = open(service)
+      const first = stream.next()
+      await entered.promise
+      await fiber.dispose()
+      release.resolve(undefined)
+      await expect(first).resolves.toEqual({ done: true, value: undefined })
+    } finally {
+      release.resolve(undefined)
+      await fiber.dispose()
+    }
+  })
+
+  it('refuses an already-aborted signal', async () => {
+    const controller = new AbortController()
+    controller.abort()
+    const stream = open(harness.endpoint(), controller)
+    await expect(stream.next()).rejects.toThrow()
+  })
+
+  it('ends when its signal aborts while idle', async () => {
+    const stream = open(harness.endpoint())
+    await expect(stream.next()).resolves.toEqual({ done: false, value: { kind: 'ready' } })
+    const first = stream.next()
+    // A delivered frame proves the generation is past setup and waiting idle.
+    await observe(join(harness.workspace, 'a.txt'), present('v1'))
+    expect((await first).done).toBe(false)
+    const pending = stream.next()
+    stream.controller.abort()
+    expect(await pending).toEqual({ done: true, value: undefined })
+  })
+
+  it('drops queued observations when cancelled after ready but before the next pull', async () => {
+    const stream = open(harness.endpoint())
+    await expect(stream.next()).resolves.toEqual({ done: false, value: { kind: 'ready' } })
+    await observe(join(harness.workspace, 'queued-before-abort.txt'), present('v1'))
+    stream.controller.abort()
+    await expect(stream.next()).resolves.toEqual({ done: true, value: undefined })
+  })
+
+  it('ends when its signal aborts during setup, without delivering anything', async () => {
+    const stream = open(harness.endpoint())
+    const pending = stream.next()
+    stream.controller.abort()
+    await observe(join(harness.workspace, 'a.txt'), present('v1'))
+    expect(await pending).toEqual({ done: true, value: undefined })
+  })
+
+  it('ends when its signal aborts while the root resolves, resolving under that signal', async () => {
+    const fs = harness.ctx.fs
+    const original = fs.resolve.bind(fs)
+    let release: () => void = () => {}
+    const gate = new Promise<void>((resolve) => { release = resolve })
+    // A backend that checks the signal after its round-trip, as a remote one does.
+    const spy = vi.spyOn(fs, 'resolve').mockImplementation(async (path, opts) => {
+      await gate
+      opts?.signal?.throwIfAborted()
+      return original(path, opts)
+    })
+    const stream = open(harness.endpoint())
+    const pending = stream.next()
+    stream.controller.abort()
+    release()
+    expect(await pending).toEqual({ done: true, value: undefined })
+    expect(spy).toHaveBeenCalledWith(expect.any(String), { signal: stream.controller.signal })
+    spy.mockRestore()
+  })
+
+  it('ends when its signal aborts between the root resolving and the first pull', async () => {
+    const fs = harness.ctx.fs
+    const original = fs.resolve.bind(fs)
+    const controller = new AbortController()
+    // The abort lands after the backend answered and before the drain installs its listener.
+    const spy = vi.spyOn(fs, 'resolve').mockImplementation(async (path, opts) => {
+      const target = await original(path, opts)
+      controller.abort()
+      return target
+    })
+    const stream = open(harness.endpoint(), controller)
+    expect(await stream.next()).toEqual({ done: true, value: undefined })
+    spy.mockRestore()
+  })
+
+  it('surfaces a root that fails to resolve', async () => {
+    const spy = vi.spyOn(harness.ctx.fs, 'resolve').mockRejectedValue(new Error('no such root'))
+    const stream = open(harness.endpoint())
+    await expect(stream.next()).rejects.toThrow('no such root')
+    spy.mockRestore()
+  })
+
+  it('stops delivering to a generation the consumer returned from', async () => {
+    const service = harness.endpoint()
+    const controller = new AbortController()
+    const iterator = service.changes(agent, controller.signal)[Symbol.asyncIterator]()
+    closeStreams.push(async () => {
+      controller.abort()
+      await iterator.return?.()
+    })
+    await expect(iterator.next()).resolves.toEqual({ done: false, value: { kind: 'ready' } })
+    const first = iterator.next()
+    const absolutePath = await observe(join(harness.workspace, 'a.txt'), present('v1'))
+    expect(await first).toEqual({ done: false, value: { kind: 'change', change: { absolutePath, version: 'v1' } } })
+    expect(await iterator.return?.(undefined)).toEqual({ done: true, value: undefined })
+    // A later observation reaches no follower: the set is empty again, so the
+    // second generation opened here is the only one that sees it.
+    const stream = open(service)
+    await expect(stream.next()).resolves.toEqual({ done: false, value: { kind: 'ready' } })
+    const pending = stream.next()
+    const later = await observe(join(harness.workspace, 'b.txt'), present('v2'))
+    expect(await pending).toEqual({ done: false, value: { kind: 'change', change: { absolutePath: later, version: 'v2' } } })
+  })
+
+  it('ends every open generation when the owning fiber is disposed', async () => {
+    let service: WorkspaceFiles | undefined
+    const fiber = await harness.ctx.plugin(Object.assign((ctx: Context) => {
+      service = new WorkspaceFiles(ctx, { maxBytes: 1, maxLines: 1, maxEntries: 1 })
+    }, { inject: ['fs', 'sandboxPolicy'] }))
+    if (service === undefined) throw new Error('plugin body did not run')
+    const stream = open(service)
+    await expect(stream.next()).resolves.toEqual({ done: false, value: { kind: 'ready' } })
+    const first = stream.next()
+    await observe(join(harness.workspace, 'a.txt'), present('v0'))
+    expect((await first).done).toBe(false)
+    const pending = stream.next()
+    await fiber.dispose()
+    expect(await pending).toEqual({ done: true, value: undefined })
+    // The listener left with the fiber: a fresh generation on a live service
+    // proves the root context still observes while the disposed one is silent.
+    const live = open(harness.endpoint())
+    await expect(live.next()).resolves.toEqual({ done: false, value: { kind: 'ready' } })
+    const next = live.next()
+    const absolutePath = await observe(join(harness.workspace, 'a.txt'), present('v1'))
+    expect(await next).toEqual({ done: false, value: { kind: 'change', change: { absolutePath, version: 'v1' } } })
+  })
+})
diff --git a/packages/api/workspace-files/tests/fake-remote.client.ts b/packages/api/workspace-files/tests/fake-remote.client.ts
new file mode 100644
index 0000000000..c34ca31256
--- /dev/null
+++ b/packages/api/workspace-files/tests/fake-remote.client.ts
@@ -0,0 +1,178 @@
+/**
+ * The Remote slice, scripted: stats answered by the spec, one push source per
+ * opened `changes` generation, and a supervisor that runs one generation and
+ * classifies its end the way the real one does.
+ */
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { WorkspaceFileWatchFrame, WorkspaceFileStat } from '../src/types.ts'
+import type { SupervisedStream, SupervisedStreamOptions, WorkspaceFilesRemote } from '../src/client/remote.ts'
+
+/** One scripted Host `changes` generation: frames pushed by the spec, ended by abort. */
+export class Source<T> implements AsyncIterable<T> {
+  private readonly queue: Array<
+    { kind: 'value'; value: T; delivered?: () => void } | { kind: 'end' } | { kind: 'fail'; error: unknown }
+  > = []
+  private wake: (() => void) | undefined
+  aborted = false
+
+  constructor(signal: AbortSignal) {
+    this.aborted = signal.aborted
+    signal.addEventListener('abort', () => {
+      this.aborted = true
+      this.wake?.()
+    }, { once: true })
+  }
+
+  push(value: T): void {
+    this.queue.push({ kind: 'value', value })
+    this.wake?.()
+  }
+
+  /** Resolve after the consumer processes this frame and asks for the next one. */
+  deliver(value: T): Promise<void> {
+    return new Promise((resolve) => {
+      this.queue.push({ kind: 'value', value, delivered: resolve })
+      this.wake?.()
+    })
+  }
+
+  end(): void {
+    this.queue.push({ kind: 'end' })
+    this.wake?.()
+  }
+
+  fail(error: unknown): void {
+    this.queue.push({ kind: 'fail', error })
+    this.wake?.()
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterator<T> {
+    while (true) {
+      if (this.aborted) return
+      const next = this.queue.shift()
+      if (next === undefined) {
+        await new Promise<void>((resolve) => { this.wake = resolve })
+        this.wake = undefined
+        continue
+      }
+      if (next.kind === 'value') {
+        yield next.value
+        next.delivered?.()
+        continue
+      }
+      if (next.kind === 'end') return
+      throw next.error
+    }
+  }
+}
+
+/** One `stat` call awaiting the spec's answer. */
+export interface PendingStat {
+  readonly sessionId: SessionId
+  readonly path: string
+  readonly signal: AbortSignal | undefined
+  resolve(result: RemoteResult<WorkspaceFileStat>): void
+}
+
+/** One opened Host watch whose acknowledgement and changes the spec controls. */
+interface OpenedWatch {
+  readonly sessionId: SessionId
+  readonly source: Source<WorkspaceFileWatchFrame>
+}
+
+/** The scripted Remote: every stat waits for the spec, every session stream is a {@link Source}. */
+export class FakeRemote implements WorkspaceFilesRemote {
+  readonly calls: Array<'changes' | 'accept' | 'stat'> = []
+  readonly opened: OpenedWatch[] = []
+  readonly disposed: string[] = []
+  readonly stats: PendingStat[] = []
+  private readonly statWaiters = new Map<number, Array<(stat: PendingStat) => void>>()
+  private readonly watchWaiters = new Map<number, Array<(watch: OpenedWatch) => void>>()
+  /** False lets a spec keep the Host subscription unacknowledged. */
+  autoReady = true
+  /** When set, every stream dispose waits for it before settling. */
+  disposeGate: Promise<void> | undefined
+
+  /** Wait for an indexed stat request without advancing or assuming scheduler timing. */
+  waitForStat(index: number): Promise<PendingStat> {
+    const stat = this.stats[index]
+    if (stat !== undefined) return Promise.resolve(stat)
+    return new Promise((resolve) => {
+      const waiters = this.statWaiters.get(index) ?? []
+      waiters.push(resolve)
+      this.statWaiters.set(index, waiters)
+    })
+  }
+
+  /** Wait until the Client calls changes, independently of the Host acknowledgement. */
+  waitForChanges(index: number): Promise<OpenedWatch> {
+    const watch = this.opened[index]
+    if (watch !== undefined) return Promise.resolve(watch)
+    return new Promise((resolve) => {
+      const waiters = this.watchWaiters.get(index) ?? []
+      waiters.push(resolve)
+      this.watchWaiters.set(index, waiters)
+    })
+  }
+
+  $stream<Item>(options: SupervisedStreamOptions<Item>): SupervisedStream<Item> {
+    const controller = new AbortController()
+    const disposed = this.disposed
+    const calls = this.calls
+    const done = Promise.withResolvers<undefined>()
+    return {
+      async *[Symbol.asyncIterator]() {
+        try {
+          let accepted = false
+          for await (const value of options.open(controller.signal)) {
+            if (controller.signal.aborted) return
+            yield { value, accept: () => { accepted = true; calls.push('accept') } }
+          }
+          if (controller.signal.aborted) return
+          throw options.ended(accepted)
+        } finally {
+          done.resolve(undefined)
+        }
+      },
+      dispose: async () => {
+        disposed.push(options.name)
+        controller.abort(new Error('disposed'))
+        await this.disposeGate
+        await done.promise
+      },
+    }
+  }
+
+  readonly workspaceFiles = {
+    stat: (sessionId: SessionId, path: string, signal?: AbortSignal): Promise<RemoteResult<WorkspaceFileStat>> =>
+      new Promise((resolve) => {
+        this.calls.push('stat')
+        const index = this.stats.length
+        const stat = { sessionId, path, signal, resolve }
+        this.stats.push(stat)
+        for (const waiter of this.statWaiters.get(index) ?? []) waiter(stat)
+        this.statWaiters.delete(index)
+      }),
+    changes: (sessionId: SessionId, signal?: AbortSignal): AsyncIterable<WorkspaceFileWatchFrame> => {
+      this.calls.push('changes')
+      if (signal === undefined) throw new Error('the feed must hand its signal to the Host stream')
+      const source = new Source<WorkspaceFileWatchFrame>(signal)
+      const watch = { sessionId, source }
+      const index = this.opened.length
+      this.opened.push(watch)
+      for (const waiter of this.watchWaiters.get(index) ?? []) waiter(watch)
+      this.watchWaiters.delete(index)
+      if (this.autoReady) source.push({ kind: 'ready' })
+      return source
+    },
+  }
+}
+
+/** Let queued microtasks and background pumps settle. */
+export const settle = (): Promise<void> => new Promise((resolve) => { setTimeout(resolve, 0) })
+
+/** The next item, or `'silent'` when none arrives within a tick. */
+export async function peek<T>(it: AsyncIterator<T>): Promise<IteratorResult<T> | 'silent'> {
+  return Promise.race([it.next(), settle().then(() => 'silent' as const)])
+}
diff --git a/packages/api/workspace-files/tests/harness.ts b/packages/api/workspace-files/tests/harness.ts
new file mode 100644
index 0000000000..2b1a5ece77
--- /dev/null
+++ b/packages/api/workspace-files/tests/harness.ts
@@ -0,0 +1,94 @@
+/**
+ * Shared fixture: a real local backend over a temp workspace beside a sibling
+ * directory outside it, and a sandbox policy whose only job is naming the root.
+ *
+ * The real backend, not a mocked `ctx.fs`, because the gates under test are
+ * only meaningful against a real filesystem: a symlink that leaves the
+ * workspace, a file whose byte size exceeds the cap, and bytes that are not
+ * text. A fake provider would let a string-prefix containment check pass this
+ * file, which is exactly the defect the gate exists to prevent.
+ */
+import { mkdir, mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
+import { remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol'
+import { WorkspaceFiles, type Config } from '../src/index.ts'
+
+/** The Agent shape the service reads: only its session reaches the policy. */
+export const agent = { id: 'a-test', session: { id: 's-test' } } as unknown as Agent
+
+export const signal = (): AbortSignal => new AbortController().signal
+
+/** One temp workspace and the context serving it. */
+export interface Harness {
+  readonly workspace: string
+  readonly outside: string
+  readonly ctx: Context
+  /**
+   * The service under test, at the given caps. One per test: the service key is
+   * global to the Context, so a second call with caps is a defect in the test.
+   */
+  endpoint(caps?: Partial<Config>): WorkspaceFiles
+  dispose(): Promise<void>
+}
+
+/**
+ * Create the workspace, its outside sibling, and a context with the local
+ * backend rooted at the workspace.
+ * @param prefix - temp directory prefix naming the suite.
+ * @returns the harness; dispose it in `afterEach`.
+ */
+export async function openWorkspace(prefix: string): Promise<Harness> {
+  const root = await mkdtemp(join(tmpdir(), prefix))
+  const workspace = join(root, 'workspace')
+  const outside = join(root, 'outside')
+  await mkdir(workspace, { recursive: true })
+  await mkdir(outside, { recursive: true })
+  const ctx = new Context()
+  const fiber = await ctx.plugin(LocalFileSystem, { cwd: workspace })
+  // The policy is the service's only source for the workspace root, so the
+  // fake supplies exactly that and nothing else.
+  ctx.provide('sandboxPolicy', { resolve: () => ({ mode: 'workspace-write', workspaceRoot: workspace }) } as never)
+  let service: WorkspaceFiles | undefined
+  return {
+    workspace,
+    outside,
+    ctx,
+    endpoint: (caps) => {
+      if (service !== undefined) {
+        if (caps !== undefined) throw new Error('the harness serves one WorkspaceFiles per test; hoist the endpoint')
+        return service
+      }
+      service = new WorkspaceFiles(ctx, {
+        maxBytes: caps?.maxBytes ?? 1024 * 1024,
+        maxLines: caps?.maxLines ?? 5000,
+        maxEntries: caps?.maxEntries ?? 2000,
+      })
+      return service
+    },
+    dispose: async () => {
+      await fiber.dispose()
+      await rm(root, { recursive: true, force: true })
+    },
+  }
+}
+
+/**
+ * Await an operation expected to fail with a Remote error.
+ * @param operation - the call under test.
+ * @returns the Remote failure's code and details.
+ */
+export async function failureOf(operation: Promise<unknown>): Promise<{ code: string; details: unknown }> {
+  try {
+    await operation
+  } catch (error: unknown) {
+    const failure = remoteErrorOf(error)
+    // A non-Remote throw is a defect in the service, not an expected outcome.
+    if (failure === undefined) throw error
+    return { code: failure.code, details: failure.details }
+  }
+  throw new Error('expected the operation to fail')
+}
diff --git a/packages/api/workspace-files/tests/host-path.client.spec.ts b/packages/api/workspace-files/tests/host-path.client.spec.ts
new file mode 100644
index 0000000000..306222f6d7
--- /dev/null
+++ b/packages/api/workspace-files/tests/host-path.client.spec.ts
@@ -0,0 +1,260 @@
+/** Host-resolved file identities across pending stats, retries, reloads, and disposal. */
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
+import { absoluteFileAddress, sessionFileAddress } from '@deepseek-ai/dsh-util-workspace-path'
+import { describe, expect, it, onTestFinished } from 'vitest'
+import { ChangeFeed } from '../src/client/change-feed.ts'
+import { createFileResourceProvider, type SessionLookup } from '../src/client/provider.ts'
+import { FakeRemote, settle } from './fake-remote.client.ts'
+
+const SESSION = 'host-only' as SessionId
+const RELATIVE = 'linked/a b.txt'
+const ADDRESS = sessionFileAddress(SESSION, RELATIVE)
+const CANONICAL = '/host/canonical/a b.txt'
+
+function harness(sessions: SessionLookup = { current: () => SESSION }) {
+  const remote = new FakeRemote()
+  const changes = new ChangeFeed(remote)
+  const provider = createFileResourceProvider(remote, changes, sessions)
+  const open = (address = ADDRESS) => {
+    const controller = new AbortController()
+    const iterator = provider.open(address, { signal: controller.signal })[Symbol.asyncIterator]()
+    onTestFinished(async () => {
+      controller.abort()
+      for (const request of remote.stats) {
+        request.resolve({ ok: false, error: new RemoteError('gateway/internal', 'test ended', {}) })
+      }
+      await iterator.return?.()
+      await changes.settle()
+    })
+    return { iterator, controller, reload: () => { provider.reload!(address) } }
+  }
+  return { remote, changes, open }
+}
+
+describe('Host-resolved file paths', () => {
+  it('accepts Host ready before submitting the unmodified relative path without a Client Session summary', async () => {
+    const { remote, open } = harness({ current: () => { throw new Error('session addresses do not read current') } })
+    const { iterator } = open()
+    const first = iterator.next()
+    const request = await remote.waitForStat(0)
+    expect(remote.calls).toEqual(['changes', 'accept', 'stat'])
+    expect(request).toMatchObject({ sessionId: SESSION, path: RELATIVE })
+    request.resolve({ ok: true, value: { absolutePath: CANONICAL, version: 'v0', bytes: 3 } })
+    await expect(first).resolves.toEqual({ done: false, value: { ok: true, value: { absolutePath: CANONICAL, version: 'v0', bytes: 3, changed: false } } })
+  })
+
+  it('does not stat an opened changes stream until the Host acknowledges its subscription', async () => {
+    const { remote, open } = harness()
+    remote.autoReady = false
+    const { iterator } = open()
+    const first = iterator.next()
+    const { source } = await remote.waitForChanges(0)
+    await settle()
+    expect(remote.calls).toEqual(['changes'])
+    expect(remote.stats).toEqual([])
+
+    await source.deliver({ kind: 'ready' })
+    const request = await remote.waitForStat(0)
+    expect(remote.calls).toEqual(['changes', 'accept', 'stat'])
+    request.resolve({ ok: true, value: { absolutePath: CANONICAL, version: 'v0' } })
+    await expect(first).resolves.toEqual({ done: false, value: { ok: true, value: { absolutePath: CANONICAL, version: 'v0', changed: false } } })
+  })
+
+  it.each(['abort', 'end', 'failure'] as const)('settles %s before Host ready without sending a stat or leaving a stream', async (ending) => {
+    const { remote, changes, open } = harness()
+    remote.autoReady = false
+    const { iterator, controller } = open()
+    const first = iterator.next()
+    const { source } = await remote.waitForChanges(0)
+    switch (ending) {
+      case 'abort': controller.abort(); break
+      case 'end': source.end(); break
+      case 'failure': source.fail(new Error('workspace root unavailable')); break
+      default: throw new Error(`Unexpected stream ending: ${ending satisfies never}`)
+    }
+    await expect(first).resolves.toEqual({ done: true, value: undefined })
+    await changes.settle()
+    expect(remote.calls).toEqual(['changes'])
+    expect(remote.stats).toEqual([])
+    expect(remote.disposed).toEqual([`workspace file changes of ${SESSION}`])
+    expect(source.aborted).toBe(true)
+  })
+
+  it('accepts another generation ready without resetting metadata or re-statting existing files', async () => {
+    const { remote, open } = harness()
+    const { iterator } = open()
+    const first = iterator.next()
+    const request = await remote.waitForStat(0)
+    request.resolve({ ok: true, value: { absolutePath: CANONICAL, version: 'v0', bytes: 3 } })
+    await first
+    const next = iterator.next()
+    const source = remote.opened[0]!.source
+    await source.deliver({ kind: 'ready' })
+    await source.deliver({ kind: 'change', change: { absolutePath: CANONICAL, version: 'v1' } })
+    expect(remote.stats).toHaveLength(1)
+    expect(remote.calls).toEqual(['changes', 'accept', 'stat', 'accept'])
+    await expect(next).resolves.toEqual({ done: false, value: { ok: true, value: { absolutePath: CANONICAL, version: 'v1', bytes: 3, changed: true } } })
+  })
+
+  it.each([
+    ['session', ADDRESS, RELATIVE],
+    ['absolute', absoluteFileAddress('/shortcut/a.txt'), '/shortcut/a.txt'],
+  ])('filters queued and live %s changes using the Host canonical path, not the input path', async (_, address, path) => {
+    const { remote, open } = harness()
+    const { iterator } = open(address)
+    const first = iterator.next()
+    const request = await remote.waitForStat(0)
+    expect(request).toMatchObject({ sessionId: SESSION, path })
+    const source = remote.opened[0]!.source
+    // Delivery is acknowledged while stat is still unresolved, before a key can be bound.
+    await source.deliver({ kind: 'change', change: { absolutePath: '/other/file.txt', version: 'other-before-stat' } })
+    await source.deliver({ kind: 'change', change: { absolutePath: CANONICAL, version: 'v1' } })
+    request.resolve({ ok: true, value: { absolutePath: CANONICAL, version: 'v0', bytes: 3 } })
+    await expect(first).resolves.toMatchObject({ value: { ok: true, value: { version: 'v0', changed: false } } })
+    await expect(iterator.next()).resolves.toEqual({ done: false, value: { ok: true, value: { absolutePath: CANONICAL, version: 'v1', bytes: 3, changed: true } } })
+
+    await source.deliver({ kind: 'change', change: { absolutePath: '/other/file.txt', version: 'other-after-stat' } })
+    await source.deliver({ kind: 'change', change: { absolutePath: CANONICAL, version: 'v2' } })
+    await expect(iterator.next()).resolves.toMatchObject({ value: { ok: true, value: { version: 'v2', changed: true } } })
+    expect(remote.stats).toHaveLength(1)
+  })
+
+  it.each(['reload', 'write'] as const)('recovers an initial failed stat through %s and filters the retry backlog after binding', async (trigger) => {
+    const { remote, open } = harness()
+    const { iterator, reload } = open()
+    const first = iterator.next()
+    const request = await remote.waitForStat(0)
+    const error = new RemoteError('workspace-file/not-found', 'missing', { path: RELATIVE })
+    request.resolve({ ok: false, error })
+    await expect(first).resolves.toEqual({ done: false, value: { ok: false, error } })
+    const source = remote.opened[0]!.source
+    const retried = iterator.next()
+    if (trigger === 'reload') reload()
+    else await source.deliver({ kind: 'change', change: { absolutePath: '/unknown-key-trigger.txt', version: 'trigger' } })
+    const retry = await remote.waitForStat(1)
+    expect(retry).toMatchObject({ sessionId: SESSION, path: RELATIVE })
+    await source.deliver({ kind: 'change', change: { absolutePath: '/other/file.txt', version: 'other' } })
+    await source.deliver({ kind: 'change', change: { absolutePath: CANONICAL, version: 'v3' } })
+    retry.resolve({ ok: true, value: { absolutePath: CANONICAL, version: 'v2', bytes: 5 } })
+    await expect(retried).resolves.toEqual({
+      done: false, value: { ok: true, value: { absolutePath: CANONICAL, version: 'v2', bytes: 5, changed: trigger === 'write' } },
+    })
+    await expect(iterator.next()).resolves.toMatchObject({ value: { ok: true, value: { version: 'v3', changed: true } } })
+    expect(remote.stats).toHaveLength(2)
+  })
+
+  it('reloads session and absolute addresses bound to the same Host key without re-statting other files', async () => {
+    const { remote, open } = harness()
+    const session = open()
+    const absolute = open(absoluteFileAddress('/shortcut/a.txt'))
+    const other = open(sessionFileAddress(SESSION, 'other.txt'))
+    const firsts = Promise.all([session.iterator.next(), absolute.iterator.next(), other.iterator.next()])
+    await remote.waitForStat(2)
+    for (const request of remote.stats) {
+      request.resolve({ ok: true, value: {
+        absolutePath: request.path === 'other.txt' ? '/host/other.txt' : CANONICAL,
+        version: 'v0', bytes: 3,
+      } })
+    }
+    await firsts
+    const reloaded = Promise.all([session.iterator.next(), absolute.iterator.next()])
+    const otherChange = other.iterator.next()
+    session.reload()
+    await remote.waitForStat(4)
+    expect(remote.stats.slice(3).map(request => request.path)).toEqual([RELATIVE, '/shortcut/a.txt'])
+    for (const request of remote.stats.slice(3)) {
+      request.resolve({ ok: true, value: { absolutePath: CANONICAL, version: 'v1', bytes: 4 } })
+    }
+    const value = { done: false, value: { ok: true, value: { absolutePath: CANONICAL, version: 'v1', bytes: 4, changed: false } } }
+    await expect(reloaded).resolves.toEqual([value, value])
+    await remote.opened[0]!.source.deliver({ kind: 'change', change: { absolutePath: '/host/other.txt', version: 'other-v1' } })
+    await expect(otherChange).resolves.toMatchObject({ value: { ok: true, value: { version: 'other-v1', changed: true } } })
+    expect(remote.stats).toHaveLength(5)
+    expect(remote.opened).toHaveLength(1)
+  })
+
+  it('binds a changed canonical path on reload before filtering writes received during that stat', async () => {
+    const { remote, open } = harness()
+    const { iterator, reload } = open()
+    const first = iterator.next()
+    const request = await remote.waitForStat(0)
+    request.resolve({ ok: true, value: { absolutePath: '/host/old-target.txt', version: 'v0' } })
+    await first
+    reload()
+    const reloaded = iterator.next()
+    const retry = await remote.waitForStat(1)
+    const source = remote.opened[0]!.source
+    await source.deliver({ kind: 'change', change: { absolutePath: '/host/old-target.txt', version: 'old-target-write' } })
+    await source.deliver({ kind: 'change', change: { absolutePath: CANONICAL, version: 'v2' } })
+    retry.resolve({ ok: true, value: { absolutePath: CANONICAL, version: 'v1' } })
+    await expect(reloaded).resolves.toMatchObject({ value: { ok: true, value: { version: 'v1', changed: false } } })
+    await expect(iterator.next()).resolves.toMatchObject({ value: { ok: true, value: { version: 'v2', changed: true } } })
+    expect(remote.stats).toHaveLength(2)
+  })
+
+  it('drops a late stat after abort and waits for the session stream disposal', async () => {
+    const { remote, changes, open } = harness()
+    const { iterator, controller } = open()
+    const first = iterator.next()
+    const request = await remote.waitForStat(0)
+    await remote.opened[0]!.source.deliver({ kind: 'change', change: { absolutePath: CANONICAL, version: 'v1' } })
+    const gate = Promise.withResolvers<undefined>()
+    remote.disposeGate = gate.promise
+    try {
+      controller.abort()
+      request.resolve({ ok: true, value: { absolutePath: CANONICAL, version: 'v0' } })
+      await expect(first).resolves.toEqual({ done: true, value: undefined })
+      expect(remote.opened[0]!.source.aborted).toBe(true)
+      let settled = false
+      const closing = changes.settle().then(() => { settled = true })
+      await settle()
+      expect(settled).toBe(false)
+      gate.resolve(undefined)
+      await closing
+      expect(settled).toBe(true)
+      expect(remote.disposed).toEqual([`workspace file changes of ${SESSION}`])
+    } finally {
+      gate.resolve(undefined)
+    }
+  })
+
+  it('aborts while waiting for a predecessor to close without sending a stat', async () => {
+    const { remote, changes, open } = harness()
+    const previous = open()
+    const first = previous.iterator.next()
+    const request = await remote.waitForStat(0)
+    request.resolve({ ok: true, value: { absolutePath: CANONICAL, version: 'v0' } })
+    await first
+    const gate = Promise.withResolvers<undefined>()
+    remote.disposeGate = gate.promise
+    try {
+      previous.controller.abort()
+      const next = open()
+      const pending = next.iterator.next()
+      next.controller.abort()
+      await expect(pending).resolves.toEqual({ done: true, value: undefined })
+      expect(remote.stats).toHaveLength(1)
+      gate.resolve(undefined)
+      await changes.settle()
+      expect(remote.disposed).toHaveLength(2)
+    } finally {
+      gate.resolve(undefined)
+    }
+  })
+
+  it.each([true, false])('releases an unconsumed notification follower after the first stat (success: %s)', async (ok) => {
+    const { remote, changes, open } = harness()
+    const { iterator } = open()
+    const first = iterator.next()
+    const request = await remote.waitForStat(0)
+    request.resolve(ok
+      ? { ok: true, value: { absolutePath: CANONICAL, version: 'v0' } }
+      : { ok: false, error: new RemoteError('workspace-file/not-found', 'missing', { path: RELATIVE }) })
+    await first
+    await iterator.return?.()
+    await changes.settle()
+    expect(remote.opened[0]!.source.aborted).toBe(true)
+    expect(remote.disposed).toEqual([`workspace file changes of ${SESSION}`])
+  })
+})
diff --git a/packages/api/workspace-files/tests/list.spec.ts b/packages/api/workspace-files/tests/list.spec.ts
new file mode 100644
index 0000000000..cb6fc4538f
--- /dev/null
+++ b/packages/api/workspace-files/tests/list.spec.ts
@@ -0,0 +1,119 @@
+/** The `list` endpoint: the same containment gates as `read`, plus the entry cap. */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { mkdir, symlink, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { agent, failureOf, openWorkspace, signal, type Harness } from './harness.ts'
+
+let harness: Harness
+let workspace: string
+let outside: string
+
+beforeEach(async () => {
+  harness = await openWorkspace('dsh-workspace-files-list-')
+  workspace = harness.workspace
+  outside = harness.outside
+})
+
+afterEach(async () => {
+  await harness.dispose()
+})
+
+const endpoint = (caps?: { maxEntries?: number }): ReturnType<Harness['endpoint']> => harness.endpoint(caps)
+
+describe('workspaceFiles.list — the happy path', () => {
+  it('lists the root as the empty workspace path, with types and file sizes', async () => {
+    await mkdir(join(workspace, 'src'))
+    await writeFile(join(workspace, 'notes.txt'), 'hello', 'utf8')
+    await writeFile(join(workspace, '.hidden'), '', 'utf8')
+    const listing = await endpoint().list(agent, '.', signal())
+    expect(listing.path).toBe('')
+    expect(listing.truncated).toBe(false)
+    expect(listing.entries).toEqual([
+      { name: '.hidden', type: 'file', size: 0 },
+      { name: 'notes.txt', type: 'file', size: 5 },
+      { name: 'src', type: 'directory' },
+    ])
+  })
+
+  it('accepts the absolute workspace root and reports the same empty path', async () => {
+    const listing = await endpoint().list(agent, workspace, signal())
+    expect(listing.path).toBe('')
+    expect(listing.entries).toEqual([])
+  })
+
+  it('reports a nested directory as its `/`-joined path relative to the root, decoded', async () => {
+    await mkdir(join(workspace, 'src', 'my dir', '子目录'), { recursive: true })
+    await writeFile(join(workspace, 'src', 'my dir', '子目录', 'a.ts'), '', 'utf8')
+    const listing = await endpoint().list(agent, 'src/my dir/子目录', signal())
+    expect(listing.path).toBe('src/my dir/子目录')
+    expect(listing.entries.map(entry => entry.name)).toEqual(['a.ts'])
+  })
+
+  it('reports a symlink child as what it points to, and a dangling one as other', async () => {
+    await writeFile(join(workspace, 'real.txt'), 'x', 'utf8')
+    await mkdir(join(workspace, 'dir'))
+    await symlink(join(workspace, 'real.txt'), join(workspace, 'to-file'))
+    await symlink(join(workspace, 'dir'), join(workspace, 'to-dir'))
+    await symlink(join(workspace, 'missing'), join(workspace, 'dangling'))
+    const listing = await endpoint().list(agent, '.', signal())
+    expect(listing.entries).toEqual([
+      { name: 'dangling', type: 'other' },
+      { name: 'dir', type: 'directory' },
+      { name: 'real.txt', type: 'file', size: 1 },
+      { name: 'to-dir', type: 'directory' },
+      { name: 'to-file', type: 'file', size: 1 },
+    ])
+  })
+})
+
+describe('workspaceFiles.list — the entry cap', () => {
+  it('cuts at the cap in name order and says so', async () => {
+    for (const name of ['a', 'b', 'c', 'd', 'e']) await writeFile(join(workspace, name), '', 'utf8')
+    const listing = await endpoint({ maxEntries: 2 }).list(agent, '.', signal())
+    expect(listing.entries.map(entry => entry.name)).toEqual(['a', 'b'])
+    expect(listing.truncated).toBe(true)
+  })
+
+  it('does not report a cut at exactly the cap', async () => {
+    for (const name of ['a', 'b']) await writeFile(join(workspace, name), '', 'utf8')
+    const listing = await endpoint({ maxEntries: 2 }).list(agent, '.', signal())
+    expect(listing.entries).toHaveLength(2)
+    expect(listing.truncated).toBe(false)
+  })
+})
+
+describe('workspaceFiles.list — gates', () => {
+  it('rejects an absolute directory outside the workspace', async () => {
+    const failure = await failureOf(endpoint().list(agent, outside, signal()))
+    expect(failure.code).toBe('workspace-file/outside-workspace')
+  })
+
+  it('rejects a traversal that climbs out of the workspace', async () => {
+    const failure = await failureOf(endpoint().list(agent, '..', signal()))
+    expect(failure.code).toBe('workspace-file/outside-workspace')
+  })
+
+  it('rejects a symlinked directory before following it, wherever it points', async () => {
+    await symlink(outside, join(workspace, 'escape'))
+    const failure = await failureOf(endpoint().list(agent, 'escape', signal()))
+    expect(failure.code).toBe('workspace-file/not-directory')
+    expect(failure.details).toMatchObject({ kind: 'symlink' })
+  })
+
+  it('rejects a file, which has no children to list', async () => {
+    await writeFile(join(workspace, 'notes.txt'), 'hello', 'utf8')
+    const failure = await failureOf(endpoint().list(agent, 'notes.txt', signal()))
+    expect(failure.code).toBe('workspace-file/not-directory')
+    expect(failure.details).toMatchObject({ path: 'notes.txt', kind: 'file' })
+  })
+
+  it('reports a missing path as not found', async () => {
+    const failure = await failureOf(endpoint().list(agent, 'nope', signal()))
+    expect(failure.code).toBe('workspace-file/not-found')
+  })
+
+  it('refuses an empty path as a bad request', async () => {
+    const failure = await failureOf(endpoint().list(agent, '', signal()))
+    expect(failure.code).toBe('gateway/bad-request')
+  })
+})
diff --git a/packages/api/workspace-files/tests/provider.client.spec.ts b/packages/api/workspace-files/tests/provider.client.spec.ts
new file mode 100644
index 0000000000..539a3888af
--- /dev/null
+++ b/packages/api/workspace-files/tests/provider.client.spec.ts
@@ -0,0 +1,363 @@
+/**
+ * The `file` provider's frame stream: how the two address scopes resolve to a
+ * Host call and a change-feed key, the opening stat, the write flag that
+ * carries no content, the reload and disappearance that stat again, failures
+ * as frames, and the life bounded by the signal.
+ */
+import { RemoteError } from '@deepseek-ai/dsh-client-test-runtime'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { RemoteFailure } from '@deepseek-ai/dsh-typert-protocol'
+import { absoluteFileAddress, sessionFileAddress } from '@deepseek-ai/dsh-util-workspace-path'
+import type { WorkspaceFileStat } from '../src/types.ts'
+import { describe, expect, it, onTestFinished } from 'vitest'
+import { ChangeFeed } from '../src/client/change-feed.ts'
+import { createFileResourceProvider } from '../src/client/provider.ts'
+import type { SessionLookup } from '../src/client/provider.ts'
+import { FakeRemote, peek, settle } from './fake-remote.client.ts'
+
+const S1 = 's1' as SessionId
+const S2 = 's2' as SessionId
+/** The relative path the address carries, and the absolute path the Host's frames spell for it under S1's root. */
+const REL_PATH = 'a b.txt'
+const HOST_PATH = '/w/a b.txt'
+const ADDRESS = sessionFileAddress(S1, REL_PATH)
+/** A file outside every workspace root, addressed absolutely. */
+const ABS_PATH = '/etc/hosts'
+const ABS_ADDRESS = absoluteFileAddress(ABS_PATH)
+
+/** Only the current Session is available to the provider; there are no Client roots. */
+function sessionsWith(current: SessionId | undefined): SessionLookup {
+  return { current: () => current }
+}
+
+const stat = (version: string, bytes: number): WorkspaceFileStat => ({ absolutePath: HOST_PATH, version, bytes })
+const notFound = (): RemoteFailure => new RemoteError('workspace-file/not-found', 'no such file', { path: REL_PATH })
+
+function opened(address = ADDRESS, sessions = sessionsWith(S1)) {
+  const remote = new FakeRemote()
+  const changes = new ChangeFeed(remote)
+  const provider = createFileResourceProvider(remote, changes, sessions)
+  const controller = new AbortController()
+  const it = provider.open(address, { signal: controller.signal })[Symbol.asyncIterator]()
+  const reload = (): void => { provider.reload!(address) }
+  onTestFinished(async () => {
+    controller.abort()
+    for (const request of remote.stats) {
+      request.resolve({ ok: false, error: new RemoteError('gateway/internal', 'test ended', {}) })
+    }
+    await it.return?.()
+    await changes.settle()
+  })
+  return { remote, provider, changes, controller, it, reload }
+}
+
+/** Open, answer the opening stat, and hand back the bench once the first frame is out. */
+async function live(version = 'v0', bytes = 3) {
+  const bench = opened()
+  const first = bench.it.next()
+  await settle()
+  bench.remote.stats[0]!.resolve({ ok: true, value: stat(version, bytes) })
+  await first
+  return bench
+}
+
+describe('file provider — the address', () => {
+  it.each([
+    ['another scope', 'dsh-resource://file/shared/x/w/a.txt'],
+    ['no path', 'dsh-resource://file/session/s1'],
+    ['an absolute address with no path', 'dsh-resource://file/absolute/'],
+    ['another resource type', 'dsh-resource://terminal/session/s1/1'],
+    ['the retired file:// grammar', 'file://sessions/s1/w/a.txt'],
+    ['a bare file URL', 'file:///w/a.txt'],
+    ['another protocol', 'sidebar:guide'],
+  ])('yields one unsupported-address failure and ends for %s, touching no Remote', async (_, address) => {
+    const { remote, it } = opened(address)
+    const first = await it.next()
+    expect(first.done).toBe(false)
+    expect(first.value).toMatchObject({ ok: false, error: { code: 'workspace-file/unsupported-address', details: { address } } })
+    await expect(it.next()).resolves.toEqual({ done: true, value: undefined })
+    expect(remote.stats).toEqual([])
+    expect(remote.opened).toEqual([])
+  })
+
+  it('rejects an absolute address with no current Session without touching the Remote', async () => {
+    const address = ABS_ADDRESS
+    const { remote, it } = opened(address, sessionsWith(undefined))
+    const first = await it.next()
+    expect(first.done).toBe(false)
+    expect(first.value).toMatchObject({ ok: false, error: { code: 'workspace-file/unknown-workspace', details: { address } } })
+    await expect(it.next()).resolves.toEqual({ done: true, value: undefined })
+    expect(remote.stats).toEqual([])
+    expect(remote.opened).toEqual([])
+  })
+
+  it('reloads nothing for an address it does not resolve', async () => {
+    for (const bench of [opened('dsh-resource://file/shared/x/w/a.txt'), opened(ABS_ADDRESS, sessionsWith(undefined))]) {
+      bench.reload()
+      await settle()
+      expect(bench.remote.stats).toEqual([])
+    }
+  })
+
+  it('hands the Host a session address\'s relative path and follows the stat absolute path', async () => {
+    const { remote, it } = opened()
+    const first = it.next()
+    await settle()
+    expect(remote.stats[0]).toMatchObject({ sessionId: S1, path: REL_PATH })
+    remote.stats[0]!.resolve({ ok: true, value: stat('v0', 3) })
+    await first
+    // The Host's frame names the file absolutely; the follower keyed by the resolved path receives it.
+    remote.opened[0]!.source.push({ kind: 'change', change: { absolutePath: HOST_PATH, version: 'v1' } })
+    await expect(it.next()).resolves.toMatchObject({ value: { ok: true, value: { version: 'v1', changed: true } } })
+  })
+
+  it('reads an absolute address through the Session on screen, with the absolute path as both Host path and follow key', async () => {
+    const { remote, it, reload } = opened(ABS_ADDRESS)
+    const first = it.next()
+    await settle()
+    expect(remote.opened.map(o => o.sessionId)).toEqual([S1])
+    expect(remote.stats[0]).toMatchObject({ sessionId: S1, path: ABS_PATH })
+    remote.stats[0]!.resolve({ ok: true, value: { absolutePath: ABS_PATH, version: 'v0', bytes: 3 } })
+    await expect(first).resolves.toEqual({ done: false, value: { ok: true, value: { absolutePath: ABS_PATH, version: 'v0', bytes: 3, changed: false } } })
+    remote.opened[0]!.source.push({ kind: 'change', change: { absolutePath: ABS_PATH, version: 'v1' } })
+    await expect(it.next()).resolves.toMatchObject({ value: { ok: true, value: { version: 'v1', changed: true } } })
+    // A reload stats the same absolute path again.
+    reload()
+    const next = it.next()
+    await settle()
+    expect(remote.stats[1]).toMatchObject({ sessionId: S1, path: ABS_PATH })
+    remote.stats[1]!.resolve({ ok: true, value: { absolutePath: ABS_PATH, version: 'v1', bytes: 4 } })
+    await expect(next).resolves.toEqual({ done: false, value: { ok: true, value: { absolutePath: ABS_PATH, version: 'v1', bytes: 4, changed: false } } })
+  })
+
+  it('opens one change stream per session named by the addresses', async () => {
+    const remote = new FakeRemote()
+    const provider = createFileResourceProvider(remote, new ChangeFeed(remote), sessionsWith(S1))
+    const signal = new AbortController().signal
+    void provider.open(sessionFileAddress(S1, 'a.txt'), { signal })[Symbol.asyncIterator]().next()
+    void provider.open(sessionFileAddress(S2, 'a.txt'), { signal })[Symbol.asyncIterator]().next()
+    await settle()
+    expect(remote.opened.map(o => o.sessionId)).toEqual([S1, S2])
+    expect(remote.stats.map(pending => pending.sessionId)).toEqual([S1, S2])
+  })
+})
+
+describe('file provider — the opening stat', () => {
+  it('stats the decoded relative path in the session the address names and yields its metadata unflagged', async () => {
+    const { remote, it, controller } = opened()
+    const first = it.next()
+    await settle()
+    expect(remote.stats).toHaveLength(1)
+    expect(remote.stats[0]).toMatchObject({ sessionId: S1, path: REL_PATH, signal: controller.signal })
+    remote.stats[0]!.resolve({ ok: true, value: stat('v0', 3) })
+    await expect(first).resolves.toEqual({ done: false, value: { ok: true, value: { absolutePath: HOST_PATH, version: 'v0', bytes: 3, changed: false } } })
+  })
+
+  it('omits bytes when the backend reports none', async () => {
+    const { remote, it } = opened()
+    const first = it.next()
+    await settle()
+    remote.stats[0]!.resolve({ ok: true, value: { absolutePath: HOST_PATH, version: 'v0' } })
+    await expect(first).resolves.toStrictEqual({ done: false, value: { ok: true, value: { absolutePath: HOST_PATH, version: 'v0', changed: false } } })
+  })
+
+  it('yields the Host failure as a frame and keeps following the address', async () => {
+    const { remote, it } = opened()
+    const first = it.next()
+    await settle()
+    const error = notFound()
+    remote.stats[0]!.resolve({ ok: false, error })
+    await expect(first).resolves.toEqual({ done: false, value: { ok: false, error } })
+    const source = remote.opened[0]!.source
+    // Still gone: no stat, no frame; the pull stays open for what comes next.
+    source.push({ kind: 'change', change: { absolutePath: HOST_PATH, absent: true } })
+    const pending = it.next()
+    await expect(Promise.race([pending, settle().then(() => 'silent' as const)])).resolves.toBe('silent')
+    expect(remote.stats).toHaveLength(1)
+    // The agent creates the file: the write stats again and the value goes live, flagged as changed.
+    source.push({ kind: 'change', change: { absolutePath: HOST_PATH, version: 'v1' } })
+    await settle()
+    remote.stats[1]!.resolve({ ok: true, value: stat('v1', 5) })
+    await expect(pending).resolves.toEqual({ done: false, value: { ok: true, value: { absolutePath: HOST_PATH, version: 'v1', bytes: 5, changed: true } } })
+  })
+
+  it('lets a reload retry a failed opening stat', async () => {
+    const { remote, it, reload } = opened()
+    const first = it.next()
+    await settle()
+    remote.stats[0]!.resolve({ ok: false, error: notFound() })
+    await first
+    reload()
+    const next = it.next()
+    await settle()
+    remote.stats[1]!.resolve({ ok: true, value: stat('v0', 3) })
+    await expect(next).resolves.toEqual({ done: false, value: { ok: true, value: { absolutePath: HOST_PATH, version: 'v0', bytes: 3, changed: false } } })
+  })
+
+  it('ends without a frame when aborted during the stat', async () => {
+    const { remote, it, controller } = opened()
+    const first = it.next()
+    await settle()
+    controller.abort()
+    remote.stats[0]!.resolve({ ok: false, error: new RemoteError('gateway/internal', 'aborted', {}) })
+    await expect(first).resolves.toEqual({ done: true, value: undefined })
+  })
+
+  it('shares one change stream between two files of a session', async () => {
+    const remote = new FakeRemote()
+    const provider = createFileResourceProvider(remote, new ChangeFeed(remote), sessionsWith(S1))
+    const signal = new AbortController().signal
+    void provider.open(sessionFileAddress(S1, 'a.txt'), { signal })[Symbol.asyncIterator]().next()
+    void provider.open(sessionFileAddress(S1, 'b.txt'), { signal })[Symbol.asyncIterator]().next()
+    await settle()
+    expect(remote.opened).toHaveLength(1)
+    expect(remote.stats).toHaveLength(2)
+  })
+})
+
+describe('file provider — Host writes', () => {
+  it('flags a write with its version and keeps the byte count', async () => {
+    const { remote, it } = await live()
+    remote.opened[0]!.source.push({ kind: 'change', change: { absolutePath: HOST_PATH, version: 'v1' } })
+    await expect(it.next()).resolves.toEqual({ done: false, value: { ok: true, value: { absolutePath: HOST_PATH, version: 'v1', bytes: 3, changed: true } } })
+    expect(remote.stats).toHaveLength(1)
+  })
+
+  it('ignores a frame carrying the version it already holds', async () => {
+    const { remote, it } = await live('v0')
+    const source = remote.opened[0]!.source
+    source.push({ kind: 'change', change: { absolutePath: HOST_PATH, version: 'v0' } })
+    // The pull outlives the silent tick: the frame that finally answers it is v1.
+    const pending = it.next()
+    await expect(Promise.race([pending, settle().then(() => 'silent' as const)])).resolves.toBe('silent')
+    source.push({ kind: 'change', change: { absolutePath: HOST_PATH, version: 'v1' } })
+    await expect(pending).resolves.toMatchObject({ value: { ok: true, value: { version: 'v1', changed: true } } })
+  })
+
+  it('does not lose a write reported during the opening stat', async () => {
+    const { remote, it } = opened()
+    const first = it.next()
+    await settle()
+    remote.opened[0]!.source.push({ kind: 'change', change: { absolutePath: HOST_PATH, version: 'v1' } })
+    await settle()
+    remote.stats[0]!.resolve({ ok: true, value: stat('v0', 3) })
+    await expect(first).resolves.toMatchObject({ value: { ok: true, value: { version: 'v0', changed: false } } })
+    await expect(it.next()).resolves.toMatchObject({ value: { ok: true, value: { version: 'v1', changed: true } } })
+  })
+})
+
+describe('file provider — a reported disappearance', () => {
+  it('stats again and, when the file is still there, yields its fresh metadata flagged', async () => {
+    const { remote, it } = await live('v0', 3)
+    remote.opened[0]!.source.push({ kind: 'change', change: { absolutePath: HOST_PATH, absent: true } })
+    const next = it.next()
+    await settle()
+    expect(remote.stats).toHaveLength(2)
+    remote.stats[1]!.resolve({ ok: true, value: stat('v2', 9) })
+    await expect(next).resolves.toEqual({ done: false, value: { ok: true, value: { absolutePath: HOST_PATH, version: 'v2', bytes: 9, changed: true } } })
+  })
+
+  it('yields the not-found frame and keeps following, so a later write stats again and brings the file back flagged', async () => {
+    const { remote, it } = await live('v0', 3)
+    const source = remote.opened[0]!.source
+    source.push({ kind: 'change', change: { absolutePath: HOST_PATH, absent: true } })
+    const next = it.next()
+    await settle()
+    const error = notFound()
+    remote.stats[1]!.resolve({ ok: false, error })
+    await expect(next).resolves.toEqual({ done: false, value: { ok: false, error } })
+    source.push({ kind: 'change', change: { absolutePath: HOST_PATH, version: 'v3' } })
+    const back = it.next()
+    await settle()
+    remote.stats[2]!.resolve({ ok: true, value: stat('v3', 8) })
+    await expect(back).resolves.toEqual({ done: false, value: { ok: true, value: { absolutePath: HOST_PATH, version: 'v3', bytes: 8, changed: true } } })
+  })
+})
+
+describe('file provider — reload', () => {
+  it('stats again and clears the flag', async () => {
+    const { remote, it, reload } = await live('v0', 3)
+    remote.opened[0]!.source.push({ kind: 'change', change: { absolutePath: HOST_PATH, version: 'v1' } })
+    await it.next()
+    reload()
+    const next = it.next()
+    await settle()
+    expect(remote.stats).toHaveLength(2)
+    expect(remote.stats[1]).toMatchObject({ sessionId: S1, path: REL_PATH })
+    remote.stats[1]!.resolve({ ok: true, value: stat('v1', 7) })
+    await expect(next).resolves.toEqual({ done: false, value: { ok: true, value: { absolutePath: HOST_PATH, version: 'v1', bytes: 7, changed: false } } })
+  })
+
+  it('yields a failed stat as a frame and keeps the stream open', async () => {
+    const { remote, it, reload } = await live()
+    reload()
+    const next = it.next()
+    await settle()
+    const error = notFound()
+    remote.stats[1]!.resolve({ ok: false, error })
+    await expect(next).resolves.toEqual({ done: false, value: { ok: false, error } })
+    await expect(peek(it)).resolves.toBe('silent')
+  })
+
+  it('ends quietly when aborted during the stat', async () => {
+    const { remote, it, reload, controller } = await live()
+    reload()
+    const next = it.next()
+    await settle()
+    controller.abort()
+    remote.stats[1]!.resolve({ ok: false, error: new RemoteError('gateway/internal', 'aborted', {}) })
+    await expect(next).resolves.toEqual({ done: true, value: undefined })
+  })
+
+  it('re-stats every record of the path on one record\'s reload: a session record and an absolute record of one file share it', async () => {
+    const remote = new FakeRemote()
+    const provider = createFileResourceProvider(remote, new ChangeFeed(remote), sessionsWith(S1))
+    const signal = new AbortController().signal
+    const session = provider.open(ADDRESS, { signal })[Symbol.asyncIterator]()
+    const absolute = provider.open(absoluteFileAddress(HOST_PATH), { signal })[Symbol.asyncIterator]()
+    const firsts = Promise.all([session.next(), absolute.next()])
+    await settle()
+    expect(remote.stats.map(pending => [pending.sessionId, pending.path])).toEqual([[S1, REL_PATH], [S1, HOST_PATH]])
+    remote.stats[0]!.resolve({ ok: true, value: stat('v0', 3) })
+    remote.stats[1]!.resolve({ ok: true, value: stat('v0', 3) })
+    await firsts
+    expect(remote.opened).toHaveLength(1)
+    // One Host write flags both records: they follow one path.
+    remote.opened[0]!.source.push({ kind: 'change', change: { absolutePath: HOST_PATH, version: 'v1' } })
+    await expect(session.next()).resolves.toMatchObject({ value: { ok: true, value: { version: 'v1', changed: true } } })
+    await expect(absolute.next()).resolves.toMatchObject({ value: { ok: true, value: { version: 'v1', changed: true } } })
+    // A reload on the session record re-stats both and clears both flags:
+    // delivery is per path, not per record.
+    provider.reload!(ADDRESS)
+    const nexts = Promise.all([session.next(), absolute.next()])
+    await settle()
+    expect(remote.stats.slice(2).map(pending => pending.path)).toEqual([REL_PATH, HOST_PATH])
+    remote.stats[2]!.resolve({ ok: true, value: stat('v1', 3) })
+    remote.stats[3]!.resolve({ ok: true, value: stat('v1', 3) })
+    const cleared = { done: false, value: { ok: true, value: { absolutePath: HOST_PATH, version: 'v1', bytes: 3, changed: false } } }
+    await expect(nexts).resolves.toEqual([cleared, cleared])
+  })
+
+  it('is a no-op for a file nobody has open', async () => {
+    const { remote, reload } = opened()
+    reload()
+    await settle()
+    expect(remote.stats).toHaveLength(0)
+  })
+})
+
+describe('file provider — the end', () => {
+  it('ends when its signal aborts and releases the session stream', async () => {
+    const { remote, it, controller } = await live()
+    controller.abort()
+    await expect(it.next()).resolves.toEqual({ done: true, value: undefined })
+    await settle()
+    expect(remote.disposed).toEqual(['workspace file changes of s1'])
+  })
+
+  it('ends when the Host closes the session stream', async () => {
+    const { remote, it } = await live()
+    remote.opened[0]!.source.end()
+    await expect(it.next()).resolves.toEqual({ done: true, value: undefined })
+  })
+})
diff --git a/packages/api/workspace-files/tests/read-bytes.spec.ts b/packages/api/workspace-files/tests/read-bytes.spec.ts
new file mode 100644
index 0000000000..8785349795
--- /dev/null
+++ b/packages/api/workspace-files/tests/read-bytes.spec.ts
@@ -0,0 +1,146 @@
+/** The `readBytes` endpoint: the byte window it cuts, its defaults and cap, and the gates it shares with `read`. */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { FsVersion } from '@deepseek-ai/dsh-fs'
+import { agent, failureOf, openWorkspace, signal, type Harness } from './harness.ts'
+
+let harness: Harness
+let workspace: string
+
+beforeEach(async () => {
+  harness = await openWorkspace('dsh-workspace-files-read-bytes-')
+  workspace = harness.workspace
+})
+
+afterEach(async () => {
+  await harness.dispose()
+})
+
+const endpoint = (caps?: { maxBytes?: number }): ReturnType<Harness['endpoint']> => harness.endpoint(caps)
+
+/** 256 bytes, each equal to its offset: the window's content names its position. */
+const RAMP = Buffer.from(Array.from({ length: 256 }, (_, i) => i))
+
+const decode = (data: string): Buffer => Buffer.from(data, 'base64')
+
+describe('workspaceFiles.readBytes — the window', () => {
+  it('returns the whole file as one window by default, with its absolute path, version, and size', async () => {
+    await writeFile(join(workspace, 'ramp.bin'), RAMP)
+    const result = await endpoint().readBytes(agent, 'ramp.bin', {}, signal())
+    expect(decode(result.data).equals(RAMP)).toBe(true)
+    expect(result).toMatchObject({ offset: 0, eof: true, bytes: 256 })
+    expect(result.absolutePath.endsWith('ramp.bin')).toBe(true)
+    expect(result.version.length).toBeGreaterThan(0)
+  })
+
+  it('cuts the requested window and reports that more follows', async () => {
+    await writeFile(join(workspace, 'ramp.bin'), RAMP)
+    const result = await endpoint().readBytes(agent, 'ramp.bin', { offset: 16, length: 8 }, signal())
+    expect([...decode(result.data)]).toEqual([16, 17, 18, 19, 20, 21, 22, 23])
+    expect(result).toMatchObject({ offset: 16, eof: false, bytes: 256 })
+  })
+
+  it('reads a window of a file far above the byte cap', async () => {
+    await writeFile(join(workspace, 'huge.bin'), Buffer.alloc(200_000, 7))
+    const result = await endpoint({ maxBytes: 1024 }).readBytes(agent, 'huge.bin', { offset: 199_000, length: 1024 }, signal())
+    expect(decode(result.data)).toHaveLength(1000)
+    expect(result).toMatchObject({ eof: true, bytes: 200_000 })
+  })
+
+  it('infers eof from a short window when the backend reports no size', async () => {
+    await writeFile(join(workspace, 'ramp.bin'), RAMP)
+    vi.spyOn(harness.ctx.fs, 'stat').mockResolvedValue({ version: FsVersion('v-sizeless'), type: 'file' })
+    const full = await endpoint().readBytes(agent, 'ramp.bin', { offset: 0, length: 256 }, signal())
+    expect(full.eof).toBe(false)
+    const short = await endpoint().readBytes(agent, 'ramp.bin', { offset: 250, length: 10 }, signal())
+    expect(short).toMatchObject({ eof: true })
+    expect(short.bytes).toBeUndefined()
+  })
+
+  it('reports eof on the window that holds the last byte, whether or not the length is reached', async () => {
+    await writeFile(join(workspace, 'ramp.bin'), RAMP)
+    const exact = await endpoint().readBytes(agent, 'ramp.bin', { offset: 248, length: 8 }, signal())
+    expect(exact.eof).toBe(true)
+    expect(decode(exact.data)).toHaveLength(8)
+    const short = await endpoint().readBytes(agent, 'ramp.bin', { offset: 250, length: 100 }, signal())
+    expect(short.eof).toBe(true)
+    expect([...decode(short.data)]).toEqual([250, 251, 252, 253, 254, 255])
+  })
+
+  it('returns an empty eof window for an offset at or past the end', async () => {
+    await writeFile(join(workspace, 'ramp.bin'), RAMP)
+    const result = await endpoint().readBytes(agent, 'ramp.bin', { offset: 300, length: 8 }, signal())
+    expect(result).toMatchObject({ data: '', offset: 300, eof: true, bytes: 256 })
+  })
+
+  it('returns an empty eof window for an empty file', async () => {
+    await writeFile(join(workspace, 'empty.bin'), Buffer.alloc(0))
+    const result = await endpoint().readBytes(agent, 'empty.bin', {}, signal())
+    expect(result).toMatchObject({ data: '', offset: 0, eof: true, bytes: 0 })
+  })
+
+  it('carries bytes a text read would refuse: NUL and invalid UTF-8 round-trip through base64', async () => {
+    const raw = Buffer.from([0, 0xff, 0xfe, 0x80, 0x41, 0])
+    await writeFile(join(workspace, 'blob.bin'), raw)
+    const result = await endpoint().readBytes(agent, 'blob.bin', {}, signal())
+    expect(decode(result.data).equals(raw)).toBe(true)
+  })
+
+  it('names the version a stat of the same file reports', async () => {
+    await writeFile(join(workspace, 'ramp.bin'), RAMP)
+    const stat = await endpoint().stat(agent, 'ramp.bin', signal())
+    const result = await endpoint().readBytes(agent, 'ramp.bin', {}, signal())
+    expect(result.version).toBe(stat.version)
+  })
+})
+
+describe('workspaceFiles.readBytes — defaults and cap', () => {
+  it('defaults the length to the configured byte cap', async () => {
+    await writeFile(join(workspace, 'ramp.bin'), RAMP.subarray(0, 64))
+    const result = await endpoint({ maxBytes: 64 }).readBytes(agent, 'ramp.bin', {}, signal())
+    expect(decode(result.data)).toHaveLength(64)
+    expect(result.eof).toBe(true)
+  })
+
+  it('refuses a window longer than the cap as too-large rather than shortening it', async () => {
+    await writeFile(join(workspace, 'ramp.bin'), RAMP)
+    const failure = await failureOf(endpoint({ maxBytes: 64 }).readBytes(agent, 'ramp.bin', { length: 65 }, signal()))
+    expect(failure.code).toBe('workspace-file/too-large')
+    expect(failure.details).toMatchObject({ limit: 64 })
+  })
+
+  it('accepts a window exactly at the cap', async () => {
+    await writeFile(join(workspace, 'ramp.bin'), RAMP.subarray(0, 64))
+    const result = await endpoint({ maxBytes: 64 }).readBytes(agent, 'ramp.bin', { length: 64 }, signal())
+    expect(decode(result.data)).toHaveLength(64)
+  })
+
+  it('refuses a negative or fractional offset and a non-positive length as bad requests', async () => {
+    await writeFile(join(workspace, 'ramp.bin'), RAMP)
+    // Beyond-safe integers and a window whose end overflows are refused too: they cannot index a file.
+    const ranges = [
+      { offset: -1 }, { offset: 1.5 }, { length: 0 }, { length: 2.5 },
+      { offset: 2 ** 53 }, { offset: Number.MAX_SAFE_INTEGER, length: 2 },
+    ]
+    for (const range of ranges) {
+      const failure = await failureOf(endpoint().readBytes(agent, 'ramp.bin', range, signal()))
+      expect(failure.code).toBe('gateway/bad-request')
+    }
+  })
+})
+
+describe('workspaceFiles.readBytes — the gates it shares with read', () => {
+  it('rejects a directory, a missing path, and an empty path', async () => {
+    await mkdir(join(workspace, 'dir'))
+    expect((await failureOf(endpoint().readBytes(agent, 'dir', {}, signal()))).code).toBe('workspace-file/not-regular-file')
+    expect((await failureOf(endpoint().readBytes(agent, 'missing.bin', {}, signal()))).code).toBe('workspace-file/not-found')
+    expect((await failureOf(endpoint().readBytes(agent, '', {}, signal()))).code).toBe('gateway/bad-request')
+  })
+
+  it('rejects an absolute path outside the workspace', async () => {
+    await writeFile(join(harness.outside, 'secret.bin'), RAMP)
+    const failure = await failureOf(endpoint().readBytes(agent, join(harness.outside, 'secret.bin'), {}, signal()))
+    expect(failure.code).toBe('workspace-file/outside-workspace')
+  })
+})
diff --git a/packages/api/workspace-files/tests/read.spec.ts b/packages/api/workspace-files/tests/read.spec.ts
new file mode 100644
index 0000000000..2ee3fa95b3
--- /dev/null
+++ b/packages/api/workspace-files/tests/read.spec.ts
@@ -0,0 +1,264 @@
+/** The `read` endpoint: its four gates and the line window it cuts. */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { mkdir, rm, symlink, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { FsError } from '@deepseek-ai/dsh-fs'
+import { agent, failureOf, openWorkspace, signal, type Harness } from './harness.ts'
+
+let harness: Harness
+let workspace: string
+let outside: string
+
+beforeEach(async () => {
+  harness = await openWorkspace('dsh-workspace-files-read-')
+  workspace = harness.workspace
+  outside = harness.outside
+})
+
+afterEach(async () => {
+  await harness.dispose()
+})
+
+const endpoint = (caps?: { maxBytes?: number; maxLines?: number }): ReturnType<Harness['endpoint']> =>
+  harness.endpoint(caps)
+
+/** Twenty lines, `line 1` through `line 20`, terminated by a final newline. */
+async function twentyLines(): Promise<void> {
+  await writeFile(join(workspace, 'long.txt'), `${Array.from({ length: 20 }, (_, i) => `line ${i + 1}`).join('\n')}\n`, 'utf8')
+}
+
+/** A file whose second line carries a NUL byte past the backend's 8 KiB binary sample. */
+async function lateNul(): Promise<void> {
+  await writeFile(join(workspace, 'late-nul.txt'), Buffer.concat([
+    Buffer.from(`${'a'.repeat(9000)}\nb`, 'utf8'),
+    Buffer.from([0]),
+    Buffer.from('c\n', 'utf8'),
+  ]))
+}
+
+describe('workspaceFiles.read — the happy path', () => {
+  it('returns the whole file as one page with its absolute path, version, and byte size', async () => {
+    await writeFile(join(workspace, 'notes.txt'), 'hello\nworld\n', 'utf8')
+    const result = await endpoint().read(agent, 'notes.txt', {}, signal())
+    expect(result.text).toBe('hello\nworld')
+    expect(result.offset).toBe(1)
+    expect(result.lines).toBe(2)
+    expect(result.eof).toBe(true)
+    expect(result.bytes).toBe(12)
+    expect(result.version.length).toBeGreaterThan(0)
+    expect(result.absolutePath.endsWith('notes.txt')).toBe(true)
+  })
+
+  it('reads a nested path relative to the workspace root, not to any backend cwd', async () => {
+    await mkdir(join(workspace, 'src', 'deep'), { recursive: true })
+    await writeFile(join(workspace, 'src', 'deep', 'a.ts'), 'export {}\n', 'utf8')
+    const result = await endpoint().read(agent, 'src/deep/a.ts', {}, signal())
+    expect(result.text).toBe('export {}')
+  })
+
+  it('returns an empty page for an empty file', async () => {
+    await writeFile(join(workspace, 'empty.txt'), '', 'utf8')
+    const result = await endpoint().read(agent, 'empty.txt', {}, signal())
+    expect(result).toMatchObject({ text: '', lines: 0, eof: true, bytes: 0 })
+  })
+
+  it('accepts multi-byte UTF-8 and counts the file bytes, not its characters', async () => {
+    await writeFile(join(workspace, 'zh.txt'), '侧栏', 'utf8')
+    const result = await endpoint().read(agent, 'zh.txt', {}, signal())
+    expect(result.text).toBe('侧栏')
+    expect(result.bytes).toBe(6)
+  })
+})
+
+describe('workspaceFiles.read — the line window', () => {
+  it('cuts the requested lines and reports that more follow', async () => {
+    await twentyLines()
+    const result = await endpoint().read(agent, 'long.txt', { offset: 6, limit: 3 }, signal())
+    expect(result).toMatchObject({ offset: 6, text: 'line 6\nline 7\nline 8', lines: 3, eof: false })
+  })
+
+  it('reports eof on the page that holds the last line, whether or not the limit is reached', async () => {
+    await twentyLines()
+    const service = endpoint()
+    const exact = await service.read(agent, 'long.txt', { offset: 16, limit: 5 }, signal())
+    expect(exact).toMatchObject({ text: 'line 16\nline 17\nline 18\nline 19\nline 20', lines: 5, eof: true })
+    const beyond = await service.read(agent, 'long.txt', { offset: 19, limit: 10 }, signal())
+    expect(beyond).toMatchObject({ text: 'line 19\nline 20', lines: 2, eof: true })
+  })
+
+  it('treats a final newline as the last line terminator, not as an empty line after it', async () => {
+    await writeFile(join(workspace, 'two.txt'), 'a\nb\n', 'utf8')
+    await writeFile(join(workspace, 'three.txt'), 'a\nb\n\n', 'utf8')
+    const service = endpoint()
+    expect(await service.read(agent, 'two.txt', { limit: 2 }, signal())).toMatchObject({ text: 'a\nb', lines: 2, eof: true })
+    expect(await service.read(agent, 'three.txt', { limit: 2 }, signal())).toMatchObject({ text: 'a\nb', lines: 2, eof: false })
+    // The third line is empty, not absent: `lines` tells it from a page past the end.
+    expect(await service.read(agent, 'three.txt', { offset: 3 }, signal())).toMatchObject({ text: '', lines: 1, eof: true })
+  })
+
+  it('returns an empty eof page for an offset past the last line', async () => {
+    await twentyLines()
+    const result = await endpoint().read(agent, 'long.txt', { offset: 21 }, signal())
+    expect(result).toMatchObject({ offset: 21, text: '', lines: 0, eof: true })
+  })
+
+  it('defaults the limit to the configured page size', async () => {
+    await twentyLines()
+    const result = await endpoint({ maxLines: 5 }).read(agent, 'long.txt', {}, signal())
+    expect(result.text.split('\n')).toHaveLength(5)
+    expect(result.eof).toBe(false)
+  })
+
+  it('refuses a limit above the configured page size and a non-positive-integer window', async () => {
+    await twentyLines()
+    const service = endpoint({ maxLines: 5 })
+    for (const range of [{ limit: 6 }, { offset: 0 }, { limit: 1.5 }, { offset: -3 }]) {
+      const failure = await failureOf(service.read(agent, 'long.txt', range, signal()))
+      expect(failure.code).toBe('gateway/bad-request')
+    }
+  })
+
+  it('keeps carriage returns: the page is the file text, not a rendering of it', async () => {
+    await writeFile(join(workspace, 'crlf.txt'), 'a\r\nb\r\n', 'utf8')
+    const result = await endpoint().read(agent, 'crlf.txt', {}, signal())
+    expect(result.text).toBe('a\r\nb\r')
+  })
+})
+
+describe('workspaceFiles.read — gate 1 and 2: authorization by containment', () => {
+  it('rejects an absolute path outside the workspace', async () => {
+    await writeFile(join(outside, 'secret.txt'), 'no', 'utf8')
+    const failure = await failureOf(endpoint().read(agent, join(outside, 'secret.txt'), {}, signal()))
+    expect(failure.code).toBe('workspace-file/outside-workspace')
+  })
+
+  it('rejects a traversal that climbs out of the workspace', async () => {
+    await writeFile(join(outside, 'secret.txt'), 'no', 'utf8')
+    const failure = await failureOf(endpoint().read(agent, '../outside/secret.txt', {}, signal()))
+    expect(failure.code).toBe('workspace-file/outside-workspace')
+  })
+
+  it('rejects a symlink that points out of the workspace — the case a prefix test cannot see', async () => {
+    await writeFile(join(outside, 'secret.txt'), 'no', 'utf8')
+    // The path itself is inside the workspace and would pass any string
+    // comparison; only lstat (before the follow) or realpath containment catches it.
+    await symlink(join(outside, 'secret.txt'), join(workspace, 'link.txt'))
+    const failure = await failureOf(endpoint().read(agent, 'link.txt', {}, signal()))
+    expect(failure.code).toBe('workspace-file/not-regular-file')
+    expect(failure.details).toMatchObject({ kind: 'symlink' })
+  })
+
+  it('rejects a symlink even when it points back inside the workspace', async () => {
+    await writeFile(join(workspace, 'real.txt'), 'fine', 'utf8')
+    await symlink(join(workspace, 'real.txt'), join(workspace, 'alias.txt'))
+    const failure = await failureOf(endpoint().read(agent, 'alias.txt', {}, signal()))
+    expect(failure.code).toBe('workspace-file/not-regular-file')
+  })
+
+  it('rejects a directory, which has no text to return', async () => {
+    await mkdir(join(workspace, 'src'), { recursive: true })
+    const failure = await failureOf(endpoint().read(agent, 'src', {}, signal()))
+    expect(failure.code).toBe('workspace-file/not-regular-file')
+    expect(failure.details).toMatchObject({ kind: 'directory' })
+  })
+
+  it('reports a missing path as not found', async () => {
+    const failure = await failureOf(endpoint().read(agent, 'nope.txt', {}, signal()))
+    expect(failure.code).toBe('workspace-file/not-found')
+  })
+
+  it('refuses an empty path as a bad request', async () => {
+    const failure = await failureOf(endpoint().read(agent, '', {}, signal()))
+    expect(failure.code).toBe('gateway/bad-request')
+  })
+})
+
+describe('workspaceFiles.read — gate 3: the page byte cap', () => {
+  it('fails a page above the cap rather than returning it shortened', async () => {
+    await writeFile(join(workspace, 'big.txt'), 'x'.repeat(4096), 'utf8')
+    const failure = await failureOf(endpoint({ maxBytes: 1024 }).read(agent, 'big.txt', {}, signal()))
+    expect(failure.code).toBe('workspace-file/too-large')
+    expect(failure.details).toMatchObject({ limit: 1024 })
+  })
+
+  it('accepts a page exactly at the cap, because the cap is inclusive', async () => {
+    await writeFile(join(workspace, 'exact.txt'), `${'x'.repeat(31)}\n${'y'.repeat(32)}\n`, 'utf8')
+    const result = await endpoint({ maxBytes: 64 }).read(agent, 'exact.txt', {}, signal())
+    expect(result.text).toHaveLength(64)
+  })
+
+  it('counts the newlines between the page lines against the cap', async () => {
+    await writeFile(join(workspace, 'exact.txt'), `${'x'.repeat(31)}\n${'y'.repeat(32)}\n`, 'utf8')
+    const failure = await failureOf(endpoint({ maxBytes: 63 }).read(agent, 'exact.txt', {}, signal()))
+    expect(failure.code).toBe('workspace-file/too-large')
+  })
+
+  it('caps the page, not the file: a small window of a file far above the cap reads', async () => {
+    await writeFile(join(workspace, 'huge.txt'), Array.from({ length: 2000 }, (_, i) => `row ${i} ${'z'.repeat(100)}`).join('\n'), 'utf8')
+    const result = await endpoint({ maxBytes: 1024 }).read(agent, 'huge.txt', { offset: 1990, limit: 3 }, signal())
+    expect(result.text.split('\n')).toHaveLength(3)
+    expect(result.eof).toBe(false)
+    expect(result.bytes).toBeGreaterThan(200_000)
+  })
+})
+
+describe('workspaceFiles.read — gate 4: text only', () => {
+  it('rejects bytes that are not valid UTF-8', async () => {
+    await writeFile(join(workspace, 'bin.dat'), Buffer.from([0xff, 0xfe, 0xfd]))
+    const failure = await failureOf(endpoint().read(agent, 'bin.dat', {}, signal()))
+    expect(failure.code).toBe('workspace-file/not-text')
+  })
+
+  it('rejects a page that carries NUL bytes, wherever in the file the page lies', async () => {
+    await writeFile(join(workspace, 'nul.dat'), Buffer.from([0x61, 0x00, 0x62]))
+    const service = endpoint()
+    expect((await failureOf(service.read(agent, 'nul.dat', {}, signal()))).code).toBe('workspace-file/not-text')
+    // Past the backend's own binary sample, so only the page scan can see it.
+    await lateNul()
+    expect((await failureOf(service.read(agent, 'late-nul.txt', { offset: 2 }, signal()))).code).toBe('workspace-file/not-text')
+  })
+
+  it('reads a page that ends before a NUL byte, because detection is per page', async () => {
+    await lateNul()
+    const result = await endpoint().read(agent, 'late-nul.txt', { limit: 1 }, signal())
+    expect(result.text).toHaveLength(9000)
+    expect(result.eof).toBe(false)
+  })
+})
+
+describe('workspaceFiles.read — the file changing under its gate', () => {
+  /** Run `mutate` after the path gate has looked, so what follows sees a different filesystem. */
+  function afterGate(mutate: () => Promise<void>): void {
+    const fs = harness.ctx.fs
+    const lstat = fs.lstat.bind(fs)
+    vi.spyOn(fs, 'lstat').mockImplementation(async (path, opts, signal) => {
+      const entry = await lstat(path, opts, signal)
+      await mutate()
+      return entry
+    })
+  }
+
+  it('reports a file deleted after the gate as not found, not as an internal failure', async () => {
+    await writeFile(join(workspace, 'fleeting.txt'), 'x', 'utf8')
+    afterGate(() => rm(join(workspace, 'fleeting.txt')))
+    const failure = await failureOf(endpoint().read(agent, 'fleeting.txt', {}, signal()))
+    expect(failure.code).toBe('workspace-file/not-found')
+  })
+
+  it('reports a file replaced by a directory after the gate as not a regular file', async () => {
+    await writeFile(join(workspace, 'fleeting.txt'), 'x', 'utf8')
+    afterGate(async () => {
+      await rm(join(workspace, 'fleeting.txt'))
+      await mkdir(join(workspace, 'fleeting.txt'))
+    })
+    const failure = await failureOf(endpoint().read(agent, 'fleeting.txt', {}, signal()))
+    expect(failure.code).toBe('workspace-file/not-regular-file')
+    expect(failure.details).toMatchObject({ kind: 'directory' })
+  })
+
+  it('passes any other backend failure through unchanged', async () => {
+    await writeFile(join(workspace, 'notes.txt'), 'x', 'utf8')
+    vi.spyOn(harness.ctx.fs, 'streamText').mockRejectedValue(new FsError('disk unreadable', 'FS_IO_ERROR'))
+    await expect(endpoint().read(agent, 'notes.txt', {}, signal())).rejects.toMatchObject({ code: 'FS_IO_ERROR' })
+  })
+})
diff --git a/packages/api/workspace-files/tests/stat.spec.ts b/packages/api/workspace-files/tests/stat.spec.ts
new file mode 100644
index 0000000000..7badc565f0
--- /dev/null
+++ b/packages/api/workspace-files/tests/stat.spec.ts
@@ -0,0 +1,79 @@
+/** The `stat` endpoint: the same gates as `read`, answering identity and freshness without content. */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { mkdir, symlink, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { FsVersion } from '@deepseek-ai/dsh-fs'
+import { agent, failureOf, openWorkspace, signal, type Harness } from './harness.ts'
+
+let harness: Harness
+
+beforeEach(async () => {
+  harness = await openWorkspace('dsh-workspace-files-stat-')
+})
+
+afterEach(async () => {
+  await harness.dispose()
+})
+
+describe('workspaceFiles.stat', () => {
+  it('returns the absolute path, a version, and the byte size', async () => {
+    await writeFile(join(harness.workspace, 'notes.txt'), 'hello\n', 'utf8')
+    const result = await harness.endpoint().stat(agent, 'notes.txt', signal())
+    expect(result.absolutePath).toBe(harness.ctx.fs.processPath(await harness.ctx.fs.resolve(join(harness.workspace, 'notes.txt'))))
+    expect(result.version.length).toBeGreaterThan(0)
+    expect(result.bytes).toBe(6)
+  })
+
+  it('answers with the version a read of the same file reports, and a new one after a write', async () => {
+    const path = join(harness.workspace, 'notes.txt')
+    await writeFile(path, 'one\n', 'utf8')
+    const endpoint = harness.endpoint()
+    const before = await endpoint.stat(agent, 'notes.txt', signal())
+    const page = await endpoint.read(agent, 'notes.txt', {}, signal())
+    expect(page.version).toBe(before.version)
+    await writeFile(path, 'one\ntwo\n', 'utf8')
+    const after = await endpoint.stat(agent, 'notes.txt', signal())
+    expect(after.version).not.toBe(before.version)
+    expect(after.bytes).toBe(8)
+  })
+
+  it('rejects under a signal the caller already aborted, before any path resolves', async () => {
+    const controller = new AbortController()
+    controller.abort()
+    await expect(harness.endpoint().stat(agent, 'notes.txt', controller.signal)).rejects.toThrow()
+  })
+
+  it('resolves the workspace root and then the confined target under the caller\'s signal', async () => {
+    await writeFile(join(harness.workspace, 'notes.txt'), 'hello\n', 'utf8')
+    const fs = harness.ctx.fs
+    const original = fs.resolve.bind(fs)
+    const spy = vi.spyOn(fs, 'resolve').mockImplementation((path, opts) => original(path, opts))
+    const controller = new AbortController()
+    await harness.endpoint().stat(agent, 'notes.txt', controller.signal)
+    expect(spy.mock.calls.map(([, opts]) => opts?.signal)).toEqual([controller.signal, controller.signal])
+    spy.mockRestore()
+  })
+
+  it('omits bytes when the backend reports no size', async () => {
+    await writeFile(join(harness.workspace, 'notes.txt'), 'hello\n', 'utf8')
+    vi.spyOn(harness.ctx.fs, 'stat').mockResolvedValue({ version: FsVersion('v-sizeless'), type: 'file' })
+    const result = await harness.endpoint().stat(agent, 'notes.txt', signal())
+    expect(result).toEqual({ absolutePath: result.absolutePath, version: 'v-sizeless' })
+  })
+
+  it('applies the read gates: symlink, directory, outside, missing, empty', async () => {
+    await writeFile(join(harness.outside, 'secret.txt'), 'no', 'utf8')
+    await symlink(join(harness.outside, 'secret.txt'), join(harness.workspace, 'link.txt'))
+    await mkdir(join(harness.workspace, 'src'))
+    const endpoint = harness.endpoint()
+    expect(await failureOf(endpoint.stat(agent, 'link.txt', signal()))).toMatchObject({
+      code: 'workspace-file/not-regular-file',
+      details: { kind: 'symlink' },
+    })
+    expect((await failureOf(endpoint.stat(agent, 'src', signal()))).details).toMatchObject({ kind: 'directory' })
+    expect((await failureOf(endpoint.stat(agent, join(harness.outside, 'secret.txt'), signal()))).code)
+      .toBe('workspace-file/outside-workspace')
+    expect((await failureOf(endpoint.stat(agent, 'nope.txt', signal()))).code).toBe('workspace-file/not-found')
+    expect((await failureOf(endpoint.stat(agent, '', signal()))).code).toBe('gateway/bad-request')
+  })
+})
diff --git a/packages/api/workspace-files/tsconfig.client.json b/packages/api/workspace-files/tsconfig.client.json
new file mode 100644
index 0000000000..43e935dc8f
--- /dev/null
+++ b/packages/api/workspace-files/tsconfig.client.json
@@ -0,0 +1,28 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "tsBuildInfoFile": "lib/tsconfig.client.tsbuildinfo"
+  },
+  "files": [
+    "src/client/index.ts",
+    "src/client/change-feed.ts",
+    "src/client/provider.ts",
+    "src/client/remote.ts",
+    "src/client/types.ts",
+    "src/types.ts"
+  ],
+  "references": [
+    { "path": "../../../vendor/cordis" },
+    { "path": "../gateway/tsconfig.client.json" },
+    { "path": "../session-controller/tsconfig.client.json" },
+    { "path": "../../core/session" },
+    { "path": "../../client/resources" },
+    { "path": "../../client/ui-slots" },
+    { "path": "../../util/workspace-path" },
+    {
+      "path": "../../typert/protocol"
+    }
+  ]
+}
diff --git a/packages/api/workspace-files/tsconfig.host.json b/packages/api/workspace-files/tsconfig.host.json
new file mode 100644
index 0000000000..c26a622e87
--- /dev/null
+++ b/packages/api/workspace-files/tsconfig.host.json
@@ -0,0 +1,39 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "tsBuildInfoFile": "lib/tsconfig.host.tsbuildinfo"
+  },
+  "files": [
+    "src/index.ts",
+    "src/types.ts",
+    "src/changes.ts"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../fs/fs"
+    },
+    {
+      "path": "../../sandbox/sandbox-policy"
+    },
+    {
+      "path": "../../typert/protocol"
+    },
+    {
+      "path": "../../util/deque"
+    }
+  ]
+}
diff --git a/packages/api/workspace-files/tsconfig.json b/packages/api/workspace-files/tsconfig.json
new file mode 100644
index 0000000000..2eca820546
--- /dev/null
+++ b/packages/api/workspace-files/tsconfig.json
@@ -0,0 +1,11 @@
+{
+  "files": [],
+  "references": [
+    {
+      "path": "./tsconfig.host.json"
+    },
+    {
+      "path": "./tsconfig.client.json"
+    }
+  ]
+}
diff --git a/packages/api/workspace-files/tsdown.config.ts b/packages/api/workspace-files/tsdown.config.ts
new file mode 100644
index 0000000000..6bf04a7409
--- /dev/null
+++ b/packages/api/workspace-files/tsdown.config.ts
@@ -0,0 +1,7 @@
+import { clientBundle } from '../../client/tsdown.client.ts'
+
+export default clientBundle(
+  '@deepseek-ai/dsh-api-workspace-files',
+  ['lib/types/index.js'],
+  { hostPhase: true },
+)
diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml
index 5fd15cc279..bb062f2623 100644
--- a/packages/boot/app-boot/README.i18n.yaml
+++ b/packages/boot/app-boot/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/boot/app-boot/README.md
-README.md: 086424009c9f7157f687a00cbb50cdc80a210e11
-README.zh.md: 4d0e45dd6be961d22d638134541c80501edec505
+README.md: 197ed81c1025f7211c3fb7a694547c52fb058ee8
+README.zh.md: 5e465a86f5e624380710cc8c73d5356c649522e4
diff --git a/packages/boot/app-boot/README.md b/packages/boot/app-boot/README.md
index 086424009c..197ed81c10 100644
--- a/packages/boot/app-boot/README.md
+++ b/packages/boot/app-boot/README.md
@@ -47,7 +47,7 @@ With that entry point, success looks like a running app with every plugin active
 
 Import profile and bundle declaration types from [`@deepseek-ai/dsh-package-manifest`](../../util/package-manifest/README.md). App-boot owns profile loading, JSON validation, and resolved runtime data.
 
-A profile is how one dsh installation ships different app surfaces: `web`, `headless`, `acp`, `sdk`, and `sdk-minimal` start distinct compositions from the same launcher. A profile lives at `$DSH_HOME/profiles/<name>` and combines installable bundles, its own `cordis.patch.yml`, and `patchReload: live | startup`; omitted reload policy keeps the historical `live` default for custom profiles. The shipped `web` template uses live reload, while the other shipped templates apply patches only at startup. `sdk-minimal` names only its standalone bundle; the other templates retain base-plus-mode stacks. `dsh plugin` creates custom profiles, and a missing bundle or one without a patch declaration fails startup loudly. Application-owned npm projects, such as Electron's reserved Desktop profile, use `loadProfileDirectory` to load an already initialized directory without exposing it through CLI profile lookup.
+A profile is how one dsh installation ships different app surfaces: `web`, `headless`, `acp`, `sdk`, and `sdk-minimal` start distinct compositions from the same launcher. A profile lives at `$DSH_HOME/profiles/<name>` and combines installable bundles, its own `cordis.patch.yml`, and `patchReload: live | startup`; omitted reload policy keeps the historical `live` default for custom profiles. The shipped `web` template uses live reload, while the other shipped templates apply patches only at startup. `sdk-minimal` names only its standalone bundle; the other templates retain base-plus-mode stacks. `dsh --profile <name> --from-default-profile <template>` creates a custom profile at a new non-shipped name from one shipped template, while `dsh plugin` initializes a base-backed profile and manages its installed bundles. A missing bundle or one without a patch declaration fails startup loudly. Application-owned npm projects, such as Electron's reserved Desktop profile, use `loadProfileDirectory` to load an already initialized directory without exposing it through CLI profile lookup.
 
 Your machine-local preferences also live in the Harness home:
 
diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md
index 4d0e45dd6b..5e465a86f5 100644
--- a/packages/boot/app-boot/README.zh.md
+++ b/packages/boot/app-boot/README.zh.md
@@ -47,7 +47,7 @@ const ctx = await boot('dsh', resolveConfigPath(argv[2], process.env.DSH_SNAPSHO
 
 Profile 与 bundle 的声明类型从 [`@deepseek-ai/dsh-package-manifest`](../../util/package-manifest/README.zh.md) 导入。App-boot 负责 profile 加载、JSON 校验和解析后的运行时数据。
 
-profile 是同一套 dsh 安装提供不同应用界面的方式：`web`、`headless`、`acp`、`sdk` 与 `sdk-minimal` 从同一 launcher 启动不同组合。profile 位于 `$DSH_HOME/profiles/<name>`，由可安装 bundle、自身 `cordis.patch.yml` 与 `patchReload: live | startup` 组成；自定义 profile 省略 reload 策略时保留历史 `live` 默认值。随产品交付的 `web` 模板实时重载，其他随附模板只在启动时应用 patch。`sdk-minimal` 只列出自身的独立 bundle，其他模板保留 base 加模式 bundle 的栈。`dsh plugin` 创建自定义 profile；缺失 bundle 或未声明 patch 的 bundle 会让启动明确失败。由应用持有的 npm 项目（例如 Electron 保留的 Desktop profile）通过 `loadProfileDirectory` 加载已经初始化的目录，而不会将它暴露给 CLI profile 查找。
+profile 是同一套 dsh 安装提供不同应用界面的方式：`web`、`headless`、`acp`、`sdk` 与 `sdk-minimal` 从同一 launcher 启动不同组合。profile 位于 `$DSH_HOME/profiles/<name>`，由可安装 bundle、自身 `cordis.patch.yml` 与 `patchReload: live | startup` 组成；自定义 profile 省略 reload 策略时保留历史 `live` 默认值。随产品交付的 `web` 模板实时重载，其他随附模板只在启动时应用 patch。`sdk-minimal` 只列出自身的独立 bundle，其他模板保留 base 加模式 bundle 的栈。`dsh --profile <name> --from-default-profile <template>` 从一个随附模板，在新的非内置名称处创建自定义 profile；`dsh plugin` 则初始化以 base 为基础的 profile，并管理其中安装的 bundle。缺失 bundle 或未声明 patch 的 bundle 会让启动明确失败。由应用持有的 npm 项目（例如 Electron 保留的 Desktop profile）通过 `loadProfileDirectory` 加载已经初始化的目录，而不会将它暴露给 CLI profile 查找。
 
 你的机器本地偏好同样位于 harness home 中：
 
diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml
index 982575eab2..346abe5347 100644
--- a/packages/bundle/web-app/cordis.patch.yml
+++ b/packages/bundle/web-app/cordis.patch.yml
@@ -105,6 +105,11 @@
     - id: session-controller
       name: '@deepseek-ai/dsh-api-session-controller'
 
+    # Workspace file service: bounded read, directory listing, and the
+    # agent-write change feed inside the session workspace root.
+    - id: workspace-files
+      name: '@deepseek-ai/dsh-api-workspace-files'
+
     # Configuration-surface reads and writes over Typert Remote. Each method
     # reports an actionable error when its settings-domain provider is absent.
     - id: settings-controller
@@ -208,9 +213,27 @@
     - id: ui-session
       name: '@deepseek-ai/dsh-client-ui-session'
 
+    # Unified resource model: protocol providers behind the useResource hook.
+    - id: resources
+      name: '@deepseek-ai/dsh-client-resources'
+
     - id: ui-sidebar
       name: '@deepseek-ai/dsh-client-ui-sidebar'
 
+    # The right Sidebar: one docking surface per session over ui-dockkit.
+    - id: ui-sidebar-right
+      name: '@deepseek-ai/dsh-client-ui-sidebar-right'
+
+
+    # The right Sidebar's first outside tab type: workspace text files, read
+    # through the bounded workspaceFiles endpoint.
+    - id: ui-sidebar-textpreview
+      name: '@deepseek-ai/dsh-client-ui-sidebar-textpreview'
+
+    # The right Sidebar's workspace file tree tab type.
+    - id: ui-sidebar-files
+      name: '@deepseek-ai/dsh-client-ui-sidebar-files'
+
     - id: ui-settings
       name: '@deepseek-ai/dsh-client-ui-settings'
 
diff --git a/packages/bundle/web-app/package.json b/packages/bundle/web-app/package.json
index bc8b3dd2e4..76076b6219 100644
--- a/packages/bundle/web-app/package.json
+++ b/packages/bundle/web-app/package.json
@@ -40,91 +40,96 @@
   },
   "dependencies": {
     "@deepseek-ai/dsh-agent-presets": "workspace:^",
-    "@deepseek-ai/dsh-tool-subagent": "workspace:^",
     "@deepseek-ai/dsh-api-remotes": "workspace:^",
+    "@deepseek-ai/dsh-api-session-controller": "workspace:^",
+    "@deepseek-ai/dsh-api-settings-controller": "workspace:^",
+    "@deepseek-ai/dsh-api-workspace-controller": "workspace:^",
+    "@deepseek-ai/dsh-api-workspace-files": "workspace:^",
     "@deepseek-ai/dsh-app-boot": "workspace:^",
     "@deepseek-ai/dsh-client-connection": "workspace:^",
     "@deepseek-ai/dsh-client-file-upload": "workspace:^",
     "@deepseek-ai/dsh-client-hmr": "workspace:^",
     "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-modules": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-renderer": "workspace:^",
+    "@deepseek-ai/dsh-client-resources": "workspace:^",
     "@deepseek-ai/dsh-client-ui-agent-preset": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-attachment": "workspace:^",
     "@deepseek-ai/dsh-client-ui-approval": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-attachment": "workspace:^",
     "@deepseek-ai/dsh-client-ui-brand-official": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-commands": "workspace:^",
     "@deepseek-ai/dsh-client-ui-chat": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-commands": "workspace:^",
     "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
     "@deepseek-ai/dsh-client-ui-cordis": "workspace:^",
     "@deepseek-ai/dsh-client-ui-deliverables": "workspace:^",
     "@deepseek-ai/dsh-client-ui-directory-picker-browse": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-open-in-app": "workspace:^",
     "@deepseek-ai/dsh-client-ui-directory-picker-native": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-message-feedback": "workspace:^",
     "@deepseek-ai/dsh-client-ui-goal": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-input-trigger": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-jobs": "workspace:^",
     "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-message-feedback": "workspace:^",
     "@deepseek-ai/dsh-client-ui-model-selection": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-settings-models": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-settings-plugin-inventory": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-open-in-app": "workspace:^",
     "@deepseek-ai/dsh-client-ui-permission-presets": "workspace:^",
     "@deepseek-ai/dsh-client-ui-plan": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-reference": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-renderer": "workspace:^",
     "@deepseek-ai/dsh-client-ui-schedule": "workspace:^",
     "@deepseek-ai/dsh-client-ui-session": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-settings-plugins": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-user-questions": "workspace:^",
     "@deepseek-ai/dsh-client-ui-settings": "workspace:^",
     "@deepseek-ai/dsh-client-ui-settings-general": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-settings-models": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-settings-plugin-inventory": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "workspace:^",
     "@deepseek-ai/dsh-client-ui-sidebar": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-sidebar-files": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-sidebar-textpreview": "workspace:^",
     "@deepseek-ai/dsh-client-ui-skill": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-input-trigger": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-reference": "workspace:^",
     "@deepseek-ai/dsh-client-ui-subagent": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-jobs": "workspace:^",
     "@deepseek-ai/dsh-client-ui-theme": "workspace:^",
     "@deepseek-ai/dsh-client-ui-tool": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-workflow-run": "workspace:^",
     "@deepseek-ai/dsh-client-ui-trajectory": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-user-questions": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-workflow-run": "workspace:^",
     "@deepseek-ai/dsh-client-ui-workspace": "workspace:^",
     "@deepseek-ai/dsh-cmdline": "workspace:^",
     "@deepseek-ai/dsh-code-runtime-worker-thread": "workspace:^",
     "@deepseek-ai/dsh-cordis-client-runner": "workspace:^",
     "@deepseek-ai/dsh-cordis-host-runner": "workspace:^",
-    "@deepseek-ai/dsh-web-frontend": "workspace:^",
-    "@deepseek-ai/dsh-host-frontend-static": "workspace:^",
+    "@deepseek-ai/dsh-file-reference": "workspace:^",
+    "@deepseek-ai/dsh-file-reference-local": "workspace:^",
     "@deepseek-ai/dsh-host-directory-picker-auto": "workspace:^",
     "@deepseek-ai/dsh-host-directory-picker-browse": "workspace:^",
     "@deepseek-ai/dsh-host-directory-picker-native": "workspace:^",
+    "@deepseek-ai/dsh-host-frontend-static": "workspace:^",
     "@deepseek-ai/dsh-host-open-in-app": "workspace:^",
     "@deepseek-ai/dsh-host-plugin-inventory": "workspace:^",
     "@deepseek-ai/dsh-host-webserver": "workspace:^",
-    "@deepseek-ai/dsh-file-reference": "workspace:^",
-    "@deepseek-ai/dsh-file-reference-local": "workspace:^",
     "@deepseek-ai/dsh-launch-environment": "workspace:^",
     "@deepseek-ai/dsh-message-feedback": "workspace:^",
-    "@deepseek-ai/dsh-session-reference": "workspace:^",
     "@deepseek-ai/dsh-session-log-export": "workspace:^",
+    "@deepseek-ai/dsh-session-reference": "workspace:^",
     "@deepseek-ai/dsh-session-stats": "workspace:^",
     "@deepseek-ai/dsh-session-turn-outline": "workspace:^",
-    "@deepseek-ai/dsh-api-session-controller": "workspace:^",
-    "@deepseek-ai/dsh-api-settings-controller": "workspace:^",
-    "@deepseek-ai/dsh-api-workspace-controller": "workspace:^",
     "@deepseek-ai/dsh-subprocess": "workspace:^",
+    "@deepseek-ai/dsh-tool-subagent": "workspace:^",
+    "@deepseek-ai/dsh-web-frontend": "workspace:^",
     "@deepseek-ai/dsh-workspace": "workspace:^",
     "@deepseek-ai/schemastery": "workspace:^",
     "commander": "^15.0.0",
     "open": "^11.0.0"
   },
   "peerDependencies": {
+    "@deepseek-ai/cordis": "workspace:^",
     "@deepseek-ai/cordis-plugin-loader": "workspace:^",
     "@deepseek-ai/dsh-shell-env": "workspace:^",
-    "@deepseek-ai/dsh-system-prompt": "workspace:^",
-    "@deepseek-ai/cordis": "workspace:^"
+    "@deepseek-ai/dsh-system-prompt": "workspace:^"
   },
   "devDependencies": {
+    "@deepseek-ai/cordis": "workspace:^",
     "@deepseek-ai/cordis-plugin-loader": "workspace:^",
     "@deepseek-ai/dsh-shell-env": "workspace:^",
-    "@deepseek-ai/dsh-system-prompt": "workspace:^",
-    "@deepseek-ai/cordis": "workspace:^"
+    "@deepseek-ai/dsh-system-prompt": "workspace:^"
   }
 }
diff --git a/packages/client/AGENTS.md b/packages/client/AGENTS.md
index cc6a249a74..0d1633b902 100644
--- a/packages/client/AGENTS.md
+++ b/packages/client/AGENTS.md
@@ -74,7 +74,7 @@ Client business code may statically read `process.env.DSH_CLIENT_*`; every refer
 
 A dynamic browser half either carries a module privately or requests the shared module-table identity. The client baseline is centralized in [`web/src/platform.ts`](web/src/platform.ts): `PLATFORM_MODULES` names shell-seeded React, Cordis, and static Client libraries; `PRELOADED_CLIENT_EXTERNALS` is reserved for dynamic rows whose factories must arrive before shell boot and is empty when no such row exists.
 
-1. **Baseline externals are implicit for every dynamic bundle.** Do not repeat React, Cordis, `client/store`, `ui-primitives`, or `ui-slots` in package manifests.
+1. **Baseline externals are implicit for every dynamic bundle.** Do not repeat React, Cordis, `client/store`, `ui-primitives`, `ui-slots`, or `ui-dockkit` in package manifests.
 2. **`dsh.client.external` is not a feature-plugin dependency mechanism.** Only infrastructure, transport, or generated assembly may add a package-specific non-baseline value request whose dynamic row must be materialized through the module table. Declare the exact import specifier; only a trailing `/client` aliases the package row.
 3. **Silence means a private copy.** Ordinary third-party implementation libraries may be bundled independently. A value reached only through `import type` is erased and creates no request.
 4. **A request has two possible suppliers.** A dynamic package supplies its own row; `PLATFORM_MODULES` supplies an exact static-table key. There is no `dsh.client.provide` alias protocol.
diff --git a/packages/client/README.i18n.yaml b/packages/client/README.i18n.yaml
index 2e7f63c51f..85dc4fcffd 100644
--- a/packages/client/README.i18n.yaml
+++ b/packages/client/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/README.md
-README.md: 75eda4a46afb21287daa72a7c94fc9cc25aa32d8
-README.zh.md: 808ee9d2a52ae67dac456b58dc1f382ae85ab260
+README.md: aec7edcb1e15d174544a9abaf99a4dc784034f2a
+README.zh.md: e4f069e1afef4973ebc8fdcc507a720c7a02be79
diff --git a/packages/client/README.md b/packages/client/README.md
index 75eda4a46a..aec7edcb1e 100644
--- a/packages/client/README.md
+++ b/packages/client/README.md
@@ -42,6 +42,8 @@ The kernel packages boot and serve the page; the UI feature packages present it.
 | [`ui-attachment/`](ui-attachment/README.md) | Registers composer and message-image attachment presentation | — |
 | [`ui-layout/`](ui-layout/README.md) | Arranges the main application regions | — |
 | [`ui-sidebar/`](ui-sidebar/README.md) | Presents workspace and session navigation | — |
+| [`resources/`](resources/README.md) | Unified resource model: protocol providers behind the `useResource` session standard hook | `ctx.resources` |
+| [`ui-sidebar-files/`](ui-sidebar-files/README.md) | Right-Sidebar workspace file tree tab type | — |
 | [`ui-brand-official/`](ui-brand-official/README.md) | Fills the generic browser-brand slots with the official name and marks | — |
 | [`ui-workspace/`](ui-workspace/README.md) | Provides workspace selection and creation surfaces | — |
 | [`ui-conversation/`](ui-conversation/README.md) | Presents the active conversation and its input surface | — |
diff --git a/packages/client/README.zh.md b/packages/client/README.zh.md
index 808ee9d2a5..e4f069e1af 100644
--- a/packages/client/README.zh.md
+++ b/packages/client/README.zh.md
@@ -42,6 +42,8 @@ kind: "package-group"
 | [`ui-attachment/`](ui-attachment/README.zh.md) | 注册输入框与消息图片的附件呈现 | — |
 | [`ui-layout/`](ui-layout/README.zh.md) | 排列应用的主要区域 | — |
 | [`ui-sidebar/`](ui-sidebar/README.zh.md) | 展示工作区与会话导航 | — |
+| [`resources/`](resources/README.zh.md) | 统一资源模型：`useResource` 会话标准 hook 背后的协议提供者 | `ctx.resources` |
+| [`ui-sidebar-files/`](ui-sidebar-files/README.zh.md) | 右侧 Sidebar 的工作区文件树 tab 类型 | — |
 | [`ui-brand-official/`](ui-brand-official/README.zh.md) | 用官方名称与标记填充通用浏览器品牌 slot | — |
 | [`ui-workspace/`](ui-workspace/README.zh.md) | 提供工作区选择与创建界面 | — |
 | [`ui-conversation/`](ui-conversation/README.zh.md) | 展示当前对话及其输入界面 | — |
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index 932ec1da3e..6946e7f580 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -1750,8 +1750,20 @@ export interface FixtureOptions {
   dropSessionCreateResponse?: boolean
   /** Order of the two successful create frames. */
   createFrameOrder?: 'session-first' | 'workspace-first'
+  /** Announce one Agent write to `notes/demo.txt` shortly after a `workspaceFiles/changes` stream opens. */
+  fileChanges?: boolean
 }
 
+/** File observation payload, mirrored so this Client fixture names no Host package. */
+type FixtureWorkspaceFileChange =
+  | { readonly absolutePath: string; readonly version: string }
+  | { readonly absolutePath: string; readonly absent: true }
+
+/** Host subscription acknowledgement followed by file observations. */
+type FixtureWorkspaceFileWatchFrame =
+  | { readonly kind: 'ready' }
+  | { readonly kind: 'change'; readonly change: FixtureWorkspaceFileChange }
+
 /** 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). breakNow force-ends the stream without the
@@ -1818,6 +1830,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
     { sessionId: sid('fx-gamma'), updatedAt: Date.now() - 120_000, running: false, blank: false, cwd: '/tmp/fixture' },
   ]
   const logs = new Map<SessionId, SessionEvent[]>([[sid('fx-alpha'), buildAlphaLog()]])
+  const goalActivations = new Map<SessionId, 'armed' | 'disarmed'>()
   const modelSelections = new Map<SessionId, ModelSelection>(sessions.map(session => [
     session.sessionId,
     { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
@@ -2179,6 +2192,23 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
     return backscanGoal(log) as FxGoalProjection
   }
 
+  /** Update process-local goal activation and publish the forwarded edge. */
+  const setGoalActivation = (id: SessionId, activation: 'armed' | 'disarmed'): void => {
+    const current = backscanGoal(logOf(id))
+    if (current === null) {
+      if (!goalActivations.delete(id)) return
+      emitRemote('goal/activation-changed', [{ sessionId: id }])
+      return
+    }
+    const previous = goalActivations.get(id)
+    goalActivations.set(id, activation)
+    if (previous === activation) return
+    emitRemote('goal/activation-changed', [{
+      sessionId: id,
+      goal: { id: current.goal.id, revision: current.goal.revision, activation },
+    }])
+  }
+
   type FxGoalRef = { id: string; revision: number }
   type FxGoalView = FxGoalProjection['goal'] & {
     roundsStarted: number
@@ -2281,6 +2311,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
             goal: { id: `fx-goal-${logOf(id).length}`, revision: 1, objective, phase: 'active', maxGoalRounds: 256 },
             roundsStarted: 0, createdAt: Date.now(), updatedAt: Date.now(),
           })
+          setGoalActivation(id, 'armed')
           text = `Goal created: ${created.goal.objective}`
         }
         const result: CommandResult = { kind: 'success', text }
@@ -2313,12 +2344,12 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
     },
   }
 
-  const goalView = (projection: FxGoalProjection): FxGoalView => ({
+  const goalView = (id: SessionId, projection: FxGoalProjection): FxGoalView => ({
     ...projection.goal,
     roundsStarted: projection.roundsStarted,
     createdAt: projection.createdAt,
     updatedAt: projection.updatedAt,
-    activation: projection.goal.phase === 'active' ? 'armed' : 'disarmed',
+    activation: goalActivations.get(id) ?? (projection.goal.phase === 'active' ? 'armed' : 'disarmed'),
   })
 
   /** Canonical fixture implementation of the generated Goal Remote contract. */
@@ -2367,6 +2398,157 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
     },
   }
 
+  /**
+   * Workspace text reads under `?fixture`.
+   *
+   * The sample content is deliberately more than one shape: the panel's states
+   * (text, oversized, unreadable) are only demonstrable if the fixture can
+   * produce each of them, and a preview that can only ever succeed hides its
+   * own failure rendering.
+   */
+  // The Session workspace the replayed conversation writes into: `list` walks a
+  // fixed tree under it so the file-tree tab has directories, files, one entry
+  // of neither kind, and one cut listing to draw.
+  const WORKSPACE_FILES_ROOT = '/tmp/fixture'
+  type FixtureWorkspaceEntry = { name: string; type: 'file' | 'directory' | 'other'; size?: number }
+  const workspaceFileTree = new Map<string, FixtureWorkspaceEntry[]>([
+    ['', [
+      { name: '.gitignore', type: 'file', size: 24 },
+      { name: 'dev.sock', type: 'other' },
+      { name: 'notes', type: 'directory' },
+      { name: 'package.json', type: 'file', size: 512 },
+      { name: 'README.md', type: 'file', size: 640 },
+      { name: 'src', type: 'directory' },
+    ]],
+    ['notes', [
+      { name: 'demo.txt', type: 'file', size: 14 },
+      { name: 'new-demo.txt', type: 'file', size: 14 },
+    ]],
+    ['src', [
+      { name: 'config.ts', type: 'file', size: 211 },
+      { name: 'index.ts', type: 'file', size: 88 },
+      { name: 'lib', type: 'directory' },
+    ]],
+    ['src/lib', Array.from({ length: 24 }, (_, index) => ({
+      name: `module-${String(index + 1).padStart(2, '0')}.ts`,
+      type: 'file' as const,
+      size: 96 + index,
+    }))],
+  ])
+  /** Resolve a `list` argument to its workspace-relative path, or undefined when it leaves the root. */
+  const workspaceFilePath = (path: string): string | undefined => {
+    const segments: string[] = []
+    for (const segment of (path.startsWith('/') ? path : `${WORKSPACE_FILES_ROOT}/${path}`).split('/')) {
+      if (segment === '' || segment === '.') continue
+      if (segment === '..') {
+        segments.pop()
+        continue
+      }
+      segments.push(segment)
+    }
+    const absolute = `/${segments.join('/')}`
+    if (absolute !== WORKSPACE_FILES_ROOT && !absolute.startsWith(`${WORKSPACE_FILES_ROOT}/`)) return undefined
+    return absolute.slice(WORKSPACE_FILES_ROOT.length + 1)
+  }
+  // Page cap mirrored from the Host default so an over-limit request fails here too.
+  const WORKSPACE_FILE_PAGE_LINES = 5000
+  /**
+   * Sample text for any readable path: a heading plus two lines of copy. The
+   * replayed conversation's `demo` files, and any `huge` path, run past two
+   * default pages so paging can be exercised without a real workspace.
+   */
+  const workspaceFileLines = (path: string): string[] => {
+    const name = path.slice(path.lastIndexOf('/') + 1)
+    const head = [`# ${name}`, '', 'fixture 模式下的示例文本，用于验收侧栏的文本预览。', '真实构建从工作区读取同名文件。']
+    return path.includes('demo') || path.includes('huge')
+      ? [...head, ...Array.from({ length: 12_000 }, (_, index) => `第 ${index + 5} 行：用于验收分页与滚动的长文本样本。`)]
+      : head
+  }
+  const workspaceFileRemotes = {
+    list(path: string): ConnectionRpcResult<{
+      path: string
+      entries: readonly FixtureWorkspaceEntry[]
+      truncated: boolean
+    }> {
+      if (path.length === 0) {
+        return { ok: false, error: { code: 'gateway/bad-request', message: 'path is required', details: {} } }
+      }
+      const relative = workspaceFilePath(path)
+      if (relative === undefined) {
+        return {
+          ok: false,
+          error: { code: 'workspace-file/outside-workspace', message: `${path} is outside the workspace`, details: { path } },
+        }
+      }
+      const entries = workspaceFileTree.get(relative)
+      if (entries === undefined) {
+        const cut = relative.lastIndexOf('/')
+        const name = relative.slice(cut + 1)
+        const sibling = workspaceFileTree.get(cut === -1 ? '' : relative.slice(0, cut))?.find(entry => entry.name === name)
+        if (sibling === undefined) {
+          return { ok: false, error: { code: 'workspace-file/not-found', message: `no entry at ${path}`, details: { path } } }
+        }
+        return {
+          ok: false,
+          error: {
+            code: 'workspace-file/not-directory',
+            message: `${path} is a ${sibling.type}`,
+            details: { path, kind: sibling.type === 'file' ? 'file' : 'other' },
+          },
+        }
+      }
+      return { ok: true, value: { path: relative, entries, truncated: relative === 'src/lib' } }
+    },
+    read(path: string, range: { offset?: number; limit?: number }): ConnectionRpcResult<{
+      absolutePath: string
+      version: string
+      bytes: number
+      offset: number
+      text: string
+      lines: number
+      eof: boolean
+    }> {
+      const located = workspaceFileRemotes.stat(path)
+      if (!located.ok) return located
+      const offset = range.offset ?? 1
+      const limit = range.limit ?? WORKSPACE_FILE_PAGE_LINES
+      if (!Number.isInteger(offset) || offset < 1 || !Number.isInteger(limit) || limit < 1 || limit > WORKSPACE_FILE_PAGE_LINES) {
+        return { ok: false, error: { code: 'gateway/bad-request', message: 'offset and limit must be positive integers within the page cap', details: {} } }
+      }
+      const lines = workspaceFileLines(path)
+      const page = lines.slice(offset - 1, offset - 1 + limit)
+      return {
+        ok: true,
+        value: {
+          ...located.value,
+          offset,
+          text: page.join('\n'),
+          lines: page.length,
+          eof: offset - 1 + limit >= lines.length,
+        },
+      }
+    },
+    stat(path: string): ConnectionRpcResult<{ absolutePath: string; version: string; bytes: number }> {
+      if (path.length === 0) {
+        return { ok: false, error: { code: 'gateway/bad-request', message: 'path is required', details: {} } }
+      }
+      if (path.endsWith('.png') || path.endsWith('.bin')) {
+        return {
+          ok: false,
+          error: { code: 'workspace-file/not-text', message: `${path} is not UTF-8 text`, details: { path } },
+        }
+      }
+      return {
+        ok: true,
+        value: {
+          absolutePath: path.startsWith('/') ? path : `/${path}`,
+          version: 'fx-v1',
+          bytes: new TextEncoder().encode(workspaceFileLines(path).join('\n')).byteLength,
+        },
+      }
+    },
+  }
+
   /**
    * Canonical fixture implementation of the generated Directory Picker Remote
    * contract. The pick is deterministic — the keyless lanes drive the full
@@ -2417,6 +2599,12 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
   }
 
   const goalRemotes = {
+    get(id: SessionId): RpcResult<FxGoalView | undefined> {
+      const missing = requireGoalSession(id)
+      if (missing !== undefined) return missing
+      const current = backscanGoal(logOf(id))
+      return { ok: true, value: current === null ? undefined : goalView(id, current) }
+    },
     create(id: SessionId, request: { objective: string; maxGoalRounds?: number }): RpcResult<{ ref: FxGoalRef }> {
       const missing = requireGoalSession(id)
       if (missing !== undefined) return missing
@@ -2436,6 +2624,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
         },
         roundsStarted: 0, createdAt: now, updatedAt: now,
       })
+      setGoalActivation(id, 'armed')
       return { ok: true, value: { ref: { id: projection.goal.id, revision: projection.goal.revision } } }
     },
     edit(id: SessionId, ref: FxGoalRef, request: { objective?: string; maxGoalRounds?: number }): RpcResult<FxGoalView> {
@@ -2475,6 +2664,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
       appendGoalChange(id, {
         kind: 'goal/change', version: 1, operation: 'clear', cleared: tombstone, clearedAt: Date.now(),
       })
+      setGoalActivation(id, 'disarmed')
       return { ok: true, value: tombstone }
     },
   }
@@ -2503,12 +2693,18 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
     if (goal === undefined) {
       return goalFailure(`invalid goal transition from "${current.goal.phase}"`)
     }
+    const currentActivation = goalActivations.get(id)
+      ?? (current.goal.phase === 'active' ? 'armed' : 'disarmed')
+    const activation = goal.phase === 'active'
+      ? current.goal.phase === 'active' ? currentActivation : 'armed'
+      : 'disarmed'
     const projection = appendGoalChange(id, {
       kind: 'goal/change', version: 1,
       operation: goal.phase === current.goal.phase ? 'edit' : goal.phase === 'paused' ? 'pause' : goal.phase === 'active' ? 'resume' : 'complete',
       goal, roundsStarted: current.roundsStarted, createdAt: current.createdAt, updatedAt: Date.now(),
     })
-    return { ok: true, value: goalView(projection) }
+    setGoalActivation(id, activation)
+    return { ok: true, value: goalView(id, projection) }
   }
 
   /** Canonical fixture implementation of the generated AgentPresets Remote contract. */
@@ -2620,6 +2816,19 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
       const messageSeqs = log.filter(event => event.type === 'user/message').map(event => event.seq)
       append(sid(id), { type: 'session/title', data: { title, messageSeqs, source: { kind: 'provider', provider: 'fixture' } } })
     },
+    /** Disarm the single active goal without a durable phase change. */
+    disarmOnlyGoal(): void {
+      const active = [...logs.entries()].filter(([, log]) => {
+        const current = backscanGoal(log)
+        return current?.goal.phase === 'active'
+      })
+      if (active.length !== 1) {
+        throw new Error(`fixture: expected one active goal, found ${String(active.length)}`)
+      }
+      const [session] = active
+      if (session === undefined) return
+      setGoalActivation(session[0], 'disarmed')
+    },
     /** Start an externally paced reasoning stream for the opt-in browser stress lane. */
     startReasoningChunkStorm(
       id: string,
@@ -3274,6 +3483,27 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
     }
   }
 
+  async function* openWorkspaceFileChanges(signal: AbortSignal): AsyncGenerator<FixtureWorkspaceFileWatchFrame> {
+    signal.throwIfAborted()
+    const conn = new FxInbox<FixtureWorkspaceFileWatchFrame>()
+    const breakNow = (): void => { conn.breakNow() }
+    streamBreakers.add(breakNow)
+    // Opt-in only: an unprompted frame would age every preview of demo.txt
+    // into its changed state on a timer the assembled snapshots cannot see.
+    const announce = options.fileChanges
+      ? setTimeout(() => {
+        conn.push({ kind: 'change', change: { absolutePath: `${WORKSPACE_FILES_ROOT}/notes/demo.txt`, version: 'fx-demo-v2' } })
+      }, 1000)
+      : undefined
+    try {
+      yield { kind: 'ready' }
+      yield* conn.drain(signal)
+    } finally {
+      if (announce !== undefined) clearTimeout(announce)
+      streamBreakers.delete(breakNow)
+    }
+  }
+
   async function* openRemoteEvents(
     signal: AbortSignal,
   ): AsyncGenerator<FixtureRemoteEventReadyFrame | FixtureRemoteEventFrame> {
@@ -3557,6 +3787,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
           line?: string
           query?: string
           path?: string
+          range?: { offset?: number; limit?: number }
           name?: string
           images?: readonly unknown[]
           // A goal ref and a credential reference name share this wire field name.
@@ -3584,6 +3815,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
         case 'directoryPicker/list': return Promise.resolve(directoryPickerRemotes.list(args.path))
         case 'directoryPicker/createDirectory':
           return Promise.resolve(directoryPickerRemotes.createDirectory(args.path ?? '', args.name ?? ''))
+        case 'goals/get': return Promise.resolve(goalRemotes.get(sessionId))
         case 'goals/create': return Promise.resolve(goalRemotes.create(sessionId, {
           objective: (request as { objective?: string } | undefined)?.objective as string,
           ...(request as { maxGoalRounds?: number } | undefined)?.maxGoalRounds === undefined
@@ -3638,6 +3870,15 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
         case 'session/openWorkspacePath': {
           return sessionOk({ opened: true as const })
         }
+        case 'workspaceFiles/read': {
+          return Promise.resolve(workspaceFileRemotes.read(args.path ?? '', args.range ?? {}))
+        }
+        case 'workspaceFiles/stat': {
+          return Promise.resolve(workspaceFileRemotes.stat(args.path ?? ''))
+        }
+        case 'workspaceFiles/list': {
+          return Promise.resolve(workspaceFileRemotes.list(args.path ?? ''))
+        }
         case 'session/canOpenWorkspacePath': return Promise.resolve({ ok: true, value: true })
         case 'session/modelCatalog': return Promise.resolve({
           ok: true,
@@ -3740,6 +3981,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
         case 'session/control': return openControl(signal)
         case 'session/follow': return openFollow(args.request as FixtureFollowRequest, signal)
         case 'workspace/follow': return openWorkspace(signal)
+        case 'workspaceFiles/changes': return openWorkspaceFileChanges(signal)
         default:
           throw new Error(`fixture connection stream endpoint ${JSON.stringify(endpoint)} is unavailable`)
       }
@@ -3766,5 +4008,6 @@ function fixtureOptionsFromLocation(): FixtureOptions {
     failWorkspaceAttach: query.get('fixtureAttach') === 'fail',
     dropSessionCreateResponse: query.get('fixtureSessionCreate') === 'drop-response',
     createFrameOrder: query.get('fixtureFrames') === 'workspace-first' ? 'workspace-first' : 'session-first',
+    fileChanges: query.get('fixtureFileChanges') === 'demo',
   }
 }
diff --git a/packages/client/connection/tests/fixture.client.spec.ts b/packages/client/connection/tests/fixture.client.spec.ts
index b18fde08c9..d3afc8c960 100644
--- a/packages/client/connection/tests/fixture.client.spec.ts
+++ b/packages/client/connection/tests/fixture.client.spec.ts
@@ -501,6 +501,7 @@ interface TimingHooks {
   failNextHistory(): void
   appendUser(id: string, msg: string): void
   appendTitle(id: string, title: string): void
+  disarmOnlyGoal(): void
   startReasoningChunkStorm(id: string, chunkCount: number, chunksPerInterval: number, intervalMs: number): string
   reasoningChunkStormState(): {
     sessionId: string
@@ -1677,6 +1678,13 @@ describe('fixture Connection RPC', () => {
     expect(revision).toBe(1)
     const ref = (at: number) => ({ id: goalId, revision: at })
     expect((await goal('goals/edit', { ref: ref(1), request: { objective: 'ship it v2' } })).ok).toBe(true)
+    expect(await goal('goals/get', {})).toMatchObject({
+      ok: true, value: { objective: 'ship it v2', revision: 2, activation: 'armed' },
+    })
+    timing().disarmOnlyGoal()
+    expect(await goal('goals/get', {})).toMatchObject({
+      ok: true, value: { objective: 'ship it v2', revision: 2, activation: 'disarmed' },
+    })
     expect((await goal('goals/pause', { ref: ref(2) })).ok).toBe(true)
     expect((await goal('goals/resume', { ref: ref(3) })).ok).toBe(true)
     // A stale ref loses the CAS check.
diff --git a/packages/client/locale/tests/language-row.client.spec.tsx b/packages/client/locale/tests/language-row.client.spec.tsx
index 44ddb31e7b..f10adf664e 100644
--- a/packages/client/locale/tests/language-row.client.spec.tsx
+++ b/packages/client/locale/tests/language-row.client.spec.tsx
@@ -1,4 +1,5 @@
 // @vitest-environment jsdom
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 import type { SessionListState } from '@deepseek-ai/dsh-api-session-controller/client'
@@ -9,6 +10,9 @@ import { LanguageRow } from '../src/client/LanguageRow.tsx'
 import type { LanguageRowComponentProps } from '../src/client/LanguageRow.tsx'
 import { createLanguageRowStore } from '../src/client/settings-store.ts'
 
+// Every fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 afterEach(cleanup)
 
 const OPTIONS = [{ id: 'zh', label: '中文' }, { id: 'en', label: 'English' }]
@@ -37,6 +41,7 @@ function mount(active = 'en') {
   const props: LanguageRowComponentProps = {
     useSessions: emptySessions(),
     useSessionPendingInteraction,
+    useResource,
     useWorkspaces: emptyWorkspaces(),
     useStore: bindSnapshotSelector(store),
     actions: store.actions,
diff --git a/packages/client/resources/README.i18n.yaml b/packages/client/resources/README.i18n.yaml
new file mode 100644
index 0000000000..50ca50a65e
--- /dev/null
+++ b/packages/client/resources/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/client/resources/README.md
+README.md: 2bc3d03bc5c58d45f9a0955aa73185be87b2bc6c
+README.zh.md: 43238fd5ff3794204f8d6d989e5d771131b8c489
diff --git a/packages/client/resources/README.md b/packages/client/resources/README.md
new file mode 100644
index 0000000000..2bc3d03bc5
--- /dev/null
+++ b/packages/client/resources/README.md
@@ -0,0 +1,108 @@
+---
+description: "Client resource model: protocol-registered providers turn URL addresses into live values that any slot component reads through the useResource standard hook."
+kind: "package-reference"
+---
+# @deepseek-ai/dsh-client-resources
+
+English | [中文](README.zh.md)
+
+## Summary
+
+The resource model of the web client. A resource is one address, and a resource address is a `dsh-resource://<type>/…` URL whose host is the protocol key; the protocol's owning client package registers a provider that turns an address into a value stream, and any slot component reads that stream through the `useResource` global standard hook. A protocol that needs a scope encodes it in the path (`dsh-resource://file/session/<sessionId>/<absolute path>`); the model knows only addresses, and an address under any other scheme (`sidebar://guide`) names no resource. Use it when a component needs live data it only knows by address (a tab record, a link, a mention) and the data's owner is another client plugin.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+  - [Read a resource](#read-a-resource)
+  - [Provide a protocol](#provide-a-protocol)
+  - [Hold a resource open](#hold-a-resource-open)
+- [Understand the implementation](#understand-the-implementation)
+  - [Lifecycle](#lifecycle)
+  - [Failures](#failures)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Nothing needs configuration to mount: the plugin provides `ctx.resources` and contributes the `resource` root keyed hook through `ctx.slots.provideRoot`, so every slot component receives it whatever its scope.
+
+<a id="read-a-resource"></a>
+### Read a resource
+
+Every slot component receives `useResource` in its props. `useResource<P>(address)` names the protocol as the type argument and returns `{ status, value, failure, reload }`: `none` when no provider is registered for the address's protocol (or the address is not a `dsh-resource://` URL), `loading` while the provider has not yielded, `live` with the latest `ok` frame's value, and `failed` when the latest frame reported a failure, with that failure beside the last value. `reload()` asks the provider for a fresh value and is a no-op without one. Subscribing through the hook is what holds the resource open; a component that mounts while another holder keeps the resource alive reads the latest value at once.
+
+<a id="provide-a-protocol"></a>
+### Provide a protocol
+
+The protocol's owning client package declares its value type in `ResourceProtocolMap` and registers one provider as an owned effect. `open` yields `RemoteResult` frames: the current content first and one frame per later change, with a failure as an `ok: false` frame rather than a throw; it must stop when `signal` aborts. `reload` is optional:
+
+```ts ignore-check
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface ResourceProtocolMap { note: NoteView }
+}
+
+export const inject = ['resources']
+
+export function apply(ctx) {
+  ctx.effect(() => ctx.resources.register<'note'>({
+    protocol: 'note',
+    async *open(address, { signal }) {
+      yield await readNote(address, signal)
+      for await (const change of followNote(address, signal)) yield change
+    },
+    reload(address) { requestReread(address) },
+  }), 'my-notes: note resource provider')
+}
+```
+
+A protocol has exactly one provider; a second registration throws. Registering a provider while addresses of its protocol are already held opens them; disposing it ends their streams and returns them to `none`.
+
+<a id="hold-a-resource-open"></a>
+### Hold a resource open
+
+`ctx.resources.pin(address, signal)` keeps a resource open without subscribing, until `signal` aborts. The right Sidebar pins every open tab's address for the tab record's lifetime, so switching tabs unmounts the body without closing its stream and switching back reads the latest value. `ctx.resources.source(address)` is the bare observable behind the hook, for callers outside React.
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<a id="lifecycle"></a>
+### Lifecycle
+
+One record per address holds a snapshot store, a holder count (hook subscribers plus pins), and the running stream's `AbortController`. The first holder opens the provider's stream; every later holder shares it; the last holder's release aborts the stream and resets the snapshot to idle (`loading` with a provider, `none` without). Records are kept for the page lifetime so `source()` stays reference-stable across React's render-then-subscribe window and a StrictMode remount. `reload` is one function per record and never changes.
+
+<a id="failures"></a>
+### Failures
+
+A failure is a frame, not a throw: a provider yields `{ ok: false, error }` and the resource turns `failed` with that error beside the last value; the next `ok` frame clears it. A stream that ends on its own keeps its last state. Frames that arrive after the release that aborted the stream are dropped, and the iterator is returned. A throw inside a provider's stream is a programming error and is not caught.
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as this package moves values between browser plugins and registers nothing model-facing.
+
+#### KV Cache effect
+
+None; resource streams do not assemble model requests.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Records live for the page lifetime** — an address's record stays in the registry after its last holder leaves; only its state is discarded. Memory grows with the number of distinct addresses ever read, not with reads.
+- **Providers own abort compliance** — the registry drops what a released stream still yields, but a provider that ignores `signal` keeps working until its next frame.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>
+
+**Runtime invariant:** No companion is published. Provider ownership and holder counts have one owner, the registry, with no independent runtime source to compare against; registration disposal and the open/close lifecycle are asserted by behavior specs.
diff --git a/packages/client/resources/README.zh.md b/packages/client/resources/README.zh.md
new file mode 100644
index 0000000000..43238fd5ff
--- /dev/null
+++ b/packages/client/resources/README.zh.md
@@ -0,0 +1,108 @@
+---
+description: "客户端资源模型：按协议注册的提供方把 URL 地址变成活数据，任何 slot 组件都通过 useResource 标准 hook 读取。"
+kind: "package-reference"
+---
+# @deepseek-ai/dsh-client-resources
+
+[English](README.md) | 中文
+
+## 概述
+
+Web 客户端的资源模型。一份资源是一个地址，资源地址是 `dsh-resource://<type>/…` 形式的 URL，host 即协议键；协议所属的客户端包注册一个提供方把地址变成值的流，任何 slot 组件通过 `useResource` 全局标准 hook 读取这条流。需要作用域的协议把它编进路径（`dsh-resource://file/session/<sessionId>/<绝对路径>`）；模型本身只认地址，其它 scheme 的地址（`sidebar://guide`）不指向资源。当组件需要的活数据只以地址形式可知（tab 记录、链接、提及），而数据的拥有者是另一个客户端插件时，请使用它。
+
+## 目录
+
+- [使用本包](#use-this-package)
+  - [读取资源](#read-a-resource)
+  - [提供协议](#provide-a-protocol)
+  - [钉住资源](#hold-a-resource-open)
+- [理解实现](#understand-the-implementation)
+  - [生命周期](#lifecycle)
+  - [失败](#failures)
+- [模型体验](#model-experience)
+- [已知限制与暂缓事项](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+挂载无需任何配置：插件提供 `ctx.resources`，并通过 `ctx.slots.provideRoot` 贡献 `resource` 根 keyed hook，因此每个 slot 组件不论作用域都能收到它。
+
+<a id="read-a-resource"></a>
+### 读取资源
+
+每个 slot 组件都在 props 上收到 `useResource`。`useResource<P>(address)` 以类型参数命名协议，返回 `{ status, value, failure, reload }`：地址协议没有提供方（或地址不是 `dsh-resource://` URL）时为 `none`，提供方尚未产出值时为 `loading`，`live` 携带最新一个 `ok` 帧的值，`failed` 表示最新一帧报告了失败，失败放在最后一个值旁。`reload()` 请提供方给一个新值，没有提供方时是空操作。通过 hook 订阅就是钉住资源的方式；另一个持有者让资源保持存活时，新挂载的组件立刻读到最新值。
+
+<a id="provide-a-protocol"></a>
+### 提供协议
+
+协议所属的客户端包在 `ResourceProtocolMap` 声明其值类型，并以自有 effect 注册一个提供方。`open` 产出 `RemoteResult` 帧：先是当前内容，之后每次变化一帧，失败以 `ok: false` 帧而非抛错表达；必须在 `signal` 中止时停止。`reload` 可选：
+
+```ts ignore-check
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface ResourceProtocolMap { note: NoteView }
+}
+
+export const inject = ['resources']
+
+export function apply(ctx) {
+  ctx.effect(() => ctx.resources.register<'note'>({
+    protocol: 'note',
+    async *open(address, { signal }) {
+      yield await readNote(address, signal)
+      for await (const change of followNote(address, signal)) yield change
+    },
+    reload(address) { requestReread(address) },
+  }), 'my-notes: note resource provider')
+}
+```
+
+一个协议恰有一个提供方；第二次注册会抛错。提供方注册时若其协议的地址已被持有，则立即开流；提供方 dispose 时结束这些流并让它们回到 `none`。
+
+<a id="hold-a-resource-open"></a>
+### 钉住资源
+
+`ctx.resources.pin(address, signal)` 在不订阅的情况下让资源保持打开，直到 `signal` 中止。右侧 Sidebar 在 tab 记录的存续期内钉住每个已打开 tab 的地址，因此切换 tab 卸载正文不会关闭其流，切回时读到最新值。`ctx.resources.source(address)` 是 hook 背后的裸 observable，供 React 之外的调用方使用。
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<a id="lifecycle"></a>
+### 生命周期
+
+每个地址一条记录，持有一个快照 store、一个持有者计数（hook 订阅者加 pin）与运行中流的 `AbortController`。第一个持有者打开提供方的流；之后的持有者共享它；最后一个持有者释放时中止流并把快照重置为空闲（有提供方为 `loading`，没有为 `none`）。记录在页面存续期内保留，使 `source()` 在 React 渲染到订阅的窗口与 StrictMode 重挂载之间保持引用稳定。`reload` 每条记录一个函数，永不变化。
+
+<a id="failures"></a>
+### 失败
+
+失败是帧而非抛错：提供方产出 `{ ok: false, error }`，资源变为 `failed` 并把该错误放在最后一个值旁；下一个 `ok` 帧将其清除。自行结束的流保持其最后状态。在中止流的那次释放之后到达的帧都被丢弃，并归还迭代器。提供方流内的抛错是编程错误，不会被捕获。
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为本包在浏览器插件之间搬运值，不注册任何面向模型的内容。
+
+#### KV Cache 影响
+
+无；资源流不会组装模型请求。
+
+## 已知限制与暂缓事项
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **记录在页面存续期内保留**——地址的记录在最后一个持有者离开后仍留在注册表中，只丢弃其状态。内存随读取过的不同地址数增长，而非随读取次数增长。
+- **中止合规由提供方负责**——注册表会丢弃已释放的流仍产出的帧，但忽略 `signal` 的提供方会一直工作到它的下一帧。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文——点击展开</summary>
+
+无。
+
+</details>
+
+**运行时不变式：** 不发布伴生入口。提供方归属与持有者计数只有注册表这一个拥有者，没有可供比对的独立运行时来源；注册的 dispose 与打开/关闭生命周期由行为测试断言。
diff --git a/packages/client/resources/package.json b/packages/client/resources/package.json
new file mode 100644
index 0000000000..cf240c9af8
--- /dev/null
+++ b/packages/client/resources/package.json
@@ -0,0 +1,57 @@
+{
+  "name": "@deepseek-ai/dsh-client-resources",
+  "description": "Unified client resource model: protocol-registered providers turn URL addresses into live values, consumed through the useResource global standard hook",
+  "version": "0.1.3-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/resources"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-renderer"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "workspace:^"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "workspace:^",
+    "@deepseek-ai/dsh-client-store": "workspace:^",
+    "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-renderer": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-typert-protocol": "workspace:^"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ]
+}
diff --git a/packages/client/resources/src/client/contract.ts b/packages/client/resources/src/client/contract.ts
new file mode 100644
index 0000000000..c297c172b0
--- /dev/null
+++ b/packages/client/resources/src/client/contract.ts
@@ -0,0 +1,122 @@
+/**
+ * The resource model's published face.
+ *
+ * A resource is one address, and a resource address is a
+ * `dsh-resource://<type>/…` URL: the host names the protocol. The protocol's
+ * owning client package registers one {@link ResourceProvider} that turns an
+ * address into a frame stream, and any slot component reads that stream through
+ * {@link UseResource}. A protocol that needs a scope (a session, a workspace)
+ * encodes it in the path, as `dsh-resource://file/session/<sessionId>/<absolute
+ * path>` does; the model itself knows only addresses. Addresses under any other
+ * scheme (`sidebar://guide`) are navigation addresses and name no resource.
+ * `ResourceProtocolMap` (declared
+ * in ui-slots) is the declaration-merged roster of protocol to value type, so a
+ * consumer names the protocol as a type argument and receives the owner's value
+ * type without importing the owner's runtime.
+ */
+import type { RemoteFailure, RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
+import type { ResourceProtocolMap } from '@deepseek-ai/dsh-client-ui-slots'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface GlobalStandardProps {
+    /** Live value of one address, resolved through the provider registered for its protocol. */
+    useResource: UseResource
+  }
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** Resource model: protocol providers, pins, and per-address live sources. */
+    resources: Resources
+  }
+}
+
+/** Every protocol some client package has declared. */
+export type ResourceProtocol = Extract<keyof ResourceProtocolMap, string>
+
+/**
+ * Where one resource stands. `none`: no provider is registered for the
+ * address's protocol, or the address is not a resource address. `loading`: a provider is open and has not yielded yet.
+ * `live`: `value` is the latest `ok` frame's value. `failed`: the latest frame
+ * reported a failure.
+ */
+export type ResourceStatus = 'none' | 'loading' | 'live' | 'failed'
+
+/** One address's current state, as `useResource` returns it. */
+export interface ResourceSnapshot<Value> {
+  readonly status: ResourceStatus
+  /** The latest `ok` frame's value; kept through a later failure frame, absent before the first. */
+  readonly value: Value | undefined
+  /** The latest frame's failure; present only while `status` is `failed`. */
+  readonly failure: RemoteFailure | undefined
+  /** Ask the provider for a fresh frame; a no-op when its protocol has no provider or no `reload`. */
+  readonly reload: () => void
+}
+
+/**
+ * Global standard hook: the current state of one address, typed by the
+ * protocol named as the type argument. Present on every slot component's
+ * props, whatever its scope.
+ */
+export type UseResource = <P extends ResourceProtocol>(
+  address: string,
+) => ResourceSnapshot<ResourceProtocolMap[P]>
+
+/** What a provider's `open` receives beside the address. */
+export interface ResourceOpenContext {
+  /** Aborted when the last subscriber or pin releases the resource; the stream must end. */
+  readonly signal: AbortSignal
+}
+
+/** One protocol's provider, registered through `ctx.resources.register`. */
+export interface ResourceProvider<P extends ResourceProtocol> {
+  /** The URL scheme this provider serves. */
+  readonly protocol: P
+  /**
+   * Open one frame stream for an address. The first frame is the current
+   * content and every later frame one change. An `ok` frame replaces the value;
+   * a failure frame marks the resource `failed` with its error and keeps the
+   * last value. Ending the stream keeps the last state. A failure is always a
+   * frame: a throw inside the stream is a programming error and is not caught.
+   * @param address - the full address, a `dsh-resource://<type>/…` URL.
+   * @param ctx - the stream's abort signal.
+   * @returns the frame stream; it must stop once `ctx.signal` aborts.
+   */
+  open(address: string, ctx: ResourceOpenContext): AsyncIterable<RemoteResult<ResourceProtocolMap[P]>>
+  /**
+   * Produce a fresh frame on the open stream. Absent when the protocol has no refresh.
+   * @param address - the full address, a `dsh-resource://<type>/…` URL.
+   */
+  reload?(address: string): void
+}
+
+/**
+ * The `ctx.resources` service. One resource is one address; it stays open
+ * while at least one `source` subscriber or one pin holds it, and the
+ * provider's stream is aborted and the state discarded when the last holder
+ * releases.
+ */
+export interface Resources {
+  /**
+   * Register the provider for one protocol for the caller's lifetime.
+   * @param provider - the protocol's provider.
+   * @returns idempotent disposer, held inside the caller's own `ctx.effect`.
+   * @throws when the protocol already has a provider.
+   */
+  register<P extends ResourceProtocol>(provider: ResourceProvider<P>): () => void
+  /**
+   * Hold one resource open without subscribing to it.
+   * @param address - the full address, a `dsh-resource://<type>/…` URL.
+   * @param signal - aborting it releases the pin; an already-aborted signal pins nothing.
+   */
+  pin(address: string, signal: AbortSignal): void
+  /**
+   * The live source of one resource. Reference-stable for one address while
+   * the resource is held; the first subscriber or pin opens the provider's
+   * stream, and a subscriber arriving later reads the latest value at once.
+   * @param address - the full address, a `dsh-resource://<type>/…` URL.
+   * @returns the observable state; `getSnapshot` reads without holding the resource.
+   */
+  source(address: string): ObservableSnapshot<ResourceSnapshot<unknown>>
+}
diff --git a/packages/client/resources/src/client/index.ts b/packages/client/resources/src/client/index.ts
new file mode 100644
index 0000000000..68d7a27e7d
--- /dev/null
+++ b/packages/client/resources/src/client/index.ts
@@ -0,0 +1,41 @@
+/**
+ * Browser half: `ctx.resources` (protocol-registered providers, pinning, live
+ * sources) and the `useResource` global standard hook.
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis'
+// Type-only service merge for ctx.slots.
+import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
+import type { RootStandardSourceContribution } from '@deepseek-ai/dsh-client-ui-slots'
+import { ResourceRegistry } from './resources.ts'
+
+export type {
+  ResourceOpenContext,
+  ResourceProtocol,
+  ResourceProvider,
+  Resources,
+  ResourceSnapshot,
+  ResourceStatus,
+  UseResource,
+} from './contract.ts'
+export type { ResourceProtocolMap } from '@deepseek-ai/dsh-client-ui-slots'
+
+/** Required browser services. */
+export const inject = ['slots']
+
+/**
+ * Client plugin body: provide `ctx.resources` and contribute the `resource`
+ * root keyed hook that reaches every slot component as `useResource`.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  // Built at apply's top level, never inside an effect: other plugins call
+  // `register()` from their own apply, and it adds an effect to this fiber.
+  const resources = new ResourceRegistry(ctx)
+  const disposeService = ctx.reflect.provide('resources', resources)
+  // Registered first, so it tears down last: the face outlives every provider
+  // that registered into it.
+  ctx.effect(() => () => { void disposeService() }, 'client-resources: service face')
+  ctx.slots.provideRoot({
+    keyedHooks: { resource: address => resources.source(address) },
+  } satisfies RootStandardSourceContribution)
+}
diff --git a/packages/client/resources/src/client/resources.ts b/packages/client/resources/src/client/resources.ts
new file mode 100644
index 0000000000..5b9a75cabe
--- /dev/null
+++ b/packages/client/resources/src/client/resources.ts
@@ -0,0 +1,217 @@
+/**
+ * `ctx.resources`: the provider registry and the per-address states behind
+ * `useResource`.
+ *
+ * A record is kept for every address ever sourced and is never dropped; what
+ * the last release discards is its state (the stream is aborted and the
+ * snapshot returns to idle). Keeping the record keeps `source()` reference-stable
+ * across React's render-then-subscribe window and a StrictMode remount, where a
+ * recreated record would make every render resubscribe and restart the stream.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
+import { createSnapshotStore, type ObservableSnapshot, type SnapshotStore } from '@deepseek-ai/dsh-client-store'
+import type {
+  ResourceOpenContext,
+  ResourceProtocol,
+  ResourceProvider,
+  Resources,
+  ResourceSnapshot,
+} from './contract.ts'
+
+/** A provider with its value type erased, so one map holds every protocol. */
+interface RuntimeProvider {
+  readonly protocol: string
+  open(address: string, ctx: ResourceOpenContext): AsyncIterable<RemoteResult<unknown>>
+  reload?(address: string): void
+}
+
+/** One address: its state, its holders, and the running stream. */
+interface ResourceRecord {
+  readonly address: string
+  /** The address's protocol key (`dsh-resource://` host); absent when the address is not a resource address. */
+  readonly protocol: string | undefined
+  readonly store: SnapshotStore<ResourceSnapshot<unknown>>
+  readonly source: ObservableSnapshot<ResourceSnapshot<unknown>>
+  readonly reload: () => void
+  /** Subscribers plus pins; the stream runs while this is positive. */
+  holders: number
+  /** Present while the provider's stream runs; aborting it ends the stream. */
+  controller: AbortController | undefined
+}
+
+/**
+ * The one URL scheme resource addresses use: `dsh-resource://<type>/…`, where
+ * the host names the protocol. Other schemes (`sidebar://…`) are navigation
+ * addresses and name no resource.
+ */
+export const RESOURCE_SCHEME = 'dsh-resource'
+
+/**
+ * The protocol key of one address: the host of a `dsh-resource://` URL, as the
+ * URL parser reads it (lower-cased). Any other string — another scheme, or one
+ * the URL parser rejects — names no protocol and is treated like an address
+ * whose protocol has no provider.
+ * @param address - the full address.
+ * @returns the protocol key, or `undefined` when the address is not a resource address.
+ */
+export function protocolOf(address: string): string | undefined {
+  let parsed: URL
+  try {
+    parsed = new URL(address)
+  } catch {
+    // The URL parser rejects strings without a scheme (`/a/b.txt`, `''`);
+    // nothing else throws here, and an unparseable address is simply not ours.
+    return undefined
+  }
+  if (parsed.protocol !== `${RESOURCE_SCHEME}:`) return undefined
+  // A non-special scheme's host is opaque to the URL parser and keeps its case.
+  return parsed.hostname === '' ? undefined : parsed.hostname.toLowerCase()
+}
+
+function idle(status: 'none' | 'loading', reload: () => void): ResourceSnapshot<unknown> {
+  return { status, value: undefined, failure: undefined, reload }
+}
+
+/** The `ctx.resources` implementation. */
+export class ResourceRegistry implements Resources {
+  private readonly providers = new Map<string, RuntimeProvider>()
+  private readonly records = new Map<string, ResourceRecord>()
+
+  /** @param ctx - Context whose effects own the registered providers. */
+  constructor(private readonly ctx: Context) {}
+
+  register<P extends ResourceProtocol>(provider: ResourceProvider<P>): () => void {
+    const runtime: RuntimeProvider = provider
+    const { protocol } = runtime
+    if (this.providers.has(protocol)) {
+      throw new Error(`resources: protocol "${protocol}" already has a provider`)
+    }
+    const dispose = this.ctx.effect(() => {
+      this.providers.set(protocol, runtime)
+      for (const record of this.recordsOf(protocol)) this.attach(record)
+      return () => {
+        this.providers.delete(protocol)
+        for (const record of this.recordsOf(protocol)) this.detach(record)
+      }
+    }, `resources.register(${JSON.stringify(protocol)})`)
+    return () => { void dispose() }
+  }
+
+  pin(address: string, signal: AbortSignal): void {
+    if (signal.aborted) return
+    const record = this.record(address)
+    this.hold(record)
+    signal.addEventListener('abort', () => { this.release(record) }, { once: true })
+  }
+
+  source(address: string): ObservableSnapshot<ResourceSnapshot<unknown>> {
+    return this.record(address).source
+  }
+
+  private record(address: string): ResourceRecord {
+    let record = this.records.get(address)
+    if (record === undefined) {
+      record = this.create(address)
+      this.records.set(address, record)
+    }
+    return record
+  }
+
+  private create(address: string): ResourceRecord {
+    const protocol = protocolOf(address)
+    const reload = (): void => {
+      this.providerOf(protocol)?.reload?.(address)
+    }
+    const store = createSnapshotStore<ResourceSnapshot<unknown>>(
+      idle(this.providerOf(protocol) === undefined ? 'none' : 'loading', reload),
+    )
+    const record: ResourceRecord = {
+      address,
+      protocol,
+      store,
+      reload,
+      holders: 0,
+      controller: undefined,
+      source: {
+        getSnapshot: () => store.getSnapshot(),
+        subscribe: (listener) => {
+          const unsubscribe = store.subscribe(listener)
+          this.hold(record)
+          let active = true
+          return () => {
+            if (!active) return
+            active = false
+            unsubscribe()
+            this.release(record)
+          }
+        },
+      },
+    }
+    return record
+  }
+
+  private providerOf(protocol: string | undefined): RuntimeProvider | undefined {
+    return protocol === undefined ? undefined : this.providers.get(protocol)
+  }
+
+  private *recordsOf(protocol: string): Iterable<ResourceRecord> {
+    for (const record of this.records.values()) {
+      if (record.protocol === protocol) yield record
+    }
+  }
+
+  private hold(record: ResourceRecord): void {
+    record.holders += 1
+    if (record.holders === 1) this.start(record)
+  }
+
+  private release(record: ResourceRecord): void {
+    record.holders -= 1
+    if (record.holders > 0) return
+    this.stop(record)
+    record.store.set(idle(this.providerOf(record.protocol) === undefined ? 'none' : 'loading', record.reload))
+  }
+
+  /** The provider arrived: a held record opens its stream, an idle one turns `loading`. */
+  private attach(record: ResourceRecord): void {
+    if (record.holders > 0) {
+      this.start(record)
+      return
+    }
+    record.store.set(idle('loading', record.reload))
+  }
+
+  /** The provider left: the stream ends and the record reports `none`. */
+  private detach(record: ResourceRecord): void {
+    this.stop(record)
+    record.store.set(idle('none', record.reload))
+  }
+
+  private start(record: ResourceRecord): void {
+    const provider = this.providerOf(record.protocol)
+    if (provider === undefined) return
+    const controller = new AbortController()
+    record.controller = controller
+    if (record.store.getSnapshot().status !== 'loading') record.store.set(idle('loading', record.reload))
+    void this.consume(record, provider, controller.signal)
+  }
+
+  private stop(record: ResourceRecord): void {
+    record.controller?.abort()
+    record.controller = undefined
+  }
+
+  /** Failures arrive as frames; a throw inside the stream is left to surface. */
+  private async consume(record: ResourceRecord, provider: RuntimeProvider, signal: AbortSignal): Promise<void> {
+    const stream = provider.open(record.address, { signal })
+    for await (const frame of stream) {
+      // A frame the provider yields after the release that aborted it belongs
+      // to nobody; ending the loop also returns the iterator.
+      if (signal.aborted) break
+      record.store.set(frame.ok
+        ? { status: 'live', value: frame.value, failure: undefined, reload: record.reload }
+        : { status: 'failed', value: record.store.getSnapshot().value, failure: frame.error, reload: record.reload })
+    }
+  }
+}
diff --git a/packages/client/resources/src/index.ts b/packages/client/resources/src/index.ts
new file mode 100644
index 0000000000..b6c7e73b8c
--- /dev/null
+++ b/packages/client/resources/src/index.ts
@@ -0,0 +1,4 @@
+/** Pure host half; the resource model lives in the browser export. */
+
+/** Host plugin body: the resource model contributes nothing to the host tree. */
+export function apply(): void {}
diff --git a/packages/client/resources/tests/apply.client.spec.ts b/packages/client/resources/tests/apply.client.spec.ts
new file mode 100644
index 0000000000..810ba7dbc1
--- /dev/null
+++ b/packages/client/resources/tests/apply.client.spec.ts
@@ -0,0 +1,98 @@
+// @vitest-environment jsdom
+/**
+ * The plugin's wiring: `ctx.resources` is provided, the `resource` root keyed
+ * hook reaches every slot component as `useResource`, and both leave with the
+ * fiber so a reload of the plugin registers cleanly again.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { act } from '@testing-library/react'
+import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
+import { apply, inject, type ResourceSnapshot, type UseResource } from '../src/client/index.ts'
+import { apply as hostApply } from '../src/index.ts'
+import { ResourceRegistry } from '../src/client/resources.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    'resources.probe': { kind: 'single'; scope: 'root' }
+  }
+  interface ResourceProtocolMap {
+    feed: string
+  }
+}
+
+const A = 'dsh-resource://feed/one'
+let runtime: SlotTestRuntime | undefined
+
+afterEach(async () => {
+  await runtime?.dispose()
+  runtime = undefined
+})
+
+const settle = (): Promise<void> => new Promise((resolve) => { setTimeout(resolve, 0) })
+
+async function boot(): Promise<SlotTestRuntime> {
+  const rt = await SlotTestRuntime.create()
+  await rt.declare({ 'resources.probe': { kind: 'single', scope: 'root' } })
+  return rt
+}
+
+describe('client-resources apply', () => {
+  it('keeps the host Loader entry inert', () => {
+    expect(hostApply).not.toThrow()
+  })
+
+  it('provides ctx.resources and hands every slot component useResource over the shared source', async () => {
+    runtime = await boot()
+    await runtime.mount({ inject: [...inject], apply })
+    expect(runtime.ctx.resources).toBeInstanceOf(ResourceRegistry)
+
+    // A root-scope component reading one address through the standard hook.
+    let seen: ResourceSnapshot<string> | undefined
+    runtime.slots.register({ name: 'resources.probe' }, ({ useResource }: { useResource: UseResource }) => {
+      seen = useResource<'feed'>(A)
+      return null
+    })
+    runtime.renderSlot('resources.probe', {})
+    expect(seen).toMatchObject({ status: 'none', value: undefined })
+
+    let push: ((value: string) => void) | undefined
+    await act(async () => {
+      runtime!.ctx.effect(() => runtime!.ctx.resources.register<'feed'>({
+        protocol: 'feed',
+        open: () => ({
+          [Symbol.asyncIterator]: () => ({
+            next: () => new Promise<IteratorResult<RemoteResult<string>>>((resolve) => {
+              push = (value) => { resolve({ done: false, value: { ok: true, value } }) }
+            }),
+          }),
+        }),
+      }), 'spec: feed provider')
+    })
+    expect(seen).toMatchObject({ status: 'loading' })
+    // Rendering the hook is what holds the address: the provider's stream is open.
+    expect(push).toBeDefined()
+    await act(async () => { push!('v1'); await settle() })
+    expect(seen).toMatchObject({ status: 'live', value: 'v1' })
+    expect(runtime.ctx.resources.source(A).getSnapshot()).toBe(seen)
+  })
+
+  it('withdraws both on dispose, so a remount registers again without a duplicate', async () => {
+    runtime = await boot()
+    const handle = await runtime.mount({ inject: [...inject], apply })
+    await handle.dispose()
+    expect(runtime.ctx.get('resources')).toBeUndefined()
+
+    // Records only whether the standard hook is present on a root-scope component's props.
+    let hook: UseResource | undefined
+    runtime.slots.register({ name: 'resources.probe' }, (props: { useResource?: UseResource }) => {
+      hook = props.useResource
+      return null
+    })
+    runtime.renderSlot('resources.probe', {})
+    expect(hook).toBeUndefined()
+
+    await runtime.mount({ inject: [...inject], apply })
+    expect(hook).toBeTypeOf('function')
+  })
+})
diff --git a/packages/client/resources/tests/resources.client.spec.ts b/packages/client/resources/tests/resources.client.spec.ts
new file mode 100644
index 0000000000..bc04ca2d7a
--- /dev/null
+++ b/packages/client/resources/tests/resources.client.spec.ts
@@ -0,0 +1,359 @@
+/**
+ * The resource lifecycle: one address opens when its first holder arrives,
+ * stays open across holder changes, and closes when the last one leaves.
+ * Providers are scripted feeds so every transition is driven by the spec,
+ * never by timing.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import type { RemoteFailure, RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
+import { RemoteError } from '@deepseek-ai/dsh-client-test-runtime'
+import { protocolOf, RESOURCE_SCHEME, ResourceRegistry } from '../src/client/resources.ts'
+import type { ResourceOpenContext, ResourceProvider } from '../src/client/contract.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface ResourceProtocolMap {
+    feed: string
+  }
+}
+
+const A = `${RESOURCE_SCHEME}://feed/one`
+
+/** One scripted stream: the spec pushes value frames, failure frames, or ends it. */
+interface Feed {
+  readonly ctx: ResourceOpenContext
+  push(value: string): void
+  fail(error: RemoteFailure): void
+  end(): void
+  /** Whether the consumer returned the iterator (its `finally` ran). */
+  readonly returned: boolean
+}
+
+type Step = { readonly kind: 'frame'; readonly frame: RemoteResult<string> } | { readonly kind: 'end' }
+
+function createFeed(ctx: ResourceOpenContext): { feed: Feed; stream: AsyncIterable<RemoteResult<string>> } {
+  const steps: Step[] = []
+  let wake: (() => void) | undefined
+  let returned = false
+  const notify = (): void => { wake?.(); wake = undefined }
+  async function* stream(): AsyncGenerator<RemoteResult<string>> {
+    try {
+      for (;;) {
+        if (steps.length === 0) await new Promise<void>((resolve) => { wake = resolve })
+        const step = steps.shift()
+        if (step === undefined) continue
+        if (step.kind === 'end') return
+        yield step.frame
+      }
+    } finally {
+      returned = true
+    }
+  }
+  const feed: Feed = {
+    ctx,
+    push: (value) => { steps.push({ kind: 'frame', frame: { ok: true, value } }); notify() },
+    fail: (error) => { steps.push({ kind: 'frame', frame: { ok: false, error } }); notify() },
+    end: () => { steps.push({ kind: 'end' }); notify() },
+    get returned() { return returned },
+  }
+  return { feed, stream: stream() }
+}
+
+/** A `feed` provider whose every `open` is recorded and spec-driven. */
+function scriptedProvider() {
+  const opens: Feed[] = []
+  const provider = {
+    protocol: 'feed' as const,
+    open: vi.fn((_address: string, ctx: ResourceOpenContext) => {
+      const { feed, stream } = createFeed(ctx)
+      opens.push(feed)
+      return stream
+    }),
+    reload: vi.fn(),
+  } satisfies ResourceProvider<'feed'>
+  return { provider, opens, last: () => opens[opens.length - 1]! }
+}
+
+const settle = (): Promise<void> => new Promise((resolve) => { setTimeout(resolve, 0) })
+
+function bench() {
+  const ctx = new Context()
+  const registry = new ResourceRegistry(ctx)
+  const scripted = scriptedProvider()
+  const snapshot = (address = A) => registry.source(address).getSnapshot()
+  return { ctx, registry, ...scripted, snapshot }
+}
+
+describe('protocolOf', () => {
+  it('reads the dsh-resource host, lower-cased, and reports none for any other address', () => {
+    expect(protocolOf('dsh-resource://file/session/s1/home/ys/b.txt')).toBe('file')
+    expect(protocolOf('DSH-RESOURCE://File/session/s1/a')).toBe('file')
+    expect(protocolOf('dsh-resource://chat/node/1')).toBe('chat')
+    // A navigation address is not a resource.
+    expect(protocolOf('sidebar://guide')).toBeUndefined()
+    expect(protocolOf('file://sessions/s1/a.txt')).toBeUndefined()
+    expect(protocolOf('dsh-resource:///no-host')).toBeUndefined()
+    expect(protocolOf('/a/b.txt')).toBeUndefined()
+    expect(protocolOf('')).toBeUndefined()
+  })
+})
+
+describe('ResourceRegistry providers', () => {
+  it('owns a protocol by exactly one provider, and frees it on dispose', () => {
+    const b = bench()
+    const dispose = b.registry.register(b.provider)
+    expect(() => b.registry.register(scriptedProvider().provider)).toThrow('protocol "feed" already has a provider')
+    dispose()
+    dispose()
+    expect(() => b.registry.register(scriptedProvider().provider)).not.toThrow()
+  })
+
+  it('reports none for an address whose protocol has no provider, and for a navigation address', () => {
+    const b = bench()
+    expect(b.snapshot()).toMatchObject({ status: 'none', value: undefined, failure: undefined })
+    expect(b.snapshot('sidebar://guide')).toMatchObject({ status: 'none' })
+    const unsubscribe = b.registry.source(A).subscribe(() => {})
+    expect(b.snapshot().status).toBe('none')
+    unsubscribe()
+  })
+
+  it('opens a held address when its provider arrives, and closes it when the provider leaves', async () => {
+    const b = bench()
+    const seen = vi.fn()
+    b.registry.source(A).subscribe(seen)
+    expect(b.snapshot().status).toBe('none')
+
+    const dispose = b.registry.register(b.provider)
+    expect(b.snapshot().status).toBe('loading')
+    expect(b.provider.open).toHaveBeenCalledWith(A, { signal: expect.any(AbortSignal) as AbortSignal })
+    b.last().push('v1')
+    await vi.waitFor(() => { expect(b.snapshot()).toMatchObject({ status: 'live', value: 'v1' }) })
+
+    dispose()
+    expect(b.last().ctx.signal.aborted).toBe(true)
+    expect(b.snapshot()).toMatchObject({ status: 'none', value: undefined })
+    expect(seen).toHaveBeenCalled()
+  })
+
+  it('opens the arriving protocol\'s held addresses only, leaving another protocol\'s records as they were', () => {
+    const b = bench()
+    const other = `${RESOURCE_SCHEME}://other/one`
+    b.registry.source(other).subscribe(() => {})
+    b.registry.source(A).subscribe(() => {})
+    b.registry.register(b.provider)
+    expect(b.snapshot().status).toBe('loading')
+    expect(b.snapshot(other).status).toBe('none')
+    expect(b.provider.open).toHaveBeenCalledExactlyOnceWith(A, { signal: expect.any(AbortSignal) as AbortSignal })
+  })
+
+  it('turns an idle, unheld address to loading when its provider arrives, without opening it', () => {
+    const b = bench()
+    expect(b.snapshot().status).toBe('none')
+    b.registry.register(b.provider)
+    expect(b.snapshot().status).toBe('loading')
+    expect(b.provider.open).not.toHaveBeenCalled()
+  })
+
+  it('drops a registration when the registering fiber is disposed', async () => {
+    const b = bench()
+    const fiber = b.ctx.plugin({
+      apply: (child: Context) => { child.effect(() => b.registry.register(b.provider), 'spec: feed provider') },
+    })
+    await fiber.await()
+    expect(b.snapshot().status).toBe('loading')
+    await fiber.dispose()
+    expect(b.snapshot().status).toBe('none')
+    expect(() => b.registry.register(scriptedProvider().provider)).not.toThrow()
+  })
+
+  it('drops every registration when the registry\'s own fiber is disposed', async () => {
+    const root = new Context()
+    let registry: ResourceRegistry | undefined
+    const fiber = root.plugin({ apply: (child: Context) => { registry = new ResourceRegistry(child) } })
+    await fiber.await()
+    const { provider } = scriptedProvider()
+    registry!.register(provider)
+    registry!.source(A).subscribe(() => {})
+    expect(provider.open).toHaveBeenCalledTimes(1)
+    await fiber.dispose()
+    expect(registry!.source(A).getSnapshot().status).toBe('none')
+  })
+})
+
+describe('ResourceRegistry holders', () => {
+  it('opens on the first subscriber only, and closes after the last one leaves', async () => {
+    const b = bench()
+    b.registry.register(b.provider)
+    const source = b.registry.source(A)
+    expect(b.provider.open).not.toHaveBeenCalled()
+
+    const first = source.subscribe(() => {})
+    const second = source.subscribe(() => {})
+    expect(b.provider.open).toHaveBeenCalledTimes(1)
+    b.last().push('v1')
+    await vi.waitFor(() => { expect(source.getSnapshot().value).toBe('v1') })
+
+    first()
+    first()
+    expect(b.last().ctx.signal.aborted).toBe(false)
+    expect(source.getSnapshot().value).toBe('v1')
+
+    second()
+    expect(b.last().ctx.signal.aborted).toBe(true)
+    expect(source.getSnapshot()).toMatchObject({ status: 'loading', value: undefined })
+  })
+
+  it('keeps one source per address and separates addresses', () => {
+    const b = bench()
+    expect(b.registry.source(A)).toBe(b.registry.source(A))
+    expect(b.registry.source(A)).not.toBe(b.registry.source(`${RESOURCE_SCHEME}://feed/two`))
+  })
+
+  it('pins hold the address open until the signal aborts; an aborted signal pins nothing', () => {
+    const b = bench()
+    b.registry.register(b.provider)
+    const controller = new AbortController()
+    b.registry.pin(A, controller.signal)
+    expect(b.provider.open).toHaveBeenCalledTimes(1)
+    controller.abort()
+    expect(b.last().ctx.signal.aborted).toBe(true)
+
+    const aborted = new AbortController()
+    aborted.abort()
+    b.registry.pin(A, aborted.signal)
+    expect(b.provider.open).toHaveBeenCalledTimes(1)
+  })
+
+  it('hands a remounting subscriber the latest value without reopening while a pin holds it', async () => {
+    const b = bench()
+    b.registry.register(b.provider)
+    const pin = new AbortController()
+    b.registry.pin(A, pin.signal)
+    const source = b.registry.source(A)
+
+    const unsubscribe = source.subscribe(() => {})
+    b.last().push('v1')
+    b.last().push('v2')
+    await vi.waitFor(() => { expect(source.getSnapshot().value).toBe('v2') })
+    unsubscribe()
+    b.last().push('v3')
+    await vi.waitFor(() => { expect(source.getSnapshot().value).toBe('v3') })
+
+    const seen = vi.fn()
+    source.subscribe(seen)
+    expect(source.getSnapshot()).toMatchObject({ status: 'live', value: 'v3' })
+    expect(b.provider.open).toHaveBeenCalledTimes(1)
+    expect(seen).not.toHaveBeenCalled()
+  })
+
+  it('reopens after the last holder left, as a fresh stream', async () => {
+    const b = bench()
+    b.registry.register(b.provider)
+    const source = b.registry.source(A)
+    const first = source.subscribe(() => {})
+    b.last().push('v1')
+    await vi.waitFor(() => { expect(source.getSnapshot().value).toBe('v1') })
+    first()
+
+    const second = source.subscribe(() => {})
+    expect(b.provider.open).toHaveBeenCalledTimes(2)
+    expect(source.getSnapshot()).toMatchObject({ status: 'loading', value: undefined })
+    b.last().push('v2')
+    await vi.waitFor(() => { expect(source.getSnapshot().value).toBe('v2') })
+    second()
+  })
+})
+
+describe('ResourceRegistry streams', () => {
+  it('ignores what a released stream still yields, and returns its iterator', async () => {
+    const b = bench()
+    b.registry.register(b.provider)
+    const source = b.registry.source(A)
+    const unsubscribe = source.subscribe(() => {})
+    const feed = b.last()
+    unsubscribe()
+    expect(feed.ctx.signal.aborted).toBe(true)
+
+    feed.push('late')
+    await settle()
+    await settle()
+    expect(source.getSnapshot()).toMatchObject({ status: 'loading', value: undefined })
+    expect(feed.returned).toBe(true)
+  })
+
+  it('keeps the last value live when the stream ends on its own', async () => {
+    const b = bench()
+    b.registry.register(b.provider)
+    const source = b.registry.source(A)
+    source.subscribe(() => {})
+    b.last().push('v1')
+    b.last().end()
+    await settle()
+    await settle()
+    expect(source.getSnapshot()).toMatchObject({ status: 'live', value: 'v1' })
+  })
+
+  it('reports a failure frame beside the last value, and the next ok frame clears it', async () => {
+    const b = bench()
+    b.registry.register(b.provider)
+    const source = b.registry.source(A)
+    source.subscribe(() => {})
+    b.last().push('v1')
+    await vi.waitFor(() => { expect(source.getSnapshot().value).toBe('v1') })
+    const failure = new RemoteError('gateway/bad-request', 'refused', {})
+    b.last().fail(failure)
+    await vi.waitFor(() => { expect(source.getSnapshot().status).toBe('failed') })
+    expect(source.getSnapshot()).toMatchObject({ value: 'v1', failure })
+    b.last().push('v2')
+    await vi.waitFor(() => { expect(source.getSnapshot().status).toBe('live') })
+    expect(source.getSnapshot()).toMatchObject({ value: 'v2', failure: undefined })
+  })
+
+  it('reports a failure frame that arrives first with no value', async () => {
+    const b = bench()
+    b.registry.register(b.provider)
+    const source = b.registry.source(A)
+    source.subscribe(() => {})
+    b.last().fail(new RemoteError('gateway/bad-request', 'refused', {}))
+    await vi.waitFor(() => { expect(source.getSnapshot().status).toBe('failed') })
+    expect(source.getSnapshot()).toMatchObject({ value: undefined, failure: { code: 'gateway/bad-request' } })
+  })
+
+  it('drops a failure frame that follows the release that aborted the stream', async () => {
+    const b = bench()
+    b.registry.register(b.provider)
+    const source = b.registry.source(A)
+    const unsubscribe = source.subscribe(() => {})
+    const feed = b.last()
+    unsubscribe()
+    feed.fail(new RemoteError('gateway/internal', 'after abort', {}))
+    await settle()
+    await settle()
+    expect(source.getSnapshot()).toMatchObject({ status: 'loading', failure: undefined })
+  })
+})
+
+describe('ResourceRegistry reload', () => {
+  it('forwards reload to the protocol\'s provider, and stays a no-op without one', () => {
+    const b = bench()
+    b.snapshot().reload()
+    b.registry.register(b.provider)
+    b.snapshot().reload()
+    expect(b.provider.reload).toHaveBeenCalledWith(A)
+
+    const bare = bench()
+    bare.registry.register({ protocol: 'feed', open: bare.provider.open })
+    expect(() => { bare.snapshot().reload() }).not.toThrow()
+  })
+
+  it('keeps one reload function per address across state changes', async () => {
+    const b = bench()
+    b.registry.register(b.provider)
+    const source = b.registry.source(A)
+    const { reload } = source.getSnapshot()
+    source.subscribe(() => {})
+    b.last().push('v1')
+    await vi.waitFor(() => { expect(source.getSnapshot().value).toBe('v1') })
+    expect(source.getSnapshot().reload).toBe(reload)
+  })
+})
diff --git a/packages/client/resources/tsconfig.json b/packages/client/resources/tsconfig.json
new file mode 100644
index 0000000000..30cb2fc68a
--- /dev/null
+++ b/packages/client/resources/tsconfig.json
@@ -0,0 +1,27 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../typert/protocol"
+    },
+    {
+      "path": "../store"
+    },
+    {
+      "path": "../ui-renderer"
+    },
+    {
+      "path": "../ui-slots"
+    }
+  ]
+}
diff --git a/packages/client/resources/tsdown.config.ts b/packages/client/resources/tsdown.config.ts
new file mode 100644
index 0000000000..a6e81e749c
--- /dev/null
+++ b/packages/client/resources/tsdown.config.ts
@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-resources', ['lib/types/index.js'])
diff --git a/packages/client/ui-agent-preset/src/client/AgentPresetSeat.module.css b/packages/client/ui-agent-preset/src/client/AgentPresetSeat.module.css
index 55fe22e81b..982603c94c 100644
--- a/packages/client/ui-agent-preset/src/client/AgentPresetSeat.module.css
+++ b/packages/client/ui-agent-preset/src/client/AgentPresetSeat.module.css
@@ -1,10 +1,25 @@
 /* Agent-preset chip on the new-session screen, beside the workspace picker.
    Geometry mirrors HeroShell's .workspace so the two read as one row. */
 
+/* Overflow-driven degradation (mirrors HeroShell's .workspace), no
+   breakpoint: the label shrinks with an ellipsis down to nothing, so the
+   preset icon and chevron always sit snug against whatever text remains —
+   full text, ellipsized text, or none. */
+/* The Menu anchor wrapper between the row and this chip: its flex
+   auto-minimum would hold the full label width and the row could never
+   compress the chip. The explicit floor is the icon-only end state — 8px
+   paddings + 16px icon + two 4px gaps + 14px chevron — so the glyphs never
+   crush once the label has ellipsized away to nothing. */
+.menuAnchor {
+  min-width: 54px;
+  max-width: 100%;
+}
+
 .seat {
   display: inline-flex;
   align-items: center;
   gap: 4px;
+  min-width: 0;
   max-width: min(100%, 240px);
   min-height: 28px;
   padding: 0 8px;
@@ -16,8 +31,6 @@
   line-height: 20px;
   font-weight: 500;
   white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
   cursor: pointer;
 }
 
@@ -36,6 +49,13 @@
   color: var(--dsw-alias-label-primary);
 }
 
+.seatLabel {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
 /* Introduce cue: the icon eases in on an overshoot-free expo curve (duration
    matches INTRO_TEXT_DELAY_MS, so the characters start the moment it lands),
    then the name's characters fade up on a stagger (delays set inline per
diff --git a/packages/client/ui-agent-preset/src/client/AgentPresetSeat.tsx b/packages/client/ui-agent-preset/src/client/AgentPresetSeat.tsx
index d0501ed0cd..f16d1c83d9 100644
--- a/packages/client/ui-agent-preset/src/client/AgentPresetSeat.tsx
+++ b/packages/client/ui-agent-preset/src/client/AgentPresetSeat.tsx
@@ -181,6 +181,7 @@ export function AgentPresetSeat({ load, select, introduced, useAgentPresetSeat,
         }}
         align="start"
         portal
+        className={css.menuAnchor}
         anchor={(
           <button
             type="button"
@@ -192,7 +193,7 @@ export function AgentPresetSeat({ load, select, introduced, useAgentPresetSeat,
             onClick={() => { setOpen(value => !value) }}
           >
             <IconAgentPresetOutline16 className={introducing ? `${css.seatIcon} ${css.introIcon}` : css.seatIcon} />
-            {shownLabel}
+            <span className={css.seatLabel}>{shownLabel}</span>
             <IconChevronDownOutline14 className={css.chevron} />
           </button>
         )}
diff --git a/packages/client/ui-attachment/src/FileCard.module.css b/packages/client/ui-attachment/src/FileCard.module.css
index 71de9ec4bf..ac4de3905e 100644
--- a/packages/client/ui-attachment/src/FileCard.module.css
+++ b/packages/client/ui-attachment/src/FileCard.module.css
@@ -106,6 +106,18 @@
   opacity: 1;
 }
 
+@media (pointer: coarse) {
+  .remove {
+    opacity: 1;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .remove {
+    transition: none;
+  }
+}
+
 .card:hover .name,
 .card:focus-within .name {
   padding-right: 18px;
diff --git a/packages/client/ui-attachment/src/FileCard.tsx b/packages/client/ui-attachment/src/FileCard.tsx
index d5634b7d9a..e10c91993c 100644
--- a/packages/client/ui-attachment/src/FileCard.tsx
+++ b/packages/client/ui-attachment/src/FileCard.tsx
@@ -1,4 +1,4 @@
-import { DocumentFileIcon, fileSizeText } from '@deepseek-ai/dsh-client-ui-primitives'
+import { DocumentFileIcon, fileSizeText, IconCloseFill14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import css from './FileCard.module.css'
 
 /** Localized strings consumed by one pending-file card. */
@@ -72,9 +72,7 @@ export function FileCard({
         aria-label={labels.remove}
         onClick={onRemove}
       >
-        <svg viewBox="0 0 16 16" width="14" height="14" aria-hidden>
-          <path d="M3 3L13 13M13 3L3 13" stroke="currentColor" strokeWidth="2" strokeLinecap="round" />
-        </svg>
+        <IconCloseFill14 size={12} />
       </button>
       {state === 'uploading' && (
         <span className={css.progressTrack} aria-hidden>
diff --git a/packages/client/ui-attachment/src/client/ComposerAttachments.module.css b/packages/client/ui-attachment/src/client/ComposerAttachments.module.css
index b4a8eba014..1c9c72aa2d 100644
--- a/packages/client/ui-attachment/src/client/ComposerAttachments.module.css
+++ b/packages/client/ui-attachment/src/client/ComposerAttachments.module.css
@@ -1,6 +1,9 @@
 .rail {
   min-width: 0;
-  padding: 4px 12px 0;
+  padding: 2px 10px 0;
+  /* The card's flex gap (12px) separates every row pair; the thumbnails sit
+     closer to the draft text than the other rows, so pull back 6 here. */
+  margin-bottom: -6px;
 }
 
 .imageItem {
diff --git a/packages/client/ui-attachment/tests/message-image.client.spec.tsx b/packages/client/ui-attachment/tests/message-image.client.spec.tsx
index 595f20cb1c..7da3a878e9 100644
--- a/packages/client/ui-attachment/tests/message-image.client.spec.tsx
+++ b/packages/client/ui-attachment/tests/message-image.client.spec.tsx
@@ -1,5 +1,6 @@
 // @vitest-environment jsdom
 
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render, waitFor } from '@testing-library/react'
 import { AttachmentId } from '@deepseek-ai/dsh-attachment'
@@ -9,6 +10,9 @@ import { ImageGallery, MessageImage } from '../src/MessageImage.tsx'
 import type { MessageImageLabels } from '../src/MessageImage.tsx'
 import { MessageImages } from '../src/client/MessageImages.tsx'
 
+// Every session-scope fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 afterEach(cleanup)
 
 const labels: MessageImageLabels = {
@@ -268,6 +272,7 @@ describe('ImageGallery', () => {
       sessionId: 'message-images-test' as MessageImagesProps['sessionId'],
       useSession,
       useSessions,
+      useResource,
       useSessionPendingInteraction,
       useWorkspaces,
       useProjection: () => undefined,
diff --git a/packages/client/ui-chat/README.i18n.yaml b/packages/client/ui-chat/README.i18n.yaml
index 746b9fc2a6..a7b4221628 100644
--- a/packages/client/ui-chat/README.i18n.yaml
+++ b/packages/client/ui-chat/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-chat/README.md
-README.md: fa9653f7acab47f352e59971b333c6e691f44191
-README.zh.md: f8dc1968fffc57336d6aece8fe07113d5b99893b
+README.md: 5dd3a1c2a52789522629a822c8d522365fe93054
+README.zh.md: 07e8c2a9d41fa3a5d4f1a40e4570b9864822547f
diff --git a/packages/client/ui-chat/README.md b/packages/client/ui-chat/README.md
index fa9653f7ac..5dd3a1c2a5 100644
--- a/packages/client/ui-chat/README.md
+++ b/packages/client/ui-chat/README.md
@@ -1,5 +1,5 @@
 ---
-description: "Browser Chat target that renders Session conversation nodes, details, historical images, actions, localization, and scroll state."
+description: "Browser Chat target that renders Session conversation nodes, historical images, actions, localization, and scroll state."
 kind: "package-reference"
 ---
 # @deepseek-ai/dsh-client-ui-chat
@@ -8,7 +8,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-The browser Chat target for Conversation assembly. It registers Chat event definitions and snapshot construction, supplies `useChat`, renders transcript nodes and details, and owns Chat-specific stores, actions, localization, and scroll restoration; historical image URLs resolve through the Conversation-owned per-session cache (`ctx.uiConversation.imageUrl`). Its Assistant and Turn Tail definitions fold packed historical Assistant runs without expanding their members. Steering classification retains only next-step Inbox IDs through persistent splice state; next-turn splices create no Chat Context. Local submission echoes (`SessionSnapshot.pendingSubmissions`) retain the surface selected when the submit begins: transcript echoes render at the flow tail, steering echoes render with the pending-steering marker, and queued echoes stay out of Chat. Each echo is hidden per render once a user/steering node or queue occurrence carries its prompt `rpcId`, so the handoff is atomic.
+The browser Chat target for Conversation assembly. It registers Chat event definitions and snapshot construction, supplies `useChat`, renders transcript nodes, and owns Chat-specific stores, actions, localization, and scroll restoration; historical image URLs resolve through the Conversation-owned per-session cache (`ctx.uiConversation.imageUrl`). Its Assistant and Turn Tail definitions fold packed historical Assistant runs without expanding their members. Steering classification retains only next-step Inbox IDs through persistent splice state; next-turn splices create no Chat Context. Local submission echoes (`SessionSnapshot.pendingSubmissions`) retain the surface selected when the submit begins: transcript echoes render at the flow tail, steering echoes render with the pending-steering marker, and queued echoes stay out of Chat. Each echo is hidden per render once a user/steering node or queue occurrence carries its prompt `rpcId`, so the handoff is atomic.
 
 ## Table of Contents
 
diff --git a/packages/client/ui-chat/README.zh.md b/packages/client/ui-chat/README.zh.md
index f8dc1968ff..07e8c2a9d4 100644
--- a/packages/client/ui-chat/README.zh.md
+++ b/packages/client/ui-chat/README.zh.md
@@ -1,5 +1,5 @@
 ---
-description: "渲染 Session 对话节点、详情、历史图片、操作、本地化和滚动状态的浏览器 Chat target。"
+description: "渲染 Session 对话节点、历史图片、操作、本地化和滚动状态的浏览器 Chat target。"
 kind: "package-reference"
 ---
 # @deepseek-ai/dsh-client-ui-chat
@@ -8,7 +8,7 @@ kind: "package-reference"
 
 ## 概述
 
-Conversation 组装的浏览器 Chat target。本包注册 Chat event definition 与 snapshot 构造、提供 `useChat`、渲染 transcript node 和详情，并拥有 Chat 专属 store、action、本地化与滚动位置恢复；历史图片 URL 通过 Conversation 持有的按会话缓存（`ctx.uiConversation.imageUrl`）解析。其中 Assistant 与 Turn Tail definition 会直接 fold packed Assistant 历史 run，不展开其成员。steering 分类通过持久 splice state 只保留 next-step Inbox ID；next-turn splice 不创建 Chat Context。本地提交回显（`SessionSnapshot.pendingSubmissions`）保留提交开始时选定的区域：transcript 回显位于消息流末尾，steering 回显带 pending-steering 标记，queued 回显不进入 Chat。一旦 user/steering 节点或 queue occurrence 携带回显的 prompt `rpcId`，该回显即在同一渲染中隐藏，因此交接是原子的。
+Conversation 组装的浏览器 Chat target。本包注册 Chat event definition 与 snapshot 构造、提供 `useChat`、渲染 transcript node，并拥有 Chat 专属 store、action、本地化与滚动位置恢复；历史图片 URL 通过 Conversation 持有的按会话缓存（`ctx.uiConversation.imageUrl`）解析。其中 Assistant 与 Turn Tail definition 会直接 fold packed Assistant 历史 run，不展开其成员。steering 分类通过持久 splice state 只保留 next-step Inbox ID；next-turn splice 不创建 Chat Context。本地提交回显（`SessionSnapshot.pendingSubmissions`）保留提交开始时选定的区域：transcript 回显位于消息流末尾，steering 回显带 pending-steering 标记，queued 回显不进入 Chat。一旦 user/steering 节点或 queue occurrence 携带回显的 prompt `rpcId`，该回显即在同一渲染中隐藏，因此交接是原子的。
 
 ## 目录
 
diff --git a/packages/client/ui-chat/package.json b/packages/client/ui-chat/package.json
index 81e7e8f94b..0d8375a8a6 100644
--- a/packages/client/ui-chat/package.json
+++ b/packages/client/ui-chat/package.json
@@ -35,6 +35,7 @@
         "@deepseek-ai/dsh-client-ui-layout",
         "@deepseek-ai/dsh-client-ui-renderer",
         "@deepseek-ai/dsh-client-ui-session",
+        "@deepseek-ai/dsh-client-ui-sidebar-right",
         "@deepseek-ai/dsh-client-ui-settings",
         "@deepseek-ai/dsh-client-ui-workspace"
       ],
@@ -55,6 +56,7 @@
     "@deepseek-ai/dsh-api-remotes": "workspace:^",
     "@deepseek-ai/dsh-api-session-controller": "workspace:^",
     "@deepseek-ai/dsh-api-workspace-controller": "workspace:^",
+    "@deepseek-ai/dsh-api-workspace-files": "workspace:^",
     "@deepseek-ai/dsh-attachment": "workspace:^",
     "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-store": "workspace:^",
@@ -65,6 +67,8 @@
     "@deepseek-ai/dsh-client-ui-renderer": "workspace:^",
     "@deepseek-ai/dsh-client-ui-session": "workspace:^",
     "@deepseek-ai/dsh-client-ui-settings": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-sidebar-textpreview": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-client-ui-workspace": "workspace:^",
     "@deepseek-ai/dsh-commands": "workspace:^",
@@ -74,14 +78,14 @@
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-stats": "workspace:^",
     "@deepseek-ai/dsh-session-turn-outline": "workspace:^",
+    "@deepseek-ai/dsh-settings": "workspace:^",
     "@deepseek-ai/dsh-token-meter": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/dsh-util-workspace-path": "workspace:^",
     "@types/react": "~18.3.1",
     "@types/react-dom": "~18.3.0",
     "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "@deepseek-ai/dsh-settings": "workspace:^"
+    "react-dom": "^18.2.0"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "workspace:^"
diff --git a/packages/client/ui-chat/src/client/apply.ts b/packages/client/ui-chat/src/client/apply.ts
index 0c7d87f344..2d8de50561 100644
--- a/packages/client/ui-chat/src/client/apply.ts
+++ b/packages/client/ui-chat/src/client/apply.ts
@@ -3,9 +3,12 @@ import type { Context } from '@deepseek-ai/cordis'
 import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
 import type {} from '@deepseek-ai/dsh-api-remotes/client'
 import type { SessionBinding } from '@deepseek-ai/dsh-api-session-controller/client'
-import type { BoundActions, ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
-import { resolveWorkspacePath } from '@deepseek-ai/dsh-util-workspace-path'
+import type {} from '@deepseek-ai/dsh-client-ui-sidebar-right/client'
+// The `file` entry of `SidebarRightResourceParamsMap`, which types `{ params: { line } }` below.
+import type {} from '@deepseek-ai/dsh-client-ui-sidebar-textpreview/client'
+import { fileAddressFor } from '@deepseek-ai/dsh-util-workspace-path'
 // Type-only service and declaration merges used by the apply world.
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
@@ -15,7 +18,7 @@ import type {} from '@deepseek-ai/dsh-client-ui-session/client'
 import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
 import type {} from '@deepseek-ai/dsh-client-ui-workspace/client'
 import type {
-  ChatNodeTurnDataInjected, ChatScrollPosition, ChatViewInjected, DetailsInjected,
+  ChatNodeTurnDataInjected, ChatScrollPosition, ChatViewInjected,
   TurnTailOwnerProps,
 } from './contract/slots.ts'
 import type { ChatSnapshot } from './contract/snapshot.ts'
@@ -23,9 +26,8 @@ import { EMPTY_CHAT_SNAPSHOT } from './contract/snapshot.ts'
 import { ApprovalCommand } from './chat/ApprovalCommand.tsx'
 import { ChatView } from './chat/ChatView.tsx'
 import { registerChatNodeRenderers } from './chat/register-node-renderers.ts'
-import { StatsLine } from './chat/StatsLine.tsx'
+import { StatsPills } from './chat/StatsPills.tsx'
 import { registerConversationNodes } from './conversation-nodes/register.ts'
-import { DetailsPanel } from './details/DetailsPanel.tsx'
 import { en, NS, zh } from './locale.ts'
 import { TranscriptViewRow, type TranscriptViewRowInjected } from './settings/TranscriptViewRow.tsx'
 import { createChatStore } from './stores.ts'
@@ -43,8 +45,8 @@ const CHAT_NODE_INJECT: ChatNodeTurnDataInjected = {
 
 /** Services required by the Chat target and its presentation registrations. */
 export const inject = [
-  'slots', 'sessions', 'uiSession', 'uiConversation', 'layout', 'locale',
-  'settingsScope', 'remote', 'remote.session',
+  'slots', 'sessions', 'uiSession', 'uiConversation', 'locale',
+  'settingsScope', 'remote', 'remote.session', 'sidebarRight',
 ]
 
 /**
@@ -103,7 +105,7 @@ export function apply(ctx: Context): void {
         'conversation.message.images': { kind: 'single', scope: 'session' },
       },
       store: chatStore,
-      inject: (sessionId: SessionId, actions: BoundActions<typeof chatStore>): ChatViewInjected => {
+      inject: (sessionId: SessionId): ChatViewInjected => {
         const binding = ctx.sessions.binding(sessionId)
         if (binding === undefined) throw new Error(`ui-chat: unknown session "${sessionId}"`)
         const session = binding.session
@@ -114,17 +116,25 @@ export function apply(ctx: Context): void {
             chatNode: key => chat.getSnapshot().nodes.source(key),
             chatNodeProcess: key => chat.getSnapshot().nodes.processSource(key),
           },
-          openDetails: (target) => {
-            actions.select(target)
-            ctx.layout.openDetails()
-          },
           fileMentions: (owner: TurnTailOwnerProps) => ctx.get('chatFileMentions')?.forClosing(owner),
-          openFile: async (path) => {
+          // Files open in the right Sidebar, not in a desktop application: the
+          // content stays in the product, beside the conversation that produced
+          // it. A relative path, or an absolute one inside the session's
+          // workspace, is addressed under this session's scope,
+          // `dsh-resource://file/session/<id>/<relative path>`; an absolute path
+          // elsewhere is addressed as `dsh-resource://file/absolute/<path>` and
+          // read through the session on screen. Which tab type claims the
+          // address is the Sidebar's decision, not this call site's.
+          // A line travels as a navigation parameter, not as part of the
+          // address: the file is one piece of content whether it is opened at
+          // its top or at line 400, so the same tab is revealed and told where
+          // to land.
+          openFile: async (path, options) => {
             const cwd = ctx.sessions.list.getSnapshot().byId[sessionId]?.cwd
-            const result = await ctx.remote.session.openWorkspacePath({
-              path: resolveWorkspacePath(cwd, path),
-            })
-            if (!result.ok) throw new Error(`path open failed: ${result.error.message}`)
+            const url = fileAddressFor(sessionId, cwd, path)
+            if (options?.line === undefined) ctx.sidebarRight.openResource(url)
+            else ctx.sidebarRight.openResource(url, { params: { line: options.line } })
+            await Promise.resolve()
           },
           loadOlder: () => { void session.loadOlder() },
           loadThrough: seq => session.loadThrough(seq),
@@ -155,16 +165,9 @@ export function apply(ctx: Context): void {
   ctx.slots.inject('conversation.composer.dock', () =>
     ctx.slots.register({
       name: 'conversation.composer.dock', id: 'stats', order: 0, locale: NS,
-    }, StatsLine))
+    }, StatsPills))
 
   ctx.slots.inject('conversation.approval.detail', () =>
     ctx.slots.register({ name: 'conversation.approval.detail' }, ApprovalCommand))
 
-  ctx.slots.inject('details', () => ctx.slots.register({
-    name: 'details',
-    locale: NS,
-    children: { 'conversation.details.tool': { kind: 'single', scope: 'session' } },
-    store: chatStore,
-    inject: (): DetailsInjected => ({ closeDetails: () => { ctx.layout.closeDetails() } }),
-  }, DetailsPanel))
 }
diff --git a/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx b/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx
index e342836fe5..b1d8d9661e 100644
--- a/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx
+++ b/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx
@@ -37,7 +37,7 @@ function turnOf(node: ChatNode | undefined): number | undefined {
 /** Subscribe, apply Turn-process visibility, and dispatch one stable Context key. */
 export const ChatNodeSeat = memo(function ChatNodeSeat({
   nodeKey, useChatNode, useChatNodeProcess, historyIncomplete, compactTranscript,
-  selectedCallId, cwd, openFile, inspectCall, forkAt,
+  cwd, openFile, inspectCall, forkAt,
   loadImage, renderMessageImages, fileMentions, useStore, actions, renderSlot, t,
 }: ChatNodeSeatProps) {
   const node = useChatNode(nodeKey)
@@ -103,7 +103,6 @@ export const ChatNodeSeat = memo(function ChatNodeSeat({
   const owner = useMemo<ChatNodeOwnerProps | null>(() => node === undefined
     ? null
     : {
-      selectedCallId,
       cwd,
       openFile,
       inspectCall,
@@ -113,7 +112,7 @@ export const ChatNodeSeat = memo(function ChatNodeSeat({
       fileMentions,
       turnProcess,
     }, [
-    node, selectedCallId, cwd, openFile, inspectCall, forkAt,
+    node, cwd, openFile, inspectCall, forkAt,
     loadImage, renderMessageImages, fileMentions, turnProcess,
   ])
   if (routedNode === undefined || owner === null) return null
diff --git a/packages/client/ui-chat/src/client/chat/ChatView.tsx b/packages/client/ui-chat/src/client/chat/ChatView.tsx
index 21e1f78a29..8ff8eca3e0 100644
--- a/packages/client/ui-chat/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-chat/src/client/chat/ChatView.tsx
@@ -7,7 +7,7 @@ import type {
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import { Button, IconChevronDownOutline14, Modal } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { ChatViewSlotProps } from '../contract/slots.ts'
+import type { ChatViewSlotProps, OpenFileOptions } from '../contract/slots.ts'
 import type { ChatSnapshot } from '../contract/snapshot.ts'
 import { PendingSteeringBubble, PendingSubmissionBubble } from './MessageItem.tsx'
 import { ChatNodeSeat } from './ChatNodeSeat.tsx'
@@ -129,11 +129,6 @@ function openFailureMessage(error: unknown, fallback: string): string {
   return message === '' ? fallback : message
 }
 
-/** ProducedFiles opens the session workspace as `.`. */
-function isFolderOpenPath(path: string): boolean {
-  return path === '.'
-}
-
 /**
  * Prompt-RPC identities already rendered by durable material: user/steering
  * node sources plus queue occurrences. A submission echo whose identity
@@ -246,7 +241,6 @@ export function ChatView({
   const openError = useSession(s => s.openError)
   const hasMore = useSession(s => s.hasMore)
   const loadingOlder = useSession(s => s.loadingOlder)
-  const selectedCallId = useStore(s => s.selection?.callId)
   const compactTranscript = useTranscriptView(mode => mode === 'compact')
   const inspectCall = useCallback((callId: string) => {
     openView('trajectory', callId)
@@ -257,10 +251,10 @@ export function ChatView({
   // gesture; otherwise a cancelled in-flight refusal reopens the dialog.
   const fileOpenRequest = useRef(0)
 
-  const requestOpenFile = useCallback((path: string) => {
+  const requestOpenFile = useCallback((path: string, options?: OpenFileOptions) => {
     const id = ++fileOpenRequest.current
     setFileOpenBusy(true)
-    void openFile(path).then(
+    void (options === undefined ? openFile(path) : openFile(path, options)).then(
       () => {
         if (id !== fileOpenRequest.current) return
         setFileOpenError(null)
@@ -272,7 +266,7 @@ export function ChatView({
           path,
           message: openFailureMessage(
             error,
-            t(isFolderOpenPath(path) ? 'fileOpen.folderUnknown' : 'fileOpen.unknown'),
+            t('fileOpen.unknown'),
           ),
         })
         setFileOpenBusy(false)
@@ -795,7 +789,6 @@ export function ChatView({
             compactTranscript={compactTranscript}
             useStore={useStore}
             actions={actions}
-            selectedCallId={selectedCallId}
             cwd={cwd}
             openFile={requestOpenFile}
             inspectCall={inspectCall}
@@ -848,7 +841,6 @@ export function ChatView({
       </div>
       {fileOpenError !== null && (
         <FileOpenErrorDialog
-          path={fileOpenError.path}
           message={fileOpenError.message}
           busy={fileOpenBusy}
           onClose={closeFileOpenError}
@@ -862,9 +854,8 @@ export function ChatView({
 
 /** In-page Host open-path refusal: the wire reason plus a retry of the same path. */
 function FileOpenErrorDialog({
-  path, message, busy, onClose, onRetry, t,
+  message, busy, onClose, onRetry, t,
 }: {
-  path: string
   message: string
   busy: boolean
   onClose: () => void
@@ -876,7 +867,7 @@ function FileOpenErrorDialog({
       open
       onClose={onClose}
       closeLabel={t('close')}
-      title={t(isFolderOpenPath(path) ? 'fileOpen.folderTitle' : 'fileOpen.title')}
+      title={t('fileOpen.title')}
       description={message}
       footer={(
         <>
diff --git a/packages/client/ui-chat/src/client/chat/ReasoningRow.tsx b/packages/client/ui-chat/src/client/chat/ReasoningRow.tsx
index 81b10a7c49..bc7859b364 100644
--- a/packages/client/ui-chat/src/client/chat/ReasoningRow.tsx
+++ b/packages/client/ui-chat/src/client/chat/ReasoningRow.tsx
@@ -17,7 +17,9 @@ function latestLine(text: string): string {
 }
 
 /**
- * Render one assistant reasoning block as the Think disclosure row.
+ * Render one assistant reasoning block as the Think disclosure row. The
+ * collapsed summary omits double-asterisk markers; expanded content preserves
+ * the complete text.
  * @param props.text - complete or streaming reasoning text.
  * @param props.running - whether this block is the streaming tail.
  * @param props.t - conversation locale seat for the running status.
@@ -25,7 +27,7 @@ function latestLine(text: string): string {
  */
 export function ReasoningRow({ text, running, t }: { text: string; running: boolean; t: ChatViewSlotProps['t'] }) {
   const [expanded, setExpanded] = useState(false)
-  const summary = running ? latestLine(text) : firstLine(text)
+  const summary = (running ? latestLine(text) : firstLine(text)).replaceAll('**', '')
 
   return (
     <div
diff --git a/packages/client/ui-chat/src/client/chat/StatsLine.module.css b/packages/client/ui-chat/src/client/chat/StatsLine.module.css
deleted file mode 100644
index 29c0bc3aab..0000000000
--- a/packages/client/ui-chat/src/client/chat/StatsLine.module.css
+++ /dev/null
@@ -1,26 +0,0 @@
-/* Session stats row: 13/20 tertiary text (the secondary content tier) under
-   the flow, aligned to the shared message column axis
-   (--dsh-chat-content-width). */
-
-.root {
-  /* Block, not flex: text-overflow only elides a block's inline content, so
-     an overlong line ends in … instead of a mid-glyph clip. */
-  display: block;
-  text-align: center;
-  max-width: var(--dsh-chat-content-width);
-  width: 100%;
-  margin: 0 auto;
-  box-sizing: border-box;
-  padding: 4px calc(var(--dsh-composer-side-clearance) + 16px) 0px;
-  font-size: var(--dsh-content-font-size-secondary, 13px);
-  line-height: calc(20px + var(--dsh-content-font-delta-secondary, 0px));
-  color: var(--dsw-alias-label-tertiary);
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
-}
-
-.sep {
-  color: var(--dsw-alias-separator-primary);
-  margin: 0 10px; /* carries the former flex gap */
-}
diff --git a/packages/client/ui-chat/src/client/chat/StatsLine.tsx b/packages/client/ui-chat/src/client/chat/StatsLine.tsx
deleted file mode 100644
index 170ffec956..0000000000
--- a/packages/client/ui-chat/src/client/chat/StatsLine.tsx
+++ /dev/null
@@ -1,209 +0,0 @@
-// Settled-node identity prevents stream-delta updates from rerendering this row.
-// Mounted on 'conversation.composer.dock' so it sticks with the composer in the
-// active conversation scrollport (see ConversationRoot data-conversation-scroll).
-
-import { Fragment, memo, useCallback, useLayoutEffect, useMemo, useRef, useState } from 'react'
-import { Tooltip } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { UseProjection } from '@deepseek-ai/dsh-api-session-controller/client'
-import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
-// Type-only: merges the sessionStats key into SessionProjectionMap for useProjection.
-import type {} from '@deepseek-ai/dsh-session-stats/client'
-import type { TokenUsageProjection } from '@deepseek-ai/dsh-token-meter/client'
-import type { ChatViewSlotProps } from '../contract/slots.ts'
-import type { ChatSnapshot } from '../contract/snapshot.ts'
-import { formatTokensPerSecond } from './message-chrome.ts'
-import { assistantStepReading } from '../contract/turn-metrics.ts'
-import { formatCacheHitPercent, formatTokens } from './token-format.ts'
-import css from './StatsLine.module.css'
-
-interface WindowStats {
-  turns: number
-  steps: number
-  /** Summed request wall time (step/start → assistant/message); 0 when no node carries timing. */
-  llmMs: number
-  /** Summed tool wall time (tool/call → tool/result); 0 when no pair is in-window. */
-  toolMs: number
-  /** Summed first-token latency over `ttftSteps`; 0 when no step records it. */
-  ttftMs: number
-  /** Steps carrying a recorded TTFT. */
-  ttftSteps: number
-  /** Summed decode wall time over steps that also report output tokens. */
-  decodeMs: number
-  /** Summed output tokens over the same decode-timed steps. */
-  decodeTokens: number
-}
-
-/**
- * Fold assistant and tool-result nodes into window-scoped display totals —
- * the FALLBACK for assemblies without the `sessionStats` projection.
- *
- * Every displayed figure rides that durable whole-log projection (and token
- * accounting rides `tokenUsage`) because the window is paged and compaction
- * rewrites it; this fold answers "what is on screen" only when no projection
- * value is served. Its field names deliberately mirror the projection's so
- * the two swap wholesale.
- * @param nodes - snapshot nodes.
- * @returns fallback counts and summed wall times.
- */
-export function deriveStats(nodes: ChatSnapshot['legacy']['nodes']): WindowStats {
-  const turns = new Set<number>()
-  let steps = 0
-  let llmMs = 0
-  let toolMs = 0
-  let ttftMs = 0
-  let ttftSteps = 0
-  let decodeMs = 0
-  let decodeTokens = 0
-  for (const node of nodes) {
-    if (node.kind === 'tool-result') {
-      if (node.callTime !== null) toolMs += Math.max(0, node.time - node.callTime)
-      continue
-    }
-    if (node.kind !== 'assistant') continue
-    turns.add(node.turn)
-    steps += 1
-    if (node.timing !== undefined && node.timing.stepStartTime !== null) {
-      llmMs += Math.max(0, node.timing.completedTime - node.timing.stepStartTime)
-    }
-    const reading = assistantStepReading(node)
-    if (reading.ttftMs !== null) {
-      ttftMs += reading.ttftMs
-      ttftSteps += 1
-    }
-    if (reading.decodeMs !== null && reading.outputTokens !== null) {
-      decodeMs += reading.decodeMs
-      decodeTokens += reading.outputTokens
-    }
-  }
-  return { turns: turns.size, steps, llmMs, toolMs, ttftMs, ttftSteps, decodeMs, decodeTokens }
-}
-
-/**
- * Compact duration: 45.2s under a minute, 2m42s from there on.
- * @param ms - duration in milliseconds.
- * @returns display string.
- */
-export function formatDuration(ms: number, t: ChatViewSlotProps['t']): string {
-  const s = ms / 1_000
-  if (s < 60) return t('duration.compactSeconds', { seconds: Math.round(s * 10) / 10 })
-  const whole = Math.round(s)
-  return t('duration.compactMinutes', {
-    minutes: Math.floor(whole / 60),
-    seconds: whole % 60,
-  })
-}
-
-/**
- * Display-ready cache-hit share of prompt-side input over the whole durable log.
- * @param usage - the session's token-usage projection value.
- * @returns integer text when integer rounding stays below 100, otherwise the
- * minimum decimal precision that still rounds below 100; a full hit returns
- * 100, and no billed input returns null.
- */
-export function cacheHitPercent(usage: TokenUsageProjection): string | null {
-  const denominator = billedInputTokens(usage)
-  return formatCacheHitPercent(usage.cacheReadTokens, denominator)
-}
-
-/**
- * Sum the three disjoint prompt-side billing buckets.
- * @param usage - the session's token-usage projection value.
- * @returns billed input tokens.
- */
-export function billedInputTokens(usage: TokenUsageProjection): number {
-  return usage.uncachedInputTokens + usage.cacheReadTokens + usage.cacheWriteTokens
-}
-
-/** Props: the conversation-snapshot selector plus the projection read seat. */
-export interface StatsLineProps {
-  useChat: SnapshotSelectorHook<ChatSnapshot>
-  useProjection: UseProjection
-  /** The owning dock's locale seat. */
-  t: ChatViewSlotProps['t']
-}
-
-/** Render and measure one non-empty statistics line. */
-const StatsLineContent = memo(function StatsLineContent({
-  groups,
-  line,
-}: {
-  readonly groups: readonly string[]
-  readonly line: string
-}) {
-  const rootRef = useRef<HTMLDivElement | null>(null)
-  const [truncated, setTruncated] = useState(false)
-  const measure = useCallback(() => {
-    const el = rootRef.current
-    if (el === null) return
-    const next = el.scrollWidth > el.clientWidth
-    setTruncated(current => current === next ? current : next)
-  }, [])
-  useLayoutEffect(() => {
-    const el = rootRef.current
-    if (el === null || typeof ResizeObserver === 'undefined') return
-    const observer = new ResizeObserver(measure)
-    observer.observe(el)
-    return () => { observer.disconnect() }
-  }, [measure])
-  useLayoutEffect(measure, [line, measure])
-  return (
-    <Tooltip label={line} side="top" delayMs={500} disabled={!truncated}>
-      <div ref={rootRef} className={css.root}>
-        {groups.map((group, i) => (
-          <Fragment key={group}>
-            {i > 0 && <><span className={css.sep} aria-hidden>|</span>{' '}</>}
-            <span>{group}</span>
-          </Fragment>
-        ))}
-      </div>
-    </Tooltip>
-  )
-})
-
-export const StatsLine = memo(function StatsLine({ useChat, useProjection, t }: StatsLineProps) {
-  const settledNodes = useChat(s => s.legacy.nodes)
-  const usage = useProjection('tokenUsage')
-  // Every figure rides the durable sessionStats projection, so paging and
-  // compaction cannot change any of them; an assembly without the unit falls
-  // back to the window-scoped fold wholesale (same field names), paid only
-  // while no projection value is served.
-  const projected = useProjection('sessionStats')
-  const stats = useMemo(() => projected ?? deriveStats(settledNodes), [projected, settledNodes])
-  // Pipe-separated groups (figma stats strip); a group with no data drops out whole.
-  const groups: string[] = []
-  if (stats.steps > 0) {
-    groups.push(t('stats.counts', { turns: stats.turns, steps: stats.steps }))
-    const durations: string[] = []
-    if (stats.llmMs > 0) durations.push(t('stats.llm', { duration: formatDuration(stats.llmMs, t) }))
-    if (stats.toolMs > 0) durations.push(t('stats.toolCall', { duration: formatDuration(stats.toolMs, t) }))
-    if (durations.length > 0) groups.push(durations.join(' · '))
-    const speeds: string[] = []
-    if (stats.ttftSteps > 0) {
-      speeds.push(t('stats.ttftAverage', { duration: formatDuration(stats.ttftMs / stats.ttftSteps, t) }))
-    }
-    if (stats.decodeMs > 0) {
-      speeds.push(t('stats.tokensPerSecond', {
-        throughput: formatTokensPerSecond(stats.decodeTokens / (stats.decodeMs / 1_000)),
-      }))
-    }
-    if (speeds.length > 0) groups.push(speeds.join(' · '))
-  }
-  // Context occupancy deliberately lives on the composer's ContextMeter ring,
-  // not here — one home per fact.
-  // Billing rides the durable projection, so these survive paging and
-  // compaction. Gated on actual token activity: a session whose steps all
-  // settled without billing (e.g. every request failed) shows its counts
-  // without a zero-token group.
-  if (usage !== undefined
-    && (billedInputTokens(usage) > 0 || usage.outputTokens > 0)) {
-    const cacheHit = cacheHitPercent(usage)
-    if (cacheHit !== null) groups.push(t('stats.cacheHit', { percent: cacheHit }))
-    groups.push(t('stats.tokens', {
-      input: formatTokens(billedInputTokens(usage), t),
-      output: formatTokens(usage.outputTokens, t),
-    }))
-  }
-  const line = groups.join(' | ')
-  if (groups.length === 0) return null
-  return <StatsLineContent groups={groups} line={line} />
-})
diff --git a/packages/client/ui-chat/src/client/chat/StatsPills.module.css b/packages/client/ui-chat/src/client/chat/StatsPills.module.css
new file mode 100644
index 0000000000..22f39a1f26
--- /dev/null
+++ b/packages/client/ui-chat/src/client/chat/StatsPills.module.css
@@ -0,0 +1,68 @@
+/* Two icon pills side by side under the composer, 13/20 tertiary text tier
+   with a hover-pill affordance; each pill's click-open panel wears the shared
+   stat-dialog.module.css skin. */
+
+.root {
+  display: flex;
+  justify-content: center;
+  gap: 12px;
+  max-width: var(--dsh-chat-content-width);
+  width: 100%;
+  margin: 0 auto;
+  box-sizing: border-box;
+  padding: 4px calc(var(--dsh-composer-side-clearance) + 16px) 0px;
+  font-size: var(--dsh-content-font-size-secondary, 13px);
+  line-height: calc(20px + var(--dsh-content-font-delta-secondary, 0px));
+}
+
+/* Dialog anchor: shrink-wraps its pill so the panel clamp measures the pill. */
+.anchor {
+  display: inline-flex;
+  min-width: 0;
+}
+
+.pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  box-sizing: border-box;
+  max-width: 100%;
+  padding: 1px 8px;
+  border: none;
+  border-radius: 24px;
+  background: transparent;
+  color: var(--dsw-alias-label-tertiary);
+  font: inherit;
+  font-variant-numeric: tabular-nums;
+  line-height: inherit;
+  white-space: nowrap;
+}
+
+.pill svg {
+  width: 14px;
+  height: 14px;
+  flex: none;
+}
+
+/* Only the button form (a pill with dialog rows to open) invites interaction;
+   the static span form keeps the resting tertiary reading. */
+button.pill {
+  cursor: pointer;
+}
+
+button.pill:hover,
+button.pill[aria-expanded='true'] {
+  background: var(--dsw-alias-interactive-bg-hover);
+  color: var(--dsw-alias-label-secondary);
+}
+
+.label {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.sep {
+  color: var(--dsw-alias-separator-primary);
+  margin: 0 6px;
+}
diff --git a/packages/client/ui-chat/src/client/chat/StatsPills.tsx b/packages/client/ui-chat/src/client/chat/StatsPills.tsx
new file mode 100644
index 0000000000..091352dac1
--- /dev/null
+++ b/packages/client/ui-chat/src/client/chat/StatsPills.tsx
@@ -0,0 +1,353 @@
+// Session stats under the composer, split into two icon pills: a gauge pill
+// (turn/step counts + output speed) opening the time-and-speed dialog, and a
+// database pill (total tokens + cache hit) opening the token-usage dialog.
+// Settled-node identity prevents stream-delta updates from rerendering the row.
+// Mounted on 'conversation.composer.dock' so it sticks with the composer in the
+// active conversation scrollport (see ConversationRoot data-conversation-scroll).
+
+import { memo, useMemo, useState } from 'react'
+import { createPortal } from 'react-dom'
+import { IconDatabaseOutline16, IconGaugeOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { UseProjection } from '@deepseek-ai/dsh-api-session-controller/client'
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
+// Type-only: merges the sessionStats key into SessionProjectionMap for useProjection.
+import type {} from '@deepseek-ai/dsh-session-stats/client'
+import type { TokenUsageProjection } from '@deepseek-ai/dsh-token-meter/client'
+import type { ChatViewSlotProps } from '../contract/slots.ts'
+import type { ChatSnapshot } from '../contract/snapshot.ts'
+import { formatTokensPerSecond } from './message-chrome.ts'
+import { assistantStepReading } from '../contract/turn-metrics.ts'
+import { formatCacheHitPercent, formatExactTokens, formatTokens } from './token-format.ts'
+import { MEASURE_STYLE, useStatDialog } from './stat-dialog.ts'
+import css from './StatsPills.module.css'
+import dialogCss from './stat-dialog.module.css'
+
+interface WindowStats {
+  turns: number
+  steps: number
+  /** Summed request wall time (step/start → assistant/message); 0 when no node carries timing. */
+  llmMs: number
+  /** Summed tool wall time (tool/call → tool/result); 0 when no pair is in-window. */
+  toolMs: number
+  /** Summed first-token latency over `ttftSteps`; 0 when no step records it. */
+  ttftMs: number
+  /** Steps carrying a recorded TTFT. */
+  ttftSteps: number
+  /** Summed decode wall time over steps that also report output tokens. */
+  decodeMs: number
+  /** Summed output tokens over the same decode-timed steps. */
+  decodeTokens: number
+}
+
+/**
+ * Fold assistant and tool-result nodes into window-scoped display totals —
+ * the FALLBACK for assemblies without the `sessionStats` projection.
+ *
+ * Every displayed figure rides that durable whole-log projection (and token
+ * accounting rides `tokenUsage`) because the window is paged and compaction
+ * rewrites it; this fold answers "what is on screen" only when no projection
+ * value is served. Its field names deliberately mirror the projection's so
+ * the two swap wholesale.
+ * @param nodes - snapshot nodes.
+ * @returns fallback counts and summed wall times.
+ */
+export function deriveStats(nodes: ChatSnapshot['legacy']['nodes']): WindowStats {
+  const turns = new Set<number>()
+  let steps = 0
+  let llmMs = 0
+  let toolMs = 0
+  let ttftMs = 0
+  let ttftSteps = 0
+  let decodeMs = 0
+  let decodeTokens = 0
+  for (const node of nodes) {
+    if (node.kind === 'tool-result') {
+      if (node.callTime !== null) toolMs += Math.max(0, node.time - node.callTime)
+      continue
+    }
+    if (node.kind !== 'assistant') continue
+    turns.add(node.turn)
+    steps += 1
+    if (node.timing !== undefined && node.timing.stepStartTime !== null) {
+      llmMs += Math.max(0, node.timing.completedTime - node.timing.stepStartTime)
+    }
+    const reading = assistantStepReading(node)
+    if (reading.ttftMs !== null) {
+      ttftMs += reading.ttftMs
+      ttftSteps += 1
+    }
+    if (reading.decodeMs !== null && reading.outputTokens !== null) {
+      decodeMs += reading.decodeMs
+      decodeTokens += reading.outputTokens
+    }
+  }
+  return { turns: turns.size, steps, llmMs, toolMs, ttftMs, ttftSteps, decodeMs, decodeTokens }
+}
+
+/**
+ * Compact duration: 45.2s under a minute, 2m42s from there on.
+ * @param ms - duration in milliseconds.
+ * @returns display string.
+ */
+export function formatDuration(ms: number, t: ChatViewSlotProps['t']): string {
+  const s = ms / 1_000
+  if (s < 60) return t('duration.compactSeconds', { seconds: Math.round(s * 10) / 10 })
+  const whole = Math.round(s)
+  return t('duration.compactMinutes', {
+    minutes: Math.floor(whole / 60),
+    seconds: whole % 60,
+  })
+}
+
+/**
+ * Display-ready cache-hit share of prompt-side input over the whole durable log.
+ * @param usage - the session's token-usage projection value.
+ * @returns integer text when integer rounding stays below 100, otherwise the
+ * minimum decimal precision that still rounds below 100; a full hit returns
+ * 100, and no billed input returns null.
+ */
+export function cacheHitPercent(usage: TokenUsageProjection): string | null {
+  const denominator = billedInputTokens(usage)
+  return formatCacheHitPercent(usage.cacheReadTokens, denominator)
+}
+
+/**
+ * Sum the three disjoint prompt-side billing buckets.
+ * @param usage - the session's token-usage projection value.
+ * @returns billed input tokens.
+ */
+export function billedInputTokens(usage: TokenUsageProjection): number {
+  return usage.uncachedInputTokens + usage.cacheReadTokens + usage.cacheWriteTokens
+}
+
+/** Props: the conversation-snapshot selector plus the projection read seat. */
+export interface StatsPillsProps {
+  useChat: SnapshotSelectorHook<ChatSnapshot>
+  useProjection: UseProjection
+  /** The owning dock's locale seat. */
+  t: ChatViewSlotProps['t']
+}
+
+function exactCount(value: number, t: ChatViewSlotProps['t']): string {
+  return t('message.turnUsage.count', { count: formatExactTokens(value, t) })
+}
+
+/** External open state one pill's dialog reads and writes (the row's exclusive slot). */
+type PillDialog = Pick<ReturnType<typeof useStatDialog>, 'open' | 'setOpen'>
+
+function TimePill({ stats, t, dialog }: {
+  stats: WindowStats
+  t: ChatViewSlotProps['t']
+  dialog: PillDialog
+}) {
+  const { open, setOpen, rootRef, panelRef, pos } = useStatDialog(dialog)
+  const counts = t('stats.counts', { turns: stats.turns, steps: stats.steps })
+  const tps = stats.decodeMs > 0
+    ? t('message.tokensPerSecond', {
+      tps: formatTokensPerSecond(stats.decodeTokens / (stats.decodeMs / 1_000)),
+    })
+    : null
+  const label = (
+    <span className={css.label}>
+      {counts}
+      {tps !== null && (
+        <>
+          <span className={css.sep} aria-hidden>·</span>
+          {tps}
+        </>
+      )}
+    </span>
+  )
+  // A window without one timed figure has no dialog rows to show, so the pill
+  // stays a plain reading instead of a button opening an empty dialog.
+  if (stats.llmMs <= 0 && stats.toolMs <= 0 && stats.ttftSteps <= 0 && stats.decodeMs <= 0) {
+    return (
+      <span className={css.anchor}>
+        <span className={css.pill}>
+          <IconGaugeOutline16 />
+          {label}
+        </span>
+      </span>
+    )
+  }
+  return (
+    <span ref={rootRef} className={css.anchor}>
+      <button
+        type="button"
+        className={css.pill}
+        aria-haspopup="dialog"
+        aria-expanded={open}
+        aria-label={tps === null ? counts : `${counts} · ${tps}`}
+        onClick={() => { setOpen(!open) }}
+      >
+        <IconGaugeOutline16 />
+        {label}
+      </button>
+      {open && createPortal(
+        <div
+          ref={panelRef}
+          className={dialogCss.panel}
+          role="dialog"
+          aria-label={t('stats.dialog.title')}
+          style={pos ?? MEASURE_STYLE}
+        >
+          <div className={dialogCss.title}>
+            <span className={dialogCss.titleLabel}>
+              <IconGaugeOutline16 />
+              {t('stats.dialog.title')}
+            </span>
+          </div>
+          <div className={dialogCss.titleRule} aria-hidden />
+          <dl className={dialogCss.details} data-session-stats-details>
+            {stats.llmMs > 0 && (
+              <>
+                <dt>{t('stats.dialog.llmTime')}</dt>
+                <dd>{formatDuration(stats.llmMs, t)}</dd>
+              </>
+            )}
+            {stats.toolMs > 0 && (
+              <>
+                <dt>{t('stats.dialog.toolTime')}</dt>
+                <dd>{formatDuration(stats.toolMs, t)}</dd>
+              </>
+            )}
+            {stats.ttftSteps > 0 && (
+              <>
+                <dt>{t('stats.dialog.ttft')}</dt>
+                <dd>{formatDuration(stats.ttftMs / stats.ttftSteps, t)}</dd>
+              </>
+            )}
+            {stats.decodeMs > 0 && (
+              <>
+                <dt>{t('stats.dialog.speed')}</dt>
+                <dd>{t('message.tokensPerSecond', {
+                  tps: formatTokensPerSecond(stats.decodeTokens / (stats.decodeMs / 1_000)),
+                })}</dd>
+              </>
+            )}
+          </dl>
+        </div>,
+        document.body,
+      )}
+    </span>
+  )
+}
+
+function UsagePill({ usage, t, dialog }: {
+  usage: TokenUsageProjection
+  t: ChatViewSlotProps['t']
+  dialog: PillDialog
+}) {
+  const { open, setOpen, rootRef, panelRef, pos } = useStatDialog(dialog)
+  // Same aggregate as the Turn pill's totalTokens: every prompt-side billing bucket plus output.
+  const total = billedInputTokens(usage) + usage.outputTokens
+  const totalText = t('message.turnUsage.count', { count: formatTokens(total, t) })
+  const cacheHit = cacheHitPercent(usage)
+  const cacheHitText = cacheHit !== null ? t('stats.cacheHit', { percent: cacheHit }) : null
+  return (
+    <span ref={rootRef} className={css.anchor}>
+      <button
+        type="button"
+        className={css.pill}
+        aria-haspopup="dialog"
+        aria-expanded={open}
+        aria-label={cacheHitText === null ? totalText : `${totalText} · ${cacheHitText}`}
+        onClick={() => { setOpen(!open) }}
+      >
+        <IconDatabaseOutline16 />
+        <span className={css.label}>
+          {totalText}
+          {cacheHitText !== null && (
+            <>
+              <span className={css.sep} aria-hidden>·</span>
+              {cacheHitText}
+            </>
+          )}
+        </span>
+      </button>
+      {open && createPortal(
+        <div
+          ref={panelRef}
+          className={dialogCss.panel}
+          role="dialog"
+          aria-label={t('stats.dialog.usageTitle')}
+          style={pos ?? MEASURE_STYLE}
+        >
+          <div className={dialogCss.title}>
+            <span className={dialogCss.titleLabel}>
+              <IconDatabaseOutline16 />
+              {t('stats.dialog.usageTitle')}
+            </span>
+            <span className={dialogCss.titleValue}>{exactCount(total, t)}</span>
+          </div>
+          <div className={dialogCss.titleRule} aria-hidden />
+          {/* jscpd:ignore-start -- the session-total bucket rows deliberately mirror
+              TurnUsagePanel's per-turn dl: same skin, different data contract (all
+              buckets always present here; per-turn fields are optional). */}
+          <dl className={dialogCss.details} data-session-stats-usage>
+            {cacheHit !== null && (
+              <>
+                <dt>{t('message.turnUsage.cacheHit')}</dt>
+                <dd>{`${cacheHit}%`}</dd>
+              </>
+            )}
+            <dt>{t('message.turnUsage.input')}</dt>
+            <dd>{exactCount(usage.uncachedInputTokens, t)}</dd>
+            <dt>{t('message.turnUsage.cacheRead')}</dt>
+            <dd>{exactCount(usage.cacheReadTokens, t)}</dd>
+            <dt>{t('message.turnUsage.cacheWrite')}</dt>
+            <dd>{exactCount(usage.cacheWriteTokens, t)}</dd>
+            <dt>{t('message.turnUsage.output')}</dt>
+            <dd>{exactCount(usage.outputTokens, t)}</dd>
+          </dl>
+          {/* jscpd:ignore-end */}
+        </div>,
+        document.body,
+      )}
+    </span>
+  )
+}
+
+export const StatsPills = memo(function StatsPills({ useChat, useProjection, t }: StatsPillsProps) {
+  const settledNodes = useChat(s => s.legacy.nodes)
+  const usage = useProjection('tokenUsage')
+  // One exclusive slot for both dialogs: opening either pill closes the other.
+  const [openPill, setOpenPill] = useState<'time' | 'usage' | null>(null)
+  // Every figure rides the durable sessionStats projection, so paging and
+  // compaction cannot change any of them; an assembly without the unit falls
+  // back to the window-scoped fold wholesale (same field names), paid only
+  // while no projection value is served.
+  const projected = useProjection('sessionStats')
+  const stats = useMemo(() => projected ?? deriveStats(settledNodes), [projected, settledNodes])
+  // Gated on actual token activity: a session whose steps all settled without
+  // billing (e.g. every request failed) shows its counts without a usage pill.
+  const hasTokens = usage !== undefined
+    && (billedInputTokens(usage) > 0 || usage.outputTokens > 0)
+  if (stats.steps === 0 && !hasTokens) return null
+  // data-composer-stats: InputBar's `.root:has([data-composer-stats])` rule
+  // tightens the composer's bottom clearance only while this row renders.
+  return (
+    <div className={css.root} data-composer-stats>
+      {stats.steps > 0 && (
+        <TimePill
+          stats={stats}
+          t={t}
+          dialog={{
+            open: openPill === 'time',
+            setOpen: (open) => { setOpenPill(open ? 'time' : null) },
+          }}
+        />
+      )}
+      {hasTokens && (
+        <UsagePill
+          usage={usage}
+          t={t}
+          dialog={{
+            open: openPill === 'usage',
+            setOpen: (open) => { setOpenPill(open ? 'usage' : null) },
+          }}
+        />
+      )}
+    </div>
+  )
+})
diff --git a/packages/client/ui-chat/src/client/chat/TurnUsagePanel.module.css b/packages/client/ui-chat/src/client/chat/TurnUsagePanel.module.css
index 7cc7c639eb..52058f8be7 100644
--- a/packages/client/ui-chat/src/client/chat/TurnUsagePanel.module.css
+++ b/packages/client/ui-chat/src/client/chat/TurnUsagePanel.module.css
@@ -1,6 +1,5 @@
-/* Icon-row Turn-usage pill (data icon + turn total) plus its click-open
-   Turn-details dialog (menu surface: r12, elevation-prominent —
-   ContextMeter's panel skin). */
+/* Icon-row Turn-usage pill (data icon + turn total); its click-open dialog
+   wears the shared stat-dialog.module.css skin. */
 
 .root {
   display: inline-flex;
@@ -74,93 +73,3 @@
     margin-left: 0;
   }
 }
-
-/* Portal surface: fixed in the viewport, left/top supplied inline from the
-   anchored-position clamp so the panel keeps its 12px viewport margin instead
-   of hanging off the trigger and clipping at the window edge. Portaled panels
-   layer above modal overlays (z 1000). */
-.panel {
-  position: fixed;
-  z-index: 1100;
-  box-sizing: border-box;
-  /* Size to the widest row so provider/model stays on one line, within a cap.
-     Both bounds yield to a viewport narrower than themselves (12px margins),
-     so a fixed floor cannot push the panel past the placement clamp. */
-  width: max-content;
-  min-width: min(300px, calc(100vw - 24px));
-  max-width: min(440px, calc(100vw - 24px));
-  padding: 16px;
-  border: 0;
-  border-radius: 12px;
-  background: var(--dsw-specific-menu);
-  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
-  box-shadow: var(--dsw-elevation-prominent);
-  font-size: 12px;
-  line-height: 18px;
-  color: var(--dsw-alias-label-secondary);
-  cursor: default;
-}
-
-/* Dialog heading row: the section name left, the section's headline value
-   (the usage total) right, both at the primary weight. */
-.title {
-  display: flex;
-  justify-content: space-between;
-  gap: 16px;
-  margin-bottom: 8px;
-  color: var(--dsw-alias-label-primary);
-  font-weight: 500;
-}
-
-/* Rule under each section heading, above its rows. */
-.titleRule {
-  margin-bottom: 10px;
-  border-top: 0.5px solid var(--dsw-alias-border-l2);
-}
-
-.titleValue {
-  font-variant-numeric: tabular-nums;
-}
-
-/* Section-heading glyph seated left of the section name. */
-.titleLabel {
-  display: inline-flex;
-  align-items: center;
-  gap: 6px;
-  min-width: 0;
-}
-
-.titleLabel svg {
-  width: 14px;
-  height: 14px;
-  flex: none;
-}
-
-.details {
-  display: grid;
-  grid-template-columns: minmax(76px, auto) minmax(0, 1fr);
-  gap: 6px 16px;
-  margin: 0;
-  color: var(--dsw-alias-label-tertiary);
-}
-
-.details dt,
-.details dd {
-  min-width: 0;
-  margin: 0;
-}
-
-.details dd {
-  color: var(--dsw-alias-label-secondary);
-  font-variant-numeric: tabular-nums;
-  text-align: right;
-}
-
-.details .route {
-  overflow-wrap: anywhere;
-}
-
-.reasoning {
-  color: var(--dsw-alias-label-tertiary);
-  white-space: nowrap;
-}
diff --git a/packages/client/ui-chat/src/client/chat/TurnUsagePanel.tsx b/packages/client/ui-chat/src/client/chat/TurnUsagePanel.tsx
index b3cd2c12a7..0d64ff9e08 100644
--- a/packages/client/ui-chat/src/client/chat/TurnUsagePanel.tsx
+++ b/packages/client/ui-chat/src/client/chat/TurnUsagePanel.tsx
@@ -3,16 +3,15 @@
 // turn wall time click-opens the Turn-time dialog. Both sit right of the
 // branch action in the tail's IconActions row, ahead of the plain clock text.
 
-import { useEffect, useRef, useState, type CSSProperties, type MutableRefObject } from 'react'
 import { createPortal } from 'react-dom'
-import {
-  IconClockOutline16, IconDatabaseOutline16, useAnchoredPosition, useDismissOnOutsidePointer,
-} from '@deepseek-ai/dsh-client-ui-primitives'
+import { IconClockOutline16, IconDatabaseOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { TurnTokenUsage } from '../contract/chat-nodes.ts'
 import type { ChatViewSlotProps } from '../contract/slots.ts'
 import { formatLatencySeconds, formatRunDuration, formatTokensPerSecond } from './message-chrome.ts'
 import { formatCacheHitPercent, formatExactTokens, formatTokens } from './token-format.ts'
+import { MEASURE_STYLE, useStatDialog } from './stat-dialog.ts'
 import css from './TurnUsagePanel.module.css'
+import dialogCss from './stat-dialog.module.css'
 
 export interface TurnUsagePanelProps {
   usage: TurnTokenUsage
@@ -39,58 +38,6 @@ function formatExactCount(value: number, t: ChatViewSlotProps['t']): string {
   return t('message.turnUsage.count', { count: formatExactTokens(value, t) })
 }
 
-/** Viewport margin the placement clamp keeps (the Menu portal margin). */
-const PANEL_MARGIN = 12
-
-/** Distance between the trigger's top edge and the panel's bottom. */
-const PANEL_GAP = 8
-
-/**
- * Unplaced portal panel: hidden but laid out so the clamp measures real
- * dimensions (the `useAnchoredPosition` measure pass).
- */
-const MEASURE_STYLE: CSSProperties = { visibility: 'hidden', left: 0, top: 0 }
-
-interface StatDialogSeat {
-  open: boolean
-  setOpen: (open: boolean) => void
-  rootRef: MutableRefObject<HTMLSpanElement | null>
-  panelRef: MutableRefObject<HTMLDivElement | null>
-  pos: CSSProperties | null
-}
-
-/** One trigger-anchored dialog seat: open state, viewport-clamped placement, outside-close. */
-function useStatDialog(): StatDialogSeat {
-  const [open, setOpen] = useState(false)
-  const rootRef = useRef<HTMLSpanElement | null>(null)
-  const panelRef = useRef<HTMLDivElement | null>(null)
-
-  // Portal placement: the dialog is fixed above the trigger and clamped inside
-  // the viewport, so a trigger near the window edge cannot push it off-screen.
-  const pos = useAnchoredPosition({
-    open,
-    anchorRef: rootRef,
-    panelRef,
-    side: 'top',
-    gap: PANEL_GAP,
-    margin: PANEL_MARGIN,
-  })
-
-  // Outside pointerdown closes through the shared primitive; the portaled
-  // panel counts as inside. Escape close stays local, one listener while open.
-  useDismissOnOutsidePointer(rootRef, open, setOpen, panelRef)
-  useEffect(() => {
-    if (!open) return
-    const onKeyDown = (e: KeyboardEvent): void => {
-      if (e.key === 'Escape') setOpen(false)
-    }
-    document.addEventListener('keydown', onKeyDown)
-    return () => { document.removeEventListener('keydown', onKeyDown) }
-  }, [open])
-
-  return { open, setOpen, rootRef, panelRef, pos }
-}
-
 /**
  * Turn-usage IconActions pill with a click-open Turn-usage details dialog.
  * @param props - Turn usage buckets and locale seat.
@@ -120,24 +67,24 @@ export function TurnUsagePanel({ usage, t }: TurnUsagePanelProps) {
       {open && createPortal(
         <div
           ref={panelRef}
-          className={css.panel}
+          className={dialogCss.panel}
           role="dialog"
           aria-label={t('message.turnUsage.title')}
           style={pos ?? MEASURE_STYLE}
         >
-          <div className={css.title}>
-            <span className={css.titleLabel}>
+          <div className={dialogCss.title}>
+            <span className={dialogCss.titleLabel}>
               <IconDatabaseOutline16 />
               {t('message.turnUsage.title')}
             </span>
-            <span className={css.titleValue}>{formatExactCount(usage.totalTokens, t)}</span>
+            <span className={dialogCss.titleValue}>{formatExactCount(usage.totalTokens, t)}</span>
           </div>
-          <div className={css.titleRule} aria-hidden />
-          <dl className={css.details} data-turn-usage-details>
+          <div className={dialogCss.titleRule} aria-hidden />
+          <dl className={dialogCss.details} data-turn-usage-details>
             {routes !== '' && (
               <>
                 <dt>{t('message.turnUsage.model')}</dt>
-                <dd className={css.route}>{routes}</dd>
+                <dd className={dialogCss.route}>{routes}</dd>
               </>
             )}
             {cacheHit !== null && (
@@ -164,7 +111,7 @@ export function TurnUsagePanel({ usage, t }: TurnUsagePanelProps) {
             <dd>
               {formatExactCount(usage.outputTokens, t)}
               {usage.reasoningTokens !== undefined && (
-                <span className={css.reasoning}>
+                <span className={dialogCss.reasoning}>
                   {t('message.turnUsage.reasoning', { tokens: formatExactCount(usage.reasoningTokens, t) })}
                 </span>
               )}
@@ -199,19 +146,19 @@ export function TurnTimePanel({ runMs, tokensPerSecond, ttftMs, t }: TurnTimePan
       {open && createPortal(
         <div
           ref={panelRef}
-          className={css.panel}
+          className={dialogCss.panel}
           role="dialog"
           aria-label={t('message.turnTime.title')}
           style={pos ?? MEASURE_STYLE}
         >
-          <div className={css.title}>
-            <span className={css.titleLabel}>
+          <div className={dialogCss.title}>
+            <span className={dialogCss.titleLabel}>
               <IconClockOutline16 />
               {t('message.turnTime.title')}
             </span>
           </div>
-          <div className={css.titleRule} aria-hidden />
-          <dl className={css.details} data-turn-time-details>
+          <div className={dialogCss.titleRule} aria-hidden />
+          <dl className={dialogCss.details} data-turn-time-details>
             <dt>{t('message.turnTime.duration')}</dt>
             <dd>{formatRunDuration(runMs, t)}</dd>
             {tokensPerSecond !== undefined && (
diff --git a/packages/client/ui-chat/src/client/chat/stat-dialog.module.css b/packages/client/ui-chat/src/client/chat/stat-dialog.module.css
new file mode 100644
index 0000000000..cc30711a68
--- /dev/null
+++ b/packages/client/ui-chat/src/client/chat/stat-dialog.module.css
@@ -0,0 +1,94 @@
+/* Stat-dialog surface skin shared by the Turn-stat pills (TurnUsagePanel) and
+   the session stats pills (StatsPills): menu surface, r12, elevation-prominent
+   — ContextMeter's panel skin. Placement comes from useStatDialog
+   (stat-dialog.ts). */
+
+/* Portal surface: fixed in the viewport, left/top supplied inline from the
+   anchored-position clamp so the panel keeps its 12px viewport margin instead
+   of hanging off the trigger and clipping at the window edge. Portaled panels
+   layer above modal overlays (z 1000). */
+.panel {
+  position: fixed;
+  z-index: 1100;
+  box-sizing: border-box;
+  /* Size to the widest row so provider/model stays on one line, within a cap.
+     Both bounds yield to a viewport narrower than themselves (12px margins),
+     so a fixed floor cannot push the panel past the placement clamp. */
+  width: max-content;
+  min-width: min(300px, calc(100vw - 24px));
+  max-width: min(440px, calc(100vw - 24px));
+  padding: 16px;
+  border: 0;
+  border-radius: 12px;
+  background: var(--dsw-specific-menu);
+  --dsw-elevation-stroke-color: var(--dsw-alias-border-l1);
+  box-shadow: var(--dsw-elevation-prominent);
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-secondary);
+  cursor: default;
+}
+
+/* Dialog heading row: the section name left, the section's headline value
+   right, both at the primary weight. */
+.title {
+  display: flex;
+  justify-content: space-between;
+  gap: 16px;
+  margin-bottom: 8px;
+  color: var(--dsw-alias-label-primary);
+  font-weight: 500;
+}
+
+/* Rule under each section heading, above its rows. */
+.titleRule {
+  margin-bottom: 10px;
+  border-top: 0.5px solid var(--dsw-alias-border-l2);
+}
+
+.titleValue {
+  font-variant-numeric: tabular-nums;
+}
+
+/* Section-heading glyph seated left of the section name. */
+.titleLabel {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+}
+
+.titleLabel svg {
+  width: 14px;
+  height: 14px;
+  flex: none;
+}
+
+.details {
+  display: grid;
+  grid-template-columns: minmax(76px, auto) minmax(0, 1fr);
+  gap: 6px 16px;
+  margin: 0;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.details dt,
+.details dd {
+  min-width: 0;
+  margin: 0;
+}
+
+.details dd {
+  color: var(--dsw-alias-label-secondary);
+  font-variant-numeric: tabular-nums;
+  text-align: right;
+}
+
+.details .route {
+  overflow-wrap: anywhere;
+}
+
+.reasoning {
+  color: var(--dsw-alias-label-tertiary);
+  white-space: nowrap;
+}
diff --git a/packages/client/ui-chat/src/client/chat/stat-dialog.ts b/packages/client/ui-chat/src/client/chat/stat-dialog.ts
new file mode 100644
index 0000000000..10c1071d3c
--- /dev/null
+++ b/packages/client/ui-chat/src/client/chat/stat-dialog.ts
@@ -0,0 +1,66 @@
+// One trigger-anchored stat dialog seat shared by the Turn-stat pills
+// (TurnUsagePanel) and the composer-dock session stats pills (StatsPills);
+// the matching dialog surface skin lives in stat-dialog.module.css.
+
+import { useEffect, useRef, useState, type CSSProperties, type MutableRefObject } from 'react'
+import { useAnchoredPosition, useDismissOnOutsidePointer } from '@deepseek-ai/dsh-client-ui-primitives'
+
+/** Viewport margin the placement clamp keeps (the Menu portal margin). */
+const PANEL_MARGIN = 12
+
+/** Distance between the trigger's top edge and the panel's bottom. */
+const PANEL_GAP = 8
+
+/**
+ * Unplaced portal panel: hidden but laid out so the clamp measures real
+ * dimensions (the `useAnchoredPosition` measure pass).
+ */
+export const MEASURE_STYLE: CSSProperties = { visibility: 'hidden', left: 0, top: 0 }
+
+/** Open state, refs, and clamped placement for one stat dialog. */
+export interface StatDialogSeat {
+  open: boolean
+  setOpen: (open: boolean) => void
+  rootRef: MutableRefObject<HTMLSpanElement | null>
+  panelRef: MutableRefObject<HTMLDivElement | null>
+  pos: CSSProperties | null
+}
+
+/**
+ * One trigger-anchored dialog seat: open state, viewport-clamped placement, outside-close.
+ * @param controlled - external open state; when given the seat reads and writes
+ * it instead of owning its own, letting sibling dialogs share one exclusive slot.
+ * @returns the seat; spread `pos ?? MEASURE_STYLE` onto the portaled panel.
+ */
+export function useStatDialog(controlled?: Pick<StatDialogSeat, 'open' | 'setOpen'>): StatDialogSeat {
+  const [ownOpen, setOwnOpen] = useState(false)
+  const open = controlled?.open ?? ownOpen
+  const setOpen = controlled?.setOpen ?? setOwnOpen
+  const rootRef = useRef<HTMLSpanElement | null>(null)
+  const panelRef = useRef<HTMLDivElement | null>(null)
+
+  // Portal placement: the dialog is fixed above the trigger and clamped inside
+  // the viewport, so a trigger near the window edge cannot push it off-screen.
+  const pos = useAnchoredPosition({
+    open,
+    anchorRef: rootRef,
+    panelRef,
+    side: 'top',
+    gap: PANEL_GAP,
+    margin: PANEL_MARGIN,
+  })
+
+  // Outside pointerdown closes through the shared primitive; the portaled
+  // panel counts as inside. Escape close stays local, one listener while open.
+  useDismissOnOutsidePointer(rootRef, open, setOpen, panelRef)
+  useEffect(() => {
+    if (!open) return
+    const onKeyDown = (e: KeyboardEvent): void => {
+      if (e.key === 'Escape') setOpen(false)
+    }
+    document.addEventListener('keydown', onKeyDown)
+    return () => { document.removeEventListener('keydown', onKeyDown) }
+  }, [open, setOpen])
+
+  return { open, setOpen, rootRef, panelRef, pos }
+}
diff --git a/packages/client/ui-chat/src/client/contract/slots.ts b/packages/client/ui-chat/src/client/contract/slots.ts
index eb2ed7cf83..3fb8bcfcee 100644
--- a/packages/client/ui-chat/src/client/contract/slots.ts
+++ b/packages/client/ui-chat/src/client/contract/slots.ts
@@ -3,7 +3,7 @@ import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
 import type { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import type {
   CommandNode, CompactionSummaryNode, ConversationLocationDataStore, ConversationTurnDataMap,
-  MessageImageLoader, MessageImagesOwnerProps, RenderMessageImages, ToolCallBlock, TurnLocation,
+  MessageImageLoader, MessageImagesOwnerProps, RenderMessageImages, TurnLocation,
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type {
   InjectFace, KeyedSnapshotSelectorHook, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore,
@@ -13,7 +13,7 @@ import type { SnapshotStore } from '@deepseek-ai/dsh-client-store'
 import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives'
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 import type { createChatStore } from '../stores.ts'
-import type { ToolCallId, SelectionTarget } from './store.ts'
+import type { ToolCallId } from './store.ts'
 import type { ChatConversationViewNode, ChatNode, ChatNodeKind } from './chat-nodes.ts'
 import type {
   ChatNodeProcessSource, ChatNodeSource, ChatSnapshot, ChatTurnProcessPresentation,
@@ -30,6 +30,12 @@ export type UseChatNode = KeyedSnapshotSelectorHook<ChatConversationViewNode | u
 /** Per-key selector hook over one Chat Node's Turn-process presentation. */
 export type UseChatNodeProcess = KeyedSnapshotSelectorHook<ChatTurnProcessPresentation | undefined>
 
+/** Where in a file an open should land. */
+export interface OpenFileOptions {
+  /** 1-based line to reveal; absent = the file's beginning. */
+  readonly line?: number
+}
+
 /** Owner currency of the completed-Turn extension chain. */
 export interface TurnTailOwnerProps {
   turn: TurnLocation
@@ -71,9 +77,8 @@ export interface ChatNodeTurnDataInjected {
 
 /** Stable owner currency delivered to a keyed Chat renderer. */
 export interface ChatNodeOwnerProps {
-  selectedCallId?: ToolCallId | undefined
   cwd?: string | undefined
-  openFile: (path: string) => void
+  openFile: (path: string, options?: OpenFileOptions) => void
   inspectCall: (callId: ToolCallId) => void
   forkAt: (seq: number) => void
   /**
@@ -101,12 +106,6 @@ export interface TurnProcessOwnerProps {
 export type ChatNodeViewProps<Kind extends ChatNodeKind = ChatNodeKind> =
   PropsRuntime<'conversation.chat.node', Kind> & PropsLocale<'chat'>
 
-/** Tool block rendered in the details panel. */
-export interface DetailsToolOwnerProps {
-  block: ToolCallBlock
-  cwd?: string | undefined
-}
-
 /** Command-row owner share. */
 export interface CommandRowOwnerProps {
   node: CommandNode
@@ -138,8 +137,7 @@ export interface ChatViewInjected {
     /** Resolve the stable Turn-process source for one Chat Node key. */
     chatNodeProcess: (key: string) => ChatNodeProcessSource
   }
-  openDetails: (target: SelectionTarget) => void
-  openFile: (path: string) => Promise<void>
+  openFile: (path: string, options?: OpenFileOptions) => Promise<void>
   loadOlder: () => void
   /** Jump loader: page history back through seq; resolves when the window covers it. */
   loadThrough: (seq: SessionSeq) => Promise<void>
@@ -163,19 +161,6 @@ export type ChatViewSlotProps =
 /** Full props of the durable-message image renderer. */
 export type MessageImagesProps = PropsRuntime<'conversation.message.images'> & PropsLocale<'conversation'>
 
-/** Details-panel callbacks. */
-export interface DetailsInjected {
-  closeDetails: () => void
-}
-
-/** Full details-panel props. */
-export type DetailsSlotProps =
-  PropsRuntime<'details'>
-  & PropsRenderSlots<'conversation.details.tool'>
-  & PropsStore<ChatStore>
-  & InjectFace<DetailsInjected>
-  & PropsLocale<'chat'>
-
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface SessionStandardProps {
     /** Selector hook over the current Conversation binding's Chat target. */
@@ -225,11 +210,5 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      * that entry. With no entries, the standard action row remains unchanged.
      */
     'conversation.chat.assistant-actions': { kind: 'list'; scope: 'session'; owner: AssistantActionOwnerProps }
-    /**
-     * Whole details-panel body for the selected Tool call. The component receives
-     * the running or settled block and optional workspace root. A registration
-     * replaces the shipped Tool details renderer; absence uses the raw fallback.
-     */
-    'conversation.details.tool': { kind: 'single'; scope: 'session'; owner: DetailsToolOwnerProps }
   }
 }
diff --git a/packages/client/ui-chat/src/client/contract/snapshot.ts b/packages/client/ui-chat/src/client/contract/snapshot.ts
index c7544d4a16..0d02198811 100644
--- a/packages/client/ui-chat/src/client/contract/snapshot.ts
+++ b/packages/client/ui-chat/src/client/contract/snapshot.ts
@@ -79,7 +79,7 @@ export interface ChatTurnProcessPresentation {
   readonly compactAnswer: boolean
 }
 
-/** Compatibility projection backing StatsLine and the legacy top-level snapshot fields. */
+/** Compatibility projection backing StatsPills and the legacy top-level snapshot fields. */
 export interface LegacyConversationSlice {
   readonly nodes: readonly ConversationNode[]
   readonly turnTimings: ReadonlyMap<number, { readonly startTime: number; readonly endTime?: number }>
diff --git a/packages/client/ui-chat/src/client/contract/store.ts b/packages/client/ui-chat/src/client/contract/store.ts
index dc7bb4463e..78a248dd54 100644
--- a/packages/client/ui-chat/src/client/contract/store.ts
+++ b/packages/client/ui-chat/src/client/contract/store.ts
@@ -1,16 +1,8 @@
-/** Chat-owned selection state shared by the transcript and details panel. */
+/** Chat-owned per-Session view state. */
 
 /** Tool call identity as carried by Chat nodes. */
 export type ToolCallId = string
 
-/** Selection target for the Chat details linkage channel. */
-export interface SelectionTarget {
-  turnSeq: number
-  stepSeq?: number
-  callId?: ToolCallId
-  toolName?: string
-}
-
 /** One manually expanded Turn answer generation. */
 export interface TurnProcessViewEntry {
   readonly turn: number
@@ -19,6 +11,5 @@ export interface TurnProcessViewEntry {
 
 /** Per-Session state shared only by the Chat view and details surface. */
 export interface ChatStoreState {
-  selection: SelectionTarget | null
   turnProcesses: TurnProcessViewEntry[]
 }
diff --git a/packages/client/ui-chat/src/client/contract/turn-metrics.ts b/packages/client/ui-chat/src/client/contract/turn-metrics.ts
index 5880a92af5..a9f4dbc7c0 100644
--- a/packages/client/ui-chat/src/client/contract/turn-metrics.ts
+++ b/packages/client/ui-chat/src/client/contract/turn-metrics.ts
@@ -1,4 +1,4 @@
-// Latency/throughput folds shared by the settled turn footer and StatsLine.
+// Latency/throughput folds shared by the settled turn footer and StatsPills.
 
 import type {
   AssistantMessageNode, ConversationNode,
diff --git a/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts b/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts
index 04cb38bc94..fb91233786 100644
--- a/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts
+++ b/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts
@@ -730,7 +730,7 @@ const EMPTY_CONTRIBUTION: LegacyContribution = {
 function legacyContribution(raw: ChatConversationViewNode): LegacyContribution {
   const node = raw as ChatNode
   // Content-free settled Assistants remain in the finalized compatibility
-  // stream so StatsLine preserves its pre-assembly step counts; hidden running
+  // stream so StatsPills preserves its pre-assembly step counts; hidden running
   // attempts have no final Node to contribute.
   if (raw.visibility !== 'visible' && node.kind !== 'assistant-step') return EMPTY_CONTRIBUTION
   switch (node.kind) {
@@ -802,7 +802,7 @@ function sameContribution(left: LegacyContribution | undefined, right: LegacyCon
     && sameReferences(left.nodes, right.nodes)
 }
 
-/** Incremental compatibility projection for StatsLine and legacy top-level snapshot fields. */
+/** Incremental compatibility projection for StatsPills and legacy top-level snapshot fields. */
 class LegacySliceBuilder {
   private readonly contributions = new Map<string, LegacyContribution>()
   private readonly finalizedContributions = new Map<string, LegacyContribution>()
diff --git a/packages/client/ui-chat/src/client/details/DetailsPanel.module.css b/packages/client/ui-chat/src/client/details/DetailsPanel.module.css
deleted file mode 100644
index 85fdd8c0df..0000000000
--- a/packages/client/ui-chat/src/client/details/DetailsPanel.module.css
+++ /dev/null
@@ -1,95 +0,0 @@
-/* Details third column, minimal fill: header (name + close) over a
-   scrolling body of Input/Output code sections. Panel width/squeeze belongs
-   to layout; this fills whatever the column gives. */
-
-.root {
-  display: flex;
-  flex-direction: column;
-  height: 100%;
-  min-width: 0;
-  border-left: 0.5px 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: 0.5px 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;
-  corner-shape: round;
-  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-chat/src/client/details/DetailsPanel.tsx b/packages/client/ui-chat/src/client/details/DetailsPanel.tsx
deleted file mode 100644
index 05c997e1fe..0000000000
--- a/packages/client/ui-chat/src/client/details/DetailsPanel.tsx
+++ /dev/null
@@ -1,110 +0,0 @@
-import { Fragment } from 'react'
-import { CodeBlock } from '@deepseek-ai/dsh-client-ui-primitives'
-import { shallowEqual } from '@deepseek-ai/dsh-client-store'
-import type { DetailsSlotProps } from '../contract/slots.ts'
-import type { ChatSnapshot, RunningToolCall, ToolCallBlock, ToolResultNode } from '../contract/snapshot.ts'
-import { findToolCall } from './tool-node-reader.ts'
-import css from './DetailsPanel.module.css'
-
-export type DetailsPanelProps = DetailsSlotProps
-
-/** The snapshot-owned block reference must remain stable across unrelated frames. */
-interface CallMaterial {
-  name: string
-  argsRaw: string | null
-  block: ToolCallBlock
-}
-
-function settledMaterial(node: ToolResultNode, callId: string): CallMaterial {
-  return { name: node.call?.name ?? callId, argsRaw: node.call?.argsRaw ?? null, block: node }
-}
-
-function runningMaterial(call: RunningToolCall): CallMaterial {
-  return { name: call.name, argsRaw: call.argsRaw, block: call }
-}
-
-function materialFor(s: ChatSnapshot, callId: string): CallMaterial | null {
-  const found = findToolCall(s, callId)
-  if (found === undefined) return null
-  return 'kind' in found ? settledMaterial(found, callId) : runningMaterial(found)
-}
-
-function pretty(raw: string): string {
-  try {
-    return JSON.stringify(JSON.parse(raw), null, 2)
-  } catch {
-    return raw
-  }
-}
-
-/** Flatten a settled result for the no-ui-tool fallback. */
-function rawResultText(block: ToolCallBlock): string {
-  if (!('kind' in block)) return ''
-  const parts = block.content.map(item => item.type === 'text' ? item.text : JSON.stringify(item, null, 2))
-  if (parts.length === 0 && block.error !== undefined) parts.push(`${block.error.name}: ${block.error.code}`)
-  return parts.join('\n')
-}
-
-export function DetailsPanel({ useChat, useSessions, sessionId, useStore, renderSlot, closeDetails, t }: DetailsPanelProps) {
-  const selection = useStore(s => s.selection)
-  // Session workspace root: a card model resolves omitted or relative
-  // tool paths against it without reading Session services.
-  const sessionCwd = useSessions(list => list.byId[sessionId]?.cwd)
-  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 = useChat(
-    s => (callId === undefined ? null : materialFor(s, callId)),
-    (a, b) => shallowEqual(a, b))
-  return (
-    <div className={css.root}>
-      <div className={css.header}>
-        <div className={css.title}>
-          {selection === null ? t('details.title') : material?.name ?? selection.toolName ?? t('details.title')}
-        </div>
-        <button
-          type="button" className={css.close} aria-label={t('details.close')}
-          onClick={() => { 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}>{t('details.empty')}</div>
-          : material === null
-            ? <div className={css.empty}>{t('details.notInWindow')}</div>
-            : (
-              <>
-                {material.argsRaw !== null && (
-                  <section className={css.section}>
-                    <div className={css.sectionLabel}>{t('details.input')}</div>
-                    <CodeBlock code={pretty(material.argsRaw)} lang="json" copyLabel={t('copy')} copiedLabel={t('copied')} />
-                  </section>
-                )}
-                <section className={css.section}>
-                  <div className={css.sectionLabel}>{t('details.output')}</div>
-                  {/* Keyed by the selected call: the body owns per-call view
-                      state (the terminal card's expand and copy), which React
-                      would otherwise carry into the next selection because the
-                      panel does not unmount between calls. */}
-                  <Fragment key={callId}>
-                    {renderSlot('conversation.details.tool', { block: material.block, cwd: sessionCwd }, {
-                      fallback: 'kind' in material.block
-                        ? (
-                          <pre className={css.code} data-error={material.block.isError || undefined}>
-                            {rawResultText(material.block)}
-                          </pre>
-                        )
-                        : <div className={css.empty}>{t('details.running')}</div>,
-                    })}
-                  </Fragment>
-                </section>
-              </>
-            )}
-      </div>
-    </div>
-  )
-}
diff --git a/packages/client/ui-chat/src/client/details/tool-node-reader.ts b/packages/client/ui-chat/src/client/details/tool-node-reader.ts
deleted file mode 100644
index 9e2488b68f..0000000000
--- a/packages/client/ui-chat/src/client/details/tool-node-reader.ts
+++ /dev/null
@@ -1,30 +0,0 @@
-import type { ChatNode } from '../contract/chat-nodes.ts'
-import type { ChatNodeStore, ChatSnapshot, ToolCallBlock } from '../contract/snapshot.ts'
-
-function toolNode(node: ReturnType<ChatNodeStore['get']>): ChatNode<'tool-call'> | undefined {
-  return node?.kind === 'tool-call' ? node as ChatNode<'tool-call'> : undefined
-}
-
-/**
- * Find any root or nested Tool lifecycle through the internal Node store.
- * @param snapshot - current Conversation snapshot.
- * @param callId - root or nested call identity.
- * @returns current Tool lifecycle when materialized in the loaded window.
- */
-export function findToolCall(snapshot: ChatSnapshot, callId: string): ToolCallBlock | undefined {
-  const visit = (block: ToolCallBlock): ToolCallBlock | undefined => {
-    if (block.callId === callId) return block
-    for (const child of block.subCalls) {
-      const found = visit(child)
-      if (found !== undefined) return found
-    }
-    return undefined
-  }
-  for (const node of snapshot.nodes.values()) {
-    const root = toolNode(node)?.data.root
-    if (root === undefined) continue
-    const found = visit(root)
-    if (found !== undefined) return found
-  }
-  return undefined
-}
diff --git a/packages/client/ui-chat/src/client/index.ts b/packages/client/ui-chat/src/client/index.ts
index 5cae4dccd7..450ce00fce 100644
--- a/packages/client/ui-chat/src/client/index.ts
+++ b/packages/client/ui-chat/src/client/index.ts
@@ -27,14 +27,13 @@ export type {
   FinalAssistantChatData, ManualCompactionChatData, RetryChatData, ToolChatData,
   TurnProcessChatData, TurnTailChatData,
 } from './contract/chat-nodes.ts'
-export type { ChatStoreState, SelectionTarget, ToolCallId, TurnProcessViewEntry } from './contract/store.ts'
+export type { ChatStoreState, ToolCallId, TurnProcessViewEntry } from './contract/store.ts'
 export type { TranscriptViewRowInjected, TranscriptViewRowProps } from './settings/TranscriptViewRow.tsx'
 export type { TranscriptViewMode } from '../chat-settings.ts'
 export type {
   AssistantActionOwnerProps, ChatFileMentions, ChatNodeOwnerProps, ChatNodeTurnDataInjected,
   ChatNodeViewProps, ChatScrollPosition, ChatStore, ChatViewInjected, ChatViewSlotProps,
-  CommandRowOwnerProps, CommandRowProps, DetailsInjected, DetailsSlotProps,
-  DetailsToolOwnerProps, MessageImagesProps,
+  CommandRowOwnerProps, CommandRowProps, MessageImagesProps, OpenFileOptions,
   TurnProcessOwnerProps, TurnTailOwnerProps, UseChat, UseChatNodeTurnData,
 } from './contract/slots.ts'
 export type {
diff --git a/packages/client/ui-chat/src/client/locale.ts b/packages/client/ui-chat/src/client/locale.ts
index f10a9ced20..e426a56a14 100644
--- a/packages/client/ui-chat/src/client/locale.ts
+++ b/packages/client/ui-chat/src/client/locale.ts
@@ -10,20 +10,14 @@ export const zh = {
   'duration.compactSeconds': '{seconds}秒',
   'duration.compactMinutes': '{minutes}分{seconds}秒',
   'duration.milliseconds': '{milliseconds}毫秒',
-  'stats.counts': '{turns} 轮 · {steps} 步',
-  'stats.llm': 'LLM {duration}',
-  'stats.toolCall': '工具调用 {duration}',
-  'stats.ttftAverage': '首 token 平均 {duration}',
-  'stats.tokensPerSecond': '{throughput} tok/s',
+  'stats.counts': '{turns} 轮 {steps} 步',
   'stats.cacheHit': '缓存命中 {percent}%',
-  'stats.tokens': '输入 {input} tok · 输出 {output} tok',
-  'details.title': '详情',
-  'details.close': '关闭详情',
-  'details.empty': '点击消息流中的工具行查看详情',
-  'details.notInWindow': '该调用不在当前窗口内',
-  'details.input': '输入',
-  'details.output': '输出',
-  'details.running': '运行中…',
+  'stats.dialog.title': '会话统计',
+  'stats.dialog.usageTitle': 'Token 用量',
+  'stats.dialog.llmTime': '模型用时',
+  'stats.dialog.toolTime': '工具调用用时',
+  'stats.dialog.ttft': '首 token 平均（TTFT）',
+  'stats.dialog.speed': '输出速度（TPS）',
   'chat.loadingHistory': '载入历史…',
   'chat.loadError': '历史加载失败：{message}（{code}）',
   'chat.loadOlder': '加载更早',
@@ -39,8 +33,6 @@ export const zh = {
   'settings.transcript.compact': 'Compact',
   'fileOpen.title': '无法打开文件',
   'fileOpen.unknown': '无法打开此文件',
-  'fileOpen.folderTitle': '无法打开文件夹',
-  'fileOpen.folderUnknown': '无法打开此文件夹',
   'message.extraBlock': '附加内容块',
   'message.systemPrompt': '系统提示词',
   'message.contextInjection': '上下文注入',
@@ -127,20 +119,14 @@ export const en = {
   'duration.compactSeconds': '{seconds}s',
   'duration.compactMinutes': '{minutes}m{seconds}s',
   'duration.milliseconds': '{milliseconds}ms',
-  'stats.counts': '{turns} turns · {steps} steps',
-  'stats.llm': 'LLM {duration}',
-  'stats.toolCall': 'Tool call {duration}',
-  'stats.ttftAverage': 'TTFT avg {duration}',
-  'stats.tokensPerSecond': '{throughput} tok/s',
+  'stats.counts': '{turns} turns {steps} steps',
   'stats.cacheHit': 'Cache hit {percent}%',
-  'stats.tokens': 'Input {input} tok · Output {output} tok',
-  'details.title': 'Details',
-  'details.close': 'Close details',
-  'details.empty': 'Click a tool row in the message flow to view its details',
-  'details.notInWindow': 'This call is outside the current window',
-  'details.input': 'Input',
-  'details.output': 'Output',
-  'details.running': 'Running…',
+  'stats.dialog.title': 'Session statistics',
+  'stats.dialog.usageTitle': 'Token usage',
+  'stats.dialog.llmTime': 'LLM time',
+  'stats.dialog.toolTime': 'Tool time',
+  'stats.dialog.ttft': 'Avg time to first token (TTFT)',
+  'stats.dialog.speed': 'Tokens per second (TPS)',
   'chat.loadingHistory': 'Loading history…',
   'chat.loadError': 'Failed to load history: {message} ({code})',
   'chat.loadOlder': 'Load earlier',
@@ -156,8 +142,6 @@ export const en = {
   'settings.transcript.compact': 'Compact',
   'fileOpen.title': 'Couldn’t open file',
   'fileOpen.unknown': 'Couldn’t open this file',
-  'fileOpen.folderTitle': 'Couldn’t open folder',
-  'fileOpen.folderUnknown': 'Couldn’t open this folder',
   'message.extraBlock': 'Extra content block',
   'message.systemPrompt': 'System prompt',
   'message.contextInjection': 'Context injection',
diff --git a/packages/client/ui-chat/src/client/stores.ts b/packages/client/ui-chat/src/client/stores.ts
index a0115445e2..afb99e2f5d 100644
--- a/packages/client/ui-chat/src/client/stores.ts
+++ b/packages/client/ui-chat/src/client/stores.ts
@@ -1,9 +1,8 @@
-/** Per-Session Chat selection store shared by the transcript and details panel. */
+/** Per-Session Chat view store. */
 import { defineStore, type EngineStoreHandle } from '@deepseek-ai/dsh-client-store'
-import type { ChatStoreState, SelectionTarget, TurnProcessViewEntry } from './contract/store.ts'
+import type { ChatStoreState, TurnProcessViewEntry } from './contract/store.ts'
 
 type ChatActions = {
-  select: (draft: ChatStoreState, target: SelectionTarget | null) => void
   setTurnProcessOpen: (
     draft: ChatStoreState,
     turn: number,
@@ -26,14 +25,13 @@ export function storedTurnProcessEntry(
 }
 
 /**
- * Create the Chat selection store handle.
+ * Create the Chat view store handle.
  * @returns a handle instantiated once per rendered Session scope.
  */
 export function createChatStore(): EngineStoreHandle<ChatStoreState, ChatActions> {
   return defineStore({
-    init: (): ChatStoreState => ({ selection: null, turnProcesses: [] }),
+    init: (): ChatStoreState => ({ turnProcesses: [] }),
     actions: {
-      select: (draft, target: SelectionTarget | null) => { draft.selection = target },
       setTurnProcessOpen: (draft, turn, answerStep, open) => {
         const index = draft.turnProcesses.findIndex(entry => entry.turn === turn)
         if (!open) {
diff --git a/packages/client/ui-chat/tests/apply-inject.client.spec.tsx b/packages/client/ui-chat/tests/apply-inject.client.spec.tsx
index fa7cb20093..590cc5602c 100644
--- a/packages/client/ui-chat/tests/apply-inject.client.spec.tsx
+++ b/packages/client/ui-chat/tests/apply-inject.client.spec.tsx
@@ -5,7 +5,7 @@ import { AttachmentId } from '@deepseek-ai/dsh-attachment'
 import type { ISession } from '@deepseek-ai/dsh-api-session-controller/client'
 import { LocaleRuntime } from '@deepseek-ai/dsh-client-locale/client'
 import {
-  RemoteError, SlotTestRuntime, TestRemote, stubSettingsScope, usePinnedBrowserLanguages,
+  SlotTestRuntime, TestRemote, stubSettingsScope, usePinnedBrowserLanguages,
 } from '@deepseek-ai/dsh-client-test-runtime'
 import type { SessionBehaviorOverrides } from '@deepseek-ai/dsh-client-test-runtime'
 import type { ClientRemote } from '@deepseek-ai/dsh-api-remotes/client'
@@ -13,7 +13,7 @@ import {
   apply as applyConversation, inject as injectConversation,
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import {
-  apply as applyChat, inject as injectChat, type ChatViewInjected, type DetailsInjected,
+  apply as applyChat, inject as injectChat, type ChatViewInjected,
 } from '@deepseek-ai/dsh-client-ui-chat/client'
 import { SessionSeq, type SessionId } from '@deepseek-ai/dsh-session/types'
 import { createChatStore } from '../src/client/stores.ts'
@@ -48,8 +48,10 @@ function sessionFakeFor() {
 async function bench() {
   const runtime = await SlotTestRuntime.create()
   runtime.ctx.provide('settingsScope', { bind: () => stubSettingsScope().scope } as never)
-  const layout = { openDetails: vi.fn(), closeDetails: vi.fn() }
+  const layout = { closeRightbar: vi.fn(), openRightbar: vi.fn() }
   runtime.ctx.provide('layout', layout as never)
+  const sidebarRight = { openResource: vi.fn<(address: string) => void>() }
+  runtime.ctx.provide('sidebarRight', sidebarRight as never)
   const openWorkspacePath = vi.fn<ClientRemote['session']['openWorkspacePath']>(
     () => Promise.resolve({ ok: true, value: { opened: true } }),
   )
@@ -68,7 +70,6 @@ async function bench() {
   runtime.slots.installLocale(locale)
   await runtime.root.declare({
     'conversation': { kind: 'single', scope: 'session-maybe' },
-    'details': { kind: 'single', scope: 'session' },
   }, (_props: { renderSlot?: unknown }) => null)
   await runtime.mount({ inject: [...injectConversation], apply: applyConversation })
   await runtime.mount({ inject: [...injectChat], apply: applyChat })
@@ -83,7 +84,7 @@ async function bench() {
     ) => ChatViewInjected)(id, instance.actions)
     return { instance, injected }
   }
-  return { runtime, layout, openWorkspacePath, session, chatViewApi }
+  return { runtime, layout, openWorkspacePath, sidebarRight, session, chatViewApi }
 }
 
 describe('Chat inject API', () => {
@@ -112,28 +113,45 @@ describe('Chat inject API', () => {
     await b.runtime.dispose()
   })
 
-  it('writes Chat selection before opening details', async () => {
-    const b = await bench()
-    const { instance, injected } = b.chatViewApi(ROOT)
-    injected.openDetails({ turnSeq: 2, callId: 'c1' })
-    expect(instance.store.getSnapshot().selection).toEqual({ turnSeq: 2, callId: 'c1' })
-    expect(b.layout.openDetails).toHaveBeenCalledOnce()
-    expect(b.runtime.storeOf('details', ROOT)).toBe(instance)
-    expect(b.runtime.storeOf('conversation.session', ROOT)).not.toBe(instance)
-    await b.runtime.dispose()
-  })
-
-  it('resolves file paths against the Session cwd and preserves failures', async () => {
+  it('addresses file paths under the Session\'s scope and opens them in the right Sidebar', async () => {
     const b = await bench()
     const { injected } = b.chatViewApi(ROOT)
     await injected.openFile('src/a.ts')
-    expect(b.openWorkspacePath).toHaveBeenCalledWith({ path: '/proj/src/a.ts' })
+    // Files stay in the product: a relative path is handed to the Sidebar as an
+    // address under this session's scope, not to a desktop opener.
+    expect(b.sidebarRight.openResource).toHaveBeenCalledWith('dsh-resource://file/session/root-1/src/a.ts')
+    expect(b.openWorkspacePath).not.toHaveBeenCalled()
 
-    b.openWorkspacePath.mockResolvedValueOnce({
-      ok: false,
-      error: new RemoteError('gateway/internal', 'xdg-open is not available', {}),
-    })
-    await expect(injected.openFile('src/b.ts')).rejects.toThrow('path open failed: xdg-open is not available')
+    // An absolute path inside the session's workspace is the same session-relative address.
+    await injected.openFile('/proj/src/a.ts')
+    expect(b.sidebarRight.openResource).toHaveBeenLastCalledWith('dsh-resource://file/session/root-1/src/a.ts')
+
+    // A name a URL would otherwise mangle survives the round trip.
+    await injected.openFile('src/a b#c.ts')
+    expect(b.sidebarRight.openResource).toHaveBeenLastCalledWith('dsh-resource://file/session/root-1/src/a%20b%23c.ts')
+
+    // A line travels as the `file` type's navigation parameter, not in the address.
+    await injected.openFile('src/a.ts', { line: 7 })
+    expect(b.sidebarRight.openResource).toHaveBeenLastCalledWith('dsh-resource://file/session/root-1/src/a.ts', { params: { line: 7 } })
+    await b.runtime.dispose()
+  })
+
+  it('keeps a relative path under the Session without a cwd, and addresses a path outside the workspace absolutely', async () => {
+    const b = await bench()
+    const NO_CWD = 'root-2' as SessionId
+    await b.runtime.sessions.add({
+      id: NO_CWD,
+      summary: { title: 'N', displayTitle: 'N' },
+      session: sessionFakeFor(),
+    }, { current: false })
+    const { injected } = b.chatViewApi(NO_CWD)
+    // The Host resolves the relative path against the root it holds for the
+    // Session; the Client need not know it.
+    await injected.openFile('src/a.ts')
+    expect(b.sidebarRight.openResource).toHaveBeenCalledWith('dsh-resource://file/session/root-2/src/a.ts')
+    // An absolute path outside every known root carries no Session in its address.
+    await injected.openFile('/abs/a.ts')
+    expect(b.sidebarRight.openResource).toHaveBeenLastCalledWith('dsh-resource://file/absolute/abs/a.ts')
     await b.runtime.dispose()
   })
 
@@ -149,17 +167,6 @@ describe('Chat inject API', () => {
     await b.runtime.dispose()
   })
 
-  it('closes details while sharing selection through the Chat store', async () => {
-    const b = await bench()
-    const entry = b.runtime.slots.entries('details')[0]!
-    const injected = (entry.inject as unknown as () => DetailsInjected)()
-    expect(Object.keys(injected)).toEqual(['closeDetails'])
-    injected.closeDetails()
-    expect(b.layout.closeDetails).toHaveBeenCalledOnce()
-    expect(b.runtime.storeOf('details', ROOT)).toBe(b.runtime.storeOf('conversation.view', ROOT))
-    await b.runtime.dispose()
-  })
-
   it('owns image loading, scroll memory, and optional closing-file mentions', async () => {
     const b = await bench()
     const { injected } = b.chatViewApi(ROOT)
diff --git a/packages/client/ui-chat/tests/chat-apply.client.spec.tsx b/packages/client/ui-chat/tests/chat-apply.client.spec.tsx
index 23d2384ec4..fc1cf43bc5 100644
--- a/packages/client/ui-chat/tests/chat-apply.client.spec.tsx
+++ b/packages/client/ui-chat/tests/chat-apply.client.spec.tsx
@@ -41,7 +41,8 @@ async function bench() {
       ? chatSettings.scope
       : stubSettingsScope().scope,
   } as never)
-  runtime.ctx.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() } as never)
+  runtime.ctx.provide('layout', { openRightbar: vi.fn(), closeRightbar: vi.fn() } as never)
+  runtime.ctx.provide('sidebarRight', { openResource: vi.fn() } as never)
   runtime.ctx.provide('uiWorkspace', {
     connectWorkspace: vi.fn(async () => SID),
   } as never)
@@ -53,7 +54,6 @@ async function bench() {
   runtime.slots.installLocale(locale)
   await runtime.root.declare({
     'conversation': { kind: 'single', scope: 'session-maybe' },
-    'details': { kind: 'single', scope: 'session' },
     'conversation.approval.detail': { kind: 'single', scope: 'session' },
     'settings.general.item': { kind: 'list', scope: 'root' },
   }, (_props: { renderSlot?: unknown }) => null)
@@ -68,12 +68,12 @@ async function bench() {
   return { runtime, conversation, chat, chatSettings, sourceDescriptor }
 }
 
-function storeOf(runtime: SlotTestRuntime, key: 'conversation.session' | 'conversation.session.header' | 'conversation.view' | 'details') {
+function storeOf(runtime: SlotTestRuntime, key: 'conversation.session' | 'conversation.session.header' | 'conversation.view') {
   return (runtime.slots.entries(key)[0] as { store?: unknown } | undefined)?.store
 }
 
 describe('Chat apply wiring', () => {
-  it('contributes Chat View, node renderers, stats, and details', async () => {
+  it('contributes Chat View, node renderers, and stats', async () => {
     const b = await bench()
     const views = b.runtime.slots.entries('conversation.view')
     expect(views.map(row => row.options.id)).toEqual(['chat'])
@@ -84,7 +84,6 @@ describe('Chat apply wiring', () => {
       .toEqual(['stats'])
     expect(b.runtime.slots.entries('settings.general.item').map(row => row.options.id))
       .toEqual(['transcript-view', 'composer-enter'])
-    expect(b.runtime.slots.entries('details')).toHaveLength(1)
     await b.runtime.dispose()
   })
 
@@ -111,7 +110,6 @@ describe('Chat apply wiring', () => {
     const conversationStore = storeOf(b.runtime, 'conversation.session')
     const chatStore = storeOf(b.runtime, 'conversation.view')
     expect(storeOf(b.runtime, 'conversation.session.header')).toBe(conversationStore)
-    expect(storeOf(b.runtime, 'details')).toBe(chatStore)
     expect(chatStore).toBeDefined()
     expect(chatStore).not.toBe(conversationStore)
     await b.runtime.dispose()
diff --git a/packages/client/ui-chat/tests/chat-branch-tails.client.spec.tsx b/packages/client/ui-chat/tests/chat-branch-tails.client.spec.tsx
index d9a77dd63b..5991449f44 100644
--- a/packages/client/ui-chat/tests/chat-branch-tails.client.spec.tsx
+++ b/packages/client/ui-chat/tests/chat-branch-tails.client.spec.tsx
@@ -16,18 +16,10 @@ import {
   UserMessageNodeView,
 } from '../src/client/chat/MessageItem.tsx'
 import { AssistantMarkdown, type AssistantMarkdownProps } from '../src/client/chat/AssistantMarkdown.tsx'
-import { StatsLine } from '../src/client/chat/StatsLine.tsx'
+import { StatsPills } from '../src/client/chat/StatsPills.tsx'
 import { zh } from '../src/client/locale.ts'
 import { chatSnapshotFixture } from './chat-snapshot-fixture.client.ts'
 
-/** jsdom has no ResizeObserver; StatsLine watches its row for ellipsis truncation through one. */
-class ResizeObserverStub {
-  observe(): void {}
-  unobserve(): void {}
-  disconnect(): void {}
-}
-
-beforeEach(() => { vi.stubGlobal('ResizeObserver', ResizeObserverStub) })
 afterEach(() => {
   cleanup()
   vi.useRealTimers()
@@ -1042,7 +1034,7 @@ describe('small branch tails', () => {
     expect(view.getByText('one-liner')).toBeTruthy()
   })
 
-  it('StatsLine omits the cache-hit segment when no input accounting exists at all', () => {
+  it('StatsPills omits the cache-hit segment when no input accounting exists at all', () => {
     // Cache hit is null only when all three prompt buckets are zero (pure
     // output accounting) — any billed input makes it a real 0%.
     const nodes = [{
@@ -1051,7 +1043,7 @@ describe('small branch tails', () => {
     const snap = chatSnapshotFixture({ nodes })
     const source = { getSnapshot: () => snap, subscribe: () => () => {} }
     const view = render(
-      <StatsLine
+      <StatsPills
         t={t}
         useChat={bindSnapshotSelector(source)}
         useProjection={(key: string) => key === 'tokenUsage'
@@ -1059,7 +1051,15 @@ describe('small branch tails', () => {
           : undefined}
       />,
     )
-    expect(view.container.textContent).toBe('1 轮 · 1 步| 输入 0 tok · 输出 10 tok')
+    // The untimed counts pill renders static, so the usage pill is the only button.
+    const [usagePill] = [...view.getAllByRole('button')] as [HTMLElement]
+    expect(view.getByText('1 轮 1 步').closest('button')).toBeNull()
+    expect(usagePill.textContent).toBe('10 tok')
+    // Pure output accounting still reaches the usage pill's click-open dialog rows.
+    fireEvent.click(usagePill)
+    const dialog = view.getByRole('dialog')
+    expect(dialog.textContent).toContain('输出10 tok')
+    expect(dialog.textContent).not.toContain('缓存命中')
   })
 })
 
diff --git a/packages/client/ui-chat/tests/chat-stats.client.spec.tsx b/packages/client/ui-chat/tests/chat-stats.client.spec.tsx
index e35aa297dc..f3980bef39 100644
--- a/packages/client/ui-chat/tests/chat-stats.client.spec.tsx
+++ b/packages/client/ui-chat/tests/chat-stats.client.spec.tsx
@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
 import type {
   AssistantMessageNode, ChatSnapshot, LegacyConversationSlice, ToolResultNode,
@@ -8,27 +8,17 @@ import type {
 import { bindSnapshotSelector, makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { en as commonEn } from '@deepseek-ai/dsh-client-locale/src/locales/en.ts'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
-import { StatsLine, deriveStats, formatDuration, type StatsLineProps } from '../src/client/chat/StatsLine.tsx'
+import { StatsPills, deriveStats, formatDuration, type StatsPillsProps } from '../src/client/chat/StatsPills.tsx'
 import { formatTokens } from '../src/client/chat/token-format.ts'
 import { en, zh } from '../src/client/locale.ts'
 import { chatSnapshotFixture } from './chat-snapshot-fixture.client.ts'
 
-const t: StatsLineProps['t'] = makeTranslate(zh, commonZh)
-const tEn: StatsLineProps['t'] = makeTranslate(en, commonEn)
+const t: StatsPillsProps['t'] = makeTranslate(zh, commonZh)
+const tEn: StatsPillsProps['t'] = makeTranslate(en, commonEn)
 
-/** jsdom has no ResizeObserver; StatsLine watches its row for ellipsis truncation through one. */
-class ResizeObserverStub {
-  observe(): void {}
-  unobserve(): void {}
-  disconnect(): void {}
-}
-
-beforeEach(() => { vi.stubGlobal('ResizeObserver', ResizeObserverStub) })
 afterEach(() => {
   cleanup()
-  vi.unstubAllGlobals()
   vi.restoreAllMocks()
-  vi.useRealTimers()
 })
 
 const assistant = (seq: number, turn: number, usage?: unknown): AssistantMessageNode => ({
@@ -135,7 +125,7 @@ describe('formatters', () => {
   })
 })
 
-describe('StatsLine', () => {
+describe('StatsPills', () => {
   const USAGE = { uncachedInputTokens: 10, outputTokens: 5, cacheReadTokens: 90, cacheWriteTokens: 0 }
 
   /** A whole-log sessionStats value: zeros plus overrides. */
@@ -147,14 +137,14 @@ describe('StatsLine', () => {
   }
 
   /** Stub the projection seat: a key-addressed table of whole values. */
-  function projections(values: Record<string, unknown>): StatsLineProps['useProjection'] {
+  function projections(values: Record<string, unknown>): StatsPillsProps['useProjection'] {
     return (key: string) => values[key]
   }
 
   function props(
     source: { getSnapshot(): ChatSnapshot; subscribe(fn: () => void): () => void },
     values: Record<string, unknown> = { tokenUsage: USAGE },
-  ): StatsLineProps {
+  ): StatsPillsProps {
     return { useChat: bindSnapshotSelector(source), useProjection: projections(values), t: tEn }
   }
 
@@ -162,37 +152,34 @@ describe('StatsLine', () => {
     return { uncachedInputTokens, outputTokens: 1, cacheReadTokens, cacheWriteTokens: 0 }
   }
 
-  it('mounts one size observer only while a non-empty line exists', () => {
-    let observers = 0
-    class CountingResizeObserver {
-      constructor(_callback: ResizeObserverCallback) { observers++ }
-      observe(): void {}
-      disconnect(): void {}
-    }
-    vi.stubGlobal('ResizeObserver', CountingResizeObserver)
-    const { set, source } = makeSource()
-    render(<StatsLine {...props(source, {})} />)
-    expect(observers).toBe(0)
-
-    act(() => { set({ nodes: [assistant(1, 1)] }) })
-    expect(observers).toBe(1)
-
-    act(() => { set({ nodes: [assistant(1, 1), assistant(2, 1)] }) })
-    expect(observers).toBe(1)
+  /** A step whose timing yields 3.8s LLM, 0.8s TTFT, and 20 tok/s over 60 tokens. */
+  const timedStep = (): AssistantMessageNode => ({
+    ...assistant(1, 1, { outputTokens: 60 }),
+    timing: { stepStartTime: 1_000, firstTokenTime: 1_800, completedTime: 4_800 },
   })
 
-  it('renders the grouped stats row and hides a brand-new empty session', () => {
+  it('renders the counts reading and usage pill and hides a brand-new empty session', () => {
     const { source } = makeSource({ nodes: [assistant(1, 1)] })
-    const view = render(<StatsLine {...props(source)} />)
-    // No timing on the fixture: the duration group drops out whole. Tokens come
-    // from the projection, so paging the window cannot change them.
-    expect(view.container.textContent).toBe('1 turns · 1 steps| Cache hit 90%| Input 100 tok · Output 5 tok')
+    const view = render(<StatsPills {...props(source)} />)
+    // InputBar's `.root:has([data-composer-stats])` bottom-clearance rule keys
+    // off this attribute: present exactly while the row renders.
+    expect(view.container.querySelector('[data-composer-stats]')).toBeTruthy()
+    // No timing on the fixture: the speed segment drops out and the dialog
+    // would have no rows, so the counts reading stays a static pill (no button).
+    expect(view.getByText('1 turns 1 steps').closest('button')).toBeNull()
+    // Cache hit comes from the projection, so paging the window cannot change
+    // it; the usage pill leads with the whole-log token total. Its accessible
+    // name separates the segments the visual sep glyph joins.
+    const usagePill = view.getAllByRole('button')
+    expect(usagePill.map(pill => pill.textContent)).toEqual(['105 tok·Cache hit 90%'])
+    expect(usagePill[0]!.getAttribute('aria-label')).toBe('105 tok · Cache hit 90%')
     const empty = makeSource()
-    const emptyView = render(<StatsLine {...props(empty.source, {
+    const emptyView = render(<StatsPills {...props(empty.source, {
       tokenUsage: { uncachedInputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 },
       contextPressure: {},
     })} />)
     expect(emptyView.container.textContent).toBe('')
+    expect(emptyView.container.querySelector('[data-composer-stats]')).toBeNull()
   })
 
   it.each([
@@ -214,153 +201,225 @@ describe('StatsLine', () => {
     { actual: '100%', tokenUsageValue: tokenUsage(10_000, 0), expected: 'Cache hit 100%' },
   ])('formats an actual $actual cache-hit ratio as $expected', ({ tokenUsageValue, expected }) => {
     const { source } = makeSource({ nodes: [assistant(1, 1)] })
-    const view = render(<StatsLine {...props(source, { tokenUsage: tokenUsageValue })} />)
-    expect(view.container.textContent).toContain(expected)
+    const view = render(<StatsPills {...props(source, { tokenUsage: tokenUsageValue })} />)
+    expect(view.getAllByRole('button')[0]!.textContent).toContain(expected)
   })
 
-  it('reveals the full line in a delayed hover tooltip only while the row is clipped', () => {
-    vi.useFakeTimers()
-    // jsdom lays nothing out; fake a row narrower than its content.
-    vi.spyOn(Element.prototype, 'scrollWidth', 'get').mockReturnValue(800)
-    vi.spyOn(Element.prototype, 'clientWidth', 'get').mockReturnValue(400)
-    const { source } = makeSource({ nodes: [assistant(1, 1)] })
-    const view = render(<StatsLine {...props(source, { tokenUsage: tokenUsage(9_995, 5) })} />)
-    expect(view.container.textContent).toContain('Cache hit 99.95%')
-    fireEvent.mouseEnter(view.container.firstElementChild!)
-    act(() => { vi.advanceTimersByTime(499) })
-    expect(view.container.querySelector('[role="tooltip"]')).toBeNull()
-    act(() => { vi.advanceTimersByTime(1) })
-    expect(view.container.querySelector('[role="tooltip"]')?.textContent)
-      .toBe('1 turns · 1 steps | Cache hit 99.95% | Input 10K tok · Output 1 tok')
+  it('exposes output speed on the counts pill when decode timing exists', () => {
+    const { source } = makeSource({ nodes: [timedStep()] })
+    const view = render(<StatsPills {...props(source)} />)
+    const timePill = view.getAllByRole('button')[0]!
+    expect(timePill.textContent).toBe('1 turns 1 steps·20 tok/s')
+    expect(timePill.getAttribute('aria-label')).toBe('1 turns 1 steps · 20 tok/s')
   })
 
-  it('suppresses the tooltip while the row fits without truncation', () => {
-    vi.useFakeTimers()
-    const { source } = makeSource({ nodes: [assistant(1, 1)] })
-    const view = render(<StatsLine {...props(source)} />)
-    fireEvent.mouseEnter(view.container.firstElementChild!)
-    act(() => { vi.advanceTimersByTime(500) })
-    expect(view.container.querySelector('[role="tooltip"]')).toBeNull()
+  it('click-opens the time-and-speed dialog carrying the time split and speeds', () => {
+    const { source } = makeSource({ nodes: [timedStep()] })
+    const view = render(<StatsPills {...props(source)} />)
+
+    const timePill = view.getAllByRole('button')[0]!
+    expect(timePill.getAttribute('aria-haspopup')).toBe('dialog')
+    expect(timePill.getAttribute('aria-expanded')).toBe('false')
+    expect(view.queryByRole('dialog')).toBeNull()
+
+    fireEvent.click(timePill)
+    expect(timePill.getAttribute('aria-expanded')).toBe('true')
+    const dialog = view.getByRole('dialog')
+    expect(dialog.getAttribute('aria-label')).toBe('Session statistics')
+    // Portaled out of the composer dock.
+    expect(dialog.parentElement).toBe(document.body)
+    expect(dialog.firstChild?.textContent).toBe('Session statistics')
+    const details = dialog.querySelector('[data-session-stats-details]') as HTMLElement
+    expect(details).toBeTruthy()
+    expect(details.textContent).toContain('LLM time3.8s')
+    // No tool call in this session: the row is absent, not zeroed.
+    expect(details.textContent).not.toContain('Tool time')
+    expect(details.textContent).toContain('Avg time to first token (TTFT)0.8s')
+    expect(details.textContent).toContain('Tokens per second (TPS)20 tok/s')
+    // Token accounting lives on the usage pill's own dialog, not here.
+    expect(dialog.textContent).not.toContain('Token usage')
   })
 
-  it('renders window latency and throughput beside the wall-time group', () => {
-    const timed: AssistantMessageNode = {
-      ...assistant(1, 1, { outputTokens: 60 }),
-      timing: { stepStartTime: 1_000, firstTokenTime: 1_800, completedTime: 4_800 },
-    }
-    const { source } = makeSource({ nodes: [timed] })
-    const view = render(<StatsLine {...props(source)} />)
-    expect(view.container.textContent).toContain('LLM 3.8s| TTFT avg 0.8s · 20 tok/s')
+  it('click-opens the token-usage dialog carrying the headline total and exact buckets', () => {
+    const { source } = makeSource({ nodes: [timedStep()] })
+    const view = render(<StatsPills {...props(source)} />)
+
+    const usagePill = view.getAllByRole('button')[1]!
+    fireEvent.click(usagePill)
+    expect(usagePill.getAttribute('aria-expanded')).toBe('true')
+    const dialog = view.getByRole('dialog')
+    expect(dialog.getAttribute('aria-label')).toBe('Token usage')
+    expect(dialog.parentElement).toBe(document.body)
+    // Headline total: all prompt-side buckets (10 + 90 + 0) plus output (5).
+    expect(dialog.firstChild?.textContent).toBe('Token usage105 tok')
+    const tokens = dialog.querySelector('[data-session-stats-usage]') as HTMLElement
+    expect(tokens).toBeTruthy()
+    expect(tokens.textContent).toContain('Cache hit90%')
+    expect(tokens.textContent).toContain('Uncached input10 tok')
+    expect(tokens.textContent).toContain('Cached input90 tok')
+    expect(tokens.textContent).toContain('Cache write0 tok')
+    expect(tokens.textContent).toContain('Output5 tok')
+    // The time split lives on the counts pill's own dialog, not here.
+    expect(dialog.textContent).not.toContain('LLM time')
   })
 
-  it('takes every stats label from the active locale', () => {
-    const timed: AssistantMessageNode = {
-      ...assistant(1, 1, { outputTokens: 60 }),
-      timing: { stepStartTime: 1_000, firstTokenTime: 1_800, completedTime: 4_800 },
-    }
-    const { source } = makeSource({ nodes: [timed] })
-    const view = render(<StatsLine {...props(source, { tokenUsage: tokenUsage(9_995, 5) })} t={t} />)
-    expect(view.container.textContent)
-      .toBe('1 轮 · 1 步| LLM 3.8秒| 首 token 平均 0.8秒 · 20 tok/s| 缓存命中 99.95%| 输入 10K tok · 输出 1 tok')
+  it('closes the dialog on Escape or outside pointerdown', () => {
+    const { source } = makeSource({ nodes: [timedStep()] })
+    const view = render(<StatsPills {...props(source)} />)
+    const timePill = view.getAllByRole('button')[0]!
+
+    fireEvent.click(timePill)
+    expect(view.queryByRole('dialog')).toBeTruthy()
+    fireEvent.keyDown(document, { key: 'Escape' })
+    expect(view.queryByRole('dialog')).toBeNull()
+    expect(timePill.getAttribute('aria-expanded')).toBe('false')
+
+    fireEvent.click(timePill)
+    // A pointerdown inside the panel keeps it open; one outside closes it.
+    fireEvent.pointerDown(view.getByRole('dialog'))
+    expect(view.queryByRole('dialog')).toBeTruthy()
+    fireEvent.pointerDown(document.body)
+    expect(view.queryByRole('dialog')).toBeNull()
   })
 
-  it('renders without ResizeObserver support', () => {
-    vi.unstubAllGlobals()
-    const { source } = makeSource({ nodes: [assistant(1, 1)] })
-    expect(() => render(<StatsLine {...props(source)} />)).not.toThrow()
+  it('keeps at most one dialog open: a sibling pill click swaps, never stacks', () => {
+    const { source } = makeSource({ nodes: [timedStep()] })
+    const view = render(<StatsPills {...props(source)} />)
+    const [timePill, usagePill] = [...view.getAllByRole('button')] as [HTMLElement, HTMLElement]
+
+    fireEvent.click(timePill)
+    expect(view.getByRole('dialog').getAttribute('aria-label')).toBe('Session statistics')
+    fireEvent.click(usagePill)
+    const dialogs = view.getAllByRole('dialog')
+    expect(dialogs).toHaveLength(1)
+    expect(dialogs[0]!.getAttribute('aria-label')).toBe('Token usage')
+    expect(timePill.getAttribute('aria-expanded')).toBe('false')
+    expect(usagePill.getAttribute('aria-expanded')).toBe('true')
   })
 
-  it('keeps durable token groups after the visible step window is empty', () => {
+  it('takes every pill and dialog label from the active locale', () => {
+    const { source } = makeSource({ nodes: [timedStep()] })
+    const view = render(<StatsPills {...props(source, { tokenUsage: tokenUsage(9_995, 5) })} t={t} />)
+    const [timePill, usagePill] = [...view.getAllByRole('button')] as [HTMLElement, HTMLElement]
+    expect(timePill.textContent).toBe('1 轮 1 步·20 tok/s')
+    // Whole-log total 9995 + 5 + 1 compacts to 10K.
+    expect(usagePill.textContent).toBe('10K tok·缓存命中 99.95%')
+    fireEvent.click(timePill)
+    const timeDialog = view.getByRole('dialog')
+    expect(timeDialog.getAttribute('aria-label')).toBe('会话统计')
+    expect(timeDialog.textContent).toContain('模型用时3.8秒')
+    expect(timeDialog.textContent).toContain('首 token 平均（TTFT）0.8秒')
+    expect(timeDialog.textContent).toContain('输出速度（TPS）20 tok/s')
+    fireEvent.keyDown(document, { key: 'Escape' })
+    fireEvent.click(usagePill)
+    const usageDialog = view.getByRole('dialog')
+    expect(usageDialog.getAttribute('aria-label')).toBe('Token 用量')
+    expect(usageDialog.textContent).toContain('未缓存输入5 tok')
+  })
+
+  it('keeps the durable usage pill after the visible step window is empty', () => {
     const { source } = makeSource()
-    const view = render(<StatsLine {...props(source, {
+    const view = render(<StatsPills {...props(source, {
       tokenUsage: USAGE,
       contextPressure: { pressureTokens: 32_000, contextWindow: 128_000 },
     })} />)
     // Context occupancy lives on the composer's ContextMeter ring, not here.
-    expect(view.container.textContent)
-      .toBe('Cache hit 90%| Input 100 tok · Output 5 tok')
+    const pills = view.getAllByRole('button')
+    expect(pills).toHaveLength(1)
+    expect(pills[0]!.textContent).toBe('105 tok·Cache hit 90%')
   })
 
-  it('drops every token group when no projection is composed', () => {
+  it('drops the usage pill when no projection is composed', () => {
     const { source } = makeSource({ nodes: [assistant(1, 1)] })
-    const view = render(<StatsLine {...props(source, {})} />)
-    expect(view.container.textContent).toBe('1 turns · 1 steps')
+    const view = render(<StatsPills {...props(source, {})} />)
+    expect(view.container.textContent).toBe('1 turns 1 steps')
+    // The untimed window has no dialog rows either, so no button renders at all.
+    expect(view.queryAllByRole('button')).toHaveLength(0)
   })
 
   it('renders whole-session counts from the sessionStats projection over the paged window', () => {
     // The bug's acceptance at unit level: one loaded page must not scope the
     // counter — the durable projection's totals win over the window fold.
     const { source } = makeSource({ nodes: [assistant(1, 1)] })
-    const view = render(<StatsLine {...props(source, {
+    const view = render(<StatsPills {...props(source, {
       tokenUsage: USAGE,
       sessionStats: sessionStats({ turns: 10, steps: 89 }),
     })} />)
-    expect(view.container.textContent)
-      .toBe('10 turns · 89 steps| Cache hit 90%| Input 100 tok · Output 5 tok')
+    expect(view.getByText('10 turns 89 steps')).toBeTruthy()
   })
 
   it('treats a defined zero-count projection as empty, not as fallback', () => {
     // A composed unit always serves the key; all-zero genuinely means no
     // closed step in the whole log, so nothing renders on a brand-new session.
     const empty = makeSource()
-    const view = render(<StatsLine {...props(empty.source, {
+    const view = render(<StatsPills {...props(empty.source, {
       tokenUsage: { uncachedInputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 },
       sessionStats: sessionStats({}),
     })} />)
     expect(view.container.textContent).toBe('')
   })
 
-  it('hides the zero-token group when steps closed without any billed activity', () => {
+  it('hides the usage pill when steps closed without any billed activity', () => {
     // A session whose only turn failed before billing (e.g. an auth error):
-    // the counts group renders alone, not an uninformative zero-token group.
+    // the counts pill renders alone, not an uninformative zero-token pill.
     const { source } = makeSource()
-    const view = render(<StatsLine {...props(source, {
+    const view = render(<StatsPills {...props(source, {
       tokenUsage: { uncachedInputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 },
       sessionStats: sessionStats({ turns: 1, steps: 1 }),
     })} />)
-    expect(view.container.textContent).toBe('1 turns · 1 steps')
+    expect(view.container.textContent).toBe('1 turns 1 steps')
+    expect(view.queryAllByRole('button')).toHaveLength(0)
   })
 
-  it('keeps the counts group over an empty visible window when the projection carries totals', () => {
+  it('keeps the counts pill over an empty visible window when the projection carries totals', () => {
     // Extends the durable-groups guarantee: full-session counts survive a
     // window that compaction (or paging) left without assistant nodes.
     const { source } = makeSource()
-    const view = render(<StatsLine {...props(source, {
+    const view = render(<StatsPills {...props(source, {
       tokenUsage: USAGE,
       sessionStats: sessionStats({ turns: 7, steps: 44 }),
     })} />)
-    expect(view.container.textContent)
-      .toBe('7 turns · 44 steps| Cache hit 90%| Input 100 tok · Output 5 tok')
+    expect(view.getByText('7 turns 44 steps')).toBeTruthy()
   })
 
-  it('renders whole-log wall times and speeds from the projection, not the loaded window', () => {
-    // The 加载更早 hazard beyond counts: LLM/tool durations and the TTFT and
-    // throughput figures must not grow per loaded page either. An untimed
-    // 1-node window renders the projection's whole-log figures verbatim.
+  it('renders whole-log speed and dialog figures from the projection, not the loaded window', () => {
+    // The 加载更早 hazard beyond counts: the pill's speed segment and the
+    // dialog's time split, TTFT, and throughput must not grow per loaded page
+    // either. An untimed 1-node window renders the projection's whole-log figures.
     const { source } = makeSource({ nodes: [assistant(1, 1)] })
-    const view = render(<StatsLine {...props(source, {
+    const view = render(<StatsPills {...props(source, {
       tokenUsage: USAGE,
       sessionStats: sessionStats({
         turns: 200, steps: 200, llmMs: 100_000, toolMs: 62_000,
         ttftMs: 1_600, ttftSteps: 2, decodeMs: 3_000, decodeTokens: 60,
       }),
     })} />)
-    expect(view.container.textContent).toBe(
-      '200 turns · 200 steps| LLM 1m40s · Tool call 1m2s| TTFT avg 0.8s · 20 tok/s| Cache hit 90%| Input 100 tok · Output 5 tok',
-    )
+    const timePill = view.getAllByRole('button')[0]!
+    expect(timePill.textContent).toBe('200 turns 200 steps·20 tok/s')
+    fireEvent.click(timePill)
+    const dialog = view.getByRole('dialog')
+    expect(dialog.textContent).toContain('LLM time1m40s')
+    expect(dialog.textContent).toContain('Tool time1m2s')
+    expect(dialog.textContent).toContain('Avg time to first token (TTFT)0.8s')
+    expect(dialog.textContent).toContain('Tokens per second (TPS)20 tok/s')
   })
 
-  it('omits cache hit when nothing was billed on the input side', () => {
+  it('omits the cache-hit segment when nothing was billed on the input side', () => {
     const { source } = makeSource({ nodes: [assistant(1, 1)] })
-    const view = render(<StatsLine {...props(source, {
+    const view = render(<StatsPills {...props(source, {
       tokenUsage: { uncachedInputTokens: 0, outputTokens: 7, cacheReadTokens: 0, cacheWriteTokens: 0 },
     })} />)
-    expect(view.container.textContent).toBe('1 turns · 1 steps| Input 0 tok · Output 7 tok')
+    const usagePill = view.getAllByRole('button')[0]!
+    expect(usagePill.textContent).toBe('7 tok')
+    expect(usagePill.getAttribute('aria-label')).toBe('7 tok')
+    // Output-only activity still fills the dialog's token rows.
+    fireEvent.click(usagePill)
+    expect(view.getByRole('dialog').textContent).toContain('Output7 tok')
   })
 
-  it('includes cache writes in billed input and the cache-hit denominator', () => {
+  it('includes cache writes in the total and the cache-hit denominator', () => {
     const { source } = makeSource({ nodes: [assistant(1, 1)] })
-    const view = render(<StatsLine {...props(source, {
+    const view = render(<StatsPills {...props(source, {
       tokenUsage: {
         uncachedInputTokens: 10,
         outputTokens: 7,
@@ -368,16 +427,15 @@ describe('StatsLine', () => {
         cacheWriteTokens: 100,
       },
     })} />)
-    expect(view.container.textContent)
-      .toBe('1 turns · 1 steps| Cache hit 45%| Input 200 tok · Output 7 tok')
+    expect(view.getAllByRole('button')[0]!.textContent).toBe('207 tok·Cache hit 45%')
   })
 
   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: StatsLineProps) {
+    function Counting(p: StatsPillsProps) {
       renders += 1
-      return <StatsLine {...p} />
+      return <StatsPills {...p} />
     }
     render(<Counting {...props(source)} />)
     const before = renders
diff --git a/packages/client/ui-chat/tests/chat-store.client.spec.ts b/packages/client/ui-chat/tests/chat-store.client.spec.ts
index 2be88ae9b8..fb0f330821 100644
--- a/packages/client/ui-chat/tests/chat-store.client.spec.ts
+++ b/packages/client/ui-chat/tests/chat-store.client.spec.ts
@@ -2,28 +2,6 @@ import { describe, expect, it } from 'vitest'
 import { createChatStore } from '../src/client/stores.ts'
 
 describe('createChatStore', () => {
-  it('starts without a selected Chat target', () => {
-    const store = createChatStore().create()
-    expect(store.store.getSnapshot()).toEqual({ selection: null, turnProcesses: [] })
-  })
-
-  it('selects and clears one Chat details target', () => {
-    const store = createChatStore().create()
-    store.actions.select({ turnSeq: 3, callId: 'c1', toolName: 'bash' })
-    expect(store.store.getSnapshot().selection)
-      .toEqual({ turnSeq: 3, callId: 'c1', toolName: 'bash' })
-    store.actions.select(null)
-    expect(store.store.getSnapshot().selection).toBeNull()
-  })
-
-  it('creates independent instances', () => {
-    const handle = createChatStore()
-    const first = handle.create()
-    const second = handle.create()
-    first.actions.select({ turnSeq: 1 })
-    expect(second.store.getSnapshot().selection).toBeNull()
-  })
-
   it('stores only manually expanded Turn-process answers', () => {
     const store = createChatStore().create()
     store.actions.setTurnProcessOpen(2, 3, true)
diff --git a/packages/client/ui-chat/tests/chat-view.client.spec.tsx b/packages/client/ui-chat/tests/chat-view.client.spec.tsx
index 074ae15330..7b72d280dc 100644
--- a/packages/client/ui-chat/tests/chat-view.client.spec.tsx
+++ b/packages/client/ui-chat/tests/chat-view.client.spec.tsx
@@ -1,12 +1,13 @@
 // @vitest-environment jsdom
 
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react'
 import { useEffect } from 'react'
 import type {
   AssistantMessageNode, ChatNode, ChatNodeOwnerProps, ChatNodeViewProps, ChatSnapshot,
   ChatViewSlotProps, CommandNode, CompactionSummaryNode, ContextMessageNode, ConversationNode,
-  LegacyConversationSlice, ModelRetryNode, RunningToolCall, SelectionTarget, SteeringMessageNode,
+  LegacyConversationSlice, ModelRetryNode, RunningToolCall, SteeringMessageNode,
   ToolCallBlock, ToolResultNode, TurnErrorNode, TurnMaxTokensNode, UseChatNodeTurnData,
   TranscriptViewMode, UserMessageNode,
 } from '@deepseek-ai/dsh-client-ui-chat/client'
@@ -43,6 +44,9 @@ import { ChatSnapshotBuilder } from '../src/client/conversation-nodes/chat-snaps
 import type { TurnProcessSpec } from '../src/client/contract/turn-process.ts'
 import { chatSnapshotFixture } from './chat-snapshot-fixture.client.ts'
 
+// Every session-scope fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 afterEach(() => {
   cleanup()
   vi.unstubAllGlobals()
@@ -245,7 +249,6 @@ function makeHarness(
   const useChatNodeProcess = bindKeyedSnapshotSelector(
     key => chatSource.source.getSnapshot().nodes.processSource(key),
   )
-  const openDetails = vi.fn<(t: SelectionTarget) => void>()
   const openFile = vi.fn<(path: string) => Promise<void>>().mockResolvedValue(undefined)
   const loadOlder = vi.fn()
   const loadThrough = vi.fn<(seq: number) => Promise<void>>().mockResolvedValue(undefined)
@@ -267,7 +270,6 @@ function makeHarness(
     callId: string
     toolName: string
     block: ToolCallBlock
-    selectedCallId: string | undefined
     openFile: ChatNodeOwnerProps['openFile']
     inspectCall: ChatNodeOwnerProps['inspectCall']
   }> = []
@@ -339,7 +341,6 @@ function makeHarness(
           callId: block.callId,
           toolName,
           block,
-          selectedCallId: nodeOwner.selectedCallId,
           openFile: nodeOwner.openFile,
           inspectCall: nodeOwner.inspectCall,
         }
@@ -371,6 +372,7 @@ function makeHarness(
     useConversation: bindSnapshotSelector(createSnapshotStore(EMPTY_CONVERSATION_SNAPSHOT)),
     useTrajectory: (() => { throw new Error('unused') }),
     useSessions: emptySessions(),
+    useResource,
     useSessionPendingInteraction: bindSnapshotSelector(
       createSnapshotStore<SessionPendingInteractionSnapshot>(new Map()),
     ),
@@ -392,7 +394,6 @@ function makeHarness(
     viewRequest: null,
     openView,
     completeViewRequest: () => {},
-    openDetails,
     openFile,
     loadOlder,
     loadThrough,
@@ -421,12 +422,11 @@ function makeHarness(
     }
     session.set(sessionUpdate)
   }
-  const setSelection = (next: SelectionTarget | null): void => { chat.actions.select(next) }
   return {
     set, setSession: session.set, setChat: chatSource.set, ChatView, props,
-    openDetails, openFile, loadOlder, loadThrough, openView,
+    openFile, loadOlder, loadThrough, openView,
     setOutline: (value: unknown) => { outlineValue = value },
-    chatScroll, forkAt, setSelection, toolOwners,
+    chatScroll, forkAt, toolOwners,
     setTranscriptView: (mode: TranscriptViewMode) => { transcriptView.set(mode) },
     setNodeRenderer: (renderer: React.ComponentProps<typeof ChatNodeSeat>['renderSlot']) => {
       nodeSlotOverride = renderer
@@ -564,7 +564,7 @@ describe('ChatView', () => {
     const afterMount = railRenders
     expect(afterMount).toBeGreaterThan(0)
 
-    act(() => { h.setSelection({ turnSeq: 3, callId: 'a', toolName: 'bash' }) })
+    act(() => { h.setTranscriptView('compact') })
 
     expect(railRenders).toBe(afterMount)
   })
@@ -2083,14 +2083,6 @@ describe('ChatView', () => {
     expect(rowRenders).toBe(afterMount)
   })
 
-  it('updates the selected call id handed to the Tool seat', () => {
-    const h = makeHarness({ nodes: [toolResult(3, 'a')] })
-    render(<h.ChatView {...h.props} />)
-    expect(h.toolOwners.at(-1)?.selectedCallId).toBeUndefined()
-    act(() => { h.setSelection({ turnSeq: 3, callId: 'a', toolName: 'bash' }) })
-    expect(h.toolOwners.at(-1)?.selectedCallId).toBe('a')
-  })
-
   it('hands running calls to a live Tool group', () => {
     const h = makeHarness({ runningCalls: [runningCall('r1')] }, { running: true })
     const view = render(<h.ChatView {...h.props} />)
@@ -2183,7 +2175,7 @@ describe('ChatView', () => {
     expect(calls).toHaveLength(1)
     expect(calls[0]).toMatchObject({
       key: 'conversation.chat.node',
-      owner: { node: { kind: 'tool-call' }, selectedCallId: undefined },
+      owner: { node: { kind: 'tool-call' } },
       entryKey: 'tool-call',
     })
     const owner = calls[0]?.owner as RoutedChatNodeOwner
@@ -2243,18 +2235,6 @@ describe('ChatView', () => {
     })
   })
 
-  it('names a workspace-folder Host refusal as a folder', async () => {
-    const openFile = vi.fn<(path: string) => Promise<void>>()
-      .mockRejectedValueOnce(new Error(''))
-    const h = makeHarness({ nodes: [toolResult(3, 'a')] })
-    h.props.openFile = openFile
-    render(<h.ChatView {...h.props} />)
-    await act(async () => { h.toolOwners[0]!.openFile('.') })
-    await waitFor(() => {
-      expect(screen.getByRole('dialog', { name: '无法打开文件夹' }).textContent).toContain('无法打开此文件夹')
-    })
-  })
-
   it('ignores a Host refusal that settles after the dialog is dismissed', async () => {
     let rejectRetry!: (error: unknown) => void
     const openFile = vi.fn<(path: string) => Promise<void>>()
diff --git a/packages/client/ui-chat/tests/gate-branch-tails.client.spec.tsx b/packages/client/ui-chat/tests/gate-branch-tails.client.spec.tsx
index 9f7d3dd062..a778ba7bfb 100644
--- a/packages/client/ui-chat/tests/gate-branch-tails.client.spec.tsx
+++ b/packages/client/ui-chat/tests/gate-branch-tails.client.spec.tsx
@@ -1,82 +1,22 @@
 // @vitest-environment jsdom
 
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, render } from '@testing-library/react'
 import { bindSnapshotSelector, makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
-import type {
-  SessionListState, SessionSnapshot,
-} from '@deepseek-ai/dsh-api-session-controller/client'
-import type { WorkspaceSnapshot } from '@deepseek-ai/dsh-api-workspace-controller/client'
-import type { SessionId } from '@deepseek-ai/dsh-session/types'
-import type { SessionProviderComponent } from '@deepseek-ai/dsh-client-ui-slots'
-import type { SessionPendingInteractionSnapshot } from '@deepseek-ai/dsh-client-ui-session/client'
-import { EMPTY_CONVERSATION_SNAPSHOT } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import type {
-  DetailsSlotProps, DetailsToolOwnerProps, RunningToolCall, SelectionTarget,
-} from '@deepseek-ai/dsh-client-ui-chat/client'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
-import { createChatStore } from '../src/client/stores.ts'
 import { AssistantMarkdown, type AssistantMarkdownProps } from '../src/client/chat/AssistantMarkdown.tsx'
-import { StatsLine } from '../src/client/chat/StatsLine.tsx'
-import { DetailsPanel } from '../src/client/details/DetailsPanel.tsx'
+import { StatsPills } from '../src/client/chat/StatsPills.tsx'
 import { zh } from '../src/client/locale.ts'
 import { chatSnapshotFixture } from './chat-snapshot-fixture.client.ts'
 
 const t: AssistantMarkdownProps['t'] = makeTranslate(zh, commonZh)
 const renderMessageImages: AssistantMarkdownProps['renderMessageImages'] = () => null
 
-/** jsdom has no ResizeObserver; StatsLine watches its row for ellipsis truncation through one. */
-class ResizeObserverStub {
-  observe(): void {}
-  unobserve(): void {}
-  disconnect(): void {}
-}
-
-beforeEach(() => { vi.stubGlobal('ResizeObserver', ResizeObserverStub) })
 afterEach(() => {
   cleanup()
   vi.unstubAllGlobals()
 })
 
-const SID = 's1' as SessionId
-
-/** Minimal framework seat for direct DetailsPanel host tests. */
-const SessionProviderStub: SessionProviderComponent = ({ children }) => children
-
-/** Observe the owner currency without importing the Tool details renderer. */
-function renderToolDetailsProbe(owners?: DetailsToolOwnerProps[]): DetailsSlotProps['renderSlot'] {
-  return (_key, owner) => {
-    owners?.push(owner as unknown as DetailsToolOwnerProps)
-    return <div data-testid="tool-details-seat" />
-  }
-}
-
-function sessionSnapshot(): SessionSnapshot {
-  return {
-    sessionId: SID,
-    queue: [],
-    pendingSubmissions: [],
-    running: false,
-    removed: false,
-    openState: 'open',
-    openError: null,
-    hasMore: false,
-    loadingOlder: false,
-    promptError: null,
-    blank: false,
-    subagent: null,
-    lastAgentError: null,
-    promptAttempted: true,
-    awaitingFirstTurn: false,
-  }
-}
-
-function emptyWorkspaces() {
-  return createSnapshotStore<WorkspaceSnapshot>({
-    items: [], archivedSessionIds: [], state: 'idle', phase: 'ready', error: null,
-  })
-}
 
 describe('render branch tails', () => {
   it('AssistantMarkdown reasoning row is ok-state when not the streaming tail', () => {
@@ -92,7 +32,7 @@ describe('render branch tails', () => {
     expect(view.container.querySelector('[data-state="ok"]')).not.toBeNull()
   })
 
-  it('StatsLine falls back to window-node counts and drops every token group without projections', () => {
+  it('StatsPills falls back to window-node counts and drops the usage pill without projections', () => {
     // No sessionStats key → the window fold supplies the counts (the
     // assembly-without-the-unit fallback). Node `usage` is deliberately
     // ignored: billing rides the durable tokenUsage projection, so an absent
@@ -105,13 +45,15 @@ describe('render branch tails', () => {
     const snap = chatSnapshotFixture({ nodes })
     const source = { getSnapshot: () => snap, subscribe: () => () => {} }
     const view = render(
-      <StatsLine
+      <StatsPills
         t={t}
         useChat={bindSnapshotSelector(source)}
         useProjection={() => undefined}
       />,
     )
-    expect(view.container.textContent).toBe('2 轮 · 3 步')
+    expect(view.container.textContent).toBe('2 轮 3 步')
+    // Window-fold counts carry no timed figure, so the pill is a static reading.
+    expect(view.queryAllByRole('button')).toHaveLength(0)
   })
 
   it('AssistantMarkdown reasoning as the streaming tail renders the running ring', () => {
@@ -126,116 +68,4 @@ describe('render branch tails', () => {
     expect(view.container.querySelector('[data-state="running"]')).not.toBeNull()
   })
 
-  it('DetailsPanel title falls to 详情 when the selection has no toolName and no material', () => {
-    localStorage.clear()
-    const session = sessionSnapshot()
-    const chatSnapshot = chatSnapshotFixture()
-    const chat = createChatStore().create()
-    chat.actions.select({ turnSeq: 1, callId: 'ghost' } satisfies SelectionTarget)
-    const emptyList = createSnapshotStore<SessionListState>(
-      { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined })
-    const workspaces = emptyWorkspaces()
-    const view = render(
-      <DetailsPanel
-        SessionProvider={SessionProviderStub}
-        renderSlot={renderToolDetailsProbe()}
-        sessionId={SID}
-        useSession={bindSnapshotSelector(createSnapshotStore(session))}
-        useChat={bindSnapshotSelector(createSnapshotStore(chatSnapshot))}
-        useConversation={bindSnapshotSelector(createSnapshotStore(EMPTY_CONVERSATION_SNAPSHOT))}
-        useTrajectory={(() => { throw new Error('unused') })}
-        useSessions={bindSnapshotSelector(emptyList)}
-        useSessionPendingInteraction={bindSnapshotSelector(
-          createSnapshotStore<SessionPendingInteractionSnapshot>(new Map()),
-        )}
-        useWorkspaces={bindSnapshotSelector(workspaces)}
-        useProjection={(() => undefined)}
-        useInput={(() => { throw new Error('unused') })}
-        inputActions={{
-          setDraft: () => {},
-          addAttachments: () => true,
-          removeAttachment: () => {},
-          pruneAttachments: () => {},
-          submit: () => {},
-        }}
-        useStore={bindSnapshotSelector(chat)}
-        actions={chat.actions}
-        closeDetails={vi.fn()}
-        t={t}
-      />,
-    )
-    expect(view.getByText('详情')).toBeTruthy()
-    expect(view.getByText('该调用不在当前窗口内')).toBeTruthy()
-  })
-
-  it('DetailsPanel passes the existing parentCallId through to the Tool details seat', () => {
-    localStorage.clear()
-    const session = sessionSnapshot()
-    const longText = 'x'.repeat(1_000)
-    const runningCalls: readonly RunningToolCall[] = [{
-      callId: 'p1', name: 'run_code', argsRaw: '{}', turn: 1, step: 1,
-      time: 7_000, subCalls: [{
-        kind: 'tool-result', seq: 8, time: 8_000, callId: 'p1:code:1',
-        parentCallId: 'p1',
-        call: { name: 'run_code', argsRaw: '{"code":"return 1"}' },
-        callTime: 8_000,
-        content: [], isError: false,
-        subCalls: [{
-          kind: 'tool-result', seq: 9, time: 9_000, callId: 'p1:code:1:code:1',
-          parentCallId: 'p1:code:1',
-          call: { name: 'read', argsRaw: '{"path":"notes/demo.txt"}' },
-          callTime: 8_500,
-          content: [{ type: 'text', text: longText }], isError: false,
-          subCalls: [],
-        }],
-      }],
-    }]
-    const chatSnapshot = chatSnapshotFixture({ runningCalls })
-    const chat = createChatStore().create()
-    chat.actions.select({ turnSeq: 9, callId: 'p1:code:1:code:1', toolName: 'read' } satisfies SelectionTarget)
-    const emptyList = createSnapshotStore<SessionListState>(
-      { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined })
-    const workspaces = emptyWorkspaces()
-    const owners: DetailsToolOwnerProps[] = []
-    const view = render(
-      <DetailsPanel
-        SessionProvider={SessionProviderStub}
-        renderSlot={renderToolDetailsProbe(owners)}
-        sessionId={SID}
-        useSession={bindSnapshotSelector(createSnapshotStore(session))}
-        useChat={bindSnapshotSelector(createSnapshotStore(chatSnapshot))}
-        useConversation={bindSnapshotSelector(createSnapshotStore(EMPTY_CONVERSATION_SNAPSHOT))}
-        useTrajectory={(() => { throw new Error('unused') })}
-        useSessions={bindSnapshotSelector(emptyList)}
-        useSessionPendingInteraction={bindSnapshotSelector(
-          createSnapshotStore<SessionPendingInteractionSnapshot>(new Map()),
-        )}
-        useWorkspaces={bindSnapshotSelector(workspaces)}
-        useProjection={(() => undefined)}
-        useInput={(() => { throw new Error('unused') })}
-        inputActions={{
-          setDraft: () => {},
-          addAttachments: () => true,
-          removeAttachment: () => {},
-          pruneAttachments: () => {},
-          submit: () => {},
-        }}
-        useStore={bindSnapshotSelector(chat)}
-        actions={chat.actions}
-        closeDetails={vi.fn()}
-        t={t}
-      />,
-    )
-    // Chat resolves the selected sub-call and keeps its Code Dispatch parent
-    // identity on the block handed to the Tool-owned details seat.
-    expect(view.getByText('read')).toBeTruthy()
-    expect(view.getByTestId('tool-details-seat')).toBeTruthy()
-    expect(owners).toHaveLength(1)
-    expect(owners[0]?.block).toMatchObject({
-      callId: 'p1:code:1:code:1',
-      parentCallId: 'p1:code:1',
-      call: { name: 'read', argsRaw: '{"path":"notes/demo.txt"}' },
-      content: [{ type: 'text', text: longText }],
-    })
-  })
 })
diff --git a/packages/client/ui-chat/tests/reasoning-row.client.spec.tsx b/packages/client/ui-chat/tests/reasoning-row.client.spec.tsx
index 4b32f77119..439b79bc7a 100644
--- a/packages/client/ui-chat/tests/reasoning-row.client.spec.tsx
+++ b/packages/client/ui-chat/tests/reasoning-row.client.spec.tsx
@@ -70,6 +70,34 @@ describe('ReasoningRow', () => {
     expect(row.getAttribute('aria-expanded')).toBe('false')
   })
 
+  it.each([
+    {
+      label: 'settled',
+      text: '**Comparing checkout and merge bases**\nKeep **reviewing**',
+      streaming: false,
+    },
+    {
+      label: 'streaming',
+      text: 'Inspect the session\n**Comparing checkout and merge bases**',
+      streaming: true,
+    },
+  ])('strips double-asterisk markers from the $label summary without changing the reasoning body', ({ text, streaming }) => {
+    const view = render(
+      <AssistantMarkdown
+        t={t}
+        blocks={[{ kind: 'reasoning', text }]}
+        streaming={streaming}
+        renderMessageImages={renderMessageImages}
+      />,
+    )
+
+    expect(view.getByText('Comparing checkout and merge bases')).toBeTruthy()
+    expect(view.queryByText('**Comparing checkout and merge bases**')).toBeNull()
+
+    fireEvent.click(view.getByText('思考'))
+    expect(view.container.querySelector('[class*="thinkBody"]')?.textContent).toBe(text)
+  })
+
   it('expanded Think drops the inline summary and renders plain prose, no IN card', () => {
     const view = render(
       <AssistantMarkdown
diff --git a/packages/client/ui-chat/tests/selection-survival.client.spec.tsx b/packages/client/ui-chat/tests/selection-survival.client.spec.tsx
deleted file mode 100644
index 3da452f418..0000000000
--- a/packages/client/ui-chat/tests/selection-survival.client.spec.tsx
+++ /dev/null
@@ -1,79 +0,0 @@
-// @vitest-environment jsdom
-/** Exercises Chat selection through the real SlotRegistry store axis. */
-import { describe, expect, it } from 'vitest'
-import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
-import type { SessionId } from '@deepseek-ai/dsh-session/types'
-import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
-import { createChatStore } from '../src/client/stores.ts'
-
-const sid = (value: string): SessionId => value as SessionId
-
-type ChatInstance = ReturnType<ReturnType<typeof createChatStore>['create']>
-
-async function createBench() {
-  const runtime = await SlotTestRuntime.create()
-  const chat = createChatStore()
-  await runtime.root.declare({
-    'conversation.view': { kind: 'list', scope: 'session' },
-    'details': { kind: 'single', scope: 'session' },
-  }, (_props: PropsRenderSlots<'conversation.view' | 'details'>) => null)
-  runtime.slots.register({ name: 'conversation.view', id: 'chat', store: chat }, () => null)
-  runtime.slots.register({ name: 'details', store: chat }, () => null)
-  runtime.renderRoot()
-  return { runtime }
-}
-
-function storeFor(
-  current: Awaited<ReturnType<typeof createBench>>,
-  slot: 'conversation.view' | 'details',
-  sessionId: SessionId,
-): ChatInstance {
-  return current.runtime.storeOf(slot, sessionId) as ChatInstance
-}
-
-describe('Chat selection survives on its store seat', () => {
-  it('shares one instance between the Chat View and details panel', async () => {
-    const b = await createBench()
-    await b.runtime.sessions.add({ id: 's1' })
-    const chat = storeFor(b, 'conversation.view', sid('s1'))
-    const details = storeFor(b, 'details', sid('s1'))
-    chat.actions.select({ turnSeq: 3, callId: 'c1' })
-
-    expect(details).toBe(chat)
-    expect(details.store.getSnapshot().selection).toEqual({ turnSeq: 3, callId: 'c1' })
-    await b.runtime.dispose()
-  })
-
-  it('isolates Session instances and preserves identity across list projection updates', async () => {
-    const b = await createBench()
-    const oneId = sid('s1')
-    await b.runtime.sessions.add({ id: 's1' })
-    await b.runtime.sessions.add({ id: 's2' })
-    const one = storeFor(b, 'conversation.view', oneId)
-    const two = storeFor(b, 'conversation.view', sid('s2'))
-    one.actions.select({ turnSeq: 1, callId: 'a' })
-    two.actions.select({ turnSeq: 9, callId: 'z' })
-
-    await b.runtime.sessions.updateSummary(oneId, { displayTitle: 'projected' })
-
-    expect(storeFor(b, 'conversation.view', oneId)).toBe(one)
-    expect(one.store.getSnapshot().selection).toEqual({ turnSeq: 1, callId: 'a' })
-    expect(two.store.getSnapshot().selection).toEqual({ turnSeq: 9, callId: 'z' })
-    await b.runtime.dispose()
-  })
-
-  it('buries selection with the Session scope', async () => {
-    const b = await createBench()
-    await b.runtime.sessions.add({ id: 's1' })
-    const doomed = storeFor(b, 'conversation.view', sid('s1'))
-    doomed.actions.select({ turnSeq: 1 })
-
-    await b.runtime.sessions.remove('s1')
-
-    await b.runtime.sessions.add({ id: 's1' })
-    const reborn = storeFor(b, 'conversation.view', sid('s1'))
-    expect(reborn).not.toBe(doomed)
-    expect(reborn.store.getSnapshot()).toEqual({ selection: null, turnProcesses: [] })
-    await b.runtime.dispose()
-  })
-})
diff --git a/packages/client/ui-chat/tests/transcript-view-row.client.spec.tsx b/packages/client/ui-chat/tests/transcript-view-row.client.spec.tsx
index f946a28f1a..5aa8e31047 100644
--- a/packages/client/ui-chat/tests/transcript-view-row.client.spec.tsx
+++ b/packages/client/ui-chat/tests/transcript-view-row.client.spec.tsx
@@ -4,6 +4,7 @@ import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import type { SessionListState } from '@deepseek-ai/dsh-api-session-controller/client'
 import type { WorkspaceSnapshot } from '@deepseek-ai/dsh-api-workspace-controller/client'
 import type { SessionPendingInteractionSnapshot } from '@deepseek-ai/dsh-client-ui-session/client'
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { bindSnapshotSelector, makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { TranscriptViewRow, type TranscriptViewRowProps } from '../src/client/settings/TranscriptViewRow.tsx'
@@ -27,6 +28,9 @@ function noPendingInteraction() {
   return bindSnapshotSelector(createSnapshotStore<SessionPendingInteractionSnapshot>(new Map()))
 }
 
+// The resource hook the resources plugin merges into GlobalStandardProps; this row reads no address.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 function mount(mode: 'normal' | 'compact' = 'compact') {
   const source = createSnapshotStore(mode)
   const setTranscriptView = vi.fn((next: 'normal' | 'compact') => { source.set(next) })
@@ -34,6 +38,7 @@ function mount(mode: 'normal' | 'compact' = 'compact') {
     useSessions: emptySessions(),
     useSessionPendingInteraction: noPendingInteraction(),
     useWorkspaces: emptyWorkspaces(),
+    useResource,
     useTranscriptView: bindSnapshotSelector(source),
     setTranscriptView,
     t: makeTranslate(en),
diff --git a/packages/client/ui-chat/tests/views-type-chain.client.spec.tsx b/packages/client/ui-chat/tests/views-type-chain.client.spec.tsx
index 231c1520da..c617831691 100644
--- a/packages/client/ui-chat/tests/views-type-chain.client.spec.tsx
+++ b/packages/client/ui-chat/tests/views-type-chain.client.spec.tsx
@@ -9,10 +9,8 @@ describe('Chat View type chain', () => {
       base: ConvViewProps,
       chat: ChatViewSlotProps,
     ): ReactNode => {
-      // @ts-expect-error openDetails belongs to the Chat inject face.
-      void base.openDetails
-      // @ts-expect-error openDetails accepts a SelectionTarget.
-      chat.openDetails('nope')
+      // @ts-expect-error openFile belongs to the Chat inject face.
+      void base.openFile
       // @ts-expect-error openFile accepts a path.
       void chat.openFile({ turnSeq: 1, callId: 'c' })
       return null
diff --git a/packages/client/ui-chat/tsconfig.json b/packages/client/ui-chat/tsconfig.json
index 6ba550f2f1..b1ad52d680 100644
--- a/packages/client/ui-chat/tsconfig.json
+++ b/packages/client/ui-chat/tsconfig.json
@@ -86,6 +86,9 @@
     {
       "path": "../ui-session"
     },
+    {
+      "path": "../ui-sidebar-right"
+    },
     {
       "path": "../ui-settings"
     },
@@ -94,6 +97,9 @@
     },
     {
       "path": "../ui-workspace"
+    },
+    {
+      "path": "../ui-sidebar-textpreview"
     }
   ]
 }
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 15a81cc65b..d93d7d7dc5 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md
-README.md: 9a1a12ed86afe4d5ccea63045aeade5860f309cc
-README.zh.md: 372f24039a3c880520c2ad690a996754b2ed2e0b
+README.md: e06270a339a23fa17fb9d51642317fcf2aec6c0f
+README.zh.md: 315fd3d7798145df7dbb6f504fe7b89c64827024
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 9a1a12ed86..e06270a339 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -48,7 +48,7 @@ Default sends commit optimistically: Enter clears the draft, occurrence table, a
 
 Queued submission echoes show “Sending…” beside disabled edit, remove, and steer buttons; a collapsed dock keeps the sending status in its header. A matching Host queue row replaces the echo and enables each action according to its normal text-content and running-state requirements. Prompt acknowledgement alone does not enable queue actions. A failed submission removes its echo and displays an error; the composer restores the failed draft when it is empty or still contains the previous automatic restoration, preserving subsequently typed text.
 
-While a normal composer is running, its primary pointer action remains Stop when the draft is empty or input is unavailable. Actionable text or attachments switch the same seat to Queue Send; clearing or successfully submitting the draft restores Stop. The busy-Enter setting selects the Queue or Steer keyboard action for ordinary Sessions and continuable children. Their QueueDock rows share Edit, Remove, and Steer, and an empty draft shares the steer-all chord. One-shot children remain read-only. Plan mode and active goals do not change attachment intake. Continuable children keep separate Send and Stop actions but expose no paperclip, paste, or drop intake; if their parent is offline, Send and the composer gestures lock while QueueDock controls for the live inbox remain available ([decisions](../../../.agents/notes/archived/bug-fix/2026-08-20-running-draft-primary-send.md), [inbox controls](../../../.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.md)).
+While a normal composer is running, its primary pointer action remains Stop when the draft is empty or input is unavailable. Actionable text or attachments switch the same seat to Send; clearing or successfully submitting the draft restores Stop. The busy-Enter setting selects the Queue or Steer delivery for ordinary Sessions and continuable children, and the running Send button delivers through the same mode plain Enter resolves to; while it is enabled (no upload pending) over a plain message draft its label names that mode (Queue message or Steer message), so the setting governs Enter and the button together while Cmd/Ctrl+Enter still uses the other mode, and idle sessions, empty drafts, and `/` command lines keep the plain Send label ([decision](../../../.agents/notes/implemented/bug-fix/2026-09-04-busy-send-button-follows-enter-setting.md)). Their QueueDock rows share Edit, Remove, and Steer, and an empty draft shares the steer-all chord. One-shot children remain read-only. Plan mode and active goals do not change attachment intake. Continuable children keep separate Send and Stop actions but expose no paperclip, paste, or drop intake; if their parent is offline, Send and the composer gestures lock while QueueDock controls for the live inbox remain available ([decisions](../../../.agents/notes/archived/bug-fix/2026-08-20-running-draft-primary-send.md), [inbox controls](../../../.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.md)).
 
 <a id="temporary-composer-entries"></a>
 ## Temporary composer entries
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index 372f24039a..315fd3d779 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -48,7 +48,7 @@ Session 首次绑定或缓存的 Session 成为 current 时，shell 会在渲染
 
 排队提交的本地回显在禁用的编辑、删除、插话按钮旁显示“发送中…”；折叠后的队列在标题栏保留发送状态。匹配的 Host 队列行替换回显后，各操作按原有的纯文本内容和运行状态要求启用。仅收到 prompt 确认不会启用队列操作。提交失败会移除回显并显示错误；输入框为空或仍保留上一次自动恢复的内容时，composer 恢复失败草稿，保留用户随后输入的文字。
 
-普通 composer 运行时，如果草稿为空或输入不可用，主指针操作保持为 Stop。可提交的文字或附件会把同一位置切换为 Queue Send；清空或成功提交草稿后恢复 Stop。繁忙态 Enter 设置会为普通 Session 与可继续 child 选择 Queue 或 Steer 键盘操作。它们的 QueueDock 行共享 Edit、Remove 与 Steer，空草稿也共享 steer-all 组合键。One-shot child 继续只读。Plan Mode 与 active goal 不改变附件入口。可继续 child 保留独立的 Send 与 Stop 操作，但不提供回形针、粘贴或拖放入口；parent 离线时，Send 与 composer 手势锁定，但在线 inbox 的 QueueDock 控制仍可使用（[决策](../../../.agents/notes/archived/bug-fix/2026-08-20-running-draft-primary-send.md)、[inbox 控制](../../../.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.zh.md)）。
+普通 composer 运行时，如果草稿为空或输入不可用，主指针操作保持为 Stop。可提交的文字或附件会把同一位置切换为 Send；清空或成功提交草稿后恢复 Stop。繁忙态 Enter 设置为普通 Session 与可继续 child 选择 Queue 或 Steer 投递，运行中的 Send 按钮按 plain Enter 解析出的同一模式投递；当它在普通消息草稿上可用（没有待上传文件）时，其标签以该模式命名（排队发送或插话发送），因此该设置同时约束 Enter 与按钮，而 Cmd/Ctrl+Enter 仍使用另一模式；空闲会话、空草稿与 `/` 命令行保留普通的 Send 标签（[决策](../../../.agents/notes/implemented/bug-fix/2026-09-04-busy-send-button-follows-enter-setting.zh.md)）。它们的 QueueDock 行共享 Edit、Remove 与 Steer，空草稿也共享 steer-all 组合键。One-shot child 继续只读。Plan Mode 与 active goal 不改变附件入口。可继续 child 保留独立的 Send 与 Stop 操作，但不提供回形针、粘贴或拖放入口；parent 离线时，Send 与 composer 手势锁定，但在线 inbox 的 QueueDock 控制仍可使用（[决策](../../../.agents/notes/archived/bug-fix/2026-08-20-running-draft-primary-send.md)、[inbox 控制](../../../.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.zh.md)）。
 
 <a id="temporary-composer-entries"></a>
 ## 临时 composer entry
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index 9cc8f95758..65b8374919 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -279,6 +279,7 @@ export function apply(ctx: Context, config: Config = Config({})): void {
       'conversation.session.header.lineage': { kind: 'single', scope: 'session' },
       'conversation.session.header.actions': { kind: 'list', scope: 'session' },
       'conversation.session.header.utilities': { kind: 'list', scope: 'session' },
+      'conversation.session.header.corner': { kind: 'single', scope: 'session' },
     },
     store: conversationStore,
     inject: (sessionId: SessionId, actions: BoundActions<typeof conversationStore>): ConversationSessionHeaderInjected => ({
@@ -311,12 +312,11 @@ export function apply(ctx: Context, config: Config = Config({})): void {
           removeAttachment: undefined,
           resolveDraftAttachments: undefined,
           retryFileUpload: undefined,
-          resolveSubmitMode: (running, gesture, steeringAvailable) =>
-            submissionPolicy.resolve(running, gesture, steeringAvailable),
           toggleCommandMenu: undefined,
           stop: undefined,
           command: undefined,
           hooks: {
+            busyEnter: submissionPolicy.busyEnter,
             fileUploads: ABSENT_FILE_UPLOADS,
             notices: ABSENT_NOTICES,
             lexicon: ABSENT_LEXICON,
@@ -349,8 +349,6 @@ export function apply(ctx: Context, config: Config = Config({})): void {
         retryFileUpload: (id) => {
           if (sessions.binding(sessionId) !== undefined) conversation.retryFileUpload(sessionId, id)
         },
-        resolveSubmitMode: (running, gesture, steeringAvailable) =>
-          submissionPolicy.resolve(running, gesture, steeringAvailable),
         toggleCommandMenu: inputTriggers === undefined
           ? undefined
           : (selection) => {
@@ -376,6 +374,7 @@ export function apply(ctx: Context, config: Config = Config({})): void {
           return result.ok && result.value.matched
         },
         hooks: {
+          busyEnter: submissionPolicy.busyEnter,
           fileUploads: conversation.fileUploads,
           notices: shell.notices,
           lexicon: shell.lexicon,
diff --git a/packages/client/ui-conversation/src/client/contract/input.ts b/packages/client/ui-conversation/src/client/contract/input.ts
index 9d65d84f1f..e9659e0022 100644
--- a/packages/client/ui-conversation/src/client/contract/input.ts
+++ b/packages/client/ui-conversation/src/client/contract/input.ts
@@ -260,7 +260,7 @@ export interface ComposerKeyboard {
   readonly snapshot: InputState
   /** The shell-owned Lexical editor the composer binds its contenteditable to. */
   readonly editor: LexicalEditor
-  /** Submit with an explicit delivery mode resolved by the keyboard policy. */
+  /** Submit with an explicit delivery mode resolved by the submission policy (Enter gestures and the primary Send button). */
   submit(mode: InputSubmitMode): void
   /**
    * Steer every still-pending queued message into the running turn (the
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index 272d84b8e3..eb38a0f261 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -19,7 +19,7 @@ import type {
   ComposerKeyboard, DraftAttachmentId, EditSelection, InputActions, InputNotice, InputState,
 } from './input.ts'
 import type { createConversationStore } from '../stores.ts'
-import type { ComposerSubmitGesture, InputSubmitMode } from './composer-submission.ts'
+import type { BusyEnterBehavior } from './composer-submission.ts'
 import type { ConversationSnapshot } from './snapshot.ts'
 import type { ViewTab } from './views.ts'
 
@@ -139,6 +139,18 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
       scope: 'session'
       owner: ConversationHeaderActionOwnerProps
     }
+    /**
+     * The header's far-right corner, past the utilities' edge and into the
+     * header's own padding, for one control that must keep its place whether or
+     * not it currently shows anything. The corner reserves its width while an
+     * occupant is registered, so the utilities beside it never move; an
+     * occupant with nothing to show renders a same-size placeholder.
+     */
+    'conversation.session.header.corner': {
+      kind: 'single'
+      scope: 'session'
+      owner: ConversationHeaderCornerOwnerProps
+    }
     /** Registered Conversation target Views, rendered one at a time. */
     'conversation.view': { kind: 'list'; scope: 'session'; owner: ConvViewOwnerProps }
     /** Selector-routed replacements for the current Session's resident composer. */
@@ -209,6 +221,12 @@ export interface ConversationHeaderActionOwnerProps {
   children?: never
 }
 
+/** The header corner's occupant derives its state from standard Session props. */
+export interface ConversationHeaderCornerOwnerProps {
+  /** Marker field: the occupant receives no owner-specific values. */
+  children?: never
+}
+
 /** Plain breadcrumb data handed to the optional lineage renderer. */
 export interface ConversationHeaderLineageOwnerProps {
   /** Session represented by this breadcrumb title. */
@@ -291,15 +309,15 @@ export interface ComposerBarInjected {
   resolveDraftAttachments: ((ids: readonly DraftAttachmentId[]) => readonly ComposerAttachment[]) | undefined
   /** Restart one failed file upload; absent without a session. */
   retryFileUpload: ((id: DraftAttachmentId) => void) | undefined
-  resolveSubmitMode: (
-    running: boolean,
-    gesture: ComposerSubmitGesture,
-    steeringAvailable: boolean,
-  ) => InputSubmitMode
   toggleCommandMenu: ((selection: EditSelection) => void) | undefined
   stop: (() => void) | undefined
   command: ((line: string) => Promise<boolean>) | undefined
   hooks: {
+    /**
+     * Live busy-state submission preference: the delivery mode plain Enter
+     * and the primary Send button use while the addressed agent is busy.
+     */
+    busyEnter: ObservableSnapshot<BusyEnterBehavior>
     /** Live per-draft upload states for file-kind drafts. */
     fileUploads: ObservableSnapshot<DraftFileUploads>
     notices: ObservableSnapshot<InputNotice | null>
@@ -375,6 +393,7 @@ export type ConversationSessionHeaderSlotProps =
     'conversation.session.header.lineage'
     | 'conversation.session.header.actions'
     | 'conversation.session.header.utilities'
+    | 'conversation.session.header.corner'
   >
   & PropsStore<ConversationStore>
   & InjectFace<ConversationSessionHeaderInjected>
diff --git a/packages/client/ui-conversation/src/client/index.ts b/packages/client/ui-conversation/src/client/index.ts
index cad5ccfb44..3cbf676c88 100644
--- a/packages/client/ui-conversation/src/client/index.ts
+++ b/packages/client/ui-conversation/src/client/index.ts
@@ -51,7 +51,7 @@ export type {
   ComposerAttachment, ComposerAttachmentsOwnerProps, ComposerAttachmentsProps,
   ComposerFileAttachment, ComposerImageAttachment, DraftFileUpload, DraftFileUploads,
   ComposerBarInjected, ComposerBarOwnerProps, ComposerBarProps, ComposerChainProps,
-  ConversationHeaderActionOwnerProps, ConversationHeaderLineageOwnerProps,
+  ConversationHeaderActionOwnerProps, ConversationHeaderCornerOwnerProps, ConversationHeaderLineageOwnerProps,
   ConversationInjected, ConversationSessionHeaderInjected, ConversationSessionHeaderSlotProps,
   ConversationSessionInjected, ConversationSessionSlotProps, ConversationSlotProps,
   ConversationStore, ConvViewOwnerProps, ConvViewProps, EmptyWorkspaceOwnerProps,
diff --git a/packages/client/ui-conversation/src/client/input/submission-policy.ts b/packages/client/ui-conversation/src/client/input/submission-policy.ts
index 0b7f0ad4df..f48d5db494 100644
--- a/packages/client/ui-conversation/src/client/input/submission-policy.ts
+++ b/packages/client/ui-conversation/src/client/input/submission-policy.ts
@@ -1,7 +1,7 @@
 /**
- * Composer submission policy. It owns the live busy-Enter
- * preference and resolves keyboard gestures into queue/steer delivery modes;
- * Host and Agent keep the actual delivery-window authority.
+ * Composer submission policy. It owns the live busy-Enter preference and
+ * resolves submission gestures into queue/steer delivery modes; Host and
+ * Agent keep the actual delivery-window authority.
  */
 import {
   createSnapshotStore, type SnapshotStore,
@@ -16,12 +16,35 @@ import type { ConversationSettings } from '../../submission-settings.ts'
 export { DEFAULT_BUSY_ENTER_BEHAVIOR } from '../../submission-settings.ts'
 
 /**
- * Busy-Enter policy used by both the composer inject face and its Settings row.
- * Direct `steer` is intentionally best-effort: AgentLoop turns a closed-window
- * submission into the next waking Queue item.
+ * Resolve one submission gesture against the busy-Enter preference. Plain
+ * Enter and the primary Send button share the `enter` gesture, so the button
+ * delivers exactly what Enter would. Direct `steer` is intentionally
+ * best-effort: AgentLoop turns a closed-window submission into the next waking
+ * Queue item.
+ * @param preferred - the live busy-Enter preference.
+ * @param running - whether the addressed agent currently reports busy.
+ * @param gesture - plain Enter (or the Send button) or the Cmd/Ctrl-accelerated chord.
+ * @param steeringAvailable - whether this session transport supports steering.
+ * @returns Queue outside steer-capable busy state; otherwise the preferred mode or its opposite.
+ */
+export function resolveSubmitMode(
+  preferred: BusyEnterBehavior,
+  running: boolean,
+  gesture: ComposerSubmitGesture,
+  steeringAvailable: boolean,
+): InputSubmitMode {
+  if (!running || !steeringAvailable) return 'queue'
+  if (gesture === 'enter') return preferred
+  return preferred === 'queue' ? 'steer' : 'queue'
+}
+
+/**
+ * Busy-Enter preference shared by the composer bar inject face and its
+ * Settings row: one live store the bar's submission gestures and Send label
+ * read, backed by the Host user-settings document when one is composed.
  */
 export class ComposerSubmissionPolicy {
-  /** Reactive preference source for the Settings row. */
+  /** Reactive preference source for the composer bar and the Settings row. */
   readonly busyEnter: SnapshotStore<BusyEnterBehavior> = createSnapshotStore(DEFAULT_BUSY_ENTER_BEHAVIOR)
   private readonly host: SettingsScope<ConversationSettings> | undefined
 
@@ -40,26 +63,8 @@ export class ComposerSubmissionPolicy {
   }
 
   /**
-   * Resolve one keyboard gesture without changing state.
-   * @param running - whether the addressed agent currently reports busy.
-   * @param gesture - plain Enter or the Cmd/Ctrl-accelerated chord.
-   * @param steeringAvailable - whether this session transport supports steering.
-   * @returns Queue outside steer-capable busy state; otherwise the preferred mode or its opposite.
-   */
-  resolve(
-    running: boolean,
-    gesture: ComposerSubmitGesture,
-    steeringAvailable: boolean,
-  ): InputSubmitMode {
-    if (!running || !steeringAvailable) return 'queue'
-    const preferred = this.busyEnter.getSnapshot()
-    if (gesture === 'enter') return preferred
-    return preferred === 'queue' ? 'steer' : 'queue'
-  }
-
-  /**
-   * Change the plain-Enter behavior used during busy state; the live value
-   * publishes before the durable write starts.
+   * Change the busy-state submission behavior; the live value publishes
+   * before the durable write starts.
    * @param behavior - Queue or Steer.
    */
   setBusyEnter(behavior: BusyEnterBehavior): void {
diff --git a/packages/client/ui-conversation/src/client/locales.ts b/packages/client/ui-conversation/src/client/locales.ts
index 2369dafe4f..4aeb755983 100644
--- a/packages/client/ui-conversation/src/client/locales.ts
+++ b/packages/client/ui-conversation/src/client/locales.ts
@@ -13,15 +13,17 @@ export const zh = {
   'hint.goal': '输入目标，智能体将持续执行',
   'hint.goal.active': '当前目标进行中。可输入 edit 修改 / pause 暂停 / resume 继续 / clear 清除',
   'placeholder.plan': PLAN_NEXT_ACTION_ZH,
-  'placeholder.default': '发消息或做任务… / 调用指令 @ 文件或对话',
+  'placeholder.default': '发消息或创建任务, / 调用指令, @ 文件或对话',
   'placeholder.unavailable': '会话不可用',
   'placeholder.parentOffline': '父会话已离线，无法继续发送；仍可停止当前运行',
-  'placeholder.hero': '描述你想要构建的内容… / 调用指令 @ 文件或对话',
+  'placeholder.hero': '描述你想要构建的内容, / 调用指令, @ 文件或对话',
   'placeholder.workspace': '选择一个工作区开始',
   'placeholder.steerQueue': 'Cmd/Ctrl+Enter 插话发送全部排队消息',
   'input.commands': '指令',
   'input.stop': '停止生成',
   'input.send': '发送消息',
+  'input.send.queue': '排队发送',
+  'input.send.steer': '插话发送',
   'input.accessMode': '访问模式，当前：{name}',
   'attachment.pending': '待发送附件',
   'attachment.scrollLeft': '向左滚动附件',
@@ -60,10 +62,10 @@ export const zh = {
   'context.aria': '上下文已用 {percent}',
   'context.used': '上下文已用',
   'context.system': '系统提示词',
-  'context.tools': '工具',
+  'context.tools': '工具定义',
   'context.messages': '对话消息',
-  'settings.enter.title': '繁忙时 Enter 键行为',
-  'settings.enter.description': '仅在智能体运行时生效；Cmd/Ctrl+Enter 使用另一行为',
+  'settings.enter.title': '繁忙时的发送行为',
+  'settings.enter.description': '智能体运行时 Enter 键和发送按钮的行为；Cmd/Ctrl+Enter 使用另一行为',
   'settings.enter.queue': '排队发送',
   'settings.enter.steer': '插话发送',
   'access.preset.readOnly': '仅可查看',
@@ -177,15 +179,17 @@ export const en = {
   'hint.goal': 'describe the objective for a long-running task',
   'hint.goal.active': 'goal active — edit / pause / resume / clear',
   'placeholder.plan': PLAN_NEXT_ACTION_EN,
-  'placeholder.default': 'Message or run a task... / commands, @ files or sessions',
+  'placeholder.default': 'Message or run a task, / commands, @ files or sessions',
   'placeholder.unavailable': 'Session unavailable',
   'placeholder.parentOffline': 'Parent session offline; sending is unavailable but you can still stop the run',
-  'placeholder.hero': 'Describe what you want to build... / commands, @ files or sessions',
+  'placeholder.hero': 'Describe what you want to build, / commands, @ files or sessions',
   'placeholder.workspace': 'Choose a workspace to start',
   'placeholder.steerQueue': 'Cmd/Ctrl+Enter steers all queued messages',
   'input.commands': 'Commands',
   'input.stop': 'Stop generating',
   'input.send': 'Send message',
+  'input.send.queue': 'Queue message',
+  'input.send.steer': 'Steer message',
   'input.accessMode': 'Access mode, current: {name}',
   'attachment.pending': 'Pending attachments',
   'attachment.scrollLeft': 'Scroll attachments left',
@@ -224,10 +228,10 @@ export const en = {
   'context.aria': '{percent} of context used',
   'context.used': 'of context used',
   'context.system': 'System prompt',
-  'context.tools': 'Tools',
+  'context.tools': 'Tool definitions',
   'context.messages': 'Messages',
-  'settings.enter.title': 'Enter behavior while busy',
-  'settings.enter.description': 'Busy only; Cmd/Ctrl+Enter uses the other behavior',
+  'settings.enter.title': 'Send behavior while busy',
+  'settings.enter.description': 'What Enter and the Send button do while the agent is running; Cmd/Ctrl+Enter uses the other behavior',
   'settings.enter.queue': 'Queue',
   'settings.enter.steer': 'Steer',
   'access.preset.readOnly': 'Read Only',
diff --git a/packages/client/ui-conversation/src/client/skeleton/ContextMeter.tsx b/packages/client/ui-conversation/src/client/skeleton/ContextMeter.tsx
index 0caaf28cb8..dc63dac9e3 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ContextMeter.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/ContextMeter.tsx
@@ -135,6 +135,8 @@ export function ContextMeter({ useProjection, t }: ContextMeterProps) {
             <span className={css.headline}>{headBefore}</span>
             <span className={css.percent}>{reading}</span>
             <span className={css.headline}>{headAfter}</span>
+            {/* `~`: usedTokens prefers projectedTokens, whose surface delta is
+                heuristically repriced on top of the provider-anchored sample. */}
             <span className={css.figures}>
               {`~${formatTokens(context.usedTokens, t)} / ${formatTokens(context.contextWindow, t)}`}
             </span>
diff --git a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css
index e7d5af7840..f988537220 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css
@@ -146,6 +146,22 @@
   display: none;
 }
 
+/* The far-right corner seat reaches 16px into the header's 28px right padding,
+   so its control sits past the utilities' edge; it is laid out only while an
+   occupant is registered, and the occupant keeps its width while hidden, so the
+   utilities never move because of it. */
+.headerCorner {
+  display: flex;
+  flex: none;
+  align-items: center;
+  margin-left: 12px;
+  margin-right: -16px;
+}
+
+.headerCorner:empty {
+  display: none;
+}
+
 /* figma Tab_Group 34:11441: 35px strip, gap 36, pad-left 8, tabs bottom-aligned. */
 .tabs {
   position: relative;
@@ -433,9 +449,10 @@
   gap: 2px;
   min-width: 0;
   margin-top: 4px;
-  /* figma drew px 8; nudged +12 so the chip's folder glyph lines up closer to
-     the card's inner controls below. */
-  padding-left: 20px;
+  /* figma drew px 8; left nudged +12 so the chip's folder glyph lines up
+     closer to the card's inner controls below; right keeps the trailing
+     preset seat off the card edge. */
+  padding: 0 16px 0 20px;
 }
 
 /* Hero: the composer sits inside the session scroll body; center there so
diff --git a/packages/client/ui-conversation/src/client/skeleton/ConversationSession.tsx b/packages/client/ui-conversation/src/client/skeleton/ConversationSession.tsx
index ea7a3fe76f..803c53fc9a 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ConversationSession.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/ConversationSession.tsx
@@ -133,6 +133,9 @@ export function ConversationSessionHeader({
             <div className={css.headerUtilities}>
               {renderSlot('conversation.session.header.utilities', {})}
             </div>
+            <div className={css.headerCorner} data-conversation-header-corner="">
+              {renderSlot('conversation.session.header.corner', {})}
+            </div>
           </div>
           {tabs.length > 1 && (
             <div className={css.tabs} role="tablist">
diff --git a/packages/client/ui-conversation/src/client/skeleton/EmptyHero.tsx b/packages/client/ui-conversation/src/client/skeleton/EmptyHero.tsx
index 6c4820ed4f..9ac7ae573b 100644
--- a/packages/client/ui-conversation/src/client/skeleton/EmptyHero.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/EmptyHero.tsx
@@ -149,10 +149,11 @@ export function HeroShell({ t, renderSlot, children }: HeroShellProps) {
               fallback: <HeroFish hovering={hovering} />,
             })}
           </span>
-          <span className={css.headlineText}>
-            {t('hero.headline')}
+          <span className={css.titleGroup}>
+            {/* Own element: keeps the headline text addressable apart from the badge. */}
+            <span>{t('hero.headline')}</span>
+            <span className={css.previewBadge}>{t('hero.preview')}</span>
           </span>
-          <span className={css.previewBadge}>{t('hero.preview')}</span>
         </div>
         <div className={css.body}>
           {/* The composer remains mounted outside this component. */}
diff --git a/packages/client/ui-conversation/src/client/skeleton/HeroShell.module.css b/packages/client/ui-conversation/src/client/skeleton/HeroShell.module.css
index 6c5053e9c6..d47e0bfe2f 100644
--- a/packages/client/ui-conversation/src/client/skeleton/HeroShell.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/HeroShell.module.css
@@ -27,9 +27,15 @@
    badge is a product addition outside that source: a mono superscript pill
    riding the title's top-right. */
 .headline {
-  display: grid;
-  grid-template-columns: 34px auto auto;
+  display: flex;
+  /* Overflow-driven: the fish and the title group are two wrap units sharing
+     one centered line while they fit; squeezed, the fish takes its own line
+     above the group. No breakpoint. */
+  flex-wrap: wrap;
   column-gap: 10px;
+  /* Wrapped, the fish sits on its own line; more air than the 10px side gap
+     keeps it reading as a mark above the title, not a squeezed inline glyph. */
+  row-gap: 12px;
   align-items: center;
   justify-content: center;
   font-size: 26px;
@@ -38,17 +44,24 @@
   color: var(--dsw-alias-label-primary);
 }
 
-.headlineText {
-  grid-row: 1;
-  grid-column: 2;
+/* Title text + badge as one wrap unit so the title never breaks mid-text with
+   the badge stranded beside a fragment. When the badge no longer fits beside
+   the title it wraps to its own centered line below; while both fit, the group
+   is content-sized and centering is a no-op, keeping the superscript snug. */
+.titleGroup {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  align-items: center;
+  /* Superscript sits 7 from the title. */
+  column-gap: 7px;
+  row-gap: 4px;
+  min-width: 0;
 }
 
 .previewBadge {
-  grid-row: 1;
-  grid-column: 3;
-  align-self: start;
+  align-self: flex-start;
   margin-top: 2px;
-  margin-left: -3px;
   padding: 1px 7px 0;
   border: 0.5px solid var(--dsw-alias-interactive-bg-hover);
   border-radius: 24px;
@@ -64,9 +77,8 @@
 /* Keep hover detection on a stationary box while the mark moves within it;
    hover rules target the hitbox so a slot-occupant mark swims too. */
 .fishHitbox {
-  grid-row: 1;
-  grid-column: 1;
   display: inline-flex;
+  flex: none;
   align-items: center;
   justify-content: center;
 }
@@ -132,7 +144,10 @@
   padding-left: 8px;
 }
 
-/* Folder + label + chevron — transparent at rest; fill only on hover / open. */
+/* Folder + label + chevron — transparent at rest; fill only on hover / open.
+   Overflow-driven degradation, no breakpoint: the label shrinks with an
+   ellipsis down to nothing, so folder and chevron always sit snug against
+   whatever text remains — full text, ellipsized text, or none. */
 .workspace {
   display: inline-flex;
   align-items: center;
@@ -167,6 +182,7 @@
 }
 
 .workspaceLabel {
+  min-width: 0;
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
index b7561bbfd8..abd5911c90 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
@@ -10,6 +10,13 @@
   padding: 0 var(--dsh-composer-side-clearance) 8px;
 }
 
+/* A mounted stats row in the composer dock (data-composer-stats, ui-chat
+   StatsPills) brings its own 4px top pad, so the root's bottom clearance
+   tightens to keep the drawn B8 rhythm. */
+.root:has([data-composer-stats]) {
+  padding-bottom: 4px;
+}
+
 .hero {
   /* No bottom pad in the centered hero, but the side clearance must survive:
      the hero wrapper is full-width on narrow viewports, so this padding is
@@ -34,12 +41,12 @@
   position: relative; /* overlay anchor positioning context */
   display: flex;
   flex-direction: column;
-  /* figma Input 75:8208: 12px between the text area and the button row; 10px
-     top pad on the card before .InputText. */
+  /* figma Input 75:8208: 12px between the text area and the button row; the
+     card's top pad before .InputText tightened from the drawn 10 to 8. */
   gap: 12px;
   width: 100%;
   max-width: var(--dsh-composer-card-max-width);
-  padding-top: 10px;
+  padding-top: 8px;
   /* Input stroke: the light neutral (l2, one step above the menus' l1),
      drawn as the elevation hairline so it costs no layout; the shadow is the
      soft elevation tier. Fill: the input surface token (elevated in dark). */
@@ -123,8 +130,8 @@
   margin-right: 4px;
 }
 
-/* The card's 22px corner arc still overlaps the scrollport's top (10px top
-   pad reaches only y=10): start the thumb's travel below the arc so it never
+/* The card's 22px corner arc still overlaps the scrollport's top (8px top
+   pad reaches only y=8): start the thumb's travel below the arc so it never
    pokes outside the capsule. WebKit-path only; Firefox's thin bar has no
    track margin, an accepted remainder. */
 .scroll::-webkit-scrollbar-track {
@@ -153,11 +160,15 @@
 }
 
 /* The contenteditable draft surface (grows with its content; .scroll caps
-   and scrolls it). figma .InputText 34:10434: pl 16 / pr 12 / pt 4 — the
-   right pad is 8 here plus .scroll's 4px bar inset. */
+   and scrolls it). figma .InputText 34:10434 drew pl 16 / pr 12 / pt 4; the
+   left pad tightened to 14, and the right pad is 8 here plus .scroll's 4px
+   bar inset. */
 .input {
   box-sizing: border-box;
-  padding: 4px 8px 0 16px;
+  /* Docked floor: one 24px line + 4px top pad = 28 content height; 36 leaves
+     an 8px breath below the line (the hero keeps its own 52px floor below). */
+  min-height: 36px;
+  padding: 4px 8px 0 14px;
   font-family: var(--dsw-font-family);
   font-size: inherit;
   line-height: inherit;
@@ -185,11 +196,16 @@
 }
 
 /* figma 34:10434: #ADB2B8 light / #81858C dark — the caption pair exactly.
-   Right inset mirrors .input's 8px pad (the other 4px sits on .scroll). */
+   Insets mirror .input's pads (the other right 4px sits on .scroll). One
+   ellipsized line: a wrapped second line would clip against the docked
+   36px floor. */
 .placeholder {
   position: absolute;
-  inset: 4px 8px auto 16px;
+  inset: 4px 8px auto 14px;
   color: var(--dsw-alias-label-caption);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
   pointer-events: none;
   user-select: none;
 }
@@ -209,6 +225,16 @@
   min-height: 52px;
 }
 
+/* The hero's 52px floor fits two lines, so its placeholder clamps at two
+   instead of the docked single line. */
+.hero .placeholder {
+  white-space: normal;
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+  line-clamp: 2;
+}
+
 /* Toolbar: attach + Plan + Read-only on the left; model + send on the right
    (figma Input_Bottom chrome). */
 .row {
@@ -218,8 +244,8 @@
   justify-content: space-between;
   gap: 12px;
   /* 2px moved from the bottom pad to the top: the whole control row sits 2px
-     lower in the card (it read too high against the textarea) while the card
-     height and the controls' own centering stay untouched. */
+     lower in the card (it read too high against the textarea) while the
+     controls' own centering stays untouched. */
   padding: 2px 8px 6px;
   min-width: 0;
   /* Size container so the chips inside can collapse to icon-only when the
@@ -238,10 +264,10 @@
 }
 
 /* figma 75:8208 drew 16 between + and the mode chips and 4 between Plan /
-   Read-only; the chip gap widened to 12 so the pill chips read as separate
-   controls. */
+   Read-only; both gaps settled on 12 so the pill chips read as separate
+   controls without drifting from the + control. */
 .tools {
-  gap: 16px;
+  gap: 12px;
 }
 
 .modes {
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
index 144df68c43..aa37b85ecf 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
@@ -32,6 +32,7 @@ import type { ComposerBarProps } from '../contract/slots.ts'
 import { ComposerContentEditable } from '../input/editor/ComposerContentEditable.tsx'
 import { DecoratorPortals } from '../input/editor/DecoratorPortals.tsx'
 import { registerComposerKeymap } from '../input/editor/keymap.ts'
+import { resolveSubmitMode } from '../input/submission-policy.ts'
 import { attachmentErrorText, imageSizeText } from '../image-labels.ts'
 import { ContextMeter } from './ContextMeter.tsx'
 import { PermissionSelect } from './PermissionSelect.tsx'
@@ -42,14 +43,15 @@ export type InputBarProps = ComposerBarProps
 export const InputBar = memo(function InputBar({
   useSession, useInput, inputActions, keyboard, addFiles, removeAttachment, resolveDraftAttachments,
   retryFileUpload,
-  resolveSubmitMode, toggleCommandMenu, stop, command, t,
-  renderSlot, useFileUploads, useNotices, useLexicon, useMenuLauncher,
+  toggleCommandMenu, stop, command, t,
+  renderSlot, useBusyEnter, useFileUploads, useNotices, useLexicon, useMenuLauncher,
   useProjection, sessionId, variant, disabled: inert = false, blocked,
   workspacePickerOpen = false, onRequestWorkspace,
   placeholder, accessory,
 }: InputBarProps) {
   const input = useInput(s => s)
   const notice = useNotices(s => s)
+  const busyEnter = useBusyEnter(s => s)
   void useLexicon // hook seat stays bound by the inject compartment; text-ref decoration rides the shell's editor transforms
   const commandMenuOpen = useMenuLauncher(source => source === 'command')
   const promptError = useSession(s => s.promptError) ?? null
@@ -263,11 +265,11 @@ export const InputBar = memo(function InputBar({
   // The keymap handlers read live bar state through this ref so the editor
   // registration survives re-renders without re-arming per keystroke.
   const gate = useRef({
-    locked, machineBusy, canSteerQueue, running, steeringAvailable, resolveSubmitMode,
+    locked, machineBusy, canSteerQueue, running, steeringAvailable, busyEnter,
     intakeFiles, uploadsPending, showToast, t,
   })
   gate.current = {
-    locked, machineBusy, canSteerQueue, running, steeringAvailable, resolveSubmitMode,
+    locked, machineBusy, canSteerQueue, running, steeringAvailable, busyEnter,
     intakeFiles, uploadsPending, showToast, t,
   }
 
@@ -294,7 +296,8 @@ export const InputBar = memo(function InputBar({
           g.showToast(g.t('file.stillUploading'))
           return
         }
-        keyboard.submit(g.resolveSubmitMode(
+        keyboard.submit(resolveSubmitMode(
+          g.busyEnter,
           g.running,
           accelerated ? 'accelerated' : 'enter',
           g.steeringAvailable,
@@ -332,19 +335,31 @@ export const InputBar = memo(function InputBar({
   }
 
   // An ordinary running session keeps Stop while the composer is empty or
-  // owner-blocked; an actionable draft gets the existing Queue action. A
-  // continuable child keeps Send primary and exposes Stop independently.
+  // owner-blocked; an actionable draft gets the busy Send action, delivered
+  // through the same mode plain Enter resolves to. The label names that mode
+  // only when the click would deliver a plain message right now — an enabled
+  // button (no pending upload) over a non-empty draft that is neither a
+  // claimed command nor a `/` line headed for adjudication — so it never
+  // describes a delivery the click cannot or does not perform; every other
+  // state keeps plain Send. A continuable child keeps Send primary and
+  // exposes Stop independently.
   const primaryStops = running && subagent === null && (empty || blocked !== undefined)
   const interruptible = running && continuable
-  const primaryLabel = primaryStops ? t('input.stop') : t('input.send')
+  const primarySubmitMode = resolveSubmitMode(busyEnter, running, 'enter', steeringAvailable)
+  const plainMessageDraft = !empty && input?.phase === 'plain' && !draft.trimStart().startsWith('/')
+  const primaryLabel = primaryStops
+    ? t('input.stop')
+    : running && steeringAvailable && !disabled && !uploadsPending && plainMessageDraft
+      ? t(primarySubmitMode === 'steer' ? 'input.send.steer' : 'input.send.queue')
+      : t('input.send')
   const onPrimary = (): void => {
     if (primaryStops) {
       stop?.()
       return
     }
-    if (inputActions === undefined) return // absent machine: the button is disabled
+    if (keyboard === undefined) return // absent machine: the button is disabled
     /* v8 ignore next -- defensive: the primary button is disabled for empty, disabled, and pending-upload states. */
-    if (!empty && !disabled && !machineBusy && !uploadsPending) inputActions.submit()
+    if (!empty && !disabled && !machineBusy && !uploadsPending) keyboard.submit(primarySubmitMode)
   }
 
   // The Access seat: the projection-fed permission chip (renders nothing
diff --git a/packages/client/ui-conversation/tests/context-meter.client.spec.tsx b/packages/client/ui-conversation/tests/context-meter.client.spec.tsx
index 75b9a59d0c..90d69e64cc 100644
--- a/packages/client/ui-conversation/tests/context-meter.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/context-meter.client.spec.tsx
@@ -58,7 +58,7 @@ describe('ContextMeter', () => {
     expect(panel.textContent).toContain('25%')
     expect(panel.textContent).toContain('上下文已用')
     expect(panel.textContent).toContain('系统提示词~120')
-    expect(panel.textContent).toContain('工具~21.5K')
+    expect(panel.textContent).toContain('工具定义~21.5K')
     expect(panel.textContent).toContain('对话消息~477K')
     // The occupancy bar splits into one colored segment per composition row.
     expect(panel.getElementsByClassName(segmentClass)).toHaveLength(3)
diff --git a/packages/client/ui-conversation/tests/enter-behavior-row.client.spec.tsx b/packages/client/ui-conversation/tests/enter-behavior-row.client.spec.tsx
index 44022cb553..0cba7c36b5 100644
--- a/packages/client/ui-conversation/tests/enter-behavior-row.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/enter-behavior-row.client.spec.tsx
@@ -1,4 +1,5 @@
 // @vitest-environment jsdom
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { bindSnapshotSelector, makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
@@ -11,6 +12,9 @@ import type { EnterBehaviorRowProps } from '../src/client/settings/EnterBehavior
 import { ComposerSubmissionPolicy } from '../src/client/input/submission-policy.ts'
 import { en } from '../src/client/locales.ts'
 
+// Every fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 afterEach(() => {
   cleanup()
   localStorage.clear()
@@ -38,6 +42,7 @@ function mount() {
   const props: EnterBehaviorRowProps = {
     useSessions: emptySessions(),
     useSessionPendingInteraction: noPendingInteraction(),
+    useResource,
     useWorkspaces: emptyWorkspaces(),
     useBusyEnter: bindSnapshotSelector(policy.busyEnter),
     setBusyEnter,
@@ -48,10 +53,10 @@ function mount() {
 }
 
 describe('EnterBehaviorRow', () => {
-  it('explains the busy-only scope and shows Queue by default', () => {
+  it('explains the busy-only scope over Enter and Send and shows Queue by default', () => {
     mount()
-    expect(screen.getByText('Enter behavior while busy')).toBeDefined()
-    expect(screen.getByText('Busy only; Cmd/Ctrl+Enter uses the other behavior')).toBeDefined()
+    expect(screen.getByText('Send behavior while busy')).toBeDefined()
+    expect(screen.getByText('What Enter and the Send button do while the agent is running; Cmd/Ctrl+Enter uses the other behavior')).toBeDefined()
     expect(screen.getByRole('button', { name: /Queue/ }).getAttribute('aria-expanded')).toBe('false')
   })
 
diff --git a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx
index e5d7cd38e7..15353a765f 100644
--- a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx
@@ -8,6 +8,7 @@
 // root listener routes them through the keymap commands); draft writes drive
 // the shell (jsdom's beforeinput lacks the ranges Lexical needs).
 
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { afterEach, describe, expect, it, onTestFinished, vi } from 'vitest'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
 import { $getRoot, $isTextNode } from 'lexical'
@@ -24,13 +25,16 @@ import type { SubmitOutcome } from '../src/client/contract/input.ts'
 import { SessionInputShell } from '../src/client/input/facade.ts'
 import { $replaceDetectSpanWithText, $selectDetectSpan } from '../src/client/input/editor/span-map.ts'
 import type {
-  ComposerAttachment, ComposerAttachmentsOwnerProps,
+  ComposerAttachment, ComposerAttachmentsOwnerProps, DraftFileUploads,
 } from '../src/client/contract/slots.ts'
 import type { DraftAttachmentId } from '../src/client/contract/input.ts'
 import { InputBar } from '../src/client/skeleton/InputBar.tsx'
 import type { InputBarProps } from '../src/client/skeleton/InputBar.tsx'
 import { zh } from '../src/client/locales.ts'
 
+// Every fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 afterEach(cleanup)
 
 // jsdom implements no Range geometry at all — `Range.prototype.getBoundingClientRect`
@@ -89,6 +93,8 @@ interface BenchOptions {
   rightItems?: React.ReactNode
   footer?: React.ReactNode
   attachments?: readonly ComposerAttachment[]
+  /** Upload states served for file-kind drafts (absent = every file is ready). */
+  fileUploads?: DraftFileUploads
   addFiles?: (files: readonly File[]) => string | null
   commandMenuOpen?: boolean
   busyEnter?: 'queue' | 'steer'
@@ -145,6 +151,7 @@ function bench(over?: BenchOptions) {
   const stop = vi.fn()
   const removeAttachment = vi.fn((id: DraftAttachmentId) => { shell.removeAttachment(id) })
   const menuLauncher = createSnapshotStore<string | null>(over?.commandMenuOpen === true ? 'command' : null)
+  const busyEnter = createSnapshotStore<'queue' | 'steer'>(over?.busyEnter ?? 'queue')
   const slotCalls: { key: string; owner: unknown }[] = []
   const renderSlot = ((key: string, owner: object) => {
     slotCalls.push({ key, owner })
@@ -162,6 +169,7 @@ function bench(over?: BenchOptions) {
     useSession: bindSnapshotSelector(session),
     useConversation: bindSnapshotSelector(createSnapshotStore(conversationFixture())),
     useSessionPendingInteraction: bindSnapshotSelector(createSnapshotStore(new Map())),
+    useResource,
     useSessions: bindSnapshotSelector(createSnapshotStore<SessionListState>({
       ids: [], byId: {}, current: undefined, phase: 'ready',
       subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined,
@@ -179,19 +187,15 @@ function bench(over?: BenchOptions) {
     inputActions: shell.actions,
     keyboard: shell,
     addFiles: over?.addFiles ?? (() => null),
-    useFileUploads: bindSnapshotSelector(createSnapshotStore({})),
+    useFileUploads: bindSnapshotSelector(createSnapshotStore<DraftFileUploads>(over?.fileUploads ?? {})),
     retryFileUpload: undefined,
     removeAttachment,
     resolveDraftAttachments: ids => ids.flatMap((id) => {
       const attachment = over?.attachments?.find(candidate => candidate.id === id)
       return attachment === undefined ? [] : [attachment]
     }),
-    resolveSubmitMode: (running, gesture, steeringAvailable) => {
-      if (!running || !steeringAvailable) return 'queue'
-      const preferred = over?.busyEnter ?? 'queue'
-      return gesture === 'enter' ? preferred : preferred === 'queue' ? 'steer' : 'queue'
-    },
     toggleCommandMenu: over?.toggleCommandMenu ?? vi.fn(),
+    useBusyEnter: bindSnapshotSelector(busyEnter),
     useNotices: bindSnapshotSelector(shell.notices),
     useLexicon: bindSnapshotSelector(shell.lexicon),
     useMenuLauncher: bindSnapshotSelector(menuLauncher),
@@ -213,13 +217,29 @@ function bench(over?: BenchOptions) {
   const sendableDraft = (over?.draft?.trim() ?? '') !== '' || (over?.attachments?.length ?? 0) > 0
   const primaryStops = over?.running === true && over.subagent === undefined
     && (!sendableDraft || over.blocked !== undefined)
-  const button = view.container.querySelector<HTMLButtonElement>(
-    `button[aria-label="${primaryStops ? '停止生成' : '发送消息'}"]`,
-  )!
+  // A running steer-capable composer (ordinary session or continuable child
+  // with its parent online) labels Send by the delivery mode it performs over
+  // a plain message draft; idle sessions, one-shot children, locked
+  // composers, a child's empty draft, drafts with a pending upload, and `/`
+  // command lines keep plain Send (an ordinary running session's empty draft
+  // is the Stop seat). The mirror models plain-phase drafts only: cases
+  // that claim a command or freeze the machine query the DOM directly.
+  const steeringAvailable = over?.subagent === undefined || over.subagent.address.mode === 'continuable'
+  const composerLocked = over?.disabled === true || over?.inert === true || over?.blocked !== undefined
+    || (over?.subagent?.address.mode === 'continuable' && over.subagent.parentAvailable !== true)
+  const uploadsPending = (over?.attachments ?? []).some(attachment =>
+    attachment.kind === 'file' && over?.fileUploads?.[attachment.id]?.status !== 'ready')
+  const plainMessageDraft = sendableDraft && !uploadsPending && !(over?.draft?.trimStart().startsWith('/') ?? false)
+  const primaryLabel = primaryStops
+    ? '停止生成'
+    : over?.running === true && steeringAvailable && !composerLocked && plainMessageDraft
+      ? (over.busyEnter === 'steer' ? '插话发送' : '排队发送')
+      : '发送消息'
+  const button = view.container.querySelector<HTMLButtonElement>(`button[aria-label="${primaryLabel}"]`)!
   const interruptButton = view.container.querySelector<HTMLButtonElement>('button[aria-label="停止生成"]')
   return {
     view, textarea, button, interruptButton, props, sink, shell, wiring: shell, session, stop, removeAttachment, slotCalls,
-    menuLauncher,
+    menuLauncher, busyEnter,
     steerQueue: over?.steerQueue,
     get placeholder() { return placeholderOf(view.container) },
     get inputDisabled() { return textarea.getAttribute('aria-disabled') === 'true' },
@@ -473,9 +493,9 @@ describe('Enter semantics', () => {
   })
 
   it('keeps the owning placeholder or ordinary guidance when whole-queue steering is unavailable', () => {
-    expect(bench({ running: true }).placeholder).toBe('发消息或做任务… / 调用指令 @ 文件或对话')
-    expect(bench({ queue: [row('q-1')] }).placeholder).toBe('发消息或做任务… / 调用指令 @ 文件或对话')
-    expect(bench({ running: true, queue: [row('q-1')], draft: '消息' }).placeholder).toBe('发消息或做任务… / 调用指令 @ 文件或对话')
+    expect(bench({ running: true }).placeholder).toBe('发消息或创建任务, / 调用指令, @ 文件或对话')
+    expect(bench({ queue: [row('q-1')] }).placeholder).toBe('发消息或创建任务, / 调用指令, @ 文件或对话')
+    expect(bench({ running: true, queue: [row('q-1')], draft: '消息' }).placeholder).toBe('发消息或创建任务, / 调用指令, @ 文件或对话')
     expect(bench({
       running: true,
       queue: [row('q-1')],
@@ -487,7 +507,7 @@ describe('Enter semantics', () => {
       running: true,
       queue: [row('q-1')],
       commandMenuOpen: true,
-    }).placeholder).toBe('发消息或做任务… / 调用指令 @ 文件或对话')
+    }).placeholder).toBe('发消息或创建任务, / 调用指令, @ 文件或对话')
     // The steer hint intentionally outranks the plan placeholder: while it
     // shows, the whole-queue gesture is genuinely available in plan mode.
     expect(bench({
@@ -719,24 +739,93 @@ describe('Enter semantics', () => {
 
 describe('running and lock semantics', () => {
   it('running switches the primary between Stop and Queue Send with the draft', async () => {
-    const { textarea, button, stop, sink, shell } = bench({ running: true, busyEnter: 'steer' })
+    const { textarea, button, stop, sink, shell } = bench({ running: true })
     expect(textarea.getAttribute('aria-disabled')).not.toBe('true')
     expect(button.getAttribute('aria-label')).toBe('停止生成')
     fireEvent.click(button)
     expect(stop).toHaveBeenCalledTimes(1)
 
     writeDraft(shell, '排队消息')
-    expect(button.getAttribute('aria-label')).toBe('发送消息')
+    expect(button.getAttribute('aria-label')).toBe('排队发送')
     writeDraft(shell, '   ')
     expect(button.getAttribute('aria-label')).toBe('停止生成')
     writeDraft(shell, '排队消息2')
-    expect(button.getAttribute('aria-label')).toBe('发送消息')
+    expect(button.getAttribute('aria-label')).toBe('排队发送')
     fireEvent.click(button)
     expect(sink).toHaveBeenCalledWith('排队消息2', [], 'queue', expect.any(AbortSignal))
     await vi.waitFor(() => { expect(button.getAttribute('aria-label')).toBe('停止生成') })
     expect(stop).toHaveBeenCalledTimes(1)
   })
 
+  it('running Send follows the busy-state Steer preference and labels the delivery', () => {
+    const { button, sink } = bench({ running: true, busyEnter: 'steer', draft: '按钮插话' })
+    expect(button.getAttribute('aria-label')).toBe('插话发送')
+    fireEvent.click(button)
+    expect(sink).toHaveBeenCalledWith('按钮插话', [], 'steer', expect.any(AbortSignal))
+  })
+
+  it('running Send relabels when the busy-state preference changes live', () => {
+    const { button, busyEnter, sink } = bench({ running: true, draft: '跟随设置' })
+    expect(button.getAttribute('aria-label')).toBe('排队发送')
+    act(() => { busyEnter.set('steer') })
+    expect(button.getAttribute('aria-label')).toBe('插话发送')
+    fireEvent.click(button)
+    expect(sink).toHaveBeenCalledWith('跟随设置', [], 'steer', expect.any(AbortSignal))
+  })
+
+  it('running Send keeps the plain label for a slash line and a claimed command', () => {
+    // An unclaimed `/` line adjudicates on submit; a claimed command executes
+    // instead of delivering a message. Neither click is a Queue/Steer delivery.
+    const slash = bench({ running: true, busyEnter: 'steer', draft: '/goal inspect' })
+    expect(slash.button.getAttribute('aria-label')).toBe('发送消息')
+    expect(slash.button.disabled).toBe(false)
+
+    const claimed = bench({ running: true, busyEnter: 'steer' })
+    act(() => {
+      claimed.shell.setDraft('/goal ')
+      claimed.shell.beginCommand(
+        { token: '/goal ', submit: () => Promise.resolve({ kind: 'success' }) },
+        { start: 0, end: 6, draftRev: claimed.shell.snapshot.draftRev },
+      )
+    })
+    expect(claimed.shell.snapshot.phase).toBe('claimed')
+    const button = claimed.view.container.querySelector<HTMLButtonElement>('button[aria-label="发送消息"]')
+    expect(button).not.toBeNull()
+    expect(claimed.view.container.querySelector('button[aria-label="插话发送"]')).toBeNull()
+  })
+
+  it('running Send keeps the plain label while a file upload is still pending', () => {
+    const file = { kind: 'file' as const, id: 'file-1' as DraftAttachmentId, file: new File(['x'], 'note.txt', { type: 'text/plain' }) }
+    const pending = bench({
+      running: true, busyEnter: 'steer', draft: '带附件', attachments: [file],
+      fileUploads: { [file.id]: { status: 'uploading', loaded: 0 } },
+    })
+    expect(pending.button.getAttribute('aria-label')).toBe('发送消息')
+    expect(pending.button.disabled).toBe(true)
+
+    // A failed upload holds the same gate until it is retried or removed.
+    const failed = bench({
+      running: true, busyEnter: 'steer', draft: '带附件', attachments: [file],
+      fileUploads: { [file.id]: { status: 'error', message: 'upload failed' } },
+    })
+    expect(failed.button.getAttribute('aria-label')).toBe('发送消息')
+    expect(failed.button.disabled).toBe(true)
+
+    const ready = bench({
+      running: true, busyEnter: 'steer', draft: '带附件', attachments: [file],
+      fileUploads: { [file.id]: { status: 'ready', receiptId: 'receipt-1' as never, file: { kind: 'file' } as never } },
+    })
+    expect(ready.button.getAttribute('aria-label')).toBe('插话发送')
+    expect(ready.button.disabled).toBe(false)
+  })
+
+  it('idle Send keeps the plain label regardless of the busy-state preference', () => {
+    const { button, sink } = bench({ busyEnter: 'steer', draft: '空闲发送' })
+    expect(button.getAttribute('aria-label')).toBe('发送消息')
+    fireEvent.click(button)
+    expect(sink).toHaveBeenCalledWith('空闲发送', [], 'queue', expect.any(AbortSignal))
+  })
+
   it('running treats an attachment-only draft as Send', async () => {
     const attachment = {
       kind: 'image' as const,
@@ -745,7 +834,7 @@ describe('running and lock semantics', () => {
       previewUrl: 'blob:pixel',
     }
     const { button, sink } = bench({ running: true, attachments: [attachment] })
-    expect(button.getAttribute('aria-label')).toBe('发送消息')
+    expect(button.getAttribute('aria-label')).toBe('排队发送')
     fireEvent.click(button)
     expect(sink).toHaveBeenCalledWith('', ['draft-1'], 'queue', expect.any(AbortSignal))
     await vi.waitFor(() => { expect(button.getAttribute('aria-label')).toBe('停止生成') })
@@ -796,7 +885,7 @@ describe('running and lock semantics', () => {
         parentAvailable: true,
       },
     })
-    expect(button.getAttribute('aria-label')).toBe('发送消息')
+    expect(button.getAttribute('aria-label')).toBe('排队发送')
     expect(interruptButton).not.toBeNull()
     expect(textarea.getAttribute('aria-disabled')).not.toBe('true')
     expect((view.getByLabelText('添加附件') as HTMLButtonElement).disabled).toBe(true)
@@ -808,6 +897,27 @@ describe('running and lock semantics', () => {
     expect(stop).toHaveBeenCalledTimes(1)
   })
 
+  it('running continuable subagent Send follows the Steer preference like an ordinary session', () => {
+    const subagent = {
+      address: {
+        parentSessionId: 'parent' as SessionId,
+        childSessionId: SID,
+        mode: 'continuable' as const,
+      },
+      parentAvailable: true,
+    }
+    const { button, sink } = bench({ running: true, busyEnter: 'steer', draft: '子代理插话', subagent })
+    expect(button.getAttribute('aria-label')).toBe('插话发送')
+    fireEvent.click(button)
+    expect(sink).toHaveBeenCalledWith('子代理插话', [], 'steer', expect.any(AbortSignal))
+
+    // No draft: the child has no Stop seat to fall back to, so its disabled
+    // Send keeps the plain label instead of naming a delivery it cannot make.
+    const empty = bench({ running: true, busyEnter: 'steer', subagent })
+    expect(empty.button.getAttribute('aria-label')).toBe('发送消息')
+    expect(empty.button.disabled).toBe(true)
+  })
+
   it.each([
     ['active plan', { plan: { active: true, pending: false } }],
     ['active goal', { goal: { phase: 'active' as const, objective: 'inspect files' } }],
@@ -1002,7 +1112,7 @@ describe('running and lock semantics', () => {
   it('disabled state shows the unavailable placeholder; custom placeholder wins', () => {
     expect(bench({ disabled: true }).placeholder).toBe('会话不可用')
     const live = bench()
-    expect(live.placeholder).toBe('发消息或做任务… / 调用指令 @ 文件或对话')
+    expect(live.placeholder).toBe('发消息或创建任务, / 调用指令, @ 文件或对话')
     const custom = bench({ placeholder: 'Custom placeholder' })
     expect(custom.placeholder).toBe('Custom placeholder')
   })
@@ -1049,7 +1159,7 @@ describe('running and lock semantics', () => {
     expect(entering.placeholder).toBe('描述你的任务以生成计划')
     // Pending exit: target is default again.
     const leaving = bench({ plan: { active: true, pending: true } })
-    expect(leaving.placeholder).toBe('发消息或做任务… / 调用指令 @ 文件或对话')
+    expect(leaving.placeholder).toBe('发消息或创建任务, / 调用指令, @ 文件或对话')
     // Owner placeholder outranks the plan swap.
     const custom = bench({ plan: { active: true, pending: false }, placeholder: 'Custom placeholder' })
     expect(custom.placeholder).toBe('Custom placeholder')
diff --git a/packages/client/ui-conversation/tests/input-matrix.client.spec.tsx b/packages/client/ui-conversation/tests/input-matrix.client.spec.tsx
index 5224973369..c333d25ada 100644
--- a/packages/client/ui-conversation/tests/input-matrix.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-matrix.client.spec.tsx
@@ -5,6 +5,7 @@
  * hint / pending), edit freedom, and the published currency's claim seat.
  * React over jsdom per the client testing discipline; the machine is real.
  */
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
 import type { Context } from '@deepseek-ai/cordis'
@@ -24,6 +25,9 @@ import { InputBar } from '../src/client/skeleton/InputBar.tsx'
 import type { InputBarProps } from '../src/client/skeleton/InputBar.tsx'
 import { zh } from '../src/client/locales.ts'
 
+// Every fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 // jsdom implements no Range geometry (Lexical's scroll-into-view measures the
 // caret with one once the surface is genuinely contenteditable).
 Range.prototype.getBoundingClientRect = () => ({
@@ -54,6 +58,7 @@ function mountBar(shell: SessionInputShell, over?: { running?: boolean; disabled
     useSessionPendingInteraction: bindSnapshotSelector(
       createSnapshotStore<SessionPendingInteractionSnapshot>(new Map()),
     ),
+    useResource,
     useWorkspaces: bindSnapshotSelector(createSnapshotStore({
       items: [], archivedSessionIds: [], state: 'idle', phase: 'ready', error: null,
       baselinesReady: true, recentWorkspaceId: undefined,
@@ -73,8 +78,8 @@ function mountBar(shell: SessionInputShell, over?: { running?: boolean; disabled
       file: new File([Uint8Array.of(1)], `${id}.png`, { type: 'image/png' }),
       previewUrl: `blob:${id}`,
     })),
-    resolveSubmitMode: () => 'queue',
     toggleCommandMenu: vi.fn(),
+    useBusyEnter: bindSnapshotSelector(createSnapshotStore<'queue' | 'steer'>('queue')),
     useNotices: bindSnapshotSelector(shell.notices),
     useLexicon: bindSnapshotSelector(shell.lexicon),
     useMenuLauncher: bindSnapshotSelector(createSnapshotStore<string | null>(null)),
diff --git a/packages/client/ui-conversation/tests/input-scenarios.client.spec.tsx b/packages/client/ui-conversation/tests/input-scenarios.client.spec.tsx
index 108385664f..9e41f82eb7 100644
--- a/packages/client/ui-conversation/tests/input-scenarios.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-scenarios.client.spec.tsx
@@ -8,6 +8,7 @@
  * itself is not a dependency of this package; the source below is the
  * decision-table contract at the `InputTriggerSource` boundary.
  */
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { afterEach, describe, expect, it, onTestFinished, vi } from 'vitest'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
 import type { SessionSnapshot } from '@deepseek-ai/dsh-api-session-controller/client'
@@ -31,6 +32,9 @@ import { InputBar } from '../src/client/skeleton/InputBar.tsx'
 import type { InputBarProps } from '../src/client/skeleton/InputBar.tsx'
 import { zh } from '../src/client/locales.ts'
 
+// Every fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 // jsdom implements no Range geometry (Lexical's scroll-into-view measures the
 // caret with one once the surface is genuinely contenteditable).
 Range.prototype.getBoundingClientRect = () => ({
@@ -143,6 +147,7 @@ async function scopedBench(register?: (inputTriggers: InputTriggerService) => vo
     useSessionPendingInteraction: bindSnapshotSelector(
       createSnapshotStore<SessionPendingInteractionSnapshot>(new Map()),
     ),
+    useResource,
     useWorkspaces: bindSnapshotSelector(createSnapshotStore({
       items: [], archivedSessionIds: [], state: 'idle', phase: 'ready', error: null,
       baselinesReady: true, recentWorkspaceId: undefined,
@@ -162,7 +167,7 @@ async function scopedBench(register?: (inputTriggers: InputTriggerService) => vo
       file: new File([Uint8Array.of(1)], `${id}.png`, { type: 'image/png' }),
       previewUrl: `blob:${id}`,
     })),
-    resolveSubmitMode: () => 'queue',
+    useBusyEnter: bindSnapshotSelector(createSnapshotStore<'queue' | 'steer'>('queue')),
     toggleCommandMenu: (selection) => {
       const snapshot = shell.snapshot
       controller.toggleSource('command', {
diff --git a/packages/client/ui-conversation/tests/queue-dock.client.spec.tsx b/packages/client/ui-conversation/tests/queue-dock.client.spec.tsx
index 07d13f9d13..b64e57aa54 100644
--- a/packages/client/ui-conversation/tests/queue-dock.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/queue-dock.client.spec.tsx
@@ -3,6 +3,7 @@
  * QueueDock rendering and operations: authoritative rows, inline editing,
  * collapse state, removal, QueueDock Steer, failure notices, and live retirement.
  */
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, waitFor } from '@testing-library/react'
 import { useSyncExternalStore } from 'react'
@@ -22,8 +23,12 @@ import type { InputState } from '../src/client/contract/input.ts'
 import { zh } from '../src/client/locales.ts'
 import { QueueDock, queueDockEntry, type QueueDockInjected, type QueueDockProps } from '../src/client/queue/QueueDock.tsx'
 
+// Every session-scope fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 afterEach(cleanup)
 
+
 const SID = 's1' as SessionId
 const iid = (id: string): QueueItemId => id as QueueItemId
 
@@ -74,6 +79,7 @@ function kitFor(snapshot: SessionSnapshot, injected: Partial<QueueDockInjected>
     sessionId: SID,
     t,
     useSessions: (() => { throw new Error('unused') }) as unknown as SnapshotSelectorHook<SessionListState>,
+    useResource,
     useSessionPendingInteraction: bindSnapshotSelector(
       createSnapshotStore<SessionPendingInteractionSnapshot>(new Map()),
     ),
diff --git a/packages/client/ui-conversation/tests/skeleton.client.spec.tsx b/packages/client/ui-conversation/tests/skeleton.client.spec.tsx
index 2c20f198c5..f1735ce415 100644
--- a/packages/client/ui-conversation/tests/skeleton.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/skeleton.client.spec.tsx
@@ -1,4 +1,5 @@
 // @vitest-environment jsdom
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type { ComponentProps, ReactNode } from 'react'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
@@ -32,12 +33,16 @@ import type {
 } from '../src/client/contract/slots.ts'
 import type { ViewTab } from '../src/client/contract/views.ts'
 
+// Every session-scope fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 // jsdom implements no Range geometry (Lexical's scroll-into-view measures the
 // caret with one once the surface is genuinely contenteditable).
 Range.prototype.getBoundingClientRect = () => ({
   top: 0, bottom: 0, left: 0, right: 0, width: 0, height: 0, x: 0, y: 0, toJSON: () => ({}),
 })
 
+
 function fakeWiring() {
   const sink = vi.fn(() => Promise.resolve({ kind: 'success' as const }))
   const shell = new SessionInputShell({ actx: {} as Context, defaultSink: sink, commandAttachments: { serialize: () => Promise.resolve([]), release: () => {}, unsupportedNotice: (token: string) => `${token.trim()} attachments-unsupported` } })
@@ -194,6 +199,7 @@ function mount(
           useChat={useChat}
           useTrajectory={useTrajectory}
           useSessions={props.useSessions}
+          useResource={useResource}
           useSessionPendingInteraction={useSessionPendingInteraction}
           useWorkspaces={props.useWorkspaces}
           useProjection={(() => undefined)}
@@ -219,6 +225,7 @@ function mount(
           useChat={useChat}
           useTrajectory={useTrajectory}
           useSessions={props.useSessions}
+          useResource={useResource}
           useSessionPendingInteraction={useSessionPendingInteraction}
           useWorkspaces={props.useWorkspaces}
           useProjection={(() => undefined)}
@@ -240,6 +247,7 @@ function mount(
         <InputBar
           sessionId={SID}
           SessionProvider={({ children }) => children}
+          useResource={useResource}
           useSession={useSession}
           useConversation={useConversation}
           useSessions={props.useSessions}
@@ -254,8 +262,8 @@ function mount(
           retryFileUpload={undefined}
           removeAttachment={() => {}}
           resolveDraftAttachments={() => []}
-          resolveSubmitMode={() => 'queue'}
           toggleCommandMenu={vi.fn()}
+          useBusyEnter={bindSnapshotSelector(createSnapshotStore<'queue' | 'steer'>('queue'))}
           useNotices={bindSnapshotSelector(wiring.notices)}
           useLexicon={bindSnapshotSelector(wiring.lexicon)}
           useMenuLauncher={bindSnapshotSelector(createSnapshotStore<string | null>(null))}
@@ -293,6 +301,7 @@ function mount(
     useConversation,
     useSessions: bindSnapshotSelector(sessions),
     useSessionPendingInteraction,
+    useResource,
     useWorkspaces: bindSnapshotSelector(workspaces),
     useProjection: (() => undefined),
     useComposerBlock: select => select(options.composerBlock),
@@ -437,6 +446,7 @@ describe('ConversationRoot resident composer', () => {
     expect(b.slotCalls).toContain('conversation.session.header.lineage')
     expect(b.slotCalls).toContain('conversation.session.header.actions')
     expect(b.slotCalls).toContain('conversation.session.header.utilities')
+    expect(b.slotCalls).toContain('conversation.session.header.corner')
   })
 
   it('sticky composer seat wraps the whole overlay chain, not only the fallback stack', () => {
diff --git a/packages/client/ui-conversation/tests/submission-policy.client.spec.ts b/packages/client/ui-conversation/tests/submission-policy.client.spec.ts
index 3117c39032..44136dee38 100644
--- a/packages/client/ui-conversation/tests/submission-policy.client.spec.ts
+++ b/packages/client/ui-conversation/tests/submission-policy.client.spec.ts
@@ -2,29 +2,37 @@
 import { describe, expect, it, vi } from 'vitest'
 import { stubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime'
 import {
-  ComposerSubmissionPolicy, DEFAULT_BUSY_ENTER_BEHAVIOR,
+  ComposerSubmissionPolicy, DEFAULT_BUSY_ENTER_BEHAVIOR, resolveSubmitMode,
 } from '../src/client/input/submission-policy.ts'
 import type { ConversationSettings } from '../src/submission-settings.ts'
 
+describe('resolveSubmitMode', () => {
+  it('queues outside steer-capable busy state and applies the preference to the enter gesture', () => {
+    expect(resolveSubmitMode('queue', false, 'enter', true)).toBe('queue')
+    expect(resolveSubmitMode('queue', false, 'accelerated', true)).toBe('queue')
+    expect(resolveSubmitMode('queue', true, 'enter', true)).toBe('queue')
+    expect(resolveSubmitMode('queue', true, 'accelerated', true)).toBe('steer')
+    expect(resolveSubmitMode('queue', true, 'enter', false)).toBe('queue')
+    expect(resolveSubmitMode('queue', true, 'accelerated', false)).toBe('queue')
+
+    expect(resolveSubmitMode('steer', true, 'enter', true)).toBe('steer')
+    expect(resolveSubmitMode('steer', true, 'accelerated', true)).toBe('queue')
+    expect(resolveSubmitMode('steer', false, 'enter', true)).toBe('queue')
+    expect(resolveSubmitMode('steer', false, 'accelerated', true)).toBe('queue')
+    expect(resolveSubmitMode('steer', true, 'enter', false)).toBe('queue')
+  })
+})
+
 describe('ComposerSubmissionPolicy', () => {
-  it('defaults to Queue and only applies the preference while running', () => {
+  it('defaults to Queue and publishes preference changes', () => {
     const policy = new ComposerSubmissionPolicy()
     expect(policy.busyEnter.getSnapshot()).toBe(DEFAULT_BUSY_ENTER_BEHAVIOR)
-    expect(policy.resolve(false, 'enter', true)).toBe('queue')
-    expect(policy.resolve(false, 'accelerated', true)).toBe('queue')
-    expect(policy.resolve(true, 'enter', true)).toBe('queue')
-    expect(policy.resolve(true, 'accelerated', true)).toBe('steer')
-    expect(policy.resolve(true, 'enter', false)).toBe('queue')
-    expect(policy.resolve(true, 'accelerated', false)).toBe('queue')
 
     const changed = vi.fn()
     policy.busyEnter.subscribe(changed)
     policy.setBusyEnter('steer')
     expect(changed).toHaveBeenCalledTimes(1)
-    expect(policy.resolve(true, 'enter', true)).toBe('steer')
-    expect(policy.resolve(true, 'accelerated', true)).toBe('queue')
-    expect(policy.resolve(false, 'enter', true)).toBe('queue')
-    expect(policy.resolve(false, 'accelerated', true)).toBe('queue')
+    expect(policy.busyEnter.getSnapshot()).toBe('steer')
   })
 
   it('writes an explicit change through the scope after publishing it locally', () => {
diff --git a/packages/client/ui-deliverables/README.i18n.yaml b/packages/client/ui-deliverables/README.i18n.yaml
index c3174c5164..01417ca259 100644
--- a/packages/client/ui-deliverables/README.i18n.yaml
+++ b/packages/client/ui-deliverables/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-deliverables/README.md
-README.md: 567ccca6e7c7668686716b3e33ed43209cfcfee4
-README.zh.md: fde644925a64f1a7d4b9d131b9eb2e2eb384c735
+README.md: bfd4c40a952122db25172bebb077d12800b49308
+README.zh.md: 23c983f938d2d77fa5f33e8dcd2526282268b835
diff --git a/packages/client/ui-deliverables/README.md b/packages/client/ui-deliverables/README.md
index 567ccca6e7..bfd4c40a95 100644
--- a/packages/client/ui-deliverables/README.md
+++ b/packages/client/ui-deliverables/README.md
@@ -25,7 +25,7 @@ This package renders the deliverables row a finished turn ends with — the file
 <a id="use-this-package"></a>
 ## Use this package
 
-Mount this plugin alongside `ui-conversation`; a finished turn then ends with the produced-files row between the closing message's body and its action footer. Each chip opens the file through the Host opener, with relative paths resolved against the session cwd; when the row first appears, it queries `session.canOpenWorkspacePath()`, and an omitted-file **Show in folder** action opens the session workspace only when the page is loopback and that query succeeds with `true`.
+Mount this plugin alongside `ui-conversation`; a finished turn then ends with the produced-files row between the closing message's body and its action footer. Each chip opens the file through the owner's `openFile`, which the chat view routes to the right Sidebar as a text-preview tab, with relative paths resolved against the session cwd. The row offers no folder action: the Sidebar has no directory form, so an omitted-file remainder is a label only.
 
 ### The row
 
@@ -55,7 +55,7 @@ The Node half registers the static `ui:deliverable-file-references` system-promp
 Read these pages when the deliverables surface is not enough. They move from the row to the turn-tail hole and the decisions behind the vocabulary.
 
 - [ui-conversation](../ui-conversation/README.md) — declares the `conversation.chat.turnTail` hole and renders the closing prose.
-- [Workspace file links](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md) — the decision behind the produced-files row and the Host open path.
+- [Workspace file links](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md) — the decision behind the produced-files row; its Host open path is superseded by the [right Sidebar](../../../.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.md).
 - [Inline file mentions](../../../.agents/notes/archived/feature/2026-08-07-web-inline-file-mentions.md) — the decision behind clickable mentions in the closing prose.
 - [Client package map](../README.md) — adjacent browser UI packages.
 
@@ -87,7 +87,7 @@ These limits define the current deliverables vocabulary. They are current packag
 
 - **Mention matching is exact path or unique basename only** — a suffix mention stays inert; widening the matcher is deferred until a real closing-message shape needs it.
 - **Files created indirectly by terminal commands remain outside the matching vocabulary** — naming such a file in inline code does not make it clickable unless a successful mutation location also records that path.
-- **Native folder handoff targets the Host desktop** — a browser reached through a non-loopback authority omits the action, as does a deployment reporting no native opener; SSH forwarding that makes a remote Host look loopback-local must set the Session Controller's `nativeOpen: false`.
+- **Directories have no destination** — chips open files in the right Sidebar's text preview, which shows files only; the former native folder handoff is gone rather than replaced.
 
 <a id="dev-note"></a>
 ### Dev Note
diff --git a/packages/client/ui-deliverables/README.zh.md b/packages/client/ui-deliverables/README.zh.md
index fde644925a..23c983f938 100644
--- a/packages/client/ui-deliverables/README.zh.md
+++ b/packages/client/ui-deliverables/README.zh.md
@@ -25,7 +25,7 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-与 `ui-conversation` 一起挂载本插件；已完成轮次随即以产出文件行收尾，位于收尾消息正文与其动作页脚之间。每个标签项经 Host 打开器打开文件，相对路径按会话 cwd 解析；该行首次显示时会查询 `session.canOpenWorkspacePath()`，有文件被省略、页面为 loopback 且查询成功返回 `true` 时，**在文件夹中显示**动作才会打开会话工作区。
+与 `ui-conversation` 一起挂载本插件；已完成轮次随即以产出文件行收尾，位于收尾消息正文与其动作页脚之间。每个标签项经属主的 `openFile` 打开文件——chat 视图把它路由到右侧 Sidebar 作为一个文本预览 tab——相对路径按会话 cwd 解析。该行不提供文件夹动作：Sidebar 没有目录形态，因此省略文件的余数只是一个标签才会打开会话工作区。
 
 ### 该行
 
@@ -55,7 +55,7 @@ Node 半部注册静态 `ui:deliverable-file-references` 系统提示词段，
 当产出物面不够用时阅读以下页面。它们从该行进入 turn-tail 洞与词表背后的决策。
 
 - [ui-conversation](../ui-conversation/README.zh.md)——声明 `conversation.chat.turnTail` 洞并渲染收尾正文。
-- [工作区文件链接](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md)——产出文件行与宿主打开路径背后的决策。
+- [工作区文件链接](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md)——产出文件行背后的决策；其 Host 打开路径已被[右侧 Sidebar](../../../.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md)取代。
 - [行内文件提及](../../../.agents/notes/archived/feature/2026-08-07-web-inline-file-mentions.md)——收尾正文可点击提及背后的决策。
 - [客户端包映射](../README.zh.md)——相邻的浏览器 UI 包。
 
diff --git a/packages/client/ui-deliverables/src/client/ProducedFiles.module.css b/packages/client/ui-deliverables/src/client/ProducedFiles.module.css
index 29310fe389..19cc03c126 100644
--- a/packages/client/ui-deliverables/src/client/ProducedFiles.module.css
+++ b/packages/client/ui-deliverables/src/client/ProducedFiles.module.css
@@ -85,8 +85,7 @@
   text-underline-offset: 3px;
 }
 
-.file:focus-visible,
-.showFolder:focus-visible {
+.file:focus-visible {
   outline: none;
   box-shadow: inset 0 0 0 2px var(--dsw-alias-border-l3);
 }
@@ -103,14 +102,6 @@
   display: inline;
 }
 
-.showFolder {
-  display: none;
-}
-
-.lane:has(.more[data-shown='6']) > .showFolder {
-  display: flex;
-}
-
 /* Each band budgets 96px per chip, 8px gaps, and 64px for the remainder. */
 @container (max-width: 687px) {
   .file:nth-of-type(6),
@@ -121,14 +112,6 @@
   .more[data-shown='5'] {
     display: inline;
   }
-
-  .showFolder {
-    display: none;
-  }
-
-  .lane:has(.more[data-shown='5']) > .showFolder {
-    display: flex;
-  }
 }
 
 @container (max-width: 583px) {
@@ -140,14 +123,6 @@
   .more[data-shown='4'] {
     display: inline;
   }
-
-  .showFolder {
-    display: none;
-  }
-
-  .lane:has(.more[data-shown='4']) > .showFolder {
-    display: flex;
-  }
 }
 
 @container (max-width: 479px) {
@@ -159,14 +134,6 @@
   .more[data-shown='3'] {
     display: inline;
   }
-
-  .showFolder {
-    display: none;
-  }
-
-  .lane:has(.more[data-shown='3']) > .showFolder {
-    display: flex;
-  }
 }
 
 @container (max-width: 375px) {
@@ -178,14 +145,6 @@
   .more[data-shown='2'] {
     display: inline;
   }
-
-  .showFolder {
-    display: none;
-  }
-
-  .lane:has(.more[data-shown='2']) > .showFolder {
-    display: flex;
-  }
 }
 
 @container (max-width: 271px) {
@@ -197,32 +156,4 @@
   .more[data-shown='1'] {
     display: inline;
   }
-
-  .showFolder {
-    display: none;
-  }
-
-  .lane:has(.more[data-shown='1']) > .showFolder {
-    display: flex;
-  }
-}
-
-.showFolder {
-  justify-self: start;
-  align-items: center;
-  gap: 5px;
-  margin: 0;
-  padding: 0 2px;
-  border: none;
-  border-radius: 4px;
-  background: transparent;
-  color: var(--dsw-alias-label-tertiary);
-  font: inherit;
-  line-height: 20px;
-  cursor: pointer;
-}
-
-.showFolder:hover {
-  color: var(--dsw-alias-label-secondary);
-  text-decoration: underline;
 }
diff --git a/packages/client/ui-deliverables/src/client/ProducedFiles.tsx b/packages/client/ui-deliverables/src/client/ProducedFiles.tsx
index 035bca4900..3908138708 100644
--- a/packages/client/ui-deliverables/src/client/ProducedFiles.tsx
+++ b/packages/client/ui-deliverables/src/client/ProducedFiles.tsx
@@ -1,6 +1,5 @@
-import { useEffect } from 'react'
 import { LinkIcon, classifyLinkPath } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { HostObservable, InjectFace, PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
 import type { TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-chat/client'
 import { basename } from './turn-deliverables.ts'
 import type { NS } from './locales.ts'
@@ -9,22 +8,10 @@ import css from './ProducedFiles.module.css'
 /** Maximum number of file chips rendered before the remainder counter. */
 const SHOWN_LIMIT = 6
 
-/** Registration-side Host capability facts. */
-export interface ProducedFilesInjected {
-  /** Whether the browser itself is connected over loopback. */
-  isLoopback: boolean
-  /** Load the opener capability when this row first reaches the page. */
-  ensureWorkspacePathOpen(): void
-  hooks: {
-    /** Current generation's Session workspace opener capability. */
-    workspacePathOpen: HostObservable<boolean | undefined>
-  }
-}
-
-/** Matched paths plus the opener, locale, and injected Host capability. */
+/** Matched paths, the opener, and the locale seat. */
 export type ProducedFilesProps = Pick<TurnTailOwnerProps, 'openFile'> & {
   matched: readonly string[]
-} & PropsLocale<typeof NS> & InjectFace<ProducedFilesInjected>
+} & PropsLocale<typeof NS>
 
 function moreLabel(t: ProducedFilesProps['t'], count: number): string {
   return count === 1 ? t('produced.moreOne') : t('produced.more', { count: String(count) })
@@ -35,12 +22,7 @@ function moreLabel(t: ProducedFilesProps['t'], count: number): string {
  * @param props - selector-matched paths, the chat view's file opener, and the locale seat.
  * @returns The produced-files row.
  */
-export function ProducedFiles({
-  matched: paths, openFile, isLoopback, ensureWorkspacePathOpen, useWorkspacePathOpen, t,
-}: ProducedFilesProps) {
-  useEffect(() => { ensureWorkspacePathOpen() }, [ensureWorkspacePathOpen])
-  const hostCanOpenPath = useWorkspacePathOpen(available => available === true)
-  const canOpenPath = isLoopback && hostCanOpenPath
+export function ProducedFiles({ matched: paths, openFile, t }: ProducedFilesProps) {
   const shown = paths.slice(0, SHOWN_LIMIT)
   return (
     <div className={css.root}>
@@ -73,16 +55,6 @@ export function ProducedFiles({
             )
           })}
         </div>
-        {paths.length > 1 && canOpenPath && (
-          <button
-            type="button"
-            className={css.showFolder}
-            onClick={() => { openFile('.') }}
-          >
-            <LinkIcon kind="folder" className={css.fileIcon} />
-            {t('produced.showInFolder')}
-          </button>
-        )}
       </div>
     </div>
   )
diff --git a/packages/client/ui-deliverables/src/client/index.ts b/packages/client/ui-deliverables/src/client/index.ts
index d66a505ff2..01877b7b57 100644
--- a/packages/client/ui-deliverables/src/client/index.ts
+++ b/packages/client/ui-deliverables/src/client/index.ts
@@ -9,7 +9,6 @@
  */
 import type { Context as ClientContext } from '@deepseek-ai/cordis'
 import type {} from '@deepseek-ai/dsh-api-remotes/client'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import type { ChatFileMentions } from '@deepseek-ai/dsh-client-ui-chat/client'
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
@@ -38,32 +37,6 @@ export const inject = ['slots', 'locale', 'uiConversation', 'remote', 'remote.se
  * @param ctx - client root context.
  */
 export function apply(ctx: ClientContext): void {
-  const workspacePathOpen = createSnapshotStore<boolean | undefined>(undefined)
-  let requestedWorkspacePathOpen = false
-  let capabilityRevision = 0
-  let pendingCapability: Promise<void> | undefined
-  const loadWorkspacePathOpen = (): void => {
-    if (pendingCapability !== undefined) return
-    const revision = capabilityRevision
-    const pending = ctx.remote.session.canOpenWorkspacePath()
-      .then((result) => {
-        if (revision === capabilityRevision) workspacePathOpen.set(result.ok && result.value)
-      })
-      .finally(() => {
-        if (pendingCapability === pending) pendingCapability = undefined
-      })
-    pendingCapability = pending
-  }
-  const ensureWorkspacePathOpen = (): void => {
-    requestedWorkspacePathOpen = true
-    if (workspacePathOpen.getSnapshot() === undefined) loadWorkspacePathOpen()
-  }
-  ctx.on('connection/reset', () => {
-    capabilityRevision++
-    pendingCapability = undefined
-    workspacePathOpen.set(undefined)
-    if (requestedWorkspacePathOpen) loadWorkspacePathOpen()
-  })
   ctx.uiConversation.events.register(deliverablesDefinition)
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-deliverables: dictionaries')
   ctx.slots.inject(
@@ -72,11 +45,6 @@ export function apply(ctx: ClientContext): void {
       name: 'conversation.chat.turnTail',
       select: selectProducedFiles,
       locale: NS,
-      inject: () => ({
-        isLoopback: ctx.remote.$host.isLoopback,
-        ensureWorkspacePathOpen,
-        hooks: { workspacePathOpen },
-      }),
     }, ProducedFiles),
   )
   // The prose side of the same vocabulary: the chat view reaches this face
diff --git a/packages/client/ui-deliverables/src/client/locales.ts b/packages/client/ui-deliverables/src/client/locales.ts
index ec8b587b28..158b659f59 100644
--- a/packages/client/ui-deliverables/src/client/locales.ts
+++ b/packages/client/ui-deliverables/src/client/locales.ts
@@ -9,7 +9,6 @@ export const zh = {
   'produced.moreOne': '+ 1 个文件',
   'produced.more': '+ {count} 个文件',
   'produced.open': '打开 {name}',
-  'produced.showInFolder': '在文件夹中显示',
 }
 
 /** English dictionary (same key set). */
@@ -18,7 +17,6 @@ export const en: Record<DeliverablesKey, string> = {
   'produced.moreOne': '+ 1 file',
   'produced.more': '+ {count} files',
   'produced.open': 'Open {name}',
-  'produced.showInFolder': 'Show in folder',
 }
 
 /** Union of this namespace's dictionary keys. */
diff --git a/packages/client/ui-deliverables/tests/produced-files.client.spec.tsx b/packages/client/ui-deliverables/tests/produced-files.client.spec.tsx
index 49a93b4ade..9c006c93e7 100644
--- a/packages/client/ui-deliverables/tests/produced-files.client.spec.tsx
+++ b/packages/client/ui-deliverables/tests/produced-files.client.spec.tsx
@@ -20,8 +20,8 @@ import type {
 import { SlotRegistry } from '@deepseek-ai/dsh-client-ui-renderer/client'
 import { apply as applyLocale, inject as localeInject } from '@deepseek-ai/dsh-client-locale/client'
 import type { ChatFileMentions, TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-chat/client'
-import { makeTranslate, RemoteError, stubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime'
-import { ProducedFiles, type ProducedFilesInjected, type ProducedFilesProps } from '../src/client/ProducedFiles.tsx'
+import { makeTranslate, stubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime'
+import { ProducedFiles } from '../src/client/ProducedFiles.tsx'
 import {
   basename, deliverablesDefinition, producedFileMentions, producedForClosing, selectProducedFiles,
   type DeliverablesTurnData,
@@ -405,24 +405,12 @@ describe('produced-file Turn data', () => {
 
 describe('ProducedFiles row', () => {
   const t = makeTranslate(zh)
-  const capability = (
-    canOpenPath: boolean | undefined,
-    isLoopback = true,
-  ): Pick<ProducedFilesProps, 'isLoopback' | 'ensureWorkspacePathOpen' | 'useWorkspacePathOpen'> => {
-    return {
-      isLoopback,
-      ensureWorkspacePathOpen: () => {},
-      useWorkspacePathOpen: selector => selector(canOpenPath),
-    }
-  }
 
-  it('renders the bounded CSS candidates and opens a file or the workspace folder', () => {
+  it('renders the bounded chips and opens the file it was clicked for', () => {
     const paths = ['deep/a.html', 'b.css', 'c.ts', 'd.ts', 'e.ts', 'f.ts', 'g.ts', 'h.ts']
     const openFile = vi.fn<(path: string) => void>()
 
-    const view = render(
-      <ProducedFiles matched={paths} openFile={openFile} {...capability(true)} t={t} />,
-    )
+    const view = render(<ProducedFiles matched={paths} openFile={openFile} t={t} />)
     expect(view.getByText('产物')).toBeTruthy()
     const row = view.container.querySelector('[data-produced-files-row]')
     if (!(row instanceof HTMLElement)) throw new Error('produced row missing')
@@ -433,24 +421,27 @@ describe('ProducedFiles row', () => {
     expect(chip.getAttribute('title')).toBe('deep/a.html')
     expect(view.queryByRole('button', { name: '打开 g.ts' })).toBeNull()
     fireEvent.click(chip)
+    // The row hands over the path it was given; where it opens is the
+    // Sidebar's decision, not this row's.
     expect(openFile).toHaveBeenCalledWith('deep/a.html')
-
-    const showFolder = view.getByRole('button', { name: '在文件夹中显示' })
-    fireEvent.click(showFolder)
-    expect(openFile).toHaveBeenLastCalledWith('.')
   })
 
-  it('keeps the folder action absent without overflow or a local native opener', () => {
+  it('renders a remainder counter after every chip but the last when every file fits', () => {
+    const view = render(<ProducedFiles matched={['a.md', 'b.md', 'c.md']} openFile={() => {}} t={t} />)
+    const row = view.container.querySelector('[data-produced-files-row]')
+    if (!(row instanceof HTMLElement)) throw new Error('produced row missing')
+    expect(within(row).getAllByRole('button')).toHaveLength(3)
+    // One counter per chip that could be the last visible one; the final chip hides nothing.
+    expect([...row.querySelectorAll('[data-shown]')].map(node => node.getAttribute('data-shown'))).toEqual(['1', '2'])
+  })
+
+  it('offers no folder action, because a directory has no preview to open', () => {
     const openFile = vi.fn<(path: string) => void>()
-    const view = render(
-      <ProducedFiles matched={['a.md']} openFile={openFile} {...capability(true)} t={t} />,
-    )
     const overflowing = ['a.md', 'b.md', 'c.md', 'd.md', 'e.md', 'f.md', 'g.md']
+    const view = render(<ProducedFiles matched={overflowing} openFile={openFile} t={t} />)
     expect(view.queryByRole('button', { name: '在文件夹中显示' })).toBeNull()
-    for (const unavailable of [capability(false), capability(true, false), capability(undefined)]) {
-      view.rerender(<ProducedFiles matched={overflowing} openFile={openFile} {...unavailable} t={t} />)
-      expect(view.queryByRole('button', { name: '在文件夹中显示' })).toBeNull()
-    }
+    // Nothing in the row reaches the local machine any more.
+    expect(openFile).not.toHaveBeenCalled()
   })
 
   it('uses singular English copy when exactly one file is hidden', () => {
@@ -458,7 +449,6 @@ describe('ProducedFiles row', () => {
       <ProducedFiles
         matched={['a.md', 'b.md', 'c.md', 'd.md', 'e.md', 'f.md', 'g.md']}
         openFile={() => {}}
-        {...capability(false)}
         t={makeTranslate(en)}
       />,
     )
@@ -523,16 +513,9 @@ describe('plugin registration', () => {
     await fiber.await()
     const [entry] = ctx.slots.entries('conversation.chat.turnTail')
     expect(entry).toBeDefined()
-    const injected = entry?.inject?.() as unknown as ProducedFilesInjected
-    expect(injected.isLoopback).toBe(false)
-    expect(typeof injected.ensureWorkspacePathOpen).toBe('function')
-    expect(injected.hooks.workspacePathOpen.getSnapshot()).toBeUndefined()
-    ctx.emit('connection/reset')
-    injected.ensureWorkspacePathOpen()
-    await vi.waitFor(() => {
-      expect(injected.hooks.workspacePathOpen.getSnapshot()).toBe(true)
-    })
-    injected.ensureWorkspacePathOpen()
+    // The row needs no injected Host capability: it hands a path to its owner
+    // and nothing in it reaches the local machine.
+    expect(entry?.inject).toBeUndefined()
 
     // The prose face is live while the plugin is: a produced turn yields a
     // resolver whose matches open through the owner-supplied opener.
@@ -554,52 +537,4 @@ describe('plugin registration', () => {
     // Fiber teardown retracts the service: the consumer's ctx.get sees the off state.
     expect((ctx as unknown as { get(name: string): unknown }).get('chatFileMentions')).toBeUndefined()
   })
-
-  it('queries the workspace opener lazily and replaces stale results after reconnect', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SlotRegistry).await()
-    new UiConversation(ctx, { binding: () => undefined } as never)
-    ctx.slots.register({
-      name: 'root',
-      children: { 'conversation.chat.turnTail': { kind: 'chain', scope: 'session' } },
-    } as never, () => null)
-    const first = Promise.withResolvers<{ ok: true; value: boolean }>()
-    const second = Promise.withResolvers<{ ok: true; value: boolean }>()
-    const staleFailure = Promise.withResolvers<{ ok: false; error: RemoteError }>()
-    const capability = vi.fn()
-      .mockReturnValueOnce(first.promise)
-      .mockReturnValueOnce(second.promise)
-      .mockReturnValueOnce(staleFailure.promise)
-      .mockResolvedValueOnce({ ok: false, error: new RemoteError('gateway/internal', 'offline', {}) })
-    const session = { canOpenWorkspacePath: capability }
-    ctx.provide('remote', {
-      $on: () => () => {},
-      $host: { home: undefined, isLoopback: true },
-      session,
-    } as never)
-    ctx.provide('remote.session', session as never)
-    ctx.provide('settingsScope', { bind: () => stubSettingsScope().scope } as never)
-    await ctx.plugin({ inject: localeInject, apply: applyLocale }).await()
-    const fiber = ctx.plugin({ inject: [...inject], apply })
-    await fiber.await()
-    const entry = ctx.slots.entries('conversation.chat.turnTail')[0]
-    const injected = entry?.inject?.() as unknown as ProducedFilesInjected
-
-    injected.ensureWorkspacePathOpen()
-    injected.ensureWorkspacePathOpen()
-    expect(capability).toHaveBeenCalledOnce()
-    ctx.emit('connection/reset')
-    expect(capability).toHaveBeenCalledTimes(2)
-    first.resolve({ ok: true, value: false })
-    await Promise.resolve()
-    expect(injected.hooks.workspacePathOpen.getSnapshot()).toBeUndefined()
-    second.resolve({ ok: true, value: true })
-    await vi.waitFor(() => { expect(injected.hooks.workspacePathOpen.getSnapshot()).toBe(true) })
-
-    ctx.emit('connection/reset')
-    ctx.emit('connection/reset')
-    staleFailure.resolve({ ok: false, error: new RemoteError('gateway/internal', 'stale offline', {}) })
-    await vi.waitFor(() => { expect(injected.hooks.workspacePathOpen.getSnapshot()).toBe(false) })
-    await fiber.dispose()
-  })
 })
diff --git a/packages/client/ui-dockkit/README.i18n.yaml b/packages/client/ui-dockkit/README.i18n.yaml
new file mode 100644
index 0000000000..bd0993ceba
--- /dev/null
+++ b/packages/client/ui-dockkit/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/client/ui-dockkit/README.md
+README.md: e012295852ad3c957695fcfbd0568a45b3f54856
+README.zh.md: 2423887d60460651a224ffe1cb0fc9b61363c0e2
diff --git a/packages/client/ui-dockkit/README.md b/packages/client/ui-dockkit/README.md
new file mode 100644
index 0000000000..e012295852
--- /dev/null
+++ b/packages/client/ui-dockkit/README.md
@@ -0,0 +1,107 @@
+---
+description: "Docking layout kit for the dsh web client: a split tree of tabbed panes with invertible operations, planners, a linear history, and the components that render and drive it."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-client-ui-dockkit
+
+English | [中文](README.zh.md)
+
+## Summary
+
+A docking layout kit: a split tree of tabbed panes with invertible operations, and the components that render and drive it. The Harness Web client is its first embedder; nothing in here knows that.
+
+> **Internal engine.** This package is published because the Sidebar links it statically, not as a stable API: its exports — `LayoutState`, `LayoutOp`, the planners, `DockIntents`, `DockLabels`, `DockMode` — may change in any release, and none of them appears in a service interface (`ctx.sidebarRight` exposes operations, never layout snapshots or operation logs).
+
+## Table of Contents
+
+- [The two layers](#the-two-layers)
+- [Embedding it](#embedding-it)
+- [Interaction rules worth keeping](#interaction-rules-worth-keeping)
+- [Build shape](#build-shape)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="the-two-layers"></a>
+## The two layers
+
+**The engine** is pure logic — no UI framework, no DOM, no host concepts.
+
+- A normalized recursive split tree: `nodes` keyed by id, `rootId` for the docked root, `floats` bottom-to-top. `PaneId`, `SplitId`, and `TabId` are branded strings: only a `Mint` (or the kit's own DOM round trip) produces one, so a pane, a split, and a tab never stand in for one another or for a bare string. A floating panel is not a second concept — it is a pane whose `host` is `'float'`, capacity one tab, drawn without a tab strip.
+- `applyOp(state, op)` returns the next state **and the operations that undo it**. Inverses are captured when an operation runs, because by undo time the pre-operation state is gone.
+- Every operation carries the ids it creates, so `replay(initial, ops)` reproduces the same tree. The engine reads no clock and no random source.
+- `Sequencer` keeps a linear history with one entry per intent: the operations one gesture or command produced step back and forward together, a run of consecutive focus-only entries steps as one, and a new entry after stepping back drops the forward branch.
+- `planSettle` is the opt-in rule that keeps every docked pane populated after an intent: panes an intent emptied are merged away, and an emptied root pane is reseeded through the embedder's factory. An embedder that wants empty panes simply does not call it.
+- `DockController` is the intent layer and an observable source (`subscribe` + `getSnapshot`, whose reference only changes when the layout does).
+
+**The components** render a layout snapshot and report settled intents — one per gesture, never a drag frame. A drag previews in local state while the gesture's own facts stay in its closure; on release the net result leaves through one `DockIntents` call — a strip release reports the caret slot as drawn, the dragged chip counted, and `planPlaceTab` turns that into the reorder or the move. That is what lets an embedder record exactly one history entry per gesture. The strip follows the WAI-ARIA tabs pattern with manual activation: the selected chip is in the tab order; Left and Right (wrapping), Home, and End move focus between chips without selecting; Enter or Space selects the focused chip through the same intent as a click. A chip is a capsule carrying one control, its close; the context menu (a secondary press on the chip) carries the same close plus the embedder's items, and renders in a portal positioned against the chip because the chip box clips its overflow on purpose (see below). After the chips sits the add control, which asks the embedder (`DockIntents.addTab`) to seat its seeded tab; the embedder's `canAddTab(paneId)` decides per pane whether the control is drawn at all. Copying a tab has no kit control — it is the embedder's API — and floating is the drag released clear of the surface.
+
+<a id="embedding-it"></a>
+## Embedding it
+
+Everything host-specific arrives through props:
+
+| Contract | Carries |
+|---|---|
+| `DockLabels` | every rendered string, already localized, accessible names included |
+| `TabRenderer` | one tab's body (`renderTab`), and optionally what its chip or panel header shows as a title (`renderTabTitle`, falling back to the record's `title`); the embedder dispatches on `tab.kind` |
+| `DockIntents` | the settled results of every gesture |
+
+`DockController` satisfies `DockIntents` as written, so the simplest embedding hands the controller straight to `DockSurface`. An embedder that routes through its own store implements the same method names instead. Two props carry control policy rather than gestures: `canSplit` (surface-wide, the pane budget; disables the split control with `splitPaneDisabled`) and `canAddTab(paneId)` (per pane, omits the add control; leave it out to draw one in every pane). Hiding the add control moves nothing else in the strip. The kit adds one policy of its own, the room rule below, which disables a pane's split control with `splitPaneNarrow`; `onRoom(fits)` reports its readings so an embedder splitting programmatically can honour the same rule.
+
+`dropZones="horizontal"` offers two half-pane hints; once budget or width forbids another split, the whole body accepts a move. `minPaneFraction` sets the preview minimum, and `planResizeSplit` accepts the same minimum for the committed operation. The Sidebar uses 0.2 and enforces two panes in its own store. The generic engine retains its tree and other split directions. `hideSplitAtCapacity` hides the split control at the pane budget; its default is false, and a width-blocked control remains disabled.
+
+A tab's `kind` is an opaque string. Seeded tabs are factories (`DockControllerOptions`), so what a fresh pane contains is the embedder's decision, not this package's. Content identity is the pair (`kind`, `contentId`): `findContentTab(state, contentId, kind?)` finds the tab showing it anywhere and `findPaneContentTab(state, paneId, contentId, kind?)` within one pane, and `planOpenContent` focuses that tab instead of opening another unless told `revealIfOpened: false`; an explicit `index` seats a new tab at a strip slot rather than at the end.
+
+`DockSurface` is the docked area. Chrome around it — a rail, a collapsed presentation, any history controls — belongs to the embedder, which reads `state.expanded` and decides; the kit ships no undo/redo control of its own. Surface-wide controls the embedder does want on the surface go through the `chrome` prop, which the kit places at the far end of the top-right pane's tab strip (the last child of every row split, the first of every column split), so a surface needs no header row of its own. `FloatLayer` owns its own gestures and positions panels in viewport coordinates, so it may be mounted anywhere, including a portal.
+
+<a id="interaction-rules-worth-keeping"></a>
+## Interaction rules worth keeping
+
+These are not stylistic; each one fixes a defect found in a real browser.
+
+- **Capture the pointer** when a gesture starts. Without it any scroll container the pointer crosses can claim the gesture, which the browser reports as a cancelled pointer and an abandoned drag. Capture is hardening — the window listeners carry the gesture either way, so an environment without the API still works.
+- **The chips give way; the strip's end controls never do.** The chip box is the strip's one shrinking part (`flex: 0 1 auto; min-width: 0; overflow: hidden`); the add, split, and chrome controls are `flex: none`, so they keep their width and place in any pane at least as wide as they are (about 130px with the chrome, 72px without). The surface's `min-width: 0` and the pane's `overflow: hidden` stop a body's longest unwrapped line from widening the pane past its box, which is what carried the controls and the body's scrollbar off-screen.
+- **The chip box is not a scroll container.** A horizontal scroller claims press-and-move for itself; tabs shrink, ellipsize, and then clip instead.
+- **A split needs room for two working halves.** A pane splits into equal halves, so each half must hold what cannot shrink: the strip's fixed part — measured as the strip's width minus the chip box and the fill, which is the padding, the gaps, and every control that pane draws (its own chrome included, so the top-right pane asks more) — plus one chip at its minimum — `.tab` declares `min-width: 44px` on a content-box, so its footprint is 44px plus 10px + 5px of padding, 59px, read from a rendered chip's computed style (the stylesheet figure when none can be read); the divider between the halves takes its rendered thickness (4px). A column split, which only an edge drop makes, needs each half to hold the strip (36px) plus a 48px body: one 13px secondary line at 1.6 line-height inside the body's 12px padding. `halvesFit` in `geometry.ts` is the arithmetic; `measure.ts` reads the rectangles after every commit and whenever the surface resizes, because the layout state carries fractions, never pixels, and the engine's planners stay that way. A pane without room keeps its split control, disabled with `splitPaneNarrow`, and offers no edge drop zone for that axis (the release is then not a move). A pane the user narrows afterwards — a divider or the embedder's column dragged — keeps its size: the rule only decides its next split.
+- **Focus lands on click, not on press.** A state change between `pointerdown` and the first `pointermove` rebuilds the pressed subtree, and a replaced element cancels the pointer. It also keeps a drag from recording a redundant focus operation first. Clicks on the chips, the strip's controls, and the embedder's chrome stop at the strip: the intent each reports already decides the active pane, or is the embedder's own, so the pane's click-to-focus records nothing extra. A floating panel's grip and corner report through their gesture the same way — a press released in place is a click that raises the panel, and a drag records only the move or resize, whose operation raises it — while a press on the panel's body raises it directly. A click on the pane that is active already, a click or key on that pane's selected chip, or a press on the panel that is active and on top already, changes nothing and records nothing.
+- **A control nested inside a draggable chip stops its own press.** Otherwise the press starts a drag, captures the pointer, and the nested control's click never lands.
+- **Emphasis takes the platform's accent, never `--dsw-alias-brand-primary`.** This platform binds `brand-primary` to its near-black (light) or near-white (dark) foreground, so a hovered divider, the drop caret, and the drop-zone hint use `--dsw-alias-brand-primary-new-colorprimary-new-color`, as the trajectory views do. A floating panel's border is the same `--dsw-alias-border-l2` hairline whether it is active or not: the active panel is already on top and casts the shadow; a darker frame around it read as a defect.
+
+<a id="build-shape"></a>
+## Build shape
+
+The package is statically linked: tsdown's `staticLinked` preset emits one browser ESM bundle at `lib/index.js` (every bare specifier stays an import, sourcemaps chain to the sources) and ships the stylesheet under `lib/` at its `src`-relative path, and the Web shell resolves the package name and bundles that artifact itself, so vite stays the only owner of class hashing. One consequence is load-bearing — the kit keeps **one** stylesheet, `dockkit.module.css`, because a consumer de-duplicates injected sheets by file name and a collision would drop one silently.
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as the package is a browser-side docking layout engine and component set that registers nothing model-facing.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Size semantics are deliberately small**: fractional weights with one minimum-size clamp. No snap, priority, or preferred size, so the cascading-squeeze behaviour of a full splitview is absent.
+- **Touch is untuned.** Gestures are pointer-based and `touch-action` is set where a scroller would otherwise interfere, but no touch-specific tuning has been done.
+- **Accessibility is incomplete**: no `separator` role on dividers and no keyboard route to split, move, or float.
+- **No published stylesheet contract.** Consumers get hashed module class names; the kit exposes no theming API beyond the `--dsw-*` custom properties it reads.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>
+
+**Runtime invariant:** No companion is published. The engine is pure functions over plain data and the components report intents only; the operation sequence's invertibility and the settle rule are asserted directly by this package's engine specs, and no cordis service is provided or observed.
diff --git a/packages/client/ui-dockkit/README.zh.md b/packages/client/ui-dockkit/README.zh.md
new file mode 100644
index 0000000000..2423887d60
--- /dev/null
+++ b/packages/client/ui-dockkit/README.zh.md
@@ -0,0 +1,107 @@
+---
+description: "dsh Web 客户端的停靠布局套件：带可逆操作的标签格分裂树、planner、线性历史，以及渲染并驱动它的组件。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-client-ui-dockkit
+
+[English](README.md) | 中文
+
+## 概述
+
+一套停靠布局套件：由带可逆操作的标签格组成的分裂树，以及渲染并驱动它的组件。Harness Web 客户端是它的第一个嵌入方；这里的代码对此一无所知。
+
+> **内部引擎。** 本包之所以发布，是因为 Sidebar 以静态链接方式使用它，而非作为稳定 API：它的导出——`LayoutState`、`LayoutOp`、各 planner、`DockIntents`、`DockLabels`、`DockMode`——在任何版本都可能变化，并且没有任何一个出现在服务接口里（`ctx.sidebarRight` 只暴露操作，从不暴露布局快照或操作日志）。
+
+## 目录
+
+- [两层结构](#the-two-layers)
+- [如何嵌入](#embedding-it)
+- [值得保留的交互规则](#interaction-rules-worth-keeping)
+- [构建形态](#build-shape)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="the-two-layers"></a>
+## 两层结构
+
+**引擎**是纯逻辑——没有 UI 框架、没有 DOM、没有宿主概念。
+
+- 一棵归一化的递归分裂树：按 id 索引的 `nodes`、指向停靠根的 `rootId`、自底向上排列的 `floats`。`PaneId`、`SplitId`、`TabId` 是带 brand 的字符串：只有 `Mint`（或库自己的 DOM 往返）能产出，因此 pane、split、tab 三种 id 彼此不可互换，也不能拿裸字符串充数。浮窗不是第二个概念——它就是 `host` 为 `'float'` 的格，容量一个 tab，绘制时不带 tab 条。
+- `applyOp(state, op)` 返回下一状态**以及撤销它的操作**。逆操作在操作执行时捕获，因为到撤销时操作前的状态已经不存在了。
+- 每个操作都携带它创建的 id，因此 `replay(initial, ops)` 能复现同一棵树。引擎不读时钟，也不读随机源。
+- `Sequencer` 维护一条线性历史，每个意图一条记录：一次手势或命令产生的操作一起后退、一起前进，连续的纯焦点记录作为一步，后退后的新记录会丢弃前进分支。
+- `planSettle` 是可选加入的规则，保证意图之后每个停靠格都有内容：被意图清空的格会被并掉，被清空的根格通过嵌入方的工厂重新播种。想要空格的嵌入方只需不调用它。
+- `DockController` 是意图层，也是一个可观察源（`subscribe` + `getSnapshot`，其引用只在布局变化时才变）。
+
+**组件**渲染布局快照并上报已落定的意图——每次手势一条，绝不上报拖动帧。拖动过程中在本地状态里预览，手势自身的事实留在它的闭包里；松手时净结果通过一次 `DockIntents` 调用离开——在标签条上松手上报的是按绘制顺序数出的插入槽位（被拖的 chip 也计入），由 `planPlaceTab` 换算成重排或移动。正是这一点让嵌入方能为每次手势记录恰好一条历史。标签条遵循 WAI-ARIA tabs 模式的手动激活：选中的 chip 在 Tab 键序里；左右方向键（循环）、Home、End 只在 chip 之间移动焦点而不选中；Enter 或空格选中当前聚焦的 chip，走与点击相同的意图。chip 是一个胶囊，携带唯一的控件——它的关闭按钮；上下文菜单（在 chip 上的次键按下）携带同样的关闭项加上嵌入方的条目，并渲染在按 chip 定位的 portal 里，因为 chip 盒会故意裁掉溢出（见下文）。chip 之后是添加控件，它请嵌入方（`DockIntents.addTab`）安放其种子 tab；嵌入方的 `canAddTab(paneId)` 按格决定是否绘制该控件。复制 tab 没有套件控件——那是嵌入方的 API——而浮出就是把拖动松手在停靠区之外。
+
+<a id="embedding-it"></a>
+## 如何嵌入
+
+一切宿主相关的东西都通过 props 进入：
+
+| 契约 | 承载内容 |
+|---|---|
+| `DockLabels` | 每一个渲染出来的字符串，已本地化，含无障碍名称 |
+| `TabRenderer` | 一个 tab 的正文（`renderTab`），以及可选的 chip 或浮窗头部显示的标题（`renderTabTitle`，回退到记录的 `title`）；嵌入方按 `tab.kind` 分发 |
+| `DockIntents` | 每次手势落定的结果 |
+
+`DockController` 原样满足 `DockIntents`，所以最简单的嵌入就是把 controller 直接交给 `DockSurface`。经由自己 store 路由的嵌入方则实现同名方法。有两个 props 承载的是控制策略而非手势：`canSplit`（整面有效，即格预算；用 `splitPaneDisabled` 禁用分栏控件）与 `canAddTab(paneId)`（按格，省略添加控件；不传则每格都画）。隐藏添加控件不会移动 tab 条里的其它任何东西。套件自己再加一条策略，即下文的空间规则，它用 `splitPaneNarrow` 禁用某格的分栏控件；`onRoom(fits)` 上报其读数，让以编程方式分栏的嵌入方能遵守同一规则。
+
+`dropZones="horizontal"` 提供左右两个半区提示；预算或宽度不允许再拆时，正文整格接收移动。`minPaneFraction` 控制预览的最小比例，`planResizeSplit` 接受相同最小值以约束提交；Sidebar使用0.2并在自己的store限制两格。通用引擎仍保留原有树与其它分割方向。 `hideSplitAtCapacity` 在达到窗格预算时隐藏分栏控件，默认值为 false；宽度不足的控件仍以禁用状态显示。
+
+tab 的 `kind` 是不透明字符串。种子 tab 是工厂（`DockControllerOptions`），因此新格里放什么由嵌入方决定，与本包无关。内容身份是二元组（`kind`、`contentId`）：`findContentTab(state, contentId, kind?)` 在任意位置找到展示它的 tab，`findPaneContentTab(state, paneId, contentId, kind?)` 在一个格内找；`planOpenContent` 会聚焦该 tab 而非再开一个，除非被告知 `revealIfOpened: false`；显式的 `index` 把新 tab 放到 tab 条的某个位置而非末尾。
+
+`DockSurface` 是停靠区。它周围的 chrome——轨道、折叠形态、任何历史控件——属于嵌入方，由嵌入方读取 `state.expanded` 后自行决定；套件不自带撤销/重做控件。嵌入方确实想放到面上的整面控件通过 `chrome` prop 传入，套件把它放在右上格 tab 条的最末端（每个横向分裂的最后一个子节点、每个纵向分裂的第一个子节点），因此停靠面不需要自己的标题行。`FloatLayer` 拥有自己的手势并以视口坐标定位浮窗，因此可以挂在任何位置，包括 portal 里。
+
+<a id="interaction-rules-worth-keeping"></a>
+## 值得保留的交互规则
+
+这些不是风格偏好；每一条都修复了在真实浏览器里发现的缺陷。
+
+- **手势开始时捕获指针。** 不捕获的话，指针经过的任何滚动容器都可能接管手势，浏览器会将其报告为指针取消和拖动中止。捕获是加固——无论如何都由 window 监听器承载手势，所以没有该 API 的环境照样可用。
+- **chip 让位；tab 条末端的控件永不让位。** chip 盒是 tab 条里唯一会收缩的部分（`flex: 0 1 auto; min-width: 0; overflow: hidden`）；添加、分栏与 chrome 控件都是 `flex: none`，因此在任何不窄于它们自身的格里（带 chrome 约 130px，不带约 72px）都保持宽度与位置。停靠面的 `min-width: 0` 与格的 `overflow: hidden` 阻止正文里最长的不换行行把格撑出自己的盒子——正是那种情况把控件和正文滚动条推到了屏幕外。
+- **chip 盒不是滚动容器。** 横向滚动容器会把按下并移动据为己有；tab 转而收缩、省略、然后被裁切。
+- **分栏需要给两个可用的半格留出空间。** 格被等分成两半，因此每一半都必须容得下不可收缩的部分：tab 条的固定部分——按 tab 条宽减去 chip 盒与填充条测得，即内边距、间隙以及该格绘制的每个控件（含它自己的 chrome，所以右上格要求更多）——加上一枚最小尺寸的 chip——`.tab` 在 content-box 上声明 `min-width: 44px`，所以它的足印是 44px 加 10px + 5px 内边距，即 59px，从已渲染 chip 的计算样式读取（读不到时用样式表数值）；两半之间的分隔条取其渲染厚度（4px）。纵向分栏只由边缘落下产生，它要求每一半容得下 tab 条（36px）加 48px 正文：正文 12px 内边距内一行 13px、行高 1.6 的次级文字。`geometry.ts` 里的 `halvesFit` 是算术；`measure.ts` 在每次提交后与停靠面尺寸变化时读取矩形，因为布局状态只携带比例、从不携带像素，引擎的 planner 也保持如此。没有空间的格保留分栏控件，以 `splitPaneNarrow` 禁用，并且在该轴上不提供边缘落区（松手就不是移动）。用户随后把格拖窄——拖分隔条或拖嵌入方的列——的格保持原尺寸：规则只决定它的下一次分栏。
+- **焦点落在 click 而不是按下。** 在 `pointerdown` 与第一次 `pointermove` 之间的状态变化会重建被按下的子树，而被替换的元素会取消指针。这也避免拖动先记录一条多余的焦点操作。chip、标签条各控件以及嵌入方 chrome 上的 click 都止于标签条：它们各自上报的意图已决定了活动格，或本就是嵌入方自己的事，所以格自身的点击聚焦不再多记一条。浮动面板的抓手与角柄同样通过手势上报——原地松开的按下是一次 click，抬起面板；真正的拖动只记录移动或缩放，由该操作自己抬起面板——而按在面板主体上则直接抬起它。点击本已活动的格、点击或按键选中该格本已选中的 chip，或按下本已活动且在最上层的面板，什么都不改变，也什么都不记录。
+- **嵌套在可拖动 chip 里的控件要拦住自己的按下。** 否则按下会开始拖动、捕获指针，嵌套控件的 click 就永远落不下。
+- **强调色用平台的强调 token，绝不用 `--dsw-alias-brand-primary`。** 本平台把 `brand-primary` 绑定到近黑（浅色）或近白（深色）的前景色，因此悬停的分隔条、落点光标与落区提示都用 `--dsw-alias-brand-primary-new-colorprimary-new-color`，与轨迹视图一致。浮窗的边框无论是否活动都是同一条 `--dsw-alias-border-l2` 细线：活动浮窗本就在最上层并投下阴影；围它一圈更深的边框读起来像缺陷。
+
+<a id="build-shape"></a>
+## 构建形态
+
+本包静态链接：tsdown 的 `staticLinked` 预设在 `lib/index.js` 产出一个浏览器 ESM bundle（所有裸说明符保持为 import，sourcemap 链回源码），并把样式表按其相对 `src` 的路径放到 `lib/` 下；Web 外壳按包名解析并自行打包该产物，因此 vite 仍是 class 哈希的唯一拥有者。有一个后果是承重的——套件只保留**一张**样式表 `dockkit.module.css`，因为消费方按文件名去重注入的样式表，撞名会静默丢掉一张。
+
+<a id="model-experience"></a>
+## 模型体验
+
+None, as the package is a browser-side docking layout engine and component set that registers nothing model-facing.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **尺寸语义刻意保持精简**：比例权重加一处最小尺寸夹取。没有吸附、优先级或首选尺寸，因此完整 splitview 的级联挤压行为不存在。
+- **触控未调优。** 手势基于 pointer 事件，并在滚动容器可能干扰处设置了 `touch-action`，但没有做过触控专项调优。
+- **无障碍不完整**：分隔条没有 `separator` 角色，也没有键盘路径去分栏、移动或浮出。
+- **没有发布样式表契约。** 消费方拿到的是哈希化的模块类名；套件除读取的 `--dsw-*` 自定义属性外不暴露任何主题 API。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文——点击展开</summary>
+
+无。
+
+</details>
+
+**运行时不变量：** 不发布 companion。引擎是作用于纯数据的纯函数，组件只上报意图；操作序列的可逆性与 settle 规则由本包的引擎 spec 直接断言，不提供也不观察任何 cordis 服务。
diff --git a/packages/client/ui-dockkit/package.json b/packages/client/ui-dockkit/package.json
new file mode 100644
index 0000000000..984daeca2a
--- /dev/null
+++ b/packages/client/ui-dockkit/package.json
@@ -0,0 +1,46 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-dockkit",
+  "description": "Docking layout kit: split-tree engine with invertible operations, and the React components that render and drive it (zero cordis)",
+  "version": "0.1.3-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/ui-dockkit"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "clsx": "^2.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "workspace:^",
+    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "react-dom": "^18.2.0"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/**/*.css",
+    "lib/types/**/*.d.ts"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "workspace:^"
+  }
+}
diff --git a/packages/client/ui-dockkit/src/components/DockSurface.tsx b/packages/client/ui-dockkit/src/components/DockSurface.tsx
new file mode 100644
index 0000000000..4ff0d3789d
--- /dev/null
+++ b/packages/client/ui-dockkit/src/components/DockSurface.tsx
@@ -0,0 +1,286 @@
+/**
+ * The docked surface: the split tree plus the tab and divider gestures over it.
+ * This is the whole kit as far as an embedder's layout column is concerned —
+ * chrome around it (a rail, a header, a collapsed state) belongs to the embedder.
+ *
+ * A gesture only previews until it ends, then leaves through one intent, so the
+ * embedder's operation sequence stays the single source of truth. Releasing a tab
+ * clear of this surface floats it; releasing inside it but on no pane is not a
+ * move at all.
+ */
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
+import type { ReactNode } from 'react'
+import type { DockIntents, DockLabels, TabMenuExtras, TabRenderer } from '../contract/adapter.ts'
+import type { LayoutState, PaneId, SplitId, TabId } from '../contract/types.ts'
+import { clampSizes, FLOAT_DEFAULT_SIZE, MIN_PANE_FRACTION } from '../engine/constraints.ts'
+import { getSplit, topRightPaneId } from '../engine/tree.ts'
+import type { DropTarget, HalvesFit } from '../engine/geometry.ts'
+import {
+  containsPoint, dividerSizes, floatRectAt, insertionIndex, passedThreshold, zoneInRect,
+} from '../engine/geometry.ts'
+import { fitOf, measurePaneFits, paneElements, sameFits } from './measure.ts'
+import { useGesture } from './pointer.ts'
+import { PaneTree, type SizePreview } from './PaneTree.tsx'
+import type { PaneCallbacks, SplitBlock } from './render.ts'
+import css from './dockkit.module.css'
+
+/** What the docked surface needs: the layout, its limits, and the outward contracts. */
+export interface DockSurfaceProps {
+  readonly state: LayoutState
+  /**
+   * Whether another pane may still be created: the pane budget. Width is the
+   * kit's own concern — a pane too narrow for two working halves keeps its
+   * split control disabled with `labels.splitPaneNarrow` (see README).
+   */
+  readonly canSplit: boolean
+  /** Hide the split control when the pane budget is spent; defaults to false. Width-blocked controls remain disabled. */
+  readonly hideSplitAtCapacity?: boolean
+  /** Body drop geometry: all edge bands, or left/right halves with whole-pane moves once splitting is unavailable. */
+  readonly dropZones?: 'edges' | 'horizontal'
+  /** Smallest share a divider may leave a pane; defaults to the kit's fraction. */
+  readonly minPaneFraction?: number
+  /**
+   * Whether a pane's strip draws the add control. Called per docked pane on
+   * every render; omit to draw one in every pane. `false` leaves the strip's
+   * end controls where they are and the chips as the only shrinking part.
+   */
+  readonly canAddTab?: (paneId: PaneId) => boolean
+  readonly intents: DockIntents
+  readonly labels: DockLabels
+  readonly renderTab: TabRenderer
+  /**
+   * What a tab's chip shows as its title; omit to show the record's `title`
+   * text. An embedder-internal seam: the Sidebar dispatches it to a per-kind
+   * slot, and nothing outside that embedder is expected to supply it.
+   */
+  readonly renderTabTitle?: TabRenderer
+  /** Extra items for a tab's context menu; omit for the kit's own item only. */
+  readonly renderTabMenuItems?: TabMenuExtras
+  /**
+   * Surface-wide controls, drawn at the far end of the top-right pane's tab
+   * strip so the surface needs no header of its own. The kit places them; what
+   * they do is the embedder's.
+   */
+  readonly chrome?: ReactNode
+  /**
+   * Called with the room rule's latest readings whenever they change, so an
+   * embedder driving splits programmatically can honour the same rule the
+   * split control does. A pane absent from the map has not been measured.
+   */
+  readonly onRoom?: (fits: ReadonlyMap<PaneId, HalvesFit>) => void
+}
+
+/** A divider drag: the split it moves and the fractions it started from. */
+interface DividerDrag {
+  readonly splitId: SplitId
+  /** The boundary being moved: between child `index` and `index + 1`. */
+  readonly index: number
+  readonly axis: 'row' | 'column'
+  /** Pointer coordinate along the axis at the press. */
+  readonly origin: number
+  /** The split's pixel extent along the axis, so travel converts to fractions. */
+  readonly extent: number
+  readonly sizes: readonly number[]
+}
+
+/** What the gesture is currently showing, before anything settles. */
+interface Preview {
+  readonly draggingTabId: TabId | undefined
+  readonly dropTarget: DropTarget | undefined
+  readonly sizes: SizePreview | undefined
+}
+
+const NO_PREVIEW: Preview = { draggingTabId: undefined, dropTarget: undefined, sizes: undefined }
+
+/** Nothing measured yet: every pane fits until a reading says otherwise. */
+const NO_FITS: ReadonlyMap<PaneId, HalvesFit> = new Map()
+
+/** The default add-control policy: every pane offers one. */
+const ALWAYS = (): boolean => true
+
+/**
+ * Resolve where a pointer sits inside the docked surface. An edge zone is only
+ * offered where the split it would make is allowed: within the pane budget and
+ * with room for two halves; otherwise the release is not a move at all.
+ */
+function hitTest(
+  root: HTMLElement,
+  x: number,
+  y: number,
+  canSplit: boolean,
+  fits: ReadonlyMap<PaneId, HalvesFit>,
+  dropZones: 'edges' | 'horizontal',
+): DropTarget | undefined {
+  for (const [paneId, pane] of paneElements(root)) {
+    const rect = pane.getBoundingClientRect()
+    if (!containsPoint(rect, x, y)) continue
+    const strip = pane.querySelector<HTMLElement>('[data-dockkit-strip]')
+    if (strip !== null && containsPoint(strip.getBoundingClientRect(), x, y)) {
+      const tabs = [...strip.querySelectorAll<HTMLElement>('[data-dockkit-tab]')]
+      return { kind: 'strip', paneId, index: insertionIndex(tabs.map(tab => tab.getBoundingClientRect()), x) }
+    }
+    const zone = dropZones === 'horizontal'
+      ? canSplit && fitOf(fits, paneId).row
+        ? x < rect.x + rect.width / 2 ? 'left' : 'right'
+        : 'center'
+      : zoneInRect(rect, x, y)
+    if (zone !== 'center') {
+      const fit = fitOf(fits, paneId)
+      const room = zone === 'left' || zone === 'right' ? fit.row : fit.column
+      if (!canSplit || !room) return undefined
+    }
+    return { kind: 'zone', paneId, zone }
+  }
+  return undefined
+}
+
+/** Fractions a divider drag has reached, clamped to the pane minimum. */
+function draggedSizes(drag: DividerDrag, x: number, y: number, minimum: number): readonly number[] {
+  const moved = (drag.axis === 'row' ? x : y) - drag.origin
+  const delta = drag.extent > 0 ? moved / drag.extent : 0
+  return clampSizes(dividerSizes(drag.sizes, drag.index, delta), minimum)
+}
+
+/** Fractions closer than this are the same split: renormalizing recorded sizes moves them by no more. */
+const SIZE_TOLERANCE = 1e-9
+
+/** Whether two fraction lists describe the same split. */
+function sameSizes(a: readonly number[], b: readonly number[]): boolean {
+  return a.length === b.length && a.every((size, index) => {
+    const other = b[index]
+    return other !== undefined && Math.abs(size - other) < SIZE_TOLERANCE
+  })
+}
+
+/** The split tree and the gestures over it. */
+export function DockSurface({
+  state, canSplit, canAddTab, intents, labels, renderTab, renderTabTitle, renderTabMenuItems, chrome, onRoom,
+  dropZones = 'edges', minPaneFraction = MIN_PANE_FRACTION, hideSplitAtCapacity = false,
+}: DockSurfaceProps): ReactNode {
+  const surface = useRef<HTMLDivElement | null>(null)
+  const [preview, setPreview] = useState<Preview>(NO_PREVIEW)
+  const [fits, setFits] = useState(NO_FITS)
+  const begin = useGesture(() => { setPreview(NO_PREVIEW) })
+
+  /** Run `use` on the surface element, which every commit and every press inside it has mounted. */
+  const withSurface = useCallback((use: (root: HTMLElement) => void): void => {
+    const root = surface.current
+    /* v8 ignore next -- ref-null guard: the surface div renders unconditionally. */
+    if (root === null) return
+    use(root)
+  }, [])
+
+  // The room rule reads pixels, which the layout state does not carry: measure
+  // after every commit (a split, a divider drag, a closed tab all move panes)
+  // and whenever the surface itself is resized (the embedder's column dragged
+  // wider or narrower). A reading that changed nothing renders nothing.
+  const remeasure = useCallback((): void => {
+    withSurface((root) => {
+      const next = measurePaneFits(root)
+      setFits(current => sameFits(current, next) ? current : next)
+    })
+  }, [withSurface])
+  useLayoutEffect(() => { remeasure() })
+  useEffect(() => { onRoom?.(fits) }, [fits, onRoom])
+  useEffect(() => {
+    const root = surface.current
+    if (root === null || typeof ResizeObserver === 'undefined') return undefined
+    const observer = new ResizeObserver(() => { remeasure() })
+    observer.observe(root)
+    return () => { observer.disconnect() }
+  }, [remeasure])
+
+  /** Why a pane cannot split right now: the budget first, then its own width. */
+  const splitBlock = (paneId: PaneId): SplitBlock | undefined => {
+    if (!canSplit) return 'budget'
+    return fitOf(fits, paneId).row ? undefined : 'width'
+  }
+
+  const callbacks: PaneCallbacks = {
+    onFocusTab: intents.focusTab.bind(intents),
+    onFocusPane: intents.focusPane.bind(intents),
+    onSplitPane: intents.splitPane.bind(intents),
+    onAddTab: intents.addTab.bind(intents),
+    onCloseTab: intents.closeTab.bind(intents),
+    // A press is not yet a drag: the chip lifts, and the drop preview follows,
+    // once the pointer has travelled the threshold. A release before that is a
+    // click and reports nothing here.
+    onTabPressed: (tabId, event) => {
+      withSurface((root) => {
+        const startX = event.clientX
+        const startY = event.clientY
+        let dragging = false
+        begin(event.currentTarget, event.pointerId, {
+          move: (moved) => {
+            if (!dragging) {
+              if (!passedThreshold(startX, startY, moved.clientX, moved.clientY)) return
+              dragging = true
+            }
+            setPreview({
+              ...NO_PREVIEW,
+              draggingTabId: tabId,
+              dropTarget: hitTest(root, moved.clientX, moved.clientY, canSplit, fits, dropZones),
+            })
+          },
+          up: (released) => {
+            if (!dragging) return
+            const target = hitTest(root, released.clientX, released.clientY, canSplit, fits, dropZones)
+            if (target === undefined) {
+              if (containsPoint(root.getBoundingClientRect(), released.clientX, released.clientY)) return
+              intents.floatTab(tabId, floatRectAt(released.clientX, released.clientY, FLOAT_DEFAULT_SIZE))
+              return
+            }
+            if (target.kind === 'strip') intents.placeTab(tabId, target.paneId, target.index)
+            else intents.dropTab(tabId, target.paneId, target.zone)
+          },
+        })
+      })
+    },
+    onDividerPressed: (splitId, index, event) => {
+      const container = event.currentTarget.parentElement
+      /* v8 ignore next -- a divider is rendered as a child of its split's element. */
+      if (container === null) return
+      const split = getSplit(state, splitId)
+      const box = container.getBoundingClientRect()
+      const drag: DividerDrag = {
+        splitId,
+        index,
+        axis: split.axis,
+        origin: split.axis === 'row' ? event.clientX : event.clientY,
+        extent: split.axis === 'row' ? box.width : box.height,
+        sizes: split.sizes,
+      }
+      // A release that left the fractions where they were — a click on the
+      // divider, a drag returned to its start, or one pushed further into the
+      // clamp — is not a resize and reports nothing.
+      begin(event.currentTarget, event.pointerId, {
+        move: (moved) => {
+          setPreview({ ...NO_PREVIEW, sizes: { splitId, sizes: draggedSizes(drag, moved.clientX, moved.clientY, minPaneFraction) } })
+        },
+        up: (released) => {
+          const sizes = draggedSizes(drag, released.clientX, released.clientY, minPaneFraction)
+          if (sameSizes(sizes, drag.sizes)) return
+          intents.resizeSplit(splitId, sizes)
+        },
+      })
+    },
+    splitBlock,
+    hideSplitAtCapacity,
+    canAddTab: canAddTab ?? ALWAYS,
+    dropTarget: preview.dropTarget,
+    horizontalDrops: dropZones === 'horizontal',
+    draggingTabId: preview.draggingTabId,
+    labels,
+    renderTab,
+    renderTabTitle,
+    renderTabMenuItems,
+    chromePaneId: topRightPaneId(state),
+    chrome,
+  }
+
+  return (
+    <div className={css.surface} ref={surface} data-dockkit-surface data-dockkit-drop-zones={dropZones}>
+      <PaneTree state={state} nodeId={state.rootId} callbacks={callbacks} preview={preview.sizes} />
+    </div>
+  )
+}
diff --git a/packages/client/ui-dockkit/src/components/FloatLayer.tsx b/packages/client/ui-dockkit/src/components/FloatLayer.tsx
new file mode 100644
index 0000000000..3c7fa9c1d9
--- /dev/null
+++ b/packages/client/ui-dockkit/src/components/FloatLayer.tsx
@@ -0,0 +1,152 @@
+/**
+ * The floating layer: one overlay panel per floating pane, bottom-to-top in the
+ * model's z order. A floating pane hosts exactly one tab and renders no tab
+ * strip — the panel *is* the tab. Pressing a panel's body raises it. Its grip
+ * and corner report through their gesture instead: a press released in place is
+ * a click and raises the panel; a drag records the move or resize, and that
+ * operation raises the panel itself, so one gesture is one intent. Raising a
+ * panel that is active and on top already changes nothing and reports nothing.
+ *
+ * The layer owns its own drag and resize gestures, so where it mounts is not
+ * part of its contract: panels are positioned in viewport coordinates and read
+ * only `state` and the outward contracts. An embedder may portal it anywhere,
+ * and nothing here assumes the docked tree is an ancestor or even present.
+ */
+import { useState } from 'react'
+import type { PointerEvent as ReactPointerEvent, ReactNode } from 'react'
+import type { DockIntents, DockLabels, TabRenderer } from '../contract/adapter.ts'
+import type { FloatRect, LayoutState, PaneId } from '../contract/types.ts'
+import { FLOAT_MIN_SIZE } from '../engine/constraints.ts'
+import { movedRect, resizedRect } from '../engine/geometry.ts'
+import { floatRect, getPane, getTab, onlyTabId } from '../engine/tree.ts'
+import { useGesture } from './pointer.ts'
+import css from './dockkit.module.css'
+
+/** The layout whose `floats` this layer draws. */
+export interface FloatLayerProps {
+  readonly state: LayoutState
+  readonly intents: DockIntents
+  readonly labels: DockLabels
+  readonly renderTab: TabRenderer
+  /** The panel header's title content; omit to show the record's `title` text (see `DockSurfaceProps`). */
+  readonly renderTabTitle?: TabRenderer
+}
+
+/** A floating-panel gesture: what it moves and where it started. */
+interface FloatDrag {
+  readonly mode: 'move' | 'resize'
+  readonly originX: number
+  readonly originY: number
+  readonly rect: FloatRect
+}
+
+/** The rectangle a gesture has reached. */
+function draggedRect(drag: FloatDrag, x: number, y: number): FloatRect {
+  const dx = x - drag.originX
+  const dy = y - drag.originY
+  return drag.mode === 'move'
+    ? movedRect(drag.rect, dx, dy)
+    : resizedRect(drag.rect, dx, dy, FLOAT_MIN_SIZE)
+}
+
+/** Whether two rectangles agree in every coordinate. */
+function sameRect(a: FloatRect, b: FloatRect): boolean {
+  return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height
+}
+
+/** Whether a floating pane is already where a raise would put it: focused and on top. */
+function raised(state: LayoutState, paneId: PaneId): boolean {
+  return state.activePaneId === paneId && state.floats.at(-1) === paneId
+}
+
+/** Every floating panel, in z order. */
+export function FloatLayer({ state, intents, labels, renderTab, renderTabTitle }: FloatLayerProps): ReactNode {
+  const [preview, setPreview] = useState<{ paneId: PaneId; rect: FloatRect } | undefined>(undefined)
+  const begin = useGesture(() => { setPreview(undefined) })
+
+  /** Focus and raise a panel from a press or click on it, unless it is raised already. */
+  const raise = (paneId: PaneId): void => {
+    if (raised(state, paneId)) return
+    intents.focusPane(paneId)
+  }
+
+  /** Start a move or resize from a press on the panel's grip or corner; a release that moved nothing is a click. */
+  const drag = (mode: 'move' | 'resize', paneId: PaneId, event: ReactPointerEvent<HTMLElement>): void => {
+    // The press stops here: the panel's own press-to-focus would record a focus
+    // entry before the drag's, and the release below decides which one it is.
+    event.stopPropagation()
+    const start: FloatDrag = { mode, originX: event.clientX, originY: event.clientY, rect: floatRect(getPane(state, paneId)) }
+    begin(event.currentTarget, event.pointerId, {
+      move: (moved) => { setPreview({ paneId, rect: draggedRect(start, moved.clientX, moved.clientY) }) },
+      up: (released) => {
+        const rect = draggedRect(start, released.clientX, released.clientY)
+        if (sameRect(rect, start.rect)) raise(paneId)
+        else if (mode === 'move') intents.moveFloat(paneId, rect.x, rect.y)
+        else intents.resizeFloat(paneId, rect)
+      },
+    })
+  }
+
+  return (
+    <>
+      {state.floats.map((paneId, depth) => {
+        const pane = getPane(state, paneId)
+        const tab = getTab(state, onlyTabId(pane))
+        // A panel mid-gesture draws where the pointer has taken it and on top,
+        // as the operation its release records will leave it.
+        const lifted = preview?.paneId === paneId ? preview.rect : undefined
+        const live = lifted ?? floatRect(pane)
+        return (
+          <div
+            key={paneId}
+            className={css.float}
+            data-dockkit-float={paneId}
+            data-dockkit-float-active={state.activePaneId === paneId || undefined}
+            style={{
+              left: live.x,
+              top: live.y,
+              width: live.width,
+              height: live.height,
+              zIndex: lifted === undefined ? depth + 1 : state.floats.length + 1,
+            }}
+            onPointerDown={() => { raise(paneId) }}
+          >
+            <header
+              className={css.floatHeader}
+              data-dockkit-float-grip={paneId}
+              onPointerDown={(event) => { drag('move', paneId, event) }}
+            >
+              <span className={css.floatTitle} data-dockkit-float-title>{renderTabTitle?.(tab) ?? tab.title}</span>
+              <button
+                type="button"
+                className={css.iconButton}
+                aria-label={labels.dockFloat}
+                data-dockkit-float-dock={paneId}
+                onPointerDown={(event) => { event.stopPropagation() }}
+                onClick={() => { intents.unfloatPane(paneId) }}
+              >
+                ⇤
+              </button>
+              <button
+                type="button"
+                className={css.iconButton}
+                aria-label={labels.closeFloat}
+                data-dockkit-float-close={paneId}
+                onPointerDown={(event) => { event.stopPropagation() }}
+                onClick={() => { intents.closeTab(tab.id) }}
+              >
+                ✕
+              </button>
+            </header>
+            <div className={css.floatBody}>{renderTab(tab)}</div>
+            <div
+              className={css.floatResize}
+              data-dockkit-float-resize={paneId}
+              onPointerDown={(event) => { drag('resize', paneId, event) }}
+            />
+          </div>
+        )
+      })}
+    </>
+  )
+}
diff --git a/packages/client/ui-dockkit/src/components/PaneTree.tsx b/packages/client/ui-dockkit/src/components/PaneTree.tsx
new file mode 100644
index 0000000000..60f3f6976e
--- /dev/null
+++ b/packages/client/ui-dockkit/src/components/PaneTree.tsx
@@ -0,0 +1,60 @@
+/**
+ * The docked split tree: nested flex runs sized by each split's fractions, with a
+ * draggable divider between neighbours. A live divider drag renders from the
+ * preview fractions instead of the recorded ones — the gesture only settles one
+ * intent when it ends.
+ */
+import { Fragment } from 'react'
+import type { ReactNode } from 'react'
+import clsx from 'clsx'
+import type { LayoutState, NodeId, SplitId } from '../contract/types.ts'
+import { getNode } from '../engine/tree.ts'
+import type { PaneCallbacks } from './render.ts'
+import { TabPanel } from './TabPanel.tsx'
+import css from './dockkit.module.css'
+
+/** Fractions a live divider drag is previewing for one split. */
+export interface SizePreview {
+  readonly splitId: SplitId
+  readonly sizes: readonly number[]
+}
+
+/** One subtree of the docked layout. */
+export interface PaneTreeProps {
+  readonly state: LayoutState
+  readonly nodeId: NodeId
+  readonly callbacks: PaneCallbacks
+  readonly preview: SizePreview | undefined
+}
+
+/** Render a split or pane node and everything under it. */
+export function PaneTree({ state, nodeId, callbacks, preview }: PaneTreeProps): ReactNode {
+  const node = getNode(state, nodeId)
+  if (node.kind === 'pane') return <TabPanel state={state} pane={node} callbacks={callbacks} />
+  const sizes = preview !== undefined && preview.splitId === node.id ? preview.sizes : node.sizes
+  return (
+    <div
+      className={clsx(css.split, node.axis === 'row' ? css.splitRow : css.splitColumn)}
+      data-dockkit-split={node.id}
+    >
+      {node.children.map((childId, index) => (
+        <Fragment key={childId}>
+          {index > 0 && (
+            <div
+              className={css.divider}
+              data-dockkit-divider={`${node.id}:${index - 1}`}
+              onPointerDown={(event) => { callbacks.onDividerPressed(node.id, index - 1, event) }}
+            />
+          )}
+          <div
+            className={css.splitCell}
+            data-dockkit-cell={`${node.id}:${index}`}
+            style={{ flexGrow: sizes[index] }}
+          >
+            <PaneTree state={state} nodeId={childId} callbacks={callbacks} preview={preview} />
+          </div>
+        </Fragment>
+      ))}
+    </div>
+  )
+}
diff --git a/packages/client/ui-dockkit/src/components/TabMenu.tsx b/packages/client/ui-dockkit/src/components/TabMenu.tsx
new file mode 100644
index 0000000000..0f610cc0ed
--- /dev/null
+++ b/packages/client/ui-dockkit/src/components/TabMenu.tsx
@@ -0,0 +1,101 @@
+/**
+ * The per-tab context menu, opened by a secondary press on the chip. It carries
+ * the close gesture and whatever the embedder appends; the copy and float
+ * gestures have no menu item — copying is an embedder API, floating is a drag
+ * released clear of the surface. Presentational — it renders what its props
+ * supply and dismisses itself on outside presses.
+ *
+ * It renders in a portal, positioned against the control that opened it. The tab
+ * strip clips its overflow on purpose (so it never becomes a scroll container
+ * that claims a drag), and a menu drawn inside the strip would be clipped with
+ * it; a portal puts it above every clipping ancestor. React still bubbles the
+ * portal's synthetic events through the strip, which is why the press guards
+ * below remain necessary.
+ */
+import { useEffect, useLayoutEffect, useRef, useState } from 'react'
+import type { CSSProperties, ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+import type { DockLabels } from '../contract/adapter.ts'
+import css from './dockkit.module.css'
+
+/** Gap between the opening control and the menu, and the viewport margin kept clear. */
+const MENU_GAP = 4
+
+/** What the menu offers, where it anchors, and how it closes. */
+export interface TabMenuProps {
+  readonly labels: DockLabels
+  /** The control that opened the menu; the menu hangs below its left edge. */
+  readonly anchor: HTMLElement
+  readonly onClose: () => void
+  /** Dismiss without acting. */
+  readonly onDismiss: () => void
+  /** Embedder items, rendered after the kit's own; absent means none. */
+  readonly extras: ReactNode
+}
+
+/** Where the menu sits, or `undefined` before the first measurement. */
+function placeMenu(anchor: HTMLElement, menu: HTMLElement): CSSProperties {
+  const rect = anchor.getBoundingClientRect()
+  const width = menu.offsetWidth
+  // Below the control, aligned to its left edge; flipped to its right edge when
+  // that would run off the viewport, as it does for the last tab in a column
+  // against the window's right side.
+  const left = rect.left + width + MENU_GAP > window.innerWidth
+    ? Math.max(MENU_GAP, rect.right - width)
+    : rect.left
+  return { top: rect.bottom + MENU_GAP, left }
+}
+
+/** The actions menu body, anchored to the control that opened it. */
+export function TabMenu({ labels, anchor, onClose, onDismiss, extras }: TabMenuProps): ReactNode {
+  const self = useRef<HTMLDivElement | null>(null)
+  const [position, setPosition] = useState<CSSProperties | undefined>(undefined)
+
+  useLayoutEffect(() => {
+    /* v8 ignore next -- the ref is attached by effect time: the menu renders unconditionally. */
+    if (self.current === null) return
+    setPosition(placeMenu(anchor, self.current))
+  }, [anchor])
+
+  useEffect(() => {
+    const menu = self.current
+    /* v8 ignore next -- the ref is attached by effect time: the menu renders unconditionally. */
+    if (menu === null) return undefined
+    // A press anywhere but inside the menu dismisses it; one with no element
+    // target (dispatched to the window itself) counts as outside.
+    const onPointerDown = (event: PointerEvent): void => {
+      if (event.target instanceof Node && menu.contains(event.target)) return
+      onDismiss()
+    }
+    // Capture phase: a press on a tab chip starts a drag on its own handler,
+    // so the menu must be gone before that handler runs.
+    window.addEventListener('pointerdown', onPointerDown, true)
+    return () => { window.removeEventListener('pointerdown', onPointerDown, true) }
+  }, [onDismiss])
+
+  return createPortal(
+    <div
+      className={css.menu}
+      ref={self}
+      role="menu"
+      data-dockkit-tab-menu
+      // Unplaced for one layout pass: measured, then positioned.
+      style={position ?? { visibility: 'hidden', top: 0, left: 0 }}
+      // React bubbles a portal's events to its tab chip, so both halves of a
+      // press must stop here: the press would otherwise start a tab drag and
+      // capture the pointer, which retargets the release and swallows this
+      // item's click; the click would otherwise also focus a tab the item may
+      // have removed.
+      onPointerDown={(event) => { event.stopPropagation() }}
+      onClick={(event) => { event.stopPropagation() }}
+    >
+      <button type="button" role="menuitem" className={css.menuItem} data-dockkit-menu-close onClick={onClose}>
+        {labels.closeTab}
+      </button>
+      {/* Embedder items last: the kit's own item is the same in every menu, so
+          a reader looks for it in the same place every time. */}
+      {extras}
+    </div>,
+    document.body,
+  )
+}
diff --git a/packages/client/ui-dockkit/src/components/TabPanel.tsx b/packages/client/ui-dockkit/src/components/TabPanel.tsx
new file mode 100644
index 0000000000..a4a9cdc6f1
--- /dev/null
+++ b/packages/client/ui-dockkit/src/components/TabPanel.tsx
@@ -0,0 +1,281 @@
+/**
+ * One pane: its tab strip (drag source, drop target, split control) and the
+ * active tab's body with the dock preview overlay. Presentational; every gesture
+ * leaves through `PaneCallbacks`, and the body itself comes from `renderTab`.
+ *
+ * A chip is a capsule carrying one control, its close, at its right end; the
+ * context menu (secondary press) carries the same close plus whatever the
+ * embedder appends. The chips sit in their own box, the strip's one shrinking
+ * part: in a narrow pane they ellipsize and then clip there, so the add
+ * control after them (drawn while the embedder's `canAddTab` allows), the
+ * pane's split control, and the embedder's chrome keep their width and their
+ * place at the strip's end.
+ */
+import { Fragment, useState } from 'react'
+import type { ReactNode } from 'react'
+import clsx from 'clsx'
+import type { LayoutState, PaneNode, TabId } from '../contract/types.ts'
+import { getTab } from '../engine/tree.ts'
+import type { PaneCallbacks, SplitBlock } from './render.ts'
+import { TabMenu } from './TabMenu.tsx'
+import css from './dockkit.module.css'
+
+/** The split control's glyph: a frame divided by a vertical line, as the split itself is. */
+function SplitGlyph(): ReactNode {
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="none" aria-hidden="true">
+      <rect x="1.5" y="2" width="11" height="10" rx="1.5" stroke="currentColor" />
+      <path d="M7 2v10" stroke="currentColor" />
+    </svg>
+  )
+}
+
+/** The add control's glyph. */
+function PlusGlyph(): ReactNode {
+  return (
+    <svg width="12" height="12" viewBox="0 0 12 12" fill="none" aria-hidden="true">
+      <path d="M6 1.5v9M1.5 6h9" stroke="currentColor" strokeWidth="1.2" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+/** The close control's glyph. */
+function CloseGlyph(): ReactNode {
+  return (
+    <svg width="10" height="10" viewBox="0 0 10 10" fill="none" aria-hidden="true">
+      <path d="M1.5 1.5l7 7M8.5 1.5l-7 7" stroke="currentColor" strokeWidth="1.2" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+/** A pane and the live layout it reads its tabs from. */
+export interface TabPanelProps {
+  readonly state: LayoutState
+  readonly pane: PaneNode
+  readonly callbacks: PaneCallbacks
+}
+
+/**
+ * The chip a navigation key moves focus to, in the WAI-ARIA tabs pattern with
+ * manual activation: Left and Right step through the strip and wrap, Home and
+ * End jump to its ends. Selecting is a separate key.
+ * @returns the chip to focus, or `undefined` when the key is not a navigation key.
+ */
+function chipToFocus(key: string, tabs: readonly TabId[], tabId: TabId): TabId | undefined {
+  const count = tabs.length
+  const index = tabs.indexOf(tabId)
+  switch (key) {
+    case 'ArrowLeft': return tabs[(index - 1 + count) % count]
+    case 'ArrowRight': return tabs[(index + 1) % count]
+    case 'Home': return tabs[0]
+    case 'End': return tabs.at(-1)
+    default: return undefined
+  }
+}
+
+/** Whether a key selects the focused chip. */
+function selects(key: string): boolean {
+  return key === 'Enter' || key === ' '
+}
+
+/** The split control's title: what it does, or why it cannot right now. */
+function splitTitle(labels: PaneCallbacks['labels'], block: SplitBlock | undefined): string {
+  switch (block) {
+    case undefined: return labels.splitPane
+    case 'budget': return labels.splitPaneDisabled
+    case 'width': return labels.splitPaneNarrow
+  }
+}
+
+/** The pane's tab strip, split control, and body. */
+export function TabPanel({ state, pane, callbacks }: TabPanelProps): ReactNode {
+  // The open context menu and the chip that opened it; the menu positions
+  // itself against that chip from its portal.
+  const [menu, setMenu] = useState<{ readonly tabId: TabId; readonly anchor: HTMLElement } | undefined>(undefined)
+  // The mounted chips by tab, for the keys that move focus between them.
+  const [chips] = useState(() => new Map<TabId, HTMLElement>())
+  const active = pane.activeTabId === undefined ? undefined : getTab(state, pane.activeTabId)
+  const block = callbacks.splitBlock(pane.id)
+  const target = callbacks.dropTarget
+  const stripIndex = target !== undefined && target.kind === 'strip' && target.paneId === pane.id
+    ? target.index
+    : undefined
+  const zone = target !== undefined && target.kind === 'zone' && target.paneId === pane.id
+    ? target.zone
+    : undefined
+
+  /** Select a tab from a click or a key, unless it is the active pane's selected tab already: that changes nothing. */
+  const activate = (tabId: TabId): void => {
+    if (state.activePaneId === pane.id && pane.activeTabId === tabId) return
+    callbacks.onFocusTab(tabId)
+  }
+
+  const focusChip = (tabId: TabId): void => {
+    const chip = chips.get(tabId)
+    /* v8 ignore next -- every tab in the strip has a mounted chip, registered by its ref. */
+    if (chip === undefined) return
+    chip.focus()
+  }
+
+  return (
+    <section
+      className={css.pane}
+      data-dockkit-pane={pane.id}
+      data-dockkit-pane-active={state.activePaneId === pane.id || undefined}
+      // A click on the pane's body or strip focuses the pane, unless it is the
+      // active one already: that click changes nothing and records nothing. The
+      // chips and the strip's controls stop their own clicks: each reports one
+      // intent, and that intent already decides which pane is active.
+      onClick={() => {
+        if (state.activePaneId === pane.id) return
+        callbacks.onFocusPane(pane.id)
+      }}
+    >
+      <div className={css.tabStrip} role="tablist" data-dockkit-strip={pane.id}>
+        <div className={css.stripTabs} role="presentation" data-dockkit-strip-tabs={pane.id}>
+          {pane.tabs.map((tabId, index) => {
+            const tab = getTab(state, tabId)
+            const selected = tabId === pane.activeTabId
+            return (
+              <Fragment key={tabId}>
+                {stripIndex === index && <div className={css.caret} data-dockkit-caret={index} />}
+                <div
+                  role="tab"
+                  aria-selected={selected}
+                  tabIndex={selected ? 0 : -1}
+                  className={clsx(
+                    css.tab,
+                    selected && css.tabActive,
+                    callbacks.draggingTabId === tabId && css.tabDragging,
+                  )}
+                  data-dockkit-tab={tabId}
+                  ref={(element) => {
+                    if (element === null) chips.delete(tabId)
+                    else chips.set(tabId, element)
+                  }}
+                  // Focus lands on click, not on press: a state change between
+                  // pointerdown and the first pointermove rebuilds this subtree,
+                  // and Chromium cancels the pointer when the pressed element is
+                  // replaced — which would abandon every drag. A drag that ends
+                  // elsewhere fires no click, and its own operation carries focus.
+                  onPointerDown={(event) => {
+                    // A secondary press is the menu, never a drag.
+                    if (event.button === 2) return
+                    callbacks.onTabPressed(tabId, event)
+                  }}
+                  onClick={(event) => {
+                    event.stopPropagation()
+                    activate(tabId)
+                  }}
+                  onKeyDown={(event) => {
+                    // Keys on the chip's nested close control are that control's.
+                    if (event.target !== event.currentTarget) return
+                    const next = chipToFocus(event.key, pane.tabs, tabId)
+                    if (next !== undefined) {
+                      event.preventDefault()
+                      focusChip(next)
+                      return
+                    }
+                    if (selects(event.key)) {
+                      event.preventDefault()
+                      activate(tabId)
+                    }
+                  }}
+                  onContextMenu={(event) => {
+                    event.preventDefault()
+                    const anchor = event.currentTarget
+                    setMenu(current => current?.tabId === tabId ? undefined : { tabId, anchor })
+                  }}
+                >
+                  <span className={css.tabTitle} data-dockkit-tab-title>{callbacks.renderTabTitle?.(tab) ?? tab.title}</span>
+                  <button
+                    type="button"
+                    className={css.tabClose}
+                    aria-label={callbacks.labels.closeTab}
+                    data-dockkit-tab-close={tabId}
+                    // A nested control stops its own press: otherwise the press
+                    // starts a drag, captures the pointer, and this click never lands.
+                    onPointerDown={(event) => { event.stopPropagation() }}
+                    onClick={(event) => {
+                      event.stopPropagation()
+                      callbacks.onCloseTab(tabId)
+                    }}
+                  >
+                    <CloseGlyph />
+                  </button>
+                  {menu?.tabId === tabId && (
+                    <TabMenu
+                      labels={callbacks.labels}
+                      anchor={menu.anchor}
+                      onClose={() => { setMenu(undefined); callbacks.onCloseTab(tabId) }}
+                      onDismiss={() => { setMenu(undefined) }}
+                      extras={callbacks.renderTabMenuItems?.(tab, () => { setMenu(undefined) })}
+                    />
+                  )}
+                </div>
+              </Fragment>
+            )
+          })}
+          {stripIndex === pane.tabs.length && <div className={css.caret} data-dockkit-caret={stripIndex} />}
+        </div>
+        {callbacks.canAddTab(pane.id) && (
+          <button
+            type="button"
+            className={css.addTab}
+            aria-label={callbacks.labels.addTab}
+            title={callbacks.labels.addTab}
+            data-dockkit-add-tab={pane.id}
+            onClick={(event) => {
+              event.stopPropagation()
+              callbacks.onAddTab(pane.id)
+            }}
+          >
+            <PlusGlyph />
+          </button>
+        )}
+        <div className={css.stripFill} data-dockkit-strip-fill />
+        {!(callbacks.hideSplitAtCapacity && block === 'budget') && (
+          <button
+            type="button"
+            className={css.iconButton}
+            aria-label={callbacks.labels.splitPane}
+            title={splitTitle(callbacks.labels, block)}
+            disabled={block !== undefined}
+            data-dockkit-split-button={pane.id}
+            data-dockkit-split-blocked={block}
+            onClick={(event) => {
+              event.stopPropagation()
+              callbacks.onSplitPane(pane.id)
+            }}
+          >
+            <SplitGlyph />
+          </button>
+        )}
+        {/* The embedder's surface-wide controls, in the top-right pane only: the
+            strip is the surface's top edge, and this pane's end is its corner. */}
+        {pane.id === callbacks.chromePaneId && callbacks.chrome !== undefined && (
+          // The embedder's controls report their own intents; the pane's
+          // click-to-focus must not add a focus entry to each of them.
+          <div
+            className={css.stripChrome}
+            data-dockkit-strip-chrome
+            onClick={(event) => { event.stopPropagation() }}
+          >
+            {callbacks.chrome}
+          </div>
+        )}
+      </div>
+      <div className={css.paneBody}>
+        {active === undefined
+          ? <p className={css.empty}>{callbacks.labels.emptyPane}</p>
+          : callbacks.renderTab(active)}
+        {zone !== undefined && (callbacks.horizontalDrops && zone !== 'center'
+          ? <>
+            <div className={css.dockHint} data-dockkit-dock-zone="left" data-dockkit-drop-active={zone === 'left' || undefined} />
+            <div className={css.dockHint} data-dockkit-dock-zone="right" data-dockkit-drop-active={zone === 'right' || undefined} />
+          </>
+          : <div className={css.dockHint} data-dockkit-dock-zone={zone} />)}
+      </div>
+    </section>
+  )
+}
diff --git a/packages/client/ui-dockkit/src/components/dockkit.module.css b/packages/client/ui-dockkit/src/components/dockkit.module.css
new file mode 100644
index 0000000000..2e995a2700
--- /dev/null
+++ b/packages/client/ui-dockkit/src/components/dockkit.module.css
@@ -0,0 +1,423 @@
+/*
+ * Docking-kit styles. One sheet on purpose: a consumer bundle de-duplicates
+ * injected stylesheets by `<pluginId>/<basename>`, so a second sheet whose file
+ * name matches one in the embedding package would be dropped silently. Keeping
+ * a single `dockkit.module.css` makes that collision impossible.
+ *
+ * Colours come from the embedder's token layer; the kit names no literal. Type
+ * follows the embedder's content axis (`--dsh-content-font-size` and its
+ * secondary step) so a surface reads at the same size as the page around it.
+ * Emphasis — a hovered divider, the drop caret, the drop-zone hint — takes the
+ * platform's accent (`--dsw-alias-brand-primary-new-colorprimary-new-color`),
+ * not `--dsw-alias-brand-primary`, which this platform binds to its
+ * near-black (light) or near-white (dark) foreground.
+ */
+
+.split {
+  display: flex;
+  flex: 1 1 auto;
+  min-width: 0;
+  min-height: 0;
+}
+
+.splitRow {
+  flex-direction: row;
+}
+
+.splitColumn {
+  flex-direction: column;
+}
+
+.splitCell {
+  display: flex;
+  flex-basis: 0;
+  min-width: 0;
+  min-height: 0;
+}
+
+.divider {
+  position: relative;
+  flex: none;
+  background: var(--dsw-alias-border-l1);
+  touch-action: none;
+}
+
+.splitRow > .divider {
+  width: 4px;
+  cursor: col-resize;
+}
+
+.splitColumn > .divider {
+  height: 4px;
+  cursor: row-resize;
+}
+
+.divider:hover {
+  background: var(--dsw-alias-brand-primary-new-colorprimary-new-color);
+}
+
+/* Both floors: a flex item's minimum is its content's, and a body's longest
+   unwrapped line would widen the surface past the embedder's box, carrying the
+   strip's controls and the body's scrollbar out of view. */
+.surface {
+  display: flex;
+  flex: 1 1 auto;
+  min-width: 0;
+  min-height: 0;
+}
+
+/* A body that overflows scrolls inside its pane; nothing escapes the pane. */
+.pane {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+  border: 1px solid transparent;
+}
+
+.pane[data-dockkit-pane-active] {
+  border-color: var(--dsw-alias-border-l2);
+}
+
+/* One centre line for everything in the strip: every child — chip, add
+   control, split control, the embedder's chrome — is 24px tall, and the strip
+   centres them, so chip text and control glyphs never sit at different heights.
+   A child with another height would break that; keep them at 24px.
+
+   The strip never clips: the chip box below is its one shrinking part, and
+   every control after it is `flex: none`, so a narrow pane costs chips, never
+   controls. */
+.tabStrip {
+  display: flex;
+  flex: none;
+  gap: 4px;
+  align-items: center;
+  height: 36px;
+  padding: 0 6px;
+  border-bottom: 0.5px solid var(--dsw-alias-border-l1);
+  touch-action: none;
+}
+
+/* The chips. Shrinks to nothing before any control after it moves; what no
+   longer fits is clipped here. Deliberately not a scroller: a horizontal
+   scroll container claims a press-and-move as its own gesture and cancels the
+   pointer, which would abandon every tab drag in a narrow pane. Tabs shrink
+   and ellipsize first. */
+.stripTabs {
+  display: flex;
+  flex: 0 1 auto;
+  gap: 4px;
+  align-items: center;
+  min-width: 0;
+  overflow: hidden;
+  touch-action: none;
+}
+
+/* Takes the free space and gives it all back first: a zero basis shrinks
+   nothing, so shortage lands on the chip box alone. */
+.stripFill {
+  flex: 1 1 0;
+  min-width: 0;
+}
+
+/* Embedder controls at the strip's end, set off from the kit's own split
+   control by a hairline so the two groups read as two groups. */
+.stripChrome {
+  display: flex;
+  flex: none;
+  gap: 2px;
+  align-items: center;
+  height: 24px;
+  margin-left: 2px;
+  padding-left: 4px;
+  border-left: 0.5px solid var(--dsw-alias-border-l1);
+}
+
+.caret {
+  flex: none;
+  align-self: center;
+  width: 2px;
+  height: 20px;
+  background: var(--dsw-alias-brand-primary-new-colorprimary-new-color);
+}
+
+.tab {
+  position: relative;
+  display: flex;
+  flex: 0 1 auto;
+  gap: 4px;
+  align-items: center;
+  min-width: 44px;
+  max-width: 170px;
+  height: 24px;
+  padding: 0 5px 0 10px;
+  color: var(--dsw-alias-label-secondary);
+  font-size: var(--dsh-content-font-size-secondary, 13px);
+  line-height: 1;
+  white-space: nowrap;
+  border-radius: 12px;
+  cursor: pointer;
+  touch-action: none;
+  user-select: none;
+}
+
+.tabTitle {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.tabClose {
+  display: flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  padding: 0;
+  color: inherit;
+  line-height: 1;
+  background: transparent;
+  border: none;
+  border-radius: 50%;
+  corner-shape: round;
+  cursor: pointer;
+}
+
+.addTab {
+  display: flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  color: var(--dsw-alias-label-secondary);
+  line-height: 1;
+  background: transparent;
+  border: none;
+  border-radius: 12px;
+  cursor: pointer;
+}
+
+.addTab:hover {
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.tabClose:hover {
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-alias-interactive-bg-hover-solid);
+}
+
+.tab:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+/* The active chip is the filled capsule; the rest are bare text. */
+.tabActive {
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-alias-interactive-bg-active);
+}
+
+.tabDragging {
+  opacity: 0.5;
+}
+
+.iconButton {
+  display: flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  color: var(--dsw-alias-label-secondary);
+  line-height: 1;
+  background: transparent;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+}
+
+.iconButton:hover:not(:disabled) {
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.iconButton:disabled {
+  color: var(--dsw-alias-label-tertiary);
+  cursor: default;
+}
+
+/*
+ * Portalled beside the app root, so its stacking level is stated here: above the
+ * floating panels (which the embedder draws at 60), because a menu opened from
+ * a tab must never sit under a panel. No z-index token layer exists to draw from
+ * yet.
+ */
+.menu {
+  position: fixed;
+  z-index: 70;
+  display: flex;
+  flex-direction: column;
+  min-width: 96px;
+  padding: 4px;
+  background: var(--dsw-alias-bg-layer-3);
+  border: 0.5px solid var(--dsw-alias-border-l2);
+  border-radius: 6px;
+}
+
+.menuItem {
+  padding: 5px 8px;
+  color: var(--dsw-alias-label-primary);
+  font-size: var(--dsh-content-font-size-secondary, 13px);
+  text-align: left;
+  background: transparent;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+}
+
+.menuItem:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.paneBody {
+  position: relative;
+  flex: 1 1 auto;
+  min-width: 0;
+  min-height: 0;
+  padding: 12px;
+  overflow: auto;  /* This sheet draws elevated surfaces (the strip and the menu), so a scroller
+     inside it rebinds the thumb indirection in a complete pair — a base-surface
+     thumb on an elevated ground reads as a smudge. */
+  --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
+  --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
+}
+
+.empty {
+  margin: 0;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: var(--dsh-content-font-size-secondary, 13px);
+}
+
+.dockHint {
+  position: absolute;
+  background: var(--dsw-alias-bg-multi-select);
+  border: 1px solid var(--dsw-alias-brand-primary-new-colorprimary-new-color);
+  pointer-events: none;
+}
+
+.dockHint[data-dockkit-dock-zone='center'] {
+  inset: 0;
+}
+
+.dockHint[data-dockkit-dock-zone='left'] {
+  top: 0;
+  bottom: 0;
+  left: 0;
+  width: 40%;
+}
+
+.dockHint[data-dockkit-dock-zone='right'] {
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: 40%;
+}
+
+[data-dockkit-drop-zones='horizontal'] .dockHint[data-dockkit-dock-zone='left'],
+[data-dockkit-drop-zones='horizontal'] .dockHint[data-dockkit-dock-zone='right'] {
+  width: 50%;
+}
+
+[data-dockkit-drop-zones='horizontal'] .dockHint[data-dockkit-dock-zone='left']:not([data-dockkit-drop-active]),
+[data-dockkit-drop-zones='horizontal'] .dockHint[data-dockkit-dock-zone='right']:not([data-dockkit-drop-active]) {
+  background: transparent;
+  border-color: var(--dsw-alias-border-l2);
+}
+
+.dockHint[data-dockkit-dock-zone='top'] {
+  top: 0;
+  right: 0;
+  left: 0;
+  height: 40%;
+}
+
+.dockHint[data-dockkit-dock-zone='bottom'] {
+  right: 0;
+  bottom: 0;
+  left: 0;
+  height: 40%;
+}
+
+.float {
+  position: fixed;
+  display: flex;
+  flex-direction: column;
+  background: var(--dsw-alias-bg-layer-1);
+  border: 0.5px solid var(--dsw-alias-border-l2);
+  border-radius: 8px;
+  box-shadow: 0 8px 24px var(--dsw-alias-bg-mask-drop);
+  pointer-events: auto;
+}
+
+/* The active panel keeps the same hairline: it is already on top of the z
+   order and casts the same shadow, and a heavier or darker frame read as a
+   defect. `data-dockkit-float-active` stays on the element for tests. */
+
+.floatHeader {
+  display: flex;
+  flex: none;
+  gap: 2px;
+  align-items: center;
+  height: 28px;
+  padding: 0 4px 0 10px;
+  border-bottom: 0.5px solid var(--dsw-alias-border-l1);
+  cursor: move;
+  touch-action: none;
+  user-select: none;
+}
+
+.floatTitle {
+  flex: 1 1 auto;
+  overflow: hidden;
+  color: var(--dsw-alias-label-primary);
+  font-size: var(--dsh-content-font-size-secondary, 13px);
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.floatBody {
+  flex: 1 1 auto;
+  min-height: 0;
+  padding: 10px;
+  overflow: auto;  /* This sheet draws elevated surfaces (the strip and the menu), so a scroller
+     inside it rebinds the thumb indirection in a complete pair — a base-surface
+     thumb on an elevated ground reads as a smudge. */
+  --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
+  --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
+}
+
+.floatResize {
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  width: 14px;
+  height: 14px;
+  cursor: nwse-resize;
+  touch-action: none;
+}
+
+.floatResize::after {
+  position: absolute;
+  right: 3px;
+  bottom: 3px;
+  width: 6px;
+  height: 6px;
+  border-right: 2px solid var(--dsw-alias-label-tertiary);
+  border-bottom: 2px solid var(--dsw-alias-label-tertiary);
+  content: '';
+}
diff --git a/packages/client/ui-dockkit/src/components/measure.ts b/packages/client/ui-dockkit/src/components/measure.ts
new file mode 100644
index 0000000000..6ce1fea4eb
--- /dev/null
+++ b/packages/client/ui-dockkit/src/components/measure.ts
@@ -0,0 +1,109 @@
+/**
+ * DOM side of the room rule: read each docked pane's rectangles after a commit
+ * and ask `halvesFit` whether a split would leave two working halves. Pixels
+ * live here and in `geometry.ts`; the engine's planners never see them.
+ */
+import type { PaneId } from '../contract/types.ts'
+import { halvesFit, SPLIT_MINIMUMS } from '../engine/geometry.ts'
+import type { HalvesFit, Rect, SplitMinimums } from '../engine/geometry.ts'
+
+const NO_RECT: Rect = { x: 0, y: 0, width: 0, height: 0 }
+
+/** What an unmeasured pane is taken to be: fitting, until a reading says otherwise. */
+const UNMEASURED: HalvesFit = { row: true, column: true }
+
+function rectOf(element: Element | null): Rect {
+  return element === null ? NO_RECT : element.getBoundingClientRect()
+}
+
+function px(value: string): number {
+  const parsed = Number.parseFloat(value)
+  return Number.isFinite(parsed) ? parsed : 0
+}
+
+/**
+ * Every docked pane element under `root`, in document order, with the pane id
+ * each carries.
+ * @param root - the docked surface's element.
+ * @returns pane ids paired with their elements.
+ */
+export function paneElements(root: HTMLElement): readonly (readonly [PaneId, HTMLElement])[] {
+  const panes: (readonly [PaneId, HTMLElement])[] = []
+  for (const pane of root.querySelectorAll<HTMLElement>('[data-dockkit-pane]')) {
+    // The attribute is the kit's own PaneId written on render; the DOM hands it
+    // back as a bare string, so the brand is restored here and nowhere else.
+    const paneId = pane.dataset.dockkitPane as PaneId | undefined
+    /* v8 ignore next -- the selector admits only elements carrying the attribute. */
+    if (paneId === undefined) continue
+    panes.push([paneId, pane])
+  }
+  return panes
+}
+
+/**
+ * One chip's minimum footprint from a rendered chip's computed style; the
+ * stylesheet fallback where none is rendered or styles are not applied.
+ */
+function chipMinimum(root: HTMLElement): number {
+  const chip = root.querySelector('[data-dockkit-tab]')
+  if (chip === null) return SPLIT_MINIMUMS.chip
+  const style = getComputedStyle(chip)
+  const min = px(style.minWidth)
+  if (min <= 0) return SPLIT_MINIMUMS.chip
+  if (style.boxSizing === 'border-box') return min
+  return min + px(style.paddingLeft) + px(style.paddingRight) + px(style.borderLeftWidth) + px(style.borderRightWidth)
+}
+
+/** A rendered divider's thickness, or the stylesheet fallback before the first split. */
+function dividerSize(root: HTMLElement): number {
+  const divider = root.querySelector('[data-dockkit-divider]')
+  if (divider === null) return SPLIT_MINIMUMS.divider
+  const { width, height } = divider.getBoundingClientRect()
+  const thickness = Math.min(width, height)
+  return thickness > 0 ? thickness : SPLIT_MINIMUMS.divider
+}
+
+/**
+ * Measure every docked pane under `root`.
+ * @param root - the docked surface's element.
+ * @returns each pane's fit, keyed by pane id.
+ */
+export function measurePaneFits(root: HTMLElement): ReadonlyMap<PaneId, HalvesFit> {
+  const minimums: SplitMinimums = { divider: dividerSize(root), chip: chipMinimum(root), body: SPLIT_MINIMUMS.body }
+  const fits = new Map<PaneId, HalvesFit>()
+  for (const [paneId, pane] of paneElements(root)) {
+    fits.set(paneId, halvesFit({
+      pane: rectOf(pane),
+      strip: rectOf(pane.querySelector('[data-dockkit-strip]')),
+      chipsWidth: rectOf(pane.querySelector('[data-dockkit-strip-tabs]')).width,
+      fillWidth: rectOf(pane.querySelector('[data-dockkit-strip-fill]')).width,
+    }, minimums))
+  }
+  return fits
+}
+
+/**
+ * One pane's latest reading. A pane the map does not name has not been
+ * measured and fits: the rule only blocks on a positive reading.
+ * @param fits - the latest measurement.
+ * @param paneId - the pane asked about.
+ * @returns whether each split axis leaves two working halves.
+ */
+export function fitOf(fits: ReadonlyMap<PaneId, HalvesFit>, paneId: PaneId): HalvesFit {
+  return fits.get(paneId) ?? UNMEASURED
+}
+
+/**
+ * Whether two measurements agree, so a re-measure that changed nothing re-renders nothing.
+ * @param a - one measurement.
+ * @param b - the other.
+ * @returns whether both name the same panes with the same readings.
+ */
+export function sameFits(a: ReadonlyMap<PaneId, HalvesFit>, b: ReadonlyMap<PaneId, HalvesFit>): boolean {
+  if (a.size !== b.size) return false
+  for (const [paneId, fit] of a) {
+    const other = b.get(paneId)
+    if (other === undefined || other.row !== fit.row || other.column !== fit.column) return false
+  }
+  return true
+}
diff --git a/packages/client/ui-dockkit/src/components/pointer.ts b/packages/client/ui-dockkit/src/components/pointer.ts
new file mode 100644
index 0000000000..a3b368ea9b
--- /dev/null
+++ b/packages/client/ui-dockkit/src/components/pointer.ts
@@ -0,0 +1,106 @@
+/**
+ * Pointer ownership shared by the docking surface and the float layer.
+ *
+ * Capture is hardening, not the mechanism: the window listeners carry the
+ * gesture either way. Capture is what stops a scroll container the pointer
+ * crosses from claiming it, which Chromium reports as a cancelled pointer and
+ * an abandoned drag. Environments without the API (jsdom) simply go unhardened.
+ */
+import { useEffect, useRef } from 'react'
+
+/** The three window listeners one gesture installs. */
+export interface PointerFollowers {
+  readonly move: (event: PointerEvent) => void
+  readonly up: (event: PointerEvent) => void
+  readonly cancel: () => void
+}
+
+/**
+ * Take ownership of the pointer for the rest of the gesture.
+ * @param element - the element the gesture started on.
+ * @param pointerId - the pointer to capture.
+ */
+export function capturePointer(element: HTMLElement, pointerId: number): void {
+  if (typeof element.setPointerCapture !== 'function') return
+  element.setPointerCapture(pointerId)
+}
+
+/**
+ * Capture the pointer, then follow it on the window until release or cancel.
+ * Only that pointer's events count: a second finger or a pen beside the mouse
+ * neither moves nor ends the gesture. The listeners remove themselves before
+ * `up` or `cancel` runs; the returned callback ends the gesture early, for an
+ * unmount or a superseding press.
+ * @param element - the element the gesture started on.
+ * @param pointerId - the pointer to capture and follow.
+ * @param followers - listeners for move, release, and cancel.
+ * @returns detach callback removing the three listeners.
+ */
+export function followPointer(element: HTMLElement, pointerId: number, followers: PointerFollowers): () => void {
+  capturePointer(element, pointerId)
+  const controller = new AbortController()
+  const { signal } = controller
+  const own = (event: PointerEvent): boolean => event.pointerId === pointerId
+  window.addEventListener('pointermove', (event) => { if (own(event)) followers.move(event) }, { signal })
+  window.addEventListener('pointerup', (event) => {
+    if (!own(event)) return
+    controller.abort()
+    followers.up(event)
+  }, { signal })
+  window.addEventListener('pointercancel', (event) => {
+    if (!own(event)) return
+    controller.abort()
+    followers.cancel()
+  }, { signal })
+  return () => { controller.abort() }
+}
+
+/** What one gesture does while it lasts and when it settles. */
+export interface GestureFollowers {
+  readonly move: (event: PointerEvent) => void
+  /** The release. The gesture has already ended, and its preview reset, when this runs. */
+  readonly up: (event: PointerEvent) => void
+}
+
+/**
+ * Start a gesture from the element a press landed on.
+ * @param element - the pressed element; the pointer is captured on it.
+ * @param pointerId - the pressing pointer.
+ * @param followers - what the gesture does.
+ */
+export type BeginGesture = (element: HTMLElement, pointerId: number, followers: GestureFollowers) => void
+
+/**
+ * One pointer gesture at a time for a component. A gesture ends on release, on
+ * cancel, or when a new press supersedes it; `reset` runs at each of those ends
+ * so the component clears its preview. Unmounting mid-gesture removes the
+ * listeners without resetting anything.
+ * @param reset - clears the component's gesture preview.
+ * @returns the gesture starter, called from a pointer-down handler.
+ */
+export function useGesture(reset: () => void): BeginGesture {
+  const inFlight = useRef<{ readonly stop: () => void; readonly end: () => void } | undefined>(undefined)
+  useEffect(() => () => { inFlight.current?.stop() }, [])
+  return (element, pointerId, followers) => {
+    inFlight.current?.end()
+    const settle = (): void => {
+      inFlight.current = undefined
+      reset()
+    }
+    const stop = followPointer(element, pointerId, {
+      move: followers.move,
+      up: (event) => {
+        settle()
+        followers.up(event)
+      },
+      cancel: settle,
+    })
+    inFlight.current = {
+      stop,
+      end: () => {
+        stop()
+        settle()
+      },
+    }
+  }
+}
diff --git a/packages/client/ui-dockkit/src/components/render.ts b/packages/client/ui-dockkit/src/components/render.ts
new file mode 100644
index 0000000000..1bc3c703f6
--- /dev/null
+++ b/packages/client/ui-dockkit/src/components/render.ts
@@ -0,0 +1,46 @@
+/**
+ * Prop shares the kit's own components pass among themselves. These are internal
+ * to the package — the outward contracts are in `adapter.ts`.
+ */
+import type { PointerEvent as ReactPointerEvent, ReactNode } from 'react'
+import type { DockLabels, TabMenuExtras, TabRenderer } from '../contract/adapter.ts'
+import type { PaneId, SplitId, TabId } from '../contract/types.ts'
+import type { DropTarget } from '../engine/geometry.ts'
+
+/** Why a pane's split control is disabled: the pane budget, or too little width for two halves. */
+export type SplitBlock = 'budget' | 'width'
+
+/** What a pane subtree needs: settled callbacks, gesture starters, and live preview. */
+export interface PaneCallbacks {
+  readonly onFocusTab: (tabId: TabId) => void
+  readonly onFocusPane: (paneId: PaneId) => void
+  readonly onSplitPane: (paneId: PaneId) => void
+  readonly onAddTab: (paneId: PaneId) => void
+  readonly onCloseTab: (tabId: TabId) => void
+  /** Begin dragging a tab; the surface owns the gesture from here. */
+  readonly onTabPressed: (tabId: TabId, event: ReactPointerEvent<HTMLElement>) => void
+  /** Begin dragging a divider inside `splitId`, at the boundary after `index`. */
+  readonly onDividerPressed: (splitId: SplitId, index: number, event: ReactPointerEvent<HTMLElement>) => void
+  /** Why a pane cannot split right now, or `undefined` while it can. */
+  readonly splitBlock: (paneId: PaneId) => SplitBlock | undefined
+  /** Hide budget-blocked split controls without hiding width-blocked controls. */
+  readonly hideSplitAtCapacity?: boolean
+  /** Whether a pane's strip draws the add control. */
+  readonly canAddTab: (paneId: PaneId) => boolean
+  /** Live drop preview, or `undefined` while nothing is being dragged. */
+  readonly dropTarget: DropTarget | undefined
+  /** Show both horizontal landing regions while a body split is being targeted. */
+  readonly horizontalDrops?: boolean
+  /** Tab currently being dragged, so its chip can render as lifted. */
+  readonly draggingTabId: TabId | undefined
+  readonly labels: DockLabels
+  readonly renderTab: TabRenderer
+  /** A chip's or panel header's title content; absent means the record's `title` text. */
+  readonly renderTabTitle: TabRenderer | undefined
+  /** Embedder items appended to a tab's context menu; absent means the kit's item only. */
+  readonly renderTabMenuItems: TabMenuExtras | undefined
+  /** The pane whose strip hosts the embedder's surface-wide controls. */
+  readonly chromePaneId: PaneId
+  /** Those controls; absent means the strip ends at the kit's own split control. */
+  readonly chrome: ReactNode
+}
diff --git a/packages/client/ui-dockkit/src/contract/adapter.ts b/packages/client/ui-dockkit/src/contract/adapter.ts
new file mode 100644
index 0000000000..eb1abf8d5f
--- /dev/null
+++ b/packages/client/ui-dockkit/src/contract/adapter.ts
@@ -0,0 +1,93 @@
+/**
+ * The kit's outward contracts: state in, intents out.
+ *
+ * Everything host-specific arrives through these — every rendered string, every
+ * tab body, and every net gesture result. The kit itself holds no copy, no icon
+ * set, and no knowledge of what a tab's `kind` means.
+ */
+import type { ReactNode } from 'react'
+import type { DockZone, FloatRect, PaneId, SplitId, TabId, TabRecord } from './types.ts'
+
+/**
+ * Every string the kit renders, already localized by the embedder.
+ *
+ * Accessible names are included: a control with no visible text still needs
+ * one, and the kit must not invent it.
+ */
+export interface DockLabels {
+  /** Body of a pane holding no tabs. */
+  readonly emptyPane: string
+  /** The split control, while splitting is allowed. */
+  readonly splitPane: string
+  /** The split control, once the pane budget is spent. */
+  readonly splitPaneDisabled: string
+  /** The split control, while the pane is too narrow for two working halves. */
+  readonly splitPaneNarrow: string
+  /** Destroy a tab: the chip's close control and the menu's close item. */
+  readonly closeTab: string
+  /** The strip's add control, which seats the embedder's seeded tab. */
+  readonly addTab: string
+  /** Send a floating panel back into the docked tree. */
+  readonly dockFloat: string
+  /** Close a floating panel. */
+  readonly closeFloat: string
+}
+
+/**
+ * Renders one tab's body. The embedder dispatches on `tab.kind`, which is the
+ * only place that string carries meaning.
+ */
+export type TabRenderer = (tab: TabRecord) => ReactNode
+
+/**
+ * Renders extra items at the end of one tab's context menu (opened by a
+ * secondary press on the chip).
+ *
+ * The kit's own item is the close gesture; anything that means something about
+ * the tab's content comes from here. An item that acts MUST call `dismiss`,
+ * because the menu closes on its own items only.
+ * @param tab - the tab whose menu is open.
+ * @param dismiss - close the menu without acting.
+ * @returns the extra items, or nothing.
+ */
+export type TabMenuExtras = (tab: TabRecord, dismiss: () => void) => ReactNode
+
+/**
+ * Net gesture results the kit reports. Each call is one settled intent — never a
+ * drag frame — so an embedder recording them produces one operation per gesture.
+ *
+ * `DockController` satisfies this contract as-is; an embedder that routes
+ * through its own store implements the same names.
+ */
+export interface DockIntents {
+  /** Focus a tab and its pane. */
+  readonly focusTab: (tabId: TabId) => void
+  /** Focus a pane, raising it when it floats. */
+  readonly focusPane: (paneId: PaneId) => void
+  /** Split a pane and seed the new one. */
+  readonly splitPane: (paneId: PaneId) => void
+  /** Add the embedder's seeded tab to a pane (the strip's `+`). */
+  readonly addTab: (paneId: PaneId) => void
+  /** Destroy a tab. */
+  readonly closeTab: (tabId: TabId) => void
+  /** Copy a tab beside itself. No kit control drives this; embedders reach it through their own API. */
+  readonly duplicateTab: (tabId: TabId) => void
+  /** Float a tab, at `rect` when the release point decided one (a drag released clear of the surface). */
+  readonly floatTab: (tabId: TabId, rect?: FloatRect) => void
+  /** Return a floating panel's tab to the docked tree. */
+  readonly unfloatPane: (paneId: PaneId) => void
+  /**
+   * Put a tab at an explicit strip slot: a reorder, a move, or a return. `index`
+   * is the caret slot counted over the destination strip's chips as drawn, the
+   * dragged chip included when the strip is its own.
+   */
+  readonly placeTab: (tabId: TabId, toPaneId: PaneId, index: number) => void
+  /** Resolve a release on a pane body: the centre moves in, an edge splits. */
+  readonly dropTab: (tabId: TabId, paneId: PaneId, zone: DockZone) => void
+  /** Net position of a floating-panel drag; the operation it records focuses and raises the panel too. */
+  readonly moveFloat: (paneId: PaneId, x: number, y: number) => void
+  /** Net rectangle of a floating-panel resize; the operation it records focuses and raises the panel too. */
+  readonly resizeFloat: (paneId: PaneId, rect: FloatRect) => void
+  /** Net fractions of a divider drag. */
+  readonly resizeSplit: (splitId: SplitId, sizes: readonly number[]) => void
+}
diff --git a/packages/client/ui-dockkit/src/contract/types.ts b/packages/client/ui-dockkit/src/contract/types.ts
new file mode 100644
index 0000000000..e5f9a665e8
--- /dev/null
+++ b/packages/client/ui-dockkit/src/contract/types.ts
@@ -0,0 +1,201 @@
+/**
+ * Layout model and operation vocabulary. Types only: no runtime code, no React,
+ * no DOM, and no host concepts — a tab's `kind` is an opaque string this kit
+ * never interprets, so the embedder owns what content families exist.
+ *
+ * The model is a normalized recursive split tree. `nodes` holds every split and
+ * pane keyed by id; `rootId` names the docked root; `floats` lists floating
+ * panes bottom-to-top. A floating panel is not a second concept — it is a pane
+ * whose `host` is `'float'`, capacity 1 tab, drawn without a tab strip.
+ *
+ * Ids are branded: a pane, a split, and a tab id never stand in for one another
+ * or for a bare string, and only a mint (or a DOM round trip of an id the kit
+ * wrote itself) produces one.
+ */
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/** Identity of a pane node in `LayoutState.nodes`. */
+export type PaneId = Branded<'PaneId'>
+
+/** Identity of a split node in `LayoutState.nodes`. */
+export type SplitId = Branded<'SplitId'>
+
+/** Identity of any node in `LayoutState.nodes`. */
+export type NodeId = PaneId | SplitId
+
+/** Identity of one open tab; distinct copies of one content share `contentId`, never `TabId`. */
+export type TabId = Branded<'TabId'>
+
+/** Direction a split lays its children out in. */
+export type SplitAxis = 'row' | 'column'
+
+/** Which side of the reference pane a new pane takes. */
+export type SplitDirection = 'before' | 'after'
+
+/** The five drop regions a pane offers a dragged tab. */
+export type DockZone = 'center' | 'top' | 'right' | 'bottom' | 'left'
+
+/**
+ * How the docked area is presented.
+ *
+ * `push` takes room from its neighbours; `fullscreen` covers the viewport. The kit
+ * records the choice but does not implement either — the embedder reads this and
+ * positions the surface. It lives here, beside `expanded`, because switching is a
+ * recorded operation the user can step back through. The values are the kit's
+ * own words and no service interface repeats them.
+ */
+export type DockMode = 'push' | 'fullscreen'
+
+/** Viewport rectangle of a floating pane, in CSS pixels. */
+export interface FloatRect {
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+}
+
+/** Interior node: an ordered run of children along one axis with fractional sizes. */
+export interface SplitNode {
+  readonly kind: 'split'
+  readonly id: SplitId
+  readonly axis: SplitAxis
+  /** At least two children; a one-child split collapses into that child. */
+  readonly children: readonly NodeId[]
+  /** Same length as `children`, each above zero, summing to 1. */
+  readonly sizes: readonly number[]
+}
+
+/** Where a pane is drawn: inside the docked split tree, or as a viewport overlay. */
+export type PaneHost = 'dock' | 'float'
+
+/** Leaf node: an ordered tab list with at most one active tab. */
+export interface PaneNode {
+  readonly kind: 'pane'
+  readonly id: PaneId
+  readonly host: PaneHost
+  readonly tabs: readonly TabId[]
+  /** `undefined` exactly when `tabs` is empty. */
+  readonly activeTabId: TabId | undefined
+  /** Set exactly when `host` is `'float'`. */
+  readonly rect: FloatRect | undefined
+}
+
+/** Either kind of tree node. */
+export type LayoutNode = SplitNode | PaneNode
+
+/**
+ * One open tab.
+ *
+ * `kind` selects the embedder's content family and is never interpreted here.
+ * `contentId` is the identity `openContent` de-duplicates against, so two tabs
+ * sharing it are deliberate copies of one thing.
+ */
+export interface TabRecord {
+  readonly id: TabId
+  readonly kind: string
+  readonly contentId: string
+  readonly title: string
+}
+
+/**
+ * The whole layout of one docking surface. Every field is replaced rather than
+ * mutated, and untouched sub-objects keep their identity so consumers can
+ * compare by reference.
+ */
+export interface LayoutState {
+  readonly nodes: Readonly<Record<NodeId, LayoutNode>>
+  readonly tabs: Readonly<Record<TabId, TabRecord>>
+  /** Root of the docked tree; always a split or pane that exists in `nodes`. */
+  readonly rootId: NodeId
+  /** Floating panes, bottom-to-top; the last entry is on top. */
+  readonly floats: readonly PaneId[]
+  /** Focused pane, docked or floating. */
+  readonly activePaneId: PaneId
+  /** Whether the docked area is expanded; floating panes ignore it. */
+  readonly expanded: boolean
+  /** How the docked area is presented; floating panes ignore it. */
+  readonly mode: DockMode
+}
+
+/** Recipe for putting a pane back where it was, used by `insertPane`. */
+export type PaneAttachment =
+  /** Re-insert as a child of an existing split, restoring that split's sizes verbatim. */
+  | { readonly mode: 'child'; readonly parentId: SplitId; readonly index: number; readonly sizes: readonly number[] }
+  /** Re-create a collapsed split in `targetId`'s slot; `split` already lists both children. */
+  | { readonly mode: 'wrap'; readonly targetId: NodeId; readonly split: SplitNode }
+  /** Re-insert a floating pane at its former z index. */
+  | { readonly mode: 'float'; readonly index: number }
+
+/**
+ * One recorded layout mutation. Ids that an operation creates are carried in
+ * the operation itself, so replaying a sequence from the same initial state
+ * reproduces the same ids without any minting during apply.
+ *
+ * `insertPane`, `insertTab`, and `restoreFocus` exist to express inverses
+ * exactly; they are applied like any other operation.
+ */
+export type LayoutOp =
+  /** Give `paneId` a new empty sibling pane along `axis`. */
+  | {
+    readonly type: 'split'
+    readonly paneId: PaneId
+    readonly axis: SplitAxis
+    readonly direction: SplitDirection
+    readonly newPaneId: PaneId
+    /** Used only when the reference pane's parent cannot host `axis` directly. */
+    readonly newSplitId: SplitId
+  }
+  /** Drop an empty docked pane and collapse the split it leaves behind. */
+  | { readonly type: 'merge'; readonly paneId: PaneId }
+  /** Add a new tab to a docked pane and focus it. */
+  | { readonly type: 'openTab'; readonly paneId: PaneId; readonly tab: TabRecord; readonly index: number }
+  /** Destroy a tab and its content state; a floating host pane goes with it. */
+  | { readonly type: 'closeTab'; readonly tabId: TabId }
+  /** Move a tab to a different docked pane. */
+  | { readonly type: 'moveTab'; readonly tabId: TabId; readonly toPaneId: PaneId; readonly index: number }
+  /** Move a tab within its own pane. */
+  | { readonly type: 'reorderTab'; readonly tabId: TabId; readonly index: number }
+  /** Focus a tab, its owning pane, and raise that pane when floating. */
+  | { readonly type: 'focusTab'; readonly tabId: TabId }
+  /** Focus a pane and raise it when floating. */
+  | { readonly type: 'focusPane'; readonly paneId: PaneId }
+  /** Net result of a divider drag. */
+  | { readonly type: 'resize'; readonly splitId: SplitId; readonly sizes: readonly number[] }
+  /** Take a tab out of the docked tree into a new floating pane. */
+  | { readonly type: 'float'; readonly tabId: TabId; readonly newPaneId: PaneId; readonly rect: FloatRect }
+  /** Return a floating pane's only tab to a docked pane and destroy the floating pane. */
+  | { readonly type: 'unfloat'; readonly paneId: PaneId; readonly toPaneId: PaneId; readonly index: number }
+  /** Net result of dragging a floating pane; the pane is focused and raised with it. */
+  | { readonly type: 'moveFloat'; readonly paneId: PaneId; readonly x: number; readonly y: number }
+  /** Net result of resizing a floating pane; the pane is focused and raised with it. */
+  | { readonly type: 'resizeFloat'; readonly paneId: PaneId; readonly rect: FloatRect }
+  /** Expand or collapse the docked area. */
+  | { readonly type: 'setExpanded'; readonly expanded: boolean }
+  /** Switch how the docked area is presented. */
+  | { readonly type: 'setMode'; readonly mode: DockMode }
+  /** Put a pane back, with the tab records it owned. */
+  | {
+    readonly type: 'insertPane'
+    readonly pane: PaneNode
+    readonly tabs: readonly TabRecord[]
+    readonly attach: PaneAttachment
+  }
+  /** Put one tab record back into a docked pane. */
+  | { readonly type: 'insertTab'; readonly paneId: PaneId; readonly tab: TabRecord; readonly index: number }
+  /** Restore focus facts an operation displaced. */
+  | {
+    readonly type: 'restoreFocus'
+    readonly activePaneId: PaneId
+    readonly floats: readonly PaneId[]
+    /** Active tab per pane, for the panes the inverted operation touched. */
+    readonly paneActiveTabs: Readonly<Record<PaneId, TabId | undefined>>
+  }
+
+/** Operation kinds that only move focus; `Sequencer` collapses runs of these into one undo step. */
+export type FocusOpType = 'focusTab' | 'focusPane' | 'restoreFocus'
+
+/** Result of applying one operation: the next state plus the operations that undo it, in order. */
+export interface ApplyResult {
+  readonly state: LayoutState
+  readonly inverse: readonly LayoutOp[]
+}
diff --git a/packages/client/ui-dockkit/src/css-modules.d.ts b/packages/client/ui-dockkit/src/css-modules.d.ts
new file mode 100644
index 0000000000..bc5e482353
--- /dev/null
+++ b/packages/client/ui-dockkit/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-dockkit/src/engine/constraints.ts b/packages/client/ui-dockkit/src/engine/constraints.ts
new file mode 100644
index 0000000000..10ebb9fb14
--- /dev/null
+++ b/packages/client/ui-dockkit/src/engine/constraints.ts
@@ -0,0 +1,104 @@
+/**
+ * Interaction limits and dock geometry. The model itself is unbounded; these
+ * are the V1 rules the interaction layer enforces before it dispatches, kept
+ * pure so they can be asserted without a browser.
+ */
+import type { DockZone, LayoutState, SplitAxis, SplitDirection } from '../contract/types.ts'
+import { assertNever, dockPaneIds } from './tree.ts'
+
+/** V1 caps the docked grid at four panes; floating panes do not count. */
+export const MAX_DOCK_PANES = 4
+
+/** Smallest fraction a divider drag may leave a pane, as a share of its split. */
+export const MIN_PANE_FRACTION = 0.12
+
+/** Size a tab takes when it first floats, in CSS pixels. */
+export const FLOAT_DEFAULT_SIZE = { width: 380, height: 300 } as const
+
+/** Smallest size a floating panel may be resized to, in CSS pixels. */
+export const FLOAT_MIN_SIZE = { width: 220, height: 140 } as const
+
+/** Fraction of a pane's width or height that counts as its dock edge. */
+export const DOCK_EDGE_FRACTION = 0.25
+
+/**
+ * Number of docked panes.
+ * @param state - current layout.
+ * @returns how many panes the docked tree holds; floating panes do not count.
+ */
+export function dockPaneCount(state: LayoutState): number {
+  return dockPaneIds(state).length
+}
+
+/**
+ * Whether another docked pane is allowed.
+ * @param state - current layout.
+ * @returns whether the docked tree is under `MAX_DOCK_PANES`.
+ */
+export function canSplit(state: LayoutState): boolean {
+  return dockPaneCount(state) < MAX_DOCK_PANES
+}
+
+/** The five dock regions a tab can be dropped on. */
+export const DOCK_ZONES: readonly DockZone[] = ['center', 'top', 'right', 'bottom', 'left']
+
+/**
+ * Which dock region a pointer sits in.
+ * @param x - pointer x as a fraction of pane width.
+ * @param y - pointer y as a fraction of pane height.
+ * @param edge - edge band width as a fraction; defaults to `DOCK_EDGE_FRACTION`.
+ * @returns the closest edge when the pointer is inside its band, else `'center'`.
+ */
+export function zoneAt(x: number, y: number, edge: number = DOCK_EDGE_FRACTION): DockZone {
+  let zone: DockZone = 'left'
+  let distance = x
+  if (1 - x < distance) { zone = 'right'; distance = 1 - x }
+  if (y < distance) { zone = 'top'; distance = y }
+  if (1 - y < distance) { zone = 'bottom'; distance = 1 - y }
+  return distance < edge ? zone : 'center'
+}
+
+/**
+ * How a dock region splits the pane it targets.
+ * @param zone - the region the pointer released in.
+ * @returns the split's axis and direction, or `undefined` for `'center'`, which moves the tab into the pane instead.
+ */
+export function zoneSplit(zone: DockZone): { axis: SplitAxis; direction: SplitDirection } | undefined {
+  switch (zone) {
+    case 'center': return undefined
+    case 'left': return { axis: 'row', direction: 'before' }
+    case 'right': return { axis: 'row', direction: 'after' }
+    case 'top': return { axis: 'column', direction: 'before' }
+    case 'bottom': return { axis: 'column', direction: 'after' }
+    /* v8 ignore next -- closed-union backstop; the compiler rejects a new zone here. */
+    default: return assertNever(zone, 'layout: dock zone')
+  }
+}
+
+/**
+ * Clamp divider sizes so no pane falls under `MIN_PANE_FRACTION`.
+ * @param sizes - candidate fractions from the drag preview.
+ * @param minimum - smallest allowed share; defaults to the kit's pane fraction.
+ * @returns fractions summing to 1 with every entry at or above the minimum.
+ */
+export function clampSizes(sizes: readonly number[], minimum = MIN_PANE_FRACTION): number[] {
+  if (sizes.length === 0) return []
+  const floor = Math.min(minimum, 1 / sizes.length)
+  const positive = sizes.map(size => (size > 0 ? size : 0))
+  const total = positive.reduce((sum, size) => sum + size, 0)
+  let shares = total > 0 ? positive.map(size => size / total) : positive.map(() => 1 / sizes.length)
+  // Pin every share under the floor at the floor and hand the remainder to the
+  // others in proportion; a share that only now drops under joins the pinned
+  // set on the next pass, so the result holds the floor exactly. The free
+  // shares sit at or above the floor and sum to at least the remainder, so at
+  // least one stays free and their total stays positive.
+  const pinned = new Set<number>()
+  for (;;) {
+    const under = shares.flatMap((share, index) => (!pinned.has(index) && share < floor ? [index] : []))
+    if (under.length === 0) return shares
+    for (const index of under) pinned.add(index)
+    const remainder = 1 - pinned.size * floor
+    const freeTotal = shares.reduce((sum, share, index) => (pinned.has(index) ? sum : sum + share), 0)
+    shares = shares.map((share, index) => (pinned.has(index) ? floor : (share / freeTotal) * remainder))
+  }
+}
diff --git a/packages/client/ui-dockkit/src/engine/controller.ts b/packages/client/ui-dockkit/src/engine/controller.ts
new file mode 100644
index 0000000000..9c599f71be
--- /dev/null
+++ b/packages/client/ui-dockkit/src/engine/controller.ts
@@ -0,0 +1,315 @@
+/**
+ * The intent layer's stateful embedding: one controller per docking surface,
+ * React-free, and itself the observable source the UI subscribes to
+ * (`subscribe` + `getSnapshot`, whose reference only changes when the layout
+ * does).
+ *
+ * Every method here is a planner call plus recording plus one notification. The
+ * decisions live in `planner.ts` so an embedder holding its layout in an external
+ * store shares them rather than reimplementing them; a planner that returns no
+ * operations records nothing and notifies nobody.
+ *
+ * The controller holds no host concepts: what a seeded tab contains arrives as a
+ * factory, and a tab's `kind` is an opaque string.
+ */
+import type {
+  DockMode, DockZone, FloatRect, LayoutOp, LayoutState, PaneId, SplitId, TabId,
+} from '../contract/types.ts'
+import { canSplit } from './constraints.ts'
+import { createIdMinter, createInitialState, type IdMinter, type TabFactory } from './initial.ts'
+import {
+  activeDockPaneId as dockedActivePane, planAddTab, planDropTab, planDuplicateTab, planFloatTab, planOpenContent, planPlaceTab,
+  planResizeSplit, planSetExpanded, planSetMode, planSplitPane, planUnfloatPane,
+  type OpenContentInput,
+} from './planner.ts'
+import type { Mint } from './planner.ts'
+import { Sequencer } from './sequence.ts'
+
+export type { OpenContentInput } from './planner.ts'
+
+/** Everything the rendering layer reads, in one immutable value. */
+export interface DockSnapshot {
+  readonly state: LayoutState
+  readonly canUndo: boolean
+  readonly canRedo: boolean
+  /** Whether the docked grid still has room for another pane. */
+  readonly canSplit: boolean
+  /** Recorded operation count, redo branch included. */
+  readonly opCount: number
+  /** How many recorded intents are applied. */
+  readonly cursor: number
+}
+
+/** What the embedder seeds new panes with. */
+export interface DockControllerOptions {
+  /** Builds the tab the starting pane holds; omit to start empty. */
+  readonly makeInitialTab?: TabFactory
+  /** Builds the tab a pane created by `splitPane` holds; omit to leave it empty. */
+  readonly makePaneTab?: TabFactory
+  /** Starting presentation; defaults to `push`. */
+  readonly mode?: DockMode
+}
+
+/** One docking surface: history, interaction limits, and change notification. */
+export class DockController {
+  private readonly minter: IdMinter
+  private readonly sequencer: Sequencer
+  private readonly listeners = new Set<() => void>()
+  private readonly makePaneTab: TabFactory | undefined
+  private snapshot: DockSnapshot
+
+  /** @param options - the tab factories this surface seeds panes with. */
+  constructor(options: DockControllerOptions = {}) {
+    this.minter = createIdMinter()
+    this.makePaneTab = options.makePaneTab
+    this.sequencer = new Sequencer(createInitialState(this.minter, options.makeInitialTab, options.mode))
+    this.snapshot = this.buildSnapshot()
+  }
+
+  /**
+   * Observe layout changes.
+   * @param listener - called after every committed change.
+   * @returns disposer removing the listener.
+   */
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  /** Current snapshot; the same reference until the layout changes. */
+  getSnapshot = (): DockSnapshot => this.snapshot
+
+  /** Recorded sequence, for tests and the operation readout. */
+  get ops(): readonly LayoutOp[] {
+    return this.sequencer.ops
+  }
+
+  private buildSnapshot(): DockSnapshot {
+    const state = this.sequencer.state
+    return {
+      state,
+      canUndo: this.sequencer.canUndo,
+      canRedo: this.sequencer.canRedo,
+      canSplit: canSplit(state),
+      opCount: this.sequencer.ops.length,
+      cursor: this.sequencer.cursor,
+    }
+  }
+
+  private commit(): void {
+    this.snapshot = this.buildSnapshot()
+    for (const listener of [...this.listeners]) listener()
+  }
+
+  private get state(): LayoutState {
+    return this.sequencer.state
+  }
+
+  private get mint(): Mint { return this.minter.next }
+
+  /**
+   * Record a planned intent as one history entry.
+   * @param ops - the planner's operations; empty plans nothing.
+   * @returns whether anything was recorded.
+   */
+  private run(ops: readonly LayoutOp[]): boolean {
+    if (ops.length === 0) return false
+    this.sequencer.dispatchAll(ops)
+    this.commit()
+    return true
+  }
+
+  /**
+   * Expand or collapse the docked area. Floating panels are unaffected.
+   * @param expanded - whether the docked area is shown.
+   */
+  setExpanded(expanded: boolean): void {
+    this.run(planSetExpanded(this.state, expanded))
+  }
+
+  /** Flip the docked area between expanded and collapsed. */
+  toggleExpanded(): void {
+    this.setExpanded(!this.state.expanded)
+  }
+
+  /**
+   * Switch how the docked area is presented.
+   * @param mode - the presentation to record.
+   */
+  setMode(mode: DockMode): void {
+    this.run(planSetMode(this.state, mode))
+  }
+
+  /**
+   * Split a pane to its right and seat the embedder's pane tab in the new pane.
+   * @param paneId - pane to split; defaults to the active docked pane.
+   * @returns false when the docked grid is already at `MAX_DOCK_PANES`.
+   */
+  splitPane(paneId?: PaneId): boolean {
+    return this.run(planSplitPane(this.state, this.mint, paneId, this.makePaneTab))
+  }
+
+  /**
+   * Seat the pane-tab factory's tab at the end of a pane's strip.
+   * @param paneId - the docked pane whose strip asked.
+   * @returns false when there is no factory or the pane is not docked.
+   */
+  addTab(paneId: PaneId): boolean {
+    return this.run(planAddTab(this.state, this.mint, paneId, this.makePaneTab))
+  }
+
+  /**
+   * Open content, or focus the tab already showing it.
+   * @param input - consistency id, copy, and optional target pane.
+   * @returns the tab now focused.
+   */
+  openContent(input: OpenContentInput): TabId {
+    const planned = planOpenContent(this.state, this.mint, input)
+    this.run(planned.ops)
+    return planned.tabId
+  }
+
+  /**
+   * Open a second, independent tab on the same content.
+   * @param tabId - tab to copy.
+   * @returns the new tab id.
+   */
+  duplicateTab(tabId: TabId): TabId {
+    const planned = planDuplicateTab(this.state, this.mint, tabId)
+    this.run(planned.ops)
+    return planned.tabId
+  }
+
+  /**
+   * Destroy a tab and its content state. A floating host panel goes with it.
+   * @param tabId - the tab to close.
+   */
+  closeTab(tabId: TabId): void {
+    this.run([{ type: 'closeTab', tabId }])
+  }
+
+  /**
+   * Focus a tab, its pane, and raise that pane when it floats.
+   * @param tabId - the tab to focus.
+   */
+  focusTab(tabId: TabId): void {
+    this.run([{ type: 'focusTab', tabId }])
+  }
+
+  /**
+   * Focus a pane, raising it when it floats.
+   * @param paneId - the pane to focus.
+   */
+  focusPane(paneId: PaneId): void {
+    this.run([{ type: 'focusPane', paneId }])
+  }
+
+  /**
+   * Move a tab inside its own pane.
+   * @param tabId - the tab to move.
+   * @param index - its position in the strip without it.
+   */
+  reorderTab(tabId: TabId, index: number): void {
+    this.run([{ type: 'reorderTab', tabId, index }])
+  }
+
+  /**
+   * Put a tab at an explicit slot: a reorder inside its own pane, otherwise a
+   * move (or a return, when it currently floats).
+   * @param tabId - the tab being placed.
+   * @param toPaneId - destination docked pane.
+   * @param index - caret slot in the destination strip, counting the dragged chip when the strip is its own.
+   * @returns false when the placement changes nothing.
+   */
+  placeTab(tabId: TabId, toPaneId: PaneId, index: number): boolean {
+    return this.run(planPlaceTab(this.state, tabId, toPaneId, index))
+  }
+
+  /**
+   * Resolve a tab drop inside the docked area.
+   * @param tabId - the dragged tab.
+   * @param targetPaneId - pane under the pointer.
+   * @param zone - dock region the pointer released in.
+   * @returns false when the drop changes nothing or the grid is full.
+   */
+  dropTab(tabId: TabId, targetPaneId: PaneId, zone: DockZone): boolean {
+    return this.run(planDropTab(this.state, this.mint, tabId, targetPaneId, zone))
+  }
+
+  /**
+   * Take a tab out into a floating panel.
+   * @param tabId - tab to float.
+   * @param rect - explicit rectangle; defaults to a cascade from the last panel.
+   * @returns the new floating pane id.
+   */
+  floatTab(tabId: TabId, rect?: FloatRect): PaneId {
+    const planned = planFloatTab(this.state, this.mint, tabId, rect)
+    this.run(planned.ops)
+    return planned.paneId
+  }
+
+  /**
+   * Send a floating panel's tab back into the docked tree.
+   * @param paneId - the floating pane.
+   * @param toPaneId - destination docked pane; defaults to the active one.
+   */
+  unfloatPane(paneId: PaneId, toPaneId?: PaneId): void {
+    this.run(planUnfloatPane(this.state, paneId, toPaneId))
+  }
+
+  /**
+   * Record the net position of a floating-panel drag; the panel is focused and raised with it.
+   * @param paneId - the floating pane.
+   * @param x - its new left edge, in viewport pixels.
+   * @param y - its new top edge, in viewport pixels.
+   */
+  moveFloat(paneId: PaneId, x: number, y: number): void {
+    this.run([{ type: 'moveFloat', paneId, x, y }])
+  }
+
+  /**
+   * Record the net rectangle of a floating-panel resize; the panel is focused and raised with it.
+   * @param paneId - the floating pane.
+   * @param rect - its new rectangle.
+   */
+  resizeFloat(paneId: PaneId, rect: FloatRect): void {
+    this.run([{ type: 'resizeFloat', paneId, rect }])
+  }
+
+  /**
+   * Record the net sizes of a divider drag, clamped to the pane minimum.
+   * @param splitId - the split whose divider moved.
+   * @param sizes - the fractions the drag reached.
+   */
+  resizeSplit(splitId: SplitId, sizes: readonly number[]): void {
+    this.run(planResizeSplit(splitId, sizes))
+  }
+
+  /**
+   * Step back one intent, or one run of consecutive focus-only intents.
+   * @returns false when there is nothing to undo.
+   */
+  undo(): boolean {
+    if (!this.sequencer.undo()) return false
+    this.commit()
+    return true
+  }
+
+  /**
+   * Step forward over what the matching undo stepped back.
+   * @returns false when there is nothing to redo.
+   */
+  redo(): boolean {
+    if (!this.sequencer.redo()) return false
+    this.commit()
+    return true
+  }
+
+  /**
+   * The pane a new tab lands in, for an embedder that needs to name it.
+   * @returns the active pane when docked, else the first docked pane.
+   */
+  activeDockPaneId(): PaneId {
+    return dockedActivePane(this.state)
+  }
+}
diff --git a/packages/client/ui-dockkit/src/engine/geometry.ts b/packages/client/ui-dockkit/src/engine/geometry.ts
new file mode 100644
index 0000000000..ff32cd3208
--- /dev/null
+++ b/packages/client/ui-dockkit/src/engine/geometry.ts
@@ -0,0 +1,208 @@
+/**
+ * Pure geometry for the drag interaction: point tests, dock-zone resolution
+ * against a real element rectangle, and tab-strip insertion slots. Kept free of
+ * React and DOM types so the drop rules can be asserted without a browser; the
+ * component layer measures rectangles and calls in.
+ */
+import type { DockZone, FloatRect, PaneId } from '../contract/types.ts'
+import { DOCK_EDGE_FRACTION, zoneAt } from './constraints.ts'
+
+/** A measured rectangle in viewport coordinates. */
+export interface Rect {
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+}
+
+/** Where a drag would land if released now. */
+export type DropTarget =
+  /** Into a tab strip at an explicit slot: a reorder or a cross-pane move. */
+  | { readonly kind: 'strip'; readonly paneId: PaneId; readonly index: number }
+  /** Onto a pane body: the centre moves the tab in, an edge splits the pane. */
+  | { readonly kind: 'zone'; readonly paneId: PaneId; readonly zone: DockZone }
+
+/**
+ * Whether a point is inside a rectangle, edges included.
+ * @param rect - the rectangle.
+ * @param x - point x in the same coordinates.
+ * @param y - point y in the same coordinates.
+ * @returns whether the point lies on or inside the rectangle.
+ */
+export function containsPoint(rect: Rect, x: number, y: number): boolean {
+  return x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height
+}
+
+/**
+ * Dock region a point falls in, relative to one pane's rectangle.
+ * @param rect - the pane's measured box.
+ * @param x - pointer x in the same coordinates.
+ * @param y - pointer y in the same coordinates.
+ * @param edge - edge band as a fraction; defaults to the model's value.
+ * @returns the region; `'center'` when the point is not in an edge band.
+ */
+export function zoneInRect(rect: Rect, x: number, y: number, edge: number = DOCK_EDGE_FRACTION): DockZone {
+  if (!(rect.width > 0) || !(rect.height > 0)) return 'center'
+  return zoneAt((x - rect.x) / rect.width, (y - rect.y) / rect.height, edge)
+}
+
+/**
+ * Slot a tab would take in a strip, by comparing the pointer with each tab's midpoint.
+ * @param tabRects - the strip's tab boxes in strip order.
+ * @param x - pointer x.
+ * @returns the insertion index, from 0 to `tabRects.length`.
+ */
+export function insertionIndex(tabRects: readonly Rect[], x: number): number {
+  let index = 0
+  for (const rect of tabRects) {
+    if (x < rect.x + rect.width / 2) break
+    index += 1
+  }
+  return index
+}
+
+/** What one pane's strip measured, for the room rule. */
+export interface PaneMeasure {
+  /** The pane's box, borders included. */
+  readonly pane: Rect
+  /** The strip's box, inside the borders; its height is what a vertical half must carry. */
+  readonly strip: Rect
+  /** Width of the chip box, the strip's one shrinking part. */
+  readonly chipsWidth: number
+  /** Width of the fill: free space, not a control. */
+  readonly fillWidth: number
+}
+
+/** Pixel minimums the room rule holds each half to. */
+export interface SplitMinimums {
+  /** The divider a split puts between the halves. */
+  readonly divider: number
+  /** One chip at its minimum: the smallest strip that still names a tab. */
+  readonly chip: number
+  /** The smallest body under a strip: one secondary text line inside the body's padding. */
+  readonly body: number
+}
+
+/**
+ * The minimums where no computed style can be read, mirroring
+ * `dockkit.module.css`: `.splitRow > .divider` is 4px wide; `.tab` is 44px of
+ * content plus 10px + 5px of padding (content-box), 59px; the body's 12px
+ * padding above and below one 13px secondary line at 1.6 line-height is 45px,
+ * held to 48px.
+ */
+export const SPLIT_MINIMUMS: SplitMinimums = { divider: 4, chip: 59, body: 48 }
+
+/** Whether a pane's two halves after an equal split would each still work. */
+export interface HalvesFit {
+  /** A row split: each half holds the strip's fixed controls and one minimum chip. */
+  readonly row: boolean
+  /** A column split: each half holds the strip and a minimum body. */
+  readonly column: boolean
+}
+
+/**
+ * The room rule. After an equal split each half must hold what cannot shrink:
+ * horizontally the strip's fixed part — its width minus the chip box and the
+ * fill, which is the padding, the gaps, and every control that pane draws —
+ * plus one chip at its minimum; vertically the strip plus a minimum body. The
+ * borders are what the pane's box exceeds the strip's by. An unmeasured pane
+ * (no layout, as under jsdom) fits: the rule only blocks on a positive reading.
+ * @param measure - the pane's rectangles.
+ * @param minimums - the pixel minimums; defaults to the stylesheet's.
+ * @returns whether a row and a column split each leave two working halves.
+ */
+export function halvesFit(measure: PaneMeasure, minimums: SplitMinimums = SPLIT_MINIMUMS): HalvesFit {
+  const { pane, strip } = measure
+  if (!(pane.width > 0) || !(pane.height > 0) || !(strip.width > 0)) return { row: true, column: true }
+  const borders = Math.max(0, pane.width - strip.width)
+  const fixed = Math.max(0, strip.width - measure.chipsWidth - measure.fillWidth)
+  const halfWidth = (pane.width - minimums.divider) / 2 - borders
+  const halfHeight = (pane.height - minimums.divider) / 2 - borders
+  return {
+    row: halfWidth >= fixed + minimums.chip,
+    column: halfHeight >= strip.height + minimums.body,
+  }
+}
+
+/** How far a pointer must travel before a press becomes a drag, in pixels. */
+export const DRAG_THRESHOLD = 4
+
+/**
+ * Whether a press has travelled far enough to be a drag.
+ * @param startX - press x.
+ * @param startY - press y.
+ * @param x - current pointer x.
+ * @param y - current pointer y.
+ * @returns whether either axis moved at least `DRAG_THRESHOLD`.
+ */
+export function passedThreshold(startX: number, startY: number, x: number, y: number): boolean {
+  return Math.abs(x - startX) >= DRAG_THRESHOLD || Math.abs(y - startY) >= DRAG_THRESHOLD
+}
+
+/**
+ * Split fractions after a divider drag.
+ * @param sizes - the split's current fractions.
+ * @param index - divider position: the boundary between `index` and `index + 1`.
+ * @param delta - pointer travel along the split axis, as a fraction of the split's extent.
+ * @returns new fractions; the two neighbours absorb the whole change.
+ */
+export function dividerSizes(
+  sizes: readonly number[],
+  index: number,
+  delta: number,
+): number[] {
+  const before = sizes[index]
+  const after = sizes[index + 1]
+  if (before === undefined || after === undefined) return [...sizes]
+  const next = [...sizes]
+  next[index] = before + delta
+  next[index + 1] = after - delta
+  return next
+}
+
+/** A width/height pair used as a floating-panel bound. */
+export interface Size {
+  readonly width: number
+  readonly height: number
+}
+
+/**
+ * A floating panel's rectangle after a drag.
+ * @param rect - the rectangle the gesture started from.
+ * @param dx - pointer travel on x.
+ * @param dy - pointer travel on y.
+ * @returns the moved rectangle; the size is unchanged.
+ */
+export function movedRect(rect: FloatRect, dx: number, dy: number): FloatRect {
+  return { ...rect, x: rect.x + dx, y: rect.y + dy }
+}
+
+/**
+ * A floating panel's rectangle after a bottom-right resize.
+ * @param rect - the rectangle the gesture started from.
+ * @param dx - pointer travel on x.
+ * @param dy - pointer travel on y.
+ * @param min - smallest size the panel may take.
+ * @returns the resized rectangle; the origin is unchanged.
+ */
+export function resizedRect(rect: FloatRect, dx: number, dy: number, min: Size): FloatRect {
+  return {
+    ...rect,
+    width: Math.max(min.width, rect.width + dx),
+    height: Math.max(min.height, rect.height + dy),
+  }
+}
+
+/**
+ * Where a panel should appear when a tab is dropped outside the docked area.
+ * @param x - drop point x.
+ * @param y - drop point y.
+ * @param size - the panel's size.
+ * @returns a rectangle whose header sits under the drop point.
+ */
+export function floatRectAt(x: number, y: number, size: Size): FloatRect {
+  return { x: Math.max(0, x - GRAB_OFFSET.x), y: Math.max(0, y - GRAB_OFFSET.y), ...size }
+}
+
+/** How far the new panel's origin sits above and left of the drop point. */
+const GRAB_OFFSET = { x: 60, y: 14 } as const
diff --git a/packages/client/ui-dockkit/src/engine/initial.ts b/packages/client/ui-dockkit/src/engine/initial.ts
new file mode 100644
index 0000000000..b3b1313d20
--- /dev/null
+++ b/packages/client/ui-dockkit/src/engine/initial.ts
@@ -0,0 +1,73 @@
+/**
+ * Initial state and the identity mint every operation draws its new ids from.
+ * Ids are minted outside `applyOp` so a recorded sequence replays to the exact
+ * same tree.
+ *
+ * What the first tab *is* belongs to the embedder: pass a factory and this
+ * module only decides where it sits.
+ */
+import type { DockMode, LayoutState, PaneId, TabId, TabRecord } from '../contract/types.ts'
+import type { Mint } from './planner.ts'
+
+/** Monotonic id source; one instance belongs to one surface's sequence. */
+export interface IdMinter {
+  /** Next id under `prefix`, unique for the life of this minter; the prefix names the id's kind. */
+  readonly next: Mint
+}
+
+/**
+ * Create an id source.
+ * @param seed - number the first id counts from; defaults to 0.
+ * @returns a minter producing `<prefix><n>` ids.
+ */
+export function createIdMinter(seed = 0): IdMinter {
+  let counter = seed
+  // The one place a string becomes an id: the prefix names the kind, the counter
+  // keeps every id this minter hands out unique.
+  const next = ((prefix: string): string => {
+    counter += 1
+    return `${prefix}${counter}`
+  }) as Mint
+  return { next }
+}
+
+/** Builds the tab record a newly seeded pane should hold. */
+export type TabFactory = (id: TabId) => TabRecord
+
+/**
+ * The state a surface starts in: collapsed, one docked pane, and whatever tab
+ * `makeInitialTab` supplies.
+ *
+ * The first tab belongs to the initial state rather than to an operation, so
+ * expanding and collapsing never accumulates copies of it.
+ * @param minter - id source this surface's sequence will keep using.
+ * @param makeInitialTab - builds the starting tab; omit for an empty pane.
+ * @param mode - starting presentation; the embedder's product default.
+ * @returns the collapsed single-pane starting state.
+ */
+export function createInitialState(
+  minter: IdMinter,
+  makeInitialTab?: TabFactory,
+  mode: DockMode = 'push',
+): LayoutState {
+  const paneId: PaneId = minter.next('pane')
+  const initial = makeInitialTab?.(minter.next('tab'))
+  return {
+    nodes: {
+      [paneId]: {
+        kind: 'pane',
+        id: paneId,
+        host: 'dock',
+        tabs: initial === undefined ? [] : [initial.id],
+        activeTabId: initial?.id,
+        rect: undefined,
+      },
+    },
+    tabs: initial === undefined ? {} : { [initial.id]: initial },
+    rootId: paneId,
+    floats: [],
+    activePaneId: paneId,
+    expanded: false,
+    mode,
+  }
+}
diff --git a/packages/client/ui-dockkit/src/engine/operations.ts b/packages/client/ui-dockkit/src/engine/operations.ts
new file mode 100644
index 0000000000..c090099404
--- /dev/null
+++ b/packages/client/ui-dockkit/src/engine/operations.ts
@@ -0,0 +1,464 @@
+/**
+ * The operation engine: one pure `applyOp` that returns the next state plus the
+ * operations that undo it. No React, no DOM, no ambient state — replaying the
+ * same operations over the same initial state always yields the same result,
+ * because every id an operation creates travels inside the operation.
+ *
+ * Interaction limits (pane count, drag preview coalescing) are not enforced
+ * here; they belong to the interaction layer (`constraints.ts` and the UI).
+ */
+import type {
+  ApplyResult, FloatRect, LayoutOp, LayoutState, NodeId, PaneId, PaneNode, TabId,
+} from '../contract/types.ts'
+import {
+  assertNever, entriesOf, findParent, findTabPane, firstDockPaneId, floatIndex, floatRect, getPane, getSplit, getTab,
+  insertAt, keysOf, neighbourTabId, normalizeSizes, onlyTabId, paneWithTabs, removeAt, replaceInParent, withNodes, withTabs,
+} from './tree.ts'
+
+/** Capture the focus facts of `paneIds` plus global focus, as the operation that restores them. */
+function focusSnapshot(state: LayoutState, paneIds: readonly PaneId[]): LayoutOp {
+  const paneActiveTabs: Record<PaneId, TabId | undefined> = {}
+  for (const id of paneIds) paneActiveTabs[id] = getPane(state, id).activeTabId
+  return {
+    type: 'restoreFocus',
+    activePaneId: state.activePaneId,
+    floats: state.floats,
+    paneActiveTabs,
+  }
+}
+
+/** Move `paneId` to the top of the floating z order. */
+function raise(floats: readonly PaneId[], paneId: PaneId): PaneId[] {
+  return [...floats.filter(id => id !== paneId), paneId]
+}
+
+/** Keep `activePaneId` on a live pane after `state` lost the focused one. */
+function reseatFocus(state: LayoutState, removedPaneId: PaneId): LayoutState {
+  if (state.activePaneId !== removedPaneId) return state
+  return { ...state, activePaneId: firstDockPaneId(state) }
+}
+
+/** A fresh empty docked pane. */
+function emptyDockPane(id: PaneId): PaneNode {
+  return { kind: 'pane', id, host: 'dock', tabs: [], activeTabId: undefined, rect: undefined }
+}
+
+/** Reject an id that a creating operation expects to be free. */
+function assertFreeNode(state: LayoutState, id: NodeId): void {
+  if (state.nodes[id] !== undefined) throw new Error(`layout: node ${id} already exists`)
+}
+
+/** Reject a tab id that an opening operation expects to be free. */
+function assertFreeTab(state: LayoutState, id: TabId): void {
+  if (state.tabs[id] !== undefined) throw new Error(`layout: tab ${id} already exists`)
+}
+
+/** Give `paneId` an empty sibling along `axis`. */
+function applySplit(state: LayoutState, op: Extract<LayoutOp, { type: 'split' }>): ApplyResult {
+  const pane = getPane(state, op.paneId)
+  if (pane.host !== 'dock') throw new Error('layout: split requires a docked pane')
+  assertFreeNode(state, op.newPaneId)
+  const newPane = emptyDockPane(op.newPaneId)
+  const parent = findParent(state, op.paneId)
+
+  if (parent !== undefined && parent.axis === op.axis) {
+    const index = parent.children.indexOf(op.paneId)
+    const at = op.direction === 'after' ? index + 1 : index
+    const children = insertAt(parent.children, at, op.newPaneId)
+    // The reference pane's share is halved between it and the new pane; the two
+    // halves are equal, so the sizes align with `children` whichever side it took.
+    const sizes = parent.sizes.flatMap((size, i) => (i === index ? [size / 2, size / 2] : [size]))
+    return {
+      state: withNodes(state, { [op.newPaneId]: newPane, [parent.id]: { ...parent, children, sizes } }),
+      inverse: [
+        { type: 'merge', paneId: op.newPaneId },
+        { type: 'resize', splitId: parent.id, sizes: parent.sizes },
+      ],
+    }
+  }
+
+  assertFreeNode(state, op.newSplitId)
+  // The reference pane's slot takes the new split; compute that swap before the
+  // split node exists, or `findParent` would find the split itself.
+  const rehomed = replaceInParent(state, op.paneId, op.newSplitId)
+  const children = op.direction === 'after' ? [op.paneId, op.newPaneId] : [op.newPaneId, op.paneId]
+  return {
+    state: withNodes(rehomed, {
+      [op.newPaneId]: newPane,
+      [op.newSplitId]: { kind: 'split', id: op.newSplitId, axis: op.axis, children, sizes: [0.5, 0.5] },
+    }),
+    inverse: [{ type: 'merge', paneId: op.newPaneId }],
+  }
+}
+
+/** Drop an empty pane; a two-child split collapses into its surviving child. */
+function applyMerge(state: LayoutState, op: Extract<LayoutOp, { type: 'merge' }>): ApplyResult {
+  const pane = getPane(state, op.paneId)
+  if (pane.tabs.length > 0) throw new Error('layout: merge requires an empty pane')
+  const focus = focusSnapshot(state, [])
+
+  if (pane.host === 'float') {
+    const index = floatIndex(state, op.paneId)
+    const dropped = withNodes({ ...state, floats: removeAt(state.floats, index) }, { [op.paneId]: null })
+    return {
+      state: reseatFocus(dropped, op.paneId),
+      inverse: [{ type: 'insertPane', pane, tabs: [], attach: { mode: 'float', index } }, focus],
+    }
+  }
+
+  const parent = findParent(state, op.paneId)
+  if (parent === undefined) throw new Error('layout: the docked root pane cannot be merged')
+  const index = parent.children.indexOf(op.paneId)
+
+  if (parent.children.length > 2) {
+    const children = removeAt(parent.children, index)
+    const sizes = normalizeSizes(removeAt(parent.sizes, index))
+    const dropped = withNodes(state, { [op.paneId]: null, [parent.id]: { ...parent, children, sizes } })
+    return {
+      state: reseatFocus(dropped, op.paneId),
+      inverse: [
+        {
+          type: 'insertPane',
+          pane,
+          tabs: [],
+          attach: { mode: 'child', parentId: parent.id, index, sizes: parent.sizes },
+        },
+        focus,
+      ],
+    }
+  }
+
+  const siblingId = parent.children[1 - index]
+  /* v8 ignore next -- a split holds at least two children, so one survives the merged pane. */
+  if (siblingId === undefined) throw new Error('layout: merge found a split without a sibling')
+  const collapsed = withNodes(replaceInParent(state, parent.id, siblingId), {
+    [op.paneId]: null,
+    [parent.id]: null,
+  })
+  return {
+    state: reseatFocus(collapsed, op.paneId),
+    inverse: [
+      { type: 'insertPane', pane, tabs: [], attach: { mode: 'wrap', targetId: siblingId, split: parent } },
+      focus,
+    ],
+  }
+}
+
+/** Add a new tab to a docked pane and focus it. */
+function applyOpenTab(state: LayoutState, op: Extract<LayoutOp, { type: 'openTab' }>): ApplyResult {
+  const pane = getPane(state, op.paneId)
+  if (pane.host !== 'dock') throw new Error('layout: openTab requires a docked pane')
+  assertFreeTab(state, op.tab.id)
+  const focus = focusSnapshot(state, [pane.id])
+  const seated = withNodes(withTabs(state, { [op.tab.id]: op.tab }), {
+    [pane.id]: paneWithTabs(pane, insertAt(pane.tabs, op.index, op.tab.id), op.tab.id),
+  })
+  return {
+    state: { ...seated, activePaneId: pane.id },
+    inverse: [{ type: 'closeTab', tabId: op.tab.id }, focus],
+  }
+}
+
+/** Put one tab record back where it was, without stealing focus. */
+function applyInsertTab(state: LayoutState, op: Extract<LayoutOp, { type: 'insertTab' }>): ApplyResult {
+  const pane = getPane(state, op.paneId)
+  if (pane.host !== 'dock') throw new Error('layout: insertTab requires a docked pane')
+  assertFreeTab(state, op.tab.id)
+  const focus = focusSnapshot(state, [pane.id])
+  const tabs = insertAt(pane.tabs, op.index, op.tab.id)
+  return {
+    state: withNodes(withTabs(state, { [op.tab.id]: op.tab }), {
+      [pane.id]: paneWithTabs(pane, tabs, pane.activeTabId ?? op.tab.id),
+    }),
+    inverse: [{ type: 'closeTab', tabId: op.tab.id }, focus],
+  }
+}
+
+/** Destroy a tab and its content state; a floating host pane goes with its only tab. */
+function applyCloseTab(state: LayoutState, op: Extract<LayoutOp, { type: 'closeTab' }>): ApplyResult {
+  const tab = getTab(state, op.tabId)
+  const pane = findTabPane(state, op.tabId)
+  const index = pane.tabs.indexOf(op.tabId)
+  const focus = focusSnapshot(state, [pane.id])
+
+  if (pane.host === 'float') {
+    const index = floatIndex(state, pane.id)
+    const dropped = withTabs(
+      withNodes({ ...state, floats: removeAt(state.floats, index) }, { [pane.id]: null }),
+      { [op.tabId]: null },
+    )
+    return {
+      state: reseatFocus(dropped, pane.id),
+      inverse: [
+        { type: 'insertPane', pane, tabs: [tab], attach: { mode: 'float', index } },
+        focus,
+      ],
+    }
+  }
+
+  const activeTabId = pane.activeTabId === op.tabId ? neighbourTabId(pane.tabs, index) : pane.activeTabId
+  return {
+    state: withTabs(
+      withNodes(state, { [pane.id]: paneWithTabs(pane, removeAt(pane.tabs, index), activeTabId) }),
+      { [op.tabId]: null },
+    ),
+    inverse: [{ type: 'insertTab', paneId: pane.id, tab, index }, focus],
+  }
+}
+
+/**
+ * Put a pane back, with the tab records it owned. A docked pane returns empty
+ * (its tabs return through `insertTab`, as `closeTab` records them); a floating
+ * pane returns with its one tab, or empty.
+ */
+function applyInsertPane(state: LayoutState, op: Extract<LayoutOp, { type: 'insertPane' }>): ApplyResult {
+  assertFreeNode(state, op.pane.id)
+  if (op.pane.tabs.length !== op.tabs.length) throw new Error('layout: insertPane tab records do not match the pane')
+  if (op.pane.host === 'dock' && op.tabs.length > 0) throw new Error('layout: insertPane returns a docked pane empty')
+  const tabUpdates: Record<TabId, typeof op.tabs[number]> = {}
+  for (const tab of op.tabs) {
+    assertFreeTab(state, tab.id)
+    tabUpdates[tab.id] = tab
+  }
+  const restoredTab = op.tabs[0]
+  const inverse: LayoutOp[] = restoredTab === undefined
+    ? [{ type: 'merge', paneId: op.pane.id }]
+    : [{ type: 'closeTab', tabId: restoredTab.id }, focusSnapshot(state, [])]
+
+  const attach = op.attach
+  switch (attach.mode) {
+    case 'child': {
+      const parent = getSplit(state, attach.parentId)
+      const children = insertAt(parent.children, attach.index, op.pane.id)
+      if (attach.sizes.length !== children.length) throw new Error('layout: insertPane sizes do not match the split')
+      inverse.push({ type: 'resize', splitId: parent.id, sizes: parent.sizes })
+      return {
+        state: withNodes(withTabs(state, tabUpdates), {
+          [op.pane.id]: op.pane,
+          [parent.id]: { ...parent, children, sizes: attach.sizes },
+        }),
+        inverse,
+      }
+    }
+    case 'wrap': {
+      if (!attach.split.children.includes(op.pane.id)) {
+        throw new Error('layout: insertPane wrap split does not list the pane')
+      }
+      const rehomed = replaceInParent(state, attach.targetId, attach.split.id)
+      return {
+        state: withNodes(withTabs(rehomed, tabUpdates), {
+          [op.pane.id]: op.pane,
+          [attach.split.id]: attach.split,
+        }),
+        inverse,
+      }
+    }
+    case 'float': {
+      if (op.pane.host !== 'float') throw new Error('layout: float attachment requires a floating pane')
+      const floats = insertAt(state.floats, attach.index, op.pane.id)
+      return {
+        state: withNodes(withTabs({ ...state, floats }, tabUpdates), { [op.pane.id]: op.pane }),
+        inverse,
+      }
+    }
+    /* v8 ignore next 2 -- closed-union backstop; the compiler rejects a new attachment mode here. */
+    default:
+      return assertNever(attach, 'layout: insertPane attachment')
+  }
+}
+
+/** Move a tab to a different docked pane and focus it there. */
+function applyMoveTab(state: LayoutState, op: Extract<LayoutOp, { type: 'moveTab' }>): ApplyResult {
+  const from = findTabPane(state, op.tabId)
+  if (from.host !== 'dock') throw new Error('layout: moveTab source must be docked; use unfloat')
+  const to = getPane(state, op.toPaneId)
+  if (to.host !== 'dock') throw new Error('layout: moveTab target must be docked')
+  if (to.id === from.id) throw new Error('layout: moveTab across one pane; use reorderTab')
+  const index = from.tabs.indexOf(op.tabId)
+  const focus = focusSnapshot(state, [from.id, to.id])
+  const activeTabId = from.activeTabId === op.tabId ? neighbourTabId(from.tabs, index) : from.activeTabId
+  const moved = withNodes(state, {
+    [from.id]: paneWithTabs(from, removeAt(from.tabs, index), activeTabId),
+    [to.id]: paneWithTabs(to, insertAt(to.tabs, op.index, op.tabId), op.tabId),
+  })
+  return {
+    state: { ...moved, activePaneId: to.id },
+    inverse: [{ type: 'moveTab', tabId: op.tabId, toPaneId: from.id, index }, focus],
+  }
+}
+
+/** Move a tab within its own pane. */
+function applyReorderTab(state: LayoutState, op: Extract<LayoutOp, { type: 'reorderTab' }>): ApplyResult {
+  const pane = findTabPane(state, op.tabId)
+  const from = pane.tabs.indexOf(op.tabId)
+  const tabs = insertAt(removeAt(pane.tabs, from), op.index, op.tabId)
+  return {
+    state: withNodes(state, { [pane.id]: { ...pane, tabs } }),
+    inverse: [{ type: 'reorderTab', tabId: op.tabId, index: from }],
+  }
+}
+
+/** Focus a tab, its pane, and raise that pane when floating. */
+function applyFocusTab(state: LayoutState, op: Extract<LayoutOp, { type: 'focusTab' }>): ApplyResult {
+  const pane = findTabPane(state, op.tabId)
+  const focus = focusSnapshot(state, [pane.id])
+  const focused = withNodes(state, { [pane.id]: { ...pane, activeTabId: op.tabId } })
+  const floats = pane.host === 'float' ? raise(focused.floats, pane.id) : focused.floats
+  return { state: { ...focused, activePaneId: pane.id, floats }, inverse: [focus] }
+}
+
+/** Focus a pane and raise it when floating. */
+function applyFocusPane(state: LayoutState, op: Extract<LayoutOp, { type: 'focusPane' }>): ApplyResult {
+  const pane = getPane(state, op.paneId)
+  const focus = focusSnapshot(state, [])
+  const floats = pane.host === 'float' ? raise(state.floats, pane.id) : state.floats
+  return { state: { ...state, activePaneId: pane.id, floats }, inverse: [focus] }
+}
+
+/** Record the net result of a divider drag. */
+function applyResize(state: LayoutState, op: Extract<LayoutOp, { type: 'resize' }>): ApplyResult {
+  const split = getSplit(state, op.splitId)
+  if (op.sizes.length !== split.children.length) throw new Error('layout: resize sizes do not match the split')
+  if (op.sizes.some(size => !(size > 0))) throw new Error('layout: resize sizes must all be above zero')
+  return {
+    state: withNodes(state, { [split.id]: { ...split, sizes: normalizeSizes(op.sizes) } }),
+    inverse: [{ type: 'resize', splitId: split.id, sizes: split.sizes }],
+  }
+}
+
+/** Take a tab out of the docked tree into a new floating pane on top. */
+function applyFloat(state: LayoutState, op: Extract<LayoutOp, { type: 'float' }>): ApplyResult {
+  getTab(state, op.tabId)
+  const from = findTabPane(state, op.tabId)
+  if (from.host !== 'dock') throw new Error('layout: float requires a docked tab')
+  assertFreeNode(state, op.newPaneId)
+  const index = from.tabs.indexOf(op.tabId)
+  const focus = focusSnapshot(state, [from.id])
+  const activeTabId = from.activeTabId === op.tabId ? neighbourTabId(from.tabs, index) : from.activeTabId
+  const floated = withNodes(state, {
+    [from.id]: paneWithTabs(from, removeAt(from.tabs, index), activeTabId),
+    [op.newPaneId]: {
+      kind: 'pane',
+      id: op.newPaneId,
+      host: 'float',
+      tabs: [op.tabId],
+      activeTabId: op.tabId,
+      rect: op.rect,
+    },
+  })
+  return {
+    state: { ...floated, floats: [...floated.floats, op.newPaneId], activePaneId: op.newPaneId },
+    inverse: [{ type: 'unfloat', paneId: op.newPaneId, toPaneId: from.id, index }, focus],
+  }
+}
+
+/** Return a floating pane's only tab to a docked pane and destroy the floating pane. */
+function applyUnfloat(state: LayoutState, op: Extract<LayoutOp, { type: 'unfloat' }>): ApplyResult {
+  const pane = getPane(state, op.paneId)
+  const rect = floatRect(pane)
+  const tabId = onlyTabId(pane)
+  const to = getPane(state, op.toPaneId)
+  if (to.host !== 'dock') throw new Error('layout: unfloat target must be docked')
+  const focus = focusSnapshot(state, [to.id])
+  const docked = withNodes({ ...state, floats: removeAt(state.floats, floatIndex(state, op.paneId)) }, {
+    [op.paneId]: null,
+    [to.id]: paneWithTabs(to, insertAt(to.tabs, op.index, tabId), tabId),
+  })
+  return {
+    state: { ...docked, activePaneId: to.id },
+    inverse: [{ type: 'float', tabId, newPaneId: op.paneId, rect }, focus],
+  }
+}
+
+/** Give a floating pane a new rectangle, focus it, and raise it: the one operation a drag of it records. */
+function reshapeFloat(state: LayoutState, pane: PaneNode, rect: FloatRect): LayoutState {
+  const reshaped = withNodes(state, { [pane.id]: { ...pane, rect } })
+  return { ...reshaped, activePaneId: pane.id, floats: raise(reshaped.floats, pane.id) }
+}
+
+/** Record the net result of dragging a floating pane, which also focuses and raises it. */
+function applyMoveFloat(state: LayoutState, op: Extract<LayoutOp, { type: 'moveFloat' }>): ApplyResult {
+  const pane = getPane(state, op.paneId)
+  const rect = floatRect(pane)
+  return {
+    state: reshapeFloat(state, pane, { ...rect, x: op.x, y: op.y }),
+    inverse: [{ type: 'moveFloat', paneId: op.paneId, x: rect.x, y: rect.y }, focusSnapshot(state, [])],
+  }
+}
+
+/** Record the net result of resizing a floating pane, which also focuses and raises it. */
+function applyResizeFloat(state: LayoutState, op: Extract<LayoutOp, { type: 'resizeFloat' }>): ApplyResult {
+  const pane = getPane(state, op.paneId)
+  const rect = floatRect(pane)
+  if (!(op.rect.width > 0) || !(op.rect.height > 0)) throw new Error('layout: float size must be above zero')
+  return {
+    state: reshapeFloat(state, pane, op.rect),
+    inverse: [{ type: 'resizeFloat', paneId: op.paneId, rect }, focusSnapshot(state, [])],
+  }
+}
+
+/** Restore focus facts a previous operation displaced. */
+function applyRestoreFocus(state: LayoutState, op: Extract<LayoutOp, { type: 'restoreFocus' }>): ApplyResult {
+  const inverse = focusSnapshot(state, keysOf(op.paneActiveTabs))
+  for (const paneId of op.floats) {
+    const pane = getPane(state, paneId)
+    if (pane.host !== 'float') throw new Error(`layout: restoreFocus lists docked pane ${paneId} as floating`)
+  }
+  let next = state
+  for (const [paneId, activeTabId] of entriesOf(op.paneActiveTabs)) {
+    const pane = getPane(next, paneId)
+    next = withNodes(next, { [paneId]: { ...pane, activeTabId } })
+  }
+  getPane(next, op.activePaneId)
+  return { state: { ...next, activePaneId: op.activePaneId, floats: op.floats }, inverse: [inverse] }
+}
+
+/**
+ * Apply one operation.
+ * @param state - state the operation reads; never mutated.
+ * @param op - the operation, carrying every id it creates.
+ * @returns the next state and the operations that undo it, applied in order.
+ * @throws when the operation addresses missing nodes or breaks a model rule.
+ */
+export function applyOp(state: LayoutState, op: LayoutOp): ApplyResult {
+  switch (op.type) {
+    case 'split': return applySplit(state, op)
+    case 'merge': return applyMerge(state, op)
+    case 'openTab': return applyOpenTab(state, op)
+    case 'insertTab': return applyInsertTab(state, op)
+    case 'closeTab': return applyCloseTab(state, op)
+    case 'insertPane': return applyInsertPane(state, op)
+    case 'moveTab': return applyMoveTab(state, op)
+    case 'reorderTab': return applyReorderTab(state, op)
+    case 'focusTab': return applyFocusTab(state, op)
+    case 'focusPane': return applyFocusPane(state, op)
+    case 'resize': return applyResize(state, op)
+    case 'float': return applyFloat(state, op)
+    case 'unfloat': return applyUnfloat(state, op)
+    case 'moveFloat': return applyMoveFloat(state, op)
+    case 'resizeFloat': return applyResizeFloat(state, op)
+    case 'setExpanded':
+      return {
+        state: { ...state, expanded: op.expanded },
+        inverse: [{ type: 'setExpanded', expanded: state.expanded }],
+      }
+    case 'setMode':
+      return {
+        state: { ...state, mode: op.mode },
+        inverse: [{ type: 'setMode', mode: state.mode }],
+      }
+    case 'restoreFocus': return applyRestoreFocus(state, op)
+    /* v8 ignore next -- closed-union backstop; the compiler rejects a new operation type here. */
+    default: return assertNever(op, 'layout: operation')
+  }
+}
+
+/**
+ * Fold operations forward, discarding inverses.
+ * @param state - starting state.
+ * @param ops - operations in recorded order.
+ * @returns the state after every operation.
+ */
+export function replay(state: LayoutState, ops: readonly LayoutOp[]): LayoutState {
+  return ops.reduce((current, op) => applyOp(current, op).state, state)
+}
diff --git a/packages/client/ui-dockkit/src/engine/planner.ts b/packages/client/ui-dockkit/src/engine/planner.ts
new file mode 100644
index 0000000000..1c61ab94c2
--- /dev/null
+++ b/packages/client/ui-dockkit/src/engine/planner.ts
@@ -0,0 +1,389 @@
+/**
+ * Intent planning: each interaction, as a pure function from the current state to
+ * the operations that carry it out.
+ *
+ * Planners mint the ids their operations create and enforce the interaction
+ * limits, but they hold no state and apply nothing. That split is what lets the
+ * same intent vocabulary serve two embeddings — a `DockController` that keeps the
+ * state itself, and a host store that keeps it and only needs the operations —
+ * without either one reimplementing `openContent`'s identity lookup, `dropTab`'s
+ * region resolution, or the floating cascade.
+ *
+ * A planner returning no operations means the intent changes nothing; the caller
+ * records nothing and notifies nobody.
+ */
+import type {
+  DockMode, DockZone, FloatRect, LayoutOp, LayoutState, PaneId, PaneNode, SplitId, TabId, TabRecord,
+} from '../contract/types.ts'
+import { canSplit, clampSizes, FLOAT_DEFAULT_SIZE, zoneSplit } from './constraints.ts'
+import type { TabFactory } from './initial.ts'
+import { applyOp } from './operations.ts'
+import { dockPaneIds, findTabPane, firstDockPaneId, getNode, getPane, getTab } from './tree.ts'
+
+/** Mints ids for the operations a planner produces: the one place a string becomes an id. */
+export interface Mint {
+  (prefix: 'tab'): TabId
+  (prefix: 'pane' | 'float'): PaneId
+  (prefix: 'split'): SplitId
+}
+
+/** Distance each newly floated panel steps down and right from the last. */
+const FLOAT_CASCADE_STEP = 24
+
+/** Where the first floating panel appears, in viewport pixels. */
+const FLOAT_ORIGIN = { x: 160, y: 120 } as const
+
+/** No operations: the intent is a no-op against this state. */
+const NOTHING: readonly LayoutOp[] = []
+
+/** Where a new tab should go and what it should say. */
+export interface OpenContentInput {
+  /** Consistency id: with `kind`, the identity opening twice focuses instead of adding to. */
+  readonly contentId: string
+  readonly title: string
+  readonly kind: string
+  /** Target pane; defaults to the active docked pane. */
+  readonly paneId?: PaneId
+  /** Strip slot in the target pane; defaults to its end. */
+  readonly index?: number
+  /**
+   * Whether a tab already showing this (kind, contentId) is focused instead of
+   * a second one being opened. Defaults to `true`.
+   */
+  readonly revealIfOpened?: boolean
+}
+
+/** An intent that both acts and names the tab it settled on. */
+export interface PlannedTab {
+  readonly ops: readonly LayoutOp[]
+  /** The tab the intent focused or created. */
+  readonly tabId: TabId
+}
+
+/**
+ * First tab in one pane carrying `contentId`, in strip order.
+ * @param state - current layout.
+ * @param paneId - the pane to search, docked or floating.
+ * @param contentId - the content identity.
+ * @param kind - restrict to tabs of this kind; omit to match any kind.
+ * @returns the tab, or `undefined` when that pane shows no such content.
+ */
+export function findPaneContentTab(state: LayoutState, paneId: PaneId, contentId: string, kind?: string): TabId | undefined {
+  for (const tabId of getPane(state, paneId).tabs) {
+    const tab = state.tabs[tabId]
+    if (tab?.contentId === contentId && (kind === undefined || tab.kind === kind)) return tabId
+  }
+  return undefined
+}
+
+/**
+ * First tab carrying `contentId`, searched docked panes first, in visual order.
+ * @param state - current layout.
+ * @param contentId - the content identity.
+ * @param kind - restrict to tabs of this kind; omit to match any kind.
+ * @returns the tab, or `undefined` when nothing shows the content.
+ */
+export function findContentTab(state: LayoutState, contentId: string, kind?: string): TabId | undefined {
+  for (const paneId of [...dockPaneIds(state), ...state.floats]) {
+    const found = findPaneContentTab(state, paneId, contentId, kind)
+    if (found !== undefined) return found
+  }
+  return undefined
+}
+
+/**
+ * The pane a new tab lands in.
+ * @param state - current layout.
+ * @returns the active pane when docked, else the first docked pane.
+ */
+export function activeDockPaneId(state: LayoutState): PaneId {
+  const active = getPane(state, state.activePaneId)
+  return active.host === 'dock' ? active.id : firstDockPaneId(state)
+}
+
+/** Send a tab into a docked pane, choosing the operation its current host needs. */
+function tabInto(source: PaneNode, tabId: TabId, toPaneId: PaneId, index: number): LayoutOp {
+  return source.host === 'float'
+    ? { type: 'unfloat', paneId: source.id, toPaneId, index }
+    : { type: 'moveTab', tabId, toPaneId, index }
+}
+
+/**
+ * Expand or collapse the docked area.
+ * @param state - current layout.
+ * @param expanded - whether the docked area is shown.
+ * @returns the operation, or none when the value is already current.
+ */
+export function planSetExpanded(state: LayoutState, expanded: boolean): readonly LayoutOp[] {
+  return state.expanded === expanded ? NOTHING : [{ type: 'setExpanded', expanded }]
+}
+
+/**
+ * Switch the presentation.
+ * @param state - current layout.
+ * @param mode - the presentation to record.
+ * @returns the operation, or none when the value is already current.
+ */
+export function planSetMode(state: LayoutState, mode: DockMode): readonly LayoutOp[] {
+  return state.mode === mode ? NOTHING : [{ type: 'setMode', mode }]
+}
+
+/**
+ * Split a pane to its right and seed the new pane.
+ * @param state - current layout.
+ * @param mint - id source for the pane, split, and seeded tab.
+ * @param paneId - pane to split; defaults to the active docked pane.
+ * @param makePaneTab - builds the seeded tab; omit to leave the new pane empty.
+ * @returns the operations, or none when the pane budget is spent.
+ */
+export function planSplitPane(
+  state: LayoutState,
+  mint: Mint,
+  paneId?: PaneId,
+  makePaneTab?: TabFactory,
+): readonly LayoutOp[] {
+  if (!canSplit(state)) return NOTHING
+  const target = paneId ?? activeDockPaneId(state)
+  if (getPane(state, target).host !== 'dock') return NOTHING
+  const newPaneId = mint('pane')
+  const ops: LayoutOp[] = [{
+    type: 'split',
+    paneId: target,
+    axis: 'row',
+    direction: 'after',
+    newPaneId,
+    newSplitId: mint('split'),
+  }]
+  // Seeding is its own operation inside the same intent: the record keeps the
+  // two apart, one step back undoes both — and the factory decides whether
+  // there is anything to seat.
+  const seed = makePaneTab?.(mint('tab'))
+  if (seed !== undefined) ops.push({ type: 'openTab', paneId: newPaneId, tab: seed, index: 0 })
+  return ops
+}
+
+/**
+ * Seat the embedder's seeded tab at the end of a docked pane's strip.
+ * @param state - current layout.
+ * @param mint - id source for the new tab.
+ * @param paneId - the pane whose strip asked; must be docked.
+ * @param makeTab - builds the seeded tab; omit to plan nothing.
+ * @returns the operations, or none when there is nothing to seat.
+ */
+export function planAddTab(
+  state: LayoutState,
+  mint: Mint,
+  paneId: PaneId,
+  makeTab?: TabFactory,
+): readonly LayoutOp[] {
+  if (makeTab === undefined) return NOTHING
+  const pane = getPane(state, paneId)
+  if (pane.host !== 'dock') return NOTHING
+  return [{ type: 'openTab', paneId, tab: makeTab(mint('tab')), index: pane.tabs.length }]
+}
+
+/**
+ * Open content, or focus the tab already showing it.
+ * @param state - current layout.
+ * @param mint - id source for a newly opened tab.
+ * @param input - identity, copy, and optional placement.
+ * @returns the operations plus the tab they settle on.
+ */
+export function planOpenContent(state: LayoutState, mint: Mint, input: OpenContentInput): PlannedTab {
+  const existing = input.revealIfOpened === false
+    ? undefined
+    : findContentTab(state, input.contentId, input.kind)
+  if (existing !== undefined) return { ops: [{ type: 'focusTab', tabId: existing }], tabId: existing }
+  const paneId = input.paneId ?? activeDockPaneId(state)
+  const tab: TabRecord = {
+    id: mint('tab'),
+    kind: input.kind,
+    contentId: input.contentId,
+    title: input.title,
+  }
+  return {
+    ops: [{ type: 'openTab', paneId, tab, index: input.index ?? getPane(state, paneId).tabs.length }],
+    tabId: tab.id,
+  }
+}
+
+/**
+ * Open a second, independent tab on the same content, beside the original.
+ * @param state - current layout.
+ * @param mint - id source for the copy.
+ * @param tabId - tab to copy.
+ * @returns the operations plus the new tab's id.
+ */
+export function planDuplicateTab(state: LayoutState, mint: Mint, tabId: TabId): PlannedTab {
+  const source = getTab(state, tabId)
+  const pane = findTabPane(state, tabId)
+  const host = pane.host === 'dock' ? pane.id : activeDockPaneId(state)
+  const index = pane.host === 'dock' ? pane.tabs.indexOf(tabId) + 1 : getPane(state, host).tabs.length
+  const tab: TabRecord = { ...source, id: mint('tab') }
+  return { ops: [{ type: 'openTab', paneId: host, tab, index }], tabId: tab.id }
+}
+
+/**
+ * Put a tab at an explicit strip slot: a reorder inside its own pane, otherwise a
+ * move, or a return when it currently floats.
+ * @param state - current layout.
+ * @param tabId - the tab being placed.
+ * @param toPaneId - destination docked pane.
+ * @param index - caret slot in the destination strip, counted over the chips as
+ *   drawn — the dragged chip included when the destination is its own pane, so
+ *   the slot just before or just after it is where it already sits.
+ * @returns the operations, or none when the placement changes nothing.
+ */
+export function planPlaceTab(
+  state: LayoutState,
+  tabId: TabId,
+  toPaneId: PaneId,
+  index: number,
+): readonly LayoutOp[] {
+  const source = findTabPane(state, tabId)
+  if (getPane(state, toPaneId).host !== 'dock') return NOTHING
+  if (source.id === toPaneId) {
+    // `reorderTab` indexes the strip without the tab: a caret past the chip
+    // counts one slot the chip itself vacates.
+    const from = source.tabs.indexOf(tabId)
+    const to = index > from ? index - 1 : index
+    return to === from ? NOTHING : [{ type: 'reorderTab', tabId, index: to }]
+  }
+  return [tabInto(source, tabId, toPaneId, index)]
+}
+
+/**
+ * Resolve a tab release on a pane body: the centre moves the tab in, an edge
+ * splits the pane and seats the tab in the new half. A pane's only tab released
+ * on that pane changes nothing in either zone: the split would empty the pane
+ * and seat the tab beside where it already was.
+ * @param state - current layout.
+ * @param mint - id source for a pane an edge release creates.
+ * @param tabId - the dragged tab.
+ * @param targetPaneId - pane under the pointer.
+ * @param zone - dock region the pointer released in.
+ * @returns the operations, or none when the release changes nothing.
+ */
+export function planDropTab(
+  state: LayoutState,
+  mint: Mint,
+  tabId: TabId,
+  targetPaneId: PaneId,
+  zone: DockZone,
+): readonly LayoutOp[] {
+  const source = findTabPane(state, tabId)
+  const target = getPane(state, targetPaneId)
+  if (target.host !== 'dock') return NOTHING
+  const split = zoneSplit(zone)
+
+  if (split === undefined) {
+    if (source.id === targetPaneId) return NOTHING
+    return [tabInto(source, tabId, targetPaneId, target.tabs.length)]
+  }
+
+  if (source.id === targetPaneId && source.tabs.length === 1) return NOTHING
+  if (!canSplit(state)) return NOTHING
+  const newPaneId = mint('pane')
+  return [
+    {
+      type: 'split',
+      paneId: targetPaneId,
+      axis: split.axis,
+      direction: split.direction,
+      newPaneId,
+      newSplitId: mint('split'),
+    },
+    tabInto(source, tabId, newPaneId, 0),
+  ]
+}
+
+/**
+ * Take a tab out into a floating panel.
+ * @param state - current layout.
+ * @param mint - id source for the floating pane.
+ * @param tabId - tab to float.
+ * @param rect - explicit rectangle; defaults to a cascade from the last panel.
+ * @returns the operations plus the floating pane's id.
+ */
+export function planFloatTab(
+  state: LayoutState,
+  mint: Mint,
+  tabId: TabId,
+  rect?: FloatRect,
+): { readonly ops: readonly LayoutOp[]; readonly paneId: PaneId } {
+  const step = state.floats.length * FLOAT_CASCADE_STEP
+  const newPaneId = mint('float')
+  return {
+    ops: [{
+      type: 'float',
+      tabId,
+      newPaneId,
+      rect: rect ?? {
+        x: FLOAT_ORIGIN.x + step,
+        y: FLOAT_ORIGIN.y + step,
+        width: FLOAT_DEFAULT_SIZE.width,
+        height: FLOAT_DEFAULT_SIZE.height,
+      },
+    }],
+    paneId: newPaneId,
+  }
+}
+
+/**
+ * Send a floating panel's tab back into the docked tree.
+ * @param state - current layout.
+ * @param paneId - the floating pane.
+ * @param toPaneId - destination docked pane; defaults to the active one.
+ * @returns the operations.
+ */
+export function planUnfloatPane(
+  state: LayoutState,
+  paneId: PaneId,
+  toPaneId?: PaneId,
+): readonly LayoutOp[] {
+  const destination = toPaneId ?? activeDockPaneId(state)
+  return [{ type: 'unfloat', paneId, toPaneId: destination, index: getPane(state, destination).tabs.length }]
+}
+
+/**
+ * Record the net sizes of a divider drag, clamped to the pane minimum.
+ * @param splitId - the split whose divider moved.
+ * @param sizes - the fractions the drag reached.
+ * @param minimum - smallest pane share; defaults to the kit's fraction.
+ * @returns the resize operation.
+ */
+export function planResizeSplit(splitId: SplitId, sizes: readonly number[], minimum?: number): readonly LayoutOp[] {
+  return [{ type: 'resize', splitId, sizes: clampSizes(sizes, minimum) }]
+}
+
+/**
+ * Keep the docked area populated after an intent: drop every docked pane the
+ * intent left empty, and when the surviving root pane is itself empty, seed it.
+ *
+ * A pane empties when its last tab is closed, moved out, or floated; each such
+ * pane is merged away, innermost first, until none remains. The root pane cannot
+ * be merged, so it is reseeded instead — with the factory's tab, or left empty
+ * when the embedder supplies none. The returned operations continue the intent
+ * they follow, so a caller records both as one entry.
+ * @param state - the layout after the intent's own operations.
+ * @param mint - id source for the reseeded tab.
+ * @param makeTab - builds the tab an emptied root pane is reseeded with.
+ * @returns the follow-up operations, or none when every docked pane holds a tab.
+ */
+export function planSettle(state: LayoutState, mint: Mint, makeTab?: TabFactory): readonly LayoutOp[] {
+  const ops: LayoutOp[] = []
+  let current = state
+  for (;;) {
+    const emptied = dockPaneIds(current)
+      .find(id => id !== current.rootId && getPane(current, id).tabs.length === 0)
+    if (emptied === undefined) break
+    const merge: LayoutOp = { type: 'merge', paneId: emptied }
+    ops.push(merge)
+    current = applyOp(current, merge).state
+  }
+  const root = getNode(current, current.rootId)
+  if (root.kind === 'pane' && root.tabs.length === 0 && makeTab !== undefined) {
+    ops.push({ type: 'openTab', paneId: root.id, tab: makeTab(mint('tab')), index: 0 })
+  }
+  return ops
+}
diff --git a/packages/client/ui-dockkit/src/engine/sequence.ts b/packages/client/ui-dockkit/src/engine/sequence.ts
new file mode 100644
index 0000000000..7e9569c051
--- /dev/null
+++ b/packages/client/ui-dockkit/src/engine/sequence.ts
@@ -0,0 +1,243 @@
+/**
+ * Linear operation history over `applyOp`. Recording is total — every operation
+ * lands in the sequence, focus moves included — and grouped by intent: the
+ * operations one gesture or command produced form one entry, so stepping lands
+ * on a point the user actually stopped at. Stepping is coarser still across
+ * focus: a run of consecutive focus-only entries undoes and redoes as one step.
+ *
+ * Redoing re-applies the recorded operations; undoing applies the inverses that
+ * were captured when they ran, so both directions stay exact. A new entry after
+ * an undo drops the redo branch.
+ *
+ * Two shapes, one implementation. `record`/`stepBack`/`stepForward` are pure
+ * functions over a plain `History`, which is what an embedder holding its layout
+ * in an external store needs; `Sequencer` is a thin mutable wrapper over exactly
+ * those functions, for an embedder that would rather hold the state here.
+ */
+import type { FocusOpType, LayoutOp, LayoutState } from '../contract/types.ts'
+import { applyOp } from './operations.ts'
+
+/** One recorded intent: its operations, and the operations that undo them all. */
+export interface HistoryEntry {
+  readonly ops: readonly LayoutOp[]
+  /** Already ordered for application: the last operation's inverse comes first. */
+  readonly inverse: readonly LayoutOp[]
+}
+
+/** A recorded sequence and how much of it is applied. Plain data, safe to store. */
+export interface History {
+  readonly entries: readonly HistoryEntry[]
+  /** How many entries are applied; entries beyond it are the redo branch. */
+  readonly cursor: number
+}
+
+/** A sequence that has recorded nothing. */
+export const EMPTY_HISTORY: History = { entries: [], cursor: 0 }
+
+/** A history and the state it produced, returned together so neither can drift. */
+export interface HistoryStep {
+  readonly history: History
+  readonly state: LayoutState
+}
+
+/** Operation kinds that only move focus. */
+const FOCUS_OP_TYPES: ReadonlySet<string> = new Set<FocusOpType>(['focusTab', 'focusPane', 'restoreFocus'])
+
+/**
+ * Whether an operation only moves focus, and so merges into its neighbours' undo step.
+ * @param op - the operation.
+ * @returns whether its type is a `FocusOpType`.
+ */
+export function isFocusOp(op: LayoutOp): boolean {
+  return FOCUS_OP_TYPES.has(op.type)
+}
+
+/** Whether the entry at `index` only moves focus. */
+function isFocusEntry(history: History, index: number): boolean {
+  const entry = history.entries[index]
+  return entry !== undefined && entry.ops.every(isFocusOp)
+}
+
+/**
+ * Whether a step back exists.
+ * @param history - the sequence so far.
+ * @returns whether any entry is applied.
+ */
+export function canStepBack(history: History): boolean {
+  return history.cursor > 0
+}
+
+/**
+ * Whether a step forward exists.
+ * @param history - the sequence so far.
+ * @returns whether a redo branch remains.
+ */
+export function canStepForward(history: History): boolean {
+  return history.cursor < history.entries.length
+}
+
+/**
+ * The operations a sequence has recorded, redo branch included.
+ * @param history - the sequence so far.
+ * @returns every entry's operations, in recorded order.
+ */
+export function recordedOps(history: History): readonly LayoutOp[] {
+  return history.entries.flatMap(entry => entry.ops)
+}
+
+/**
+ * Apply one intent's operations and record them as one entry, dropping any redo
+ * branch first. An intent with no operations records nothing.
+ * @param history - the sequence so far.
+ * @param state - the state the operations apply to.
+ * @param ops - the intent's operations, in application order.
+ * @returns the extended history and the state after the operations.
+ * @throws when an operation is invalid against the state it reaches; nothing is
+ *   recorded.
+ */
+export function record(history: History, state: LayoutState, ops: readonly LayoutOp[]): HistoryStep {
+  if (ops.length === 0) return { history, state }
+  let next = state
+  const inverse: LayoutOp[] = []
+  for (const op of ops) {
+    const result = applyOp(next, op)
+    next = result.state
+    // Undo runs the inverses in reverse operation order.
+    inverse.unshift(...result.inverse)
+  }
+  const kept = history.cursor === history.entries.length
+    ? history.entries
+    : history.entries.slice(0, history.cursor)
+  return {
+    history: { entries: [...kept, { ops, inverse }], cursor: history.cursor + 1 },
+    state: next,
+  }
+}
+
+/**
+ * Step back one intent, or one whole run of consecutive focus-only intents.
+ * @param history - the sequence so far.
+ * @param state - the current state.
+ * @returns the stepped-back pair, or `undefined` when nothing can be undone.
+ */
+export function stepBack(history: History, state: LayoutState): HistoryStep | undefined {
+  if (!canStepBack(history)) return undefined
+  let count = 1
+  if (isFocusEntry(history, history.cursor - 1)) {
+    while (isFocusEntry(history, history.cursor - 1 - count)) count += 1
+  }
+  let next = state
+  for (const entry of history.entries.slice(history.cursor - count, history.cursor).reverse()) {
+    for (const op of entry.inverse) next = applyOp(next, op).state
+  }
+  return { history: { entries: history.entries, cursor: history.cursor - count }, state: next }
+}
+
+/**
+ * Step forward over the intents the matching step back undid.
+ * @param history - the sequence so far.
+ * @param state - the current state.
+ * @returns the stepped-forward pair, or `undefined` when nothing can be redone.
+ */
+export function stepForward(history: History, state: LayoutState): HistoryStep | undefined {
+  if (!canStepForward(history)) return undefined
+  let count = 1
+  if (isFocusEntry(history, history.cursor)) {
+    while (isFocusEntry(history, history.cursor + count)) count += 1
+  }
+  let next = state
+  for (const entry of history.entries.slice(history.cursor, history.cursor + count)) {
+    for (const op of entry.ops) next = applyOp(next, op).state
+  }
+  return { history: { entries: history.entries, cursor: history.cursor + count }, state: next }
+}
+
+/** Layout state plus its history cursor, held here instead of by the embedder. */
+export class Sequencer {
+  private current: LayoutState
+  private recorded: History = EMPTY_HISTORY
+
+  /** @param initial - state the sequence replays from; never mutated. */
+  constructor(initial: LayoutState) {
+    this.current = initial
+  }
+
+  /** Current state. */
+  get state(): LayoutState {
+    return this.current
+  }
+
+  /** The recorded sequence as plain data. */
+  get history(): History {
+    return this.recorded
+  }
+
+  /** The whole recorded sequence, including a redo branch that is not applied. */
+  get ops(): readonly LayoutOp[] {
+    return recordedOps(this.recorded)
+  }
+
+  /** How many recorded operations are currently applied. */
+  get cursor(): number {
+    return this.recorded.cursor
+  }
+
+  /** Whether a step back exists. */
+  get canUndo(): boolean {
+    return canStepBack(this.recorded)
+  }
+
+  /** Whether a step forward exists. */
+  get canRedo(): boolean {
+    return canStepForward(this.recorded)
+  }
+
+  /**
+   * Apply and record one operation as its own entry, dropping any redo branch first.
+   * @param op - the operation to record.
+   * @returns the state after it.
+   * @throws when the operation is invalid against the current state; the
+   *   sequence is left untouched.
+   */
+  dispatch(op: LayoutOp): LayoutState {
+    return this.dispatchAll([op])
+  }
+
+  /**
+   * Apply and record one intent's operations as one entry, dropping any redo
+   * branch first.
+   * @param ops - the intent's operations; none records nothing.
+   * @returns the state after them.
+   * @throws when an operation is invalid; the sequence is left untouched.
+   */
+  dispatchAll(ops: readonly LayoutOp[]): LayoutState {
+    const stepped = record(this.recorded, this.current, ops)
+    this.recorded = stepped.history
+    this.current = stepped.state
+    return this.current
+  }
+
+  /**
+   * Step back one intent, or one whole run of consecutive focus-only intents.
+   * @returns false when there is nothing to undo.
+   */
+  undo(): boolean {
+    const stepped = stepBack(this.recorded, this.current)
+    if (stepped === undefined) return false
+    this.recorded = stepped.history
+    this.current = stepped.state
+    return true
+  }
+
+  /**
+   * Step forward over the intents the matching undo stepped back.
+   * @returns false when there is nothing to redo.
+   */
+  redo(): boolean {
+    const stepped = stepForward(this.recorded, this.current)
+    if (stepped === undefined) return false
+    this.recorded = stepped.history
+    this.current = stepped.state
+    return true
+  }
+}
diff --git a/packages/client/ui-dockkit/src/engine/tree.ts b/packages/client/ui-dockkit/src/engine/tree.ts
new file mode 100644
index 0000000000..de71e580e1
--- /dev/null
+++ b/packages/client/ui-dockkit/src/engine/tree.ts
@@ -0,0 +1,323 @@
+/**
+ * Pure tree helpers over `LayoutState`. Every reader throws on a dangling id
+ * (the operation vocabulary is closed, so a miss is a caller defect), and every
+ * writer returns a new state that keeps untouched nodes at their old identity.
+ */
+import type {
+  FloatRect, LayoutNode, LayoutState, NodeId, PaneId, PaneNode, SplitNode, TabId, TabRecord,
+} from '../contract/types.ts'
+
+/**
+ * Reject an unhandled discriminant at the end of a closed switch.
+ * @param value - the discriminant the switch did not handle.
+ * @param what - the union being switched on, for the message.
+ * @returns never; it throws.
+ */
+export function assertNever(value: never, what: string): never {
+  throw new Error(`${what}: unhandled ${JSON.stringify(value)}`)
+}
+
+/**
+ * Read any node.
+ * @param state - current layout.
+ * @param id - the node.
+ * @returns the split or pane.
+ * @throws when `id` is not in the tree.
+ */
+export function getNode(state: LayoutState, id: NodeId): LayoutNode {
+  const node = state.nodes[id]
+  if (node === undefined) throw new Error(`layout: unknown node ${id}`)
+  return node
+}
+
+/**
+ * Read a pane.
+ * @param state - current layout.
+ * @param id - the pane.
+ * @returns the pane node.
+ * @throws when `id` is missing or names a split.
+ */
+export function getPane(state: LayoutState, id: NodeId): PaneNode {
+  const node = getNode(state, id)
+  if (node.kind !== 'pane') throw new Error(`layout: ${id} is not a pane`)
+  return node
+}
+
+/**
+ * Read a split.
+ * @param state - current layout.
+ * @param id - the split.
+ * @returns the split node.
+ * @throws when `id` is missing or names a pane.
+ */
+export function getSplit(state: LayoutState, id: NodeId): SplitNode {
+  const node = getNode(state, id)
+  if (node.kind !== 'split') throw new Error(`layout: ${id} is not a split`)
+  return node
+}
+
+/**
+ * Read a tab record.
+ * @param state - current layout.
+ * @param id - the tab.
+ * @returns the record.
+ * @throws when `id` is not open.
+ */
+export function getTab(state: LayoutState, id: TabId): TabRecord {
+  const tab = state.tabs[id]
+  if (tab === undefined) throw new Error(`layout: unknown tab ${id}`)
+  return tab
+}
+
+/**
+ * A floating pane's rectangle.
+ * @param pane - the pane.
+ * @returns its viewport rectangle.
+ * @throws when `pane` is docked.
+ */
+export function floatRect(pane: PaneNode): FloatRect {
+  if (pane.host !== 'float' || pane.rect === undefined) throw new Error(`layout: ${pane.id} is not floating`)
+  return pane.rect
+}
+
+/**
+ * A floating pane's position in the z order.
+ * @param state - current layout.
+ * @param id - the floating pane.
+ * @returns its index in `floats`, bottom first.
+ * @throws when `id` is not listed in `floats`.
+ */
+export function floatIndex(state: LayoutState, id: PaneId): number {
+  const index = state.floats.indexOf(id)
+  if (index < 0) throw new Error(`layout: floating pane ${id} is not in the z order`)
+  return index
+}
+
+/**
+ * The one tab a pane holds.
+ * @param pane - the pane.
+ * @returns its tab's id.
+ * @throws when `pane` holds any other number of tabs.
+ */
+export function onlyTabId(pane: PaneNode): TabId {
+  const tabId = pane.tabs[0]
+  if (tabId === undefined || pane.tabs.length !== 1) throw new Error(`layout: ${pane.id} does not hold exactly one tab`)
+  return tabId
+}
+
+/**
+ * The split holding a node.
+ * @param state - current layout.
+ * @param id - the node.
+ * @returns its parent split, or `undefined` for the docked root and floating panes.
+ */
+export function findParent(state: LayoutState, id: NodeId): SplitNode | undefined {
+  for (const node of Object.values(state.nodes)) {
+    if (node.kind === 'split' && node.children.includes(id)) return node
+  }
+  return undefined
+}
+
+/**
+ * The pane holding a tab.
+ * @param state - current layout.
+ * @param tabId - the tab.
+ * @returns the pane whose strip lists it.
+ * @throws when no pane lists it.
+ */
+export function findTabPane(state: LayoutState, tabId: TabId): PaneNode {
+  for (const node of Object.values(state.nodes)) {
+    if (node.kind === 'pane' && node.tabs.includes(tabId)) return node
+  }
+  throw new Error(`layout: tab ${tabId} has no pane`)
+}
+
+/**
+ * Docked pane ids in visual order (depth-first through the split tree).
+ * @param state - current layout.
+ * @returns every docked pane's id; floating panes are absent.
+ */
+export function dockPaneIds(state: LayoutState): PaneId[] {
+  const out: PaneId[] = []
+  const walk = (id: NodeId): void => {
+    const node = getNode(state, id)
+    if (node.kind === 'pane') {
+      out.push(node.id)
+      return
+    }
+    for (const child of node.children) walk(child)
+  }
+  walk(state.rootId)
+  return out
+}
+
+/**
+ * Scale `sizes` so they sum to 1. Input that already sums to 1 is copied
+ * unchanged, so restoring recorded sizes never drifts.
+ * @param sizes - fractions or any positive weights.
+ * @returns the fractions, summing to 1.
+ * @throws when the input cannot be normalized.
+ */
+export function normalizeSizes(sizes: readonly number[]): number[] {
+  const total = sizes.reduce((sum, size) => sum + size, 0)
+  if (!(total > 0)) throw new Error('layout: sizes must sum above zero')
+  if (Math.abs(total - 1) < 1e-12) return [...sizes]
+  return sizes.map(size => size / total)
+}
+
+/**
+ * `Object.entries` keeping the record's own key type: the keys were written from
+ * ids, so reading them back as ids is exact.
+ * @param record - an id-keyed record.
+ * @returns its entries with typed keys.
+ */
+export function entriesOf<K extends string, V>(record: Readonly<Record<K, V>>): readonly (readonly [K, V])[] {
+  return Object.entries(record) as [K, V][]
+}
+
+/**
+ * `Object.keys` keeping the record's own key type; see {@link entriesOf}.
+ * @param record - an id-keyed record.
+ * @returns its keys, typed.
+ */
+export function keysOf<K extends string>(record: Readonly<Record<K, unknown>>): readonly K[] {
+  return Object.keys(record) as K[]
+}
+
+/**
+ * Replace or delete nodes.
+ * @param state - current layout.
+ * @param updates - nodes by id; a `null` update deletes that id.
+ * @returns the layout with those nodes replaced; untouched nodes keep their identity.
+ */
+export function withNodes(
+  state: LayoutState,
+  updates: Readonly<Record<NodeId, LayoutNode | null>>,
+): LayoutState {
+  const nodes: Record<NodeId, LayoutNode> = {}
+  for (const [id, node] of entriesOf(state.nodes)) {
+    if (!(id in updates)) nodes[id] = node
+  }
+  for (const [id, node] of entriesOf(updates)) {
+    if (node !== null) nodes[id] = node
+  }
+  return { ...state, nodes }
+}
+
+/**
+ * Replace or delete tab records.
+ * @param state - current layout.
+ * @param updates - records by id; a `null` update deletes that id.
+ * @returns the layout with those records replaced; untouched records keep their identity.
+ */
+export function withTabs(
+  state: LayoutState,
+  updates: Readonly<Record<TabId, TabRecord | null>>,
+): LayoutState {
+  const tabs: Record<TabId, TabRecord> = {}
+  for (const [id, tab] of entriesOf(state.tabs)) {
+    if (!(id in updates)) tabs[id] = tab
+  }
+  for (const [id, tab] of entriesOf(updates)) {
+    if (tab !== null) tabs[id] = tab
+  }
+  return { ...state, tabs }
+}
+
+/**
+ * Insert a value into a list.
+ * @param items - the list.
+ * @param index - the slot, clamped to the list's bounds.
+ * @param value - what to insert.
+ * @returns a new list with the value at the slot.
+ */
+export function insertAt<T>(items: readonly T[], index: number, value: T): T[] {
+  const at = Math.max(0, Math.min(index, items.length))
+  return [...items.slice(0, at), value, ...items.slice(at)]
+}
+
+/**
+ * Remove one entry from a list.
+ * @param items - the list.
+ * @param index - the entry to drop.
+ * @returns a new list without it.
+ */
+export function removeAt<T>(items: readonly T[], index: number): T[] {
+  return [...items.slice(0, index), ...items.slice(index + 1)]
+}
+
+/**
+ * Which tab a pane focuses after one leaves it.
+ * @param tabs - the strip before the removal.
+ * @param removedIndex - the leaving tab's slot.
+ * @returns the previous neighbour when one exists, otherwise the next, otherwise `undefined`.
+ */
+export function neighbourTabId(tabs: readonly TabId[], removedIndex: number): TabId | undefined {
+  const remaining = removeAt(tabs, removedIndex)
+  if (remaining.length === 0) return undefined
+  return remaining[Math.max(0, removedIndex - 1)]
+}
+
+/**
+ * Copy a pane with a new tab list.
+ * @param pane - the pane.
+ * @param tabs - its new strip.
+ * @param activeTabId - the active tab, which the caller keeps consistent with `tabs`.
+ * @returns the copied pane.
+ */
+export function paneWithTabs(pane: PaneNode, tabs: readonly TabId[], activeTabId: TabId | undefined): PaneNode {
+  return { ...pane, tabs, activeTabId }
+}
+
+/**
+ * Swap a node for another in its parent's slot, or make the replacement the docked root.
+ * @param state - current layout.
+ * @param targetId - the node to swap out.
+ * @param replacementId - the node taking its slot.
+ * @returns the layout with the slot rewritten.
+ * @throws when `targetId` is neither rooted nor parented.
+ */
+export function replaceInParent(state: LayoutState, targetId: NodeId, replacementId: NodeId): LayoutState {
+  const parent = findParent(state, targetId)
+  if (parent === undefined) {
+    if (state.rootId !== targetId) throw new Error(`layout: ${targetId} is neither rooted nor parented`)
+    return { ...state, rootId: replacementId }
+  }
+  const children = parent.children.map(child => child === targetId ? replacementId : child)
+  return withNodes(state, { [parent.id]: { ...parent, children } })
+}
+
+/** Walk from the docked root to a pane, taking the child `choose` names at every split. */
+function descend(state: LayoutState, choose: (split: SplitNode) => NodeId | undefined): PaneId {
+  let node = getNode(state, state.rootId)
+  while (node.kind === 'split') {
+    const next = choose(node)
+    /* v8 ignore next -- a split holds at least two children, so every choice names one. */
+    if (next === undefined) throw new Error(`layout: split ${node.id} has no children`)
+    node = getNode(state, next)
+  }
+  return node.id
+}
+
+/**
+ * The first docked pane in visual order: the docked root, or the first leaf
+ * under it. Focus falls back here when the focused pane is removed, and a new
+ * tab lands here when the focused pane floats.
+ * @param state - current layout.
+ * @returns the first docked pane's id.
+ */
+export function firstDockPaneId(state: LayoutState): PaneId {
+  return descend(state, split => split.children[0])
+}
+
+/**
+ * The docked pane in the top-right corner: from the root, the last child of
+ * every row split and the first child of every column split. Its tab strip is
+ * where an embedder's surface-wide controls sit, so they read as the surface's
+ * own top-right corner however the tree is divided.
+ * @param state - current layout.
+ * @returns the top-right docked pane's id.
+ */
+export function topRightPaneId(state: LayoutState): PaneId {
+  return descend(state, split => (split.axis === 'row' ? split.children.at(-1) : split.children[0]))
+}
diff --git a/packages/client/ui-dockkit/src/index.ts b/packages/client/ui-dockkit/src/index.ts
new file mode 100644
index 0000000000..f72adb9271
--- /dev/null
+++ b/packages/client/ui-dockkit/src/index.ts
@@ -0,0 +1,68 @@
+/**
+ * A docking layout kit: a split tree of tabbed panes with invertible operations,
+ * and the React components that render and drive it.
+ *
+ * Two layers, and the boundary between them is the point of the package. The
+ * engine (`applyOp`, `Sequencer`, `DockController`) is pure TypeScript with no
+ * React, no DOM, and no host concepts; replaying a recorded sequence over the
+ * same initial state reproduces the same tree, because every operation carries
+ * the ids it creates. The components render a layout snapshot and report settled
+ * intents — one per gesture, never a drag frame — so the embedder's sequence
+ * stays the single source of truth.
+ *
+ * Nothing host-specific lives here: rendered strings arrive as `DockLabels`, tab
+ * bodies as a `TabRenderer`, and a tab's `kind` is an opaque string this kit
+ * never interprets.
+ *
+ * @module
+ */
+
+// Model and operations.
+export type {
+  ApplyResult, DockMode, DockZone, FloatRect, LayoutNode, LayoutOp, LayoutState, NodeId,
+  PaneAttachment, PaneHost, PaneId, PaneNode, SplitAxis, SplitDirection, SplitId,
+  SplitNode, TabId, TabRecord,
+} from './contract/types.ts'
+export { applyOp, replay } from './engine/operations.ts'
+export {
+  canStepBack, canStepForward, EMPTY_HISTORY, isFocusOp, record, recordedOps,
+  Sequencer, stepBack, stepForward,
+} from './engine/sequence.ts'
+export type { History, HistoryEntry, HistoryStep } from './engine/sequence.ts'
+export {
+  dockPaneIds, findParent, findTabPane, getNode, getPane, getSplit, getTab, topRightPaneId,
+} from './engine/tree.ts'
+
+// Interaction limits and geometry.
+export {
+  canSplit, clampSizes, DOCK_EDGE_FRACTION, DOCK_ZONES, dockPaneCount,
+  FLOAT_DEFAULT_SIZE, FLOAT_MIN_SIZE, MAX_DOCK_PANES, MIN_PANE_FRACTION, zoneAt, zoneSplit,
+} from './engine/constraints.ts'
+export {
+  containsPoint, dividerSizes, DRAG_THRESHOLD, floatRectAt, halvesFit, insertionIndex,
+  movedRect, passedThreshold, resizedRect, SPLIT_MINIMUMS, zoneInRect,
+} from './engine/geometry.ts'
+export type { DropTarget, HalvesFit, PaneMeasure, Rect, Size, SplitMinimums } from './engine/geometry.ts'
+
+// Intent planning: the shared decisions, as pure functions.
+export {
+  activeDockPaneId, findContentTab, findPaneContentTab, planAddTab, planDropTab, planDuplicateTab, planFloatTab,
+  planOpenContent, planPlaceTab, planResizeSplit, planSetExpanded, planSetMode,
+  planSettle, planSplitPane, planUnfloatPane,
+} from './engine/planner.ts'
+export type { Mint, OpenContentInput, PlannedTab } from './engine/planner.ts'
+
+// The intent layer's stateful embedding, and its seeds.
+export { DockController } from './engine/controller.ts'
+export type { DockControllerOptions, DockSnapshot } from './engine/controller.ts'
+export { createIdMinter, createInitialState } from './engine/initial.ts'
+export type { IdMinter, TabFactory } from './engine/initial.ts'
+
+// Outward contracts.
+export type { DockIntents, DockLabels, TabMenuExtras, TabRenderer } from './contract/adapter.ts'
+
+// React surface.
+export { DockSurface } from './components/DockSurface.tsx'
+export type { DockSurfaceProps } from './components/DockSurface.tsx'
+export { FloatLayer } from './components/FloatLayer.tsx'
+export type { FloatLayerProps } from './components/FloatLayer.tsx'
diff --git a/packages/client/ui-dockkit/tests/apply.client.spec.ts b/packages/client/ui-dockkit/tests/apply.client.spec.ts
new file mode 100644
index 0000000000..f385cfea8e
--- /dev/null
+++ b/packages/client/ui-dockkit/tests/apply.client.spec.ts
@@ -0,0 +1,629 @@
+/**
+ * Model and operation-engine behavior: what each operation does to the tree, and
+ * that applying its inverse returns the exact state it started from.
+ */
+import { describe, expect, it } from 'vitest'
+import { applyOp, replay } from '../src/engine/operations.ts'
+import { createIdMinter, createInitialState } from '../src/engine/initial.ts'
+import { asPane, asSplit, asTab, childAt, fileTab, firstTab, seedTab } from './fixtures.client.ts'
+import {
+  assertNever, dockPaneIds, findParent, findTabPane, firstDockPaneId, floatIndex, floatRect, getNode, getPane, getSplit,
+  getTab, normalizeSizes, onlyTabId, replaceInParent, topRightPaneId,
+} from '../src/engine/tree.ts'
+import type { IdMinter } from '../src/engine/initial.ts'
+import type { LayoutOp, LayoutState, PaneId, PaneNode, TabId } from '../src/contract/types.ts'
+
+interface Fixture {
+  readonly state: LayoutState
+  readonly minter: IdMinter
+  readonly paneId: PaneId
+  readonly guideTabId: TabId
+}
+
+function fixture(): Fixture {
+  const minter = createIdMinter()
+  const state = createInitialState(minter, seedTab)
+  const paneId = getPane(state, state.rootId).id
+  const guideTabId = getPane(state, paneId).tabs[0]
+  if (guideTabId === undefined) throw new Error('fixture: initial pane has no guide tab')
+  return { state, minter, paneId, guideTabId }
+}
+
+/** Apply `op`, then its inverse, and require the original state back. */
+function expectRoundTrip(state: LayoutState, op: LayoutOp): LayoutState {
+  const result = applyOp(state, op)
+  const back = result.inverse.reduce((current, inverse) => applyOp(current, inverse).state, result.state)
+  expect(back).toEqual(state)
+  return result.state
+}
+
+/** Split `paneId` to the right, returning the state and the new pane id. */
+function split(
+  state: LayoutState,
+  minter: IdMinter,
+  paneId: PaneId,
+  axis: 'row' | 'column' = 'row',
+  direction: 'before' | 'after' = 'after',
+): { state: LayoutState; newPaneId: PaneId } {
+  const newPaneId = minter.next('pane')
+  const op: LayoutOp = { type: 'split', paneId, axis, direction, newPaneId, newSplitId: minter.next('split') }
+  return { state: expectRoundTrip(state, op), newPaneId }
+}
+
+describe('initial state', () => {
+  it('starts collapsed with one docked pane holding an active guide tab', () => {
+    const { state, paneId, guideTabId } = fixture()
+    expect(state.expanded).toBe(false)
+    expect(dockPaneIds(state)).toEqual([paneId])
+    expect(state.floats).toEqual([])
+    expect(state.activePaneId).toBe(paneId)
+    const pane = getPane(state, paneId)
+    expect(pane.tabs).toEqual([guideTabId])
+    expect(pane.activeTabId).toBe(guideTabId)
+    expect(state.tabs[guideTabId]?.kind).toBe('seed')
+  })
+})
+
+describe('split', () => {
+  it('wraps the reference pane in a new split and adds an empty sibling', () => {
+    const { state, minter, paneId } = fixture()
+    const after = split(state, minter, paneId).state
+    const root = getSplit(after, after.rootId)
+    expect(root.axis).toBe('row')
+    expect(root.children).toHaveLength(2)
+    expect(root.children[0]).toBe(paneId)
+    expect(root.sizes).toEqual([0.5, 0.5])
+    expect(dockPaneIds(after)).toHaveLength(2)
+    const sibling = getPane(after, childAt(root, 1))
+    expect(sibling.tabs).toEqual([])
+    expect(sibling.activeTabId).toBeUndefined()
+  })
+
+  it('puts the new pane before the reference pane when asked', () => {
+    const { state, minter, paneId } = fixture()
+    const after = split(state, minter, paneId, 'row', 'before').state
+    expect(getSplit(after, after.rootId).children[1]).toBe(paneId)
+  })
+
+  it('joins an existing split of the same axis instead of nesting', () => {
+    const { state, minter, paneId } = fixture()
+    const first = split(state, minter, paneId)
+    const second = split(first.state, minter, paneId)
+    const root = getSplit(second.state, second.state.rootId)
+    expect(root.children).toHaveLength(3)
+    expect(root.sizes).toEqual([0.25, 0.25, 0.5])
+    expect(dockPaneIds(second.state)).toHaveLength(3)
+  })
+
+  it('joins an existing split before the reference pane when asked', () => {
+    const { state, minter, paneId } = fixture()
+    const first = split(state, minter, paneId)
+    const second = split(first.state, minter, paneId, 'row', 'before')
+    const root = getSplit(second.state, second.state.rootId)
+    expect(root.children).toEqual([second.newPaneId, paneId, first.newPaneId])
+    expect(root.sizes).toEqual([0.25, 0.25, 0.5])
+  })
+
+  it('nests when the parent split runs on the other axis', () => {
+    const { state, minter, paneId } = fixture()
+    const first = split(state, minter, paneId)
+    const second = split(first.state, minter, first.newPaneId, 'column')
+    const root = getSplit(second.state, second.state.rootId)
+    expect(root.axis).toBe('row')
+    expect(root.children).toHaveLength(2)
+    const nested = getSplit(second.state, childAt(root, 1))
+    expect(nested.axis).toBe('column')
+    expect(nested.children).toEqual([first.newPaneId, second.newPaneId])
+  })
+
+  it('refuses an unknown pane and a floating pane', () => {
+    const { state, minter, paneId, guideTabId } = fixture()
+    expect(() => applyOp(state, {
+      type: 'split', paneId: asPane('nope'), axis: 'row', direction: 'after', newPaneId: asPane('p'), newSplitId: asSplit('s'),
+    })).toThrow(/unknown node/)
+    const floatId = minter.next('float')
+    const floated = applyOp(state, {
+      type: 'float', tabId: guideTabId, newPaneId: floatId, rect: { x: 0, y: 0, width: 100, height: 100 },
+    }).state
+    expect(() => applyOp(floated, {
+      type: 'split', paneId: floatId, axis: 'row', direction: 'after', newPaneId: asPane('p'), newSplitId: asSplit('s'),
+    })).toThrow(/docked pane/)
+    expect(paneId).toBeDefined()
+  })
+})
+
+describe('merge', () => {
+  it('collapses a two-child split back into its surviving pane', () => {
+    const { state, minter, paneId } = fixture()
+    const after = split(state, minter, paneId)
+    const merged = expectRoundTrip(after.state, { type: 'merge', paneId: after.newPaneId })
+    expect(merged.rootId).toBe(paneId)
+    expect(dockPaneIds(merged)).toEqual([paneId])
+    expect(merged.nodes[after.newPaneId]).toBeUndefined()
+  })
+
+  it('drops one child of a wider split and renormalizes the rest', () => {
+    const { state, minter, paneId } = fixture()
+    const first = split(state, minter, paneId)
+    const second = split(first.state, minter, paneId)
+    const merged = expectRoundTrip(second.state, { type: 'merge', paneId: second.newPaneId })
+    const root = getSplit(merged, merged.rootId)
+    expect(root.children).toHaveLength(2)
+    expect(root.sizes.reduce((sum, size) => sum + size, 0)).toBeCloseTo(1)
+  })
+
+  it('refuses a non-empty pane and the docked root pane', () => {
+    const { state, minter, paneId } = fixture()
+    expect(() => applyOp(state, { type: 'merge', paneId })).toThrow(/empty pane/)
+    const after = split(state, minter, paneId)
+    expect(() => applyOp(after.state, { type: 'merge', paneId: asPane(after.newPaneId + 'x') })).toThrow(/unknown node/)
+    const emptied = applyOp(after.state, { type: 'closeTab', tabId: firstTab(getPane(after.state, paneId)) }).state
+    const collapsed = applyOp(emptied, { type: 'merge', paneId }).state
+    expect(() => applyOp(collapsed, { type: 'merge', paneId: after.newPaneId })).toThrow(/root pane/)
+  })
+
+  it('reseats focus when the merged pane held it', () => {
+    const { state, minter, paneId } = fixture()
+    const after = split(state, minter, paneId)
+    const focused = applyOp(after.state, { type: 'focusPane', paneId: after.newPaneId }).state
+    expect(focused.activePaneId).toBe(after.newPaneId)
+    const merged = expectRoundTrip(focused, { type: 'merge', paneId: after.newPaneId })
+    expect(merged.activePaneId).toBe(paneId)
+  })
+})
+
+describe('tabs', () => {
+  it('opens a tab into a pane and focuses it', () => {
+    const { state, minter, paneId, guideTabId } = fixture()
+    const tab = fileTab(minter.next('tab'), 'dsh-resource://file/session/s/a.txt', 'a.txt')
+    const after = expectRoundTrip(state, { type: 'openTab', paneId, tab, index: 0 })
+    const pane = getPane(after, paneId)
+    expect(pane.tabs).toEqual([tab.id, guideTabId])
+    expect(pane.activeTabId).toBe(tab.id)
+    expect(after.activePaneId).toBe(paneId)
+  })
+
+  it('refuses to reopen a live tab id', () => {
+    const { state, paneId, guideTabId } = fixture()
+    const clash = { id: guideTabId, kind: 'guide' as const, contentId: 'x', title: 'x' }
+    expect(() => applyOp(state, { type: 'openTab', paneId, tab: clash, index: 0 })).toThrow(/already exists/)
+  })
+
+  it('closes the active tab onto its previous neighbour', () => {
+    const { state, minter, paneId, guideTabId } = fixture()
+    const first = fileTab(minter.next('tab'), 'dsh-resource://file/session/s/a.txt', 'a.txt')
+    const second = fileTab(minter.next('tab'), 'dsh-resource://file/session/s/b.txt', 'b.txt')
+    let current = applyOp(state, { type: 'openTab', paneId, tab: first, index: 1 }).state
+    current = applyOp(current, { type: 'openTab', paneId, tab: second, index: 2 }).state
+    expect(getPane(current, paneId).tabs).toEqual([guideTabId, first.id, second.id])
+    const after = expectRoundTrip(current, { type: 'closeTab', tabId: second.id })
+    const pane = getPane(after, paneId)
+    expect(pane.tabs).toEqual([guideTabId, first.id])
+    expect(pane.activeTabId).toBe(first.id)
+    expect(after.tabs[second.id]).toBeUndefined()
+  })
+
+  it('closes a tab that is not the active one without moving focus', () => {
+    const { state, minter, paneId, guideTabId } = fixture()
+    const tab = fileTab(minter.next('tab'), 'dsh-resource://file/session/s/a.txt', 'a.txt')
+    const opened = applyOp(state, { type: 'openTab', paneId, tab, index: 1 }).state
+    const after = expectRoundTrip(opened, { type: 'closeTab', tabId: guideTabId })
+    expect(getPane(after, paneId).tabs).toEqual([tab.id])
+    expect(getPane(after, paneId).activeTabId).toBe(tab.id)
+  })
+
+  it('leaves an empty pane with no active tab', () => {
+    const { state, paneId, guideTabId } = fixture()
+    const after = expectRoundTrip(state, { type: 'closeTab', tabId: guideTabId })
+    const pane = getPane(after, paneId)
+    expect(pane.tabs).toEqual([])
+    expect(pane.activeTabId).toBeUndefined()
+  })
+
+  it('moves a tab across panes and focuses the destination', () => {
+    const { state, minter, paneId, guideTabId } = fixture()
+    const after = split(state, minter, paneId)
+    const moved = expectRoundTrip(after.state, { type: 'moveTab', tabId: guideTabId, toPaneId: after.newPaneId, index: 0 })
+    expect(getPane(moved, paneId).tabs).toEqual([])
+    expect(getPane(moved, after.newPaneId).tabs).toEqual([guideTabId])
+    expect(moved.activePaneId).toBe(after.newPaneId)
+  })
+
+  it('moves a tab that is not the active one, leaving the source focus alone', () => {
+    const { state, minter, paneId, guideTabId } = fixture()
+    const tab = fileTab(minter.next('tab'), 'dsh-resource://file/session/s/a.txt', 'a.txt')
+    const opened = applyOp(state, { type: 'openTab', paneId, tab, index: 1 }).state
+    const after = split(opened, minter, paneId)
+    const moved = expectRoundTrip(after.state, { type: 'moveTab', tabId: guideTabId, toPaneId: after.newPaneId, index: 0 })
+    expect(getPane(moved, paneId).tabs).toEqual([tab.id])
+    expect(getPane(moved, paneId).activeTabId).toBe(tab.id)
+    expect(getPane(moved, after.newPaneId).activeTabId).toBe(guideTabId)
+  })
+
+  it('refuses a cross-pane move onto the tab own pane', () => {
+    const { state, paneId, guideTabId } = fixture()
+    expect(() => applyOp(state, { type: 'moveTab', tabId: guideTabId, toPaneId: paneId, index: 0 }))
+      .toThrow(/reorderTab/)
+  })
+
+  it('reorders inside one pane without changing the active tab', () => {
+    const { state, minter, paneId, guideTabId } = fixture()
+    const tab = fileTab(minter.next('tab'), 'dsh-resource://file/session/s/a.txt', 'a.txt')
+    const opened = applyOp(state, { type: 'openTab', paneId, tab, index: 1 }).state
+    const after = expectRoundTrip(opened, { type: 'reorderTab', tabId: tab.id, index: 0 })
+    expect(getPane(after, paneId).tabs).toEqual([tab.id, guideTabId])
+    expect(getPane(after, paneId).activeTabId).toBe(tab.id)
+  })
+})
+
+describe('focus', () => {
+  it('focuses a tab and its pane', () => {
+    const { state, minter, paneId, guideTabId } = fixture()
+    const tab = fileTab(minter.next('tab'), 'dsh-resource://file/session/s/a.txt', 'a.txt')
+    const opened = applyOp(state, { type: 'openTab', paneId, tab, index: 1 }).state
+    const after = expectRoundTrip(opened, { type: 'focusTab', tabId: guideTabId })
+    expect(getPane(after, paneId).activeTabId).toBe(guideTabId)
+  })
+
+  it('raises a floating pane when its tab takes focus', () => {
+    const { state, minter, paneId, guideTabId } = fixture()
+    const tab = fileTab(minter.next('tab'), 'dsh-resource://file/session/s/a.txt', 'a.txt')
+    let current = applyOp(state, { type: 'openTab', paneId, tab, index: 1 }).state
+    const firstFloat = minter.next('float')
+    const secondFloat = minter.next('float')
+    current = applyOp(current, {
+      type: 'float', tabId: guideTabId, newPaneId: firstFloat, rect: { x: 0, y: 0, width: 100, height: 100 },
+    }).state
+    current = applyOp(current, {
+      type: 'float', tabId: tab.id, newPaneId: secondFloat, rect: { x: 10, y: 10, width: 100, height: 100 },
+    }).state
+    const after = expectRoundTrip(current, { type: 'focusTab', tabId: guideTabId })
+    expect(after.floats).toEqual([secondFloat, firstFloat])
+    expect(after.activePaneId).toBe(firstFloat)
+  })
+
+  it('raises a floating pane when it takes focus', () => {
+    const { state, minter, paneId, guideTabId } = fixture()
+    const tab = fileTab(minter.next('tab'), 'dsh-resource://file/session/s/a.txt', 'a.txt')
+    let current = applyOp(state, { type: 'openTab', paneId, tab, index: 1 }).state
+    const firstFloat = minter.next('float')
+    const secondFloat = minter.next('float')
+    current = applyOp(current, {
+      type: 'float', tabId: guideTabId, newPaneId: firstFloat, rect: { x: 0, y: 0, width: 100, height: 100 },
+    }).state
+    current = applyOp(current, {
+      type: 'float', tabId: tab.id, newPaneId: secondFloat, rect: { x: 10, y: 10, width: 100, height: 100 },
+    }).state
+    expect(current.floats).toEqual([firstFloat, secondFloat])
+    const after = expectRoundTrip(current, { type: 'focusPane', paneId: firstFloat })
+    expect(after.floats).toEqual([secondFloat, firstFloat])
+    expect(after.activePaneId).toBe(firstFloat)
+  })
+})
+
+describe('resize', () => {
+  it('replaces divider sizes', () => {
+    const { state, minter, paneId } = fixture()
+    const after = split(state, minter, paneId)
+    const resized = expectRoundTrip(after.state, { type: 'resize', splitId: getSplit(after.state, after.state.rootId).id, sizes: [0.3, 0.7] })
+    expect(getSplit(resized, resized.rootId).sizes).toEqual([0.3, 0.7])
+  })
+
+  it('rejects the wrong count and non-positive sizes', () => {
+    const { state, minter, paneId } = fixture()
+    const after = split(state, minter, paneId)
+    const splitId = getSplit(after.state, after.state.rootId).id
+    expect(() => applyOp(after.state, { type: 'resize', splitId, sizes: [1] })).toThrow(/do not match/)
+    expect(() => applyOp(after.state, { type: 'resize', splitId, sizes: [0, 1] })).toThrow(/above zero/)
+  })
+})
+
+describe('floating panes', () => {
+  it('takes a tab out of the docked tree onto the top of the z order', () => {
+    const { state, minter, paneId, guideTabId } = fixture()
+    const floatId = minter.next('float')
+    const rect = { x: 40, y: 50, width: 300, height: 200 }
+    const after = expectRoundTrip(state, { type: 'float', tabId: guideTabId, newPaneId: floatId, rect })
+    expect(getPane(after, paneId).tabs).toEqual([])
+    expect(after.floats).toEqual([floatId])
+    expect(after.activePaneId).toBe(floatId)
+    const pane = getPane(after, floatId)
+    expect(pane.host).toBe('float')
+    expect(pane.tabs).toEqual([guideTabId])
+    expect(pane.rect).toEqual(rect)
+    expect(findParent(after, floatId)).toBeUndefined()
+  })
+
+  it('returns a floating tab to a docked pane and drops the floating pane', () => {
+    const { state, minter, paneId, guideTabId } = fixture()
+    const floatId = minter.next('float')
+    const floated = applyOp(state, {
+      type: 'float', tabId: guideTabId, newPaneId: floatId, rect: { x: 0, y: 0, width: 100, height: 100 },
+    }).state
+    const docked = expectRoundTrip(floated, { type: 'unfloat', paneId: floatId, toPaneId: paneId, index: 0 })
+    expect(docked.floats).toEqual([])
+    expect(docked.nodes[floatId]).toBeUndefined()
+    expect(getPane(docked, paneId).tabs).toEqual([guideTabId])
+    expect(docked.activePaneId).toBe(paneId)
+  })
+
+  it('destroys the floating pane together with its only tab', () => {
+    const { state, minter, paneId, guideTabId } = fixture()
+    const floatId = minter.next('float')
+    const floated = applyOp(state, {
+      type: 'float', tabId: guideTabId, newPaneId: floatId, rect: { x: 0, y: 0, width: 100, height: 100 },
+    }).state
+    const closed = expectRoundTrip(floated, { type: 'closeTab', tabId: guideTabId })
+    expect(closed.floats).toEqual([])
+    expect(closed.nodes[floatId]).toBeUndefined()
+    expect(closed.tabs[guideTabId]).toBeUndefined()
+    expect(closed.activePaneId).toBe(paneId)
+  })
+
+  it('records net drag and resize results, focusing and raising the pane they reshape', () => {
+    const { state, minter, paneId, guideTabId } = fixture()
+    const tab = fileTab(minter.next('tab'), 'dsh-resource://file/session/s/a.txt', 'a.txt')
+    const floatId = minter.next('float')
+    const topId = minter.next('float')
+    let current = applyOp(state, { type: 'openTab', paneId, tab, index: 1 }).state
+    current = applyOp(current, {
+      type: 'float', tabId: guideTabId, newPaneId: floatId, rect: { x: 0, y: 0, width: 100, height: 100 },
+    }).state
+    current = applyOp(current, {
+      type: 'float', tabId: tab.id, newPaneId: topId, rect: { x: 10, y: 10, width: 100, height: 100 },
+    }).state
+    current = applyOp(current, { type: 'focusPane', paneId }).state
+    expect(current.floats).toEqual([floatId, topId])
+    expect(current.activePaneId).toBe(paneId)
+
+    // The lower, unfocused panel is dragged: it ends on top and focused; undo puts both facts back.
+    const moved = expectRoundTrip(current, { type: 'moveFloat', paneId: floatId, x: 25, y: 35 })
+    expect(getPane(moved, floatId).rect).toEqual({ x: 25, y: 35, width: 100, height: 100 })
+    expect(moved.floats).toEqual([topId, floatId])
+    expect(moved.activePaneId).toBe(floatId)
+
+    const lowered = applyOp(moved, { type: 'focusPane', paneId: topId }).state
+    const resized = expectRoundTrip(lowered, {
+      type: 'resizeFloat', paneId: floatId, rect: { x: 25, y: 35, width: 420, height: 260 },
+    })
+    expect(getPane(resized, floatId).rect).toEqual({ x: 25, y: 35, width: 420, height: 260 })
+    expect(resized.floats).toEqual([topId, floatId])
+    expect(resized.activePaneId).toBe(floatId)
+    expect(() => applyOp(moved, {
+      type: 'resizeFloat', paneId: floatId, rect: { x: 0, y: 0, width: 0, height: 10 },
+    })).toThrow(/above zero/)
+  })
+
+  it('refuses to float a tab that already floats', () => {
+    const { state, minter, guideTabId } = fixture()
+    const floatId = minter.next('float')
+    const floated = applyOp(state, {
+      type: 'float', tabId: guideTabId, newPaneId: floatId, rect: { x: 0, y: 0, width: 100, height: 100 },
+    }).state
+    expect(() => applyOp(floated, {
+      type: 'float', tabId: guideTabId, newPaneId: minter.next('float'), rect: { x: 0, y: 0, width: 10, height: 10 },
+    })).toThrow(/docked tab/)
+  })
+})
+
+describe('presentation flags', () => {
+  it('round-trips the collapsed flag', () => {
+    const { state } = fixture()
+    const after = expectRoundTrip(state, { type: 'setExpanded', expanded: true })
+    expect(after.expanded).toBe(true)
+  })
+
+  it('round-trips the presentation mode', () => {
+    const { state } = fixture()
+    expect(state.mode).toBe('push')
+    const after = expectRoundTrip(state, { type: 'setMode', mode: 'fullscreen' })
+    expect(after.mode).toBe('fullscreen')
+    // The two flags are independent: switching one leaves the other alone.
+    expect(after.expanded).toBe(state.expanded)
+  })
+
+  it('starts in the presentation the embedder seeded', () => {
+    const minter = createIdMinter()
+    expect(createInitialState(minter, seedTab, 'fullscreen').mode).toBe('fullscreen')
+  })
+})
+
+describe('tree readers', () => {
+  /** The seeded pane floated out, leaving the root pane empty. */
+  function floated(): { state: LayoutState; paneId: PaneId; floatId: PaneId; guideTabId: TabId } {
+    const { state, minter, paneId, guideTabId } = fixture()
+    const floatId = minter.next('float')
+    const next = applyOp(state, {
+      type: 'float', tabId: guideTabId, newPaneId: floatId, rect: { x: 0, y: 0, width: 100, height: 100 },
+    }).state
+    return { state: next, paneId, floatId, guideTabId }
+  }
+
+  it('throw on a dangling id or a node of the other kind', () => {
+    const { state, minter, paneId } = fixture()
+    const after = split(state, minter, paneId).state
+    expect(() => getNode(after, asPane('nope'))).toThrow(/unknown node nope/)
+    expect(() => getPane(after, after.rootId)).toThrow(/is not a pane/)
+    expect(() => getSplit(after, paneId)).toThrow(/is not a split/)
+    expect(() => getTab(after, asTab('nope'))).toThrow(/unknown tab nope/)
+    expect(() => findTabPane(after, asTab('nope'))).toThrow(/has no pane/)
+    expect(() => replaceInParent(after, asPane('nope'), paneId)).toThrow(/neither rooted nor parented/)
+  })
+
+  it('read a floating pane\'s rectangle, z position, and only tab, and refuse a docked one', () => {
+    const { state, paneId, floatId, guideTabId } = floated()
+    const pane = getPane(state, floatId)
+    expect(floatRect(pane)).toEqual({ x: 0, y: 0, width: 100, height: 100 })
+    expect(floatIndex(state, floatId)).toBe(0)
+    expect(onlyTabId(pane)).toBe(guideTabId)
+    const docked = getPane(state, paneId)
+    expect(() => floatRect(docked)).toThrow(/is not floating/)
+    expect(() => floatIndex(state, paneId)).toThrow(/not in the z order/)
+    expect(() => onlyTabId(docked)).toThrow(/exactly one tab/)
+    const two: PaneNode = { ...pane, tabs: [guideTabId, asTab('other')] }
+    expect(() => onlyTabId(two)).toThrow(/exactly one tab/)
+  })
+
+  it('name the first and the top-right docked pane however the tree is divided', () => {
+    const { state, minter, paneId } = fixture()
+    expect(firstDockPaneId(state)).toBe(paneId)
+    expect(topRightPaneId(state)).toBe(paneId)
+    const right = split(state, minter, paneId)
+    const below = split(right.state, minter, right.newPaneId, 'column')
+    expect(firstDockPaneId(below.state)).toBe(paneId)
+    expect(topRightPaneId(below.state)).toBe(right.newPaneId)
+    const above = split(below.state, minter, paneId, 'column', 'before')
+    expect(firstDockPaneId(above.state)).toBe(above.newPaneId)
+  })
+
+  it('normalize sizes without drifting an exact sum, and refuse a zero total', () => {
+    const exact = [0.25, 0.75]
+    expect(normalizeSizes(exact)).toEqual(exact)
+    expect(normalizeSizes(exact)).not.toBe(exact)
+    expect(normalizeSizes([1, 3])).toEqual([0.25, 0.75])
+    expect(() => normalizeSizes([0, 0])).toThrow(/sum above zero/)
+  })
+
+  it('assertNever names the value a closed switch failed to handle', () => {
+    expect(() => { assertNever('nope' as never, 'layout: thing') }).toThrow('layout: thing: unhandled "nope"')
+  })
+})
+
+describe('operations refuse', () => {
+  /** A second docked pane plus a floating one holding a content tab. */
+  function mixed(): {
+    state: LayoutState
+    minter: IdMinter
+    paneId: PaneId
+    secondPaneId: PaneId
+    floatId: PaneId
+    guideTabId: TabId
+    floatTabId: TabId
+  } {
+    const { state, minter, paneId, guideTabId } = fixture()
+    const second = split(state, minter, paneId)
+    const tab = fileTab(minter.next('tab'), 'dsh-resource://file/session/s/a.txt', 'a.txt')
+    const opened = applyOp(second.state, { type: 'openTab', paneId, tab, index: 1 }).state
+    const floatId = minter.next('float')
+    const floated = applyOp(opened, {
+      type: 'float', tabId: tab.id, newPaneId: floatId, rect: { x: 0, y: 0, width: 100, height: 100 },
+    }).state
+    return { state: floated, minter, paneId, secondPaneId: second.newPaneId, floatId, guideTabId, floatTabId: tab.id }
+  }
+
+  it('opening or inserting a tab into a floating pane', () => {
+    const { state, minter, floatId } = mixed()
+    const tab = fileTab(minter.next('tab'), 'dsh-resource://file/session/s/b.txt', 'b.txt')
+    expect(() => applyOp(state, { type: 'openTab', paneId: floatId, tab, index: 0 })).toThrow(/docked pane/)
+    expect(() => applyOp(state, { type: 'insertTab', paneId: floatId, tab, index: 0 })).toThrow(/docked pane/)
+  })
+
+  it('moving a tab out of or into a floating pane, which is what unfloat and float are for', () => {
+    const { state, paneId, floatId, guideTabId, floatTabId } = mixed()
+    expect(() => applyOp(state, { type: 'moveTab', tabId: floatTabId, toPaneId: paneId, index: 0 })).toThrow(/use unfloat/)
+    expect(() => applyOp(state, { type: 'moveTab', tabId: guideTabId, toPaneId: floatId, index: 0 })).toThrow(/target must be docked/)
+  })
+
+  it('returning a floating tab anywhere but a docked pane, and treating a docked pane as floating', () => {
+    const { state, minter, paneId, floatId, guideTabId } = mixed()
+    const otherFloat = minter.next('float')
+    const twoFloats = applyOp(state, {
+      type: 'float', tabId: guideTabId, newPaneId: otherFloat, rect: { x: 5, y: 5, width: 100, height: 100 },
+    }).state
+    expect(() => applyOp(twoFloats, { type: 'unfloat', paneId: floatId, toPaneId: otherFloat, index: 0 }))
+      .toThrow(/target must be docked/)
+    expect(() => applyOp(state, { type: 'unfloat', paneId, toPaneId: paneId, index: 0 })).toThrow(/is not floating/)
+    expect(() => applyOp(state, { type: 'moveFloat', paneId, x: 1, y: 1 })).toThrow(/is not floating/)
+    expect(() => applyOp(state, { type: 'resizeFloat', paneId, rect: { x: 0, y: 0, width: 10, height: 10 } }))
+      .toThrow(/is not floating/)
+  })
+
+  it('creating a node under an id that is already taken', () => {
+    const { state, minter, paneId, secondPaneId } = mixed()
+    expect(() => applyOp(state, {
+      type: 'split', paneId, axis: 'column', direction: 'after', newPaneId: secondPaneId, newSplitId: minter.next('split'),
+    })).toThrow(/already exists/)
+    expect(() => applyOp(state, {
+      type: 'split', paneId, axis: 'column', direction: 'after', newPaneId: minter.next('pane'), newSplitId: asSplit(state.rootId),
+    })).toThrow(/already exists/)
+  })
+
+  it('putting a pane back with records that do not match the pane or the split', () => {
+    const { state, minter, paneId, secondPaneId, floatId } = mixed()
+    const pane = getPane(state, secondPaneId)
+    const stray = fileTab(minter.next('tab'), 'dsh-resource://file/session/s/c.txt', 'c.txt')
+    const fresh: PaneNode = { ...pane, id: minter.next('pane') }
+    const parent = getSplit(state, state.rootId)
+    expect(() => applyOp(state, {
+      type: 'insertPane', pane, tabs: [], attach: { mode: 'child', parentId: parent.id, index: 1, sizes: parent.sizes },
+    })).toThrow(/already exists/)
+    expect(() => applyOp(state, {
+      type: 'insertPane', pane: fresh, tabs: [stray], attach: { mode: 'child', parentId: parent.id, index: 1, sizes: parent.sizes },
+    })).toThrow(/do not match the pane/)
+    expect(() => applyOp(state, {
+      type: 'insertPane', pane: fresh, tabs: [], attach: { mode: 'child', parentId: parent.id, index: 1, sizes: parent.sizes },
+    })).toThrow(/sizes do not match the split/)
+    expect(() => applyOp(state, {
+      type: 'insertPane', pane: fresh, tabs: [], attach: { mode: 'wrap', targetId: paneId, split: parent },
+    })).toThrow(/does not list the pane/)
+    expect(() => applyOp(state, {
+      type: 'insertPane', pane: fresh, tabs: [], attach: { mode: 'float', index: 0 },
+    })).toThrow(/requires a floating pane/)
+    expect(floatId).toBeDefined()
+  })
+
+  it('restoring focus facts that name a docked pane as floating or an unknown pane', () => {
+    const { state, paneId } = mixed()
+    expect(() => applyOp(state, { type: 'restoreFocus', activePaneId: paneId, floats: [paneId], paneActiveTabs: {} }))
+      .toThrow(/as floating/)
+    expect(() => applyOp(state, { type: 'restoreFocus', activePaneId: paneId, floats: [], paneActiveTabs: { [asPane('nope')]: undefined } }))
+      .toThrow(/unknown node/)
+  })
+})
+
+describe('inverses the engine itself never records', () => {
+  it('refuse to return a docked pane with tab records: closeTab records those through insertTab', () => {
+    const { state, minter, paneId } = fixture()
+    const after = split(state, minter, paneId)
+    const parent = getSplit(after.state, after.state.rootId)
+    const tab = fileTab(minter.next('tab'), 'dsh-resource://file/session/s/a.txt', 'a.txt')
+    const pane: PaneNode = { kind: 'pane', id: minter.next('pane'), host: 'dock', tabs: [tab.id], activeTabId: tab.id, rect: undefined }
+    expect(() => applyOp(after.state, {
+      type: 'insertPane', pane, tabs: [tab], attach: { mode: 'child', parentId: parent.id, index: 2, sizes: [0.25, 0.25, 0.5] },
+    })).toThrow(/returns a docked pane empty/)
+  })
+
+  it('merge away an empty floating pane and restore it at its z position', () => {
+    const { state, minter } = fixture()
+    const pane: PaneNode = {
+      kind: 'pane', id: minter.next('float'), host: 'float', tabs: [], activeTabId: undefined, rect: { x: 1, y: 2, width: 50, height: 40 },
+    }
+    const inserted = expectRoundTrip(state, { type: 'insertPane', pane, tabs: [], attach: { mode: 'float', index: 0 } })
+    expect(inserted.floats).toEqual([pane.id])
+    const merged = expectRoundTrip(inserted, { type: 'merge', paneId: pane.id })
+    expect(merged.floats).toEqual([])
+    expect(merged.nodes[pane.id]).toBeUndefined()
+  })
+})
+
+describe('replay', () => {
+  it('rebuilds the same tree from the recorded operations', () => {
+    const { state, minter, paneId, guideTabId } = fixture()
+    const preview = fileTab(minter.next('tab'), 'dsh-resource://file/session/s/a.txt', 'a.txt')
+    const secondPaneId = minter.next('pane')
+    const floatId = minter.next('float')
+    const ops: LayoutOp[] = [
+      { type: 'setExpanded', expanded: true },
+      { type: 'openTab', paneId, tab: preview, index: 1 },
+      { type: 'split', paneId, axis: 'row', direction: 'after', newPaneId: secondPaneId, newSplitId: minter.next('split') },
+      { type: 'moveTab', tabId: preview.id, toPaneId: secondPaneId, index: 0 },
+      { type: 'focusTab', tabId: guideTabId },
+      { type: 'float', tabId: preview.id, newPaneId: floatId, rect: { x: 10, y: 20, width: 200, height: 150 } },
+      { type: 'moveFloat', paneId: floatId, x: 60, y: 70 },
+    ]
+    const direct = ops.reduce((current, op) => applyOp(current, op).state, state)
+    expect(replay(state, ops)).toEqual(direct)
+    expect(replay(state, ops)).toEqual(replay(state, ops))
+    expect(findTabPane(direct, preview.id).id).toBe(floatId)
+  })
+})
diff --git a/packages/client/ui-dockkit/tests/components.client.spec.tsx b/packages/client/ui-dockkit/tests/components.client.spec.tsx
new file mode 100644
index 0000000000..0ff855f694
--- /dev/null
+++ b/packages/client/ui-dockkit/tests/components.client.spec.tsx
@@ -0,0 +1,1150 @@
+// @vitest-environment jsdom
+/**
+ * Component-level behaviour of the kit's React surface, driven by props alone:
+ * no cordis, no slot registry, no scaffold. These assert what a user sees and
+ * which settled intent each gesture reports — the layout maths itself is covered
+ * by the engine suites.
+ *
+ * jsdom lays nothing out, so the gesture specs hand the surface a layout: panes
+ * of one width side by side, each 600px tall with a 36px strip and 100px chips.
+ */
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { DockIntents } from '../src/contract/adapter.ts'
+import type { PaneId, TabId } from '../src/contract/types.ts'
+import { DockController } from '../src/engine/controller.ts'
+import { applyOp } from '../src/engine/operations.ts'
+import { FLOAT_DEFAULT_SIZE, FLOAT_MIN_SIZE } from '../src/engine/constraints.ts'
+import { floatRectAt } from '../src/engine/geometry.ts'
+import { DockSurface, type DockSurfaceProps } from '../src/components/DockSurface.tsx'
+import type { TabMenuExtras } from '../src/contract/adapter.ts'
+import { FloatLayer } from '../src/components/FloatLayer.tsx'
+import { dockPaneIds, getPane } from '../src/engine/tree.ts'
+import { TEST_LABELS, asPane, asTab, fileTab, seededController } from './fixtures.client.ts'
+
+afterEach(() => {
+  cleanup()
+  vi.restoreAllMocks()
+  vi.unstubAllGlobals()
+})
+
+/** Every intent as a spy, so a spec can assert exactly which one fired. */
+function spyIntents(): DockIntents & Record<keyof DockIntents, ReturnType<typeof vi.fn>> {
+  return {
+    focusTab: vi.fn(),
+    focusPane: vi.fn(),
+    splitPane: vi.fn(),
+    addTab: vi.fn(),
+    closeTab: vi.fn(),
+    duplicateTab: vi.fn(),
+    floatTab: vi.fn(),
+    unfloatPane: vi.fn(),
+    placeTab: vi.fn(),
+    dropTab: vi.fn(),
+    moveFloat: vi.fn(),
+    resizeFloat: vi.fn(),
+    resizeSplit: vi.fn(),
+  } as DockIntents & Record<keyof DockIntents, ReturnType<typeof vi.fn>>
+}
+
+/** Render the docked surface over a controller's current layout. */
+function renderSurface(
+  controller: DockController,
+  intents: DockIntents,
+  canSplit = true,
+  renderTabMenuItems?: TabMenuExtras,
+  options: Pick<DockSurfaceProps, 'dropZones' | 'minPaneFraction'> = {},
+) {
+  const snapshot = controller.getSnapshot()
+  return render(
+    <DockSurface
+      {...options}
+      state={snapshot.state}
+      canSplit={canSplit}
+      intents={intents}
+      labels={TEST_LABELS}
+      renderTab={tab => <p data-testid="body">{tab.contentId}</p>}
+      {...renderTabMenuItems === undefined ? {} : { renderTabMenuItems }}
+    />,
+  )
+}
+
+const box = (x: number, y: number, width: number, height: number): DOMRect =>
+  ({ x, y, width, height, top: y, left: x, right: x + width, bottom: y + height, toJSON: () => ({}) })
+
+/** Height every laid-out pane takes. */
+const PANE_HEIGHT = 600
+
+/** Width of one laid-out chip. */
+const CHIP_WIDTH = 100
+
+/**
+ * Lay the surface out: `panes` in visual order, each `paneWidth` wide, side by
+ * side from the origin. Every pane's strip is 36px tall inside a 1px border,
+ * its chips 100px wide from the strip's left edge, its fixed controls 104px.
+ * Dividers are 4px wide; the surface and every split container span every
+ * pane, except the split containers `splits` gives their own box.
+ */
+function layOut(panes: readonly PaneId[], paneWidth: number, splits: Readonly<Record<string, DOMRect>> = {}): void {
+  vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
+    if (this.hasAttribute('data-dockkit-split')) {
+      return splits[this.getAttribute('data-dockkit-split') ?? ''] ?? box(0, 0, panes.length * paneWidth, PANE_HEIGHT)
+    }
+    if (this.hasAttribute('data-dockkit-surface')) return box(0, 0, panes.length * paneWidth, PANE_HEIGHT)
+    if (this.hasAttribute('data-dockkit-divider')) return box(0, 0, 4, PANE_HEIGHT)
+    const pane = this.closest<HTMLElement>('[data-dockkit-pane]')
+    const index = pane === null ? -1 : panes.indexOf(asPane(pane.dataset.dockkitPane ?? ''))
+    if (pane === null || index < 0) return box(0, 0, 0, 0)
+    const left = index * paneWidth
+    if (this === pane) return box(left, 0, paneWidth, PANE_HEIGHT)
+    const chips = [...pane.querySelectorAll('[data-dockkit-tab]')]
+    if (this.hasAttribute('data-dockkit-strip')) return box(left + 1, 1, paneWidth - 2, 36)
+    if (this.hasAttribute('data-dockkit-strip-tabs')) return box(left + 1, 1, chips.length * CHIP_WIDTH, 34)
+    if (this.hasAttribute('data-dockkit-strip-fill')) {
+      return box(left + 1 + chips.length * CHIP_WIDTH + 32, 1, Math.max(0, paneWidth - 2 - chips.length * CHIP_WIDTH - 104), 34)
+    }
+    if (this.hasAttribute('data-dockkit-tab')) return box(left + 1 + chips.indexOf(this) * CHIP_WIDTH, 1, CHIP_WIDTH, 34)
+    return box(0, 0, 0, 0)
+  })
+}
+
+/** Press `element` at a point and move to another, releasing there unless told not to. */
+function drag(element: Element, from: readonly [number, number], to: readonly [number, number], release = true): void {
+  fireEvent.pointerDown(element, { clientX: from[0], clientY: from[1], pointerId: 7, button: 0 })
+  fireEvent.pointerMove(window, { pointerId: 7, clientX: to[0], clientY: to[1] })
+  if (release) fireEvent.pointerUp(window, { pointerId: 7, clientX: to[0], clientY: to[1] })
+}
+
+/** Two seeded docked panes, the first also holding a content tab, with the layout state on a spied intent set. */
+function twoPanes(
+  paneWidth = 420,
+  canSplit = true,
+  options: Pick<DockSurfaceProps, 'dropZones' | 'minPaneFraction'> = {},
+): {
+  intents: ReturnType<typeof spyIntents>
+  first: PaneId
+  second: PaneId
+  seedTabId: TabId
+  fileTabId: TabId
+  chip: (tabId: TabId) => HTMLElement
+  unmount: () => void
+} {
+  const controller = seededController()
+  controller.setExpanded(true)
+  controller.splitPane()
+  const [first, second] = dockPaneIds(controller.getSnapshot().state)
+  if (first === undefined || second === undefined) throw new Error('expected two docked panes')
+  const fileTabId = controller.openContent({
+    contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file', paneId: first,
+  })
+  const seedTabId = getPane(controller.getSnapshot().state, first).tabs[0]
+  if (seedTabId === undefined) throw new Error('expected the seeded tab')
+  layOut([first, second], paneWidth)
+  const intents = spyIntents()
+  const { unmount } = renderSurface(controller, intents, canSplit, undefined, options)
+  const chip = (tabId: TabId): HTMLElement => {
+    const element = document.querySelector<HTMLElement>(`[data-dockkit-tab="${tabId}"]`)
+    if (element === null) throw new Error(`no chip for ${tabId}`)
+    return element
+  }
+  return { intents, first, second, seedTabId, fileTabId, chip, unmount }
+}
+
+/** The chip the layout puts second in the first pane: pressed at its centre. */
+const FILE_CHIP: readonly [number, number] = [151, 18]
+
+/** Which gesture intents fired, in order. */
+function gestureIntents(intents: ReturnType<typeof spyIntents>): string[] {
+  return (['placeTab', 'dropTab', 'floatTab', 'resizeSplit'] as const).filter(name => intents[name].mock.calls.length > 0)
+}
+
+describe('DockSurface', () => {
+  it('renders each pane with its tabs and the active tab body', () => {
+    const controller = seededController()
+    controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file' })
+    renderSurface(controller, spyIntents())
+
+    // The chip's text is its title alone: the close control is an icon.
+    expect(screen.getAllByRole('tab').map(tab => tab.textContent)).toEqual(['Start', 'a.txt'])
+    expect(screen.getByTestId('body').textContent).toBe('dsh-resource://file/session/s/a.txt')
+    expect(screen.getByRole('tab', { name: /a\.txt/u }).getAttribute('aria-selected')).toBe('true')
+  })
+
+  it('shows the empty-pane label when a pane holds nothing', () => {
+    const controller = new DockController()
+    renderSurface(controller, spyIntents())
+    expect(screen.getByText(TEST_LABELS.emptyPane)).toBeDefined()
+  })
+
+  it('reports one focus intent when a tab is clicked, not when it is pressed, and none for the pane', () => {
+    const controller = seededController()
+    controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file' })
+    const intents = spyIntents()
+    renderSurface(controller, intents)
+    const tab = screen.getByRole('tab', { name: /Start/u })
+
+    fireEvent.pointerDown(tab)
+    expect(intents.focusTab).not.toHaveBeenCalled()
+    fireEvent.click(tab)
+    const seeded = Object.values(controller.getSnapshot().state.tabs)[0]
+    expect(intents.focusTab).toHaveBeenCalledTimes(1)
+    expect(intents.focusTab).toHaveBeenCalledWith(seeded?.id)
+    // The tab's own operation decides the active pane; the pane records nothing of its own.
+    expect(intents.focusPane).not.toHaveBeenCalled()
+  })
+
+  it('records nothing for a click on the active pane\'s selected chip, but selects that chip in another pane', () => {
+    const controller = seededController()
+    controller.setExpanded(true)
+    controller.splitPane()
+    const state = controller.getSnapshot().state
+    const [first, second] = dockPaneIds(state)
+    if (first === undefined || second === undefined) throw new Error('expected two docked panes')
+    expect(state.activePaneId).toBe(second)
+    const intents = spyIntents()
+    renderSurface(controller, intents)
+    const selectedChip = (paneId: PaneId): Element => {
+      const chip = document.querySelector(`[data-dockkit-pane="${paneId}"] [data-dockkit-tab][aria-selected="true"]`)
+      if (chip === null) throw new Error(`expected a selected chip in ${paneId}`)
+      return chip
+    }
+    fireEvent.click(selectedChip(second))
+    expect(intents.focusTab).not.toHaveBeenCalled()
+    fireEvent.click(selectedChip(first))
+    expect(intents.focusTab).toHaveBeenCalledWith(getPane(state, first).activeTabId)
+    expect(intents.focusPane).not.toHaveBeenCalled()
+  })
+
+  it('focuses a pane when its body or strip is clicked, unless it is the active pane already', () => {
+    const controller = seededController()
+    controller.setExpanded(true)
+    controller.splitPane()
+    const state = controller.getSnapshot().state
+    const [first, second] = dockPaneIds(state)
+    if (first === undefined || second === undefined) throw new Error('expected two docked panes')
+    expect(state.activePaneId).toBe(second)
+    const intents = spyIntents()
+    renderSurface(controller, intents)
+    const body = (paneId: PaneId): Element => {
+      const element = document.querySelector(`[data-dockkit-pane="${paneId}"] [data-testid="body"]`)
+      if (element === null) throw new Error(`expected a body in ${paneId}`)
+      return element
+    }
+    // The active pane: nothing would change, so nothing is recorded.
+    fireEvent.click(body(second))
+    fireEvent.click(document.querySelector(`[data-dockkit-strip="${second}"]`) ?? body(second))
+    expect(intents.focusPane).not.toHaveBeenCalled()
+    // The other pane: its body and its strip's blank area both focus it.
+    fireEvent.click(body(first))
+    fireEvent.click(document.querySelector(`[data-dockkit-strip="${first}"]`) ?? body(first))
+    expect(intents.focusPane).toHaveBeenCalledTimes(2)
+    expect(intents.focusPane).toHaveBeenCalledWith(first)
+    expect(intents.focusTab).not.toHaveBeenCalled()
+  })
+
+  it('reports a split intent from the pane control, and disables it when the budget is spent', () => {
+    const controller = seededController()
+    const intents = spyIntents()
+    const { unmount } = renderSurface(controller, intents)
+    fireEvent.click(screen.getByRole('button', { name: TEST_LABELS.splitPane }))
+    expect(intents.splitPane).toHaveBeenCalledWith(controller.getSnapshot().state.rootId)
+    expect(intents.focusPane).not.toHaveBeenCalled()
+    unmount()
+
+    renderSurface(controller, intents, false)
+    const disabled = screen.getByRole('button', { name: TEST_LABELS.splitPane })
+    expect(disabled.hasAttribute('disabled')).toBe(true)
+    expect(disabled.getAttribute('title')).toBe(TEST_LABELS.splitPaneDisabled)
+    expect(disabled.getAttribute('data-dockkit-split-blocked')).toBe('budget')
+  })
+
+  it('hides capacity-blocked split controls when opted in and restores them when capacity returns', () => {
+    const controller = seededController()
+    controller.splitPane()
+    const state = controller.getSnapshot().state
+    layOut(dockPaneIds(state), 420)
+    const intents = spyIntents()
+    const props: DockSurfaceProps = {
+      state, canSplit: false, hideSplitAtCapacity: true, intents, labels: TEST_LABELS, renderTab: tab => <p>{tab.title}</p>,
+    }
+    const view = render(<DockSurface {...props} />)
+    expect(screen.queryByRole('button', { name: TEST_LABELS.splitPane })).toBeNull()
+    expect(view.container.querySelectorAll('[data-dockkit-split-button]')).toHaveLength(0)
+    expect(view.container.querySelectorAll('[data-dockkit-pane]')).toHaveLength(2)
+
+    view.rerender(<DockSurface {...props} canSplit />)
+    const buttons = screen.getAllByRole('button', { name: TEST_LABELS.splitPane })
+    expect(buttons).toHaveLength(2)
+    expect(buttons.every(button => !button.hasAttribute('disabled'))).toBe(true)
+    fireEvent.click(buttons[0]!)
+    expect(intents.splitPane).toHaveBeenCalledExactlyOnceWith(dockPaneIds(state)[0])
+  })
+
+  // jsdom lays nothing out, so the room rule reads the rectangles this spec
+  // hands it: two panes, one wide enough for two halves and one not. The
+  // strip's fixed part is 104px in both (the chrome pane's controls), the chip
+  // minimum falls back to the stylesheet's 59px.
+  it.each([false, true])('keeps the width-blocked split control and its title with hideSplitAtCapacity=%s', (hideSplitAtCapacity) => {
+    const controller = seededController()
+    controller.setExpanded(true)
+    controller.splitPane()
+    const snapshot = controller.getSnapshot()
+    const [wide, narrow] = dockPaneIds(snapshot.state)
+    if (wide === undefined || narrow === undefined) throw new Error('expected two docked panes')
+    const widths: Record<string, number> = { [wide]: 420, [narrow]: 208 }
+    vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
+      const paneWidth = widths[this.closest<HTMLElement>('[data-dockkit-pane]')?.dataset.dockkitPane ?? ''] ?? 0
+      if (this.hasAttribute('data-dockkit-pane')) return box(0, 0, paneWidth, 600)
+      if (this.hasAttribute('data-dockkit-strip')) return box(0, 0, paneWidth - 2, 36)
+      if (this.hasAttribute('data-dockkit-strip-tabs')) return box(0, 0, 60, 24)
+      if (this.hasAttribute('data-dockkit-strip-fill')) return box(0, 0, Math.max(0, paneWidth - 2 - 60 - 104), 24)
+      return box(0, 0, 0, 0)
+    })
+    render(
+      <DockSurface
+        state={snapshot.state}
+        canSplit
+        hideSplitAtCapacity={hideSplitAtCapacity}
+        intents={controller}
+        labels={TEST_LABELS}
+        renderTab={tab => <p>{tab.contentId}</p>}
+      />,
+    )
+    const wideButton = document.querySelector(`[data-dockkit-split-button="${wide}"]`)
+    const narrowButton = document.querySelector(`[data-dockkit-split-button="${narrow}"]`)
+    expect(wideButton?.hasAttribute('disabled')).toBe(false)
+    expect(wideButton?.getAttribute('title')).toBe(TEST_LABELS.splitPane)
+    expect(narrowButton?.hasAttribute('disabled')).toBe(true)
+    expect(narrowButton?.getAttribute('title')).toBe(TEST_LABELS.splitPaneNarrow)
+    expect(narrowButton?.getAttribute('data-dockkit-split-blocked')).toBe('width')
+  })
+
+  it('reports the room readings through onRoom, and re-reads them when the surface resizes', () => {
+    class FakeResizeObserver implements ResizeObserver {
+      static latest: FakeResizeObserver | undefined
+      readonly observe = vi.fn()
+      readonly unobserve = vi.fn()
+      readonly disconnect = vi.fn()
+      constructor(private readonly callback: ResizeObserverCallback) {
+        FakeResizeObserver.latest = this
+      }
+
+      /** What the platform does when the observed element's size changes. */
+      fire(): void {
+        this.callback([], this)
+      }
+    }
+    vi.stubGlobal('ResizeObserver', FakeResizeObserver)
+    const controller = seededController()
+    controller.setExpanded(true)
+    controller.splitPane()
+    const snapshot = controller.getSnapshot()
+    const panes = dockPaneIds(snapshot.state)
+    let paneWidth = 420
+    vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
+      if (this.hasAttribute('data-dockkit-pane')) return box(0, 0, paneWidth, 600)
+      if (this.hasAttribute('data-dockkit-strip')) return box(0, 0, paneWidth - 2, 36)
+      if (this.hasAttribute('data-dockkit-strip-tabs')) return box(0, 0, 60, 24)
+      if (this.hasAttribute('data-dockkit-strip-fill')) return box(0, 0, Math.max(0, paneWidth - 2 - 60 - 104), 24)
+      return box(0, 0, 0, 0)
+    })
+    const onRoom = vi.fn()
+    const { unmount } = render(
+      <DockSurface
+        state={snapshot.state}
+        canSplit
+        intents={controller}
+        labels={TEST_LABELS}
+        renderTab={tab => <p>{tab.contentId}</p>}
+        onRoom={onRoom}
+      />,
+    )
+    const observer = FakeResizeObserver.latest
+    if (observer === undefined) throw new Error('expected the surface to observe its own size')
+    expect(observer.observe).toHaveBeenCalledWith(document.querySelector('[data-dockkit-surface]'))
+    expect(onRoom).toHaveBeenLastCalledWith(new Map(panes.map(id => [id, { row: true, column: true }])))
+    const readings = onRoom.mock.calls.length
+
+    // The same reading again renders nothing new.
+    act(() => { observer.fire() })
+    expect(onRoom).toHaveBeenCalledTimes(readings)
+
+    // The column narrowed: every pane loses the room for a row split.
+    paneWidth = 208
+    act(() => { observer.fire() })
+    expect(onRoom).toHaveBeenLastCalledWith(new Map(panes.map(id => [id, { row: false, column: true }])))
+    unmount()
+    expect(observer.disconnect).toHaveBeenCalledTimes(1)
+  })
+
+  it('asks for the seeded tab from the strip\'s add control, naming the pane and nothing else', () => {
+    const controller = seededController()
+    const intents = spyIntents()
+    renderSurface(controller, intents)
+    fireEvent.click(screen.getByRole('button', { name: TEST_LABELS.addTab }))
+    expect(intents.addTab).toHaveBeenCalledWith(controller.getSnapshot().state.rootId)
+    expect(intents.focusPane).not.toHaveBeenCalled()
+  })
+
+  it('draws the add control only where the embedder\'s canAddTab allows, pane by pane', () => {
+    const controller = seededController()
+    controller.setExpanded(true)
+    controller.splitPane()
+    const snapshot = controller.getSnapshot()
+    const [first, second] = dockPaneIds(snapshot.state)
+    if (first === undefined || second === undefined) throw new Error('expected two docked panes')
+    render(
+      <DockSurface
+        state={snapshot.state}
+        canSplit
+        canAddTab={paneId => paneId === second}
+        intents={controller}
+        labels={TEST_LABELS}
+        renderTab={tab => <p>{tab.contentId}</p>}
+        chrome={<button type="button">chrome</button>}
+      />,
+    )
+    expect(document.querySelector(`[data-dockkit-pane="${first}"] [data-dockkit-add-tab]`)).toBeNull()
+    expect(document.querySelector(`[data-dockkit-pane="${second}"] [data-dockkit-add-tab]`)).not.toBeNull()
+    // The strip's end controls stay: only the add control is missing.
+    const strip = document.querySelector(`[data-dockkit-pane="${first}"] [data-dockkit-strip]`)
+    expect(strip?.querySelector('[data-dockkit-split-button]')).not.toBeNull()
+    expect(strip?.querySelector('[data-dockkit-strip-tabs]')).not.toBeNull()
+  })
+
+  it('lets the embedder render a chip\'s title, and shows the record\'s text when it does not', () => {
+    const controller = seededController()
+    controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file' })
+    const snapshot = controller.getSnapshot()
+    render(
+      <DockSurface
+        state={snapshot.state}
+        canSplit
+        intents={controller}
+        labels={TEST_LABELS}
+        renderTab={tab => <p>{tab.contentId}</p>}
+        renderTabTitle={tab => tab.kind === 'file' ? <em data-testid="rich-title">{tab.title.toUpperCase()}</em> : undefined}
+      />,
+    )
+    const titles = [...document.querySelectorAll('[data-dockkit-tab-title]')].map(el => el.textContent)
+    expect(titles).toEqual(['Start', 'A.TXT'])
+    expect(screen.getByTestId('rich-title').tagName).toBe('EM')
+  })
+
+  it('closes a tab from the chip\'s own control, without starting a drag', () => {
+    const controller = seededController()
+    const intents = spyIntents()
+    renderSurface(controller, intents)
+    const close = screen.getByRole('button', { name: TEST_LABELS.closeTab })
+    // A press on the nested control must not reach the chip's gesture handler;
+    // if it did, the pointer would be captured and this click would never land.
+    fireEvent.pointerDown(close)
+    fireEvent.click(close)
+    expect(intents.closeTab).toHaveBeenCalledTimes(1)
+    expect(intents.focusTab).not.toHaveBeenCalled()
+  })
+
+  it('opens the context menu on a secondary press, offering close and closing after acting', () => {
+    const controller = seededController()
+    const intents = spyIntents()
+    renderSurface(controller, intents)
+    expect(screen.queryByRole('menu')).toBeNull()
+    fireEvent.contextMenu(screen.getByRole('tab'))
+    expect(screen.getByRole('menu')).toBeDefined()
+    fireEvent.click(screen.getByRole('menuitem', { name: TEST_LABELS.closeTab }))
+    expect(intents.closeTab).toHaveBeenCalledTimes(1)
+    expect(screen.queryByRole('menu')).toBeNull()
+  })
+
+  it('toggles the menu closed on a second secondary press, and dismisses it on a press anywhere else', () => {
+    const controller = seededController()
+    renderSurface(controller, spyIntents())
+    const tab = screen.getByRole('tab')
+    fireEvent.contextMenu(tab)
+    fireEvent.contextMenu(tab)
+    expect(screen.queryByRole('menu')).toBeNull()
+
+    fireEvent.contextMenu(tab)
+    expect(screen.getByRole('menu')).toBeDefined()
+    fireEvent.pointerDown(document.body)
+    expect(screen.queryByRole('menu')).toBeNull()
+
+    // A press with no element target, dispatched to the window itself, counts as outside.
+    fireEvent.contextMenu(tab)
+    fireEvent.pointerDown(window)
+    expect(screen.queryByRole('menu')).toBeNull()
+  })
+
+  it('hangs the menu below the chip\'s left edge, or from its right edge when it would run off the viewport', () => {
+    const controller = seededController()
+    let left = 10
+    vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
+      return this.hasAttribute('data-dockkit-tab') ? box(left, 4, 60, 26) : box(0, 0, 0, 0)
+    })
+    const { unmount } = renderSurface(controller, spyIntents())
+    fireEvent.contextMenu(screen.getByRole('tab'))
+    expect(screen.getByRole('menu').style.top).toBe('34px')
+    expect(screen.getByRole('menu').style.left).toBe('10px')
+    unmount()
+
+    left = window.innerWidth + 100
+    renderSurface(controller, spyIntents())
+    fireEvent.contextMenu(screen.getByRole('tab'))
+    expect(screen.getByRole('menu').style.left).toBe(`${left + 60}px`)
+  })
+
+  it('offers no copy or float item: those gestures are the embedder\'s API and the drag', () => {
+    const controller = seededController()
+    renderSurface(controller, spyIntents())
+    fireEvent.contextMenu(screen.getByRole('tab'))
+    expect(screen.getAllByRole('menuitem').map(item => item.textContent)).toEqual([TEST_LABELS.closeTab])
+    expect(document.querySelector('[data-dockkit-tab-more]')).toBeNull()
+  })
+
+  it('appends embedder menu items after its own, and hands them the tab and a dismiss', () => {
+    const controller = seededController()
+    const acted = vi.fn<(contentId: string) => void>()
+    const extras: TabMenuExtras = (tab, dismiss) => (
+      <button
+        type="button"
+        role="menuitem"
+        data-testid="extra"
+        onClick={() => { acted(tab.contentId); dismiss() }}
+      >
+        embedder item
+      </button>
+    )
+    renderSurface(controller, spyIntents(), true, extras)
+    fireEvent.contextMenu(screen.getByRole('tab'))
+
+    // Order is contract: the kit's own item stays in the same place in every
+    // menu, so an embedder item cannot displace it.
+    expect(screen.getAllByRole('menuitem').map(item => item.textContent)).toEqual([
+      TEST_LABELS.closeTab, 'embedder item',
+    ])
+
+    fireEvent.click(screen.getByTestId('extra'))
+    expect(acted).toHaveBeenCalledWith('seed:start')
+    expect(screen.queryByRole('menu')).toBeNull()
+  })
+
+  it('keeps a menu press from starting a tab drag', () => {
+    const controller = seededController()
+    const intents = spyIntents()
+    renderSurface(controller, intents)
+    fireEvent.contextMenu(screen.getByRole('tab'))
+    const item = screen.getByRole('menuitem', { name: TEST_LABELS.closeTab })
+
+    // A press inside the menu must not reach the chip's gesture handler; if it
+    // did, the pointer would be captured and this click would never land.
+    fireEvent.pointerDown(item)
+    fireEvent.click(item)
+    expect(intents.closeTab).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('tab drags', () => {
+  it('previews a caret at the slot under the pointer and reports that slot on release', () => {
+    const { intents, first, fileTabId, chip } = twoPanes()
+    // Left of the first chip's midpoint: slot 0.
+    drag(chip(fileTabId), FILE_CHIP, [30, 18], false)
+    expect(document.querySelector('[data-dockkit-caret]')?.getAttribute('data-dockkit-caret')).toBe('0')
+    // Past both chips: the slot after the last one, drawn at the strip's end.
+    fireEvent.pointerMove(window, { pointerId: 7, clientX: 300, clientY: 18 })
+    expect(document.querySelector('[data-dockkit-caret]')?.getAttribute('data-dockkit-caret')).toBe('2')
+    fireEvent.pointerUp(window, { pointerId: 7, clientX: 300, clientY: 18 })
+    // The slot counts the dragged chip itself; the planner turns it into a reorder.
+    expect(intents.placeTab).toHaveBeenCalledWith(fileTabId, first, 2)
+    expect(gestureIntents(intents)).toEqual(['placeTab'])
+    expect(document.querySelector('[data-dockkit-caret]')).toBeNull()
+  })
+
+  it('reports a slot in another pane\'s strip as a placement there', () => {
+    const { intents, second, fileTabId, chip } = twoPanes()
+    drag(chip(fileTabId), FILE_CHIP, [420 + 30, 18])
+    expect(intents.placeTab).toHaveBeenCalledWith(fileTabId, second, 0)
+  })
+
+  it('shows the dock hint on the pane under the pointer and reports the zone on release', () => {
+    const { intents, second, fileTabId, chip } = twoPanes()
+    drag(chip(fileTabId), FILE_CHIP, [420 + 210, 300], false)
+    const hint = document.querySelector(`[data-dockkit-pane="${second}"] [data-dockkit-dock-zone]`)
+    expect(hint?.getAttribute('data-dockkit-dock-zone')).toBe('center')
+    fireEvent.pointerMove(window, { pointerId: 7, clientX: 420 + 410, clientY: 300 })
+    expect(document.querySelector('[data-dockkit-dock-zone]')?.getAttribute('data-dockkit-dock-zone')).toBe('right')
+    fireEvent.pointerUp(window, { pointerId: 7, clientX: 420 + 410, clientY: 300 })
+    expect(intents.dropTab).toHaveBeenCalledWith(fileTabId, second, 'right')
+    expect(document.querySelector('[data-dockkit-dock-zone]')).toBeNull()
+  })
+
+  it('offers no edge zone once the pane budget is spent: a release there moves nothing', () => {
+    const { intents, fileTabId, chip } = twoPanes(420, false)
+    drag(chip(fileTabId), FILE_CHIP, [420 + 410, 300], false)
+    expect(document.querySelector('[data-dockkit-dock-zone]')).toBeNull()
+    fireEvent.pointerUp(window, { pointerId: 7, clientX: 420 + 410, clientY: 300 })
+    expect(gestureIntents(intents)).toEqual([])
+  })
+
+  // 208px panes: room for a column split (600px tall) but not for a row split.
+  it('offers an edge zone only on the axis the pane has room to split on', () => {
+    const { intents, second, fileTabId, chip } = twoPanes(208)
+    drag(chip(fileTabId), FILE_CHIP, [208 + 200, 300], false)
+    expect(document.querySelector('[data-dockkit-dock-zone]')).toBeNull()
+    fireEvent.pointerMove(window, { pointerId: 7, clientX: 208 + 104, clientY: 100 })
+    expect(document.querySelector('[data-dockkit-dock-zone]')?.getAttribute('data-dockkit-dock-zone')).toBe('top')
+    fireEvent.pointerUp(window, { pointerId: 7, clientX: 208 + 104, clientY: 100 })
+    expect(intents.dropTab).toHaveBeenCalledWith(fileTabId, second, 'top')
+  })
+
+  it('floats a tab released clear of the surface, with the panel under the drop point', () => {
+    const { intents, fileTabId, chip } = twoPanes()
+    drag(chip(fileTabId), FILE_CHIP, [2000, 900])
+    expect(intents.floatTab).toHaveBeenCalledWith(fileTabId, floatRectAt(2000, 900, FLOAT_DEFAULT_SIZE))
+    expect(gestureIntents(intents)).toEqual(['floatTab'])
+  })
+
+  it('treats a press that never travels the threshold as no drag at all', () => {
+    const { intents, fileTabId, chip } = twoPanes()
+    drag(chip(fileTabId), FILE_CHIP, [FILE_CHIP[0] + 2, FILE_CHIP[1] + 1], false)
+    expect(document.querySelector('[data-dockkit-caret]')).toBeNull()
+    fireEvent.pointerUp(window, { pointerId: 7, clientX: 2000, clientY: 900 })
+    expect(gestureIntents(intents)).toEqual([])
+  })
+
+  it('ignores a secondary press: that is the menu, never a drag', () => {
+    const { intents, fileTabId, chip } = twoPanes()
+    fireEvent.pointerDown(chip(fileTabId), { clientX: FILE_CHIP[0], clientY: FILE_CHIP[1], pointerId: 7, button: 2 })
+    fireEvent.pointerMove(window, { pointerId: 7, clientX: 2000, clientY: 900 })
+    fireEvent.pointerUp(window, { pointerId: 7, clientX: 2000, clientY: 900 })
+    expect(gestureIntents(intents)).toEqual([])
+  })
+
+  it('drops the preview and reports nothing when the platform cancels the pointer', () => {
+    const { intents, fileTabId, chip } = twoPanes()
+    drag(chip(fileTabId), FILE_CHIP, [30, 18], false)
+    expect(document.querySelector('[data-dockkit-caret]')).not.toBeNull()
+    fireEvent.pointerCancel(window, { pointerId: 7 })
+    expect(document.querySelector('[data-dockkit-caret]')).toBeNull()
+    fireEvent.pointerUp(window, { pointerId: 7, clientX: 30, clientY: 18 })
+    expect(gestureIntents(intents)).toEqual([])
+  })
+
+  it('lets a new press take over from a gesture still in flight', () => {
+    const { intents, first, seedTabId, fileTabId, chip } = twoPanes()
+    drag(chip(fileTabId), FILE_CHIP, [30, 18], false)
+    expect(document.querySelector('[data-dockkit-caret]')).not.toBeNull()
+    // The second press ends the first gesture: its preview clears and its release never reports.
+    fireEvent.pointerDown(chip(seedTabId), { clientX: 51, clientY: 18, pointerId: 8, button: 0 })
+    expect(document.querySelector('[data-dockkit-caret]')).toBeNull()
+    fireEvent.pointerMove(window, { pointerId: 8, clientX: 300, clientY: 18 })
+    fireEvent.pointerUp(window, { pointerId: 8, clientX: 300, clientY: 18 })
+    expect(intents.placeTab).toHaveBeenCalledTimes(1)
+    expect(intents.placeTab).toHaveBeenCalledWith(seedTabId, first, 2)
+  })
+
+  it('stops following the pointer when unmounted mid-gesture', () => {
+    const { intents, fileTabId, chip, unmount } = twoPanes()
+    drag(chip(fileTabId), FILE_CHIP, [30, 18], false)
+    unmount()
+    fireEvent.pointerMove(window, { pointerId: 7, clientX: 300, clientY: 18 })
+    fireEvent.pointerUp(window, { pointerId: 7, clientX: 300, clientY: 18 })
+    expect(gestureIntents(intents)).toEqual([])
+  })
+
+  it('follows only its own pointer: another pointer neither moves, releases, nor cancels the gesture', () => {
+    const { intents, first, fileTabId, chip } = twoPanes()
+    fireEvent.pointerDown(chip(fileTabId), { clientX: FILE_CHIP[0], clientY: FILE_CHIP[1], pointerId: 7, button: 0 })
+    fireEvent.pointerMove(window, { pointerId: 9, clientX: 30, clientY: 18 })
+    expect(document.querySelector('[data-dockkit-caret]')).toBeNull()
+    fireEvent.pointerUp(window, { pointerId: 9, clientX: 30, clientY: 18 })
+    fireEvent.pointerCancel(window, { pointerId: 9 })
+    expect(gestureIntents(intents)).toEqual([])
+    // The gesture is still alive for its own pointer.
+    fireEvent.pointerMove(window, { pointerId: 7, clientX: 30, clientY: 18 })
+    expect(document.querySelector('[data-dockkit-caret]')?.getAttribute('data-dockkit-caret')).toBe('0')
+    fireEvent.pointerUp(window, { pointerId: 7, clientX: 30, clientY: 18 })
+    expect(intents.placeTab).toHaveBeenCalledWith(fileTabId, first, 0)
+    expect(intents.placeTab).toHaveBeenCalledTimes(1)
+  })
+
+  it('captures the pointer on the pressed chip where the platform offers capture', () => {
+    const capture = vi.fn<(pointerId: number) => void>()
+    Object.defineProperty(HTMLElement.prototype, 'setPointerCapture', { value: capture, configurable: true, writable: true })
+    try {
+      const { fileTabId, chip } = twoPanes()
+      fireEvent.pointerDown(chip(fileTabId), { clientX: FILE_CHIP[0], clientY: FILE_CHIP[1], pointerId: 7, button: 0 })
+      expect(capture).toHaveBeenCalledWith(7)
+    } finally {
+      Reflect.deleteProperty(HTMLElement.prototype, 'setPointerCapture')
+    }
+  })
+})
+
+describe('horizontal workbench drops', () => {
+  it.each([
+    { x: 450, y: 300, zone: 'left' },
+    { x: 810, y: 590, zone: 'right' },
+  ] as const)('offers both halves and targets $zone at ($x, $y)', ({ x, y, zone }) => {
+    const { intents, second, fileTabId, chip } = twoPanes(420, true, { dropZones: 'horizontal' })
+    drag(chip(fileTabId), FILE_CHIP, [x, y], false)
+    const hints = document.querySelectorAll('[data-dockkit-dock-zone]')
+    expect([...hints].map(hint => hint.getAttribute('data-dockkit-dock-zone'))).toEqual(['left', 'right'])
+    expect(document.querySelector('[data-dockkit-drop-active]')?.getAttribute('data-dockkit-dock-zone')).toBe(zone)
+    fireEvent.pointerUp(window, { pointerId: 7, clientX: x, clientY: y })
+    expect(intents.dropTab).toHaveBeenCalledExactlyOnceWith(fileTabId, second, zone)
+  })
+
+  it('uses the entire other pane for moving once the split budget is spent', () => {
+    const { intents, second, fileTabId, chip } = twoPanes(420, false, { dropZones: 'horizontal' })
+    drag(chip(fileTabId), FILE_CHIP, [425, 590])
+    expect(intents.dropTab).toHaveBeenCalledExactlyOnceWith(fileTabId, second, 'center')
+  })
+
+  it('does not offer a new split when a pane cannot fit two halves', () => {
+    const { intents, second, fileTabId, chip } = twoPanes(300, true, { dropZones: 'horizontal' })
+    drag(chip(fileTabId), FILE_CHIP, [450, 300], false)
+    expect(document.querySelectorAll('[data-dockkit-dock-zone]')).toHaveLength(1)
+    expect(document.querySelector('[data-dockkit-dock-zone]')?.getAttribute('data-dockkit-dock-zone')).toBe('center')
+    fireEvent.pointerUp(window, { pointerId: 7, clientX: 450, clientY: 300 })
+    expect(intents.dropTab).toHaveBeenCalledExactlyOnceWith(fileTabId, second, 'center')
+  })
+
+  it('clamps the live divider preview and committed sizes to the requested minimum', () => {
+    const { intents } = twoPanes(420, false, { minPaneFraction: 0.2 })
+    const divider = document.querySelector('[data-dockkit-divider]')
+    if (divider === null) throw new Error('expected a divider')
+    drag(divider, [420, 300], [0, 300], false)
+    const cells = document.querySelectorAll<HTMLElement>('[data-dockkit-cell]')
+    expect(Number(cells[0]?.style.flexGrow)).toBeCloseTo(0.2)
+    expect(Number(cells[1]?.style.flexGrow)).toBeCloseTo(0.8)
+    fireEvent.pointerUp(window, { pointerId: 7, clientX: 0, clientY: 300 })
+    expect(intents.resizeSplit.mock.calls[0]?.[1]).toEqual([0.2, 0.8])
+  })
+})
+
+describe('keyboard tabs', () => {
+  /** One pane holding the seed and two files, the last opened selected, with the chips by title. */
+  function threeChips(): { intents: ReturnType<typeof spyIntents>; chip: (title: string) => HTMLElement; ids: Record<string, TabId> } {
+    const controller = seededController()
+    const a = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file' })
+    const b = controller.openContent({ contentId: 'dsh-resource://file/session/s/b.txt', title: 'b.txt', kind: 'file' })
+    const seed = getPane(controller.getSnapshot().state, controller.getSnapshot().state.rootId).tabs[0]
+    if (seed === undefined) throw new Error('expected the seeded tab')
+    const intents = spyIntents()
+    renderSurface(controller, intents)
+    const chip = (title: string): HTMLElement => screen.getByRole('tab', { name: new RegExp(title.replace('.', '\\.'), 'u') })
+    return { intents, chip, ids: { Start: seed, 'a.txt': a, 'b.txt': b } }
+  }
+
+  it('puts only the selected chip in the tab order', () => {
+    const { chip } = threeChips()
+    expect(chip('b.txt').tabIndex).toBe(0)
+    expect(chip('a.txt').tabIndex).toBe(-1)
+    expect(chip('Start').tabIndex).toBe(-1)
+  })
+
+  it('moves focus with Left and Right, wrapping, and with Home and End, without selecting', () => {
+    const { intents, chip } = threeChips()
+    chip('b.txt').focus()
+    fireEvent.keyDown(chip('b.txt'), { key: 'ArrowRight' })
+    expect(document.activeElement).toBe(chip('Start'))
+    fireEvent.keyDown(chip('Start'), { key: 'ArrowLeft' })
+    expect(document.activeElement).toBe(chip('b.txt'))
+    fireEvent.keyDown(chip('b.txt'), { key: 'ArrowLeft' })
+    expect(document.activeElement).toBe(chip('a.txt'))
+    fireEvent.keyDown(chip('a.txt'), { key: 'Home' })
+    expect(document.activeElement).toBe(chip('Start'))
+    fireEvent.keyDown(chip('Start'), { key: 'End' })
+    expect(document.activeElement).toBe(chip('b.txt'))
+    expect(intents.focusTab).not.toHaveBeenCalled()
+  })
+
+  it('selects the focused chip with Enter or Space, once each, and ignores other keys', () => {
+    const { intents, chip, ids } = threeChips()
+    chip('b.txt').focus()
+    fireEvent.keyDown(chip('b.txt'), { key: 'ArrowLeft' })
+    fireEvent.keyDown(chip('a.txt'), { key: 'Enter' })
+    expect(intents.focusTab).toHaveBeenCalledWith(ids['a.txt'])
+    fireEvent.keyDown(chip('a.txt'), { key: 'Home' })
+    fireEvent.keyDown(chip('Start'), { key: ' ' })
+    expect(intents.focusTab).toHaveBeenCalledWith(ids.Start)
+    fireEvent.keyDown(chip('Start'), { key: 'a' })
+    fireEvent.keyDown(chip('Start'), { key: 'Escape' })
+    expect(intents.focusTab).toHaveBeenCalledTimes(2)
+  })
+
+  it('records nothing for Enter on the active pane\'s selected chip, and leaves keys on the close control alone', () => {
+    const { intents, chip } = threeChips()
+    fireEvent.keyDown(chip('b.txt'), { key: 'Enter' })
+    fireEvent.keyDown(chip('b.txt'), { key: ' ' })
+    const close = chip('a.txt').querySelector('[data-dockkit-tab-close]')
+    if (close === null) throw new Error('expected the close control')
+    fireEvent.keyDown(close, { key: 'Enter' })
+    fireEvent.keyDown(close, { key: 'ArrowLeft' })
+    expect(intents.focusTab).not.toHaveBeenCalled()
+    expect(intents.closeTab).not.toHaveBeenCalled()
+  })
+})
+
+describe('divider drags', () => {
+  /** A row split whose second pane is itself split into a column: the column split's id and a spied intent set. */
+  function withColumn(columnBox: DOMRect): { intents: ReturnType<typeof spyIntents>; columnId: string } {
+    const controller = seededController()
+    controller.setExpanded(true)
+    controller.splitPane()
+    const [first, second] = dockPaneIds(controller.getSnapshot().state)
+    if (first === undefined || second === undefined) throw new Error('expected two docked panes')
+    const opened = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file', paneId: second })
+    controller.dropTab(opened, second, 'bottom')
+    const state = controller.getSnapshot().state
+    const root = state.nodes[state.rootId]
+    const columnId = root?.kind === 'split' ? root.children[1] : undefined
+    if (columnId === undefined || state.nodes[columnId]?.kind !== 'split') throw new Error('expected a column split')
+    layOut(dockPaneIds(state), 420, { [columnId]: columnBox })
+    const intents = spyIntents()
+    renderSurface(controller, intents)
+    return { intents, columnId }
+  }
+
+  it('moves a column split\'s divider along the vertical axis', () => {
+    const { intents, columnId } = withColumn(box(420, 0, 420, 600))
+    const divider = document.querySelector(`[data-dockkit-divider="${columnId}:0"]`)
+    if (divider === null) throw new Error('expected the column divider')
+    drag(divider, [630, 300], [630, 360])
+    const [reportedSplit, sizes] = intents.resizeSplit.mock.calls[0] as [string, readonly number[]]
+    expect(reportedSplit).toBe(columnId)
+    expect(sizes[0]).toBeCloseTo(0.6)
+    expect(sizes[1]).toBeCloseTo(0.4)
+  })
+
+  it('reports nothing for a release that left the fractions where they were', () => {
+    const { intents } = twoPanes()
+    const divider = document.querySelector('[data-dockkit-divider]')
+    if (divider === null) throw new Error('expected a divider between the two panes')
+    // A click on the divider.
+    drag(divider, [420, 300], [420, 300])
+    // A drag returned to where it began.
+    drag(divider, [420, 300], [504, 300], false)
+    fireEvent.pointerMove(window, { pointerId: 7, clientX: 420, clientY: 300 })
+    fireEvent.pointerUp(window, { pointerId: 7, clientX: 420, clientY: 300 })
+    expect(intents.resizeSplit).not.toHaveBeenCalled()
+    // A real move still reports, once.
+    drag(divider, [420, 300], [504, 300])
+    expect(intents.resizeSplit).toHaveBeenCalledTimes(1)
+  })
+
+  it('reports nothing along a split that has no measured extent', () => {
+    const { intents, columnId } = withColumn(box(420, 0, 420, 0))
+    const divider = document.querySelector(`[data-dockkit-divider="${columnId}:0"]`)
+    if (divider === null) throw new Error('expected the column divider')
+    drag(divider, [630, 300], [630, 360])
+    expect(intents.resizeSplit).not.toHaveBeenCalled()
+  })
+
+  it('previews the fractions while the divider moves and reports the net result once', () => {
+    const { intents, first, second } = twoPanes()
+    const divider = document.querySelector('[data-dockkit-divider]')
+    if (divider === null) throw new Error('expected a divider between the two panes')
+    const splitId = divider.getAttribute('data-dockkit-divider')?.split(':')[0]
+    // The split spans 840px, so 84px of travel is a tenth of it.
+    drag(divider, [420, 300], [504, 300], false)
+    const cell = (index: number): number =>
+      Number(document.querySelector<HTMLElement>(`[data-dockkit-cell="${splitId}:${index}"]`)?.style.flexGrow)
+    expect(cell(0)).toBeCloseTo(0.6)
+    expect(cell(1)).toBeCloseTo(0.4)
+    fireEvent.pointerUp(window, { pointerId: 7, clientX: 504, clientY: 300 })
+    expect(intents.resizeSplit).toHaveBeenCalledTimes(1)
+    const [reportedSplit, sizes] = intents.resizeSplit.mock.calls[0] as [string, readonly number[]]
+    expect(reportedSplit).toBe(splitId)
+    expect(sizes[0]).toBeCloseTo(0.6)
+    expect(sizes[1]).toBeCloseTo(0.4)
+    // The recorded fractions come back through the state; the preview is gone.
+    expect(cell(0)).toBeCloseTo(0.5)
+    expect(intents.placeTab).not.toHaveBeenCalled()
+    expect([first, second]).toHaveLength(2)
+  })
+})
+
+describe('FloatLayer', () => {
+  /** Two floating panels, `lower` under `upper`, with `upper` active. */
+  function twoFloats(): {
+    intents: ReturnType<typeof spyIntents>
+    lower: PaneId
+    upper: PaneId
+    panel: (paneId: PaneId) => HTMLElement
+    part: (attribute: string, paneId: PaneId) => Element
+  } {
+    const controller = seededController()
+    const first = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file' })
+    const second = controller.openContent({ contentId: 'dsh-resource://file/session/s/b.txt', title: 'b.txt', kind: 'file' })
+    const lower = controller.floatTab(first, { x: 100, y: 80, width: 300, height: 200 })
+    const upper = controller.floatTab(second, { x: 500, y: 80, width: 300, height: 200 })
+    const intents = spyIntents()
+    render(<FloatLayer state={controller.getSnapshot().state} intents={intents} labels={TEST_LABELS} renderTab={() => null} />)
+    const part = (attribute: string, paneId: PaneId): Element => {
+      const element = document.querySelector(`[${attribute}="${paneId}"]`)
+      if (element === null) throw new Error(`expected ${attribute} of ${paneId}`)
+      return element
+    }
+    const panel = (paneId: PaneId): HTMLElement => {
+      const element = document.querySelector<HTMLElement>(`[data-dockkit-float="${paneId}"]`)
+      if (element === null) throw new Error(`expected the panel ${paneId}`)
+      return element
+    }
+    return { intents, lower, upper, panel, part }
+  }
+
+  /** One floating panel over a spied intent set. */
+  function floating(): { intents: ReturnType<typeof spyIntents>; paneId: PaneId; tabId: TabId; panel: HTMLElement } {
+    const controller = seededController()
+    const tabId = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file' })
+    const paneId = controller.floatTab(tabId, { x: 100, y: 80, width: 300, height: 200 })
+    const intents = spyIntents()
+    render(
+      <FloatLayer
+        state={controller.getSnapshot().state}
+        intents={intents}
+        labels={TEST_LABELS}
+        renderTab={tab => <p data-testid="float-body">{tab.title}</p>}
+      />,
+    )
+    const panel = document.querySelector<HTMLElement>(`[data-dockkit-float="${paneId}"]`)
+    if (panel === null) throw new Error('expected a floating panel')
+    return { intents, paneId, tabId, panel }
+  }
+
+  it('draws one panel per floating pane, without a tab strip', () => {
+    const { intents } = floating()
+    expect(screen.getByTestId('float-body').textContent).toBe('a.txt')
+    expect(screen.queryByRole('tablist')).toBeNull()
+    fireEvent.click(screen.getByRole('button', { name: TEST_LABELS.dockFloat }))
+    expect(intents.unfloatPane).toHaveBeenCalledTimes(1)
+  })
+
+  it('closes a floating panel through its own control', () => {
+    const { intents, tabId } = floating()
+    fireEvent.click(screen.getByRole('button', { name: TEST_LABELS.closeFloat }))
+    expect(intents.closeTab).toHaveBeenCalledWith(tabId)
+  })
+
+  it('raises a panel on a press on its body, but not from a press on its controls, grip, or corner', () => {
+    const { intents, lower, panel, part } = twoFloats()
+    fireEvent.pointerDown(panel(lower))
+    expect(intents.focusPane).toHaveBeenCalledWith(lower)
+    fireEvent.pointerDown(part('data-dockkit-float-dock', lower))
+    fireEvent.pointerDown(part('data-dockkit-float-close', lower))
+    fireEvent.pointerDown(part('data-dockkit-float-grip', lower), { clientX: 150, clientY: 90, pointerId: 7, button: 0 })
+    fireEvent.pointerDown(part('data-dockkit-float-resize', lower), { clientX: 400, clientY: 280, pointerId: 8, button: 0 })
+    expect(intents.focusPane).toHaveBeenCalledTimes(1)
+  })
+
+  it('records nothing for a press on the panel that is active and on top already', () => {
+    const { intents, upper, panel, part } = twoFloats()
+    fireEvent.pointerDown(panel(upper))
+    // A grip or corner press released in place is a click on the same panel.
+    drag(part('data-dockkit-float-grip', upper), [550, 90], [550, 90])
+    drag(part('data-dockkit-float-resize', upper), [800, 280], [800, 280])
+    expect(intents.focusPane).not.toHaveBeenCalled()
+    expect(intents.moveFloat).not.toHaveBeenCalled()
+    expect(intents.resizeFloat).not.toHaveBeenCalled()
+  })
+
+  it('raises the active panel when another has been drawn over it', () => {
+    const controller = seededController()
+    const first = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file' })
+    const second = controller.openContent({ contentId: 'dsh-resource://file/session/s/b.txt', title: 'b.txt', kind: 'file' })
+    const lower = controller.floatTab(first, { x: 100, y: 80, width: 300, height: 200 })
+    const upper = controller.floatTab(second, { x: 500, y: 80, width: 300, height: 200 })
+    // Focus on the lower panel while the upper stays on top: only a recorded
+    // focus snapshot puts the layout there, as an undo does.
+    const buried = applyOp(controller.getSnapshot().state, {
+      type: 'restoreFocus', activePaneId: lower, floats: [lower, upper], paneActiveTabs: {},
+    }).state
+    const intents = spyIntents()
+    render(<FloatLayer state={buried} intents={intents} labels={TEST_LABELS} renderTab={() => null} />)
+    const panel = document.querySelector(`[data-dockkit-float="${lower}"]`)
+    if (panel === null) throw new Error('expected the lower panel')
+    fireEvent.pointerDown(panel)
+    expect(intents.focusPane).toHaveBeenCalledWith(lower)
+  })
+
+  it('moves a panel by its grip as one intent, previewing the position and the panel on top', () => {
+    const controller = seededController()
+    const first = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file' })
+    const second = controller.openContent({ contentId: 'dsh-resource://file/session/s/b.txt', title: 'b.txt', kind: 'file' })
+    const lower = controller.floatTab(first, { x: 100, y: 80, width: 300, height: 200 })
+    controller.floatTab(second, { x: 500, y: 80, width: 300, height: 200 })
+    const intents = spyIntents()
+    render(<FloatLayer state={controller.getSnapshot().state} intents={intents} labels={TEST_LABELS} renderTab={() => null} />)
+    const panel = document.querySelector<HTMLElement>(`[data-dockkit-float="${lower}"]`)
+    const grip = document.querySelector(`[data-dockkit-float-grip="${lower}"]`)
+    if (panel === null || grip === null) throw new Error('expected the lower panel')
+    expect(panel.style.zIndex).toBe('1')
+
+    drag(grip, [150, 90], [180, 110], false)
+    expect(panel.style.left).toBe('130px')
+    expect(panel.style.top).toBe('100px')
+    // Mid-gesture the panel draws on top, as the move it records will leave it.
+    expect(panel.style.zIndex).toBe('3')
+    fireEvent.pointerUp(window, { pointerId: 7, clientX: 180, clientY: 110 })
+    expect(intents.moveFloat).toHaveBeenCalledWith(lower, 130, 100)
+    expect(intents.moveFloat).toHaveBeenCalledTimes(1)
+    expect(intents.focusPane).not.toHaveBeenCalled()
+    // The recorded rectangle and depth are drawn again once the preview clears.
+    expect(panel.style.left).toBe('100px')
+    expect(panel.style.zIndex).toBe('1')
+  })
+
+  it('treats a press on the grip or corner released where it began as a click that raises the panel', () => {
+    const { intents, lower, part } = twoFloats()
+    drag(part('data-dockkit-float-grip', lower), [150, 90], [150, 90])
+    drag(part('data-dockkit-float-resize', lower), [400, 280], [400, 280])
+    expect(intents.focusPane).toHaveBeenCalledTimes(2)
+    expect(intents.focusPane).toHaveBeenCalledWith(lower)
+    expect(intents.moveFloat).not.toHaveBeenCalled()
+    expect(intents.resizeFloat).not.toHaveBeenCalled()
+  })
+
+  it('resizes from the corner as one intent, holding the minimum size', () => {
+    const { intents, paneId, panel } = floating()
+    const corner = document.querySelector(`[data-dockkit-float-resize="${paneId}"]`)
+    if (corner === null) throw new Error('expected a resize corner')
+    drag(corner, [400, 280], [440, 310], false)
+    expect(panel.style.width).toBe('340px')
+    expect(panel.style.height).toBe('230px')
+    fireEvent.pointerMove(window, { pointerId: 7, clientX: -1000, clientY: -1000 })
+    expect(panel.style.width).toBe(`${FLOAT_MIN_SIZE.width}px`)
+    fireEvent.pointerUp(window, { pointerId: 7, clientX: -1000, clientY: -1000 })
+    expect(intents.resizeFloat).toHaveBeenCalledWith(paneId, { x: 100, y: 80, ...FLOAT_MIN_SIZE })
+    expect(intents.resizeFloat).toHaveBeenCalledTimes(1)
+    expect(intents.focusPane).not.toHaveBeenCalled()
+  })
+
+  it('stacks panels in the model z order', () => {
+    const controller = seededController()
+    const first = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file' })
+    const second = controller.openContent({ contentId: 'dsh-resource://file/session/s/b.txt', title: 'b.txt', kind: 'file' })
+    controller.floatTab(first)
+    controller.floatTab(second)
+    render(
+      <FloatLayer
+        state={controller.getSnapshot().state}
+        intents={spyIntents()}
+        labels={TEST_LABELS}
+        renderTab={() => null}
+      />,
+    )
+    const zIndexes = screen.getAllByRole('banner').map(header => header.parentElement?.style.zIndex)
+    expect(zIndexes).toEqual(['1', '2'])
+  })
+})
+
+describe('surface chrome', () => {
+  it('renders the embedder\'s controls once, at the end of the top-right pane\'s strip', () => {
+    const controller = seededController()
+    controller.setExpanded(true)
+    // A row split puts the new pane to the right; a bottom drop under it puts a
+    // pane below that. The top-right pane is the right column's upper one.
+    controller.splitPane()
+    const right = controller.getSnapshot().state
+    const root = right.nodes[right.rootId]
+    const rightPaneId = root?.kind === 'split' ? root.children[1] : undefined
+    if (rightPaneId === undefined) throw new Error('expected a row split')
+    const seeded = controller.getSnapshot().state.nodes[rightPaneId]
+    if (seeded === undefined || seeded.kind !== 'pane' || seeded.tabs[0] === undefined) throw new Error('expected a seeded pane')
+    const opened = controller.openContent({ contentId: 'dsh-resource://file/session/s/b.txt', title: 'b.txt', kind: 'file', paneId: seeded.id })
+    controller.dropTab(opened, seeded.id, 'bottom')
+
+    const snapshot = controller.getSnapshot()
+    render(
+      <DockSurface
+        state={snapshot.state}
+        canSplit
+        intents={controller}
+        labels={TEST_LABELS}
+        renderTab={tab => <p>{tab.contentId}</p>}
+        chrome={<button type="button">chrome</button>}
+      />,
+    )
+    const hosts = screen.getAllByRole('button', { name: 'chrome' })
+    expect(hosts).toHaveLength(1)
+    const pane = hosts[0]?.closest('[data-dockkit-pane]')
+    // The upper of the two right-hand panes, not the lower one the drop created.
+    expect(pane?.getAttribute('data-dockkit-pane')).toBe(rightPaneId)
+    // At the strip's end: after the split control.
+    const strip = pane?.querySelector('[data-dockkit-strip]')
+    const children = [...(strip?.children ?? [])]
+    expect(children.at(-1)?.hasAttribute('data-dockkit-strip-chrome')).toBe(true)
+  })
+
+  it('keeps a click on the chrome from focusing the pane: the embedder\'s controls report their own intents', () => {
+    const controller = seededController()
+    const intents = spyIntents()
+    render(
+      <DockSurface
+        state={controller.getSnapshot().state}
+        canSplit
+        intents={intents}
+        labels={TEST_LABELS}
+        renderTab={tab => <p>{tab.contentId}</p>}
+        chrome={<button type="button">chrome</button>}
+      />,
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'chrome' }))
+    expect(intents.focusPane).not.toHaveBeenCalled()
+  })
+
+  it('renders no chrome host when the embedder supplies none', () => {
+    const controller = seededController()
+    renderSurface(controller, spyIntents())
+    expect(document.querySelector('[data-dockkit-strip-chrome]')).toBeNull()
+  })
+
+  // Layout itself is the stylesheet's; what the DOM promises is that every
+  // chip and drop caret sits inside the strip's one shrinking box, and that the
+  // controls after it are the strip's own children, in this order.
+  it('keeps the chips in their own box ahead of the add, split, and chrome controls', () => {
+    const controller = seededController()
+    controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file' })
+    const snapshot = controller.getSnapshot()
+    render(
+      <DockSurface
+        state={snapshot.state}
+        canSplit
+        intents={controller}
+        labels={TEST_LABELS}
+        renderTab={tab => <p>{tab.contentId}</p>}
+        chrome={<button type="button">chrome</button>}
+      />,
+    )
+    const strip = document.querySelector('[data-dockkit-strip]')
+    const role = (child: Element): string => {
+      if (child.hasAttribute('data-dockkit-strip-tabs')) return 'tabs'
+      if (child.hasAttribute('data-dockkit-add-tab')) return 'add'
+      if (child.hasAttribute('data-dockkit-split-button')) return 'split'
+      if (child.hasAttribute('data-dockkit-strip-chrome')) return 'chrome'
+      return 'fill'
+    }
+    expect([...(strip?.children ?? [])].map(role)).toEqual(['tabs', 'add', 'fill', 'split', 'chrome'])
+    expect(strip?.querySelectorAll('[data-dockkit-strip-tabs] [data-dockkit-tab]')).toHaveLength(2)
+    expect(strip?.querySelectorAll(':scope > [data-dockkit-tab]')).toHaveLength(0)
+  })
+})
+
+describe('a controller satisfies the intent contract', () => {
+  it('accepts a DockController wherever DockIntents is required', () => {
+    const controller = seededController()
+    const intents: DockIntents = controller
+    renderSurface(controller, intents)
+    fireEvent.click(screen.getByRole('button', { name: TEST_LABELS.splitPane }))
+    // One click, one entry: the split seeded its new pane, and that seating is
+    // what decides the active pane — the control's click reports nothing else.
+    expect(controller.ops.map(op => op.type)).toEqual(['split', 'openTab'])
+  })
+})
+
+describe('fileTab', () => {
+  it('builds a content tab the kit treats as opaque', () => {
+    expect(fileTab(asTab('t1'), 'dsh-resource://file/session/s/x', 'x').kind).toBe('file')
+  })
+})
diff --git a/packages/client/ui-dockkit/tests/constraints.client.spec.ts b/packages/client/ui-dockkit/tests/constraints.client.spec.ts
new file mode 100644
index 0000000000..0b116ee229
--- /dev/null
+++ b/packages/client/ui-dockkit/tests/constraints.client.spec.ts
@@ -0,0 +1,131 @@
+/**
+ * Interaction limits: the four-pane cap, the five dock regions, and divider
+ * clamping. The model itself stays unbounded; these rules gate dispatch.
+ */
+import { describe, expect, it } from 'vitest'
+import { applyOp } from '../src/engine/operations.ts'
+import {
+  canSplit, clampSizes, DOCK_ZONES, dockPaneCount, MAX_DOCK_PANES, MIN_PANE_FRACTION, zoneAt, zoneSplit,
+} from '../src/engine/constraints.ts'
+import { createIdMinter, createInitialState } from '../src/engine/initial.ts'
+import { seedTab } from './fixtures.client.ts'
+import { getPane } from '../src/engine/tree.ts'
+import type { LayoutState } from '../src/contract/types.ts'
+
+/** Split the root pane repeatedly until the docked grid holds `count` panes. */
+function grid(count: number): LayoutState {
+  const minter = createIdMinter()
+  let state = createInitialState(minter, seedTab)
+  while (dockPaneCount(state) < count) {
+    state = applyOp(state, {
+      type: 'split',
+      paneId: state.activePaneId,
+      axis: 'row',
+      direction: 'after',
+      newPaneId: minter.next('pane'),
+      newSplitId: minter.next('split'),
+    }).state
+  }
+  return state
+}
+
+describe('pane cap', () => {
+  it('allows splitting up to four docked panes and no further', () => {
+    expect(MAX_DOCK_PANES).toBe(4)
+    expect(canSplit(createInitialState(createIdMinter(), seedTab))).toBe(true)
+    expect(dockPaneCount(grid(4))).toBe(4)
+    expect(canSplit(grid(4))).toBe(false)
+    expect(canSplit(grid(3))).toBe(true)
+  })
+
+  it('ignores floating panes when counting the grid', () => {
+    const minter = createIdMinter()
+    const state = createInitialState(minter, seedTab)
+    const guideTabId = getPane(state, state.rootId).tabs[0]
+    if (guideTabId === undefined) throw new Error('fixture: no guide tab')
+    const floated = applyOp(state, {
+      type: 'float', tabId: guideTabId, newPaneId: minter.next('float'), rect: { x: 0, y: 0, width: 10, height: 10 },
+    }).state
+    expect(floated.floats).toHaveLength(1)
+    expect(dockPaneCount(floated)).toBe(1)
+    expect(canSplit(floated)).toBe(true)
+  })
+})
+
+describe('dock regions', () => {
+  it('offers five regions', () => {
+    expect([...DOCK_ZONES].sort()).toEqual(['bottom', 'center', 'left', 'right', 'top'])
+  })
+
+  it('reads the centre of a pane as a move, not a split', () => {
+    expect(zoneAt(0.5, 0.5)).toBe('center')
+    expect(zoneSplit('center')).toBeUndefined()
+  })
+
+  it('reads each edge band as its own region', () => {
+    expect(zoneAt(0.05, 0.5)).toBe('left')
+    expect(zoneAt(0.95, 0.5)).toBe('right')
+    expect(zoneAt(0.5, 0.05)).toBe('top')
+    expect(zoneAt(0.5, 0.95)).toBe('bottom')
+  })
+
+  it('takes the closest edge in a corner', () => {
+    expect(zoneAt(0.02, 0.10)).toBe('left')
+    expect(zoneAt(0.10, 0.02)).toBe('top')
+  })
+
+  it('maps regions to the split they create', () => {
+    expect(zoneSplit('left')).toEqual({ axis: 'row', direction: 'before' })
+    expect(zoneSplit('right')).toEqual({ axis: 'row', direction: 'after' })
+    expect(zoneSplit('top')).toEqual({ axis: 'column', direction: 'before' })
+    expect(zoneSplit('bottom')).toEqual({ axis: 'column', direction: 'after' })
+  })
+})
+
+describe('divider clamping', () => {
+  it('honours an embedder\'s twenty-percent minimum', () => {
+    expect(clampSizes([0.01, 0.99], 0.2)).toEqual([0.2, 0.8])
+    expect(clampSizes([0.99, 0.01], 0.2)).toEqual([0.8, 0.2])
+    expect(clampSizes([0.5, 0.5], 0.2)).toEqual([0.5, 0.5])
+  })
+
+  it('keeps sizes summing to one', () => {
+    const sizes = clampSizes([0.6, 0.4])
+    expect(sizes.reduce((sum, size) => sum + size, 0)).toBeCloseTo(1)
+    expect(sizes[0]).toBeCloseTo(0.6)
+  })
+
+  it('lifts a pane dragged under the minimum', () => {
+    const sizes = clampSizes([0.01, 0.99])
+    expect(sizes[0]).toBeGreaterThanOrEqual(MIN_PANE_FRACTION * 0.9)
+    expect(sizes.reduce((sum, size) => sum + size, 0)).toBeCloseTo(1)
+  })
+
+  it('accepts unnormalized pixel-like input', () => {
+    const sizes = clampSizes([300, 100])
+    expect(sizes[0]).toBeCloseTo(0.75)
+    expect(sizes[1]).toBeCloseTo(0.25)
+  })
+
+  it('treats a negative size as zero and shares an all-zero input equally', () => {
+    expect(clampSizes([])).toEqual([])
+    const lifted = clampSizes([-1, 1])
+    expect(lifted[0]).toBeCloseTo(MIN_PANE_FRACTION)
+    expect(lifted[1]).toBeCloseTo(1 - MIN_PANE_FRACTION)
+    expect(clampSizes([0, 0])).toEqual([0.5, 0.5])
+  })
+
+  it('pins a share that drops under the minimum only after the first pass', () => {
+    // 0.13 clears the floor until the first pin takes its 0.11 from everyone.
+    const sizes = clampSizes([0.01, 0.13, 0.86])
+    expect(sizes[0]).toBeCloseTo(MIN_PANE_FRACTION)
+    expect(sizes[1]).toBeCloseTo(MIN_PANE_FRACTION)
+    expect(sizes[2]).toBeCloseTo(1 - 2 * MIN_PANE_FRACTION)
+  })
+
+  it('never lifts a pane above an equal share when the minimum would not fit them all', () => {
+    const sizes = clampSizes(Array.from({ length: 10 }, (_, index) => (index === 0 ? 0.001 : 1)))
+    expect(sizes[0]).toBeCloseTo(0.1)
+    expect(sizes.reduce((sum, size) => sum + size, 0)).toBeCloseTo(1)
+  })
+})
diff --git a/packages/client/ui-dockkit/tests/controller.client.spec.ts b/packages/client/ui-dockkit/tests/controller.client.spec.ts
new file mode 100644
index 0000000000..5c296763b6
--- /dev/null
+++ b/packages/client/ui-dockkit/tests/controller.client.spec.ts
@@ -0,0 +1,360 @@
+/**
+ * Controller behavior: the interaction vocabulary the UI calls, including tab
+ * identity (focus an existing tab, or open an explicit copy), the guide tab a
+ * split seats, drop resolution, floating, and the notification contract.
+ */
+import { describe, expect, it } from 'vitest'
+import { DockController } from '../src/engine/controller.ts'
+import { dockPaneCount, FLOAT_DEFAULT_SIZE } from '../src/engine/constraints.ts'
+import { SEED_CONTENT_ID, childAt, firstTab, seededController } from './fixtures.client.ts'
+import { dockPaneIds, findTabPane, getPane, getSplit } from '../src/engine/tree.ts'
+import type { LayoutState, PaneId } from '../src/contract/types.ts'
+
+/** Tab titles of one pane, in strip order. */
+function titles(state: LayoutState, paneId: PaneId): string[] {
+  return getPane(state, paneId).tabs.map(id => state.tabs[id]?.title ?? '?')
+}
+
+/** A controller expanded once, with its first pane id. */
+function expanded(): { controller: DockController; paneId: PaneId } {
+  const controller = seededController()
+  controller.setExpanded(true)
+  const { state } = controller.getSnapshot()
+  return { controller, paneId: getPane(state, state.rootId).id }
+}
+
+describe('expand', () => {
+  it('starts collapsed with a guide tab already seated', () => {
+    const controller = seededController()
+    const snapshot = controller.getSnapshot()
+    expect(snapshot.state.expanded).toBe(false)
+    expect(snapshot.canUndo).toBe(false)
+    expect(snapshot.canSplit).toBe(true)
+    expect(titles(snapshot.state, getPane(snapshot.state, snapshot.state.rootId).id)).toHaveLength(1)
+    const guide = Object.values(snapshot.state.tabs)[0]
+    expect(guide?.contentId).toBe(SEED_CONTENT_ID)
+  })
+
+  it('records a toggle and ignores a redundant set', () => {
+    const controller = seededController()
+    controller.toggleExpanded()
+    expect(controller.getSnapshot().state.expanded).toBe(true)
+    expect(controller.ops).toHaveLength(1)
+    controller.setExpanded(true)
+    expect(controller.ops).toHaveLength(1)
+    controller.toggleExpanded()
+    expect(controller.getSnapshot().state.expanded).toBe(false)
+    expect(controller.ops).toHaveLength(2)
+  })
+})
+
+describe('presentation', () => {
+  it('records a mode switch once and ignores a redundant one', () => {
+    const controller = seededController()
+    controller.setMode('fullscreen')
+    expect(controller.getSnapshot().state.mode).toBe('fullscreen')
+    controller.setMode('fullscreen')
+    expect(controller.ops.map(op => op.type)).toEqual(['setMode'])
+  })
+})
+
+describe('splitting', () => {
+  it('splits the active pane to the right and seats a guide tab there', () => {
+    const { controller, paneId } = expanded()
+    expect(controller.splitPane()).toBe(true)
+    const state = controller.getSnapshot().state
+    const root = getSplit(state, state.rootId)
+    expect(root.axis).toBe('row')
+    const newPaneId = getPane(state, childAt(root, 1)).id
+    expect(newPaneId).not.toBe(paneId)
+    expect(titles(state, newPaneId)).toHaveLength(1)
+    expect(state.tabs[firstTab(getPane(state, newPaneId))]?.contentId).toBe(SEED_CONTENT_ID)
+    expect(controller.ops.map(op => op.type)).toEqual(['setExpanded', 'split', 'openTab'])
+  })
+
+  it('seats the pane factory\'s tab at the end of a strip from the add control, and nothing without one', () => {
+    const { controller, paneId } = expanded()
+    expect(controller.addTab(paneId)).toBe(true)
+    expect(titles(controller.getSnapshot().state, paneId)).toEqual(['Start', 'Start'])
+    const bare = new DockController({ makeInitialTab: id => ({ id, kind: 'seed', contentId: SEED_CONTENT_ID, title: 'Start' }) })
+    expect(bare.addTab(getPane(bare.getSnapshot().state, bare.getSnapshot().state.rootId).id)).toBe(false)
+  })
+
+  it('names the pane a new tab lands in: the active pane, or the first docked one while a panel floats', () => {
+    const { controller, paneId } = expanded()
+    expect(controller.activeDockPaneId()).toBe(paneId)
+    const tabId = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    const floatId = controller.floatTab(tabId)
+    expect(controller.getSnapshot().state.activePaneId).toBe(floatId)
+    expect(controller.activeDockPaneId()).toBe(paneId)
+  })
+
+  it('stops at four panes without recording anything', () => {
+    const { controller } = expanded()
+    expect(controller.splitPane()).toBe(true)
+    expect(controller.splitPane()).toBe(true)
+    expect(controller.splitPane()).toBe(true)
+    expect(dockPaneCount(controller.getSnapshot().state)).toBe(4)
+    const before = controller.ops.length
+    expect(controller.splitPane()).toBe(false)
+    expect(controller.ops).toHaveLength(before)
+    expect(controller.getSnapshot().canSplit).toBe(false)
+  })
+})
+
+describe('tab identity', () => {
+  it('focuses the existing tab when the same content is opened twice', () => {
+    const { controller, paneId } = expanded()
+    const first = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    controller.splitPane()
+    const again = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    expect(again).toBe(first)
+    const state = controller.getSnapshot().state
+    expect(getPane(state, paneId).activeTabId).toBe(first)
+    expect(state.activePaneId).toBe(paneId)
+    expect(Object.values(state.tabs).filter(tab => tab.contentId === 'dsh-resource://file/session/s/a.txt')).toHaveLength(1)
+  })
+
+  it('opens an explicit second copy beside the original', () => {
+    const { controller, paneId } = expanded()
+    const first = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    const copy = controller.duplicateTab(first)
+    expect(copy).not.toBe(first)
+    const state = controller.getSnapshot().state
+    expect(state.tabs[copy]?.contentId).toBe('dsh-resource://file/session/s/a.txt')
+    expect(getPane(state, paneId).tabs.indexOf(copy)).toBe(getPane(state, paneId).tabs.indexOf(first) + 1)
+  })
+
+  it('closes a tab and leaves the pane in place', () => {
+    const { controller, paneId } = expanded()
+    const tabId = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    controller.closeTab(tabId)
+    const state = controller.getSnapshot().state
+    expect(state.tabs[tabId]).toBeUndefined()
+    expect(dockPaneIds(state)).toEqual([paneId])
+  })
+})
+
+describe('drops', () => {
+  it('moves a tab into the pane under the pointer', () => {
+    const { controller, paneId } = expanded()
+    const tabId = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    controller.splitPane()
+    const target = getSplit(controller.getSnapshot().state, controller.getSnapshot().state.rootId).children[1]
+    if (target === undefined) throw new Error('expected a second pane')
+    expect(controller.dropTab(tabId, getPane(controller.getSnapshot().state, target).id, 'center')).toBe(true)
+    const state = controller.getSnapshot().state
+    expect(getPane(state, target).tabs).toContain(tabId)
+    expect(getPane(state, paneId).tabs).not.toContain(tabId)
+    expect(state.activePaneId).toBe(target)
+  })
+
+  it('rejects a centre drop on the tab own pane', () => {
+    const { controller, paneId } = expanded()
+    const tabId = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    const before = controller.ops.length
+    expect(controller.dropTab(tabId, paneId, 'center')).toBe(false)
+    expect(controller.ops).toHaveLength(before)
+  })
+
+  it('splits on an edge drop and lands the tab in the new pane', () => {
+    const { controller, paneId } = expanded()
+    const tabId = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    expect(controller.dropTab(tabId, paneId, 'bottom')).toBe(true)
+    const state = controller.getSnapshot().state
+    const root = getSplit(state, state.rootId)
+    expect(root.axis).toBe('column')
+    const created = root.children[1]
+    if (created === undefined) throw new Error('expected a split child')
+    expect(getPane(state, created).tabs).toEqual([tabId])
+    expect(dockPaneCount(state)).toBe(2)
+  })
+
+  it('refuses an edge drop once the grid is full', () => {
+    const { controller, paneId } = expanded()
+    const tabId = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    controller.splitPane()
+    controller.splitPane()
+    controller.splitPane()
+    const before = controller.ops.length
+    expect(controller.dropTab(tabId, paneId, 'right')).toBe(false)
+    expect(controller.ops).toHaveLength(before)
+  })
+
+  it('reorders inside one pane', () => {
+    const { controller, paneId } = expanded()
+    const first = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    controller.reorderTab(first, 0)
+    expect(getPane(controller.getSnapshot().state, paneId).tabs[0]).toBe(first)
+  })
+})
+
+describe('explicit tab placement', () => {
+  it('reorders when the slot is in the tab own pane', () => {
+    const { controller, paneId } = expanded()
+    const first = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    expect(controller.placeTab(first, paneId, 0)).toBe(true)
+    expect(getPane(controller.getSnapshot().state, paneId).tabs[0]).toBe(first)
+    expect(controller.ops.at(-1)?.type).toBe('reorderTab')
+  })
+
+  it('reports no change when the slot is where the tab already sits', () => {
+    const { controller, paneId } = expanded()
+    const tabId = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    const index = getPane(controller.getSnapshot().state, paneId).tabs.indexOf(tabId)
+    const before = controller.ops.length
+    expect(controller.placeTab(tabId, paneId, index)).toBe(false)
+    expect(controller.ops).toHaveLength(before)
+  })
+
+  it('moves across panes into the requested slot', () => {
+    const { controller, paneId } = expanded()
+    const tabId = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    controller.splitPane()
+    const target = getSplit(controller.getSnapshot().state, controller.getSnapshot().state.rootId).children[1]
+    if (target === undefined) throw new Error('expected a second pane')
+    expect(controller.placeTab(tabId, getPane(controller.getSnapshot().state, target).id, 0)).toBe(true)
+    const state = controller.getSnapshot().state
+    expect(getPane(state, target).tabs[0]).toBe(tabId)
+    expect(getPane(state, paneId).tabs).not.toContain(tabId)
+  })
+
+  it('returns a floating tab when placed into a docked strip', () => {
+    const { controller, paneId } = expanded()
+    const tabId = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    const floatId = controller.floatTab(tabId)
+    expect(controller.placeTab(tabId, paneId, 0)).toBe(true)
+    const state = controller.getSnapshot().state
+    expect(state.floats).toEqual([])
+    expect(state.nodes[floatId]).toBeUndefined()
+    expect(getPane(state, paneId).tabs[0]).toBe(tabId)
+  })
+
+  it('refuses a floating pane as the destination', () => {
+    const { controller } = expanded()
+    const first = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    const second = controller.openContent({ contentId: 'dsh-resource://file/session/s/b.txt', title: 'b.txt', kind: 'text-preview' })
+    const floatId = controller.floatTab(first)
+    const before = controller.ops.length
+    expect(controller.placeTab(second, floatId, 0)).toBe(false)
+    expect(controller.ops).toHaveLength(before)
+  })
+})
+
+describe('floating', () => {
+  it('takes a tab out and cascades each new panel', () => {
+    const { controller, paneId } = expanded()
+    const first = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    const second = controller.openContent({ contentId: 'dsh-resource://file/session/s/b.txt', title: 'b.txt', kind: 'text-preview' })
+    const firstFloat = controller.floatTab(first)
+    const secondFloat = controller.floatTab(second)
+    const state = controller.getSnapshot().state
+    expect(state.floats).toEqual([firstFloat, secondFloat])
+    const one = getPane(state, firstFloat)
+    const two = getPane(state, secondFloat)
+    expect(one.rect?.width).toBe(FLOAT_DEFAULT_SIZE.width)
+    expect(two.rect?.x).toBeGreaterThan(one.rect?.x ?? 0)
+    expect(getPane(state, paneId).tabs).toHaveLength(1)
+  })
+
+  it('is unaffected by collapsing the column', () => {
+    const { controller } = expanded()
+    const tabId = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    const floatId = controller.floatTab(tabId)
+    controller.setExpanded(false)
+    const state = controller.getSnapshot().state
+    expect(state.expanded).toBe(false)
+    expect(state.floats).toEqual([floatId])
+    expect(getPane(state, floatId).tabs).toEqual([tabId])
+  })
+
+  it('sends a floating panel back into the grid', () => {
+    const { controller, paneId } = expanded()
+    const tabId = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    const floatId = controller.floatTab(tabId)
+    controller.unfloatPane(floatId)
+    const state = controller.getSnapshot().state
+    expect(state.floats).toEqual([])
+    expect(findTabPane(state, tabId).id).toBe(paneId)
+  })
+
+  it('treats a centre drop from a floating panel as a return', () => {
+    const { controller, paneId } = expanded()
+    const tabId = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    const floatId = controller.floatTab(tabId)
+    expect(controller.dropTab(tabId, paneId, 'center')).toBe(true)
+    const state = controller.getSnapshot().state
+    expect(state.floats).toEqual([])
+    expect(state.nodes[floatId]).toBeUndefined()
+    expect(findTabPane(state, tabId).id).toBe(paneId)
+  })
+
+  it('records net drag and resize results', () => {
+    const { controller } = expanded()
+    const tabId = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    const floatId = controller.floatTab(tabId)
+    controller.moveFloat(floatId, 300, 210)
+    controller.resizeFloat(floatId, { x: 300, y: 210, width: 500, height: 400 })
+    expect(getPane(controller.getSnapshot().state, floatId).rect)
+      .toEqual({ x: 300, y: 210, width: 500, height: 400 })
+    expect(controller.ops.map(op => op.type).slice(-2)).toEqual(['moveFloat', 'resizeFloat'])
+  })
+
+  it('raises a panel to the top when focused', () => {
+    const { controller } = expanded()
+    const first = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'text-preview' })
+    const second = controller.openContent({ contentId: 'dsh-resource://file/session/s/b.txt', title: 'b.txt', kind: 'text-preview' })
+    const firstFloat = controller.floatTab(first)
+    const secondFloat = controller.floatTab(second)
+    controller.focusPane(firstFloat)
+    expect(controller.getSnapshot().state.floats).toEqual([secondFloat, firstFloat])
+  })
+})
+
+describe('dividers', () => {
+  it('clamps a drag that would starve a pane', () => {
+    const { controller } = expanded()
+    controller.splitPane()
+    const splitId = getSplit(controller.getSnapshot().state, controller.getSnapshot().state.rootId).id
+    controller.resizeSplit(splitId, [0.01, 0.99])
+    const sizes = getSplit(controller.getSnapshot().state, splitId).sizes
+    expect(sizes[0]).toBeGreaterThan(0.05)
+    expect(sizes.reduce((sum, size) => sum + size, 0)).toBeCloseTo(1)
+  })
+})
+
+describe('notification', () => {
+  it('notifies subscribers and keeps the snapshot stable between changes', () => {
+    const controller = seededController()
+    let notifications = 0
+    const dispose = controller.subscribe(() => { notifications += 1 })
+    const before = controller.getSnapshot()
+    expect(controller.getSnapshot()).toBe(before)
+
+    controller.setExpanded(true)
+    expect(notifications).toBe(1)
+    expect(controller.getSnapshot()).not.toBe(before)
+
+    controller.setExpanded(true)
+    expect(notifications).toBe(1)
+
+    dispose()
+    controller.setExpanded(false)
+    expect(notifications).toBe(1)
+  })
+
+  it('steps one compound command as one entry, however many operations it recorded', () => {
+    expect(seededController().undo()).toBe(false)
+    const { controller } = expanded()
+    const before = controller.ops.length
+    controller.splitPane()
+    // The split and the seeded tab are two operations of one intent.
+    expect(controller.ops.length - before).toBe(2)
+    expect(controller.getSnapshot().canUndo).toBe(true)
+    expect(controller.undo()).toBe(true)
+    expect(dockPaneCount(controller.getSnapshot().state)).toBe(1)
+    expect(controller.redo()).toBe(true)
+    expect(dockPaneCount(controller.getSnapshot().state)).toBe(2)
+    expect(controller.redo()).toBe(false)
+  })
+})
diff --git a/packages/client/ui-dockkit/tests/fixtures.client.ts b/packages/client/ui-dockkit/tests/fixtures.client.ts
new file mode 100644
index 0000000000..a4c87a52e8
--- /dev/null
+++ b/packages/client/ui-dockkit/tests/fixtures.client.ts
@@ -0,0 +1,68 @@
+/**
+ * Shared spec fixtures. The kit has no notion of a guide or a preview tab, so
+ * the suites supply their own content families — exactly as an embedder does.
+ */
+import type { NodeId, PaneId, PaneNode, SplitId, SplitNode, TabId, TabRecord } from '../src/contract/types.ts'
+import { createIdMinter, createInitialState, DockController, type IdMinter } from '../src/index.ts'
+import type { DockLabels } from '../src/contract/adapter.ts'
+import type { LayoutState } from '../src/contract/types.ts'
+
+/** Consistency id of the seeded tab these suites use. */
+export const SEED_CONTENT_ID = 'seed:start'
+
+/** Title of the seeded tab. */
+export const SEED_TITLE = 'Start'
+
+/** The seeded tab an embedder would put in a fresh pane. */
+export function seedTab(id: TabId): TabRecord {
+  return { id, kind: 'seed', contentId: SEED_CONTENT_ID, title: SEED_TITLE }
+}
+
+/** A content tab addressed by a file URL, the shape the first embedder uses. */
+export function fileTab(id: TabId, contentId: string, title: string): TabRecord {
+  return { id, kind: 'file', contentId, title }
+}
+
+/** A controller seeded on both the initial pane and every pane a split creates. */
+export function seededController(): DockController {
+  return new DockController({ makeInitialTab: seedTab, makePaneTab: seedTab })
+}
+
+/** An initial state holding one seeded tab, plus the minter that produced it. */
+export function seededState(): { state: LayoutState; minter: IdMinter } {
+  const minter = createIdMinter()
+  return { state: createInitialState(minter, seedTab), minter }
+}
+
+/** Labels a spec can pass without caring what they say. */
+export const TEST_LABELS: DockLabels = {
+  emptyPane: 'empty pane',
+  splitPane: 'split right',
+  splitPaneDisabled: 'pane budget spent',
+  splitPaneNarrow: 'too narrow to split',
+  closeTab: 'close',
+  addTab: 'new tab',
+  dockFloat: 'dock',
+  closeFloat: 'close panel',
+}
+
+/** Brand a literal a spec spells out: an id the kit would have minted. */
+export const asPane = (id: string): PaneId => id as PaneId
+/** See {@link asPane}. */
+export const asSplit = (id: string): SplitId => id as SplitId
+/** See {@link asPane}. */
+export const asTab = (id: string): TabId => id as TabId
+
+/** The first tab of a pane the spec knows is not empty. */
+export function firstTab(pane: PaneNode): TabId {
+  const id = pane.tabs[0]
+  if (id === undefined) throw new Error(`fixture: pane ${pane.id} holds no tab`)
+  return id
+}
+
+/** A split's child at an index the spec knows exists. */
+export function childAt(split: SplitNode, index: number): NodeId {
+  const id = split.children[index]
+  if (id === undefined) throw new Error(`fixture: split ${split.id} has no child ${String(index)}`)
+  return id
+}
diff --git a/packages/client/ui-dockkit/tests/geometry.client.spec.ts b/packages/client/ui-dockkit/tests/geometry.client.spec.ts
new file mode 100644
index 0000000000..69f1e821b8
--- /dev/null
+++ b/packages/client/ui-dockkit/tests/geometry.client.spec.ts
@@ -0,0 +1,144 @@
+/**
+ * Drag geometry: point tests, dock-zone resolution against a real rectangle,
+ * tab-strip insertion slots, the drag threshold, and divider arithmetic.
+ */
+import { describe, expect, it } from 'vitest'
+import {
+  containsPoint, dividerSizes, DRAG_THRESHOLD, floatRectAt, insertionIndex, movedRect,
+  passedThreshold, resizedRect, zoneInRect,
+} from '../src/engine/geometry.ts'
+import type { PaneMeasure, Rect } from '../src/engine/geometry.ts'
+import { halvesFit, SPLIT_MINIMUMS } from '../src/engine/geometry.ts'
+import { FLOAT_DEFAULT_SIZE, FLOAT_MIN_SIZE } from '../src/index.ts'
+
+const PANE: Rect = { x: 100, y: 200, width: 400, height: 300 }
+
+describe('containsPoint', () => {
+  it('includes the edges and excludes anything outside', () => {
+    expect(containsPoint(PANE, 100, 200)).toBe(true)
+    expect(containsPoint(PANE, 500, 500)).toBe(true)
+    expect(containsPoint(PANE, 300, 350)).toBe(true)
+    expect(containsPoint(PANE, 99, 350)).toBe(false)
+    expect(containsPoint(PANE, 300, 501)).toBe(false)
+  })
+})
+
+describe('zoneInRect', () => {
+  it('reads the middle of a pane as its centre', () => {
+    expect(zoneInRect(PANE, 300, 350)).toBe('center')
+  })
+
+  it('reads each edge band as its own region', () => {
+    expect(zoneInRect(PANE, 110, 350)).toBe('left')
+    expect(zoneInRect(PANE, 490, 350)).toBe('right')
+    expect(zoneInRect(PANE, 300, 210)).toBe('top')
+    expect(zoneInRect(PANE, 300, 490)).toBe('bottom')
+  })
+
+  it('treats a collapsed rectangle as all centre', () => {
+    expect(zoneInRect({ x: 0, y: 0, width: 0, height: 0 }, 0, 0)).toBe('center')
+  })
+})
+
+describe('insertionIndex', () => {
+  const tabs: Rect[] = [
+    { x: 0, y: 0, width: 100, height: 30 },
+    { x: 100, y: 0, width: 100, height: 30 },
+    { x: 200, y: 0, width: 100, height: 30 },
+  ]
+
+  it('places before a tab while left of its midpoint', () => {
+    expect(insertionIndex(tabs, 10)).toBe(0)
+    expect(insertionIndex(tabs, 49)).toBe(0)
+  })
+
+  it('places after a tab once past its midpoint', () => {
+    expect(insertionIndex(tabs, 51)).toBe(1)
+    expect(insertionIndex(tabs, 151)).toBe(2)
+    expect(insertionIndex(tabs, 400)).toBe(3)
+  })
+
+  it('places at the start of an empty strip', () => {
+    expect(insertionIndex([], 400)).toBe(0)
+  })
+})
+
+describe('passedThreshold', () => {
+  it('ignores travel under the threshold on both axes', () => {
+    expect(passedThreshold(10, 10, 10, 10)).toBe(false)
+    expect(passedThreshold(10, 10, 10 + DRAG_THRESHOLD - 1, 10)).toBe(false)
+    expect(passedThreshold(10, 10, 10 + DRAG_THRESHOLD, 10)).toBe(true)
+    expect(passedThreshold(10, 10, 10, 10 - DRAG_THRESHOLD)).toBe(true)
+  })
+})
+
+describe('dividerSizes', () => {
+  it('moves the change between the two neighbours only', () => {
+    expect(dividerSizes([0.5, 0.5], 0, 0.1)).toEqual([0.6, 0.4])
+    expect(dividerSizes([0.25, 0.25, 0.5], 1, -0.05)).toEqual([0.25, 0.2, 0.55])
+  })
+
+  it('leaves the fractions alone at a boundary that has no pair', () => {
+    expect(dividerSizes([0.5, 0.5], 1, 0.1)).toEqual([0.5, 0.5])
+  })
+})
+
+describe('floating rectangles', () => {
+  const rect = { x: 100, y: 80, width: 300, height: 200 }
+
+  it('moves without changing the size', () => {
+    expect(movedRect(rect, 25, -15)).toEqual({ x: 125, y: 65, width: 300, height: 200 })
+  })
+
+  it('resizes from the origin and honours the minimum', () => {
+    expect(resizedRect(rect, 40, 30, FLOAT_MIN_SIZE))
+      .toEqual({ x: 100, y: 80, width: 340, height: 230 })
+    expect(resizedRect(rect, -1000, -1000, FLOAT_MIN_SIZE))
+      .toEqual({ x: 100, y: 80, ...FLOAT_MIN_SIZE })
+  })
+
+  it('places a new panel with its header under the drop point', () => {
+    const dropped = floatRectAt(400, 300, FLOAT_DEFAULT_SIZE)
+    expect(dropped.width).toBe(FLOAT_DEFAULT_SIZE.width)
+    expect(dropped.x).toBeLessThan(400)
+    expect(dropped.y).toBeLessThan(300)
+    expect(floatRectAt(5, 5, FLOAT_DEFAULT_SIZE)).toMatchObject({ x: 0, y: 0 })
+  })
+})
+
+describe('halvesFit — the room rule', () => {
+  /** A pane whose strip shows `fixed` px of controls and one chip box of 60px; the fill takes the rest. */
+  const measure = (width: number, height: number, fixed: number): PaneMeasure => {
+    const strip = { x: 1, y: 1, width: width - 2, height: 36 }
+    return { pane: { x: 0, y: 0, width, height }, strip, chipsWidth: 60, fillWidth: Math.max(0, strip.width - 60 - fixed) }
+  }
+
+  it('lets an unmeasured pane split: the rule only blocks on a positive reading', () => {
+    expect(halvesFit(measure(0, 0, 104))).toEqual({ row: true, column: true })
+  })
+
+  it('needs each half to hold the strip\'s fixed controls plus one minimum chip', () => {
+    // 420px: halves of 206px inside the borders, against 104 + 59.
+    expect(halvesFit(measure(420, 600, 104)).row).toBe(true)
+    // 208px: halves of 100px, short of 163.
+    expect(halvesFit(measure(208, 600, 104)).row).toBe(false)
+    // The boundary is inclusive: 2 * (163 + 2 borders) + 4 divider = 334.
+    expect(halvesFit(measure(334, 600, 104)).row).toBe(true)
+    expect(halvesFit(measure(333, 600, 104)).row).toBe(false)
+    // A strip with fewer controls needs less.
+    expect(halvesFit(measure(208, 600, 44)).row).toBe(false)
+    expect(halvesFit(measure(214, 600, 44)).row).toBe(true)
+  })
+
+  it('needs each half to hold the strip plus a minimum body for a column split', () => {
+    // Halves of (h - 4) / 2 - 2 against 36 + 48 = 84.
+    expect(halvesFit(measure(420, 176, 104)).column).toBe(true)
+    expect(halvesFit(measure(420, 175, 104)).column).toBe(false)
+  })
+
+  it('takes the minimums it is given, and the stylesheet\'s by default', () => {
+    expect(SPLIT_MINIMUMS).toEqual({ divider: 4, chip: 59, body: 48 })
+    expect(halvesFit(measure(208, 600, 104), { divider: 0, chip: 0, body: 0 }).row).toBe(false)
+    expect(halvesFit(measure(220, 600, 104), { divider: 0, chip: 0, body: 0 }).row).toBe(true)
+  })
+})
diff --git a/packages/client/ui-dockkit/tests/measure.client.spec.ts b/packages/client/ui-dockkit/tests/measure.client.spec.ts
new file mode 100644
index 0000000000..52f30d3237
--- /dev/null
+++ b/packages/client/ui-dockkit/tests/measure.client.spec.ts
@@ -0,0 +1,122 @@
+// @vitest-environment jsdom
+/**
+ * The DOM side of the room rule, over a hand-built pane tree: which rectangles
+ * and computed styles feed `halvesFit`, and what an unmeasured pane reads as.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { fitOf, measurePaneFits, paneElements, sameFits } from '../src/components/measure.ts'
+import type { HalvesFit, Rect } from '../src/engine/geometry.ts'
+import { asPane } from './fixtures.client.ts'
+
+/** Give one element a fixed rectangle, as a browser's layout would. */
+function lay(element: HTMLElement, rect: Rect): void {
+  element.getBoundingClientRect = (): DOMRect => ({
+    ...rect, top: rect.y, left: rect.x, right: rect.x + rect.width, bottom: rect.y + rect.height, toJSON: () => ({}),
+  })
+}
+
+/** A pane element with the parts the measurement reads; `width` is the pane's, `fixed` the strip's controls. */
+function pane(id: string, width: number, fixed = 104): HTMLElement {
+  const element = document.createElement('section')
+  element.dataset.dockkitPane = id
+  lay(element, { x: 0, y: 0, width, height: 600 })
+  const strip = document.createElement('div')
+  strip.dataset.dockkitStrip = id
+  lay(strip, { x: 1, y: 1, width: width - 2, height: 36 })
+  const chips = document.createElement('div')
+  chips.dataset.dockkitStripTabs = id
+  lay(chips, { x: 1, y: 1, width: 60, height: 34 })
+  const fill = document.createElement('div')
+  fill.dataset.dockkitStripFill = ''
+  lay(fill, { x: 61, y: 1, width: Math.max(0, width - 2 - 60 - fixed), height: 34 })
+  strip.append(chips, fill)
+  element.append(strip)
+  return element
+}
+
+/** A chip with the given inline box styles, appended to `strip`'s chip box. */
+function chip(host: HTMLElement, style: Partial<CSSStyleDeclaration>): HTMLElement {
+  const element = document.createElement('div')
+  element.dataset.dockkitTab = 't'
+  Object.assign(element.style, style)
+  host.querySelector('[data-dockkit-strip-tabs]')?.append(element)
+  return element
+}
+
+/** A surface root in the document, so computed styles resolve. */
+function surface(): HTMLElement {
+  const root = document.createElement('div')
+  document.body.append(root)
+  return root
+}
+
+afterEach(() => { document.body.replaceChildren() })
+
+describe('measurePaneFits', () => {
+  it('keys every pane by the id it carries, and reads an unlaid pane as fitting', () => {
+    const root = surface()
+    const bare = document.createElement('section')
+    bare.dataset.dockkitPane = 'bare'
+    root.append(pane('wide', 420), bare)
+    expect(paneElements(root).map(([id]) => id)).toEqual(['wide', 'bare'])
+    const fits = measurePaneFits(root)
+    expect(fits.get(asPane('wide'))).toEqual({ row: true, column: true })
+    expect(fits.get(asPane('bare'))).toEqual({ row: true, column: true })
+  })
+
+  // 308px: halves of 150px inside the borders, against 104px of controls plus one chip.
+  it('reads the chip minimum from a rendered chip\'s computed style, padding included for a content box', () => {
+    const root = surface()
+    const narrow = pane('p', 308)
+    root.append(narrow)
+    // No chip rendered: the stylesheet's 59px, so 163 > 150.
+    expect(measurePaneFits(root).get(asPane('p'))?.row).toBe(false)
+    // 44px of content plus 4px + 4px of padding is 52: 156 > 150.
+    const rendered = chip(narrow, { minWidth: '44px', paddingLeft: '4px', paddingRight: '4px', boxSizing: 'content-box' })
+    expect(measurePaneFits(root).get(asPane('p'))?.row).toBe(false)
+    // The same declaration as a border box is the whole footprint: 148 fits.
+    rendered.style.boxSizing = 'border-box'
+    expect(measurePaneFits(root).get(asPane('p'))?.row).toBe(true)
+    // Unstyled or zero minimum: back to the stylesheet's figure.
+    rendered.style.minWidth = '0px'
+    expect(measurePaneFits(root).get(asPane('p'))?.row).toBe(false)
+    rendered.style.minWidth = ''
+    expect(measurePaneFits(root).get(asPane('p'))?.row).toBe(false)
+  })
+
+  // 336px: halves of 164px against 163 with the stylesheet's 4px divider, 162 with an 8px one.
+  it('reads the divider\'s thickness from a rendered divider, and the stylesheet\'s before one exists', () => {
+    const root = surface()
+    root.append(pane('p', 336))
+    expect(measurePaneFits(root).get(asPane('p'))?.row).toBe(true)
+    const divider = document.createElement('div')
+    divider.dataset.dockkitDivider = 's:0'
+    root.append(divider)
+    lay(divider, { x: 0, y: 0, width: 8, height: 600 })
+    expect(measurePaneFits(root).get(asPane('p'))?.row).toBe(false)
+    // A divider without layout yet falls back too.
+    lay(divider, { x: 0, y: 0, width: 0, height: 0 })
+    expect(measurePaneFits(root).get(asPane('p'))?.row).toBe(true)
+  })
+})
+
+describe('fitOf', () => {
+  it('answers from the map, and takes an unmeasured pane to fit', () => {
+    const blocked: HalvesFit = { row: false, column: true }
+    const fits = new Map([[asPane('p'), blocked]])
+    expect(fitOf(fits, asPane('p'))).toBe(blocked)
+    expect(fitOf(fits, asPane('q'))).toEqual({ row: true, column: true })
+  })
+})
+
+describe('sameFits', () => {
+  const fit: HalvesFit = { row: true, column: false }
+
+  it('agrees only when both name the same panes with the same readings', () => {
+    expect(sameFits(new Map([[asPane('a'), fit]]), new Map([[asPane('a'), { ...fit }]]))).toBe(true)
+    expect(sameFits(new Map([[asPane('a'), fit]]), new Map())).toBe(false)
+    expect(sameFits(new Map([[asPane('a'), fit]]), new Map([[asPane('b'), fit]]))).toBe(false)
+    expect(sameFits(new Map([[asPane('a'), fit]]), new Map([[asPane('a'), { row: false, column: false }]]))).toBe(false)
+    expect(sameFits(new Map([[asPane('a'), fit]]), new Map([[asPane('a'), { row: true, column: true }]]))).toBe(false)
+  })
+})
diff --git a/packages/client/ui-dockkit/tests/planner.client.spec.ts b/packages/client/ui-dockkit/tests/planner.client.spec.ts
new file mode 100644
index 0000000000..16d7fcb339
--- /dev/null
+++ b/packages/client/ui-dockkit/tests/planner.client.spec.ts
@@ -0,0 +1,385 @@
+/**
+ * The two properties the intent layer must not lose in refactoring.
+ *
+ * Determinism: a planner reads only the state and the minter it is handed, so the
+ * same inputs plan the same operations and replay stays exact. Nothing here may
+ * reach a clock or a random source.
+ *
+ * One undo behaviour: focus-run merging and redo-branch discarding live in the
+ * pure history functions, so the stateful `Sequencer` embedding and an embedder
+ * driving `record`/`stepBack` directly cannot drift apart.
+ */
+import { describe, expect, it } from 'vitest'
+import { applyOp } from '../src/engine/operations.ts'
+import { DockController } from '../src/engine/controller.ts'
+import { createIdMinter, createInitialState } from '../src/engine/initial.ts'
+import {
+  activeDockPaneId, findContentTab, findPaneContentTab, planDropTab, planDuplicateTab, planFloatTab, planOpenContent,
+  planPlaceTab, planSetExpanded, planSetMode, planSettle, planSplitPane, planUnfloatPane, planAddTab,
+} from '../src/engine/planner.ts'
+import {
+  EMPTY_HISTORY, record, recordedOps, stepBack, stepForward, type History,
+} from '../src/engine/sequence.ts'
+import { dockPaneIds, findTabPane, getPane, getSplit } from '../src/engine/tree.ts'
+import type { LayoutOp, LayoutState, PaneId, TabId } from '../src/contract/types.ts'
+import type { Mint } from '../src/engine/planner.ts'
+import { asTab, fileTab, firstTab, seedTab, seededState } from './fixtures.client.ts'
+
+/** A deep snapshot, for proving a planner left its input alone. */
+function frozen(state: LayoutState): string {
+  return JSON.stringify(state)
+}
+
+/** Apply a plan the way any embedder does, and return the resulting state. */
+function applyAll(state: LayoutState, ops: readonly LayoutOp[]): LayoutState {
+  return ops.reduce((current, op) => applyOp(current, op).state, state)
+}
+
+describe('planner determinism', () => {
+  it('plans the same operations from the same state and a fresh minter', () => {
+    const first = seededState()
+    const second = seededState()
+    const planOne = planSplitPane(first.state, first.minter.next, undefined, seedTab)
+    const planTwo = planSplitPane(second.state, second.minter.next, undefined, seedTab)
+    expect(planOne).toEqual(planTwo)
+    expect(planOne.length).toBeGreaterThan(0)
+  })
+
+  it('leaves the state it was handed untouched', () => {
+    const { state, minter } = seededState()
+    const before = frozen(state)
+    const mint = minter.next
+
+    planSetExpanded(state, true)
+    planSplitPane(state, mint, undefined, seedTab)
+    planOpenContent(state, mint, { contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file' })
+    planFloatTab(state, mint, firstTab(getPane(state, state.rootId)))
+    expect(frozen(state)).toBe(before)
+  })
+
+  it('plans nothing for an intent that changes nothing', () => {
+    const { state, minter } = seededState()
+    const mint = minter.next
+    const tabId = getPane(state, state.rootId).tabs[0]
+    if (tabId === undefined) throw new Error('fixture: seeded tab missing')
+
+    // Already collapsed; already in that mode; already in that slot; centre
+    // release on its own pane.
+    expect(planSetExpanded(state, false)).toEqual([])
+    expect(planSetMode(state, 'push')).toEqual([])
+    expect(planSetMode(state, 'fullscreen')).toEqual([{ type: 'setMode', mode: 'fullscreen' }])
+    expect(planPlaceTab(state, tabId, getPane(state, state.rootId).id, 0)).toEqual([])
+    expect(planDropTab(state, mint, tabId, getPane(state, state.rootId).id, 'center')).toEqual([])
+  })
+
+  it('refuses to plan past the pane budget', () => {
+    const seeded = seededState()
+    let { state } = seeded
+    const { minter } = seeded
+    const mint = minter.next
+    for (let index = 0; index < 3; index += 1) {
+      state = applyAll(state, planSplitPane(state, mint, state.activePaneId, seedTab))
+    }
+    expect(planSplitPane(state, mint, state.activePaneId, seedTab)).toEqual([])
+    // The root is a split once panes exist, so address a real pane.
+    const firstPane = dockPaneIds(state)[0]
+    if (firstPane === undefined) throw new Error('fixture: no docked pane')
+    const tabId = getPane(state, firstPane).tabs[0]
+    if (tabId === undefined) throw new Error('fixture: seeded tab missing')
+    expect(planDropTab(state, mint, tabId, firstPane, 'right')).toEqual([])
+  })
+})
+
+describe('planPlaceTab', () => {
+  /** One docked pane holding three tabs, in strip order. */
+  function threeTabs(): { state: LayoutState; paneId: PaneId; tabs: readonly [TabId, TabId, TabId] } {
+    const { state, minter } = seededState()
+    const mint = minter.next
+    const paneId = getPane(state, state.rootId).id
+    const b = planOpenContent(state, mint, { contentId: 'dsh-resource://file/session/s/b.txt', title: 'b', kind: 'file' })
+    const withB = applyAll(state, b.ops)
+    const c = planOpenContent(withB, mint, { contentId: 'dsh-resource://file/session/s/c.txt', title: 'c', kind: 'file' })
+    const withC = applyAll(withB, c.ops)
+    const a = getPane(withC, paneId).tabs[0]
+    if (a === undefined) throw new Error('fixture: seeded tab missing')
+    return { state: withC, paneId, tabs: [a, b.tabId, c.tabId] }
+  }
+
+  /** Strip order after placing `tabId` at caret slot `index` in its own pane. */
+  function after(tabId: TabId, index: number): readonly TabId[] {
+    const { state, paneId } = threeTabs()
+    return getPane(applyAll(state, planPlaceTab(state, tabId, paneId, index)), paneId).tabs
+  }
+
+  it('reads the slot as the caret over the strip as drawn, the dragged chip included', () => {
+    const { tabs: [a, b, c] } = threeTabs()
+    // Rightward: the caret between b and c is slot 2, and a lands between them.
+    expect(after(a, 2)).toEqual([b, a, c])
+    expect(after(a, 3)).toEqual([b, c, a])
+    // Leftward: the chip sits after the caret, so the slot is the final index.
+    expect(after(c, 0)).toEqual([c, a, b])
+    expect(after(c, 1)).toEqual([a, c, b])
+  })
+
+  it('plans nothing for the slot on either side of the dragged chip', () => {
+    const { state, paneId, tabs: [a, b, c] } = threeTabs()
+    expect(planPlaceTab(state, a, paneId, 0)).toEqual([])
+    expect(planPlaceTab(state, a, paneId, 1)).toEqual([])
+    expect(planPlaceTab(state, b, paneId, 1)).toEqual([])
+    expect(planPlaceTab(state, b, paneId, 2)).toEqual([])
+    expect(planPlaceTab(state, c, paneId, 2)).toEqual([])
+    expect(planPlaceTab(state, c, paneId, 3)).toEqual([])
+  })
+})
+
+describe('planDropTab on the tab\'s own pane', () => {
+  it('plans nothing for a pane\'s only tab released on any of its own edges', () => {
+    const { state, minter } = seededState()
+    const mint = minter.next
+    const tabId = getPane(state, state.rootId).tabs[0]
+    if (tabId === undefined) throw new Error('fixture: seeded tab missing')
+    for (const zone of ['left', 'right', 'top', 'bottom'] as const) {
+      expect(planDropTab(state, mint, tabId, getPane(state, state.rootId).id, zone)).toEqual([])
+    }
+  })
+
+  it('splits the pane when it keeps another tab', () => {
+    const { state, minter } = seededState()
+    const mint = minter.next
+    const opened = planOpenContent(state, mint, { contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file' })
+    const two = applyAll(state, opened.ops)
+    const ops = planDropTab(two, mint, opened.tabId, getPane(two, two.rootId).id, 'right')
+    expect(ops.map(op => op.type)).toEqual(['split', 'moveTab'])
+    const split = applyAll(two, ops)
+    expect(dockPaneIds(split)).toHaveLength(2)
+    expect(getPane(split, two.rootId).tabs).toHaveLength(1)
+  })
+})
+
+describe('floating panes as planner arguments', () => {
+  /** A docked pane holding the seed, plus one content tab floated out of it. */
+  function withFloat(): { state: LayoutState; mint: Mint; floatId: PaneId; tabId: TabId } {
+    const { state, minter } = seededState()
+    const mint = minter.next
+    const opened = planOpenContent(state, mint, { contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file' })
+    const docked = applyAll(state, opened.ops)
+    const floated = planFloatTab(docked, mint, opened.tabId)
+    return { state: applyAll(docked, floated.ops), mint, floatId: floated.paneId, tabId: opened.tabId }
+  }
+
+  it('plans nothing into a floating pane: no split, no seeded tab, no drop', () => {
+    const { state, mint, floatId } = withFloat()
+    expect(planSplitPane(state, mint, floatId, seedTab)).toEqual([])
+    expect(planAddTab(state, mint, floatId, seedTab)).toEqual([])
+    const seeded = getPane(state, state.rootId).tabs[0]
+    if (seeded === undefined) throw new Error('fixture: seeded tab missing')
+    expect(planDropTab(state, mint, seeded, floatId, 'center')).toEqual([])
+  })
+
+  it('copies a floating tab into the active docked pane, at its end', () => {
+    const { state, mint, tabId } = withFloat()
+    expect(state.activePaneId).not.toBe(state.rootId)
+    expect(activeDockPaneId(state)).toBe(state.rootId)
+    const copy = planDuplicateTab(state, mint, tabId)
+    expect(copy.ops[0]).toMatchObject({ type: 'openTab', paneId: state.rootId, index: 1 })
+    expect(getPane(applyAll(state, copy.ops), state.rootId).tabs.at(-1)).toBe(copy.tabId)
+  })
+})
+
+describe('planSettle', () => {
+  /** Two seeded docked panes side by side. */
+  function twoPanes(): { state: LayoutState; mint: Mint; left: PaneId; right: PaneId } {
+    const { state, minter } = seededState()
+    const mint = minter.next
+    const split = applyAll(state, planSplitPane(state, mint, undefined, seedTab))
+    const [left, right] = dockPaneIds(split)
+    if (left === undefined || right === undefined) throw new Error('fixture: expected two panes')
+    return { state: split, mint, left, right }
+  }
+
+  it('plans nothing while every docked pane holds a tab', () => {
+    const { state, mint } = twoPanes()
+    expect(planSettle(state, mint, seedTab)).toEqual([])
+  })
+
+  it('merges away each pane an intent emptied, one after another', () => {
+    const { state, mint, left, right } = twoPanes()
+    const third = applyAll(state, planSplitPane(state, mint, right, seedTab))
+    const emptied = dockPaneIds(third).flatMap(id => getPane(third, id).tabs)
+      .filter(tabId => findTabPane(third, tabId).id !== left)
+      .reduce((current, tabId) => applyAll(current, [{ type: 'closeTab', tabId }]), third)
+    const ops = planSettle(emptied, mint, seedTab)
+    expect(ops.map(op => op.type)).toEqual(['merge', 'merge'])
+    expect(dockPaneIds(applyAll(emptied, ops))).toEqual([left])
+  })
+
+  it('reseeds an emptied root pane through the factory, and leaves it empty without one', () => {
+    const { state, minter } = seededState()
+    const mint = minter.next
+    const tabId = getPane(state, state.rootId).tabs[0]
+    if (tabId === undefined) throw new Error('fixture: seeded tab missing')
+    const emptied = applyAll(state, [{ type: 'closeTab', tabId }])
+    const reseeded = planSettle(emptied, mint, seedTab)
+    expect(reseeded.map(op => op.type)).toEqual(['openTab'])
+    expect(getPane(applyAll(emptied, reseeded), emptied.rootId).tabs).toHaveLength(1)
+    expect(planSettle(emptied, mint)).toEqual([])
+  })
+})
+
+describe('planOpenContent placement and identity', () => {
+  it('identifies content by (kind, contentId): the same address under another kind opens another tab', () => {
+    const { state, minter } = seededState()
+    const mint = minter.next
+    const first = planOpenContent(state, mint, { contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file' })
+    const opened = applyAll(state, first.ops)
+    expect(findContentTab(opened, 'dsh-resource://file/session/s/a.txt')).toBe(first.tabId)
+    expect(findContentTab(opened, 'dsh-resource://file/session/s/a.txt', 'file')).toBe(first.tabId)
+    expect(findContentTab(opened, 'dsh-resource://file/session/s/a.txt', 'hex')).toBeUndefined()
+    // The pane-level lookup answers for one pane only.
+    const [pane] = dockPaneIds(opened)
+    if (pane === undefined) throw new Error('expected a docked pane')
+    expect(findPaneContentTab(opened, pane, 'dsh-resource://file/session/s/a.txt')).toBe(first.tabId)
+    expect(findPaneContentTab(opened, pane, 'dsh-resource://file/session/s/a.txt', 'hex')).toBeUndefined()
+    expect(findPaneContentTab(opened, pane, 'dsh-resource://file/session/s/nowhere.txt')).toBeUndefined()
+    const again = planOpenContent(opened, mint, { contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file' })
+    expect(again.ops.map(op => op.type)).toEqual(['focusTab'])
+    const other = planOpenContent(opened, mint, { contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'hex' })
+    expect(other.ops.map(op => op.type)).toEqual(['openTab'])
+  })
+
+  it('opens another tab when told not to reveal the existing one', () => {
+    const { state, minter } = seededState()
+    const mint = minter.next
+    const opened = applyAll(state, planOpenContent(state, mint, { contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file' }).ops)
+    const copy = planOpenContent(opened, mint, { contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file', revealIfOpened: false })
+    expect(copy.ops.map(op => op.type)).toEqual(['openTab'])
+    const both = applyAll(opened, copy.ops)
+    expect(Object.values(both.tabs).filter(tab => tab.contentId === 'dsh-resource://file/session/s/a.txt')).toHaveLength(2)
+  })
+
+  it('seats a new tab at an explicit strip slot', () => {
+    const { state, minter } = seededState()
+    const mint = minter.next
+    const paneId = getPane(state, state.rootId).id
+    const planned = planOpenContent(state, mint, { contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file', paneId, index: 0 })
+    expect(planned.ops[0]).toMatchObject({ type: 'openTab', paneId, index: 0 })
+    expect(getPane(applyAll(state, planned.ops), paneId).tabs[0]).toBe(planned.tabId)
+  })
+})
+
+describe('planAddTab', () => {
+  it('seats the factory\'s tab at the end of the pane, and plans nothing without a factory', () => {
+    const { state, minter } = seededState()
+    const mint = minter.next
+    const paneId = getPane(state, state.rootId).id
+    const ops = planAddTab(state, mint, paneId, seedTab)
+    expect(ops.map(op => op.type)).toEqual(['openTab'])
+    expect(ops[0]).toMatchObject({ paneId, index: getPane(state, paneId).tabs.length })
+    expect(planAddTab(state, mint, paneId)).toEqual([])
+  })
+})
+
+describe('one undo behaviour across both embeddings', () => {
+  /** Drive a script of intents through the pure history functions. */
+  function driveByHand(): { history: History; state: LayoutState } {
+    const minter = createIdMinter()
+    const mint = minter.next
+    let state = createInitialState(minter, seedTab)
+    let history = EMPTY_HISTORY
+    const run = (ops: readonly LayoutOp[]): void => {
+      const stepped = record(history, state, ops)
+      history = stepped.history
+      state = stepped.state
+    }
+    run(planSetExpanded(state, true))
+    run(planSplitPane(state, mint, undefined, seedTab))
+    const opened = planOpenContent(state, mint, { contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file' })
+    run(opened.ops)
+    const copy = planDuplicateTab(state, mint, opened.tabId)
+    run(copy.ops)
+    run([{ type: 'focusTab', tabId: opened.tabId }])
+    run([{ type: 'focusTab', tabId: copy.tabId }])
+    run([{ type: 'focusTab', tabId: opened.tabId }])
+    return { history, state }
+  }
+
+  /** The same script through the stateful embedding. */
+  function driveByController(): DockController {
+    const controller = new DockController({ makeInitialTab: seedTab, makePaneTab: seedTab })
+    controller.setExpanded(true)
+    controller.splitPane()
+    const opened = controller.openContent({ contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file' })
+    const copy = controller.duplicateTab(opened)
+    controller.focusTab(opened)
+    controller.focusTab(copy)
+    controller.focusTab(opened)
+    return controller
+  }
+
+  it('records the same sequence either way', () => {
+    const byHand = driveByHand()
+    const controller = driveByController()
+    expect(recordedOps(byHand.history)).toEqual(controller.ops)
+    expect(byHand.state).toEqual(controller.getSnapshot().state)
+  })
+
+  it('merges a focus run into one step in both embeddings', () => {
+    const byHand = driveByHand()
+    const controller = driveByController()
+
+    const stepped = stepBack(byHand.history, byHand.state)
+    if (stepped === undefined) throw new Error('expected a step back')
+    expect(controller.undo()).toBe(true)
+    // Three consecutive focus moves collapse to one step on both paths.
+    expect(byHand.history.cursor - stepped.history.cursor).toBe(3)
+    expect(stepped.history.cursor).toBe(controller.getSnapshot().cursor)
+    expect(stepped.state).toEqual(controller.getSnapshot().state)
+
+    const forward = stepForward(stepped.history, stepped.state)
+    if (forward === undefined) throw new Error('expected a step forward')
+    expect(controller.redo()).toBe(true)
+    expect(forward.history.cursor).toBe(controller.getSnapshot().cursor)
+    expect(forward.state).toEqual(controller.getSnapshot().state)
+  })
+
+  it('discards the redo branch on both paths when a new operation lands', () => {
+    const byHand = driveByHand()
+    const controller = driveByController()
+    const stepped = stepBack(byHand.history, byHand.state)
+    if (stepped === undefined) throw new Error('expected a step back')
+    expect(controller.undo()).toBe(true)
+
+    const reopened = record(stepped.history, stepped.state, [{ type: 'setExpanded', expanded: false }])
+    controller.setExpanded(false)
+    expect(recordedOps(reopened.history)).toEqual(controller.ops)
+    expect(stepForward(reopened.history, reopened.state)).toBeUndefined()
+    expect(controller.getSnapshot().canRedo).toBe(false)
+  })
+})
+
+describe('planned intents survive replay', () => {
+  it('rebuilds the same tree from the operations a planner produced', () => {
+    const { state, minter } = seededState()
+    const mint = minter.next
+    const ops: LayoutOp[] = []
+    let current = state
+
+    const push = (planned: readonly LayoutOp[]): void => {
+      ops.push(...planned)
+      current = applyAll(current, planned)
+    }
+    push(planSetExpanded(current, true))
+    push(planSplitPane(current, mint, undefined, seedTab))
+    const opened = planOpenContent(current, mint, { contentId: 'dsh-resource://file/session/s/a.txt', title: 'a.txt', kind: 'file' })
+    push(opened.ops)
+    const second = getSplit(current, current.rootId).children[1]
+    if (second === undefined) throw new Error('expected a second pane')
+    push(planPlaceTab(current, opened.tabId, getPane(current, second).id, 0))
+    const floated = planFloatTab(current, mint, opened.tabId)
+    push(floated.ops)
+    push(planUnfloatPane(current, floated.paneId))
+
+    expect(applyAll(state, ops)).toEqual(current)
+    expect(fileTab(asTab('t'), 'dsh-resource://file/session/s/a.txt', 'a.txt').kind).toBe('file')
+  })
+})
diff --git a/packages/client/ui-dockkit/tests/sequence.client.spec.ts b/packages/client/ui-dockkit/tests/sequence.client.spec.ts
new file mode 100644
index 0000000000..76449d2069
--- /dev/null
+++ b/packages/client/ui-dockkit/tests/sequence.client.spec.ts
@@ -0,0 +1,203 @@
+/**
+ * Sequence behavior: linear history, exact inverses, the focus-run undo step, and
+ * the redo branch a new operation discards.
+ */
+import { describe, expect, it } from 'vitest'
+import { replay } from '../src/engine/operations.ts'
+import { createIdMinter, createInitialState } from '../src/engine/initial.ts'
+import { asPane, asTab, fileTab, seedTab } from './fixtures.client.ts'
+import { EMPTY_HISTORY, isFocusOp, record, Sequencer } from '../src/engine/sequence.ts'
+import { dockPaneIds, getPane, getSplit } from '../src/engine/tree.ts'
+import type { LayoutState, PaneId, TabId } from '../src/contract/types.ts'
+
+interface Fixture {
+  readonly initial: LayoutState
+  readonly sequencer: Sequencer
+  readonly minter: ReturnType<typeof createIdMinter>
+  readonly paneId: PaneId
+  readonly guideTabId: TabId
+}
+
+function fixture(): Fixture {
+  const minter = createIdMinter()
+  const initial = createInitialState(minter, seedTab)
+  const guideTabId = getPane(initial, initial.rootId).tabs[0]
+  if (guideTabId === undefined) throw new Error('fixture: initial pane has no guide tab')
+  return { initial, sequencer: new Sequencer(initial), minter, paneId: getPane(initial, initial.rootId).id, guideTabId }
+}
+
+describe('isFocusOp', () => {
+  it('names the operations that only move focus', () => {
+    expect(isFocusOp({ type: 'focusPane', paneId: asPane('p') })).toBe(true)
+    expect(isFocusOp({ type: 'focusTab', tabId: asTab('t') })).toBe(true)
+    expect(isFocusOp({ type: 'restoreFocus', activePaneId: asPane('p'), floats: [], paneActiveTabs: {} })).toBe(true)
+    expect(isFocusOp({ type: 'setExpanded', expanded: true })).toBe(false)
+  })
+})
+
+describe('recording', () => {
+  it('starts with nothing to step through', () => {
+    const { sequencer, initial } = fixture()
+    expect(sequencer.state).toBe(initial)
+    expect(sequencer.canUndo).toBe(false)
+    expect(sequencer.canRedo).toBe(false)
+    expect(sequencer.undo()).toBe(false)
+    expect(sequencer.redo()).toBe(false)
+  })
+
+  it('records every operation, focus moves included', () => {
+    const { sequencer, minter, paneId, guideTabId } = fixture()
+    const tab = fileTab(minter.next('tab'), 'dsh-resource://file/session/s/a.txt', 'a.txt')
+    sequencer.dispatch({ type: 'openTab', paneId, tab, index: 1 })
+    sequencer.dispatch({ type: 'focusTab', tabId: guideTabId })
+    sequencer.dispatch({ type: 'focusTab', tabId: tab.id })
+    expect(sequencer.ops.map(op => op.type)).toEqual(['openTab', 'focusTab', 'focusTab'])
+    expect(sequencer.cursor).toBe(3)
+  })
+
+  it('exposes the recorded sequence as plain history, and records nothing for an empty intent', () => {
+    const { sequencer, initial, paneId } = fixture()
+    expect(sequencer.history).toBe(EMPTY_HISTORY)
+    sequencer.dispatch({ type: 'focusPane', paneId })
+    expect(sequencer.history.entries).toHaveLength(1)
+    expect(sequencer.history.cursor).toBe(1)
+    const unchanged = record(EMPTY_HISTORY, initial, [])
+    expect(unchanged.history).toBe(EMPTY_HISTORY)
+    expect(unchanged.state).toBe(initial)
+    expect(sequencer.dispatchAll([])).toBe(sequencer.state)
+    expect(sequencer.history.entries).toHaveLength(1)
+  })
+
+  it('leaves the sequence untouched when an operation is invalid', () => {
+    const { sequencer } = fixture()
+    expect(() => sequencer.dispatch({ type: 'focusPane', paneId: asPane('nope') })).toThrow(/unknown node/)
+    expect(sequencer.ops).toHaveLength(0)
+    expect(sequencer.canUndo).toBe(false)
+  })
+})
+
+describe('stepping back and forward', () => {
+  it('returns to the exact previous state', () => {
+    const { sequencer, initial, minter, paneId } = fixture()
+    const newPaneId = minter.next('pane')
+    sequencer.dispatch({
+      type: 'split', paneId, axis: 'row', direction: 'after', newPaneId, newSplitId: minter.next('split'),
+    })
+    expect(dockPaneIds(sequencer.state)).toHaveLength(2)
+    expect(sequencer.undo()).toBe(true)
+    expect(sequencer.state).toEqual(initial)
+    expect(sequencer.canUndo).toBe(false)
+    expect(sequencer.canRedo).toBe(true)
+    expect(sequencer.redo()).toBe(true)
+    expect(dockPaneIds(sequencer.state)).toHaveLength(2)
+  })
+
+  it('collapses a run of consecutive focus moves into one step', () => {
+    const { sequencer, minter, paneId, guideTabId } = fixture()
+    const tab = fileTab(minter.next('tab'), 'dsh-resource://file/session/s/a.txt', 'a.txt')
+    sequencer.dispatch({ type: 'openTab', paneId, tab, index: 1 })
+    const afterOpen = sequencer.state
+    sequencer.dispatch({ type: 'focusTab', tabId: guideTabId })
+    sequencer.dispatch({ type: 'focusTab', tabId: tab.id })
+    sequencer.dispatch({ type: 'focusTab', tabId: guideTabId })
+    expect(sequencer.cursor).toBe(4)
+
+    expect(sequencer.undo()).toBe(true)
+    expect(sequencer.cursor).toBe(1)
+    expect(sequencer.state).toEqual(afterOpen)
+
+    expect(sequencer.redo()).toBe(true)
+    expect(sequencer.cursor).toBe(4)
+    expect(getPane(sequencer.state, paneId).activeTabId).toBe(guideTabId)
+  })
+
+  it('steps one structural operation even when focus moves precede it', () => {
+    const { sequencer, paneId, guideTabId } = fixture()
+    sequencer.dispatch({ type: 'focusPane', paneId })
+    sequencer.dispatch({ type: 'focusTab', tabId: guideTabId })
+    sequencer.dispatch({ type: 'setExpanded', expanded: true })
+    expect(sequencer.undo()).toBe(true)
+    expect(sequencer.cursor).toBe(2)
+    expect(sequencer.state.expanded).toBe(false)
+    expect(sequencer.undo()).toBe(true)
+    expect(sequencer.cursor).toBe(0)
+  })
+
+  it('undoes a whole session back to the initial state', () => {
+    const { sequencer, initial, minter, paneId, guideTabId } = fixture()
+    const newPaneId = minter.next('pane')
+    const floatId = minter.next('float')
+    sequencer.dispatch({ type: 'setExpanded', expanded: true })
+    sequencer.dispatch({
+      type: 'split', paneId, axis: 'row', direction: 'after', newPaneId, newSplitId: minter.next('split'),
+    })
+    sequencer.dispatch({ type: 'moveTab', tabId: guideTabId, toPaneId: newPaneId, index: 0 })
+    sequencer.dispatch({
+      type: 'float', tabId: guideTabId, newPaneId: floatId, rect: { x: 5, y: 6, width: 200, height: 100 },
+    })
+    sequencer.dispatch({ type: 'moveFloat', paneId: floatId, x: 50, y: 60 })
+    while (sequencer.undo()) { /* step back to the beginning */ }
+    expect(sequencer.state).toEqual(initial)
+    expect(sequencer.cursor).toBe(0)
+  })
+})
+
+describe('a floating panel\'s drag as one step', () => {
+  it('raises and focuses the panel with the move, and steps both back and forward together', () => {
+    const { sequencer, minter, paneId, guideTabId } = fixture()
+    const tab = fileTab(minter.next('tab'), 'dsh-resource://file/session/s/a.txt', 'a.txt')
+    const lower = minter.next('float')
+    const upper = minter.next('float')
+    sequencer.dispatch({ type: 'openTab', paneId, tab, index: 1 })
+    sequencer.dispatch({ type: 'float', tabId: guideTabId, newPaneId: lower, rect: { x: 0, y: 0, width: 200, height: 100 } })
+    sequencer.dispatch({ type: 'float', tabId: tab.id, newPaneId: upper, rect: { x: 20, y: 20, width: 200, height: 100 } })
+    sequencer.dispatch({ type: 'focusPane', paneId })
+    const before = sequencer.state
+    expect(before.floats).toEqual([lower, upper])
+
+    sequencer.dispatch({ type: 'moveFloat', paneId: lower, x: 50, y: 60 })
+    expect(sequencer.state.floats).toEqual([upper, lower])
+    expect(sequencer.state.activePaneId).toBe(lower)
+
+    // One step back restores the rectangle, the z order, and the focus; the
+    // preceding focus-only entry is its own step.
+    expect(sequencer.undo()).toBe(true)
+    expect(sequencer.state).toEqual(before)
+    expect(sequencer.redo()).toBe(true)
+    expect(sequencer.state.floats).toEqual([upper, lower])
+    expect(getPane(sequencer.state, lower).rect).toEqual({ x: 50, y: 60, width: 200, height: 100 })
+    expect(sequencer.state.activePaneId).toBe(lower)
+  })
+})
+
+describe('linear history', () => {
+  it('drops the redo branch when a new operation lands after an undo', () => {
+    const { sequencer, minter, paneId } = fixture()
+    sequencer.dispatch({ type: 'setExpanded', expanded: true })
+    sequencer.dispatch({
+      type: 'split', paneId, axis: 'row', direction: 'after', newPaneId: minter.next('pane'), newSplitId: minter.next('split'),
+    })
+    expect(sequencer.undo()).toBe(true)
+    expect(sequencer.canRedo).toBe(true)
+    sequencer.dispatch({ type: 'focusPane', paneId })
+    expect(sequencer.canRedo).toBe(false)
+    expect(sequencer.ops.map(op => op.type)).toEqual(['setExpanded', 'focusPane'])
+    expect(dockPaneIds(sequencer.state)).toHaveLength(1)
+  })
+
+  it('keeps the applied prefix replayable at any cursor', () => {
+    const { sequencer, initial, minter, paneId, guideTabId } = fixture()
+    const newPaneId = minter.next('pane')
+    sequencer.dispatch({ type: 'setExpanded', expanded: true })
+    sequencer.dispatch({
+      type: 'split', paneId, axis: 'row', direction: 'after', newPaneId, newSplitId: minter.next('split'),
+    })
+    sequencer.dispatch({ type: 'moveTab', tabId: guideTabId, toPaneId: newPaneId, index: 0 })
+    sequencer.dispatch({ type: 'resize', splitId: getSplit(sequencer.state, sequencer.state.rootId).id, sizes: [0.7, 0.3] })
+    sequencer.undo()
+    sequencer.undo()
+    expect(replay(initial, sequencer.ops.slice(0, sequencer.cursor))).toEqual(sequencer.state)
+    sequencer.redo()
+    expect(replay(initial, sequencer.ops.slice(0, sequencer.cursor))).toEqual(sequencer.state)
+  })
+})
diff --git a/packages/client/ui-dockkit/tsconfig.json b/packages/client/ui-dockkit/tsconfig.json
new file mode 100644
index 0000000000..2139bcf7ba
--- /dev/null
+++ b/packages/client/ui-dockkit/tsconfig.json
@@ -0,0 +1,15 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../util/brand"
+    }
+  ]
+}
diff --git a/packages/client/ui-dockkit/tsdown.config.ts b/packages/client/ui-dockkit/tsdown.config.ts
new file mode 100644
index 0000000000..7e4e7ba807
--- /dev/null
+++ b/packages/client/ui-dockkit/tsdown.config.ts
@@ -0,0 +1,6 @@
+import { staticLinked } from '../tsdown.client.ts'
+
+export default staticLinked(
+  '@deepseek-ai/dsh-client-ui-dockkit',
+  ['lib/types/index.js'],
+)
diff --git a/packages/client/ui-goal/README.i18n.yaml b/packages/client/ui-goal/README.i18n.yaml
index 1290b0416d..e2d16274f7 100644
--- a/packages/client/ui-goal/README.i18n.yaml
+++ b/packages/client/ui-goal/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-goal/README.md
-README.md: 8556575b00e1d3073f251d83f3dee0bafb4c8969
-README.zh.md: 22d0417bc2d37719150ec46aad849ad2bce8b460
+README.md: bec1e1dfed96731d70a10404c23230f9b7fe6e0a
+README.zh.md: 31bf10735ad46ff8344e2ced7b975c3807a18d42
diff --git a/packages/client/ui-goal/README.md b/packages/client/ui-goal/README.md
index 8556575b00..bec1e1dfed 100644
--- a/packages/client/ui-goal/README.md
+++ b/packages/client/ui-goal/README.md
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-This package renders the goal surface in the Web GUI: a strip in the composer-context stack that shows the current goal of the session and offers edit, pause, resume, and clear actions. It reads the live goal from the host-computed projection and routes every mutation through the goal service, surfacing rejections inline. It also projects each durable `/goal` command run as a `Command input` bubble in the chat, so a goal command entered by the user or the model appears in the transcript. Goal creation is outside this plugin. The shipped Web presets other than `minimal` mount `/goal` in their agent scope.
+This package renders the goal surface in the Web GUI: a strip in the composer-context stack that shows the current goal of the session and offers edit, pause, resume, and clear actions. It reads the durable goal from the host-computed projection, overlays process-local `activation` from a registrant-private observable hook, and routes every mutation through the goal service, surfacing rejections inline. It also projects each durable `/goal` command run as a `Command input` bubble in the chat, so a goal command entered by the user or the model appears in the transcript. Goal creation is outside this plugin. The shipped Web presets other than `minimal` mount `/goal` in their agent scope.
 
 ## Table of Contents
 
@@ -25,7 +25,7 @@ This package renders the goal surface in the Web GUI: a strip in the composer-co
 <a id="use-this-package"></a>
 ## Use this package
 
-Mount this plugin alongside `ui-conversation` and the goal domain package; the strip then appears as the second card in the composer-context stack (after Todo, before Queue) whenever the session has a goal. An active goal offers pause; a paused one offers resume; edit rewrites the objective; clear removes the goal and suppresses the strip until the projection catches up.
+Mount this plugin alongside `ui-conversation` and the goal domain package; the strip then appears as the second card in the composer-context stack (after Todo, before Queue) whenever the session has a goal. An armed active goal offers pause; an active-but-disarmed or paused goal offers resume; edit rewrites the objective; clear removes the goal and suppresses the strip until the projection catches up.
 
 ### The command-input bubble
 
@@ -43,7 +43,7 @@ A rejected mutation surfaces the Remote error inline on the strip; loading, abse
 <details>
 <summary>Implementation internals — click to expand</summary>
 
-The strip is projection-mode: the live goal arrives through `useProjection('goal')` (seeded by the history tail page and updated by `session/projection` frames), so the plugin owns no domain store, refresh chain, or event listener. The inject face carries only the four mutation verbs through `ctx.remote.goals`; each reads the CAS ref from the session's current projected value at call time, and the RPC's compare-and-set is the staleness guard. The strip single-flights mutations synchronously because a pending render cannot fence same-frame clicks. The command-input projection is a separate Conversation Definition that builds a `command-input` Chat Node before the generic command result Node; it never creates `user/message` or a model turn.
+The durable goal arrives through `useProjection('goal')` (seeded by the history tail page and updated by `session/projection` frames). The inject face carries a registrant-private activation hook source plus the four mutation verbs. That source starts only while the framework hook observes it, reads `ctx.remote.goals.get`, subscribes to `goal/activation-changed`, and refreshes on running-state or connection resets. Live-event epochs invalidate in-flight reads, so a stale HTTP result cannot overwrite a newer activation edge; running refreshes retain the last known activation until the read resolves. The strip owns no domain store or cross-plugin cache. Each mutation reads the CAS ref from the session's current projected value at call time, and the RPC's compare-and-set is the staleness guard. The strip single-flights mutations synchronously because a pending render cannot fence same-frame clicks. The command-input projection is a separate Conversation Definition that builds a `command-input` Chat Node before the generic command result Node; it never creates `user/message` or a model turn.
 
 </details>
 
@@ -76,7 +76,6 @@ None unless the queued goal context is admitted. An admitted context extends the
 
 These limits define the current goal surface. They are current package constraints, not a goal-domain comparison or a task backlog.
 
-- **Durable phase only** — the projection omits process-local activation, so the strip cannot distinguish an active-but-disarmed goal from an armed one; resume re-arms through the RPC side. There is no host-live activation channel.
 - **Preset-independent host state** — switching an active session to `minimal` leaves its host-owned goal intact. `/goal` and goal tools disappear, while this strip can still edit, pause, resume, or clear the goal.
 
 <a id="dev-note"></a>
@@ -89,4 +88,4 @@ None.
 
 </details>
 
-**Runtime invariant:** No companion is published. A single GoalBar dock registration whose disposal is proven by the HMR-safety spec — the plugin owns no store (state arrives on the goal projection), emits no cordis events, and holds no cross-plugin mutable state.
+**Runtime invariant:** No companion is published. A single GoalBar dock registration whose disposal is proven by the HMR-safety spec — durable state arrives on the goal projection, process-local activation arrives through the entry's private hook source, and that source subscribes only while the framework hook observes it.
diff --git a/packages/client/ui-goal/README.zh.md b/packages/client/ui-goal/README.zh.md
index 22d0417bc2..31bf10735a 100644
--- a/packages/client/ui-goal/README.zh.md
+++ b/packages/client/ui-goal/README.zh.md
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-本包在 Web GUI 中渲染 goal 表面：composer 上下文堆栈里的一条条带，显示会话的当前目标，并提供编辑、暂停、恢复与清除动作。它从宿主计算的投影读取活目标，把每次变更都经 goal 服务路由，并把拒绝内联呈现。它还把每条持久的 `/goal` 命令运行投影为聊天中的 `Command input` 气泡，让用户或模型输入的 goal 命令出现在文本记录中。goal 创建不归本插件。除 `minimal` 外，随附的 Web preset 都会在其 agent scope 中挂载 `/goal`。
+本包在 Web GUI 中渲染 goal 表面：composer 上下文堆栈里的一条条带，显示会话的当前目标，并提供编辑、暂停、恢复与清除动作。它从宿主计算的投影读取持久 goal，通过 registrant-private 的可观察 hook 叠加进程本地 `activation`，把每次变更都经 goal 服务路由，并把拒绝内联呈现。它还把每条持久的 `/goal` 命令运行投影为聊天中的 `Command input` 气泡，让用户或模型输入的 goal 命令出现在文本记录中。goal 创建不归本插件。除 `minimal` 外，随附的 Web preset 都会在其 agent scope 中挂载 `/goal`。
 
 ## 目录
 
@@ -25,7 +25,7 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-与 `ui-conversation` 及 goal 领域包一起挂载本插件；只要会话存在目标，条带就会作为 composer 上下文堆栈的第二张卡片出现（位于 Todo 之后、Queue 之前）。active 的 goal 提供暂停动作；paused 的提供恢复；编辑重写目标文本；清除移除目标，并在投影追上之前抑制条带。
+与 `ui-conversation` 及 goal 领域包一起挂载本插件；只要会话存在目标，条带就会作为 composer 上下文堆栈的第二张卡片出现（位于 Todo 之后、Queue 之前）。已 armed 的 active goal 提供暂停动作；active-but-disarmed 或 paused 的 goal 提供恢复；编辑重写目标文本；清除移除目标，并在投影追上之前抑制条带。
 
 ### 指令输入气泡
 
@@ -43,7 +43,7 @@ kind: "package-reference"
 <details>
 <summary>实现细节——点击展开</summary>
 
-条带是投影模式：活目标经 `useProjection('goal')` 到达（由历史尾页播种、`session/projection` 帧更新），因此插件不持有领域 store、不设刷新链、不挂事件监听。注入面只携带四个变更动词，经 `ctx.remote.goals` 调用；每个动词在调用时从会话当前投影值读取 CAS ref，比较并交换（RPC 的 CAS）就是陈旧性护栏。由于 React 的 pending 渲染无法拦住同一帧内的点击，条带会同步为变更建立 single-flight 防护。指令输入投影是独立的 Conversation Definition，在通用命令结果 Node 之前构建 `command-input` Chat Node；它绝不创建 `user/message` 或模型轮次。
+持久 goal 经 `useProjection('goal')` 到达（由历史尾页播种、`session/projection` 帧更新）。注入面携带 registrant-private 的 activation hook source 与四个变更动词。该 source 仅在框架 hook 观察期间订阅，读取 `ctx.remote.goals.get`、订阅 `goal/activation-changed`，并在 running 状态或连接 reset 时刷新。live event epoch 会让在途读取失效，因此较旧的 HTTP 响应不能覆盖更新的 activation 边界；running 刷新会保留最后一次已知 activation，直到读取完成。条带不持有领域 store 或跨插件缓存。每个变更在调用时从会话当前投影值读取 CAS ref，比较并交换（RPC 的 CAS）就是陈旧性护栏。由于 React 的 pending 渲染无法拦住同一帧内的点击，条带会同步为变更建立 single-flight 防护。指令输入投影是独立的 Conversation Definition，在通用命令结果 Node 之前构建 `command-input` Chat Node；它绝不创建 `user/message` 或模型轮次。
 
 </details>
 
@@ -76,7 +76,6 @@ kind: "package-reference"
 
 这些限制界定了当前 goal 表面。它们是当前包约束，不是 goal 领域对比或任务积压。
 
-- **只反映持久阶段**——投影省略进程本地的激活状态，因此条带无法区分已激活但未武装的 goal 与已武装的 goal；恢复经 RPC 侧重新武装。不存在宿主实时激活通道。
 - **Host 状态与 preset 无关**——把活跃会话切换到 `minimal` 后，Host 拥有的 goal 仍会保留。`/goal` 与 goal 工具会消失，但该条带仍可编辑、暂停、恢复或清除 goal。
 
 <a id="dev-note"></a>
@@ -89,4 +88,4 @@ kind: "package-reference"
 
 </details>
 
-**运行时不变式：** 不发布伴生入口。插件只注册一个 GoalBar dock，HMR 测试覆盖释放；状态来自 goal projection，本包不持有 store 或跨插件可变状态。
+**运行时不变式：** 不发布伴生入口。插件只注册一个 GoalBar dock，HMR 测试覆盖释放；持久状态来自 goal projection，进程本地 activation 来自入口私有 hook source，且该 source 只在框架 hook 观察期间订阅。
diff --git a/packages/client/ui-goal/src/client/GoalBar.tsx b/packages/client/ui-goal/src/client/GoalBar.tsx
index f7a9050597..905bdb7631 100644
--- a/packages/client/ui-goal/src/client/GoalBar.tsx
+++ b/packages/client/ui-goal/src/client/GoalBar.tsx
@@ -1,27 +1,29 @@
 /**
  * GoalBar: the goal indicator docked above the message composer (input dock
  * strip). A present goal shows a goal glyph, a phase label, the truncated
- * objective, and icon actions — resume when paused, edit (inline form in the
- * same strip), and clear. Goal creation lives on the `/goal` command, not
- * here: loading (undefined), no goal (null), and complete goals render
- * nothing. Live state arrives as the projected whole snapshot; the verbs are
- * the injected face.
+ * objective, and icon actions — resume when active-disarmed or paused, edit
+ * (inline form in the same strip), and clear. Goal creation lives on the
+ * `/goal` command, not here: loading (undefined), no goal (null), and complete
+ * goals render nothing. Durable state arrives as the projected whole snapshot;
+ * process-local activation arrives through the injected activation hook.
  */
 
 import { useCallback, useEffect, useRef, useState } from 'react'
-import type { GoalSnapshot } from '@deepseek-ai/dsh-goal/client'
+import type { GoalActivation, GoalSnapshot } from '@deepseek-ai/dsh-goal/client'
 import {
   IconCheckOutline16, IconCloseOutline16, IconEditOutline16, IconGoalOutline16,
   IconPauseOutline16, IconPlayOutline16, IconTrashOutline16, Tooltip,
 } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
-import type { GoalActionResult, GoalBarActions } from './slots.ts'
+import type { InjectFace, PropsLocale, TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
+import type { GoalActionResult, GoalBarActions, GoalBarInjected } from './slots.ts'
 import type { GoalKey } from './locales.ts'
 import css from './GoalBar.module.css'
 
 export interface GoalBarProps extends GoalBarActions {
   /** Current goal snapshot; undefined = capability absent or loading, null = no goal set. */
   goal: GoalSnapshot | null | undefined
+  /** Process-local continuation activation; absent while the live read is pending. */
+  activation?: GoalActivation
 }
 
 /** Strip label keys per visible phase; complete goals render nothing. */
@@ -31,7 +33,13 @@ const PHASE_LABELS = {
   blocked: 'phase.blocked',
 } as const satisfies Record<string, GoalKey>
 
-export function GoalBar({ goal, onEdit, onPause, onResume, onClear, t }: GoalBarProps & PropsLocale<'goal'>) {
+/** Strip label for an active goal using its process-local activation. */
+function activeLabel(activation: GoalActivation | undefined, t: TranslateNS<'goal'>): string {
+  if (activation === 'disarmed') return t('phase.active.disarmed')
+  return t(PHASE_LABELS.active)
+}
+
+export function GoalBar({ goal, activation, onEdit, onPause, onResume, onClear, t }: GoalBarProps & PropsLocale<'goal'>) {
   const [editing, setEditing] = useState(false)
   const [draft, setDraft] = useState('')
   const [pending, setPending] = useState(false)
@@ -124,22 +132,25 @@ export function GoalBar({ goal, onEdit, onPause, onResume, onClear, t }: GoalBar
   }
 
   const title = goal.phase === 'blocked' ? goal.blockedReason?.message : undefined
+  const label = goal.phase === 'active' ? activeLabel(activation, t) : t(PHASE_LABELS[goal.phase])
+  const showResume = goal.phase === 'paused'
+    || (goal.phase === 'active' && activation === 'disarmed')
   return (
     <div className={css.dock} data-goal-bar>
       <div className={css.bar} title={title}>
         <span className={css.goalGlyph}><IconGoalOutline16 size={14} /></span>
-        <span className={css.label}>{t(PHASE_LABELS[goal.phase])}</span>
+        <span className={css.label}>{label}</span>
         <span className={css.objective}>{goal.objective}</span>
         {actionError !== null && <span className={css.error} role="alert">{actionError}</span>}
         <div className={css.actions}>
-          {goal.phase === 'active' && (
+          {goal.phase === 'active' && activation === 'armed' && (
             <Tooltip label={t('action.pause')} side="bottom" delayMs={500}>
               <button type="button" className={css.iconBtn} disabled={pending} onClick={() => { void runAction(onPause) }} aria-label={t('action.pause')}>
                 <IconPauseOutline16 size={14} />
               </button>
             </Tooltip>
           )}
-          {goal.phase === 'paused' && (
+          {showResume && (
             <Tooltip label={t('action.resume')} side="bottom" delayMs={500}>
               <button type="button" className={css.iconBtn} disabled={pending} onClick={() => { void runAction(onResume) }} aria-label={t('action.resume')}>
                 <IconPlayOutline16 size={14} />
@@ -168,15 +179,28 @@ export function GoalBar({ goal, onEdit, onPause, onResume, onClear, t }: GoalBar
   )
 }
 
-/** Full props of the dock entry: InputZone owner share + session standard kit + injected verbs + the locale seat. */
-export type GoalDockProps = import('@deepseek-ai/dsh-client-ui-slots').PropsRuntime<'conversation.input.dock'> & GoalBarActions & PropsLocale<'goal'>
+/** Full props of the dock entry: InputZone owner share + injected verbs/activation hook + the locale seat. */
+export type GoalDockProps =
+  import('@deepseek-ai/dsh-client-ui-slots').PropsRuntime<'conversation.input.dock'>
+  & InjectFace<GoalBarInjected>
+  & PropsLocale<'goal'>
 
-/** Dock adapter: reads the host-computed 'goal' projection (whole value; absent or null renders nothing). */
-export function GoalDock({ useProjection, onEdit, onPause, onResume, onClear, t }: GoalDockProps) {
+/** Dock adapter: overlays process-local activation on the durable goal projection. */
+export function GoalDock({
+  useProjection, useGoalActivation, onEdit, onPause, onResume, onClear, t,
+}: GoalDockProps) {
   const projection = useProjection('goal')
+  const goal = projection === undefined || projection === null ? projection : projection.goal
+  const goalId = goal?.id
+  const revision = goal?.revision
+  const activation = useGoalActivation(next => (
+    next.id === goalId && next.revision === revision ? next.activation : undefined
+  ))
+
   return (
     <GoalBar
-      goal={projection === undefined ? undefined : projection === null ? null : projection.goal}
+      goal={goal}
+      {...activation === undefined ? {} : { activation }}
       onEdit={onEdit}
       onPause={onPause}
       onResume={onResume}
diff --git a/packages/client/ui-goal/src/client/activation-source.ts b/packages/client/ui-goal/src/client/activation-source.ts
new file mode 100644
index 0000000000..23c65740a0
--- /dev/null
+++ b/packages/client/ui-goal/src/client/activation-source.ts
@@ -0,0 +1,140 @@
+/** Goal activation observable that orders Remote reads and live activation events. */
+
+import type { RemoteResult } from '@deepseek-ai/dsh-api-remotes/client'
+import type { HostObservable } from '@deepseek-ai/dsh-client-ui-slots'
+import type {
+  GoalActivationChanged, GoalProjection, GoalRef, GoalView,
+} from '@deepseek-ai/dsh-goal/client'
+import type { GoalActivationSnapshot } from './slots.ts'
+
+/** Live inputs for one Session's goal activation source. */
+export interface GoalActivationDeps {
+  /** Durable projection used to derive the current active goal ref. */
+  readonly projection: HostObservable<GoalProjection | null | undefined>
+  /** Session snapshot; running flips trigger a fresh authoritative read. */
+  readonly session: HostObservable<{ readonly running: boolean }>
+  /** Read the current live goal at call time. */
+  readonly getGoal: () => Promise<RemoteResult<GoalView | undefined>>
+  /** Subscribe to activation edges after the transport delivers them. */
+  readonly subscribeActivation: (listener: (goal: GoalActivationChanged['goal']) => void) => () => void
+  /** Refresh after a connection-generation reset. */
+  readonly subscribeReset: (listener: () => void) => () => void
+}
+
+/** Compare two empty-or-populated activation snapshots by value. */
+function sameSnapshot(left: GoalActivationSnapshot, right: GoalActivationSnapshot): boolean {
+  return left.id === right.id && left.revision === right.revision && left.activation === right.activation
+}
+
+/** Return the current active CAS ref, or undefined when the goal is not active. */
+function activeRef(projection: GoalProjection | null | undefined): GoalRef | undefined {
+  return projection?.goal.phase === 'active' ? projection.goal : undefined
+}
+
+/**
+ * Create one registrant-private activation source. The source subscribes only
+ * while a framework hook observes it, so unmount releases the Remote event,
+ * projection, running-snapshot, and reset listeners.
+ * @param deps - projection, session, Remote read, and live-event inputs.
+ * @returns stable snapshot source consumed by `useGoalActivation`.
+ */
+export function createGoalActivationSource(deps: GoalActivationDeps): HostObservable<GoalActivationSnapshot> {
+  let snapshot: GoalActivationSnapshot = {}
+  let subscriptions = 0
+  let disposers: readonly (() => void)[] = []
+  let running = deps.session.getSnapshot().running
+  let eventEpoch = 0
+  let projectionEpoch = 0
+  let readEpoch = 0
+  const listeners = new Set<() => void>()
+
+  const publish = (next: GoalActivationSnapshot): void => {
+    if (sameSnapshot(snapshot, next)) return
+    snapshot = next
+    for (const listener of listeners) listener()
+  }
+
+  const startRead = (ref: GoalRef | undefined): void => {
+    if (ref === undefined) return
+    const read = ++readEpoch
+    const startedAtEvent = eventEpoch
+    const startedAtProjection = projectionEpoch
+    void deps.getGoal().then((result) => {
+      if (read !== readEpoch || startedAtEvent !== eventEpoch || startedAtProjection !== projectionEpoch) return
+      if (!result.ok) return
+      const goal = result.value
+      /* v8 ignore next 4 -- projection drive is the authoritative clear edge; an active projection with no live goal is transient. */
+      if (goal === undefined) {
+        if (activeRef(deps.projection.getSnapshot()) === undefined) publish({})
+        return
+      }
+      publish({ id: goal.id, revision: goal.revision, activation: goal.activation })
+    })
+  }
+
+  const refreshProjection = (): void => {
+    projectionEpoch++
+    const ref = activeRef(deps.projection.getSnapshot())
+    if (ref === undefined) {
+      /* v8 ignore next -- clearing an already-empty activation snapshot is idempotent. */
+      if (snapshot.id !== undefined) publish({})
+      return
+    }
+    if (snapshot.id !== ref.id || snapshot.revision !== ref.revision) {
+      publish({ id: ref.id, revision: ref.revision })
+    }
+    startRead(ref)
+  }
+
+  const onActivation = (goal: GoalActivationChanged['goal']): void => {
+    eventEpoch++
+    readEpoch++
+    publish(goal === undefined
+      ? {}
+      : { id: goal.id, revision: goal.revision, activation: goal.activation })
+  }
+
+  const onRunning = (): void => {
+    const next = deps.session.getSnapshot().running
+    if (next === running) return
+    running = next
+    startRead(activeRef(deps.projection.getSnapshot()))
+  }
+
+  const onReset = (): void => {
+    eventEpoch++
+    projectionEpoch++
+    startRead(activeRef(deps.projection.getSnapshot()))
+  }
+
+  const start = (): void => {
+    disposers = [
+      deps.projection.subscribe(refreshProjection),
+      deps.session.subscribe(onRunning),
+      deps.subscribeActivation(onActivation),
+      deps.subscribeReset(onReset),
+    ]
+    running = deps.session.getSnapshot().running
+    refreshProjection()
+  }
+
+  const stop = (): void => {
+    for (const dispose of disposers) dispose()
+    disposers = []
+    readEpoch++
+  }
+
+  return {
+    getSnapshot: () => snapshot,
+    subscribe(listener) {
+      listeners.add(listener)
+      if (subscriptions === 0) start()
+      subscriptions++
+      return () => {
+        listeners.delete(listener)
+        subscriptions--
+        if (subscriptions === 0) stop()
+      }
+    },
+  }
+}
diff --git a/packages/client/ui-goal/src/client/index.ts b/packages/client/ui-goal/src/client/index.ts
index c2c98cada5..93e1c996bf 100644
--- a/packages/client/ui-goal/src/client/index.ts
+++ b/packages/client/ui-goal/src/client/index.ts
@@ -1,15 +1,14 @@
 /**
  * Goal surface plugin, browser half: the GoalBar entry in the
- * conversation.input.dock strip. Projection-mode surface — the live goal
- * arrives through `useProjection('goal')` (seeded by the history tail page,
- * updated by session/projection frames), so this plugin owns no store, no
- * refresh chain, and no event listener. The inject face carries only the
- * four mutation verbs through the generated Goal Remote API;
- * their CAS ref reads the session's current projected value at call time.
+ * conversation.input.dock strip. The durable goal arrives through
+ * `useProjection('goal')`. A registrant-private activation hook source owns
+ * the live Remote read and event subscription; the inject face carries that
+ * hook plus the four mutation verbs through the generated Goal Remote API.
  * This plugin does not create goals; deployments may expose /goal separately.
  */
 import type { Context as ClientContext } from '@deepseek-ai/cordis'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { HostObservable } from '@deepseek-ai/dsh-client-ui-slots'
 // Type-only: pulls the generated Remote API and ctx.remote merge through the Client assembly boundary.
 import type {} from '@deepseek-ai/dsh-api-remotes/client'
 // Type-only: pulls the Session Controller service used for projected goal state.
@@ -26,14 +25,17 @@ import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
 import type {} from '@deepseek-ai/dsh-client-ui-session/client'
 // Type-only: the `goal` SessionProjectionMap key merge (single source, the domain's pure outlet).
 import type { GoalProjection, GoalRef } from '@deepseek-ai/dsh-goal/client'
-import type { GoalActionResult, GoalBarActions } from './slots.ts'
+import type { GoalActionResult, GoalBarInjected } from './slots.ts'
+import { createGoalActivationSource } from './activation-source.ts'
 import { GoalDock } from './GoalBar.tsx'
 import { GoalCommandInputView } from './GoalCommandInputView.tsx'
 import { goalCommandInputDefinition } from './goal-command-input.ts'
 import { en, zh, type GoalKey } from './locales.ts'
 
 export { GoalBar, GoalDock } from './GoalBar.tsx'
-export type { GoalActionResult, GoalBarActions } from './slots.ts'
+export type {
+  GoalActionResult, GoalBarActions,
+} from './slots.ts'
 export type { GoalKey } from './locales.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
@@ -83,27 +85,41 @@ export function apply(ctx: ClientContext): void {
     id: 'goal',
     order: 10,
     locale: NS,
-    inject: (sessionId): GoalBarActions => ({
-      onEdit: async (objective) => {
-        const ref = refOf(sessionId)
-        if (ref === undefined) return noCurrentGoal
-        return await ctx.remote.goals.edit(sessionId, ref, { objective })
-      },
-      onPause: async () => {
-        const ref = refOf(sessionId)
-        if (ref === undefined) return noCurrentGoal
-        return await ctx.remote.goals.pause(sessionId, ref)
-      },
-      onResume: async () => {
-        const ref = refOf(sessionId)
-        if (ref === undefined) return noCurrentGoal
-        return await ctx.remote.goals.resume(sessionId, ref)
-      },
-      onClear: async () => {
-        const ref = refOf(sessionId)
-        if (ref === undefined) return noCurrentGoal
-        return await ctx.remote.goals.clear(sessionId, ref)
-      },
-    }),
+    inject: (sessionId): GoalBarInjected => {
+      const binding = sessions.binding(sessionId)
+      if (binding === undefined) throw new Error(`ui-goal: session "${sessionId}" is unavailable`)
+      const goalActivation = createGoalActivationSource({
+        projection: binding.session.projections.faceOf('goal') as HostObservable<GoalProjection | null | undefined>,
+        session: binding.session,
+        getGoal: () => ctx.remote.goals.get(sessionId),
+        subscribeActivation: listener => ctx.remote.$on('goal/activation-changed', (event) => {
+          if (event.sessionId === sessionId) listener(event.goal)
+        }),
+        subscribeReset: listener => ctx.on('connection/reset', listener),
+      })
+      return {
+        hooks: { goalActivation },
+        onEdit: async (objective) => {
+          const ref = refOf(sessionId)
+          if (ref === undefined) return noCurrentGoal
+          return await ctx.remote.goals.edit(sessionId, ref, { objective })
+        },
+        onPause: async () => {
+          const ref = refOf(sessionId)
+          if (ref === undefined) return noCurrentGoal
+          return await ctx.remote.goals.pause(sessionId, ref)
+        },
+        onResume: async () => {
+          const ref = refOf(sessionId)
+          if (ref === undefined) return noCurrentGoal
+          return await ctx.remote.goals.resume(sessionId, ref)
+        },
+        onClear: async () => {
+          const ref = refOf(sessionId)
+          if (ref === undefined) return noCurrentGoal
+          return await ctx.remote.goals.clear(sessionId, ref)
+        },
+      }
+    },
   }, GoalDock))
 }
diff --git a/packages/client/ui-goal/src/client/locales.ts b/packages/client/ui-goal/src/client/locales.ts
index 055991e277..812b9d484d 100644
--- a/packages/client/ui-goal/src/client/locales.ts
+++ b/packages/client/ui-goal/src/client/locales.ts
@@ -3,6 +3,7 @@
 /** Simplified Chinese dictionary (the key-set source of truth). */
 export const zh = {
   'phase.active': '进行中的目标',
+  'phase.active.disarmed': '未运行的目标',
   'phase.paused': '已暂停的目标',
   'phase.blocked': '受阻的目标',
   'objective.aria': '目标内容',
@@ -21,6 +22,7 @@ export type GoalKey = keyof typeof zh
 /** English dictionary, checked complete against the zh key set. */
 export const en = {
   'phase.active': 'Ongoing Goal',
+  'phase.active.disarmed': 'Inactive Goal',
   'phase.paused': 'Paused Goal',
   'phase.blocked': 'Blocked Goal',
   'objective.aria': 'Goal objective',
diff --git a/packages/client/ui-goal/src/client/slots.ts b/packages/client/ui-goal/src/client/slots.ts
index a343b44fc9..eeffa48f17 100644
--- a/packages/client/ui-goal/src/client/slots.ts
+++ b/packages/client/ui-goal/src/client/slots.ts
@@ -1,13 +1,15 @@
 /**
  * GoalBar's injected face. The target 'conversation.input.dock' slot is
  * declared (children table) and typed by ui-conversation; this package only
- * contributes the entry, so no SlotMap merge lives here. The live goal value
- * is NOT part of this face — it arrives through `useProjection('goal')`
- * (the framework standard kit); inject carries only the mutation verbs
- * (callbacks from inject, live state from useProjection).
+ * contributes the entry, so no SlotMap merge lives here. The durable goal
+ * value arrives through `useProjection('goal')` (the framework standard kit);
+ * the injected face carries mutation verbs and a registrant-private
+ * activation hook source.
  */
 
 import type { RemoteResult } from '@deepseek-ai/dsh-api-remotes/client'
+import type { HostObservable } from '@deepseek-ai/dsh-client-ui-slots'
+import type { GoalActivation, GoalId } from '@deepseek-ai/dsh-goal/client'
 
 /**
  * The one failure the strip reports without a wire call: the session projects
@@ -25,6 +27,23 @@ export interface GoalLocalFailure {
  */
 export type GoalActionResult = RemoteResult<unknown> | GoalLocalFailure
 
+/** Process-local activation matched to one exact goal revision. */
+export interface GoalActivationSnapshot {
+  /** Exact current goal id, absent before create or after clear. */
+  readonly id?: GoalId
+  /** Exact current revision for the activation edge. */
+  readonly revision?: number
+  /** Process-local continuation state; absent while no matching edge is known. */
+  readonly activation?: GoalActivation
+}
+
+/** Registrant-private observable source bound by the slot renderer. */
+export interface GoalActivationInjected {
+  readonly hooks: {
+    readonly goalActivation: HostObservable<GoalActivationSnapshot>
+  }
+}
+
 /** Injected business face of the GoalBar dock entry: the mutation verbs (function properties: the strip destructures them freely). */
 export interface GoalBarActions {
   /**
@@ -39,3 +58,6 @@ export interface GoalBarActions {
   /** Clear the current goal (tombstone). */
   onClear: () => Promise<GoalActionResult>
 }
+
+/** Injected business face of the GoalBar dock entry. */
+export type GoalBarInjected = GoalBarActions & GoalActivationInjected
diff --git a/packages/client/ui-goal/tests/activation-source.client.spec.ts b/packages/client/ui-goal/tests/activation-source.client.spec.ts
new file mode 100644
index 0000000000..be8aee64fb
--- /dev/null
+++ b/packages/client/ui-goal/tests/activation-source.client.spec.ts
@@ -0,0 +1,199 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
+import type { RemoteResult } from '@deepseek-ai/dsh-api-remotes/client'
+import type { GoalActivationChanged, GoalId, GoalProjection, GoalView } from '@deepseek-ai/dsh-goal/client'
+import { RemoteError } from '@deepseek-ai/dsh-client-test-runtime'
+import { createGoalActivationSource } from '../src/client/activation-source.ts'
+
+const GOAL_ID = 'g-1' as GoalId
+
+function projection(): GoalProjection {
+  return {
+    goal: {
+      id: GOAL_ID,
+      revision: 1,
+      objective: 'ship it',
+      phase: 'active',
+      maxGoalRounds: 8,
+    },
+    roundsStarted: 0,
+    createdAt: 1,
+    updatedAt: 1,
+  }
+}
+
+function goalView(activation: 'armed' | 'disarmed'): GoalView {
+  return { ...projection().goal, roundsStarted: 0, createdAt: 1, updatedAt: 1, activation }
+}
+
+describe('goal activation source', () => {
+  it('does not let a stale read overwrite a later activation event', async () => {
+    const projectionStore = createSnapshotStore<GoalProjection | null | undefined>(projection())
+    const session = createSnapshotStore({ running: false })
+    let resolveRead!: (value: RemoteResult<GoalView | undefined>) => void
+    const getGoal = vi.fn(() => new Promise<RemoteResult<GoalView | undefined>>((resolve) => {
+      resolveRead = resolve
+    }))
+    let activationListener: ((goal: GoalActivationChanged['goal']) => void) | undefined
+    const source = createGoalActivationSource({
+      projection: projectionStore,
+      session,
+      getGoal,
+      subscribeActivation: (listener) => {
+        activationListener = listener
+        return () => { activationListener = undefined }
+      },
+      subscribeReset: () => () => {},
+    })
+    const dispose = source.subscribe(() => {})
+
+    activationListener?.({ id: GOAL_ID, revision: 1, activation: 'disarmed' })
+    resolveRead({ ok: true, value: goalView('armed') })
+    await Promise.resolve()
+
+    expect(source.getSnapshot()).toMatchObject({ id: 'g-1', revision: 1, activation: 'disarmed' })
+    dispose()
+  })
+
+  it('refreshes on the running edge without clearing the last activation', async () => {
+    const projectionStore = createSnapshotStore<GoalProjection | null | undefined>(projection())
+    const session = createSnapshotStore({ running: false })
+    const getGoal = vi.fn()
+      .mockResolvedValueOnce({ ok: true as const, value: goalView('disarmed') })
+      .mockImplementationOnce(() => new Promise<RemoteResult<GoalView | undefined>>(() => {}))
+    const source = createGoalActivationSource({
+      projection: projectionStore,
+      session,
+      getGoal,
+      subscribeActivation: () => () => {},
+      subscribeReset: () => () => {},
+    })
+    const dispose = source.subscribe(() => {})
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(source.getSnapshot().activation).toBe('disarmed')
+
+    session.set({ running: true })
+    expect(source.getSnapshot().activation).toBe('disarmed')
+    dispose()
+  })
+
+  it('merges lifecycle edges and releases subscriptions with the last observer', async () => {
+    const projectionStore = createSnapshotStore<GoalProjection | null | undefined>(projection())
+    const session = createSnapshotStore({ running: false })
+    const getGoal = vi.fn(() => Promise.resolve({
+      ok: true as const,
+      value: goalView('armed'),
+    }))
+    let emitActivation: ((goal: GoalActivationChanged['goal']) => void) | undefined
+    let emitReset: (() => void) | undefined
+    const disposeProjection: Array<() => void> = []
+    const disposeSession: Array<() => void> = []
+    const source = createGoalActivationSource({
+      projection: {
+        getSnapshot: () => projectionStore.getSnapshot(),
+        subscribe: (listener) => {
+          disposeProjection.push(listener)
+          return projectionStore.subscribe(listener)
+        },
+      },
+      session: {
+        getSnapshot: () => session.getSnapshot(),
+        subscribe: (listener) => {
+          disposeSession.push(listener)
+          return session.subscribe(listener)
+        },
+      },
+      getGoal,
+      subscribeActivation: (listener) => {
+        emitActivation = listener
+        return () => { emitActivation = undefined }
+      },
+      subscribeReset: (listener) => {
+        emitReset = listener
+        return () => { emitReset = undefined }
+      },
+    })
+
+    const first = source.subscribe(() => {})
+    const second = source.subscribe(() => {})
+    emitActivation?.({ id: GOAL_ID, revision: 1, activation: 'disarmed' })
+    emitActivation?.({ id: GOAL_ID, revision: 1, activation: 'disarmed' })
+    emitActivation?.(undefined)
+    emitActivation?.({ id: GOAL_ID, revision: 1, activation: 'armed' })
+    projectionStore.set(null)
+    session.set({ running: false })
+    session.set({ running: true })
+    await Promise.resolve()
+    emitReset?.()
+    await Promise.resolve()
+    projectionStore.set(projection())
+    await Promise.resolve()
+
+    expect(source.getSnapshot()).toMatchObject({ id: 'g-1', revision: 1, activation: 'armed' })
+    expect(disposeProjection.length).toBeGreaterThan(0)
+    expect(disposeSession.length).toBeGreaterThan(0)
+    first()
+    expect(emitActivation).toBeDefined()
+    second()
+    expect(emitActivation).toBeUndefined()
+    expect(emitReset).toBeUndefined()
+  })
+
+  it('leaves the ref unarmed when an authoritative read fails', async () => {
+    const projectionStore = createSnapshotStore<GoalProjection | null | undefined>(projection())
+    const session = createSnapshotStore({ running: false })
+    const source = createGoalActivationSource({
+      projection: projectionStore,
+      session,
+      getGoal: () => Promise.resolve({
+        ok: false,
+        error: new RemoteError('gateway/internal', 'no', {}),
+      }),
+      subscribeActivation: () => () => {},
+      subscribeReset: () => () => {},
+    })
+    const dispose = source.subscribe(() => {})
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(source.getSnapshot()).toMatchObject({ id: 'g-1', revision: 1 })
+    expect(source.getSnapshot().activation).toBeUndefined()
+    dispose()
+  })
+
+  it('does not republish an unchanged active ref or an already-empty projection', async () => {
+    const emptyProjection = createSnapshotStore<GoalProjection | null | undefined>(null)
+    const emptySession = createSnapshotStore({ running: false })
+    const emptySource = createGoalActivationSource({
+      projection: emptyProjection,
+      session: emptySession,
+      getGoal: () => Promise.resolve({ ok: true, value: undefined }),
+      subscribeActivation: () => () => {},
+      subscribeReset: () => () => {},
+    })
+    const emptyDispose = emptySource.subscribe(() => {})
+    expect(emptySource.getSnapshot()).toEqual({})
+    emptyDispose()
+
+    const projectionStore = createSnapshotStore<GoalProjection | null | undefined>(projection())
+    const session = createSnapshotStore({ running: false })
+    const source = createGoalActivationSource({
+      projection: projectionStore,
+      session,
+      getGoal: () => Promise.resolve({ ok: true, value: goalView('armed') }),
+      subscribeActivation: () => () => {},
+      subscribeReset: () => () => {},
+    })
+    const dispose = source.subscribe(() => {})
+    await Promise.resolve()
+    await Promise.resolve()
+    let notifications = 0
+    const disposeObserver = source.subscribe(() => { notifications++ })
+    projectionStore.set(projection())
+    await Promise.resolve()
+    expect(notifications).toBe(0)
+    expect(source.getSnapshot()).toMatchObject({ id: 'g-1', revision: 1, activation: 'armed' })
+    disposeObserver()
+    dispose()
+  })
+})
diff --git a/packages/client/ui-goal/tests/browser-plugin.client.spec.tsx b/packages/client/ui-goal/tests/browser-plugin.client.spec.tsx
index c98f795863..6181f3621b 100644
--- a/packages/client/ui-goal/tests/browser-plugin.client.spec.tsx
+++ b/packages/client/ui-goal/tests/browser-plugin.client.spec.tsx
@@ -11,17 +11,17 @@
  */
 import { Context, Service } from '@deepseek-ai/cordis'
 import { describe, expect, it, vi } from 'vitest'
-import { cleanup, render } from '@testing-library/react'
+import { cleanup, render, screen, waitFor } from '@testing-library/react'
 import { afterEach } from 'vitest'
 import { SlotRegistry } from '@deepseek-ai/dsh-client-ui-renderer/client'
 import { UiConversation } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
-import type { GoalProjection } from '@deepseek-ai/dsh-goal/client'
+import type { GoalActivation, GoalId, GoalProjection, GoalView } from '@deepseek-ai/dsh-goal/client'
 import { LocaleRuntime } from '@deepseek-ai/dsh-client-locale/client'
 import { makeTranslate, RemoteError } from '@deepseek-ai/dsh-client-test-runtime'
 import type { RemoteFailure } from '@deepseek-ai/dsh-api-remotes/client'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
-import type { GoalBarActions } from '../src/client/slots.ts'
+import type { GoalActivationSnapshot, GoalBarActions, GoalBarInjected } from '../src/client/slots.ts'
 import { apply, inject } from '../src/client/index.ts'
 import { GoalDock } from '../src/client/GoalBar.tsx'
 import { zh } from '../src/client/locales.ts'
@@ -30,11 +30,12 @@ import { apply as nodeApply } from '../src/index.ts'
 afterEach(cleanup)
 
 const sid = (k: string): SessionId => k as SessionId
+const GOAL_ID = 'g-1' as GoalId
 
 function makeProjection(revision = 3): GoalProjection {
   return {
     goal: {
-      id: 'g-1' as GoalProjection['goal']['id'],
+      id: GOAL_ID,
       revision,
       objective: 'Ship it',
       phase: 'active',
@@ -49,17 +50,22 @@ function makeProjection(revision = 3): GoalProjection {
 /** Boot the plugin over fake faces; Goal Remote methods record arguments and answer per the script. */
 async function bench(options: {
   projection?: GoalProjection | null | undefined
+  activation?: GoalActivation
   failWith?: RemoteFailure
 } = {}) {
   const ctx = new Context()
   const calls: { method: string; args: unknown[] }[] = []
   const sessions = {
-    binding: (id: SessionId) => ({
+    binding: (id: SessionId) => id === sid('missing') ? undefined : ({
       sessionId: id,
-      session: { projections: { faceOf: (key: string) => ({
-        getSnapshot: () => (key === 'goal' ? options.projection : undefined),
+      session: {
+        getSnapshot: () => ({ running: false }),
         subscribe: () => () => {},
-      }) } },
+        projections: { faceOf: (key: string) => ({
+          getSnapshot: () => (key === 'goal' ? options.projection : undefined),
+          subscribe: () => () => {},
+        }) },
+      },
       ctx,
     }),
   }
@@ -73,7 +79,18 @@ async function bench(options: {
     }
   }
   const ref = { id: 'g-1', revision: 3 }
+  const goalView = (): GoalView | undefined => {
+    if (options.projection === null || options.projection === undefined) return undefined
+    return {
+      ...options.projection.goal,
+      roundsStarted: options.projection.roundsStarted,
+      createdAt: options.projection.createdAt,
+      updatedAt: options.projection.updatedAt,
+      activation: options.activation ?? 'armed',
+    }
+  }
   const goals = (prefix: string) => ({
+    get: answer(`${prefix}/get`, goalView()),
     edit: answer(`${prefix}/edit`, { ref }),
     pause: answer(`${prefix}/pause`, { ref }),
     resume: answer(`${prefix}/resume`, { ref }),
@@ -81,12 +98,35 @@ async function bench(options: {
   })
   let activeGoals: ReturnType<typeof goals> | undefined = goals('goals')
   class RemoteService extends Service {
+    readonly activationListeners = new Set<(event: {
+      sessionId: SessionId
+      goal?: { id: string; revision: number; activation: GoalActivation }
+    }) => void>()
+
     constructor(serviceCtx: Context) {
       super(serviceCtx, 'remote')
     }
+
+    $on(_event: string, listener: (event: {
+      sessionId: SessionId
+      goal?: { id: string; revision: number; activation: GoalActivation }
+    }) => void): () => void {
+      this.activationListeners.add(listener)
+      return () => { this.activationListeners.delete(listener) }
+    }
+
+    emitActivation(
+      sessionId: SessionId,
+      goal: { id: string; revision: number; activation: GoalActivation } | undefined,
+    ): void {
+      for (const listener of this.activationListeners) {
+        listener({ sessionId, ...goal === undefined ? {} : { goal } })
+      }
+    }
   }
-  new RemoteService(ctx)
+  const remote = new RemoteService(ctx)
   ctx.provide('remote.goals', {
+    get get() { return activeGoals?.get },
     get edit() { return activeGoals?.edit },
     get pause() { return activeGoals?.pause },
     get resume() { return activeGoals?.resume },
@@ -105,6 +145,7 @@ async function bench(options: {
     ctx,
     fiber,
     calls,
+    emitActivation: remote.emitActivation.bind(remote),
     definitions: () => conversationEvents.entries(),
     remountGoals: () => { activeGoals = goals('remounted-goals') },
     unmountGoals: () => { activeGoals = undefined },
@@ -114,7 +155,7 @@ async function bench(options: {
       return {
         ...entry.options,
         locale: entry.locale,
-        inject: entry.inject as unknown as ((sessionId: SessionId) => GoalBarActions) | undefined,
+        inject: entry.inject as unknown as ((sessionId: SessionId) => GoalBarInjected) | undefined,
       }
     },
     chatEntry: () => ctx.slots.entries('conversation.chat.node')[0],
@@ -127,6 +168,7 @@ describe('ui-goal browser plugin', () => {
     await b.fiber.await()
     expect(b.entry()).toMatchObject({ id: 'goal', order: 10, locale: 'goal' })
     expect(b.entry()?.inject).toBeTypeOf('function')
+    expect(() => b.entry()!.inject!(sid('missing'))).toThrow(/unavailable/)
     expect(b.definitions().map(definition => definition.kind)).toEqual(['goal-command-input'])
     expect(b.chatEntry()?.options).toMatchObject({ key: 'command-input' })
     expect(b.chatEntry()?.locale).toBe('goal')
@@ -161,6 +203,26 @@ describe('ui-goal browser plugin', () => {
     expect(b.calls).toMatchObject([{ method: 'remounted-goals/pause' }])
   })
 
+  it('binds the activation hook and forwards only this session activation events', async () => {
+    const b = await bench({ projection: makeProjection(), activation: 'disarmed' })
+    await b.fiber.await()
+    const injected = b.entry()!.inject!(sid('s1'))
+    const source = injected.hooks.goalActivation
+    const seen: unknown[] = []
+    const dispose = source.subscribe(() => { seen.push(source.getSnapshot()) })
+    await waitFor(() => {
+      expect(source.getSnapshot()).toMatchObject({ id: 'g-1', revision: 3, activation: 'disarmed' })
+    })
+    expect(b.calls.at(-1)).toMatchObject({ method: 'goals/get', args: ['s1'] })
+
+    b.emitActivation(sid('s2'), { id: 'g-1', revision: 3, activation: 'armed' })
+    expect(source.getSnapshot().activation).toBe('disarmed')
+    b.emitActivation(sid('s1'), { id: 'g-1', revision: 3, activation: 'armed' })
+    expect(source.getSnapshot().activation).toBe('armed')
+    dispose()
+    expect(seen.length).toBeGreaterThan(0)
+  })
+
   it('rejects every verb once the Remote namespace is gone', async () => {
     const b = await bench({ projection: makeProjection() })
     await b.fiber.await()
@@ -216,6 +278,9 @@ describe('GoalDock adapter', () => {
   it('renders the projected goal snapshot and nothing for absent/null', () => {
     const projection = makeProjection()
     const useProjection = vi.fn(() => projection)
+    const useGoalActivation = (
+      selector: (snapshot: GoalActivationSnapshot) => unknown,
+    ) => selector({ id: GOAL_ID, revision: 3, activation: 'armed' })
     const actions: GoalBarActions = {
       onEdit: () => Promise.resolve({ ok: true, value: undefined }),
       onPause: () => Promise.resolve({ ok: true, value: undefined }),
@@ -224,7 +289,7 @@ describe('GoalDock adapter', () => {
     }
     const t = makeTranslate(zh, commonZh)
     const dockProps = (up: () => GoalProjection | null | undefined) =>
-      ({ useProjection: up, ...actions, t }) as unknown as Parameters<typeof GoalDock>[0]
+      ({ useProjection: up, useGoalActivation, ...actions, t }) as unknown as Parameters<typeof GoalDock>[0]
     const shown = render(<GoalDock {...dockProps(useProjection)} />)
     expect(shown.getByText('Ship it')).toBeTruthy()
     cleanup()
@@ -236,6 +301,26 @@ describe('GoalDock adapter', () => {
     const absent = render(<GoalDock {...dockProps(() => undefined)} />)
     expect(absent.container.firstChild).toBeNull()
   })
+
+  it('matches activation by goal id and revision from the injected hook', () => {
+    const projection = makeProjection()
+    const useProjection = vi.fn(() => projection)
+    const useGoalActivation = (
+      selector: (snapshot: GoalActivationSnapshot) => unknown,
+    ) => selector({ id: GOAL_ID, revision: 3, activation: 'disarmed' })
+    const actions: GoalBarActions = {
+      onEdit: () => Promise.resolve({ ok: true, value: undefined }),
+      onPause: () => Promise.resolve({ ok: true, value: undefined }),
+      onResume: () => Promise.resolve({ ok: true, value: undefined }),
+      onClear: () => Promise.resolve({ ok: true, value: undefined }),
+    }
+    const t = makeTranslate(zh, commonZh)
+    const props = { useProjection, useGoalActivation, ...actions, t } as unknown as Parameters<typeof GoalDock>[0]
+    const rendered = render(<GoalDock {...props} />)
+    expect(rendered.getByText('未运行的目标')).toBeTruthy()
+    expect(screen.getByRole('button', { name: '恢复目标' })).toBeTruthy()
+    expect(rendered.queryByRole('button', { name: '暂停目标' })).toBeNull()
+  })
 })
 
 describe('ui-goal node half', () => {
diff --git a/packages/client/ui-goal/tests/goalbar.client.spec.tsx b/packages/client/ui-goal/tests/goalbar.client.spec.tsx
index c4518fb757..c321ccf5ff 100644
--- a/packages/client/ui-goal/tests/goalbar.client.spec.tsx
+++ b/packages/client/ui-goal/tests/goalbar.client.spec.tsx
@@ -129,11 +129,20 @@ describe('GoalBar', () => {
 
   it('active goal: the pause action pauses', () => {
     const actions = makeActions()
-    render(<GoalBar goal={makeGoal()} {...actions} t={t} />)
+    render(<GoalBar goal={makeGoal()} activation="armed" {...actions} t={t} />)
     fireEvent.click(screen.getByRole('button', { name: '暂停目标' }))
     expect(actions.onPause).toHaveBeenCalledTimes(1)
   })
 
+  it('active disarmed goal: "未运行的目标" with a resume action instead of pause', () => {
+    const actions = makeActions()
+    render(<GoalBar goal={makeGoal()} activation="disarmed" {...actions} t={t} />)
+    expect(screen.getByText('未运行的目标')).toBeTruthy()
+    fireEvent.click(screen.getByRole('button', { name: '恢复目标' }))
+    expect(actions.onResume).toHaveBeenCalledTimes(1)
+    expect(screen.queryByRole('button', { name: '暂停目标' })).toBeNull()
+  })
+
   it('paused goal: "已暂停的目标" with a resume action before edit', () => {
     const actions = makeActions()
     render(<GoalBar goal={makeGoal({ phase: 'paused' })} {...actions} t={t} />)
diff --git a/packages/client/ui-layout/README.i18n.yaml b/packages/client/ui-layout/README.i18n.yaml
index 17187a8179..eb1cbebbee 100644
--- a/packages/client/ui-layout/README.i18n.yaml
+++ b/packages/client/ui-layout/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-layout/README.md
-README.md: aa00242f1d63924b990cfec23bd0438332662b06
-README.zh.md: 801346967f9fbb031e5e6c2612dff84af79f2d45
+README.md: 0e353e21f39ba8a84e661f1c540db2c2424bcbfa
+README.zh.md: 16471fdabb46bbfb35158ef85aa2544db4ceae93
diff --git a/packages/client/ui-layout/README.md b/packages/client/ui-layout/README.md
index aa00242f1d..0e353e21f3 100644
--- a/packages/client/ui-layout/README.md
+++ b/packages/client/ui-layout/README.md
@@ -1,5 +1,5 @@
 ---
-description: "Shell layout for the Web GUI: the three-column AppFrame with drag handles, concession behavior, the panel-geometry service, and theme presentation; for users and maintainers of the window chrome."
+description: "Shell layout for the Web GUI: the three-column AppFrame whose right column is a track for an edge-anchored panel, the panel-geometry service, and theme presentation; for users and maintainers of the window chrome."
 kind: "package-reference"
 ---
 
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-This package provides the shell layout of the Web GUI: a three-column AppFrame with resizable sidebar and details panels, a concession chain that shrinks the details column and then auto-closes it when space runs out, and the `ctx.layout` panel-geometry service other plugins call to open or close the details column. It also seats the theme presenter, which projects the resolved color scheme, alias tokens, content font size, and `theme-color` metadata onto the document. Choose it for the standard window chrome; panel geometry is transient and resets on reload.
+This package provides the Web GUI's three-column AppFrame, edge-column widths, and `ctx.layout` presentation control. The right column concedes space before the center; its occupant renders fullscreen while the frame retains the wide-screen track underneath. The theme presenter owns color scheme, alias tokens, content font size, and document metadata. Layout state resets on reload.
 
 ## Table of Contents
 
@@ -25,7 +25,7 @@ This package provides the shell layout of the Web GUI: a three-column AppFrame w
 <a id="use-this-package"></a>
 ## Use this package
 
-Mount this plugin at the root slot; it then renders the app frame around whatever occupies the sidebar, conversation, and details columns. Users resize the sidebar by dragging its invisible hit strip and the details panel by dragging its floating pill; when the window narrows, only details shrinks, then auto-closes. A closed sidebar retains a 56px control rail; details closes to zero width.
+The root slot composes the sidebar, conversation, and right column. The sidebar spans 264–420px, defaults to 280px, and retains a 56px rail when collapsed; below 1024px it collapses automatically, and opening the right panel collapses a manually expanded sidebar. The right panel first opens at 45% of the viewport, then retains the user's pixel preference, capped at 70%. To protect 400px for the center, the frame first reduces the right panel to 300px, then reports insufficient room so its occupant closes it, and only then compresses the center further. Dragging has no transition delay; the right handle is absent while closed or fullscreen.
 
 ### Theme presentation
 
@@ -39,7 +39,7 @@ The presenter consumes resolved theme snapshots and projects them onto the docum
 <details>
 <summary>Implementation internals — click to expand</summary>
 
-One `register()` call contributes `AppFrame` into the runtime's built-in `'root'` slot and, in the same breath, declares the four child slots (`sidebar`, `conversation`, `details`, `shell.overlay`), seats the layout store (panel geometry), and wires the `ctx.layout` panel-action service. The transient layout store starts the sidebar at its default width and details closed, and never reads or writes `localStorage`. AppFrame always mounts the conversation and details columns; a connected Session renders through `SessionProvider`. It projects the selected Session title over the build-configured product title or the localized `common.brand.localBuild` fallback, so locale revisions update document metadata with the root entry. The theme presenter is a second effect: pure DOM writes from resolved snapshots — initial state through the getter once, then event-driven only, with no React path. It applies palette, font-size, and token variables before measuring the rendered background as the single color authority.
+One registration declares four child slots and binds `ctx.layout` methods `toggleSidebar`, `openRightbar(track, fullscreen)`, and `closeRightbar`. The store owns the single frame-width measurement, width preferences, and the occupant's presentation report. The `rightbar` owner supplies actual `width`, `viewportWidth`, and normal-presentation eligibility `canShow`; insufficient room causes a deterministic close, never automatic reopening on widening. Fullscreen hides the width handle without releasing a track the occupant retains. AppFrame always mounts the conversation and right columns; a connected Session renders through `SessionProvider`, and without one the right column is an empty zero-width track. It projects the selected Session title over the build-configured product title or the localized `common.brand.localBuild` fallback, so locale revisions update document metadata with the root entry. The theme presenter is a second effect: pure DOM writes from resolved snapshots — initial state through the getter once, then event-driven only, with no React path. It applies palette, font-size, and token variables before measuring the rendered background as the single color authority. Fullscreen presentation suppresses grid and handle transitions; its occupant reports the new columns only after covering the frame. Fullscreen exit keeps transitions suppressed while the frame installs its destination geometry: close removes the right track, and restore retains it. Subsequent normal geometry actions restore ordinary transitions.
 
 </details>
 
@@ -51,7 +51,8 @@ One `register()` call contributes `AppFrame` into the runtime's built-in `'root'
 Read these pages when the layout surface is not enough. They move from the frame to the columns it renders and the theme it presents.
 
 - [ui-sidebar](../ui-sidebar/README.md) — occupies the `sidebar` column and its seats.
-- [ui-conversation](../ui-conversation/README.md) — occupies the `conversation` and `details` columns.
+- [ui-conversation](../ui-conversation/README.md) — occupies the `conversation` column.
+- [ui-sidebar-right](../ui-sidebar-right/README.md) — occupies the `rightbar` column with one docking surface per session.
 - [ui-theme](../ui-theme/README.md) — the theme seam whose resolved snapshots the presenter consumes.
 - [Web client architecture](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md) — how browser plugin rows load and register slots.
 
@@ -73,8 +74,9 @@ None; this package neither assembles nor sends a provider request.
 
 These limits define the current layout behavior. They are current package constraints, not a general window-manager comparison or a task backlog.
 
-- **Panel geometry is transient** — reload restores the sidebar default and details closed; switching between distinct Session ids also closes details and forgets its dragged width, while unselected surfaces render details at zero width without modifying geometry.
-- **Concession-chain auto-close derives a zero width without touching the preferred width** — the panel restores itself when the window widens; consumers must not read the stored details width as the rendered truth.
+- **Panel geometry is transient** — reload restores the sidebar default and the right panel hidden; each dragged width is one frame-wide preference, not a per-Session fact.
+- **Extremely narrow windows** — after the right panel closes, the center may still fall below 400px; the left 56px rail remains.
+- **Track and panel travel on one shared curve** — the frame's track transition and the occupant's slide read the same duration and easing variables; an occupant that used its own would detach the panel's edge from the conversation's while squeezing.
 - **No scroll anchoring during squeeze reflow** — layout changes may move the reader's viewport.
 
 <a id="dev-note"></a>
@@ -87,4 +89,4 @@ None.
 
 </details>
 
-**Runtime invariant:** No companion is published. The shell viewing-state store behind ctx.layout emits no cordis events; clamp/prune/concession-chain sequencing is asserted directly by this package's columns and service specs.
+**Runtime invariant:** No companion is published. The shell viewing-state store behind ctx.layout emits no cordis events; clamp and track sequencing is asserted directly by this package's columns and service specs.
diff --git a/packages/client/ui-layout/README.zh.md b/packages/client/ui-layout/README.zh.md
index 801346967f..16471fdabb 100644
--- a/packages/client/ui-layout/README.zh.md
+++ b/packages/client/ui-layout/README.zh.md
@@ -1,5 +1,5 @@
 ---
-description: "Web GUI 的外壳布局：三栏 AppFrame、拖动手柄与让步行为、面板几何服务与主题呈现；供窗口外观的用户与维护者阅读。"
+description: "Web GUI 的外壳布局：三栏 AppFrame——其右栏是贴边面板的轨道——面板几何服务与主题呈现；供窗口外观的用户与维护者阅读。"
 kind: "package-reference"
 ---
 
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-本包提供 Web GUI 的外壳布局：一个三栏 AppFrame，带可缩放的侧栏与详情面板；一条让步链，在空间不足时先收缩详情栏、随后自动关闭它；以及 `ctx.layout` 面板几何服务，供其他插件调用以打开或关闭详情栏。它还承载主题呈现器，把解析后的配色方案、别名 token、正文字号与 `theme-color` 元数据投影到 document。需要标准窗口外观时选择它；面板几何是瞬时的，重新加载即重置。
+本包提供 Web GUI 的三栏 AppFrame、左右栏宽度与 `ctx.layout` 呈现控制。右栏先让步以保护中栏空间，全屏由占用方呈现，框架保留宽屏底层轨道。主题呈现器负责配色、别名 token、正文字号与 document 元数据；布局状态在刷新后重置。
 
 ## 目录
 
@@ -25,7 +25,7 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-在 root 槽位挂载本插件；它随即围绕占据侧栏、会话与详情栏的内容渲染应用框架。用户拖动不可见命中条带缩放侧栏、拖动浮动胶囊缩放详情面板；窗口变窄时只有详情栏收缩，随后自动关闭。关闭的侧栏保留 56px 控制栏；详情栏关闭到零宽度。
+本插件在 root slot 组合侧栏、会话与右栏。左栏为264～420px，默认280px，收起后保留56px；窗口低于1024px时自动收起，打开右栏也会收起手动展开的左栏。右栏首次打开使用窗口宽度的45%，之后保留用户像素偏好，上限为70%；中栏不足400px时先把右栏压到300px，仍不足则通知占用方收起，最后才继续压缩中栏。拖拽跟手且无过渡延迟，关闭或全屏时不显示右栏拖拽区。
 
 ### 主题呈现
 
@@ -39,7 +39,7 @@ kind: "package-reference"
 <details>
 <summary>实现细节——点击展开</summary>
 
-一次 `register()` 调用把 `AppFrame` 贡献进运行时的内建 `'root'` 槽位，并在同一刻声明四个子槽位（`sidebar`、`conversation`、`details`、`shell.overlay`）、安放布局 store（面板几何）并接好 `ctx.layout` 面板动作服务。瞬时布局 store 以默认宽度启动侧栏、保持详情栏关闭，从不读写 `localStorage`。AppFrame 始终挂载会话与详情两栏；已连接 Session 经 `SessionProvider` 渲染。它把所选 Session 标题投影到构建配置的产品标题或本地化 `common.brand.localBuild` 回退值之上，因此 locale revision 会随根 entry 一起更新文档元数据。主题呈现器是第二个 effect：从解析后的快照做纯 DOM 写入——初始状态经 getter 读取一次，此后仅事件驱动，不经过 React。它先应用调色板、字号与 token 变量，再把渲染出的背景测量为唯一的颜色依据。
+一次注册声明四个子slot并绑定 `ctx.layout` 的 `toggleSidebar`、`openRightbar(track, fullscreen)` 与 `closeRightbar`。store持有唯一的frame宽度测量、左右栏偏好及占用方报告的呈现状态。`rightbar` 的owner参数为实际 `width`、`viewportWidth` 与普通呈现的 `canShow`；占用方在空间不足时执行确定性的收起，变宽不自行重新展开。全屏隐藏宽度手柄，但不自行释放占用方要求保留的轨道。AppFrame 始终挂载会话与右栏；已连接 Session 经 `SessionProvider` 渲染，没有 Session 时右栏是一条空的零宽轨道。它把所选 Session 标题投影到构建配置的产品标题或本地化 `common.brand.localBuild` 回退值之上，因此 locale revision 会随根 entry 一起更新文档元数据。主题呈现器是第二个 effect：从解析后的快照做纯 DOM 写入——初始状态经 getter 读取一次，此后仅事件驱动，不经过 React。它先应用调色板、字号与 token 变量，再把渲染出的背景测量为唯一的颜色依据。 全屏呈现禁用网格和手柄过渡；占用方完全覆盖框架后才报告新的列宽。 退出全屏时，框架先保持无过渡并安装目标布局：关闭移除右轨道，恢复保留右轨道。后续普通几何操作恢复正常过渡。
 
 </details>
 
@@ -51,7 +51,8 @@ kind: "package-reference"
 当布局面不够用时阅读以下页面。它们从框架进入它所渲染的栏与它所呈现的主题。
 
 - [ui-sidebar](../ui-sidebar/README.zh.md)——占据 `sidebar` 栏及其座位。
-- [ui-conversation](../ui-conversation/README.zh.md)——占据 `conversation` 与 `details` 栏。
+- [ui-conversation](../ui-conversation/README.zh.md)——占据 `conversation` 栏。
+- [ui-sidebar-right](../ui-sidebar-right/README.zh.md)——以每会话一个停靠面占据 `rightbar` 栏。
 - [ui-theme](../ui-theme/README.zh.md)——呈现器消费其解析快照的主题 seam。
 - [Web 客户端架构](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md)——浏览器插件行如何加载并注册槽位。
 
@@ -73,8 +74,9 @@ kind: "package-reference"
 
 这些限制界定了当前布局行为。它们是当前包约束，不是通用窗口管理器对比或任务积压。
 
-- **面板几何是瞬时状态**——重新加载会恢复侧栏默认值并保持详情栏关闭；在不同会话 id 之间切换同样会关闭详情栏并忘记拖动后的宽度，而未选中表面以零宽度渲染详情栏却不修改几何。
-- **让步链自动关闭通过推导零宽度实现，不触碰偏好宽度**——窗口变宽时面板自行恢复；消费方不得把 store 中的详情宽度当作渲染真值。
+- **面板几何是瞬时状态**——重新加载会恢复侧栏默认值并隐藏右侧面板；每个拖出的宽度都是一份框架级偏好，不是按 Session 的事实。
+- **极窄窗口**——右栏关闭后，中栏仍可能小于400px；左侧56px控制栏保留。
+- **轨道与面板沿同一条曲线运动**——框架的轨道过渡和占位方的滑入读取同一组时长与缓动变量；占位方若自用一套，挤压时面板边缘就会与对话边缘脱开。
 - **挤压重排期间无滚动锚定**——布局变化可能移动读者的视口。
 
 <a id="dev-note"></a>
@@ -87,4 +89,4 @@ kind: "package-reference"
 
 </details>
 
-**运行时不变式：** 不发布伴生入口。`ctx.layout` 后的 viewing-state store 不发出 Cordis 事件；clamp、prune 与 concession-chain 顺序由本包测试覆盖。
+**运行时不变式：** 不发布伴生入口。`ctx.layout` 后的 viewing-state store 不发出 Cordis 事件；clamp 与轨道的时序由本包的 columns 与 service 规格直接断言。
diff --git a/packages/client/ui-layout/src/client/AppFrame.module.css b/packages/client/ui-layout/src/client/AppFrame.module.css
index 9ba4e82be6..5a4f131e5b 100644
--- a/packages/client/ui-layout/src/client/AppFrame.module.css
+++ b/packages/client/ui-layout/src/client/AppFrame.module.css
@@ -36,21 +36,12 @@
   overflow: hidden;
 }
 
-.detailsCol {
-  min-width: 0;
-  overflow: hidden;
-  border-left: 0.5px solid var(--dsw-alias-border-l3);
-}
-
-/* The details subtree stays mounted at zero width, so its border must not paint
-   a 1px seam. The collapsed sidebar instead retains a bordered compact rail. */
-.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. Details
-   adds a visible 12x32 pill at vertical center; sidebar keeps only the hit strip. */
+   centered on the column border via inline left, above column content. No
+   handle draws a visible pill: the details column was the only one that did,
+   and the right column never had one. The right handle sits above the right
+   panel (which states z-index 10) so it stays grabbable when the panel hangs
+   over the centre. */
 .handle {
   position: absolute;
   top: 0;
@@ -58,7 +49,7 @@
   width: 8px;
   margin-left: -4px;
   cursor: col-resize;
-  z-index: 2;
+  z-index: 11;
   touch-action: none;
   /* Rides the same curve as the tracks so the pill stays on the moving
      border during collapse/expand; paused while dragging (frame rule). */
@@ -69,42 +60,31 @@
   transition: none;
 }
 
+/* Fullscreen covers the frame while its underlying columns enter or exit. */
+.frame[data-rightbar-fullscreen],
+.frame[data-rightbar-fullscreen] .handle,
+.frame[data-rightbar-instant],
+.frame[data-rightbar-instant] .handle {
+  transition: none;
+}
+
 @media (prefers-reduced-motion: reduce) {
   .handle {
     transition: none;
   }
 }
 
-.handle[data-side='details']::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-button-floating-fill);
-  border: 0.5px solid var(--dsw-alias-border-l2-darkmode-thin);
-  /* Hover affordance: the details pill hides until the pointer is over its
-     column, the strip itself, or a drag. */
-  opacity: 0;
-  transition:
-    opacity var(--ds-transition-duration-slow) var(--ds-ease-in-out),
-    background var(--ds-transition-duration-slow) var(--ds-ease-in-out);
-}
-
-.detailsCol:hover ~ .handle[data-side='details']::after,
-.handle[data-side='details']:hover::after,
-.handle[data-side='details'][data-dragging='true']::after {
-  opacity: 1;
-}
-
-.handle[data-side='details']:hover::after,
-.handle[data-side='details'][data-dragging='true']::after {
-  background: var(--dsw-alias-button-floating-hover);
-  border-color: var(--dsw-alias-border-l3);
+/*
+ * The right column never clips: its occupant anchors a fixed-width panel to the
+ * column's right edge (the frame's edge, which never moves) and lets the track
+ * decide whether the centre makes room. With no track the panel hangs over the
+ * centre from a zero-width column, and while the track animates the panel stays
+ * where it is. The occupant draws its own left border.
+ */
+.rightbarCol {
+  position: relative;
+  min-width: 0;
+  overflow: visible;
 }
 
 .overlayLayer {
diff --git a/packages/client/ui-layout/src/client/AppFrame.tsx b/packages/client/ui-layout/src/client/AppFrame.tsx
index cbef893aed..905341f503 100644
--- a/packages/client/ui-layout/src/client/AppFrame.tsx
+++ b/packages/client/ui-layout/src/client/AppFrame.tsx
@@ -1,21 +1,26 @@
 /**
  * Three-column shell frame, registered into the built-in 'root' slot (the web
  * shell renders only 'root'). Owns the grid tracks (sidebar | center |
- * details), the drag handles (pointer capture + rAF throttle), the concession
- * chain (columns.ts), and the child-slot render decisions: the sidebar slot
- * renders HERE with live parameters from the concession solve, and the
- * session-aware occupants render in fixed column positions; strict entries
- * gate themselves on current-session availability while session-maybe
- * entries retain identity. Pure component: everything arrives
- * through the three framework shares — zero cordis or framework imports,
- * zero self-made hooks.
+ * rightbar), the drag handles (pointer capture + rAF throttle), the column
+ * solve (columns.ts), and the child-slot render decisions: the sidebar slot
+ * renders HERE with live parameters from that solve, and the session-aware
+ * occupants render in fixed column positions; the strict right-column entry
+ * gates itself on current-session availability while the session-maybe
+ * conversation retains identity.
+ *
+ * The right column is a track, not a box: its occupant draws its panel anchored
+ * to the frame's right edge at the resolved normal width, and the
+ * track only decides whether the centre makes room for it. The occupant reports
+ * shown/track/fullscreen through `ctx.layout`; fullscreen keeps the reported
+ * track but hides the outer resize handle. Everything arrives through the framework
+ * shares — zero cordis or framework imports, zero self-made hooks.
  */
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
 import type { ReactNode } from 'react'
 import type {
   PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore,
 } from '@deepseek-ai/dsh-client-ui-slots'
-import { computeColumns, SIDEBAR_AUTO_COLLAPSE, SIDEBAR_DEFAULT } from './columns.ts'
+import { computeColumns, RIGHTBAR_DEFAULT_RATIO, SIDEBAR_AUTO_COLLAPSE, SIDEBAR_DEFAULT } from './columns.ts'
 import { DocumentTitle } from './DocumentTitle.tsx'
 import type { createLayoutStore } from './stores.ts'
 import css from './AppFrame.module.css'
@@ -23,7 +28,7 @@ import css from './AppFrame.module.css'
 /** Full composed props: runtime share + child-slot render share + store share. */
 export type AppFrameProps =
   & PropsRuntime<'root'>
-  & PropsRenderSlots<'sidebar' | 'conversation' | 'details' | 'shell.overlay'>
+  & PropsRenderSlots<'sidebar' | 'conversation' | 'rightbar' | 'shell.overlay'>
   & PropsStore<ReturnType<typeof createLayoutStore>>
   & PropsLocale<'common'>
 
@@ -32,33 +37,51 @@ 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). */
-function DetailsColumn(props: { children?: ReactNode }) {
-  return <div className={css.detailsCol}>{props.children}</div>
+/**
+ * Right column grid item. Zero-width unless the occupant asked for a track; the
+ * occupant's panel is positioned against the column's right edge, which never
+ * moves, so it can hang over the centre when there is no track.
+ */
+function RightbarColumn(props: { children?: ReactNode }) {
+  return <div className={css.rightbarCol} data-rightbar-col>{props.children}</div>
 }
 
 /**
  * One drag handle: pointer capture, rAF-throttled dx reports against the drag-start origin.
  * `side` keys the hover-reveal CSS to the owning column.
  */
-function DragHandle(props: { side: 'sidebar' | 'details'; left: number; onStart: () => void; onDrag: (dx: number) => void; onEnd: () => void }) {
+function DragHandle(props: { side: 'sidebar' | 'rightbar'; left: number; onStart: () => void; onDrag: (dx: number) => void; onEnd: () => void }) {
   const [dragging, setDragging] = useState(false)
   const origin = useRef(0)
   const latest = useRef(0)
   const frame = useRef<number | null>(null)
+  const capture = useRef<{ element: HTMLDivElement; id: number } | null>(null)
   const callbacks = useRef({ onStart: props.onStart, onDrag: props.onDrag, onEnd: props.onEnd })
   callbacks.current = { onStart: props.onStart, onDrag: props.onDrag, onEnd: props.onEnd }
 
+  const endDrag = useCallback(() => {
+    const active = capture.current
+    if (active === null) return
+    capture.current = null
+    if (frame.current !== null) { cancelAnimationFrame(frame.current); frame.current = null }
+    if (active.element.hasPointerCapture(active.id)) active.element.releasePointerCapture(active.id)
+    setDragging(false)
+    callbacks.current.onEnd()
+  }, [])
+  useEffect(() => endDrag, [endDrag])
+
   const onPointerDown = useCallback((e: React.PointerEvent<HTMLDivElement>) => {
+    if (e.button !== 0 || capture.current !== null) return
     e.preventDefault()
     e.currentTarget.setPointerCapture(e.pointerId)
+    capture.current = { element: e.currentTarget, id: 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
+    if (capture.current?.id !== e.pointerId) return
     latest.current = e.clientX
     frame.current ??= requestAnimationFrame(() => {
       frame.current = null
@@ -66,13 +89,13 @@ function DragHandle(props: { side: 'sidebar' | 'details'; left: number; onStart:
     })
   }, [])
   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)
-    callbacks.current.onEnd()
-  }, [])
+    if (capture.current?.id !== e.pointerId) return
+    callbacks.current.onDrag(e.clientX - origin.current)
+    endDrag()
+  }, [endDrag])
+  const onPointerCancel = useCallback((e: React.PointerEvent<HTMLDivElement>) => {
+    if (capture.current?.id === e.pointerId) endDrag()
+  }, [endDrag])
 
   return (
     <div
@@ -83,6 +106,8 @@ function DragHandle(props: { side: 'sidebar' | 'details'; left: number; onStart:
       onPointerDown={onPointerDown}
       onPointerMove={onPointerMove}
       onPointerUp={onPointerUp}
+      onPointerCancel={onPointerCancel}
+      onLostPointerCapture={onPointerCancel}
     />
   )
 }
@@ -97,78 +122,71 @@ export function AppFrame({
   t,
 }: AppFrameProps) {
   const panels = useStore(s => s)
-  const detailsSession = useSessions((s) => {
-    const current = s.current
-    return current !== undefined && s.byId[current]?.blank === false ? current : undefined
-  })
   const documentTitle = useSessions((s) => {
     const current = s.current
     return current === undefined ? undefined : s.byId[current]?.title
   })
   const frameRef = useRef<HTMLDivElement | null>(null)
-  const [viewport, setViewport] = useState(() => window.innerWidth)
-
-  const lastSession = useRef(detailsSession)
-  useLayoutEffect(() => {
-    if (detailsSession === undefined) return
-    if (lastSession.current !== undefined && lastSession.current !== detailsSession) {
-      actions.closeDetails()
-    }
-    lastSession.current = detailsSession
-  }, [actions, detailsSession])
+  const viewport = panels.viewportWidth
 
   // Track the frame's own box (not the window): rAF-throttled ResizeObserver.
-  useEffect(() => {
+  useLayoutEffect(() => {
     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
+    let disposed = false
+    const measure = () => {
+      const width = el.getBoundingClientRect().width
+      if (width > 0) actions.setViewportWidth(width)
+    }
+    measure()
     const observer = new ResizeObserver(() => {
+      if (disposed) return
       raf ??= requestAnimationFrame(() => {
         raf = null
-        const width = el.getBoundingClientRect().width
-        if (width > 0) setViewport(width)
+        measure()
       })
     })
     observer.observe(el)
     return () => {
+      disposed = true
       observer.disconnect()
       if (raf !== null) cancelAnimationFrame(raf)
     }
-  }, [])
+  }, [actions])
 
-  // Narrow viewports auto-collapse the sidebar; the store mirror keeps
-  // toggleSidebar's semantics right (narrow toggles flip the manual
-  // re-expand override, stores.ts). Collapsed is decided here, so the
-  // solver stays breakpoint-free: a narrow re-expand passes the preference
-  // (or the default when the wide preference is closed) and the center
-  // absorbs the squeeze.
   const narrow = viewport < SIDEBAR_AUTO_COLLAPSE
-  useEffect(() => { actions.setNarrow(narrow) }, [actions, narrow])
   const sidebarCollapsed = narrow ? !panels.narrowExpanded : panels.sidebar === 0
   const sidebarPreference = sidebarCollapsed
     ? 0
     : panels.sidebar === 0 ? SIDEBAR_DEFAULT : panels.sidebar
-  const cols = computeColumns(viewport, sidebarPreference, detailsSession === undefined ? 0 : panels.details)
+  const rightbarPreference = panels.rightbar ?? viewport * RIGHTBAR_DEFAULT_RATIO
+  // Opening on a narrow frame collapses the left sidebar. Eligibility must
+  // include that space before the occupant's first shown report arrives.
+  const normal = computeColumns(viewport, !panels.rightbarShown && narrow ? 0 : sidebarPreference, rightbarPreference)
+  const cols = computeColumns(viewport, sidebarPreference, panels.rightbarTrack ? rightbarPreference : 0)
   const colsRef = useRef(cols)
   colsRef.current = cols
+  const rightbarWidth = useRef(normal.rightbar)
+  rightbarWidth.current = normal.rightbar
 
   // The drag base is the rendered width captured at drag start (grabbing a
   // concession-clamped panel must not jump back to the stored preference);
   // it stays frozen for the whole gesture so dx deltas do not compound.
   const sidebarBase = useRef(0)
-  const detailsBase = useRef(0)
+  const rightbarBase = useRef(0)
   // Track-level transitions pause for the whole gesture: eased tracks would
   // detach the column edge from the pointer (AppFrame.module.css).
   const [dragging, setDragging] = useState(false)
   const onDragEnd = useCallback(() => { setDragging(false) }, [])
   const onSidebarStart = useCallback(() => { sidebarBase.current = colsRef.current.sidebar; setDragging(true) }, [])
-  const onDetailsStart = useCallback(() => { detailsBase.current = colsRef.current.details; setDragging(true) }, [])
   const onSidebarDrag = useCallback((dx: number) => {
     actions.setSidebar(sidebarBase.current + dx)
   }, [actions])
-  const onDetailsDrag = useCallback((dx: number) => {
-    actions.setDetails(detailsBase.current - dx)
+  const onRightbarStart = useCallback(() => { rightbarBase.current = rightbarWidth.current; setDragging(true) }, [])
+  const onRightbarDrag = useCallback((dx: number) => {
+    actions.setRightbar(rightbarBase.current - dx)
   }, [actions])
   const productTitle = process.env.DSH_CLIENT_TITLE ?? t('brand.localBuild')
 
@@ -176,9 +194,14 @@ export function AppFrame({
     <div
       ref={frameRef}
       className={css.frame}
-      style={{ gridTemplateColumns: `${cols.sidebar}px minmax(0, 1fr) ${cols.details}px` }}
+      style={{
+        gridTemplateColumns:
+          `${cols.sidebar}px minmax(0, 1fr) ${cols.rightbar}px`,
+      }}
       data-sidebar-collapsed={sidebarCollapsed || undefined}
-      data-details-collapsed={cols.details === 0 || undefined}
+      data-rightbar-collapsed={cols.rightbar === 0 || undefined}
+      data-rightbar-fullscreen={panels.rightbarFullscreen || undefined}
+      data-rightbar-instant={panels.rightbarInstant || undefined}
       data-dragging={dragging || undefined}
     >
       <DocumentTitle
@@ -199,20 +222,27 @@ export function AppFrame({
       <>
         {/* Both column occupants stay at fixed tree positions from first
             paint — no loading gate: a bare status line reads worse than
-            the shell's own pending rendering. The conversation
-            is session-maybe; SessionProvider withholds the strict details
+            the shell's own pending rendering. The conversation is
+            session-maybe; SessionProvider withholds the strict right-column
             entry while no session is current. */}
         <CenterColumn>{renderSlot('conversation', {})}</CenterColumn>
-        <DetailsColumn>
-          <SessionProvider>{renderSlot('details', {})}</SessionProvider>
-        </DetailsColumn>
+        <RightbarColumn>
+          {/* Strict session entry: with no session there is no surface, and the
+              column is an empty zero-width track. The occupant receives the
+              panel width it should draw at; the track is the frame's business. */}
+          <SessionProvider>
+            {renderSlot('rightbar', { width: normal.rightbar, viewportWidth: viewport, canShow: normal.rightbar > 0 })}
+          </SessionProvider>
+        </RightbarColumn>
       </>
       <div className={css.overlayLayer} data-shell-overlay>
         {renderSlot('shell.overlay', {})}
       </div>
       {/* The collapsed rail is fixed-width: no resize handle while closed. */}
       {!sidebarCollapsed && <DragHandle side="sidebar" left={cols.sidebar} onStart={onSidebarStart} onDrag={onSidebarDrag} onEnd={onDragEnd} />}
-      {cols.details > 0 && <DragHandle side="details" left={viewport - cols.details} onStart={onDetailsStart} onDrag={onDetailsDrag} onEnd={onDragEnd} />}
+      {panels.rightbarShown && !panels.rightbarFullscreen && normal.rightbar > 0 && (
+        <DragHandle side="rightbar" left={viewport - normal.rightbar} onStart={onRightbarStart} onDrag={onRightbarDrag} onEnd={onDragEnd} />
+      )}
     </div>
   )
 }
diff --git a/packages/client/ui-layout/src/client/columns.ts b/packages/client/ui-layout/src/client/columns.ts
index 374ce64703..a58b284255 100644
--- a/packages/client/ui-layout/src/client/columns.ts
+++ b/packages/client/ui-layout/src/client/columns.ts
@@ -1,24 +1,14 @@
 /**
- * Pure concession-chain column solver for the three-column AppFrame.
- * Chain order is fixed by contract: keep center >= CENTER_MIN by shrinking
- * details, then auto-closing it (derived zero width — preferred width
- * preferences are never rewritten, so widening the window restores them).
- * The sidebar never concedes: its rendered width is always the drag
- * preference (or the collapsed rail), and center absorbs any remaining
- * deficit as the last resort. Inputs are the layout store's plain width
- * preferences (0 = closed); a closed sidebar resolves to the fixed
- * SIDEBAR_COLLAPSED control rail while closed details resolve to zero width.
- * The SIDEBAR_AUTO_COLLAPSE breakpoint is consumed by AppFrame, which decides
- * the effective sidebar preference before solving; the solver itself stays
- * breakpoint-free.
+ * Normal column geometry: the right column shrinks, then loses its track,
+ * before the center drops below its minimum. The sidebar never concedes here;
+ * AppFrame supplies its effective preference after responsive collapse.
  */
 
-/** 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 }
+/** Resolved widths for one frame. */
+export interface Columns { sidebar: number; center: number; rightbar: 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
+/** Center width protected while the normal right column is open. */
+export const CENTER_MIN = 400
 /** Sidebar drag clamp floor. */
 export const SIDEBAR_MIN = 264
 /** Sidebar drag clamp ceiling. */
@@ -31,12 +21,12 @@ export const SIDEBAR_COLLAPSED = 56
  * LG breakpoint); a manual toggle below it re-expands over the squeezed center
  * (stores.ts narrowExpanded). */
 export const SIDEBAR_AUTO_COLLAPSE = 1024
-/** 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
+/** Right column drag clamp floor. */
+export const RIGHTBAR_MIN = 300
+/** Maximum normal right panel width as a fraction of the frame. */
+export const RIGHTBAR_MAX_RATIO = 0.7
+/** First-open right panel preference as a fraction of the frame. */
+export const RIGHTBAR_DEFAULT_RATIO = 0.45
 
 /**
  * Clamp a panel width into its contract range.
@@ -50,28 +40,18 @@ export function clampWidth(px: number, min: number, max: number): number {
 }
 
 /**
- * Solve the three column widths for one viewport frame. Pure: no hysteresis —
- * the output is a function of (viewport, preferences) only, so recovery on
- * re-widening is automatic. Preferences re-clamp here because they cross the
- * store boundary and callers may still supply stale ranges.
+ * Solve the three column widths for one viewport frame.
  * @param viewport - available frame width in px.
  * @param sidebar - sidebar width preference in px (0 = closed).
- * @param details - details width preference in px (0 = closed).
- * @returns resolved widths; details 0 means visually closed (never unmounted), while a closed sidebar keeps its compact rail.
+ * @param rightbar - requested right panel width in px (0 = no track).
+ * @returns actual widths after shrinking or removing the right track; only
+ *   without that track may the center fall below its minimum, down to zero.
  */
-export function computeColumns(viewport: number, sidebar: number, details: number): Columns {
-  // The sidebar is fixed at its preference (or the rail) — it never concedes.
+export function computeColumns(viewport: number, sidebar: number, rightbar: number): Columns {
   const s = sidebar === 0 ? SIDEBAR_COLLAPSED : clampWidth(sidebar, SIDEBAR_MIN, SIDEBAR_MAX)
-  const d0 = details === 0 ? 0 : clampWidth(details, DETAILS_MIN, DETAILS_MAX)
-
-  // Step 1: everything fits at preferred widths.
-  if (s + d0 + CENTER_MIN <= viewport) return { sidebar: s, center: viewport - s - d0, details: d0 }
-
-  // Step 2: shrink details toward its minimum.
-  const d1 = d0 === 0 ? 0 : Math.max(DETAILS_MIN, viewport - s - CENTER_MIN)
-  if (s + d1 + CENTER_MIN <= viewport) return { sidebar: s, center: CENTER_MIN, details: d1 }
-
-  // Step 3: auto-close details (derived — preferences untouched); center
-  // absorbs any remaining deficit (may drop below CENTER_MIN).
-  return { sidebar: s, center: Math.max(0, viewport - s), details: 0 }
+  const available = viewport - s - CENTER_MIN
+  const r = rightbar === 0 || available < RIGHTBAR_MIN
+    ? 0
+    : Math.min(available, clampWidth(rightbar, RIGHTBAR_MIN, viewport * RIGHTBAR_MAX_RATIO))
+  return { sidebar: s, center: Math.max(0, viewport - s - r), rightbar: r }
 }
diff --git a/packages/client/ui-layout/src/client/index.ts b/packages/client/ui-layout/src/client/index.ts
index 56afec15e3..649215b96d 100644
--- a/packages/client/ui-layout/src/client/index.ts
+++ b/packages/client/ui-layout/src/client/index.ts
@@ -64,15 +64,19 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      */
     'conversation': { kind: 'single'; scope: 'session-maybe'; owner: ConvOwnerProps }
     /**
-     * The right details column, shown when the layout opens it. OCCUPIED by
-     * ui-conversation's DetailsPanel, which declares the tool-details seat
-     * inside it — registering here replaces the column and takes that seat
-     * with it. Absent an occupant the column renders nothing.
+     * The right column: a track the centre makes room for, or nothing. OCCUPIED
+     * by the right Sidebar, which uses the resolved column width in normal
+     * mode and covers the viewport in fullscreen, retaining the wide-screen
+     * column reservation underneath.
      *
-     * No owner props: the framework injects the session id and hooks for the
-     * `session` scope, and `ctx.layout` owns whether the column is open.
+     * Whether the panel is shown, and whether it takes a track, is the
+     * occupant's own recorded business — it reports the composition of its
+     * expanded and presentation state through `ctx.layout`, and the frame sizes
+     * the track and places the resize handle from that. The expand control is
+     * not this column's: it is a button in the conversation header. With no
+     * current session nothing is mounted here.
      */
-    'details': { kind: 'single'; scope: 'session'; owner: DetailsOwnerProps }
+    'rightbar': { kind: 'single'; scope: 'session'; owner: RightbarOwnerProps }
     /**
      * Frame-wide floating layer, above every column and outside their scroll
      * containers. Deliberately generic and unowned by any feature: a badge, a
@@ -104,8 +108,18 @@ export interface SidebarOwnerProps {
 /** Conversation owner share: business state and actions belong to the registrant. */
 export interface ConvOwnerProps {}
 
-/** Details owner share: empty — sessionId arrives as a framework-standard prop. */
-export interface DetailsOwnerProps {}
+/** Right column owner share: resolved normal geometry and opening eligibility. */
+export interface RightbarOwnerProps {
+  /** Resolved normal panel width in px, not the saved preference; zero if it cannot fit. */
+  width: number
+  /** Current frame width in px. */
+  viewportWidth: number
+  /**
+   * Whether a normal right panel can retain 300px beside a 400px center.
+   * Before a narrow opening, includes the space from collapsing the left sidebar.
+   */
+  canShow: boolean
+}
 
 /** Required services (cordis fiber inject — the loader passes all module exports as an object plugin). */
 export const inject = ['slots', 'theme', 'locale']
@@ -126,7 +140,7 @@ export function apply(ctx: ClientContext): void {
       children: {
         'sidebar': { kind: 'single', scope: 'root' },
         'conversation': { kind: 'single', scope: 'session-maybe' },
-        'details': { kind: 'single', scope: 'session' },
+        'rightbar': { kind: 'single', scope: 'session' },
         'shell.overlay': { kind: 'list', scope: 'root' },
       },
       // Exclusive store: the factory itself — the framework instantiates per
diff --git a/packages/client/ui-layout/src/client/service.ts b/packages/client/ui-layout/src/client/service.ts
index 2b2e50e5d5..46369f0346 100644
--- a/packages/client/ui-layout/src/client/service.ts
+++ b/packages/client/ui-layout/src/client/service.ts
@@ -5,8 +5,8 @@
  * the per-session active view dissolved into ui-conversation's session store
  * (its only consumer). What remains here is the contract other plugins'
  * apply worlds reach for panel transitions (sidebar toggle from ui-sidebar,
- * details open/close from ui-conversation) — writes stay inside the store's
- * declared action set, delivered as the registration's bound actions.
+ * right-panel show/hide from ui-sidebar-right) — writes stay inside the
+ * store's declared action set, delivered as the registration's bound actions.
  */
 import type { BoundActions } from '@deepseek-ai/dsh-client-ui-slots'
 import type { createLayoutStore } from './stores.ts'
@@ -23,10 +23,16 @@ export type PanelActions = BoundActions<ReturnType<typeof createLayoutStore>>
 export interface ILayout {
   /** Toggle the sidebar panel (closed ⟷ contract default width). */
   toggleSidebar(): void
-  /** Open the details panel (no-op when already open). */
-  openDetails(): void
-  /** Close the details panel. */
-  closeDetails(): void
+  /**
+   * Report the right panel's presentation without changing its expanded state.
+   * @param track - whether the normal panel width reserves a grid track,
+   *   including beneath a fullscreen overlay.
+   * @param fullscreen - whether the panel covers the frame and hides its outer
+   *   resize handle; independent of the underlying grid track.
+   */
+  openRightbar(track: boolean, fullscreen: boolean): void
+  /** Report the right panel as hidden: no track, no handle. */
+  closeRightbar(): void
 }
 
 /** Cross-plugin panel-action face (ctx.layout). */
@@ -49,14 +55,14 @@ export class LayoutController implements ILayout {
     this.#require().toggleSidebar()
   }
 
-  /** Open the details panel (no-op when already open). */
-  openDetails(): void {
-    this.#require().openDetails()
+  /** Report the right panel's track and fullscreen presentation. */
+  openRightbar(track: boolean, fullscreen: boolean): void {
+    this.#require().openRightbar(track, fullscreen)
   }
 
-  /** Close the details panel. */
-  closeDetails(): void {
-    this.#require().closeDetails()
+  /** Report the right panel as hidden: no track, no handle. */
+  closeRightbar(): void {
+    this.#require().closeRightbar()
   }
 
   #require(): PanelActions {
diff --git a/packages/client/ui-layout/src/client/stores.ts b/packages/client/ui-layout/src/client/stores.ts
index 7b6e2807ee..9191745a66 100644
--- a/packages/client/ui-layout/src/client/stores.ts
+++ b/packages/client/ui-layout/src/client/stores.ts
@@ -1,26 +1,46 @@
 /**
- * The root entry's transient layout store: panel geometry as plain widths in
- * px (0 = closed). Module level exports the factory only — a module-level
- * handle would pin the store's identity in the module
- * cache (a de-facto singleton surviving plugin reloads). register() receives
- * the factory (exclusive use: the framework instantiates per entry), AppFrame
- * derives its PropsStore share from the return type, and the service face
- * receives the bound actions through the registration's inject hook.
+ * Root-owned frame measurement, panel preferences, and presentation reports.
+ * The registration supplies a fresh store and binds its actions to ctx.layout.
  */
 import { defineStore, type EngineStoreHandle } from '@deepseek-ai/dsh-client-store'
 import {
-  clampWidth, DETAILS_DEFAULT, DETAILS_MAX, DETAILS_MIN,
-  SIDEBAR_DEFAULT, SIDEBAR_MAX, SIDEBAR_MIN,
+  clampWidth, RIGHTBAR_DEFAULT_RATIO, RIGHTBAR_MAX_RATIO, RIGHTBAR_MIN,
+  SIDEBAR_AUTO_COLLAPSE, SIDEBAR_DEFAULT, SIDEBAR_MAX, SIDEBAR_MIN,
 } from './columns.ts'
 
 /**
- * Layout store state: panel width preferences in px (0 = closed), plus the
- * narrow-viewport pair — `narrow` mirrors AppFrame's breakpoint reading
- * (viewport < SIDEBAR_AUTO_COLLAPSE) so toggleSidebar can pick semantics, and
- * `narrowExpanded` is the manual override that re-expands the auto-collapsed
- * sidebar over the squeezed center without rewriting the width preference.
+ * Transient layout preferences. Responsive concessions never rewrite widths;
+ * the right panel's expanded state belongs to its occupant.
  */
-type LayoutState = { sidebar: number; details: number; narrow: boolean; narrowExpanded: boolean }
+type LayoutState = {
+  sidebar: number
+  /** Last positive frame measurement; window width bootstraps the first render. */
+  viewportWidth: number
+  narrowExpanded: boolean
+  /**
+   * Saved right panel width in px, or null before its first opening. Resizing
+   * the frame and closing the panel preserve this preference.
+   */
+  rightbar: number | null
+  /**
+   * Whether the right panel is drawn at all, in either presentation.
+   *
+   * Derived chrome, not a source of truth: whether the right surface is
+   * expanded is a recorded fact owned by that surface, reported here so the
+   * frame can place the panel's resize handle. The occupant reports it; nothing
+   * else writes it.
+   */
+  rightbarShown: boolean
+  /**
+   * Whether the normal panel width reserves a grid track, including beneath
+   * fullscreen. Reported by the occupant; always false while hidden.
+   */
+  rightbarTrack: boolean
+  /** Reported fullscreen presentation; hides the outer resize handle. */
+  rightbarFullscreen: boolean
+  /** Suppress transitions for a fullscreen exit until another geometry action. */
+  rightbarInstant: boolean
+}
 
 /**
  * Annotation twin of the actions literal below (the export needs a declared
@@ -28,44 +48,76 @@ type LayoutState = { sidebar: number; details: number; narrow: boolean; narrowEx
  */
 type LayoutActions = {
   setSidebar: (draft: LayoutState, px: number) => void
-  setDetails: (draft: LayoutState, px: number) => void
   toggleSidebar: (draft: LayoutState) => void
-  setNarrow: (draft: LayoutState, narrow: boolean) => void
-  openDetails: (draft: LayoutState) => void
-  closeDetails: (draft: LayoutState) => void
+  setViewportWidth: (draft: LayoutState, width: number) => void
+  setRightbar: (draft: LayoutState, px: number) => void
+  openRightbar: (draft: LayoutState, track: boolean, fullscreen: boolean) => void
+  closeRightbar: (draft: LayoutState) => void
 }
 
 /**
- * Create the layout panel store handle. The preference IS the width, so
- * closing a panel forgets its drag width — reopening restores the contract
- * default. Actions are the complete write set: drag writes clamp
- * into the panel's contract range and never cross the open/closed line;
- * open/close transitions write 0 / the default explicitly. Below the
- * auto-collapse breakpoint (AppFrame feeds setNarrow) the sidebar toggle
- * flips the narrowExpanded override instead of the preference.
+ * Create the layout panel store handle. For the sidebar the preference IS the
+ * width, so closing it forgets its drag width — reopening restores the contract
+ * default. The right panel initializes at 45% of the frame on first opening
+ * and keeps that px preference across resizes and close. Drag writes clamp to
+ * the current frame's range. Narrow sidebar toggles change only the expansion
+ * override; opening the right panel clears that override.
  * @returns the store handle (spec + type + identity + factory in one).
  */
 export function createLayoutStore(): EngineStoreHandle<LayoutState, LayoutActions>  {
   const handle = defineStore({
-    init: (): LayoutState => ({ sidebar: SIDEBAR_DEFAULT, details: 0, narrow: false, narrowExpanded: false }),
+    init: (): LayoutState => ({
+      sidebar: SIDEBAR_DEFAULT,
+      viewportWidth: window.innerWidth,
+      narrowExpanded: false,
+      rightbar: null,
+      rightbarShown: false,
+      rightbarTrack: false,
+      rightbarFullscreen: false,
+      rightbarInstant: false,
+    }),
     actions: {
-      setSidebar: (d, px: number) => { d.sidebar = clampWidth(px, SIDEBAR_MIN, SIDEBAR_MAX) },
-      setDetails: (d, px: number) => { d.details = clampWidth(px, DETAILS_MIN, DETAILS_MAX) },
+      setSidebar: (d, px: number) => {
+        d.rightbarInstant = false
+        d.sidebar = clampWidth(px, SIDEBAR_MIN, SIDEBAR_MAX)
+      },
       // Narrow toggles flip only the override: the width preference survives
       // untouched, so re-widening restores the pre-squeeze layout.
       toggleSidebar: (d) => {
-        if (d.narrow) d.narrowExpanded = !d.narrowExpanded
+        d.rightbarInstant = false
+        if (d.viewportWidth < SIDEBAR_AUTO_COLLAPSE) d.narrowExpanded = !d.narrowExpanded
         else d.sidebar = d.sidebar === 0 ? SIDEBAR_DEFAULT : 0
       },
       // Crossing the breakpoint in either direction drops the override: the
       // narrow default is auto-collapsed, the wide state is the preference.
-      setNarrow: (d, narrow: boolean) => {
-        if (d.narrow === narrow) return
-        d.narrow = narrow
-        d.narrowExpanded = false
+      setViewportWidth: (d, width: number) => {
+        if (d.viewportWidth === width) return
+        d.rightbarInstant = false
+        if ((d.viewportWidth < SIDEBAR_AUTO_COLLAPSE) !== (width < SIDEBAR_AUTO_COLLAPSE)) {
+          d.narrowExpanded = false
+        }
+        d.viewportWidth = width
+      },
+      setRightbar: (d, px: number) => {
+        d.rightbarInstant = false
+        d.rightbar = clampWidth(px, RIGHTBAR_MIN, Math.max(RIGHTBAR_MIN, d.viewportWidth * RIGHTBAR_MAX_RATIO))
+      },
+      openRightbar: (d, track: boolean, fullscreen: boolean) => {
+        if (!d.rightbarShown || d.rightbarTrack !== track || d.rightbarFullscreen !== fullscreen) {
+          d.rightbarInstant = d.rightbarFullscreen && !fullscreen
+        }
+        if (!d.rightbarShown && d.viewportWidth < SIDEBAR_AUTO_COLLAPSE) d.narrowExpanded = false
+        d.rightbar ??= Math.max(RIGHTBAR_MIN, Math.round(d.viewportWidth * RIGHTBAR_DEFAULT_RATIO))
+        d.rightbarShown = true
+        d.rightbarTrack = track
+        d.rightbarFullscreen = fullscreen
+      },
+      closeRightbar: (d) => {
+        if (d.rightbarShown) d.rightbarInstant = d.rightbarFullscreen
+        d.rightbarShown = false
+        d.rightbarTrack = false
+        d.rightbarFullscreen = false
       },
-      openDetails: (d) => { if (d.details === 0) d.details = DETAILS_DEFAULT },
-      closeDetails: (d) => { d.details = 0 },
     },
   })
   return handle
diff --git a/packages/client/ui-layout/tests/app-frame.client.spec.tsx b/packages/client/ui-layout/tests/app-frame.client.spec.tsx
index a640480360..62623b9b81 100644
--- a/packages/client/ui-layout/tests/app-frame.client.spec.tsx
+++ b/packages/client/ui-layout/tests/app-frame.client.spec.tsx
@@ -1,436 +1,574 @@
 // @vitest-environment jsdom
-/**
- * AppFrame interaction spec under the four-share props form: real layout
- * store instance (createLayoutStore().create() — the test-sanctioned engine
- * path), a recording renderSlot stub, and a SessionProvider component stub
- * (the real one is framework-wired to the renderer host; its own behavior is
- * ui-renderer's spec territory). Drag sequences (pointer capture + rAF flush),
- * concession response to viewport change, and details staying mounted at
- * zero width are the preserved behavior assertions. jsdom has no layout
- * engine, so the frame width comes from a mocked getBoundingClientRect and
- * resizes are driven through the ResizeObserver stub.
- */
+/** Frame interactions with a real store and explicitly driven browser measurements. */
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, render } from '@testing-library/react'
 import { useSyncExternalStore } from 'react'
-import { AppFrame } from '@deepseek-ai/dsh-client-ui-layout/src/client/AppFrame.tsx'
-import type { AppFrameProps } from '@deepseek-ai/dsh-client-ui-layout/src/client/AppFrame.tsx'
-import { SIDEBAR_COLLAPSED } from '@deepseek-ai/dsh-client-ui-layout/src/client/columns.ts'
-import { createLayoutStore } from '@deepseek-ai/dsh-client-ui-layout/src/client/stores.ts'
+import { AppFrame } from '../src/client/AppFrame.tsx'
+import type { AppFrameProps } from '../src/client/AppFrame.tsx'
+import type { RightbarOwnerProps, SidebarOwnerProps } from '../src/client/index.ts'
+import { createLayoutStore } from '../src/client/stores.ts'
 import type { SessionListState } from '@deepseek-ai/dsh-api-session-controller/client'
 import type { WorkspaceSnapshot } from '@deepseek-ai/dsh-api-workspace-controller/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 
-// Session selection controls for the SessionProvider and useSessions stubs.
-const selectedSession = { current: 's-test' as SessionId | undefined }
-const selectedSessionBlank = { current: false }
-const selectedSessionTitle = { current: undefined as string | undefined }
-const workspacesReady = { current: true }
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+let selectedSession: SessionId | undefined
+let selectedSessionTitle: string | undefined
+let workspacesReady = true
 type AttentionSnapshot = Parameters<Parameters<AppFrameProps['useSessionPendingInteraction']>[0]>[0]
 const noAttention: AttentionSnapshot = new Map()
 const useSessionPendingInteraction: AppFrameProps['useSessionPendingInteraction'] = selector => selector(noAttention)
-
-// Provider contract stub fed through the standard seat prop (the renderer
-// injects the real one in production): session mode renders children and
-// empty mode runs the empty branch.
 const SessionProviderStub: AppFrameProps['SessionProvider'] = ({ children, empty }) =>
-  selectedSession.current === undefined ? <>{empty?.() ?? null}</> : <>{children}</>
+  selectedSession === undefined ? <>{empty?.() ?? null}</> : <>{children}</>
 
-
-/** Observer stub: captures the callback so tests can fire resizes manually. */
-let fireResize: (() => void) | null = null
+let observers: ResizeObserverStub[]
 class ResizeObserverStub {
-  #cb: ResizeObserverCallback
-  constructor(cb: ResizeObserverCallback) { this.#cb = cb }
-  observe(): void { fireResize = () => { this.#cb([], this) } }
+  disconnected = false
+  constructor(private callback: ResizeObserverCallback) { observers.push(this) }
+  observe(): void {}
   unobserve(): void {}
-  disconnect(): void { fireResize = null }
+  disconnect(): void { this.disconnected = true }
+  fire(): void { this.callback([], this) }
 }
 
-let frameWidth = 1920
+let frameWidth: number
+let animationFrames: Map<number, FrameRequestCallback>
+let nextFrame: number
+let originalTitle: string
+const restoreProperties: (() => void)[] = []
+
+function replaceProperty<T extends object, K extends keyof T>(target: T, key: K, value: T[K]): void {
+  const descriptor = Object.getOwnPropertyDescriptor(target, key)
+  restoreProperties.push(() => {
+    if (descriptor === undefined) Reflect.deleteProperty(target, key)
+    else Object.defineProperty(target, key, descriptor)
+  })
+  Object.defineProperty(target, key, { configurable: true, writable: true, value })
+}
+
+/** Flush one browser frame without depending on the worker's timer cadence. */
+function flushFrames(): void {
+  for (const [id, callback] of [...animationFrames]) {
+    if (!animationFrames.delete(id)) continue
+    callback(0)
+  }
+}
+
+function resize(width: number): void {
+  frameWidth = width
+  act(() => {
+    for (const observer of observers) if (!observer.disconnected) observer.fire()
+    flushFrames()
+  })
+}
 
-/** Test-local selector hook over a framework-neutral store instance. */
 function hookOf<T>(inst: { subscribe: (fn: () => void) => () => void; getSnapshot: () => T }) {
   return function useSelector<S>(sel: (s: T) => S): S { return sel(useSyncExternalStore(inst.subscribe, inst.getSnapshot)) }
 }
 
-function mountFrame() {
-  window.innerWidth = frameWidth // first-render viewport source before the observer fires
+function mountFrame(windowWidth = frameWidth) {
+  vi.stubGlobal('innerWidth', windowWidth)
   const instance = createLayoutStore().create()
-  const slotCalls: { key: string; props: unknown }[] = []
+  const slotCalls: { key: string; props: object }[] = []
   const renderSlot = ((key: string, owner: object) => {
     slotCalls.push({ key, props: owner })
-    if (key === 'sidebar') return <div data-testid="sidebar-content" />
-    if (key === 'conversation') return <div data-testid="center-content" />
-    if (key === 'details') return <div data-testid="details-content" />
-    if (key === 'conversation.empty') return <div data-testid="empty-content" />
-    return <div data-testid="other-content" />
+    return <div data-testid={`${key}-content`} />
   }) as AppFrameProps['renderSlot']
-  const useSessions = ((sel: (s: SessionListState) => unknown) => {
-    const current = selectedSession.current
-    const sessionState = {
-      ids: current === undefined ? [] : [current],
-      byId: current === undefined
-        ? {}
-        : {
-          [current]: {
-            id: current,
-            displayTitle: 'Test',
-            running: false,
-            blank: selectedSessionBlank.current,
-            updatedAt: 1,
-            ...(selectedSessionTitle.current === undefined ? {} : { title: selectedSessionTitle.current }),
-          },
-        },
-      current,
-      phase: 'ready',
-    } as SessionListState
-    return sel(sessionState)
-  }) as never
+  const useSessions = ((sel: (s: SessionListState) => unknown) => sel({
+    ids: selectedSession === undefined ? [] : [selectedSession],
+    byId: selectedSession === undefined ? {} : {
+      [selectedSession]: {
+        id: selectedSession, displayTitle: 'Test', running: false, blank: false, updatedAt: 1,
+        ...(selectedSessionTitle === undefined ? {} : { title: selectedSessionTitle }),
+      },
+    },
+    current: selectedSession,
+    phase: 'ready',
+  } as SessionListState)) as AppFrameProps['useSessions']
   const workspaceState: WorkspaceSnapshot = {
     items: [], archivedSessionIds: [], state: 'idle', phase: 'ready', error: null,
-    ...(workspacesReady.current ? {} : { state: 'loading' as const, phase: 'pending' as const }),
+    ...(workspacesReady ? {} : { state: 'loading' as const, phase: 'pending' as const }),
   }
+  const useStore = hookOf(instance)
   const element = () => (
     <AppFrame
-      useStore={hookOf(instance)}
+      useStore={useStore}
       actions={instance.actions}
       renderSlot={renderSlot}
       useSessions={useSessions}
       useSessionPendingInteraction={useSessionPendingInteraction}
-      useWorkspaces={((sel: (s: WorkspaceSnapshot) => unknown) => sel(workspaceState)) as never}
+      useResource={useResource}
+      useWorkspaces={((sel: (s: WorkspaceSnapshot) => unknown) => sel(workspaceState)) as AppFrameProps['useWorkspaces']}
       SessionProvider={SessionProviderStub}
       t={key => key === 'brand.localBuild' ? 'DSH Local Build' : key}
     />
   )
   const utils = render(element())
   const frame = utils.container.firstElementChild as HTMLElement
-  return { instance, frame, slotCalls, rerenderFrame: () => { utils.rerender(element()) }, ...utils }
+  return {
+    ...utils, instance, frame, slotCalls,
+    rerenderFrame: () => { utils.rerender(element()) },
+    rightOwner: () => slotCalls.findLast(c => c.key === 'rightbar')!.props as RightbarOwnerProps,
+    sidebarOwner: () => slotCalls.findLast(c => c.key === 'sidebar')!.props as SidebarOwnerProps,
+  }
 }
 
 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])]
+  const match = /^([\d.]+)px minmax\(0, 1fr\) ([\d.]+)px$/.exec(frame.style.gridTemplateColumns)
+  if (match === null) throw new Error(`unexpected template: ${frame.style.gridTemplateColumns}`)
+  return [Number(match[1]), Number(match[2])]
+}
+
+function handleFor(frame: HTMLElement, side: 'sidebar' | 'rightbar'): HTMLElement {
+  const handle = frame.querySelector<HTMLElement>(`[data-side="${side}"]`)
+  if (handle === null) throw new Error(`missing ${side} resize handle`)
+  return handle
+}
+
+function pointer(handle: Element, type: string, clientX: number, pointerId = 1, button = 0): void {
+  act(() => { handle.dispatchEvent(new PointerEvent(type, { pointerId, clientX, button, bubbles: true })) })
 }
 
 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) })
+  pointer(handle, 'pointerdown', fromX)
+  pointer(handle, 'pointermove', toX)
+  act(flushFrames)
+  pointer(handle, 'pointerup', toX)
 }
 
 beforeEach(() => {
+  originalTitle = document.title
   frameWidth = 1920
-  selectedSession.current = 's-test' as SessionId
-  selectedSessionBlank.current = false
-  selectedSessionTitle.current = undefined
-  workspacesReady.current = true
-  vi.useFakeTimers()
+  selectedSession = 's-test' as SessionId
+  selectedSessionTitle = undefined
+  workspacesReady = true
+  observers = []
+  animationFrames = new Map()
+  nextFrame = 1
+  vi.stubEnv('DSH_CLIENT_TITLE', undefined)
   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: () => ({}) }
-  }
-  // 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) }
+  vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+    const id = nextFrame++
+    animationFrames.set(id, callback)
+    return id
+  })
+  vi.stubGlobal('cancelAnimationFrame', (id: number) => { animationFrames.delete(id) })
+  vi.spyOn(Element.prototype, 'getBoundingClientRect').mockImplementation(() => ({
+    width: frameWidth, height: 1080, top: 0, left: 0, right: frameWidth, bottom: 1080,
+    x: 0, y: 0, toJSON: () => ({}),
+  }))
+  // jsdom has no pointer capture. Each element retains the actual pointer id,
+  // and teardown restores absent methods as well as existing descriptors.
+  const captured = new WeakMap<Element, number>()
+  replaceProperty(Element.prototype, 'setPointerCapture', function (this: Element, id: number) { captured.set(this, id) })
+  replaceProperty(Element.prototype, 'releasePointerCapture', function (this: Element) { captured.delete(this) })
+  replaceProperty(Element.prototype, 'hasPointerCapture', function (this: Element, id: number) { return captured.get(this) === id })
 })
 
 afterEach(() => {
-  cleanup()
-  document.title = ''
-  vi.useRealTimers()
-  vi.unstubAllGlobals()
-  vi.unstubAllEnvs()
+  try {
+    cleanup()
+  } finally {
+    for (const restore of restoreProperties.splice(0).reverse()) restore()
+    document.title = originalTitle
+    vi.restoreAllMocks()
+    vi.unstubAllGlobals()
+    vi.unstubAllEnvs()
+  }
 })
 
 describe('AppFrame', () => {
-  it('localizes the product title when the build does not supply one', () => {
+  it('localizes the product title without a configured build title', () => {
     mountFrame()
     expect(document.title).toBe('DSH Local Build')
   })
 
-  it('projects the selected durable Session title', () => {
+  it('follows the selected durable Session title', () => {
     vi.stubEnv('DSH_CLIENT_TITLE', 'Product')
-    selectedSessionTitle.current = 'First'
+    selectedSessionTitle = 'First'
     const { rerenderFrame } = mountFrame()
     expect(document.title).toBe('First — Product')
-
-    selectedSessionTitle.current = 'Revised'
-    act(() => { rerenderFrame() })
+    selectedSessionTitle = 'Revised'
+    rerenderFrame()
     expect(document.title).toBe('Revised — Product')
-
-    selectedSession.current = undefined
-    act(() => { rerenderFrame() })
+    selectedSession = undefined
+    rerenderFrame()
     expect(document.title).toBe('Product')
   })
 
-  it('renders three tracks from store state', () => {
-    const { frame } = mountFrame()
+  it('renders owner props for the default sidebar and prospective right panel', () => {
+    const { frame, rightOwner, sidebarOwner, slotCalls } = mountFrame()
     expect(tracks(frame)).toEqual([280, 0])
-  })
-
-  it('renders the session pair with empty owner shares (sessionId is framework-standard)', () => {
-    const { slotCalls, getByTestId } = mountFrame()
-    expect(getByTestId('center-content')).toBeTruthy()
-    expect(getByTestId('details-content')).toBeTruthy()
-    const keys = slotCalls.map(c => c.key)
-    expect(keys).toContain('conversation')
-    expect(keys).toContain('details')
-    expect(keys).not.toContain('conversation.empty')
+    expect(sidebarOwner()).toEqual({ collapsed: false, width: 280 })
+    expect(rightOwner()).toEqual({ width: 864, viewportWidth: 1920, canShow: true })
     expect(slotCalls.find(c => c.key === 'conversation')!.props).toEqual({})
-    expect(slotCalls.find(c => c.key === 'details')!.props).toEqual({})
   })
 
-  it('keeps the conversation slot mounted while no session is current', () => {
-    // No current session: the session-maybe conversation shell owns the New
-    // Session view itself — the center column renders it unconditionally.
-    selectedSession.current = undefined
-    const { slotCalls, getByTestId, queryByTestId } = mountFrame()
-    expect(getByTestId('center-content')).toBeTruthy()
-    expect(slotCalls.map(c => c.key)).toContain('conversation')
-    expect(queryByTestId('details-content')).toBeNull()
-    expect(slotCalls.map(c => c.key)).toContain('details')
-  })
-
-  it('renders both column occupants before baselines settle (no loading gate)', () => {
-    // No loading gate: a bare loading status reads worse than the shell's own
-    // pending rendering — both occupants mount from first paint.
-    workspacesReady.current = false
-    const { slotCalls } = mountFrame()
-    expect(slotCalls.map(c => c.key)).toContain('conversation')
-    expect(slotCalls.map(c => c.key)).toContain('details')
-  })
-
-  it('ignores unselected states and closes only when the Session id changes', () => {
-    const { frame, instance, rerenderFrame } = mountFrame()
-    expect(tracks(frame)).toEqual([280, 0])
-
-    act(() => { instance.actions.openDetails() })
-    expect(tracks(frame)).toEqual([280, 360])
-
-    selectedSession.current = 's-next' as SessionId
-    act(() => { rerenderFrame() })
-    expect(tracks(frame)).toEqual([280, 0])
-
-    act(() => { instance.actions.openDetails() })
-    selectedSession.current = 's-blank' as SessionId
-    selectedSessionBlank.current = true
-    act(() => { rerenderFrame() })
-    expect(tracks(frame)).toEqual([280, 0])
-    expect(instance.getSnapshot().details).toBe(360)
-
-    selectedSession.current = 's-next' as SessionId
-    selectedSessionBlank.current = false
-    act(() => { rerenderFrame() })
-    expect(tracks(frame)).toEqual([280, 360])
-
-    selectedSession.current = undefined
-    act(() => { rerenderFrame() })
-    expect(tracks(frame)).toEqual([280, 0])
-    selectedSession.current = 's-test' as SessionId
-    act(() => { rerenderFrame() })
-    expect(tracks(frame)).toEqual([280, 0])
-  })
-
-  it('keeps details closed when the first Session materializes', () => {
-    selectedSession.current = undefined
-    const { frame, instance, rerenderFrame } = mountFrame()
-    expect(tracks(frame)).toEqual([280, 0])
-    expect(instance.getSnapshot().details).toBe(0)
-
-    selectedSession.current = 's-first' as SessionId
-    act(() => { rerenderFrame() })
-    expect(tracks(frame)).toEqual([280, 0])
-  })
-
-  it('sidebar slot receives live concession output as owner props', () => {
-    const { slotCalls } = mountFrame()
-    expect(slotCalls.find(c => c.key === 'sidebar')!.props).toEqual({ collapsed: false, width: 280 })
-  })
-
-  it('sidebar drag widens through rAF-batched pointer moves', () => {
-    const { frame } = mountFrame()
-    const handles = frame.querySelectorAll('[class*="handle"]')
-    drag(handles[0]!, 280, 350)
-    expect(tracks(frame)[0]).toBe(350)
-  })
-
-  it('details drag widens leftward (negative dx grows the panel)', () => {
-    const { frame, instance } = mountFrame()
-    act(() => { instance.actions.openDetails() })
-    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 330 while preference is 360
-    const { frame, instance } = mountFrame()
-    act(() => { instance.actions.openDetails() })
-    expect(tracks(frame)).toEqual([280, 330])
-    const handles = frame.querySelectorAll('[class*="handle"]')
-    drag(handles[1]!, 920, 930) // shrink by 10 from the rendered width
-    expect(instance.getSnapshot().details).toBe(320)
-  })
-
-  it('details column stays mounted at zero width', () => {
-    const { frame, getByTestId } = mountFrame()
-    expect(tracks(frame)).toEqual([280, 0])
-    expect(getByTestId('details-content')).toBeTruthy()
-    expect(frame.hasAttribute('data-details-collapsed')).toBe(true)
-  })
-
-  it('closed sidebar keeps its compact rail with mounted slot content and collapsed owner props', () => {
-    const { frame, instance, slotCalls, getByTestId } = mountFrame()
-    act(() => { instance.actions.toggleSidebar() })
-    expect(tracks(frame)).toEqual([SIDEBAR_COLLAPSED, 0])
+  it('retains conversation and sidebar content without a current Session', () => {
+    selectedSession = undefined
+    const { frame, getByTestId, queryByTestId } = mountFrame()
+    expect(getByTestId('conversation-content')).toBeTruthy()
     expect(getByTestId('sidebar-content')).toBeTruthy()
-    expect(frame.hasAttribute('data-sidebar-collapsed')).toBe(true)
-    const lastSidebarCall = slotCalls.filter(c => c.key === 'sidebar').at(-1)!
-    expect(lastSidebarCall.props).toEqual({ collapsed: true, width: SIDEBAR_COLLAPSED })
+    expect(queryByTestId('rightbar-content')).toBeNull()
+    expect(tracks(frame)).toEqual([280, 0])
   })
 
-  it('viewport shrink triggers the concession chain via ResizeObserver', () => {
-    const { frame, instance } = mountFrame()
-    act(() => { instance.actions.openDetails() })
-    frameWidth = 1250
-    act(() => { fireResize?.(); vi.advanceTimersByTime(20) })
-    expect(tracks(frame)).toEqual([280, 330])
-    frameWidth = 1920
-    act(() => { fireResize?.(); vi.advanceTimersByTime(20) })
-    expect(tracks(frame)).toEqual([280, 360])
+  it('renders both occupants before workspace baselines settle', () => {
+    workspacesReady = false
+    const { getByTestId } = mountFrame()
+    expect(getByTestId('conversation-content')).toBeTruthy()
+    expect(getByTestId('rightbar-content')).toBeTruthy()
   })
 
-  it('drag handles disappear for collapsed columns', () => {
-    const { frame, instance } = mountFrame()
-    expect(frame.querySelectorAll('[class*="handle"]')).toHaveLength(1)
-    act(() => { instance.actions.openDetails() })
-    expect(frame.querySelectorAll('[class*="handle"]')).toHaveLength(2)
-    act(() => { instance.actions.closeDetails() })
-    expect(frame.querySelectorAll('[class*="handle"]')).toHaveLength(1)
+  it('keeps the closed sidebar mounted at its 56px rail without a handle', () => {
+    const { frame, instance, sidebarOwner, getByTestId } = mountFrame()
     act(() => { instance.actions.toggleSidebar() })
-    expect(frame.querySelectorAll('[class*="handle"]')).toHaveLength(0)
+    expect(tracks(frame)).toEqual([56, 0])
+    expect(sidebarOwner()).toEqual({ collapsed: true, width: 56 })
+    expect(getByTestId('sidebar-content')).toBeTruthy()
+    expect(frame.querySelector('[data-side="sidebar"]')).toBeNull()
   })
 })
 
-describe('AppFrame — narrow-viewport auto-collapse', () => {
-  it('mounts collapsed below the breakpoint with no sidebar handle', () => {
-    frameWidth = 980
-    const { frame, slotCalls } = mountFrame()
-    expect(tracks(frame)).toEqual([SIDEBAR_COLLAPSED, 0])
-    expect(frame.hasAttribute('data-sidebar-collapsed')).toBe(true)
-    expect(slotCalls.filter(c => c.key === 'sidebar').at(-1)!.props).toEqual({ collapsed: true, width: SIDEBAR_COLLAPSED })
-    expect(frame.querySelectorAll('[class*="handle"]')).toHaveLength(0)
+describe('AppFrame normal width concessions', () => {
+  it('measures the frame, not the window, before choosing the first-open preference', () => {
+    frameWidth = 1000
+    const { instance, rightOwner } = mountFrame(1920)
+    expect(instance.getSnapshot().viewportWidth).toBe(1000)
+    expect(rightOwner()).toEqual({ width: 450, viewportWidth: 1000, canShow: true })
+    act(() => { instance.actions.openRightbar(true, false) })
+    expect(instance.getSnapshot().rightbar).toBe(450)
+    resize(1920)
+    expect(rightOwner().width).toBe(450)
   })
 
-  it('narrow toggle re-expands over the squeezed center and back', () => {
-    frameWidth = 980
-    const { frame, instance } = mountFrame()
+  it('shrinks the right panel to 300px, drops its track, and only then squeezes center', () => {
+    const { frame, instance, rightOwner } = mountFrame()
+    act(() => { instance.actions.setSidebar(420); instance.actions.openRightbar(true, false) })
+    resize(1200)
+    expect(tracks(frame)).toEqual([420, 380])
+    expect(rightOwner()).toEqual({ width: 380, viewportWidth: 1200, canShow: true })
+    resize(1120)
+    expect(tracks(frame)).toEqual([420, 300])
+    resize(1119)
+    expect(tracks(frame)).toEqual([420, 0])
+    expect(rightOwner()).toEqual({ width: 0, viewportWidth: 1119, canShow: false })
+    expect(frame.querySelector('[data-side="rightbar"]')).toBeNull()
+    expect(instance.getSnapshot()).toMatchObject({ rightbarShown: true, rightbar: 864 })
+    act(() => { instance.actions.closeRightbar() })
+    resize(455)
+    expect(tracks(frame)).toEqual([56, 0])
+    resize(1920)
+    expect(tracks(frame)).toEqual([420, 0])
+  })
+
+  it('uses the post-collapse left rail to permit a narrow first opening', () => {
+    frameWidth = 800
+    const { frame, instance, rightOwner } = mountFrame()
     act(() => { instance.actions.toggleSidebar() })
     expect(tracks(frame)).toEqual([280, 0])
-    expect(frame.hasAttribute('data-sidebar-collapsed')).toBe(false)
-    expect(frame.querySelectorAll('[class*="handle"]')).toHaveLength(1)
-    act(() => { instance.actions.toggleSidebar() })
-    expect(tracks(frame)).toEqual([SIDEBAR_COLLAPSED, 0])
+    expect(rightOwner()).toEqual({ width: 344, viewportWidth: 800, canShow: true })
+    act(() => { instance.actions.openRightbar(true, false) })
+    expect(tracks(frame)).toEqual([56, 344])
+    expect(instance.getSnapshot()).toMatchObject({ narrowExpanded: false, rightbar: 360 })
+    expect(rightOwner().canShow).toBe(true)
   })
 
-  it('a wide-closed preference re-expands at the contract default while narrow', () => {
-    frameWidth = 1920
-    const { frame, instance } = mountFrame()
-    act(() => { instance.actions.toggleSidebar() }) // close while wide: preference 0
-    frameWidth = 980
-    act(() => { fireResize?.(); vi.advanceTimersByTime(20) })
+  it.each([[756, 300, true], [755, 0, false]] as const)('reports eligibility at %ipx', (width, rightbar, canShow) => {
+    frameWidth = width
+    const { instance, rightOwner } = mountFrame()
     act(() => { instance.actions.toggleSidebar() })
-    expect(tracks(frame)).toEqual([280, 0])
-    expect(instance.getSnapshot().sidebar).toBe(0) // preference untouched
+    expect(rightOwner()).toEqual({ width: rightbar, viewportWidth: width, canShow })
   })
 
-  it('shrinking across the breakpoint auto-collapses; re-widening restores the drag width', () => {
+  it('does not anticipate another left collapse after the right panel is already shown', () => {
+    frameWidth = 800
+    const { instance, rightOwner } = mountFrame()
+    act(() => { instance.actions.openRightbar(true, false); instance.actions.toggleSidebar() })
+    expect(rightOwner().canShow).toBe(false)
+  })
+
+  it('auto-collapses only below 1024px and preserves the wide sidebar preference', () => {
     const { frame, instance } = mountFrame()
     act(() => { instance.actions.setSidebar(400) })
-    frameWidth = 980
-    act(() => { fireResize?.(); vi.advanceTimersByTime(20) })
-    expect(tracks(frame)).toEqual([SIDEBAR_COLLAPSED, 0])
-    frameWidth = 1920
-    act(() => { fireResize?.(); vi.advanceTimersByTime(20) })
-    expect(tracks(frame)).toEqual([400, 0])
+    resize(1024)
+    expect(tracks(frame)[0]).toBe(400)
+    resize(1023)
+    expect(tracks(frame)[0]).toBe(56)
+    act(() => { instance.actions.toggleSidebar() })
+    expect(tracks(frame)[0]).toBe(400)
+    resize(980)
+    expect(tracks(frame)[0]).toBe(400)
+    act(() => { instance.actions.toggleSidebar() })
+    expect(tracks(frame)[0]).toBe(56)
+    resize(1920)
+    expect(tracks(frame)[0]).toBe(400)
+  })
+
+  it('re-expands a wide-closed sidebar at the default width while narrow', () => {
+    const { frame, instance } = mountFrame()
+    act(() => { instance.actions.toggleSidebar() })
+    resize(980)
+    act(() => { instance.actions.toggleSidebar() })
+    expect(tracks(frame)[0]).toBe(280)
+    expect(instance.getSnapshot().sidebar).toBe(0)
   })
 })
 
-describe('AppFrame — guard branches', () => {
-  it('pointer moves without capture are ignored (no width write)', () => {
+describe('AppFrame right panel presentation', () => {
+  it('releases the fullscreen track with the instant marker while clearing fullscreen', () => {
     const { frame, instance } = mountFrame()
-    const handle = frame.querySelectorAll('[class*="handle"]')[0]!
-    const before = instance.getSnapshot().sidebar
-    // 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(instance.getSnapshot().sidebar).toBe(before)
+    act(() => { instance.actions.openRightbar(true, true) })
+    expect(tracks(frame)).toEqual([280, 864])
+    act(() => { instance.actions.closeRightbar() })
+    expect(tracks(frame)).toEqual([280, 0])
+    expect(frame.dataset.rightbarFullscreen).toBeUndefined()
+    expect(frame.dataset.rightbarInstant).toBe('true')
+    expect(frame.querySelector('[data-side="rightbar"]')).toBeNull()
+    act(() => { instance.actions.closeRightbar() })
+    expect(frame.dataset.rightbarInstant).toBe('true')
   })
 
-  it('two moves inside one frame coalesce through the pending rAF', () => {
+  it('marks restoration instant without suppressing the following normal close', () => {
     const { frame, instance } = mountFrame()
-    const handle = frame.querySelectorAll('[class*="handle"]')[0]!
-    act(() => { handle.dispatchEvent(new PointerEvent('pointerdown', { pointerId: 1, clientX: 280, bubbles: true })) })
-    act(() => {
-      // Two moves before the frame flushes: the second must ride the pending
-      // rAF (frame.current ??= guard), and the flush sees the latest x.
-      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(instance.getSnapshot().sidebar).toBe(340)
+    act(() => { instance.actions.openRightbar(true, true) })
+    act(() => { instance.actions.openRightbar(true, false) })
+    expect(tracks(frame)).toEqual([280, 864])
+    expect(frame.dataset.rightbarFullscreen).toBeUndefined()
+    expect(frame.dataset.rightbarInstant).toBe('true')
+    act(() => { instance.actions.closeRightbar() })
+    expect(tracks(frame)).toEqual([280, 0])
+    expect(frame.dataset.rightbarFullscreen).toBeUndefined()
+    expect(frame.dataset.rightbarInstant).toBeUndefined()
   })
 
-  it('pointerup with a pending rAF cancels it and commits the final position', () => {
+  it.each(['setSidebar', 'toggleSidebar', 'setRightbar', 'viewport', 'open'] as const)('reenables normal transitions after %s', (action) => {
     const { frame, instance } = mountFrame()
-    const handle = frame.querySelectorAll('[class*="handle"]')[0]!
-    act(() => { handle.dispatchEvent(new PointerEvent('pointerdown', { pointerId: 1, clientX: 280, bubbles: true })) })
+    act(() => { instance.actions.openRightbar(true, true); instance.actions.closeRightbar() })
+    expect(frame.dataset.rightbarInstant).toBe('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 }))
+      if (action === 'viewport') resize(1800)
+      else if (action === 'open') instance.actions.openRightbar(true, false)
+      else if (action === 'toggleSidebar') instance.actions.toggleSidebar()
+      else instance.actions[action](350)
     })
+    expect(frame.dataset.rightbarInstant).toBeUndefined()
+    expect(frame.dataset.rightbarFullscreen).toBeUndefined()
+  })
+
+  it('keeps fullscreen suppression independent from resetting the instant marker', () => {
+    const { frame, instance } = mountFrame()
+    act(() => { instance.actions.openRightbar(true, true) })
+    act(() => { instance.actions.setSidebar(350) })
+    expect(frame.dataset.rightbarInstant).toBeUndefined()
+    expect(frame.dataset.rightbarFullscreen).toBe('true')
+  })
+
+  it('preserves normal tracks through fullscreen and hides the outer resize handle', () => {
+    const { frame, instance, rightOwner } = mountFrame()
+    act(() => { instance.actions.openRightbar(true, false) })
+    expect(tracks(frame)).toEqual([280, 864])
+    expect(handleFor(frame, 'rightbar').style.left).toBe('1056px')
+    act(() => { instance.actions.openRightbar(true, true) })
+    expect(tracks(frame)).toEqual([280, 864])
+    expect(rightOwner().width).toBe(864)
+    expect(frame.dataset.rightbarFullscreen).toBe('true')
+    expect(frame.querySelector('[data-side="rightbar"]')).toBeNull()
+    act(() => { instance.actions.openRightbar(true, false) })
+    expect(tracks(frame)).toEqual([280, 864])
+    expect(handleFor(frame, 'rightbar').style.left).toBe('1056px')
+    expect(frame.dataset.rightbarFullscreen).toBeUndefined()
+    act(() => { instance.actions.closeRightbar() })
+    expect(tracks(frame)).toEqual([280, 0])
+    expect(frame.querySelector('[data-side="rightbar"]')).toBeNull()
+    expect(frame.dataset.rightbarFullscreen).toBeUndefined()
+  })
+
+  it('inserts a fullscreen track and its transition-suppression marker in the same render', () => {
+    const { frame, instance } = mountFrame()
+    expect(tracks(frame)).toEqual([280, 0])
+    expect(frame.dataset.rightbarFullscreen).toBeUndefined()
+    act(() => { instance.actions.openRightbar(true, true) })
+    expect(tracks(frame)).toEqual([280, 864])
+    expect(frame.dataset.rightbarFullscreen).toBe('true')
+    expect(frame.querySelector('[data-side="rightbar"]')).toBeNull()
+    act(() => { instance.actions.openRightbar(true, false) })
+    expect(tracks(frame)).toEqual([280, 864])
+    expect(frame.dataset.rightbarFullscreen).toBeUndefined()
+  })
+
+  it('retains fullscreen without a track when normal columns cannot fit', () => {
+    frameWidth = 700
+    const { frame, instance, rightOwner } = mountFrame()
+    act(() => { instance.actions.openRightbar(false, true) })
+    expect(tracks(frame)).toEqual([56, 0])
+    expect(rightOwner()).toEqual({ width: 0, viewportWidth: 700, canShow: false })
+    expect(instance.getSnapshot().rightbarShown).toBe(true)
+    expect(frame.querySelector('[data-side="rightbar"]')).toBeNull()
+  })
+
+  it('keeps resolved panel width independent of the requested track', () => {
+    const { frame, instance, rightOwner } = mountFrame()
+    act(() => { instance.actions.openRightbar(false, false) })
+    resize(1100)
+    expect(tracks(frame)).toEqual([280, 0])
+    expect(rightOwner().width).toBe(420)
+    drag(handleFor(frame, 'rightbar'), 680, 690)
+    expect(instance.getSnapshot().rightbar).toBe(410)
+    expect(rightOwner().width).toBe(410)
+    expect(tracks(frame)[1]).toBe(0)
+  })
+})
+
+describe('AppFrame pointer resizing', () => {
+  it('updates columns during the gesture and freezes the drag-start width', () => {
+    const { frame, instance } = mountFrame()
+    const handle = handleFor(frame, 'sidebar')
+    pointer(handle, 'pointerdown', 280)
+    expect(frame.dataset.dragging).toBe('true')
+    pointer(handle, 'pointermove', 320)
+    pointer(handle, 'pointermove', 340)
+    expect(animationFrames.size).toBe(1)
+    act(flushFrames)
+    expect(tracks(frame)[0]).toBe(340)
+    pointer(handle, 'pointermove', 360)
+    act(flushFrames)
+    expect(tracks(frame)[0]).toBe(360)
+    pointer(handle, 'pointerup', 360)
+    expect(instance.getSnapshot().sidebar).toBe(360)
+    expect(frame.dataset.dragging).toBeUndefined()
+    expect(handle.hasPointerCapture(1)).toBe(false)
+  })
+
+  it('starts a conceded right drag at its actual width, shared by panel and track', () => {
+    const { frame, instance, rightOwner } = mountFrame()
+    act(() => { instance.actions.openRightbar(true, false) })
+    resize(1100)
+    const handle = handleFor(frame, 'rightbar')
+    expect(rightOwner().width).toBe(420)
+    expect(tracks(frame)[1]).toBe(420)
+    expect(handle.style.left).toBe('680px')
+    drag(handle, 680, 690)
+    expect(instance.getSnapshot().rightbar).toBe(410)
+    expect(rightOwner().width).toBe(410)
+    expect(tracks(frame)[1]).toBe(410)
+    expect(handle.style.left).toBe('690px')
+  })
+
+  it('widens to the 70% limit and shrinks to 300px through pointer input', () => {
+    frameWidth = 3000
+    const { frame, instance, rightOwner } = mountFrame()
+    act(() => { instance.actions.toggleSidebar(); instance.actions.openRightbar(true, false) })
+    drag(handleFor(frame, 'rightbar'), 1650, 0)
+    expect(rightOwner().width).toBe(2100)
+    expect(tracks(frame)[1]).toBe(2100)
+    drag(handleFor(frame, 'rightbar'), 900, 3000)
+    expect(rightOwner().width).toBe(300)
+    expect(tracks(frame)[1]).toBe(300)
+  })
+
+  it('commits the pointerup coordinate and cancels its pending animation frame', () => {
+    const { frame, instance } = mountFrame()
+    const handle = handleFor(frame, 'sidebar')
+    pointer(handle, 'pointerdown', 280)
+    pointer(handle, 'pointermove', 320)
+    pointer(handle, 'pointerup', 360)
+    expect(instance.getSnapshot().sidebar).toBe(360)
+    expect(animationFrames.size).toBe(0)
+    act(flushFrames)
     expect(instance.getSnapshot().sidebar).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([280, 0])
-  })
-})
-
-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)', () => {
+  it('ignores uncaptured motion, secondary buttons, and a second pointer', () => {
     const { frame, instance } = mountFrame()
-    act(() => { instance.actions.openDetails() })
-    frameWidth = 1250
-    act(() => { fireResize?.(); fireResize?.(); vi.advanceTimersByTime(20) })
-    expect(tracks(frame)).toEqual([280, 330])
+    const handle = handleFor(frame, 'sidebar')
+    pointer(handle, 'pointermove', 500, 9)
+    pointer(handle, 'pointerup', 500, 9)
+    pointer(handle, 'pointercancel', 500, 9)
+    pointer(handle, 'pointerdown', 500, 9, 2)
+    expect(frame.dataset.dragging).toBeUndefined()
+    pointer(handle, 'pointerdown', 280)
+    pointer(handle, 'pointerdown', 500, 9)
+    pointer(handle, 'pointermove', 500, 9)
+    pointer(handle, 'pointerup', 500, 9)
+    expect(animationFrames.size).toBe(0)
+    expect(instance.getSnapshot().sidebar).toBe(280)
+    pointer(handle, 'pointerup', 300)
+    expect(instance.getSnapshot().sidebar).toBe(300)
+  })
+
+  it.each(['pointercancel', 'lostpointercapture'])('ends %s without committing queued motion', (event) => {
+    const { frame, instance } = mountFrame()
+    const handle = handleFor(frame, 'sidebar')
+    pointer(handle, 'pointerdown', 280)
+    pointer(handle, 'pointermove', 340)
+    if (event === 'lostpointercapture') handle.releasePointerCapture(1)
+    pointer(handle, event, 340)
+    act(flushFrames)
+    expect(instance.getSnapshot().sidebar).toBe(280)
+    expect(animationFrames.size).toBe(0)
+    expect(frame.dataset.dragging).toBeUndefined()
+    expect(handle.hasPointerCapture(1)).toBe(false)
+  })
+
+  it.each(['fullscreen', 'close', 'unmount'])('cancels a pending drag on %s', (change) => {
+    const { frame, instance, unmount } = mountFrame()
+    act(() => { instance.actions.openRightbar(true, false) })
+    const handle = handleFor(frame, 'rightbar')
+    pointer(handle, 'pointerdown', 1056)
+    pointer(handle, 'pointermove', 1000)
+    act(() => {
+      if (change === 'fullscreen') instance.actions.openRightbar(true, true)
+      else if (change === 'close') instance.actions.closeRightbar()
+      else unmount()
+    })
+    const settled = instance.getSnapshot()
+    act(flushFrames)
+    expect(instance.getSnapshot()).toBe(settled)
+    expect(instance.getSnapshot().rightbar).toBe(864)
+    expect(animationFrames.size).toBe(0)
+    expect(handle.hasPointerCapture(1)).toBe(false)
+    if (change !== 'unmount') expect(frame.dataset.dragging).toBeUndefined()
+  })
+})
+
+describe('AppFrame frame measurement lifecycle', () => {
+  it('coalesces observer reports and publishes the latest frame measurement', () => {
+    const { instance, rightOwner } = mountFrame()
+    const observer = observers.at(-1)!
+    act(() => {
+      frameWidth = 900
+      observer.fire()
+      frameWidth = 1200
+      observer.fire()
+    })
+    expect(animationFrames.size).toBe(1)
+    expect(instance.getSnapshot().viewportWidth).toBe(1920)
+    act(flushFrames)
+    expect(instance.getSnapshot().viewportWidth).toBe(1200)
+    expect(rightOwner().viewportWidth).toBe(1200)
+    expect(instance.getSnapshot().rightbar).toBeNull()
+  })
+
+  it('retains the last positive measurement while the frame is hidden', () => {
+    const { instance, rightOwner } = mountFrame()
+    resize(0)
+    expect(instance.getSnapshot().viewportWidth).toBe(1920)
+    expect(rightOwner().viewportWidth).toBe(1920)
+  })
+
+  it('disconnects the observer and prevents queued or late reports after unmount', () => {
+    const { instance, unmount } = mountFrame()
+    const observer = observers.at(-1)!
+    frameWidth = 800
+    act(() => { observer.fire() })
+    expect(animationFrames.size).toBe(1)
+    unmount()
+    expect(observer.disconnected).toBe(true)
+    expect(animationFrames.size).toBe(0)
+    act(() => { observer.fire(); flushFrames() })
+    expect(instance.getSnapshot().viewportWidth).toBe(1920)
+    expect(animationFrames.size).toBe(0)
   })
 })
diff --git a/packages/client/ui-layout/tests/apply.client.spec.ts b/packages/client/ui-layout/tests/apply.client.spec.ts
index da3056b5db..38732eda2c 100644
--- a/packages/client/ui-layout/tests/apply.client.spec.ts
+++ b/packages/client/ui-layout/tests/apply.client.spec.ts
@@ -43,7 +43,6 @@ describe('ui-layout client apply', () => {
     // …and declared the three children in the ledger.
     expect(slots.spec('sidebar')).toEqual({ kind: 'single', scope: 'root' })
     expect(slots.spec('conversation')).toEqual({ kind: 'single', scope: 'session-maybe' })
-    expect(slots.spec('details')).toEqual({ kind: 'single', scope: 'session' })
   })
 
   it('injects no business face and attaches the layout actions', async () => {
diff --git a/packages/client/ui-layout/tests/columns.client.spec.ts b/packages/client/ui-layout/tests/columns.client.spec.ts
index ae8c39a117..4278516f0e 100644
--- a/packages/client/ui-layout/tests/columns.client.spec.ts
+++ b/packages/client/ui-layout/tests/columns.client.spec.ts
@@ -1,12 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import {
-  CENTER_MIN, clampWidth, computeColumns,
-  DETAILS_DEFAULT, DETAILS_MIN, SIDEBAR_COLLAPSED, SIDEBAR_DEFAULT, SIDEBAR_MIN,
-} from '@deepseek-ai/dsh-client-ui-layout/src/client/columns.ts'
-
-// Numeric preference form (0 = closed); helpers keep the scenario names readable.
-const open = (width: number) => width
-const closed = (_width: number) => 0
+import { clampWidth, computeColumns } from '../src/client/columns.ts'
 
 describe('clampWidth', () => {
   it('clamps into the range and rounds', () => {
@@ -17,79 +10,44 @@ describe('clampWidth', () => {
 })
 
 describe('computeColumns', () => {
-  it('step 1: everything fits at preferred widths', () => {
-    const cols = computeColumns(1920, open(SIDEBAR_DEFAULT), open(DETAILS_DEFAULT))
-    expect(cols).toEqual({ sidebar: 280, center: 1920 - 280 - 360, details: 360 })
+  it('gives each edge column its preference when the center has enough room', () => {
+    expect(computeColumns(1920, 280, 864)).toEqual({ sidebar: 280, center: 776, rightbar: 864 })
   })
 
-  it('closed sidebar keeps its compact rail while closed details contribute zero width', () => {
-    expect(computeColumns(1920, closed(300), closed(360)))
-      .toEqual({ sidebar: SIDEBAR_COLLAPSED, center: 1920 - SIDEBAR_COLLAPSED, details: 0 })
+  it('keeps only the left rail when both panels are closed', () => {
+    expect(computeColumns(1920, 0, 0)).toEqual({ sidebar: 56, center: 1864, rightbar: 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)
-    expect(computeColumns(1920, open(1), open(DETAILS_DEFAULT)).sidebar).toBe(SIDEBAR_MIN)
+  it('clamps sidebar preferences and limits the right panel to 70% of the frame', () => {
+    expect(computeColumns(3000, 9999, 9999)).toEqual({ sidebar: 420, center: 480, rightbar: 2100 })
+    expect(computeColumns(1920, 1, 1)).toEqual({ sidebar: 264, center: 1356, rightbar: 300 })
   })
 
-  it('step 2: details shrinks first, center pinned at min', () => {
-    // 280 + 360 + 640 = 1280 > 1250; details concedes to 1250-280-640 = 330.
-    const cols = computeColumns(1250, open(SIDEBAR_DEFAULT), open(DETAILS_DEFAULT))
-    expect(cols).toEqual({ sidebar: 280, center: CENTER_MIN, details: 330 })
+  it.each([
+    [1300, 280, 620, 400],
+    [1100, 280, 420, 400],
+    [1120, 420, 300, 400],
+    [1119, 420, 0, 699],
+    [1024, 420, 0, 604],
+    [756, 0, 300, 400],
+    [755, 0, 0, 699],
+    [455, 0, 0, 399],
+    [20, 0, 0, 0],
+  ])('solves frame %i and sidebar %i to right %i and center %i', (viewport, sidebar, rightbar, center) => {
+    expect(computeColumns(viewport, sidebar, 864)).toEqual({ sidebar: sidebar || 56, center, rightbar })
   })
 
-  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('does not reduce the wide sidebar to keep a normal right panel open', () => {
+    expect(computeColumns(1024, 420, 500)).toEqual({ sidebar: 420, center: 604, rightbar: 0 })
   })
 
-  it('step 3: details auto-closes when its min still starves center — sidebar holds its preference', () => {
-    // 280 + 300 + 640 = 1220 > 1210 → details 0; sidebar untouched: center = 1210-280 = 930.
-    const cols = computeColumns(1210, open(SIDEBAR_DEFAULT), open(DETAILS_DEFAULT))
-    expect(cols).toEqual({ sidebar: 280, center: 930, details: 0 })
+  it('restores a still-open preference when the frame widens', () => {
+    expect(computeColumns(1100, 280, 864).rightbar).toBe(420)
+    expect(computeColumns(1920, 280, 864).rightbar).toBe(864)
   })
 
-  it('the sidebar never concedes: center absorbs the deficit below CENTER_MIN', () => {
-    // 700 < 280+640: sidebar keeps 280, center takes 420 < CENTER_MIN.
-    const cols = computeColumns(700, open(SIDEBAR_DEFAULT), closed(DETAILS_DEFAULT))
-    expect(cols).toEqual({ sidebar: SIDEBAR_DEFAULT, center: 420, details: 0 })
-  })
-
-  it('sidebar-closed narrow window: details concedes then auto-closes', () => {
-    const fits = computeColumns(SIDEBAR_COLLAPSED + DETAILS_MIN + CENTER_MIN, closed(300), open(DETAILS_DEFAULT))
-    expect(fits).toEqual({ sidebar: SIDEBAR_COLLAPSED, center: CENTER_MIN, details: DETAILS_MIN })
-    const starved = computeColumns(SIDEBAR_COLLAPSED + DETAILS_MIN + CENTER_MIN - 1, closed(300), open(DETAILS_DEFAULT))
-    expect(starved).toEqual({
-      sidebar: SIDEBAR_COLLAPSED,
-      center: DETAILS_MIN + CENTER_MIN - 1,
-      details: 0,
-    })
-  })
-
-  it('tiny viewport: details closes, sidebar holds, center takes the remainder', () => {
-    const cols = computeColumns(400, open(SIDEBAR_DEFAULT), open(DETAILS_DEFAULT))
-    expect(cols.details).toBe(0)
-    expect(cols.sidebar).toBe(SIDEBAR_DEFAULT)
-    expect(cols.center).toBe(Math.max(0, 400 - SIDEBAR_DEFAULT))
-  })
-
-  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 the rest', () => {
-    // Reaches step 3's auto-close with the compact rail sidebar.
-    expect(computeColumns(500, closed(300), open(DETAILS_DEFAULT)))
-      .toEqual({ sidebar: SIDEBAR_COLLAPSED, center: 500 - SIDEBAR_COLLAPSED, details: 0 })
+  it('leaves a closed right track closed when the frame widens', () => {
+    expect(computeColumns(755, 0, 0).rightbar).toBe(0)
+    expect(computeColumns(1920, 0, 0).rightbar).toBe(0)
   })
 })
diff --git a/packages/client/ui-layout/tests/layout-store.client.spec.ts b/packages/client/ui-layout/tests/layout-store.client.spec.ts
index c6f0069197..60dacf2f4b 100644
--- a/packages/client/ui-layout/tests/layout-store.client.spec.ts
+++ b/packages/client/ui-layout/tests/layout-store.client.spec.ts
@@ -1,103 +1,226 @@
 // @vitest-environment jsdom
-/**
- * createLayoutStore unit account: init shape, the action write set (clamp
- * inside actions), and the absence of browser persistence. Uses the
- * test-sanctioned path: factory self-call + .create() gives the
- * real engine instance (same create path as production).
- */
-import { beforeEach, describe, expect, it } from 'vitest'
-import { createLayoutStore } from '@deepseek-ai/dsh-client-ui-layout/src/client/stores.ts'
-import {
-  DETAILS_DEFAULT, DETAILS_MAX, DETAILS_MIN,
-  SIDEBAR_DEFAULT, SIDEBAR_MAX, SIDEBAR_MIN,
-} from '@deepseek-ai/dsh-client-ui-layout/src/client/columns.ts'
 
-const PERSIST_KEY = 'dsh.layout.panels'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createLayoutStore } from '../src/client/stores.ts'
 
-beforeEach(() => { localStorage.clear() })
+beforeEach(() => { vi.stubGlobal('innerWidth', 1920) })
+afterEach(() => { vi.unstubAllGlobals(); vi.restoreAllMocks() })
 
 describe('createLayoutStore', () => {
-  it('initializes the sidebar at its default width, details closed, wide viewport assumed', () => {
+  it('starts with the default sidebar and no right panel preference', () => {
     const { store } = createLayoutStore().create()
-    expect(store.getSnapshot()).toEqual({ sidebar: SIDEBAR_DEFAULT, details: 0, narrow: false, narrowExpanded: false })
+    expect(store.getSnapshot()).toEqual({
+      sidebar: 280,
+      viewportWidth: 1920,
+      narrowExpanded: false,
+      rightbar: null,
+      rightbarShown: false,
+      rightbarTrack: false,
+      rightbarFullscreen: false,
+      rightbarInstant: false,
+    })
   })
 
-  it('each create() is an independent instance (factory is not a singleton)', () => {
+  it('creates independent instances without browser persistence', () => {
+    const write = vi.spyOn(Storage.prototype, 'setItem')
     const a = createLayoutStore().create()
     const b = createLayoutStore().create()
     a.actions.setSidebar(400)
-    expect(b.store.getSnapshot().sidebar).toBe(SIDEBAR_DEFAULT)
+    a.actions.openRightbar(true, false)
+    expect(b.store.getSnapshot().sidebar).toBe(280)
+    expect(b.store.getSnapshot().rightbar).toBeNull()
+    expect(write).not.toHaveBeenCalled()
   })
 
-  it('setSidebar/setDetails clamp into the contract ranges', () => {
+  it('clamps the sidebar to 264–420px', () => {
     const { store, actions } = createLayoutStore().create()
     actions.setSidebar(1)
-    expect(store.getSnapshot().sidebar).toBe(SIDEBAR_MIN)
+    expect(store.getSnapshot().sidebar).toBe(264)
     actions.setSidebar(9999)
-    expect(store.getSnapshot().sidebar).toBe(SIDEBAR_MAX)
-    actions.setDetails(1)
-    expect(store.getSnapshot().details).toBe(DETAILS_MIN)
-    actions.setDetails(9999)
-    expect(store.getSnapshot().details).toBe(DETAILS_MAX)
+    expect(store.getSnapshot().sidebar).toBe(420)
   })
 
-  it('toggleSidebar flips closed <-> contract default (drag width forgotten)', () => {
+  it('toggles the wide sidebar between closed and default width', () => {
     const { store, actions } = createLayoutStore().create()
     actions.setSidebar(400)
     actions.toggleSidebar()
     expect(store.getSnapshot().sidebar).toBe(0)
     actions.toggleSidebar()
-    expect(store.getSnapshot().sidebar).toBe(SIDEBAR_DEFAULT)
+    expect(store.getSnapshot().sidebar).toBe(280)
   })
 
-  it('narrow toggleSidebar flips only the re-expand override; the width preference survives', () => {
+  it('keeps the sidebar preference while toggling its narrow override', () => {
     const { store, actions } = createLayoutStore().create()
     actions.setSidebar(400)
-    actions.setNarrow(true)
+    actions.setViewportWidth(980)
     actions.toggleSidebar()
-    expect(store.getSnapshot()).toEqual({ sidebar: 400, details: 0, narrow: true, narrowExpanded: true })
+    expect(store.getSnapshot()).toMatchObject({ sidebar: 400, viewportWidth: 980, narrowExpanded: true })
     actions.toggleSidebar()
-    expect(store.getSnapshot().narrowExpanded).toBe(false)
-    expect(store.getSnapshot().sidebar).toBe(400)
+    expect(store.getSnapshot()).toMatchObject({ sidebar: 400, narrowExpanded: false })
   })
 
-  it('crossing the breakpoint drops the override; a same-value setNarrow keeps it', () => {
+  it('clears the manual override only when crossing 1024px', () => {
     const { store, actions } = createLayoutStore().create()
-    actions.setNarrow(true)
+    actions.setViewportWidth(980)
     actions.toggleSidebar()
+    actions.setViewportWidth(980)
+    actions.setViewportWidth(1023)
     expect(store.getSnapshot().narrowExpanded).toBe(true)
-    actions.setNarrow(true)
-    expect(store.getSnapshot().narrowExpanded).toBe(true)
-    actions.setNarrow(false)
-    expect(store.getSnapshot()).toMatchObject({ narrow: false, narrowExpanded: false })
-    actions.setNarrow(true)
+    actions.setViewportWidth(1024)
+    expect(store.getSnapshot().narrowExpanded).toBe(false)
+    actions.setViewportWidth(980)
     expect(store.getSnapshot().narrowExpanded).toBe(false)
   })
+})
 
-  it('openDetails uses the contract default, preserves an open width, and closeDetails zeroes', () => {
-    const { store, actions } = createLayoutStore().create()
-    actions.openDetails()
-    expect(store.getSnapshot().details).toBe(DETAILS_DEFAULT)
-    actions.setDetails(500)
-    actions.openDetails()
-    expect(store.getSnapshot().details).toBe(500)
-    actions.closeDetails()
-    expect(store.getSnapshot().details).toBe(0)
-  })
-
-  it('does not persist panel geometry', () => {
-    const first = createLayoutStore().create()
-    first.actions.setSidebar(400)
-    first.actions.openDetails()
-    first.actions.setDetails(500)
-    expect(localStorage.getItem(PERSIST_KEY)).toBeNull()
-
-    const second = createLayoutStore().create()
-    expect(second.store.getSnapshot()).toEqual({
-      sidebar: SIDEBAR_DEFAULT,
-      details: 0,
-      narrow: false,
-      narrowExpanded: false,
+describe('right panel', () => {
+  it('initializes at 45% of the latest frame only on first opening', () => {
+    const { store, actions } = createLayoutStore().create()
+    actions.setViewportWidth(1000)
+    expect(store.getSnapshot().rightbar).toBeNull()
+    actions.openRightbar(true, false)
+    expect(store.getSnapshot().rightbar).toBe(450)
+    actions.setViewportWidth(2000)
+    actions.openRightbar(true, true)
+    expect(store.getSnapshot().rightbar).toBe(450)
+    actions.closeRightbar()
+    actions.openRightbar(true, false)
+    expect(store.getSnapshot().rightbar).toBe(450)
+  })
+
+  it('keeps track and fullscreen reports independent and clears both on close', () => {
+    const { store, actions } = createLayoutStore().create()
+    actions.openRightbar(true, false)
+    expect(store.getSnapshot()).toMatchObject({ rightbarShown: true, rightbarTrack: true, rightbarFullscreen: false })
+    actions.openRightbar(true, true)
+    expect(store.getSnapshot()).toMatchObject({ rightbarShown: true, rightbarTrack: true, rightbarFullscreen: true })
+    actions.openRightbar(false, true)
+    expect(store.getSnapshot()).toMatchObject({ rightbarShown: true, rightbarTrack: false, rightbarFullscreen: true })
+    actions.closeRightbar()
+    expect(store.getSnapshot()).toMatchObject({ rightbarShown: false, rightbarTrack: false, rightbarFullscreen: false })
+  })
+
+  it('keeps dragged px preferences across resize, close, and reopen', () => {
+    const { store, actions } = createLayoutStore().create()
+    actions.openRightbar(true, false)
+    actions.setRightbar(1100)
+    actions.setViewportWidth(800)
+    expect(store.getSnapshot().rightbar).toBe(1100)
+    actions.closeRightbar()
+    actions.openRightbar(false, true)
+    expect(store.getSnapshot().rightbar).toBe(1100)
+  })
+
+  it('clamps drag preferences to 300px and 70% of the current frame', () => {
+    const { store, actions } = createLayoutStore().create()
+    actions.setViewportWidth(1600)
+    actions.setRightbar(9999)
+    expect(store.getSnapshot().rightbar).toBe(1120)
+    actions.setViewportWidth(1000)
+    actions.setRightbar(9999)
+    expect(store.getSnapshot().rightbar).toBe(700)
+    actions.setRightbar(1)
+    expect(store.getSnapshot().rightbar).toBe(300)
+  })
+
+  it('retains a minimum normal preference when first opened fullscreen on a phone', () => {
+    const { store, actions } = createLayoutStore().create()
+    actions.setViewportWidth(320)
+    actions.openRightbar(false, true)
+    expect(store.getSnapshot().rightbar).toBe(300)
+  })
+
+  it('collapses a manually expanded narrow sidebar on opening, not presentation reports', () => {
+    const { store, actions } = createLayoutStore().create()
+    actions.setSidebar(400)
+    actions.setViewportWidth(800)
+    actions.toggleSidebar()
+    actions.openRightbar(true, false)
+    expect(store.getSnapshot()).toMatchObject({ sidebar: 400, narrowExpanded: false })
+    actions.toggleSidebar()
+    actions.openRightbar(true, true)
+    expect(store.getSnapshot().narrowExpanded).toBe(true)
+    actions.closeRightbar()
+    actions.openRightbar(true, false)
+    expect(store.getSnapshot().narrowExpanded).toBe(false)
+  })
+
+  it('keeps the wide sidebar preference and never opens a closed right panel on resize', () => {
+    const { store, actions } = createLayoutStore().create()
+    actions.setSidebar(420)
+    actions.openRightbar(true, false)
+    expect(store.getSnapshot().sidebar).toBe(420)
+    actions.closeRightbar()
+    actions.setViewportWidth(3000)
+    expect(store.getSnapshot()).toMatchObject({ sidebar: 420, rightbarShown: false, rightbarTrack: false })
+  })
+})
+
+describe('right panel instant geometry', () => {
+  it.each([true, false])('closes fullscreen with track=%s in one instant update and retains repeated close reports', (track) => {
+    const { store, actions } = createLayoutStore().create()
+    actions.openRightbar(track, true)
+    actions.closeRightbar()
+    expect(store.getSnapshot()).toMatchObject({
+      rightbarShown: false, rightbarTrack: false, rightbarFullscreen: false, rightbarInstant: true,
+    })
+    const closed = store.getSnapshot()
+    actions.closeRightbar()
+    expect(store.getSnapshot()).toBe(closed)
+  })
+
+  it('restores the normal track instantly, retaining the marker on an identical report', () => {
+    const { store, actions } = createLayoutStore().create()
+    actions.openRightbar(true, true)
+    actions.openRightbar(true, false)
+    expect(store.getSnapshot()).toMatchObject({
+      rightbarShown: true, rightbarTrack: true, rightbarFullscreen: false, rightbarInstant: true,
     })
+    const restored = store.getSnapshot()
+    actions.openRightbar(true, false)
+    expect(store.getSnapshot()).toBe(restored)
+    actions.openRightbar(false, false)
+    expect(store.getSnapshot().rightbarInstant).toBe(false)
+  })
+
+  it('allows a normal close to animate, including after restoring from fullscreen', () => {
+    const { store, actions } = createLayoutStore().create()
+    actions.openRightbar(true, false)
+    actions.closeRightbar()
+    expect(store.getSnapshot().rightbarInstant).toBe(false)
+    actions.openRightbar(true, true)
+    actions.openRightbar(true, false)
+    expect(store.getSnapshot().rightbarInstant).toBe(true)
+    actions.closeRightbar()
+    expect(store.getSnapshot()).toMatchObject({ rightbarTrack: false, rightbarInstant: false })
+  })
+
+  it.each(['setSidebar', 'toggleSidebar', 'setRightbar', 'setViewportWidth'] as const)('clears instant geometry on %s', (action) => {
+    const { store, actions } = createLayoutStore().create()
+    actions.openRightbar(true, true)
+    actions.closeRightbar()
+    expect(store.getSnapshot().rightbarInstant).toBe(true)
+    if (action === 'toggleSidebar') actions.toggleSidebar()
+    else actions[action](action === 'setViewportWidth' ? 1800 : 350)
+    expect(store.getSnapshot().rightbarInstant).toBe(false)
+    actions.closeRightbar()
+    expect(store.getSnapshot().rightbarInstant).toBe(false)
+  })
+
+  it('does not let an unchanged frame measurement reset the fullscreen-exit marker', () => {
+    const { store, actions } = createLayoutStore().create()
+    actions.openRightbar(true, true)
+    actions.closeRightbar()
+    const closed = store.getSnapshot()
+    actions.setViewportWidth(closed.viewportWidth)
+    expect(store.getSnapshot()).toBe(closed)
+  })
+
+  it.each([true, false])('clears the exit marker on a fresh opening with fullscreen=%s', (fullscreen) => {
+    const { store, actions } = createLayoutStore().create()
+    actions.openRightbar(true, true)
+    actions.closeRightbar()
+    actions.openRightbar(true, fullscreen)
+    expect(store.getSnapshot()).toMatchObject({ rightbarShown: true, rightbarFullscreen: fullscreen, rightbarInstant: false })
   })
 })
diff --git a/packages/client/ui-layout/tests/service.client.spec.ts b/packages/client/ui-layout/tests/service.client.spec.ts
index ea4118927c..a95c6a5b44 100644
--- a/packages/client/ui-layout/tests/service.client.spec.ts
+++ b/packages/client/ui-layout/tests/service.client.spec.ts
@@ -1,40 +1,51 @@
 import { describe, expect, it, vi } from 'vitest'
-import { LayoutController } from '@deepseek-ai/dsh-client-ui-layout/src/client/service.ts'
-import type { PanelActions } from '@deepseek-ai/dsh-client-ui-layout/src/client/service.ts'
+import { LayoutController } from '../src/client/service.ts'
+import type { PanelActions } from '../src/client/service.ts'
 
 function fakePanels(): PanelActions {
   return {
     setSidebar: vi.fn(),
-    setDetails: vi.fn(),
     toggleSidebar: vi.fn(),
-    setNarrow: vi.fn(),
-    openDetails: vi.fn(),
-    closeDetails: vi.fn(),
+    setViewportWidth: vi.fn(),
+    setRightbar: vi.fn(),
+    openRightbar: vi.fn(),
+    closeRightbar: vi.fn(),
   }
 }
 
 describe('LayoutController', () => {
+  it('forwards the right column transitions to the attached set', () => {
+    const service = new LayoutController()
+    const panels = fakePanels()
+    service.attachPanels(panels)
+
+    service.openRightbar(true, false)
+    service.openRightbar(true, true)
+    service.openRightbar(false, true)
+    service.closeRightbar()
+
+    expect(panels.openRightbar).toHaveBeenNthCalledWith(1, true, false)
+    expect(panels.openRightbar).toHaveBeenNthCalledWith(2, true, true)
+    expect(panels.openRightbar).toHaveBeenNthCalledWith(3, false, true)
+    expect(panels.closeRightbar).toHaveBeenCalledTimes(1)
+    // The drag width stays the frame's own business, never the caller's.
+    expect(panels.setRightbar).not.toHaveBeenCalled()
+  })
+
   it('forwards the three panel actions to the attached set', () => {
     const service = new LayoutController()
     const panels = fakePanels()
     service.attachPanels(panels)
 
     service.toggleSidebar()
-    service.openDetails()
-    service.closeDetails()
 
     expect(panels.toggleSidebar).toHaveBeenCalledTimes(1)
-    expect(panels.openDetails).toHaveBeenCalledTimes(1)
-    expect(panels.closeDetails).toHaveBeenCalledTimes(1)
     expect(panels.setSidebar).not.toHaveBeenCalled()
-    expect(panels.setDetails).not.toHaveBeenCalled()
   })
 
   it('fails loud before the root entry wired its actions', () => {
     const service = new LayoutController()
     expect(() => { service.toggleSidebar() }).toThrow(/panel actions not wired/)
-    expect(() => { service.openDetails() }).toThrow(/panel actions not wired/)
-    expect(() => { service.closeDetails() }).toThrow(/panel actions not wired/)
   })
 
   it('re-attach overwrites the stale action set (entry re-register)', () => {
diff --git a/packages/client/ui-model-selection/package.json b/packages/client/ui-model-selection/package.json
index cbee5f3884..ac7104234d 100644
--- a/packages/client/ui-model-selection/package.json
+++ b/packages/client/ui-model-selection/package.json
@@ -58,6 +58,8 @@
     "@types/react": "~18.3.1",
     "@deepseek-ai/cordis": "workspace:^",
     "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@types/react-dom": "~18.3.0",
     "@deepseek-ai/dsh-client-store": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-client-ui-renderer": "workspace:^",
diff --git a/packages/client/ui-model-selection/src/client/ModelSelect.module.css b/packages/client/ui-model-selection/src/client/ModelSelect.module.css
index 85b67ba496..b2cb715287 100644
--- a/packages/client/ui-model-selection/src/client/ModelSelect.module.css
+++ b/packages/client/ui-model-selection/src/client/ModelSelect.module.css
@@ -49,12 +49,42 @@
   white-space: nowrap;
 }
 
-/* Effort value beside the model name (mock's 'High': same 13/20/500, caption tone). */
+/* Effort value beside the model name (mock's 'High': same 13/20/500, caption
+   tone). Adaptive priority: the huge shrink factor makes the effort absorb
+   all deficit first — it ellipsizes away to nothing before the model name
+   loses a single pixel, and the chevron stays snug throughout. */
 .triggerEffort {
-  flex: 0 0 auto;
+  flex-shrink: 1000;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
   color: var(--dsw-alias-label-caption);
 }
 
+/* Stand-in for the whole text below the icon-only cut: the settings page's
+   Models glyph (IconDataOutline16), hidden while any text fits. */
+.triggerIcon {
+  display: none;
+  flex: 0 0 auto;
+}
+
+/* Icon-only floor: past continuous shrink (effort ellipsizes away first, then
+   the name), a 360px composer row leaves the 45cqw cap too little for a
+   legible name, so the text yields to the Models glyph. Same anonymous
+   container as PermissionSelect's 460px cut (InputBar .row); the full name
+   stays reachable through the trigger's title and aria-label. */
+@container (max-width: 360px) {
+  .triggerIcon {
+    display: block;
+  }
+
+  .triggerLabel,
+  .triggerEffort {
+    display: none;
+  }
+}
+
 .chevron {
   flex: 0 0 auto;
   color: var(--dsw-alias-label-caption);
@@ -65,11 +95,12 @@
   transform: rotate(180deg);
 }
 
+/* Portaled to body and placed from the trigger rect by the component (the
+   Menu primitive's portal rules), so the sidebar and the columns' overflow
+   clips cannot crop it; z matches the primitive's .portal layer. */
 .menu {
-  position: absolute;
-  right: 0;
-  bottom: calc(100% + 8px);
-  z-index: 20;
+  position: fixed;
+  z-index: 1100;
   display: flex;
   flex-direction: column;
   /* Let the visible pane's rows set the card width, but keep pathological ids
diff --git a/packages/client/ui-model-selection/src/client/ModelSelect.tsx b/packages/client/ui-model-selection/src/client/ModelSelect.tsx
index e910651e86..e9fc0195ef 100644
--- a/packages/client/ui-model-selection/src/client/ModelSelect.tsx
+++ b/packages/client/ui-model-selection/src/client/ModelSelect.tsx
@@ -12,14 +12,15 @@
  * card; the in-menu strip with Retry remains the catalog-load surface.
  */
 import {
-  useEffect, useId, useMemo, useRef, useState, useSyncExternalStore,
-  type KeyboardEvent, type FocusEvent,
+  useEffect, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore,
+  type CSSProperties, type KeyboardEvent, type FocusEvent,
 } from 'react'
+import { createPortal } from 'react-dom'
 import clsx from 'clsx'
 import type { ModelReasoningEffort, ModelSelection } from '@deepseek-ai/dsh-api-remotes/client'
 import {
   IconCheckOutline16, IconChevronDownOutline14, IconChevronRightOutline14,
-  IconWarningOutline16, Toast,
+  IconDataOutline16, IconWarningOutline16, Toast,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
 import type { ModelSelectInjected } from './slots.ts'
@@ -35,6 +36,9 @@ interface EffortChoice {
   label: string
 }
 
+/** Unplaced portal card: hidden but laid out at a fixed origin so offsetWidth/offsetHeight are real (Menu primitive's measure pass). */
+const MEASURE_STYLE: CSSProperties = { visibility: 'hidden', left: 0, top: 0 }
+
 /**
  * Render the composer model seat.
  * @param props - owner share (locked) + injected face (shared directory
@@ -60,6 +64,8 @@ export function ModelSelect(
   const toastSeq = useRef(0)
   const rootRef = useRef<HTMLDivElement | null>(null)
   const triggerRef = useRef<HTMLButtonElement | null>(null)
+  const menuRef = useRef<HTMLDivElement | null>(null)
+  const [menuPos, setMenuPos] = useState<CSSProperties | null>(null)
   const itemRefs = useRef<(HTMLButtonElement | null)[]>([])
   const id = useId()
 
@@ -108,12 +114,49 @@ export function ModelSelect(
   useEffect(() => {
     if (!open) return
     const closeOutside = (event: MouseEvent): void => {
-      if (!rootRef.current?.contains(event.target as Node)) setOpen(false)
+      // The portaled card is outside the trigger subtree; check both.
+      if (rootRef.current?.contains(event.target as Node) === true) return
+      if (menuRef.current?.contains(event.target as Node) === true) return
+      setOpen(false)
     }
     document.addEventListener('mousedown', closeOutside)
     return () => { document.removeEventListener('mousedown', closeOutside) }
   }, [open])
 
+  // Portaled placement (the Menu primitive's portal rules: fixed from the
+  // anchor rect, measured before paint, clamped inside the viewport): above
+  // the trigger, right edges aligned. Depends on pane and directory state
+  // because pane switches and async catalog loads resize the card.
+  /* jscpd:ignore-start -- deliberate mirror of ui-primitives useAnchoredPosition:
+     that hook only places from the anchor's LEFT edge, while this card aligns
+     right edges (x = rect.right - width), so the measure-and-clamp plumbing repeats. */
+  useLayoutEffect(() => {
+    if (!open) { setMenuPos(null); return }
+    const place = (): void => {
+      /* v8 ignore next 2 -- the trigger ref is attached whenever the menu is open. */
+      const rect = triggerRef.current?.getBoundingClientRect()
+      if (rect === undefined) return
+      const MARGIN = 12
+      const lw = menuRef.current?.offsetWidth ?? 0
+      const lh = menuRef.current?.offsetHeight ?? 0
+      let x = rect.right - lw
+      let y = rect.top - 8 - lh
+      if (lw > 0) x = Math.min(Math.max(x, MARGIN), window.innerWidth - lw - MARGIN)
+      if (lh > 0) y = Math.min(Math.max(y, MARGIN), window.innerHeight - lh - MARGIN)
+      setMenuPos({ left: x, top: y })
+    }
+    // First run measures the hidden pre-render (same commit as `open`), so
+    // the card lands placed before anything paints.
+    place()
+    window.addEventListener('scroll', place, true)
+    window.addEventListener('resize', place)
+    return () => {
+      window.removeEventListener('scroll', place, true)
+      window.removeEventListener('resize', place)
+    }
+  }, [open, pane, state])
+  /* jscpd:ignore-end */
+
   if (!available) return null
 
   const show = (): void => {
@@ -152,7 +195,10 @@ export function ModelSelect(
   }
 
   const onBlur = (event: FocusEvent<HTMLDivElement>): void => {
-    if (event.relatedTarget instanceof Node && rootRef.current?.contains(event.relatedTarget)) return
+    if (event.relatedTarget instanceof Node && (
+      rootRef.current?.contains(event.relatedTarget) === true
+      || menuRef.current?.contains(event.relatedTarget) === true
+    )) return
     close()
   }
 
@@ -232,15 +278,21 @@ export function ModelSelect(
           }
         }}
       >
+        <IconDataOutline16 className={css.triggerIcon} size={16} />
         <span className={css.triggerLabel}>{modelLabel}</span>
         {effortLabel !== undefined && <span className={css.triggerEffort}>{effortLabel}</span>}
         <IconChevronDownOutline14 className={clsx(css.chevron, open && css.chevronOpen)} />
       </button>
 
-      {open && (
+      {/* Portaled to body (Menu primitive's portal mode) so the sidebar and
+          column overflow clips cannot crop the card; synthetic events still
+          bubble through this React subtree, keeping onKeyDown/onBlur live. */}
+      {open && createPortal(
         <div
+          ref={menuRef}
           id={`${id}-menu`}
           className={css.menu}
+          style={menuPos ?? MEASURE_STYLE}
           role="menu"
           aria-label={t('menu.aria')}
           aria-busy={state.status === 'loading' || busy}
@@ -349,7 +401,8 @@ export function ModelSelect(
                 ))}
             </>
           )}
-        </div>
+        </div>,
+        document.body,
       )}
       {toast !== null && (
         <Toast
diff --git a/packages/client/ui-model-selection/tests/model-select.client.spec.tsx b/packages/client/ui-model-selection/tests/model-select.client.spec.tsx
index f30c3f7f3e..3b8c92d8bf 100644
--- a/packages/client/ui-model-selection/tests/model-select.client.spec.tsx
+++ b/packages/client/ui-model-selection/tests/model-select.client.spec.tsx
@@ -200,6 +200,43 @@ describe('ModelSelect reasoning effort', () => {
     expect(screen.queryByRole('button', { name: '重试' })).toBeNull()
   })
 
+  it('portals the placed menu card to body and closes only on truly-outside mousedown', () => {
+    const offsetWidth = Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'offsetWidth')!
+    const offsetHeight = Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'offsetHeight')!
+    Object.defineProperty(HTMLElement.prototype, 'offsetWidth', { configurable: true, get: () => 200 })
+    Object.defineProperty(HTMLElement.prototype, 'offsetHeight', { configurable: true, get: () => 300 })
+    try {
+      const { container } = render(<ModelSelect
+        locked={false}
+        available
+        directory={createSnapshotStore(state())}
+        load={vi.fn()}
+        select={vi.fn().mockResolvedValue(true)}
+        t={t}
+      />)
+      const trigger = screen.getByRole('button', { name: /选择模型/ })
+      fireEvent.click(trigger)
+      const menu = screen.getByRole('menu')
+      // Outside the composer subtree — column overflow clips cannot crop it.
+      expect(container.contains(menu)).toBe(false)
+      expect(menu.parentElement).toBe(document.body)
+      // jsdom anchor rects are all zero, so the measured 200x300 card clamps
+      // to the 12px viewport margin on both axes.
+      expect(menu.style.left).toBe('12px')
+      expect(menu.style.top).toBe('12px')
+      // Interactions inside the trigger subtree or the portaled card stay open.
+      fireEvent.mouseDown(menu)
+      fireEvent.mouseDown(trigger)
+      fireEvent.blur(trigger, { relatedTarget: menu })
+      expect(screen.getByRole('menu')).toBeTruthy()
+      fireEvent.mouseDown(document.body)
+      expect(screen.queryByRole('menu')).toBeNull()
+    } finally {
+      Object.defineProperty(HTMLElement.prototype, 'offsetWidth', offsetWidth)
+      Object.defineProperty(HTMLElement.prototype, 'offsetHeight', offsetHeight)
+    }
+  })
+
   it('renders no Agent-bound control for an addressed subagent session', () => {
     const load = vi.fn()
     render(<ModelSelect
diff --git a/packages/client/ui-permission-presets/tests/permission-presets-row.client.spec.tsx b/packages/client/ui-permission-presets/tests/permission-presets-row.client.spec.tsx
index b083a4074a..5ef380f656 100644
--- a/packages/client/ui-permission-presets/tests/permission-presets-row.client.spec.tsx
+++ b/packages/client/ui-permission-presets/tests/permission-presets-row.client.spec.tsx
@@ -1,4 +1,5 @@
 // @vitest-environment jsdom
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { Context } from '@deepseek-ai/cordis'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
@@ -10,6 +11,9 @@ import { zh } from '../src/client/locales.ts'
 import { SettingsDescribeMirror } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-mirror.ts'
 import { PermissionPresetSettingsController } from '../src/client/settings-store.ts'
 
+// Every fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 const schema = new SettingsSchemaService(new Context())
 
 /** Controller over a real mirror derived from the same scripted context. */
@@ -56,6 +60,7 @@ const useSessionPendingInteraction: PermissionRowProps['useSessionPendingInterac
 const runtime = {
   useSessions: (() => { throw new Error('unused') }) as never,
   useSessionPendingInteraction,
+  useResource,
   useWorkspaces: (() => { throw new Error('unused') }) as never,
 }
 
diff --git a/packages/client/ui-primitives/src/Menu.tsx b/packages/client/ui-primitives/src/Menu.tsx
index c70d4ad8d3..3130086777 100644
--- a/packages/client/ui-primitives/src/Menu.tsx
+++ b/packages/client/ui-primitives/src/Menu.tsx
@@ -98,7 +98,7 @@ export function Menu({ open, anchor, items, selectedId, selectedIds, onSelect, o
   compact?: boolean
   selection?: 'check' | 'fill'
   getAnchorRect?: () => DOMRect | null
-  className?: string
+  className?: string | undefined
 }) {
   const rootRef = useRef<HTMLSpanElement>(null)
   const listRef = useRef<HTMLDivElement>(null)
diff --git a/packages/client/ui-primitives/src/Toast.module.css b/packages/client/ui-primitives/src/Toast.module.css
index 0af6ec2151..793cbe23a1 100644
--- a/packages/client/ui-primitives/src/Toast.module.css
+++ b/packages/client/ui-primitives/src/Toast.module.css
@@ -5,7 +5,7 @@
 
 .toast {
   position: fixed;
-  top: 120px;
+  top: 40px;
   left: 50%;
   /* Above the 1000 the image lightbox backdrop uses: a failure reported while
      a preview is open must stay readable. */
@@ -15,7 +15,12 @@
   display: flex;
   align-items: center;
   gap: 10px;
-  max-width: min(560px, calc(100vw - 48px));
+  /* Fixed boxes with `left` set shrink-to-fit against the space RIGHT of
+     `left` (the -50% translate happens after sizing), so an anchored banner
+     near the window edge would wrap early. max-content sizes the box from
+     its text alone, capped by the max-width below. */
+  width: max-content;
+  max-width: min(640px, calc(100vw - 48px));
   padding: 12px 16px;
   border-radius: 14px;
   background: var(--dsw-alias-button-contrast-fill);
diff --git a/packages/client/ui-primitives/src/icons/index.tsx b/packages/client/ui-primitives/src/icons/index.tsx
index b2d52182cf..4afc31089f 100644
--- a/packages/client/ui-primitives/src/icons/index.tsx
+++ b/packages/client/ui-primitives/src/icons/index.tsx
@@ -778,6 +778,17 @@ export const IconClockOutline16 = ({ size = 16, className }: IconProps) => (
   </svg>
 )
 
+/** Thin-stroke gauge: dial arc open at the bottom, filled hub, square-cut needle to the upper right.
+ * The dial center sits at y=8.75, not 8: the bottom opening leaves the glyph top-heavy, and the
+ * 0.75 drop optically centers the drawn extent in the 16 box. */
+export const IconGaugeOutline16 = ({ 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="M3.49 13.26A6.375 6.375 0 1 1 12.51 13.26" stroke="currentColor" strokeWidth="1.25" />
+    <path d="M8 8.75L11.4 5.35" stroke="currentColor" strokeWidth="1.25" />
+    <circle cx="8" cy="8.75" r="1.55" fill="currentColor" />
+  </svg>
+)
+
 /** ic_send_outline_14 (figma extract): thin-stroke upward send arrow. */
 export const IconSendOutline14 = ({ size = 14, className }: IconProps) => (
   <svg width={size} height={size} className={className} viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg">
diff --git a/packages/client/ui-primitives/tests/icons.client.spec.tsx b/packages/client/ui-primitives/tests/icons.client.spec.tsx
index e29bb2ce14..1b9a9c7773 100644
--- a/packages/client/ui-primitives/tests/icons.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/icons.client.spec.tsx
@@ -17,8 +17,8 @@ const icons = Object.fromEntries(
 const iconNames = Object.keys(icons)
 
 describe('ic_ds_ icon set', () => {
-  it('exports the full icon set (46 deepsuite + 21 figma extracts + seven product glyphs outside those sets)', () => {
-    expect(iconNames.length).toBe(74)
+  it('exports the full icon set (46 deepsuite + 21 figma extracts + eight product glyphs outside those sets)', () => {
+    expect(iconNames.length).toBe(75)
   })
 
   it.each(iconNames)('%s renders an svg with currentColor fills and no hardcoded palette', (name) => {
diff --git a/packages/client/ui-settings-general/tests/components.client.spec.tsx b/packages/client/ui-settings-general/tests/components.client.spec.tsx
index d106f0211e..c3daeaaeb6 100644
--- a/packages/client/ui-settings-general/tests/components.client.spec.tsx
+++ b/packages/client/ui-settings-general/tests/components.client.spec.tsx
@@ -1,4 +1,5 @@
 // @vitest-environment jsdom
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { bindSnapshotSelector, RemoteError } from '@deepseek-ai/dsh-client-test-runtime'
@@ -10,6 +11,9 @@ import { SettingsDocumentAction } from '../src/client/SettingsDocumentAction.tsx
 import { SettingsDescribeMirror } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-mirror.ts'
 import { SettingsDocumentStore } from '../src/client/settings-document-store.ts'
 
+// Every fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 /** Store over a real mirror derived from the same scripted context. */
 function derivedDocumentStore(remote: object) {
   const ctx = { remote } as never
@@ -28,7 +32,7 @@ const unusedHook = (() => { throw new Error('unused by settings-general componen
 type AttentionSnapshot = Parameters<Parameters<TriggerContentProps['useSessionPendingInteraction']>[0]>[0]
 const noAttention: AttentionSnapshot = new Map()
 const useSessionPendingInteraction: TriggerContentProps['useSessionPendingInteraction'] = selector => selector(noAttention)
-const kit = { useSessions: unusedHook, useSessionPendingInteraction, useWorkspaces: unusedHook }
+const kit = { useSessions: unusedHook, useSessionPendingInteraction, useResource, useWorkspaces: unusedHook }
 
 describe('chrome content', () => {
   it('TriggerContent renders the icon with the label in the wide column', () => {
diff --git a/packages/client/ui-settings-general/tests/settings-root.client.spec.tsx b/packages/client/ui-settings-general/tests/settings-root.client.spec.tsx
index a496344319..3ebce030b4 100644
--- a/packages/client/ui-settings-general/tests/settings-root.client.spec.tsx
+++ b/packages/client/ui-settings-general/tests/settings-root.client.spec.tsx
@@ -1,4 +1,5 @@
 // @vitest-environment jsdom
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { useEffect, useState } from 'react'
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
@@ -7,6 +8,9 @@ import type { SettingsRootComponentProps } from '../src/client/shell-contract.ts
 import { SettingsRoot } from '../src/client/SettingsRoot.tsx'
 import { en } from '../src/client/locales.ts'
 
+// Every fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 afterEach(() => {
   cleanup()
   vi.useRealTimers()
@@ -72,6 +76,7 @@ function mount({
   const props: SettingsRootComponentProps = {
     useSessions,
     useSessionPendingInteraction,
+    useResource,
     useWorkspaces: unusedHook,
     wide,
     reconnect,
diff --git a/packages/client/ui-settings-models/tests/onboarding-dialog.client.spec.tsx b/packages/client/ui-settings-models/tests/onboarding-dialog.client.spec.tsx
index 996b0ff2f4..9f10184eaa 100644
--- a/packages/client/ui-settings-models/tests/onboarding-dialog.client.spec.tsx
+++ b/packages/client/ui-settings-models/tests/onboarding-dialog.client.spec.tsx
@@ -1,5 +1,6 @@
 // @vitest-environment jsdom
 /** First-run DeepSeek prompt behavior over the shared Models join. */
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import Schema from '@deepseek-ai/schemastery'
@@ -14,6 +15,9 @@ import { createModelsOperations } from '../src/client/operations.ts'
 import { en } from '../src/client/locales.ts'
 import { settingsSchema } from './settings-schema.client.ts'
 
+// Every fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 afterEach(() => {
   cleanup()
   document.getElementById('root')?.remove()
@@ -143,6 +147,7 @@ function harness(options: {
     openSection,
     useSessions: unusedHook,
     useSessionPendingInteraction,
+    useResource,
     useWorkspaces: unusedHook,
     controller,
     useModels: bindSnapshotSelector(controller.store),
diff --git a/packages/client/ui-settings-models/tests/welcome-notice.client.spec.tsx b/packages/client/ui-settings-models/tests/welcome-notice.client.spec.tsx
index efa8c01665..59b2b7acd8 100644
--- a/packages/client/ui-settings-models/tests/welcome-notice.client.spec.tsx
+++ b/packages/client/ui-settings-models/tests/welcome-notice.client.spec.tsx
@@ -1,4 +1,5 @@
 // @vitest-environment jsdom
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { bindSnapshotSelector, RemoteError } from '@deepseek-ai/dsh-client-test-runtime'
@@ -7,6 +8,9 @@ import { SettingsSchemaService } from '@deepseek-ai/dsh-client-ui-settings/src/c
 import { SettingsDescribeMirror } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-mirror.ts'
 import { SettingsScopeController } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-scope.ts'
 
+// Every fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 /** Stateless schema service for scope construction in this jsdom fixture. */
 const schemaService = new SettingsSchemaService(new Context())
 import { WelcomeNotice } from '../src/client/WelcomeNotice.tsx'
@@ -89,6 +93,7 @@ function mount(
     openSection: vi.fn(),
     useSessions: unusedHook,
     useSessionPendingInteraction,
+    useResource,
     useWorkspaces: unusedHook,
     controller,
     useWelcome: bindSnapshotSelector(controller.store),
diff --git a/packages/client/ui-sidebar-files/README.i18n.yaml b/packages/client/ui-sidebar-files/README.i18n.yaml
new file mode 100644
index 0000000000..52e19f2db3
--- /dev/null
+++ b/packages/client/ui-sidebar-files/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/client/ui-sidebar-files/README.md
+README.md: 6e9e305b15058797156f832a56a29c095b0641f3
+README.zh.md: 95a15444182a988fdf512735be4e0fbfcaad6bdd
diff --git a/packages/client/ui-sidebar-files/README.md b/packages/client/ui-sidebar-files/README.md
new file mode 100644
index 0000000000..6e9e305b15
--- /dev/null
+++ b/packages/client/ui-sidebar-files/README.md
@@ -0,0 +1,72 @@
+---
+description: "The right Sidebar's file-tree tab type for the dsh web client: the session workspace root listed one level at a time over the wire, opening files into the Sidebar by resource address."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-client-ui-sidebar-files
+
+English | [中文](README.zh.md)
+
+## Summary
+
+The right Sidebar's navigator tab type: the session's workspace root as a tree, listed one level at a time over the wire, opening files into the Sidebar. It is a page type reached from the guide and claims no address; it opens files by address for the `dsh-resource://file` viewers to claim — nothing in `ui-sidebar-right` knows this package.
+
+## Table of Contents
+
+- [What it registers](#what-it-registers)
+- [The tree](#the-tree)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="what-it-registers"></a>
+## What it registers
+
+- **The type** — `ctx.sidebarRightTabs.register(...)` with kind `files`, id `@deepseek-ai/dsh-client-ui-sidebar-files`, band `builtin`, no patterns, and one guide entry (order 10, titled from the `sidebarFiles` namespace) that opens the type.
+- **The body** — the keyed `sidebar.right.pane.tab` seat under that id: the tree, with its one control, reload, at the right of its header row.
+
+Six source files under `src/client/`: `definition.ts` (the type), `store.ts` (what it keeps), `face.ts` (how it lists, Remote binding included), `FilesBody.tsx` (what it draws, with its ordering and failure-line helpers), `locales.ts` (what it says), and `index.ts` (the wiring).
+
+<a id="the-tree"></a>
+## The tree
+
+The root is the session's working directory, read from `useSessions().byId[sessionId].cwd`, and labelled by `workspaceTitleOf` from `@deepseek-ai/dsh-util-workspace-path`. Every level is keyed by absolute path; a child's path is its parent's joined with the entry name by `/`. A level is listed when it is first expanded, through `remote.workspaceFiles.list(sessionId, absolutePath)` on the `@deepseek-ai/dsh-api-workspace-files` namespace; the adapter keeps the listing's entries and truncation flag and drops its workspace-relative path. Rows are ordered directories first, then by natural, case-insensitive name; dotfiles are shown like any other entry.
+
+| Entry type | Row |
+|---|---|
+| `directory` | Toggles; the level is fetched the first time it opens and kept while collapsed. |
+| `file` | Opens `dsh-resource://file/session/<sessionId>/<encoded path relative to the root>`, built by `fileAddressFor` from `@deepseek-ai/dsh-util-workspace-path` from the entry's absolute path and the tree's root, through `useTabInfo().tab.actions.openResource`, landing in the tab's own pane. |
+| `other` | Shown greyed and not clickable, so the directory is reported whole. |
+
+A level cut by the endpoint's entry cap ends with a marker; an empty level says so; a level that failed shows one line per code — `workspace-file/not-found`, `outside-workspace`, `not-directory` — and the transport's own message otherwise. Reload drops every listed level and asks again for the expanded ones; collapsed levels are fetched again when they next open. A session without a working directory shows a single line instead of a tree.
+
+State lives in the type's own store, bucketed by tab id: `root`, `levels` (loading / ready / failed per absolute path), and `expanded`. The owner's `signal` ends a bucket: on abort the tab is forgotten and a listing that settles afterwards writes nothing.
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as this package draws a workspace file tree in the browser and registers nothing model-facing.
+
+#### KV Cache effect
+
+None; directory listings travel over the Remote and assemble no model request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+- **Listing only.** No search, artifact filter, drag-and-drop, rename, context menu, current-file highlight, or filesystem watching; a level changes only through reload.
+- **One root.** The tree is rooted at the session's working directory; there is no way to browse above it, and the Host refuses paths outside the workspace root anyway.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>
+
+**Runtime invariant:** No companion is published. The tree's only runtime state is one Slot store per tab, written by the body that owns it and forgotten on the tab's abort signal; there is no second observation of it to compare against.
diff --git a/packages/client/ui-sidebar-files/README.zh.md b/packages/client/ui-sidebar-files/README.zh.md
new file mode 100644
index 0000000000..95a1544418
--- /dev/null
+++ b/packages/client/ui-sidebar-files/README.zh.md
@@ -0,0 +1,72 @@
+---
+description: "dsh Web 客户端右侧 Sidebar 的文件树 tab 类型：逐层经线上列出会话工作区根目录，按资源地址把文件打开到 Sidebar。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-client-ui-sidebar-files
+
+[English](README.md) | 中文
+
+## 概述
+
+右侧 Sidebar 的导航器 tab 类型：把会话的工作区根目录画成一棵树，逐层经线上列出，并把文件打开到 Sidebar 里。它是从引导页进入的页类型，不认领任何地址；它按地址打开文件，交给 `dsh-resource://file` 的查看器认领：`ui-sidebar-right` 里没有任何东西认识本包。
+
+## 目录
+
+- [注册了什么](#what-it-registers)
+- [树](#the-tree)
+- [模型体验](#model-experience)
+- [已知限制与暂缓事项](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="what-it-registers"></a>
+## 注册了什么
+
+- **类型**：`ctx.sidebarRightTabs.register(...)`，kind 为 `files`，id 为 `@deepseek-ai/dsh-client-ui-sidebar-files`，档位 `builtin`，没有 patterns，另有一个打开该类型的引导页入口（order 10，标题取自 `sidebarFiles` 命名空间）。
+- **正文**：以该 id 为键的 `sidebar.right.pane.tab` 坑位：树本身，以及它唯一的控件、位于标题行右端的重新读取。
+
+`src/client/` 下六个源文件：`definition.ts`（类型是什么）、`store.ts`（它保存什么）、`face.ts`（它如何列目录，含 Remote 绑定）、`FilesBody.tsx`（它画什么，含排序与失败行两个辅助函数）、`locales.ts`（它说什么）、`index.ts`（接线）。
+
+<a id="the-tree"></a>
+## 树
+
+根是会话的工作目录，读自 `useSessions().byId[sessionId].cwd`，标签由 `@deepseek-ai/dsh-util-workspace-path` 的 `workspaceTitleOf` 给出。每一层以绝对路径为键；子路径是父路径以 `/` 拼上条目名。一层在首次展开时经 `@deepseek-ai/dsh-api-workspace-files` 命名空间的 `remote.workspaceFiles.list(sessionId, absolutePath)` 列出；适配层保留列表的条目与截断标志，丢弃其工作区相对路径。行序为目录优先，其后按自然序、不分大小写的名称排列；dotfiles 与其他条目一样显示。
+
+| 条目类型 | 行 |
+|---|---|
+| `directory` | 切换展开与折叠；该层在首次打开时拉取，折叠期间保留。 |
+| `file` | 经 `useTabInfo().tab.actions.openResource` 打开 `dsh-resource://file/session/<sessionId>/<encoded path relative to the root>`，地址由 `@deepseek-ai/dsh-util-workspace-path` 的 `fileAddressFor` 从条目的绝对路径与树的根生成，落在该 tab 自己的 pane 里。 |
+| `other` | 灰显且不可点击，使目录被完整报告。 |
+
+被端点条目上限截断的层以一条标记收尾；空层如实说明；失败的层按错误码各显示一行（`workspace-file/not-found`、`outside-workspace`、`not-directory`），其他情况显示传输层自己的消息。重新读取丢弃所有已列出的层并只对展开中的层重新请求；折叠的层在下次打开时重新拉取。没有工作目录的会话只显示一行说明，而不是树。
+
+状态住在类型自己的存储里，按 tab id 分桶：`root`、`levels`（每个绝对路径的 loading / ready / failed）与 `expanded`。owner 的 `signal` 终结一个桶：中止时忘掉该 tab，其后才结算的列表什么也不写。
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为本包在浏览器里绘制工作区文件树，不注册任何面向模型的内容。
+
+#### KV Cache 影响
+
+无；目录列表经 Remote 传输，不会组装模型请求。
+
+## 已知限制与暂缓事项
+
+<a id="known-limitations-and-deferred-work"></a>
+- **只有列目录。**没有搜索、产物过滤、拖拽、重命名、右键菜单、当前文件高亮或文件系统监听；一层只会因重新读取而变化。
+- **只有一个根。**树以会话工作目录为根；没有办法浏览到它之上，而 Host 本来也拒绝工作区根之外的路径。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文——点击展开</summary>
+
+无。
+
+</details>
+
+**运行时不变量：** 不发布 companion。树唯一的运行时状态是每 tab 一份的 Slot store，由持有它的正文写入、随 tab 的中止信号忘掉；没有第二个观测源可与之比对。
diff --git a/packages/client/ui-sidebar-files/package.json b/packages/client/ui-sidebar-files/package.json
new file mode 100644
index 0000000000..0ba064054e
--- /dev/null
+++ b/packages/client/ui-sidebar-files/package.json
@@ -0,0 +1,76 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-sidebar-files",
+  "description": "Workspace file tree tab type for the right Sidebar: lazy directory listing over the workspaceFiles Remote namespace, opening files into the Sidebar",
+  "version": "0.1.3-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/ui-sidebar-files"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-api-workspace-files",
+        "@deepseek-ai/dsh-client-ui-sidebar-right",
+        "@deepseek-ai/dsh-client-ui-session",
+        "@deepseek-ai/dsh-api-remotes"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "clsx": "^2.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "workspace:^"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "workspace:^",
+    "@deepseek-ai/dsh-api-remotes": "workspace:^",
+    "@deepseek-ai/dsh-api-workspace-files": "workspace:^",
+    "@deepseek-ai/dsh-client-locale": "workspace:^",
+    "@deepseek-ai/dsh-client-store": "workspace:^",
+    "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-dockkit": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-renderer": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-session": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-util-workspace-path": "workspace:^",
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ]
+}
diff --git a/packages/client/ui-sidebar-files/src/client/FilesBody.module.css b/packages/client/ui-sidebar-files/src/client/FilesBody.module.css
new file mode 100644
index 0000000000..4ae79aa58a
--- /dev/null
+++ b/packages/client/ui-sidebar-files/src/client/FilesBody.module.css
@@ -0,0 +1,128 @@
+.root {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  min-height: 0;
+  overflow: auto;
+  padding: 4px 0 8px;
+  color: var(--dsw-alias-label-primary);
+  font-size: var(--dsh-content-font-size-secondary, 13px);
+  line-height: 1.5;
+}
+
+.header {
+  display: flex;
+  flex: 0 0 auto;
+  gap: 6px;
+  align-items: center;
+  padding: 4px 10px;
+  color: var(--dsw-alias-label-secondary);
+  font-weight: 500;
+}
+
+.level {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+/* Every nested level indents by one step; the root level sits under the header. */
+.level .level {
+  padding-left: 14px;
+}
+
+.item {
+  margin: 0;
+  padding: 0;
+}
+
+.row {
+  display: flex;
+  gap: 6px;
+  align-items: center;
+  width: 100%;
+  min-width: 0;
+  padding: 3px 10px;
+  color: inherit;
+  font: inherit;
+  text-align: left;
+  background: transparent;
+  border: 0;
+  border-radius: 6px;
+  cursor: pointer;
+}
+
+.row:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.icon {
+  flex: 0 0 auto;
+  color: var(--dsw-alias-label-secondary);
+}
+
+/* The document glyph is drawn 24×28; it rides the row at icon height. */
+.fileIcon {
+  flex: 0 0 auto;
+  width: 14px;
+  height: 16px;
+}
+
+.name {
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+/* Neither a file nor a directory: shown so the directory is reported whole,
+   greyed so nobody tries to open it. */
+.other {
+  color: var(--dsw-alias-label-tertiary);
+  cursor: default;
+}
+
+.other:hover {
+  background: transparent;
+}
+
+.note {
+  margin: 0;
+  padding: 3px 10px;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 12px;
+}
+
+.status {
+  display: flex;
+  flex-direction: column;
+  padding: 12px 10px;
+}
+
+.statusLine {
+  margin: 0;
+  color: var(--dsw-alias-label-secondary);
+  font-size: var(--dsh-content-font-size-secondary, 13px);
+  line-height: 1.6;
+}
+
+/* The header's reload control, pushed to the row's right edge. */
+.tool {
+  display: inline-flex;
+  flex: 0 0 auto;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  margin-left: auto;
+  padding: 0;
+  color: var(--dsw-alias-label-secondary);
+  background: transparent;
+  border: 0;
+  border-radius: 6px;
+  cursor: pointer;
+}
+
+.tool:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
diff --git a/packages/client/ui-sidebar-files/src/client/FilesBody.tsx b/packages/client/ui-sidebar-files/src/client/FilesBody.tsx
new file mode 100644
index 0000000000..46727638b7
--- /dev/null
+++ b/packages/client/ui-sidebar-files/src/client/FilesBody.tsx
@@ -0,0 +1,192 @@
+/**
+ * The file tree's body: the session's workspace root, listed one level at a time.
+ *
+ * Everything the tree keeps lives in its store, keyed by tab; everything it asks
+ * for goes through its injected face. The component itself only decides what to
+ * draw for each absolute path and what a click means: a directory toggles, a
+ * file opens through the owner's `tabActions` for a `file:` viewer to claim, and
+ * anything else is shown but refuses to open. The header row carries the one
+ * control: reload, which drops every listed level and asks again for the
+ * expanded ones.
+ */
+import { useEffect } from 'react'
+import type { ReactNode } from 'react'
+import clsx from 'clsx'
+import type { RemoteFailure } from '@deepseek-ai/dsh-api-remotes/client'
+import type { PropsLocale, PropsRuntime, PropsStore, TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
+import {
+  DocumentFileIcon, IconFolderClose16, IconFolderOpen16, IconRefreshOutline16,
+} from '@deepseek-ai/dsh-client-ui-primitives'
+import { fileAddressFor, workspaceTitleOf } from '@deepseek-ai/dsh-util-workspace-path'
+import type { WorkspaceDirectoryEntry } from '@deepseek-ai/dsh-api-workspace-files/types'
+import { childPath } from './face.ts'
+import type { FilesInjected } from './face.ts'
+import type {} from './locales.ts'
+import type { FilesTabState, createFilesStore } from './store.ts'
+import css from './FilesBody.module.css'
+
+/** The body's composed props: the tab it draws, its store, its face, and its copy. */
+export type FilesBodyProps =
+  & PropsRuntime<'sidebar.right.pane.tab'>
+  & PropsStore<ReturnType<typeof createFilesStore>>
+  & FilesInjected
+  & PropsLocale<'sidebarFiles'>
+
+/** Natural, case-insensitive name order, so `file2` precedes `file10`. */
+const byName = new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' })
+
+/**
+ * Order one level's entries for display: directories first, then everything
+ * else, each group by name. The endpoint's order is a listing fact; this is the
+ * reader's.
+ * @param entries - the listing as the endpoint returned it.
+ * @returns a new array, directories first, then by name within each group.
+ */
+export function orderEntries(entries: readonly WorkspaceDirectoryEntry[]): WorkspaceDirectoryEntry[] {
+  return [...entries].sort((left, right) => {
+    const group = Number(right.type === 'directory') - Number(left.type === 'directory')
+    return group !== 0 ? group : byName.compare(left.name, right.name)
+  })
+}
+
+/**
+ * Say why a directory could not be listed, in terms of the directory.
+ * @param t - namespace-bound translate.
+ * @param failure - the settled Remote failure.
+ * @returns the line to show under the directory.
+ */
+export function failureLine(t: TranslateNS<'sidebarFiles'>, failure: RemoteFailure): string {
+  switch (failure.code) {
+    case 'workspace-file/not-found': return t('error.notFound')
+    case 'workspace-file/outside-workspace': return t('error.outsideWorkspace')
+    case 'workspace-file/not-directory': return t('error.notDirectory')
+    // Carrier and unclassified host failures reach the reader as themselves:
+    // this tree knows nothing useful to add to a transport-level message.
+    default: return t('error.unavailable', { message: failure.message })
+  }
+}
+
+/** What every level shares: the tab's tree and the two gestures. */
+interface TreeContext {
+  readonly state: FilesTabState
+  readonly onToggle: (path: string) => void
+  readonly onOpen: (path: string) => void
+  readonly t: TranslateNS<'sidebarFiles'>
+}
+
+/** One entry's row, and its children when it is an expanded directory. */
+function Entry({ parent, entry, tree }: { parent: string; entry: WorkspaceDirectoryEntry; tree: TreeContext }): ReactNode {
+  const path = childPath(parent, entry.name)
+  if (entry.type === 'directory') {
+    const expanded = tree.state.expanded.includes(path)
+    return (
+      <li className={css.item} data-files-entry="directory" data-files-path={path}>
+        <button type="button" className={css.row} aria-expanded={expanded} onClick={() => { tree.onToggle(path) }}>
+          {expanded ? <IconFolderOpen16 className={css.icon} /> : <IconFolderClose16 className={css.icon} />}
+          <span className={css.name}>{entry.name}</span>
+        </button>
+        {expanded && <ul className={css.level}><Level path={path} tree={tree} /></ul>}
+      </li>
+    )
+  }
+  if (entry.type === 'file') {
+    return (
+      <li className={css.item} data-files-entry="file" data-files-path={path}>
+        <button type="button" className={css.row} onClick={() => { tree.onOpen(path) }}>
+          <DocumentFileIcon className={css.fileIcon} />
+          <span className={css.name}>{entry.name}</span>
+        </button>
+      </li>
+    )
+  }
+  return (
+    <li className={css.item} data-files-entry="other" data-files-path={path}>
+      <span className={clsx(css.row, css.other)} aria-disabled="true" title={tree.t('entry.other')}>
+        <span className={css.name}>{entry.name}</span>
+      </span>
+    </li>
+  )
+}
+
+/** One directory's rows: its state while listing, its entries once listed. */
+function Level({ path, tree }: { path: string; tree: TreeContext }): ReactNode {
+  const { state, t } = tree
+  const level = state.levels[path]
+  if (level === undefined || level.kind === 'loading') {
+    return <li className={css.note} data-files-row="loading">{t('loading')}</li>
+  }
+  if (level.kind === 'failed') {
+    return (
+      <li className={css.note} data-files-row="failed" data-files-code={level.failure.code}>
+        {failureLine(t, level.failure)}
+      </li>
+    )
+  }
+  const entries = orderEntries(level.level.entries)
+  return (
+    <>
+      {entries.length === 0 && <li className={css.note} data-files-row="empty">{t('empty')}</li>}
+      {entries.map(entry => <Entry key={entry.name} parent={path} entry={entry} tree={tree} />)}
+      {level.level.truncated && <li className={css.note} data-files-row="truncated">{t('truncated')}</li>}
+    </>
+  )
+}
+
+/** The file tree's body: the workspace root and whatever the reader has opened under it. */
+export function FilesBody({
+  useTabInfo, sessionId, useSessions, useStore, actions, start, load, toggle, t,
+}: FilesBodyProps): ReactNode {
+  const { tab } = useTabInfo()
+  const { signal, actions: tabActions } = tab
+  const cwd = useSessions(sessions => sessions.byId[sessionId]?.cwd)
+  const state = useStore(store => store.byTab[tab.id])
+  useEffect(() => {
+    // A bucket gone because the record aborted must not be re-seeded by a
+    // component that has not unmounted yet.
+    if (state !== undefined || cwd === undefined || signal.aborted) return
+    start(tab.id, cwd, signal)
+  }, [state, cwd, tab.id, signal, start])
+
+  if (cwd === undefined) {
+    return (
+      <div className={css.status} data-files-state="no-workspace">
+        <p className={css.statusLine}>{t('noWorkspace')}</p>
+      </div>
+    )
+  }
+  if (state === undefined) return null
+  const tree: TreeContext = {
+    state,
+    onToggle: (path) => { toggle(tab.id, path, state.levels[path] !== undefined, signal) },
+    // Every row is under the tree's root, so its address is session-relative.
+    onOpen: (path) => { tabActions.openResource(fileAddressFor(sessionId, state.root, path)) },
+    t,
+  }
+  // Reload drops every level and asks again for the expanded ones; a collapsed
+  // level is fetched again the next time it opens.
+  const reload = (): void => {
+    actions.reset(tab.id)
+    for (const path of state.expanded) load(tab.id, path, signal)
+  }
+  // A separator-only root has no final segment; the root itself is the label then.
+  const title = workspaceTitleOf(state.root) || state.root
+  return (
+    <div className={css.root} data-files-state="tree" data-files-root={state.root}>
+      <div className={css.header}>
+        <IconFolderOpen16 className={css.icon} />
+        <span className={css.name}>{title}</span>
+        <button
+          type="button"
+          className={css.tool}
+          aria-label={t('reload')}
+          title={t('reload')}
+          data-files-reload
+          onClick={reload}
+        >
+          <IconRefreshOutline16 />
+        </button>
+      </div>
+      <ul className={css.level}><Level path={state.root} tree={tree} /></ul>
+    </div>
+  )
+}
diff --git a/packages/client/ui-sidebar-files/src/client/definition.ts b/packages/client/ui-sidebar-files/src/client/definition.ts
new file mode 100644
index 0000000000..f967a472a0
--- /dev/null
+++ b/packages/client/ui-sidebar-files/src/client/definition.ts
@@ -0,0 +1,37 @@
+/**
+ * Stage one of this package's registration: what the `files` tab type IS.
+ *
+ * The type is a page, not a viewer: it claims no address. The guide page offers
+ * it as an entry box, and the tree opens files through `tabActions.openResource`
+ * for the `dsh-resource://file` viewers to claim.
+ */
+import type { SidebarRightTabDefinition } from '@deepseek-ai/dsh-client-ui-sidebar-right/client'
+import type { TranslateNS } from '@deepseek-ai/dsh-client-locale/client'
+import type {} from './locales.ts'
+import { IconFolderClose16 } from '@deepseek-ai/dsh-client-ui-primitives'
+
+/** The tab kind this package owns. */
+export const FILES_KIND = 'files'
+
+/** This implementation's identity in the tab system, and the key its body registers under. */
+export const FILES_ID = '@deepseek-ai/dsh-client-ui-sidebar-files'
+
+/**
+ * The files type's registry definition.
+ * @param t - namespace-bound translate, read fresh on every label call.
+ * @returns the definition to register.
+ */
+export function filesDefinition(t: TranslateNS<'sidebarFiles'>): SidebarRightTabDefinition {
+  return {
+    id: FILES_ID,
+    kind: FILES_KIND,
+    priority: 'builtin',
+    title: () => t('type.label'),
+    guide: [{
+      order: 10,
+      title: () => t('guide.title'),
+      description: () => t('guide.description'),
+      icon: IconFolderClose16,
+    }],
+  }
+}
diff --git a/packages/client/ui-sidebar-files/src/client/face.ts b/packages/client/ui-sidebar-files/src/client/face.ts
new file mode 100644
index 0000000000..a170e897ce
--- /dev/null
+++ b/packages/client/ui-sidebar-files/src/client/face.ts
@@ -0,0 +1,149 @@
+/**
+ * The tree's asynchronous half: listing directories into the store.
+ *
+ * The component never awaits anything. It calls `start` / `load` / `toggle`, and
+ * this face performs the listing and writes the outcome through the store's own
+ * actions — the Slot-standard `inject` shape, so the session id is resolved by
+ * the framework and the write set stays the store's.
+ *
+ * The listing itself is bound here to the Client Remote face: the tree keys
+ * every level by absolute path and hands the endpoint that same absolute path;
+ * the endpoint answers with the directory's workspace-relative path as well,
+ * which the tree has no use for and drops.
+ *
+ * One level has one listing in force: asking for a level again — the reload
+ * gesture, a directory reopened after a reset — retires the listing still in
+ * flight for it, whose settlement then writes nothing. Cleanup rides the owner's
+ * `signal`: a request is not made for a record that already ended, and when the
+ * record goes away the bucket and the tab's listing bookkeeping are forgotten,
+ * so no later settlement writes to it.
+ */
+import type { ClientRemote, RemoteResult } from '@deepseek-ai/dsh-api-remotes/client'
+import type { BoundActions } from '@deepseek-ai/dsh-client-store'
+import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { DirLevel, createFilesStore } from './store.ts'
+
+/**
+ * One directory listing, bound to a Remote face.
+ *
+ * The session travels with the call because the endpoint resolves the workspace
+ * root from it: the same path means different directories in different sessions.
+ * A Remote call does not reject — the result carries the failure.
+ */
+export type ListWorkspaceDirectory = (
+  sessionId: SessionId,
+  path: string,
+  signal: AbortSignal,
+) => Promise<RemoteResult<DirLevel>>
+
+/**
+ * The slice of the Client Remote face this package calls: the `workspaceFiles`
+ * namespace's `list`, exactly as the Host's generated client declares it.
+ */
+export type WorkspaceFilesListRemote = {
+  readonly workspaceFiles: Pick<ClientRemote['workspaceFiles'], 'list'>
+}
+
+/**
+ * Bind the listing to one Remote face, keeping only what the tree stores.
+ * @param remote - the Client Remote face carrying the `workspaceFiles` namespace.
+ * @returns the listing the tree's face performs.
+ */
+export function createList(remote: WorkspaceFilesListRemote): ListWorkspaceDirectory {
+  return async (sessionId, path, signal) => {
+    const result = await remote.workspaceFiles.list(sessionId, path, signal)
+    if (!result.ok) return result
+    return { ok: true, value: { entries: result.value.entries, truncated: result.value.truncated } }
+  }
+}
+
+/**
+ * The absolute path of one child entry.
+ *
+ * Joined with `/` whatever the parent's separators: the Host resolves mixed
+ * separators, and the tree only needs a stable key.
+ * @param parent - absolute path of the listed directory.
+ * @param name - the entry's basename.
+ * @returns the child's absolute path.
+ */
+export function childPath(parent: string, name: string): string {
+  return `${parent.replace(/[/\\]+$/, '')}/${name}`
+}
+
+/** The tree's injected business face, as the body receives it. */
+export interface FilesInjected {
+  /**
+   * Seed this tab's tree and list its root.
+   * @param tabId - the tab being drawn.
+   * @param root - absolute path of the workspace root.
+   * @param signal - the tab record's lifetime.
+   */
+  readonly start: (tabId: TabId, root: string, signal: AbortSignal) => void
+  /**
+   * List one directory into the store.
+   * @param tabId - the tab being drawn.
+   * @param path - absolute directory path.
+   * @param signal - the tab record's lifetime.
+   */
+  readonly load: (tabId: TabId, path: string, signal: AbortSignal) => void
+  /**
+   * Open or collapse one directory, listing it the first time it opens.
+   * @param tabId - the tab being drawn.
+   * @param path - absolute directory path.
+   * @param loaded - whether this level already has state.
+   * @param signal - the tab record's lifetime.
+   */
+  readonly toggle: (tabId: TabId, path: string, loaded: boolean, signal: AbortSignal) => void
+}
+
+/**
+ * Bind the tree's face to one directory listing.
+ * @param list - the bound `workspaceFiles.list` call.
+ * @returns the Slot `inject` factory: session and bound actions in, face out.
+ */
+export function filesFace(
+  list: ListWorkspaceDirectory,
+): (sessionId: SessionId, actions: BoundActions<ReturnType<typeof createFilesStore>>) => FilesInjected {
+  return (
+    sessionId: SessionId,
+    actions: BoundActions<ReturnType<typeof createFilesStore>>,
+  ): FilesInjected => {
+    /** Per tab, per absolute path: the listing generation a settlement must match; the latest request wins. */
+    const generations = new Map<TabId, Map<string, number>>()
+    const nextGeneration = (tabId: TabId, path: string): number => {
+      const byPath = generations.get(tabId) ?? new Map<string, number>()
+      generations.set(tabId, byPath)
+      const generation = (byPath.get(path) ?? 0) + 1
+      byPath.set(path, generation)
+      return generation
+    }
+    const load = (tabId: TabId, path: string, signal: AbortSignal): void => {
+      if (signal.aborted) return
+      const generation = nextGeneration(tabId, path)
+      actions.loading(tabId, path)
+      void list(sessionId, path, signal).then((result) => {
+        // A newer listing of this level was asked for since, or the record is
+        // gone and its bookkeeping with it: nothing left for this one to write.
+        if (generations.get(tabId)?.get(path) !== generation) return
+        if (result.ok) actions.loaded(tabId, path, result.value)
+        else actions.failed(tabId, path, result.error)
+      })
+    }
+    return {
+      start(tabId, root, signal) {
+        actions.start(tabId, root)
+        signal.addEventListener('abort', () => {
+          generations.delete(tabId)
+          actions.forget(tabId)
+        }, { once: true })
+        load(tabId, root, signal)
+      },
+      load,
+      toggle(tabId, path, loaded, signal) {
+        actions.toggled(tabId, path)
+        if (!loaded) load(tabId, path, signal)
+      },
+    }
+  }
+}
diff --git a/packages/client/ui-sidebar-files/src/client/index.ts b/packages/client/ui-sidebar-files/src/client/index.ts
new file mode 100644
index 0000000000..0f04544729
--- /dev/null
+++ b/packages/client/ui-sidebar-files/src/client/index.ts
@@ -0,0 +1,52 @@
+/**
+ * Browser half: register `files` as a right-Sidebar tab type.
+ *
+ * The public two-stage path, unmodified: the type into `ctx.sidebarRightTabs`,
+ * the body into the keyed `sidebar.right.pane.tab` seat under the type's `id`.
+ *
+ * The file split is this package's layering: what the type IS
+ * (`definition.ts`), what it keeps (`store.ts`), how it lists (`face.ts`), what
+ * it draws (`FilesBody.tsx`), what it says (`locales.ts`), and this module,
+ * which only wires them together.
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-api-remotes/client'
+import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
+import type {} from '@deepseek-ai/dsh-client-ui-session/client'
+import type {} from '@deepseek-ai/dsh-client-ui-sidebar-right/client'
+import { FILES_ID, filesDefinition } from './definition.ts'
+import { createList, filesFace } from './face.ts'
+import { FilesBody } from './FilesBody.tsx'
+import { en, zh } from './locales.ts'
+import { createFilesStore } from './store.ts'
+
+export type { SidebarFilesKey } from './locales.ts'
+export type { DirLevel, FilesState, FilesTabState, LevelState } from './store.ts'
+export type { FilesInjected, ListWorkspaceDirectory, WorkspaceFilesListRemote } from './face.ts'
+export type { FilesBodyProps } from './FilesBody.tsx'
+
+/** This package's copy namespace. */
+const NS = 'sidebarFiles'
+
+/**
+ * Required browser services: the tab registry, the keyed seat, the Remote
+ * carrier and its namespace, and copy.
+ */
+export const inject = ['slots', 'locale', 'sidebarRightTabs', 'remote', 'remote.workspaceFiles']
+
+/**
+ * Client plugin body: register the type, its dictionaries, then its body.
+ * @param ctx - client root context carrying the registry, the slots, and the Remote face.
+ */
+export function apply(ctx: ClientContext): void {
+  const t = ctx.locale.bind(NS)
+  ctx.effect(() => ctx.sidebarRightTabs.register(filesDefinition(t)), 'ui-sidebar-files: files type')
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-sidebar-files: dictionaries')
+
+  const store = createFilesStore()
+  const inject = filesFace(createList(ctx.remote))
+  ctx.effect(() => ctx.slots.inject('sidebar.right.pane.tab', () => ctx.slots.register(
+    { name: 'sidebar.right.pane.tab', key: FILES_ID, locale: NS, store, inject },
+    FilesBody,
+  )), 'ui-sidebar-files: files tab body')
+}
diff --git a/packages/client/ui-sidebar-files/src/client/locales.ts b/packages/client/ui-sidebar-files/src/client/locales.ts
new file mode 100644
index 0000000000..1976add093
--- /dev/null
+++ b/packages/client/ui-sidebar-files/src/client/locales.ts
@@ -0,0 +1,56 @@
+/**
+ * `sidebarFiles` namespace dictionaries, and the namespace's declaration.
+ *
+ * The failure lines name what the tree could not list, one code each, because a
+ * directory that is gone, one outside the workspace, and a path that is not a
+ * directory each suggest a different next step.
+ *
+ * The namespace merge lives with its key set so that any module naming
+ * `TranslateNS<'sidebarFiles'>` or `PropsLocale<'sidebarFiles'>` needs only this
+ * file, whichever entry a program loads first.
+ */
+import type {} from '@deepseek-ai/dsh-client-ui-slots'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap {
+    /** File-tree type name, guide entry, row states, and failure lines. */
+    sidebarFiles: SidebarFilesKey
+  }
+}
+
+/** Simplified Chinese dictionary and key-set source of truth. */
+export const zh = {
+  'type.label': '文件',
+  'guide.title': '文件',
+  'guide.description': '浏览这个会话工作区里的文件，点开就能查看。',
+  loading: '正在读取…',
+  empty: '空目录',
+  truncated: '条目太多，只显示了一部分。',
+  noWorkspace: '这个会话没有工作区目录。',
+  reload: '重新读取',
+  'entry.other': '这不是文件或目录，没法打开。',
+  'error.notFound': '这个目录不在了。可能已被移动或删除。',
+  'error.outsideWorkspace': '这个目录在工作区之外，侧栏不会读取它。',
+  'error.notDirectory': '这不是一个目录。',
+  'error.unavailable': '读取失败：{message}',
+} satisfies Record<string, string>
+
+/** Files dictionary key union. */
+export type SidebarFilesKey = keyof typeof zh
+
+/** English dictionary, checked against the Chinese key set. */
+export const en = {
+  'type.label': 'Files',
+  'guide.title': 'Files',
+  'guide.description': 'Browse the files in this session\'s workspace and open any of them.',
+  loading: 'Reading…',
+  empty: 'Empty directory',
+  truncated: 'Too many entries; showing only some of them.',
+  noWorkspace: 'This session has no workspace directory.',
+  reload: 'Reload',
+  'entry.other': 'Not a file or a directory, so it cannot be opened.',
+  'error.notFound': 'That directory is gone. It may have been moved or deleted.',
+  'error.outsideWorkspace': 'That directory is outside the workspace, so the sidebar will not read it.',
+  'error.notDirectory': 'That is not a directory.',
+  'error.unavailable': 'Read failed: {message}',
+} satisfies Record<SidebarFilesKey, string>
diff --git a/packages/client/ui-sidebar-files/src/client/store.ts b/packages/client/ui-sidebar-files/src/client/store.ts
new file mode 100644
index 0000000000..619ed0ba30
--- /dev/null
+++ b/packages/client/ui-sidebar-files/src/client/store.ts
@@ -0,0 +1,165 @@
+/**
+ * The file tree's view state: which directories are expanded, and what each
+ * loaded level contains.
+ *
+ * The tree is not one resource. A directory listing per level, expanded lazily,
+ * is state the type owns — so it lives in a Slot-standard exclusive store
+ * (one instance per session), bucketed by tab id because two tabs of this kind
+ * in one session expand independently.
+ *
+ * Writers run between `start` and `forget`: the owner's `signal` is what ends a
+ * bucket's life, and the face stops dispatching once it aborts.
+ */
+import { defineStore, type EngineStoreHandle } from '@deepseek-ai/dsh-client-store'
+import type { RemoteFailure } from '@deepseek-ai/dsh-api-remotes/client'
+import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+import type { WorkspaceDirectoryEntry } from '@deepseek-ai/dsh-api-workspace-files/types'
+
+/**
+ * One directory's contents, as one expanded level of the tree.
+ *
+ * The endpoint's listing also names the directory as a workspace-relative path;
+ * the tree keys every level by absolute path instead, so the adapter drops it.
+ */
+export interface DirLevel {
+  /** The directory's entries, in the endpoint's order. */
+  readonly entries: readonly WorkspaceDirectoryEntry[]
+  /** The listing hit the endpoint's entry cap, so entries are missing. */
+  readonly truncated: boolean
+}
+
+/** What one directory level is doing right now. */
+export type LevelState =
+  | { readonly kind: 'loading' }
+  | { readonly kind: 'ready'; readonly level: DirLevel }
+  | { readonly kind: 'failed'; readonly failure: RemoteFailure }
+
+/**
+ * One tab's tree: its root, the levels it has asked for, and what is open.
+ *
+ * Every path here is absolute: the root is the session's working directory as
+ * the Host reports it, and a child is the parent joined with the entry name.
+ */
+export interface FilesTabState {
+  /** Absolute path of the workspace root this tree is rooted at. */
+  root: string
+  /** Level state by absolute directory path; a path absent here was never asked for. */
+  levels: Record<string, LevelState>
+  /** Expanded absolute directory paths, root included. */
+  expanded: string[]
+}
+
+/** Every tab's tree, keyed by tab id. */
+export interface FilesState {
+  byTab: Record<TabId, FilesTabState>
+}
+
+/**
+ * One tab's bucket, which every writer after `start` relies on: the face only
+ * dispatches while the record's signal is live, and `forget` runs on its abort.
+ * @param state - the draft.
+ * @param tabId - the tab being written.
+ * @returns the tab's tree.
+ */
+function bucket(state: FilesState, tabId: TabId): FilesTabState {
+  const tree = state.byTab[tabId]
+  if (tree === undefined) throw new Error(`ui-sidebar-files: no tree for tab "${tabId}"`)
+  return tree
+}
+
+/** The tree store's write set; every action names the tab it writes. */
+type FilesActions = {
+  start: (draft: FilesState, tabId: TabId, root: string) => void
+  loading: (draft: FilesState, tabId: TabId, path: string) => void
+  loaded: (draft: FilesState, tabId: TabId, path: string, level: DirLevel) => void
+  failed: (draft: FilesState, tabId: TabId, path: string, failure: RemoteFailure) => void
+  toggled: (draft: FilesState, tabId: TabId, path: string) => void
+  reset: (draft: FilesState, tabId: TabId) => void
+  forget: (draft: FilesState, tabId: TabId) => void
+}
+
+/**
+ * Declare the file tree's store.
+ *
+ * A factory rather than a shared handle: the registration declares it as an
+ * exclusive store, so the framework mints one instance per session.
+ * @returns the store handle to declare on the registration.
+ */
+export function createFilesStore(): EngineStoreHandle<FilesState, FilesActions> {
+  return defineStore({
+    init: (): FilesState => ({ byTab: {} }),
+    actions: {
+      /**
+       * Seed one tab's tree at its workspace root, with the root expanded.
+       * @param d - draft state.
+       * @param tabId - the tab being drawn.
+       * @param root - absolute path of the workspace root.
+       */
+      start: (d, tabId: TabId, root: string) => {
+        d.byTab[tabId] = { root, levels: {}, expanded: [root] }
+      },
+      /**
+       * Mark one directory as being listed.
+       * @param d - draft state.
+       * @param tabId - the tab being drawn.
+       * @param path - absolute directory path.
+       */
+      loading: (d, tabId: TabId, path: string) => {
+        bucket(d, tabId).levels[path] = { kind: 'loading' }
+      },
+      /**
+       * Record one directory's contents.
+       * @param d - draft state.
+       * @param tabId - the tab being drawn.
+       * @param path - absolute directory path.
+       * @param level - the listing to show under it.
+       */
+      loaded: (d, tabId: TabId, path: string, level: DirLevel) => {
+        bucket(d, tabId).levels[path] = { kind: 'ready', level }
+      },
+      /**
+       * Record why one directory could not be listed.
+       * @param d - draft state.
+       * @param tabId - the tab being drawn.
+       * @param path - absolute directory path.
+       * @param failure - the settled Remote failure.
+       */
+      failed: (d, tabId: TabId, path: string, failure: RemoteFailure) => {
+        bucket(d, tabId).levels[path] = { kind: 'failed', failure }
+      },
+      /**
+       * Open a collapsed directory, or collapse an open one.
+       *
+       * A collapsed level keeps what it loaded, so reopening it draws at once.
+       * @param d - draft state.
+       * @param tabId - the tab being drawn.
+       * @param path - absolute directory path.
+       */
+      toggled: (d, tabId: TabId, path: string) => {
+        const state = bucket(d, tabId)
+        const at = state.expanded.indexOf(path)
+        if (at >= 0) state.expanded.splice(at, 1)
+        else state.expanded.push(path)
+      },
+      /**
+       * Drop every loaded level, keeping what is expanded.
+       *
+       * This is the reload gesture's first half: the expanded set says which
+       * levels to fetch again.
+       * @param d - draft state.
+       * @param tabId - the tab being drawn.
+       */
+      reset: (d, tabId: TabId) => {
+        bucket(d, tabId).levels = {}
+      },
+      /**
+       * Forget one tab's tree, for a tab record that is gone.
+       * @param d - draft state.
+       * @param tabId - the tab that went away.
+       */
+      forget: (d, tabId: TabId) => {
+        d.byTab = Object.fromEntries(Object.entries(d.byTab).filter(([id]) => id !== tabId))
+      },
+    },
+  })
+}
diff --git a/packages/client/ui-sidebar-files/src/css-modules.d.ts b/packages/client/ui-sidebar-files/src/css-modules.d.ts
new file mode 100644
index 0000000000..bc5e482353
--- /dev/null
+++ b/packages/client/ui-sidebar-files/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-files/src/index.ts b/packages/client/ui-sidebar-files/src/index.ts
new file mode 100644
index 0000000000..154525a7cb
--- /dev/null
+++ b/packages/client/ui-sidebar-files/src/index.ts
@@ -0,0 +1,4 @@
+/** Pure host half; the whole tab type lives in the browser export. */
+
+/** Host plugin body: the file tree contributes nothing to the host tree. */
+export function apply(): void {}
diff --git a/packages/client/ui-sidebar-files/tests/apply.client.spec.ts b/packages/client/ui-sidebar-files/tests/apply.client.spec.ts
new file mode 100644
index 0000000000..8ab773ae13
--- /dev/null
+++ b/packages/client/ui-sidebar-files/tests/apply.client.spec.ts
@@ -0,0 +1,89 @@
+/**
+ * The plugin's registrations, and their removal when the plugin goes.
+ *
+ * The registry is real, because "registered" means what it says a type is; the
+ * slot, locale, and Remote faces are recorders, because what matters here is
+ * what was handed to them — one body seat under the type's id with its store
+ * and face — and that every registration is gone after dispose, which is what
+ * makes a reload safe.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import { SidebarRightTabRegistry } from '@deepseek-ai/dsh-client-ui-sidebar-right/src/client/tab-registry.ts'
+import { FILES_ID, FILES_KIND } from '../src/client/definition.ts'
+import { apply, inject } from '../src/client/index.ts'
+import { apply as hostApply } from '../src/index.ts'
+import { FilesBody } from '../src/client/FilesBody.tsx'
+import { en, zh } from '../src/client/locales.ts'
+
+interface Recorded {
+  name: string
+  key: string
+  locale: string
+  store: unknown
+  inject: unknown
+  component: unknown
+}
+
+async function boot() {
+  const ctx = new Context()
+  const tabs = new SidebarRightTabRegistry(ctx)
+  const registered: Recorded[] = []
+  const slots = {
+    inject: vi.fn((_name: string, register: () => () => void) => register()),
+    register: vi.fn((options: Omit<Recorded, 'component'>, component: unknown) => {
+      const entry: Recorded = { ...options, component }
+      registered.push(entry)
+      return () => { registered.splice(registered.indexOf(entry), 1) }
+    }),
+  }
+  const dictionaries = new Map<string, unknown>()
+  const locale = {
+    // Copy is the dictionary's contract; the key stands in for the translation.
+    bind: vi.fn(() => (key: string) => key),
+    register: vi.fn((ns: string, dicts: unknown) => {
+      dictionaries.set(ns, dicts)
+      return () => { dictionaries.delete(ns) }
+    }),
+  }
+  const workspaceFiles = { list: vi.fn() }
+  ctx.provide('sidebarRightTabs', tabs as never)
+  ctx.provide('slots', slots as never)
+  ctx.provide('locale', locale as never)
+  ctx.provide('remote', { workspaceFiles } as never)
+  ctx.provide('remote.workspaceFiles', workspaceFiles as never)
+  const fiber = ctx.plugin({ inject: [...inject], apply })
+  await fiber.await()
+  return { tabs, registered, dictionaries, fiber }
+}
+
+describe('ui-sidebar-files apply', () => {
+  it('keeps the host Loader entry inert', () => {
+    expect(hostApply).not.toThrow()
+  })
+
+  it('registers the type, its dictionaries, and the body seat under the type\'s id with a store and a face', async () => {
+    const { tabs, registered, dictionaries } = await boot()
+    const definition = tabs.get(FILES_KIND)
+    expect(definition?.id).toBe(FILES_ID)
+    expect(definition?.priority).toBe('builtin')
+    expect(definition?.title('sidebar://files')).toBe('type.label')
+    expect(definition?.guide?.map(entry => [entry.order, entry.title(), entry.description()])).toEqual([[10, 'guide.title', 'guide.description']])
+    expect(dictionaries.get('sidebarFiles')).toEqual({ zh, en })
+    // The seat key is the implementation's id, not the kind: an extension may
+    // take the kind over, and the seat must still find this body.
+    expect(registered.map(entry => [entry.name, entry.key, entry.locale, entry.component])).toEqual([
+      ['sidebar.right.pane.tab', FILES_ID, 'sidebarFiles', FilesBody],
+    ])
+    expect(registered[0]?.store).toBeDefined()
+    expect(typeof registered[0]?.inject).toBe('function')
+  })
+
+  it('takes every registration back when the plugin is disposed', async () => {
+    const { tabs, registered, dictionaries, fiber } = await boot()
+    await fiber.dispose()
+    expect(tabs.get(FILES_KIND)).toBeUndefined()
+    expect(registered).toEqual([])
+    expect(dictionaries.size).toBe(0)
+  })
+})
diff --git a/packages/client/ui-sidebar-files/tests/definition.client.spec.ts b/packages/client/ui-sidebar-files/tests/definition.client.spec.ts
new file mode 100644
index 0000000000..dc5dfeda1b
--- /dev/null
+++ b/packages/client/ui-sidebar-files/tests/definition.client.spec.ts
@@ -0,0 +1,44 @@
+/**
+ * Stage one, as the registry sees it: the type is a page that claims no
+ * address, sits in the builtin band, and offers the guide page one entry that
+ * opens its kind.
+ */
+import { describe, expect, it } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import { SidebarRightTabRegistry } from '@deepseek-ai/dsh-client-ui-sidebar-right/src/client/tab-registry.ts'
+import { sessionFileAddress } from '@deepseek-ai/dsh-util-workspace-path'
+import {
+  FILES_ID, FILES_KIND, filesDefinition,
+} from '../src/client/definition.ts'
+import { zh } from '../src/client/locales.ts'
+
+const t = makeTranslate(zh)
+
+describe('filesDefinition', () => {
+  it('registers under its kind and id and claims no address', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register(filesDefinition(t))
+    expect(registry.get(FILES_KIND)?.id).toBe(FILES_ID)
+    expect(registry.candidates(sessionFileAddress('s-1', '/work/app/a.ts'))).toEqual([])
+  })
+
+  it('offers the guide page one entry at order 10 that opens the files kind', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register(filesDefinition(t))
+    const [entry, ...rest] = registry.guide()
+    expect(rest).toEqual([])
+    expect(entry?.order).toBe(10)
+    expect(entry?.kind).toBe(FILES_KIND)
+    expect(entry?.title()).toBe(zh['guide.title'])
+    expect(entry?.description()).toBe(zh['guide.description'])
+    expect(entry?.icon).toBeDefined()
+  })
+
+  it('sits in the builtin band and titles itself from the dictionary', () => {
+    const definition = filesDefinition(t)
+    expect(definition.priority).toBe('builtin')
+    expect(definition.patterns).toBeUndefined()
+    expect(definition.title('')).toBe(zh['type.label'])
+  })
+})
diff --git a/packages/client/ui-sidebar-files/tests/face.client.spec.ts b/packages/client/ui-sidebar-files/tests/face.client.spec.ts
new file mode 100644
index 0000000000..dfa1710b23
--- /dev/null
+++ b/packages/client/ui-sidebar-files/tests/face.client.spec.ts
@@ -0,0 +1,143 @@
+/**
+ * The tree's asynchronous half against a scripted listing, and the Remote
+ * adapter under it.
+ *
+ * The face's contract is what reaches the store and when: a level is `loading`
+ * before the listing settles, `ready` or `failed` after, never written once the
+ * owner's signal aborted or a newer listing of the level was asked for, and a
+ * tab whose record is gone leaves no bucket behind. The adapter's is what it
+ * keeps and what it drops: entries and the
+ * truncation flag reach the store, the endpoint's workspace-relative path does
+ * not, and a failure passes through untouched.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { RemoteError } from '@deepseek-ai/dsh-client-test-runtime'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { WorkspaceDirectoryListing } from '@deepseek-ai/dsh-api-workspace-files/types'
+import { childPath, createList, filesFace } from '../src/client/face.ts'
+import type { WorkspaceFilesListRemote } from '../src/client/face.ts'
+import { createFilesStore } from '../src/client/store.ts'
+import type { DirLevel } from '../src/client/store.ts'
+import { scriptedList } from './scripted-list.client.ts'
+import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+
+const SESSION = 's-1' as SessionId
+const ROOT = '/work/app'
+const TAB = 'tab-1' as TabId
+
+const LEVEL: DirLevel = { entries: [{ name: 'src', type: 'directory' }], truncated: false }
+
+function mount() {
+  const instance = createFilesStore().create()
+  const script = scriptedList()
+  const face = filesFace(script.list)(SESSION, instance.actions)
+  return { ...script, face, snapshot: () => instance.getSnapshot().byTab[TAB] }
+}
+
+describe('filesFace', () => {
+  it('start seeds the tab and lists the root with the session and the absolute root path', async () => {
+    const { face, list, settle, snapshot } = mount()
+    const controller = new AbortController()
+    face.start(TAB, ROOT, controller.signal)
+    expect(list).toHaveBeenCalledWith(SESSION, ROOT, controller.signal)
+    expect(snapshot()!.levels[ROOT]).toEqual({ kind: 'loading' })
+    await settle({ ok: true, value: LEVEL })
+    expect(snapshot()!.levels[ROOT]).toEqual({ kind: 'ready', level: LEVEL })
+  })
+
+  it('records a failed listing under its level', async () => {
+    const { face, settle, snapshot } = mount()
+    face.start(TAB, ROOT, new AbortController().signal)
+    const error = new RemoteError('workspace-file/not-directory', 'not a directory', { path: ROOT, kind: 'file' })
+    await settle({ ok: false, error })
+    expect(snapshot()!.levels[ROOT]).toEqual({ kind: 'failed', failure: error })
+  })
+
+  it('toggle expands and lists a directory the first time, and only toggles afterwards', async () => {
+    const { face, list, settle, snapshot } = mount()
+    const signal = new AbortController().signal
+    const child = `${ROOT}/src`
+    face.start(TAB, ROOT, signal)
+    await settle({ ok: true, value: LEVEL })
+    face.toggle(TAB, child, false, signal)
+    expect(list).toHaveBeenLastCalledWith(SESSION, child, signal)
+    expect(snapshot()!.expanded).toEqual([ROOT, child])
+    await settle({ ok: true, value: LEVEL })
+    face.toggle(TAB, child, true, signal)
+    expect(snapshot()!.expanded).toEqual([ROOT])
+    expect(list).toHaveBeenCalledTimes(2)
+  })
+
+  it('abort forgets the bucket and a late settlement writes nothing', async () => {
+    const { face, settle, snapshot } = mount()
+    const controller = new AbortController()
+    face.start(TAB, ROOT, controller.signal)
+    controller.abort()
+    expect(snapshot()).toBeUndefined()
+    await settle({ ok: true, value: LEVEL })
+    expect(snapshot()).toBeUndefined()
+  })
+
+  it('makes no request for a record that already ended', () => {
+    const { face, list } = mount()
+    const controller = new AbortController()
+    controller.abort()
+    face.load(TAB, ROOT, controller.signal)
+    expect(list).not.toHaveBeenCalled()
+  })
+
+  it('lets the latest listing of a level win, whichever settles first', async () => {
+    const { face, list, settle, settleLatest, snapshot, outstanding } = mount()
+    const signal = new AbortController().signal
+    const older: DirLevel = { entries: [{ name: 'old.txt', type: 'file' }], truncated: false }
+    face.start(TAB, ROOT, signal)
+    // The reload gesture asks for the root again while the first listing is still out.
+    face.load(TAB, ROOT, signal)
+    expect(list).toHaveBeenCalledTimes(2)
+    expect(outstanding()).toEqual([ROOT, ROOT])
+    await settleLatest({ ok: true, value: LEVEL })
+    expect(snapshot()!.levels[ROOT]).toEqual({ kind: 'ready', level: LEVEL })
+    // The retired listing lands afterwards and changes nothing.
+    await settle({ ok: true, value: older })
+    expect(snapshot()!.levels[ROOT]).toEqual({ kind: 'ready', level: LEVEL })
+    // A retired failure is dropped the same way.
+    face.load(TAB, ROOT, signal)
+    face.load(TAB, ROOT, signal)
+    await settleLatest({ ok: true, value: LEVEL })
+    await settle({ ok: false, error: new RemoteError('workspace-file/not-found', 'gone', { path: ROOT }) })
+    expect(snapshot()!.levels[ROOT]).toEqual({ kind: 'ready', level: LEVEL })
+  })
+})
+
+describe('createList', () => {
+  it('passes the session, the absolute path, and the signal through, and keeps entries and truncation', async () => {
+    const listing: WorkspaceDirectoryListing = {
+      path: 'src',
+      entries: [{ name: 'a.ts', type: 'file', size: 3 }],
+      truncated: true,
+    }
+    const list = vi.fn<WorkspaceFilesListRemote['workspaceFiles']['list']>()
+      .mockResolvedValue({ ok: true, value: listing })
+    const signal = new AbortController().signal
+    const result = await createList({ workspaceFiles: { list } })(SESSION, `${ROOT}/src`, signal)
+    expect(list).toHaveBeenCalledWith(SESSION, `${ROOT}/src`, signal)
+    expect(result).toEqual({ ok: true, value: { entries: listing.entries, truncated: true } })
+  })
+
+  it('returns a failure as the endpoint reported it', async () => {
+    const error = new RemoteError('workspace-file/not-directory', 'file', { path: 'x', kind: 'file' })
+    const list = vi.fn<WorkspaceFilesListRemote['workspaceFiles']['list']>()
+      .mockResolvedValue({ ok: false, error })
+    const result = await createList({ workspaceFiles: { list } })(SESSION, `${ROOT}/x`, new AbortController().signal)
+    expect(result).toEqual({ ok: false, error })
+  })
+})
+
+describe('childPath', () => {
+  it('joins with one slash whatever the parent ends in', () => {
+    expect(childPath('/work/app', 'src')).toBe('/work/app/src')
+    expect(childPath('/work/app/', 'src')).toBe('/work/app/src')
+    expect(childPath('/', 'etc')).toBe('/etc')
+    expect(childPath('C:\\work\\', 'src')).toBe('C:\\work/src')
+  })
+})
diff --git a/packages/client/ui-sidebar-files/tests/files-body.client.spec.tsx b/packages/client/ui-sidebar-files/tests/files-body.client.spec.tsx
new file mode 100644
index 0000000000..cf889e3859
--- /dev/null
+++ b/packages/client/ui-sidebar-files/tests/files-body.client.spec.tsx
@@ -0,0 +1,177 @@
+// @vitest-environment jsdom
+/**
+ * The body against a scripted listing.
+ *
+ * What is asserted is the reader's contract: the root lists itself on mount,
+ * rows come out directories-first, a directory click asks for exactly that
+ * level, a file click opens exactly that session-scoped `file:` address through
+ * the owner, an `other` entry is shown but not clickable, the tree says when it
+ * was cut or could not be read, and reload asks again for the expanded levels
+ * only. The two pure helpers the rows are built from are checked on their own.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { act, cleanup, fireEvent } from '@testing-library/react'
+import { makeTranslate, RemoteError } from '@deepseek-ai/dsh-client-test-runtime'
+import type { RemoteFailure } from '@deepseek-ai/dsh-api-remotes/client'
+import { fileAddressFor } from '@deepseek-ai/dsh-util-workspace-path'
+import { failureLine, orderEntries } from '../src/client/FilesBody.tsx'
+import type { DirLevel } from '../src/client/store.ts'
+import { zh } from '../src/client/locales.ts'
+import { mountBody, ROOT, SESSION, TAB } from './mount.client.tsx'
+
+const ROOT_LEVEL: DirLevel = {
+  entries: [
+    { name: 'README.md', type: 'file', size: 12 },
+    { name: 'src', type: 'directory' },
+    { name: '.env', type: 'file', size: 2 },
+    { name: 'pipe', type: 'other' },
+  ],
+  truncated: false,
+}
+
+afterEach(() => { cleanup() })
+
+/** Row labels in document order. */
+function names(root: HTMLElement): string[] {
+  return [...root.querySelectorAll('[data-files-entry]')].map(li => li.getAttribute('data-files-path')!)
+}
+
+describe('FilesBody', () => {
+  it('says so when the session has no workspace directory, and asks for nothing', () => {
+    const { view, script } = mountBody(null)
+    expect(view.container.querySelector('[data-files-state="no-workspace"]')?.textContent).toBe(zh.noWorkspace)
+    expect(script.list).not.toHaveBeenCalled()
+  })
+
+  it('lists the root on mount, names it by its basename, and draws directories first with dotfiles kept', async () => {
+    const { view, script } = mountBody()
+    expect(script.list).toHaveBeenCalledWith(SESSION, ROOT, expect.any(AbortSignal))
+    expect(view.container.querySelector('[data-files-row="loading"]')).not.toBeNull()
+    await act(() => script.settle({ ok: true, value: ROOT_LEVEL }))
+    expect(view.container.querySelector('[data-files-state="tree"]')?.getAttribute('data-files-root')).toBe(ROOT)
+    expect(view.container.querySelector('[data-files-state="tree"] > div')?.textContent).toBe('app')
+    expect(names(view.container)).toEqual([`${ROOT}/src`, `${ROOT}/.env`, `${ROOT}/pipe`, `${ROOT}/README.md`])
+  })
+
+  it('labels a separator-only root by the root itself, since it has no final segment', async () => {
+    const { view, script } = mountBody('/')
+    await act(() => script.settle({ ok: true, value: ROOT_LEVEL }))
+    expect(view.container.querySelector('[data-files-state="tree"] > div')?.textContent).toBe('/')
+    expect(names(view.container)).toEqual(['/src', '/.env', '/pipe', '/README.md'])
+  })
+
+  it('a directory click lists that level once and marks it expanded; a second click collapses without asking again', async () => {
+    const { view, script } = mountBody()
+    await act(() => script.settle({ ok: true, value: ROOT_LEVEL }))
+    const dir = view.container.querySelector(`[data-files-path="${ROOT}/src"] > button`)!
+    act(() => { fireEvent.click(dir) })
+    expect(script.list).toHaveBeenLastCalledWith(SESSION, `${ROOT}/src`, expect.any(AbortSignal))
+    expect(dir.getAttribute('aria-expanded')).toBe('true')
+    await act(() => script.settle({ ok: true, value: { entries: [{ name: 'a.ts', type: 'file' }], truncated: false } }))
+    expect(names(view.container)).toContain(`${ROOT}/src/a.ts`)
+    act(() => { fireEvent.click(dir) })
+    expect(dir.getAttribute('aria-expanded')).toBe('false')
+    expect(names(view.container)).not.toContain(`${ROOT}/src/a.ts`)
+    act(() => { fireEvent.click(dir) })
+    expect(names(view.container)).toContain(`${ROOT}/src/a.ts`)
+    expect(script.list).toHaveBeenCalledTimes(2)
+  })
+
+  it('a file click opens its session-scoped file: address through the owner; an other entry offers no button', async () => {
+    const { view, script, tabActions } = mountBody()
+    await act(() => script.settle({ ok: true, value: ROOT_LEVEL }))
+    fireEvent.click(view.container.querySelector(`[data-files-path="${ROOT}/README.md"] > button`)!)
+    // Every row sits under the tree's root, so the address is the path relative to it.
+    expect(tabActions.openResource).toHaveBeenCalledWith(fileAddressFor(SESSION, ROOT, `${ROOT}/README.md`))
+    expect(tabActions.openResource).toHaveBeenCalledWith('dsh-resource://file/session/s-test/README.md')
+    const other = view.container.querySelector(`[data-files-path="${ROOT}/pipe"]`)!
+    expect(other.querySelector('button')).toBeNull()
+    expect(other.querySelector('[aria-disabled="true"]')?.getAttribute('title')).toBe(zh['entry.other'])
+  })
+
+  it('marks a cut listing and an empty one', async () => {
+    const { view, script } = mountBody()
+    await act(() => script.settle({ ok: true, value: { entries: [{ name: 'd', type: 'directory' }], truncated: true } }))
+    expect(view.container.querySelector('[data-files-row="truncated"]')?.textContent).toBe(zh.truncated)
+    act(() => { fireEvent.click(view.container.querySelector(`[data-files-path="${ROOT}/d"] > button`)!) })
+    await act(() => script.settle({ ok: true, value: { entries: [], truncated: false } }))
+    expect(view.container.querySelector('[data-files-row="empty"]')?.textContent).toBe(zh.empty)
+  })
+
+  it('shows a failed level under its directory with the failure code', async () => {
+    const { view, script } = mountBody()
+    await act(() => script.settle({
+      ok: false,
+      error: new RemoteError('workspace-file/not-found', 'gone', { path: ROOT }),
+    }))
+    const failed = view.container.querySelector('[data-files-row="failed"]')
+    expect(failed?.getAttribute('data-files-code')).toBe('workspace-file/not-found')
+    expect(failed?.textContent).toBe(zh['error.notFound'])
+  })
+
+  it('reload resets every level and lists the expanded ones again', async () => {
+    const { view, script, controller, instance } = mountBody()
+    const child = `${ROOT}/src`
+    const collapsed = `${ROOT}/docs`
+    await act(() => script.settle({ ok: true, value: ROOT_LEVEL }))
+    act(() => { fireEvent.click(view.container.querySelector(`[data-files-path="${child}"] > button`)!) })
+    await act(() => script.settle({ ok: true, value: ROOT_LEVEL }))
+    // A level listed earlier and since collapsed is dropped, not re-fetched.
+    act(() => { instance.actions.loaded(TAB, collapsed, ROOT_LEVEL) })
+    script.list.mockClear()
+
+    act(() => { fireEvent.click(view.container.querySelector('[data-files-reload]')!) })
+    expect(script.list.mock.calls.map(call => call[1])).toEqual([ROOT, child])
+    expect(script.list).toHaveBeenCalledWith(SESSION, ROOT, controller.signal)
+    const state = instance.getSnapshot().byTab[TAB]!
+    expect(state.expanded).toEqual([ROOT, child])
+    expect(state.levels).toEqual({ [ROOT]: { kind: 'loading' }, [child]: { kind: 'loading' } })
+    expect(view.container.querySelector('[data-files-reload]')?.getAttribute('aria-label')).toBe(zh.reload)
+  })
+
+  it('an aborted record is forgotten and not seeded again while the body is still mounted', async () => {
+    const { view, script, controller, instance } = mountBody()
+    await act(() => script.settle({ ok: true, value: ROOT_LEVEL }))
+    act(() => { controller.abort() })
+    expect(instance.getSnapshot().byTab[TAB]).toBeUndefined()
+    expect(view.container.querySelector('[data-files-state="tree"]')).toBeNull()
+    expect(script.list).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('orderEntries', () => {
+  it('puts directories first and orders each group by name, numbers included', () => {
+    const ordered = orderEntries([
+      { name: 'file10.txt', type: 'file' },
+      { name: 'zeta', type: 'directory' },
+      { name: 'file2.txt', type: 'file' },
+      { name: '.env', type: 'file' },
+      { name: 'Alpha', type: 'directory' },
+      { name: 'sock', type: 'other' },
+    ])
+    expect(ordered.map(entry => entry.name)).toEqual(['Alpha', 'zeta', '.env', 'file2.txt', 'file10.txt', 'sock'])
+  })
+
+  it('leaves the endpoint\'s array untouched', () => {
+    const entries = [{ name: 'b', type: 'file' as const }, { name: 'a', type: 'file' as const }]
+    orderEntries(entries)
+    expect(entries.map(entry => entry.name)).toEqual(['b', 'a'])
+  })
+})
+
+describe('failureLine', () => {
+  const t = makeTranslate(zh)
+
+  it('names each directory failure', () => {
+    expect(failureLine(t, new RemoteError('workspace-file/not-found', 'x', { path: 'p' }))).toBe(zh['error.notFound'])
+    expect(failureLine(t, new RemoteError('workspace-file/outside-workspace', 'x', { path: 'p' })))
+      .toBe(zh['error.outsideWorkspace'])
+    expect(failureLine(t, new RemoteError('workspace-file/not-directory', 'x', { path: 'p', kind: 'file' })))
+      .toBe(zh['error.notDirectory'])
+  })
+
+  it('carries an unclassified failure\'s own message', () => {
+    const failure = { code: 'remote/transport', message: 'socket closed' } as unknown as RemoteFailure
+    expect(failureLine(t, failure)).toBe('读取失败：socket closed')
+  })
+})
diff --git a/packages/client/ui-sidebar-files/tests/mount.client.tsx b/packages/client/ui-sidebar-files/tests/mount.client.tsx
new file mode 100644
index 0000000000..389c383a9e
--- /dev/null
+++ b/packages/client/ui-sidebar-files/tests/mount.client.tsx
@@ -0,0 +1,100 @@
+/**
+ * Mount the body over a real store instance and a scripted listing.
+ *
+ * The component reads a handful of its props; the rest of the standard kit is
+ * framework-injected and never touched here, so one documented cast keeps the
+ * harness to what is actually exercised.
+ */
+import { useSyncExternalStore } from 'react'
+import { render } from '@testing-library/react'
+import type { RenderResult } from '@testing-library/react'
+import { vi } from 'vitest'
+import type { Mock } from 'vitest'
+import type { SessionListState } from '@deepseek-ai/dsh-api-session-controller/client'
+import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { SidebarRightTabActions } from '@deepseek-ai/dsh-client-ui-sidebar-right/client'
+import { filesFace } from '../src/client/face.ts'
+import type { FilesInjected } from '../src/client/face.ts'
+import { FilesBody } from '../src/client/FilesBody.tsx'
+import type { FilesBodyProps } from '../src/client/FilesBody.tsx'
+import { zh } from '../src/client/locales.ts'
+import { createFilesStore } from '../src/client/store.ts'
+import { scriptedList } from './scripted-list.client.ts'
+import type { ScriptedList } from './scripted-list.client.ts'
+import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+
+export const SESSION = 's-test' as SessionId
+export const ROOT = '/work/app'
+export const TAB = 'tab-1' as TabId
+
+/** Test-local selector hook over a framework-neutral store instance. */
+function hookOf<T>(inst: { subscribe: (fn: () => void) => () => void; getSnapshot: () => T }) {
+  return function useSelector<S>(sel: (s: T) => S): S {
+    return sel(useSyncExternalStore(inst.subscribe, inst.getSnapshot))
+  }
+}
+
+/** A live instance of the tree's store, as the framework would mint one per session. */
+type FilesStoreInstance = ReturnType<ReturnType<typeof createFilesStore>['create']>
+
+/** The owner's tab actions as recording mocks. */
+interface MockedTabActions {
+  readonly openResource: Mock<SidebarRightTabActions['openResource']>
+  readonly openTab: Mock<SidebarRightTabActions['openTab']>
+  readonly close: Mock<SidebarRightTabActions['close']>
+}
+
+/** What a spec holds after mounting: the rendered view and every hand on the tree. */
+export interface Mounted {
+  readonly view: RenderResult
+  readonly instance: FilesStoreInstance
+  readonly script: ScriptedList
+  readonly face: FilesInjected
+  readonly controller: AbortController
+  readonly tabActions: MockedTabActions
+}
+
+/** One store instance, one face, one owner share. */
+function harness(cwd: string | null) {
+  const instance = createFilesStore().create()
+  const script = scriptedList()
+  const face = filesFace(script.list)(SESSION, instance.actions)
+  const controller = new AbortController()
+  const tabActions: MockedTabActions = {
+    openResource: vi.fn<SidebarRightTabActions['openResource']>(),
+    openTab: vi.fn<SidebarRightTabActions['openTab']>(),
+    close: vi.fn<SidebarRightTabActions['close']>(),
+  }
+  const sessions = { byId: cwd === null ? {} : { [SESSION]: { cwd } } } as unknown as SessionListState
+  const shared = {
+    // A page tab's address is the shell's to mint; the body never reads it.
+    useTabInfo: () => ({
+      sidebar: { expanded: true, fullscreen: false },
+      panel: { id: 'pane-1' },
+      tab: {
+        id: TAB, kind: 'files', contentId: 'files', title: zh['type.label'], visible: true,
+        navigation: { address: 'files', params: undefined, revision: 1 },
+        signal: controller.signal,
+        actions: tabActions,
+      },
+    }),
+    sessionId: SESSION,
+    useSessions: <S,>(sel: (s: SessionListState) => S) => sel(sessions),
+    useStore: hookOf(instance),
+    actions: instance.actions,
+    ...face,
+    t: makeTranslate(zh),
+  }
+  return { instance, script, face, controller, tabActions, shared }
+}
+
+/**
+ * Mount the body.
+ * @param cwd - the session's working directory as `useSessions` reports it; `null` for a session without one.
+ */
+export function mountBody(cwd: string | null = ROOT): Mounted {
+  const { shared, ...hands } = harness(cwd)
+  const view = render(<FilesBody {...shared as unknown as FilesBodyProps} />)
+  return { ...hands, view }
+}
diff --git a/packages/client/ui-sidebar-files/tests/scripted-list.client.ts b/packages/client/ui-sidebar-files/tests/scripted-list.client.ts
new file mode 100644
index 0000000000..7825afc719
--- /dev/null
+++ b/packages/client/ui-sidebar-files/tests/scripted-list.client.ts
@@ -0,0 +1,51 @@
+/** A directory listing the spec settles by hand, one deferred result per call. */
+import { vi } from 'vitest'
+import type { Mock } from 'vitest'
+import type { RemoteResult } from '@deepseek-ai/dsh-api-remotes/client'
+import type { ListWorkspaceDirectory } from '../src/client/face.ts'
+import type { DirLevel } from '../src/client/store.ts'
+
+/** The scripted listing: the mock the face receives, and the hand that settles it. */
+export interface ScriptedList {
+  readonly list: Mock<ListWorkspaceDirectory>
+  /**
+   * Settle the oldest outstanding call and let its store write land.
+   * @param result - what the endpoint answers.
+   */
+  readonly settle: (result: RemoteResult<DirLevel>) => Promise<void>
+  /**
+   * Settle the newest outstanding call first, so an older one can arrive after it.
+   * @param result - what the endpoint answers.
+   */
+  readonly settleLatest: (result: RemoteResult<DirLevel>) => Promise<void>
+  /** Paths of calls not yet settled, oldest first. */
+  readonly outstanding: () => readonly string[]
+}
+
+/**
+ * Build a listing whose every call stays pending until the spec settles it.
+ * @returns the scripted listing.
+ */
+/** One listing awaiting the spec's answer. */
+interface PendingList {
+  readonly path: string
+  resolve(result: RemoteResult<DirLevel>): void
+}
+
+export function scriptedList(): ScriptedList {
+  const pending: PendingList[] = []
+  const list = vi.fn<ListWorkspaceDirectory>((_sessionId, path) =>
+    new Promise((resolve) => { pending.push({ path, resolve }) }))
+  const land = async (call: PendingList | undefined, result: RemoteResult<DirLevel>): Promise<void> => {
+    if (call === undefined) throw new Error('no outstanding listing to settle')
+    call.resolve(result)
+    await Promise.resolve()
+    await Promise.resolve()
+  }
+  return {
+    list,
+    settle: result => land(pending.shift(), result),
+    settleLatest: result => land(pending.pop(), result),
+    outstanding: () => pending.map(call => call.path),
+  }
+}
diff --git a/packages/client/ui-sidebar-files/tests/store.client.spec.ts b/packages/client/ui-sidebar-files/tests/store.client.spec.ts
new file mode 100644
index 0000000000..ea364c564e
--- /dev/null
+++ b/packages/client/ui-sidebar-files/tests/store.client.spec.ts
@@ -0,0 +1,95 @@
+/**
+ * The tree's write set, one tab at a time.
+ *
+ * Two facts here are load-bearing for the body: a collapsed level keeps what it
+ * loaded (reopening draws at once), and `reset` clears levels while keeping the
+ * expanded set, which is what lets the reload gesture know which levels to ask
+ * for again.
+ */
+import { describe, expect, it } from 'vitest'
+import { RemoteError } from '@deepseek-ai/dsh-client-test-runtime'
+import { createFilesStore } from '../src/client/store.ts'
+import type { DirLevel } from '../src/client/store.ts'
+import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+
+const ROOT = '/work/app'
+const TAB = 'tab-1' as TabId
+
+const LEVEL: DirLevel = {
+  entries: [{ name: 'src', type: 'directory' }, { name: 'README.md', type: 'file', size: 12 }],
+  truncated: false,
+}
+
+describe('createFilesStore', () => {
+  it('mints an independent instance per call', () => {
+    const first = createFilesStore().create()
+    const second = createFilesStore().create()
+    first.actions.start(TAB, ROOT)
+    expect(second.getSnapshot().byTab[TAB]).toBeUndefined()
+  })
+
+  it('seeds a tab at its root with the root expanded and nothing loaded', () => {
+    const store = createFilesStore().create()
+    const { actions } = store
+    const getSnapshot = (): ReturnType<typeof store.getSnapshot> => store.getSnapshot()
+    actions.start(TAB, ROOT)
+    expect(getSnapshot().byTab[TAB]).toEqual({ root: ROOT, levels: {}, expanded: [ROOT] })
+  })
+
+  it('walks one level through loading, ready, and failed', () => {
+    const store = createFilesStore().create()
+    const { actions } = store
+    const getSnapshot = (): ReturnType<typeof store.getSnapshot> => store.getSnapshot()
+    actions.start(TAB, ROOT)
+    actions.loading(TAB, ROOT)
+    expect(getSnapshot().byTab[TAB]!.levels[ROOT]).toEqual({ kind: 'loading' })
+    actions.loaded(TAB, ROOT, LEVEL)
+    expect(getSnapshot().byTab[TAB]!.levels[ROOT]).toEqual({ kind: 'ready', level: LEVEL })
+    const failure = new RemoteError('workspace-file/not-found', 'gone', { path: ROOT })
+    actions.failed(TAB, ROOT, failure)
+    expect(getSnapshot().byTab[TAB]!.levels[ROOT]).toEqual({ kind: 'failed', failure })
+  })
+
+  it('toggles a directory in and out of the expanded set without touching its level', () => {
+    const store = createFilesStore().create()
+    const { actions } = store
+    const getSnapshot = (): ReturnType<typeof store.getSnapshot> => store.getSnapshot()
+    const child = `${ROOT}/src`
+    actions.start(TAB, ROOT)
+    actions.loaded(TAB, child, LEVEL)
+    actions.toggled(TAB, child)
+    expect(getSnapshot().byTab[TAB]!.expanded).toEqual([ROOT, child])
+    actions.toggled(TAB, child)
+    expect(getSnapshot().byTab[TAB]!.expanded).toEqual([ROOT])
+    // Collapsing keeps the listing, so reopening draws without another fetch.
+    expect(getSnapshot().byTab[TAB]!.levels[child]).toEqual({ kind: 'ready', level: LEVEL })
+  })
+
+  it('reset drops every level and keeps the expanded set', () => {
+    const store = createFilesStore().create()
+    const { actions } = store
+    const getSnapshot = (): ReturnType<typeof store.getSnapshot> => store.getSnapshot()
+    const child = `${ROOT}/src`
+    actions.start(TAB, ROOT)
+    actions.loaded(TAB, ROOT, LEVEL)
+    actions.toggled(TAB, child)
+    actions.loaded(TAB, child, LEVEL)
+    actions.reset(TAB)
+    expect(getSnapshot().byTab[TAB]).toEqual({ root: ROOT, levels: {}, expanded: [ROOT, child] })
+  })
+
+  it('refuses to write a level for a tab that was never started', () => {
+    const { actions } = createFilesStore().create()
+    expect(() => { actions.loading('tab-nowhere' as TabId, ROOT) }).toThrow('no tree for tab "tab-nowhere"')
+  })
+
+  it('forget removes exactly the tab that went away', () => {
+    const store = createFilesStore().create()
+    const { actions } = store
+    const getSnapshot = (): ReturnType<typeof store.getSnapshot> => store.getSnapshot()
+    actions.start(TAB, ROOT)
+    actions.start('tab-2' as TabId, ROOT)
+    actions.forget(TAB)
+    expect(Object.keys(getSnapshot().byTab)).toEqual(['tab-2'])
+  })
+})
diff --git a/packages/client/ui-sidebar-files/tsconfig.json b/packages/client/ui-sidebar-files/tsconfig.json
new file mode 100644
index 0000000000..97ba9441ec
--- /dev/null
+++ b/packages/client/ui-sidebar-files/tsconfig.json
@@ -0,0 +1,48 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../api/remotes/tsconfig.client.json"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../locale"
+    },
+    {
+      "path": "../store"
+    },
+    {
+      "path": "../ui-dockkit"
+    },
+    {
+      "path": "../ui-primitives"
+    },
+    {
+      "path": "../ui-session"
+    },
+    {
+      "path": "../ui-sidebar-right"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../../util/workspace-path"
+    },
+    {
+      "path": "../../api/workspace-files/tsconfig.client.json"
+    }
+  ]
+}
diff --git a/packages/client/ui-sidebar-files/tsdown.config.ts b/packages/client/ui-sidebar-files/tsdown.config.ts
new file mode 100644
index 0000000000..15e759c557
--- /dev/null
+++ b/packages/client/ui-sidebar-files/tsdown.config.ts
@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-ui-sidebar-files', ['lib/types/index.js'])
diff --git a/packages/client/ui-sidebar-right/README.i18n.yaml b/packages/client/ui-sidebar-right/README.i18n.yaml
new file mode 100644
index 0000000000..8d11c28b28
--- /dev/null
+++ b/packages/client/ui-sidebar-right/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/client/ui-sidebar-right/README.md
+README.md: feb75c6184098f54961ca161b4dc5ca5d0c7fc78
+README.zh.md: 03c841dfdaac970e938cf934e7f09d151268be8b
diff --git a/packages/client/ui-sidebar-right/README.md b/packages/client/ui-sidebar-right/README.md
new file mode 100644
index 0000000000..feb75c6184
--- /dev/null
+++ b/packages/client/ui-sidebar-right/README.md
@@ -0,0 +1,133 @@
+---
+description: "The right Sidebar of the dsh web client: one docking surface per session, two presentations, the navigation controller ctx.sidebarRight, the tab-type registry ctx.sidebarRightTabs, and the Tab domain."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-client-ui-sidebar-right
+
+English | [中文](README.zh.md)
+
+## Summary
+
+The right Sidebar: where the docking kit meets this product. It holds one docking surface per session, draws it as one edge-anchored panel in the frame's right column in either of two presentations, puts the expand button in the conversation header, and owns the navigation controller (`ctx.sidebarRight`), the tab-type registry (`ctx.sidebarRightTabs`), and the Tab domain that tells each open tab how it was navigated to and how long it lives.
+
+## Table of Contents
+
+- [What lives here, and what does not](#what-lives-here-and-what-does-not)
+- [Presentations](#presentations)
+- [The expand button](#the-expand-button)
+- [State](#state)
+- [Extension seats](#extension-seats)
+- [`ctx.sidebarRight`](#ctxsidebarright)
+- [The Tab domain](#the-tab-domain)
+- [The guide](#the-guide)
+- [Copy](#copy)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="what-lives-here-and-what-does-not"></a>
+## What lives here, and what does not
+
+The layout itself — the split tree, its operations, the drag gestures, the floating panels — belongs to `@deepseek-ai/dsh-client-ui-dockkit` and stays host-agnostic. This package supplies everything that kit refuses to know: the product's copy, what a tab's `kind` means, which tab a fresh pane is seeded with, where the surface is mounted, and how other plugins reach it.
+
+<a id="presentations"></a>
+## Presentations
+
+Normal and fullscreen presentations share the same content tree, so switching does not remount tabs. The normal panel anchors to the right column; fullscreen covers the viewport while retaining the wide-screen columns underneath. Opening below 768px uses fullscreen automatically; leaving fullscreen on a narrow viewport closes the panel, and widening does not reopen a closed panel. A fullscreen opening keeps the underlying columns unchanged until its slide finishes, then prepares the normal track without a column transition. Before a fullscreen panel retreats, closing prepares a full-width conversation and restoring prepares the normal right track; the background does not animate during the retreat.
+
+| Mode | The track | The panel |
+|---|---|---|
+| `push` (default) | Panel width: the conversation makes room | In the track; its left edge and the conversation's right edge travel together, on the frame's own curve |
+| `fullscreen` | Retains the wide-screen normal track; automatic narrow-screen fullscreen takes no track | Covers the entire viewport |
+
+The seat reports presentation through `ctx.layout.openRightbar(track, fullscreen)` / `closeRightbar()`; the frame does not inject this package. Switching fullscreen on a wide viewport leaves the center width unchanged, and the width handle appears only in expanded normal mode. Independent floating panels and `float`/`dock` operations remain available.
+
+The panel has no header row. Its two controls — the presentation switch and the collapse button — ride the kit's chrome seat at the far end of the top-right pane's tab strip, so the strip is the panel's whole top edge. Each strip reads, left to right: the tabs as capsules with their own close, the add control (drawn only while that pane holds no guide tab; it opens the guide there through `ctx.sidebarRight.openTab`), the pane's split control, and in the top-right pane the two panel controls. Only the chips give way in a narrow pane; the controls after them never shrink or clip.
+
+<a id="the-expand-button"></a>
+## The expand button
+
+While the panel is hidden, one button in the conversation header's corner seat (`conversation.session.header.corner`, past the utilities' right edge and level with the Session log control) is the way back in. Its glyph is the left sidebar's collapse icon mirrored. It shares the panel's store (the slot runtime allows one handle across two same-scope seats); while the panel is shown it renders a same-size placeholder, so the corner keeps its width and nothing in the header row moves. A collapsed Sidebar therefore costs the conversation nothing: no rail, no width, and the transcript's scrollbar stays at the column's edge. Without a session there is no button and no panel.
+
+The panel takes the conversation's ground colour and content font sizes rather than a raised layer of its own: it is a column of the page, not a card over it.
+
+<a id="state"></a>
+## State
+
+One `SurfaceState` per session id — the layout, its recorded sequence, and how many ids it has minted — held in a store declared at the registration. Every action follows the same shape: mint the ids the intent needs, ask a kit planner which operations carry it out, record them, then assign the session's whole surface back. No action edits a layout in place, which is what keeps the kit's pure functions the only thing that computes one.
+
+Carrying the mint counter in the surface is what makes a recorded sequence replayable: operations embed the ids they create, so replaying from the same initial state reproduces the same tree. Every action records one history entry, however many operations it needed. Expanding, collapsing, and switching presentation are recorded too.
+
+After every action the kit's settle planner keeps the surface populated: a docked pane whose last tab was closed, moved out, or floated is merged away, and when only the root pane is left and it is empty, the guide tab is reseeded. There is always at least one tab, and never an empty pane — so there is no separate "close pane" gesture.
+
+State is memory-only. A reload returns every session to the collapsed default; switching sessions keeps each surface where it was.
+
+<a id="extension-seats"></a>
+## Extension seats
+
+A tab type registers in two stages, and the shipped guide type goes through exactly the same public path a type from another package does (`ui-sidebar-textpreview` is the live proof). Both stages sit inside the type's own `ctx.effect`, so the registration lives exactly as long as the plugin that made it.
+
+1. **The type** — `ctx.sidebarRightTabs.register({ id, kind, patterns?, priority?, canOpen?, title, guide? })`, a static declaration with no runtime hook, returning a disposer. `id` is this implementation's identity in the tab system, unique across every registration (a package name is the natural value; the shipped guide is `@deepseek-ai/dsh-client-ui-sidebar-right/guide`): a kind is not unique once an extension may take a builtin's over, so the implementation names itself, and a second registration of an `id` throws. A resource type names `patterns`, globs over `dsh-resource://` addresses: one containing `:` matches the whole address (`dsh-resource://file/**`); one without matches the URI's path at any depth, ignoring case (`*.md`), and an address that is not a URI matches no such pattern. A page type — the guide, a file tree — names none and is opened by kind. `canOpen(address)` vetoes a match. `title(address)` is the tab chip's text, captured when the tab opens. `guide` lists entry boxes for the guide page; picking one opens the contributing type as a page. A `kind` carries at most one `builtin` and one `extension` registration (the extension is in force; the builtin resumes when it leaves); any other collision on a kind throws. The `id` is also the key the type's body and title register under, so an extension and the builtin it takes over hold distinct cells and the seat renders the one in force.
+2. **The body** — `ctx.slots.register({ name: 'sidebar.right.pane.tab', key: definition.id }, Body)` reads `{ sidebar, panel, tab }` through the framework-injected `useTabInfo()`. `sidebar` supplies expansion and fullscreen information; `panel.id` identifies its pane; `tab` contains the record fields, `visible`, `navigation`, `signal`, and `actions`. These are not parallel owner props; the type's own store still uses `useStore`/`actions`. Optional title registrations and guide replacements share this hook; an absent title registration uses the text captured at open time.
+
+Which type opens a resource follows the editor-resolver convention: the types whose `patterns` match are ranked by `priority` band — `extension` (a type from outside the product, the highest, and the default when none is named), `builtin`, `fallback` (plain viewers anything more specific should beat) — then by the length of the matched pattern, then by registration order; `canOpen` removes a candidate. The bands are string literals so a type in another package needs no runtime import from here. `candidates(address)` returns the ranking, `claim(address, kind?)` the decision; naming a `kind` skips its globs but keeps its `canOpen`.
+
+Two more seats extend what is already there: `sidebar.right.tab.guide` (chain) replaces the guide tab's body without replacing the tab, and `sidebar.right.tab.menu.item` (list) appends content-level actions to a tab's menu after the kit's own layout actions. No seat exists for pane-level actions or for collapsed-state controls yet, because nothing needs one.
+
+<a id="ctxsidebarright"></a>
+## `ctx.sidebarRight`
+
+`openResource(address, options?)` and `openTab(kind, options?)` are the navigation controller, and every way into the column calls one of them: the conversation's file links and a tool row's line reference (`openResource(fileAddress, { params: { line } })`), the strip's add control and a guide entry box (`openTab`), a file tree's rows (`tab.actions.openResource`). A resource address is a `dsh-resource://<type>/…` URI; without `options.kind` the registry claims it (globs and `canOpen`, best band wins), with it that kind's type in force opens it. A page is named by kind; the tab is recorded under an address this package composes and nobody else spells (`contract/seed.ts`). Both run the same steps as one history entry: a tab already showing the same (kind, contentId) is focused unless `revealIfOpened: false`; otherwise a new tab lands in `options.replaceTab`'s pane and slot (closing that tab), else `options.paneId`, else the active docked pane; the panel expands, because content the user cannot see is not opened. Then the Tab domain records the navigation — `params` reach the body as `navigation.params`, with `revision` stepped — outside the layout history. `params` is typed by what is opened: a viewer for a resource type merges its entry into `SidebarRightResourceParamsMap` (the text preview declares `{ line?: number }`); a page type that takes parameters merges into `SidebarRightTabParamsMap` under its kind; values are JSON-shaped by convention, unchecked at run time. An address outside `dsh-resource://`, one no type claims, or a kind nothing registered throws: that is a wiring mistake, not a user error.
+
+`close(tabId)` closes a tab; `active()` reads the active tab. `isExpanded()` and `toggleExpanded()` read and drive the column's expansion; the presentation switch is the panel's own control and not part of this face. Layout operations, for callers that arrange the column programmatically, each recorded like the gesture it stands in for: `focus(tabId)` focuses a tab and its pane; `split(paneId?)` splits a docked pane (the active one by default) under the same pane budget and room rule as the strip's control and returns the new pane's id, or `undefined` — recording nothing — when it cannot; `float(tabId, rect?)` takes a docked tab out into a panel; `dock(paneId)` returns a floating panel to the active docked pane. A tab or pane that does not exist, or already is where the call would put it, is left alone. The face exposes operations only: no layout snapshot, no operation log, no lookup by address. `_undo()` / `_redo()` step the mounted surface's history; they are `@internal` — the sequence has no user-facing control, and these exist for tests. Commands need a mounted session surface; with none, they throw rather than write into a surface nobody draws.
+
+<a id="the-tab-domain"></a>
+## The Tab domain
+
+The Tab domain retains navigation, an abort signal, and bound actions per (Session, tab id). A private assembly callback adopts each Session's store and reconciles records on its commits. Only record removal or plugin unload aborts the signal; closing the sidebar and switching Sessions retain records, while undo restores a new occurrence. `useTabInfo()` composes framework-bound store and navigation hooks without manual component subscriptions or render-time record creation. `tab.actions` always target their own Session; `tab.visible` distinguishes bodies from titles, and floating tabs remain visible when the sidebar closes. `adopt` is absent from the public controller.
+
+<a id="the-guide"></a>
+## The guide
+
+The guide tab is a centred title, one line under it, and one entry box per `guide` entry the registered types contributed, in `order`. Picking a box calls `tab.actions.openTab(entry.kind, { replaceTab: true })`, so the guide gives way to the page it opened. A pane holds at most one guide tab. The strip's add control is drawn only while its pane holds none and opens one there with `openTab('guide', { paneId, revealIfOpened: false })`, so a guide in another pane does not capture the click; opening the guide into a pane that already has one focuses it instead; a guide dragged, dropped, or docked into such a pane merges into it — the arriving guide closes and the pane's own is focused; `duplicateTab` on the guide records nothing. A split or an emptied root pane seeds a guide through the kit's factory, one per new pane. A plain `openTab('guide')` keeps the tree-wide reveal every open has. The product allows two horizontal panes, initially equal, with divider ratios limited to 20%–80%. Insufficient width blocks a new split; with two panes already present, a body drop moves the tab between panes instead of creating a third. At the two-pane limit, split controls are hidden; closing back to one pane restores them.
+
+<a id="copy"></a>
+## Copy
+
+Every string in the column comes from the `sidebarRight` locale namespace, including the kit's accessible names. A tab's title is fixed when the tab is minted; a type's display name follows the current language.
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as the package is a browser-side UI plugin layer that registers nothing model-facing.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Memory-only.** Nothing is persisted; a reload starts every session collapsed.
+- **No surface without a session.** State is keyed by session id, so the hero screen shows nothing on the right.
+- **Hard-coded stacking.** The panel and the float host use fixed z-index values because the client has no z-index token layer yet.
+- **Undo is not exposed.** The recorded sequence is stepped only through the `@internal` service methods; product controls are deliberately absent.
+- **Guide copy is a draft** awaiting product review; the words live in `locales.ts`.
+- **Titles are fixed at open time.** A type's `title(address)` is captured into the record; a live title comes only from the optional title seat.
+- **No content navigation stack.** Stepping back replays layout operations; an editor-style back/forward over visited content is not built.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>
+
+**Runtime invariant:** No companion is published. The two services (`sidebarRight`, `sidebarRightTabs`) are provided through `ctx.reflect.provide` inside one effect and torn down with it; the seat's binding and the Tab domain's occurrence lifetimes are asserted directly by this package's specs, and no independent observation exists to diverge from them.
diff --git a/packages/client/ui-sidebar-right/README.zh.md b/packages/client/ui-sidebar-right/README.zh.md
new file mode 100644
index 0000000000..03c841dfda
--- /dev/null
+++ b/packages/client/ui-sidebar-right/README.zh.md
@@ -0,0 +1,133 @@
+---
+description: "dsh Web 客户端的右侧 Sidebar：每会话一个停靠面、两种呈现形态、导航控制器 ctx.sidebarRight、tab 类型注册表 ctx.sidebarRightTabs 与 Tab 域。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-client-ui-sidebar-right
+
+[English](README.md) | 中文
+
+## 概述
+
+右侧 Sidebar：停靠套件与本产品相遇的地方。它为每个会话持有一个停靠面，以两种呈现形态之一把它画成贴靠框架右列边缘的一块面板，把展开按钮放进会话 header，并拥有导航控制器（`ctx.sidebarRight`）、tab 类型注册表（`ctx.sidebarRightTabs`），以及告诉每个已开 tab 它是如何被导航到、能活多久的 Tab 域。
+
+## 目录
+
+- [什么住在这里，什么不住](#what-lives-here-and-what-does-not)
+- [呈现形态](#presentations)
+- [展开按钮](#the-expand-button)
+- [状态](#state)
+- [扩展席位](#extension-seats)
+- [`ctx.sidebarRight`](#ctxsidebarright)
+- [Tab 域](#the-tab-domain)
+- [引导页](#the-guide)
+- [文案](#copy)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="what-lives-here-and-what-does-not"></a>
+## 什么住在这里，什么不住
+
+布局本身——分裂树、它的操作、拖拽手势、浮窗——属于 `@deepseek-ai/dsh-client-ui-dockkit`，并保持与宿主无关。本包提供套件拒绝知道的一切：产品文案、tab 的 `kind` 是什么意思、新格用哪个 tab 播种、停靠面挂在哪里、其它插件如何触达它。
+
+<a id="presentations"></a>
+## 呈现形态
+
+普通与全屏共用同一棵面板内容树，切换不会重挂载Tab。普通面板贴靠右栏；全屏面板覆盖窗口并保留宽屏底层列宽。窗口低于768px时打开右栏自动全屏；窄屏退出全屏会收起右栏，变宽不重新打开已关闭的右栏。 全屏打开时，底层列宽保持不变，直到滑入结束后才无过渡地准备普通轨道。 全屏面板退场前，关闭先准备全宽会话区，恢复先准备普通右轨道；退场期间底层不播放宽度动画。
+
+| 形态 | 轨道 | 面板 |
+|---|---|---|
+| `push`（默认） | 面板宽度：会话区让出空间 | 在轨道内；它的左缘与会话区的右缘沿框架自己的曲线一起移动 |
+| `fullscreen` | 保留宽屏普通轨道；窄屏自动全屏不占轨道 | 覆盖整个窗口 |
+
+席位通过 `ctx.layout.openRightbar(track, fullscreen)` / `closeRightbar()` 报告呈现，框架不注入本包。宽屏切换全屏不改变中栏宽度；宽度拖拽区只在普通展开态显示。独立浮窗及 `float`/`dock` 操作保持可用。
+
+面板没有标题行。它的两个控件——形态切换与折叠按钮——搭在套件 chrome 席位上，位于右上格 tab 条的最末端，因此 tab 条就是面板的整条上边。每条 tab 条从左到右读作：作为胶囊、各带关闭按钮的 tab，添加控件（只在该格没有引导 tab 时绘制；它通过 `ctx.sidebarRight.openTab` 在该格打开引导页），该格的分栏控件，以及右上格里的两个面板控件。窄格里只有 chip 让位；其后的控件从不收缩或被裁切。
+
+<a id="the-expand-button"></a>
+## 展开按钮
+
+面板隐藏时，会话 header 角落席位里的一个按钮（`conversation.session.header.corner`，在工具组右缘之外，与 Session 日志控件齐平）是回去的路。它的图形是左侧 sidebar 折叠图标的镜像。它与面板共用一个存储（slot 运行时允许两个同作用域席位共用一个 handle）；面板显示时它渲染一个同尺寸的占位，因此角落保持宽度，header 行里没有东西会移动。于是折叠的 Sidebar 不花会话区任何代价：没有轨条、没有宽度，转录的滚动条留在列的边缘。没有会话就没有按钮也没有面板。
+
+面板取会话区的底色与正文字号，而不是自成一层浮起的表面：它是页面的一列，不是压在页面上的卡片。
+
+<a id="state"></a>
+## 状态
+
+每个会话 id 一个 `SurfaceState`——布局、它记录的序列、以及它已铸造的 id 数——保存在注册时声明的存储里。每个动作都遵循同一形态：铸造意图需要的 id，向套件 planner 询问由哪些操作承载，记录它们，然后把该会话的整个停靠面赋回去。没有任何动作就地编辑布局，这正是让套件的纯函数成为唯一计算布局之处的原因。
+
+把铸造计数器带在停靠面里，是记录的序列可回放的原因：操作内嵌它们创建的 id，因此从同一初始状态回放能复现同一棵树。每个动作记录一条历史，无论它需要多少操作。展开、折叠与切换形态也都被记录。
+
+每个动作之后，套件的 settle planner 保证停靠面有内容：最后一个 tab 被关闭、搬走或浮出的停靠格会被并掉；只剩根格且它为空时，重新播种引导 tab。永远至少有一个 tab，永远没有空格——因此没有单独的「关闭格」手势。
+
+状态只在内存中。刷新会让每个会话回到折叠的默认态；切换会话则让每个停靠面留在原处。
+
+<a id="extension-seats"></a>
+## 扩展席位
+
+tab 类型分两阶段注册，随包发布的引导类型走的正是别的包的类型走的同一条公开路径（`ui-sidebar-textpreview` 是活的证明）。两个阶段都在类型自己的 `ctx.effect` 里，因此注册与创建它的插件同生共死。
+
+1. **类型**——`ctx.sidebarRightTabs.register({ id, kind, patterns?, priority?, canOpen?, title, guide? })`，一份没有运行时钩子的静态声明，返回 disposer。`id` 是这个实现在 tab 系统里的身份，在全部注册中唯一（包名是天然取值；随包引导页是 `@deepseek-ai/dsh-client-ui-sidebar-right/guide`）：一旦 extension 可以接管 builtin 的 kind，kind 就不再唯一，所以实现要自己命名，同一 `id` 的第二次注册会 throw。资源类型给出 `patterns`，即作用于 `dsh-resource://` 地址的 glob：含 `:` 的匹配整个地址（`dsh-resource://file/**`）；不含的匹配 URI 路径的任意深度且忽略大小写（`*.md`），不是 URI 的地址不匹配任何这类模式。页类型——引导页、文件树——不给出模式，按 kind 打开。`canOpen(address)` 否决一次命中。`title(address)` 是 tab chip 的文字，在 tab 打开时捕获。`guide` 列出引导页的入口框；选中一个即把贡献它的类型作为页打开。一个 `kind` 最多承载一份 `builtin` 与一份 `extension` 注册（extension 生效；它离开后 builtin 恢复）；kind 上的其它任何撞名都 throw。`id` 同时也是该类型正文与标题注册时用的 key，因此 extension 与它接管的 builtin 各占一个格位，席位渲染生效的那个。
+2. **正文**——`ctx.slots.register({ name: 'sidebar.right.pane.tab', key: definition.id }, Body)` 通过框架注入的 `useTabInfo()` 读取 `{ sidebar, panel, tab }`。`sidebar` 提供开合与全屏信息，`panel.id` 命名所在格，`tab` 包含原记录字段、`visible`、`navigation`、`signal` 和 `actions`。这些字段不再作为平铺owner props传入；类型自己的store仍使用 `useStore`/`actions`。可选标题注册及引导替换共享该hook；未注册标题时使用打开时保存的文本。
+
+由哪个类型打开资源遵循编辑器解析器的惯例：`patterns` 命中的类型先按 `priority` 档排序——`extension`（产品外的类型，最高档，也是未命名时的默认）、`builtin`、`fallback`（任何更具体的类型都应胜过的通用查看器）——再按命中模式的长度，再按注册顺序；`canOpen` 会剔除候选。各档是字符串字面量，因此别的包里的类型不需要从这里做运行时导入。`candidates(address)` 返回排序，`claim(address, kind?)` 返回决定；指定 `kind` 时跳过它的 glob 但保留它的 `canOpen`。
+
+另有两个席位扩展已有之物：`sidebar.right.tab.guide`（chain）替换引导 tab 的正文而不替换 tab，`sidebar.right.tab.menu.item`（list）在套件自己的布局动作之后向 tab 菜单追加内容级动作。目前没有面向格级动作或折叠态控件的席位，因为还没有东西需要它。
+
+<a id="ctxsidebarright"></a>
+## `ctx.sidebarRight`
+
+`openResource(address, options?)` 与 `openTab(kind, options?)` 是导航控制器，进入该列的每条路都调用其中之一：会话区的文件链接与工具行的行号引用（`openResource(fileAddress, { params: { line } })`），tab 条的添加控件与引导入口框（`openTab`），文件树的行（`tab.actions.openResource`）。资源地址是 `dsh-resource://<type>/…` URI；不带 `options.kind` 时由注册表认领（glob 与 `canOpen`，最高档胜出），带它时由该 kind 生效的类型打开。页按 kind 命名；tab 记录在本包拼出、别处无人书写的地址下（`contract/seed.ts`）。两者以同一组步骤作为一条历史运行：已展示同一 (kind, contentId) 的 tab 被聚焦，除非 `revealIfOpened: false`；否则新 tab 落到 `options.replaceTab` 所在的格与位置（并关掉那个 tab），再退而落到 `options.paneId`，再退而落到活跃停靠格；面板展开，因为用户看不到的内容不算打开。随后 Tab 域记录这次导航——`params` 以 `navigation.params` 抵达正文，`revision` 递增——不进布局历史。`params` 按所开之物定型：某资源类型的查看器把自己那项并入 `SidebarRightResourceParamsMap`（文本预览声明 `{ line?: number }`）；接受参数的页类型按其 kind 并入 `SidebarRightTabParamsMap`；值约定为 JSON 形状，运行时不校验。`dsh-resource://` 之外的地址、无人认领的地址、或未注册的 kind 都会 throw：那是接线错误，不是用户错误。
+
+`close(tabId)` 关闭一个 tab；`active()` 读取活动 tab。`isExpanded()` 与 `toggleExpanded()` 读取并驱动该列的展开；形态切换是面板自己的控件，不属于这个接口。布局操作供以编程方式安排该列的调用方使用，每个都像它替代的手势一样被记录：`focus(tabId)` 聚焦一个 tab 及其格；`split(paneId?)` 在与 tab 条控件相同的格预算与空间规则下分栏一个停靠格（默认活跃格），返回新格的 id，做不到时返回 `undefined`——且不记录任何东西；`float(tabId, rect?)` 把停靠 tab 浮出为浮窗；`dock(paneId)` 把浮窗放回活跃停靠格。不存在的 tab 或格、或已处于调用目标状态的，都原样不动。该接口只暴露操作：没有布局快照、没有操作日志、没有按地址查找。`_undo()` / `_redo()` 步进已挂载停靠面的历史；它们是 `@internal`——序列没有面向用户的控件，这两个只为测试存在。命令需要一个已挂载的会话停靠面；没有时它们 throw，而不是写进一个没人绘制的面里。
+
+<a id="the-tab-domain"></a>
+## Tab 域
+
+Tab域按（Session，Tab id）保留导航、中止信号与绑定动作；私有装配回调收养各会话的store，并在每次提交时对齐记录。记录消失或插件卸载才中止signal，收起和切会话不销毁记录；undo恢复的是新occurrence。`useTabInfo()` 组合框架绑定的store与导航hook，不在组件中手写订阅或在渲染时创建记录。`tab.actions` 始终作用于自己的会话；`tab.visible` 区分正文与标题，浮窗不受整栏收起影响。`adopt` 不在公开控制器上。
+
+<a id="the-guide"></a>
+## 引导页
+
+引导 tab 是一个居中标题、其下一行说明，以及各已注册类型贡献的每个 `guide` 条目一个入口框，按 `order` 排列。选中一个框会调用 `tab.actions.openTab(entry.kind, { replaceTab: true })`，于是引导页让位给它打开的页。一个格最多持有一个引导 tab。tab 条的添加控件只在该格没有引导 tab 时绘制，并以 `openTab('guide', { paneId, revealIfOpened: false })` 在该格打开一个，这样别的格里的引导页不会截走这次点击；把引导页开进已有引导页的格则改为聚焦它；把引导页拖入、放入或收回到这样的格会合并进去——来者关闭，该格自己的被聚焦；对引导页 `duplicateTab` 不记录任何东西。分栏或被清空的根格通过套件的工厂播种一个引导页，每个新格一个。普通的 `openTab('guide')` 保留每次打开都有的整树聚焦。产品最多保留左右两格，默认均分，分隔条限定20%～80%。宽度不足以容纳两格时不允许新分栏；已有两格时，正文拖放用于跨格移动，不再创建第三格。 达到两格上限时隐藏分栏控件；关闭回单格后恢复。
+
+<a id="copy"></a>
+## 文案
+
+该列里的每个字符串都来自 `sidebarRight` 语言命名空间，包括套件的无障碍名称。tab 的标题在 tab 铸造时固定；类型的显示名跟随当前语言。
+
+<a id="model-experience"></a>
+## 模型体验
+
+None, as the package is a browser-side UI plugin layer that registers nothing model-facing.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **只在内存中。** 不持久化任何东西；刷新让每个会话从折叠态开始。
+- **没有会话就没有停靠面。** 状态按会话 id 键控，因此 hero 画面右侧什么都不显示。
+- **硬编码的层叠。** 面板与浮窗宿主使用固定的 z-index 值，因为客户端还没有 z-index token 层。
+- **未暴露撤销。** 记录的序列只能通过 `@internal` 服务方法步进；产品控件是有意缺席的。
+- **引导页文案是草稿**，等待产品评审；文字住在 `locales.ts`。
+- **标题在打开时固定。** 类型的 `title(address)` 被捕获进记录；会变的标题只来自可选的标题席位。
+- **没有内容导航栈。** 后退回放的是布局操作；编辑器式的「已访问内容」前进/后退尚未构建。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文——点击展开</summary>
+
+无。
+
+</details>
+
+**运行时不变量：** 不发布 companion。两个服务（`sidebarRight`、`sidebarRightTabs`）在同一个 effect 内经 `ctx.reflect.provide` 提供并随之拆除；席位绑定与 Tab 域 occurrence 的生命周期由本包的 spec 直接断言，不存在会与之分歧的独立观察。
diff --git a/packages/client/ui-sidebar-right/package.json b/packages/client/ui-sidebar-right/package.json
new file mode 100644
index 0000000000..0268a05a33
--- /dev/null
+++ b/packages/client/ui-sidebar-right/package.json
@@ -0,0 +1,79 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-sidebar-right",
+  "description": "Right Sidebar: the docking surface's session-bound state, its panel and header expand control, and the navigation service over it",
+  "version": "0.1.3-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/ui-sidebar-right"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-api-session-controller",
+        "@deepseek-ai/dsh-client-resources",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-session"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "clsx": "^2.0.0",
+    "picomatch": "^4.0.4",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "workspace:^"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "workspace:^",
+    "@deepseek-ai/dsh-api-session-controller": "workspace:^",
+    "@deepseek-ai/dsh-client-locale": "workspace:^",
+    "@deepseek-ai/dsh-client-resources": "workspace:^",
+    "@deepseek-ai/dsh-client-store": "workspace:^",
+    "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-dockkit": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-renderer": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-session": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@testing-library/react": "^16.1.0",
+    "@types/picomatch": "^4.0.2",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ]
+}
diff --git a/packages/client/ui-sidebar-right/src/client/contract/params.ts b/packages/client/ui-sidebar-right/src/client/contract/params.ts
new file mode 100644
index 0000000000..6b29656839
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/client/contract/params.ts
@@ -0,0 +1,52 @@
+/**
+ * Navigation parameters, typed by what is being opened.
+ *
+ * Two declaration-merged maps. `SidebarRightResourceParamsMap` is keyed by
+ * resource type — the segment after `dsh-resource://` — and filled by the
+ * package that owns that type (the `file` provider adds `file: { line?: number }`);
+ * `SidebarRightTabParamsMap` is keyed by tab kind and filled by a page type that
+ * takes parameters (neither shipped page does). Values are JSON-shaped by
+ * convention; nothing validates them at run time, because caller and body meet
+ * at a typed same-process boundary. A body narrows `navigation.params` by the
+ * scheme and type of `navigation.address`.
+ *
+ * The unions below are spelled as indexed accesses over a record rather than as
+ * `A | B`: in a program where no package has augmented a map, both sides of such
+ * a union resolve to `undefined`, which the type-aware lint reads as a duplicated
+ * constituent. The indexed access names the same union without the pair.
+ */
+
+/** The values of a record, as one union. */
+type ValuesOf<T> = T[keyof T]
+
+/** Resource type → the parameters a resource of that type accepts. Merge-extensible. */
+export interface SidebarRightResourceParamsMap {}
+
+/** What `openResource` accepts as `params`: a declared resource type's parameters, or `undefined` for none. */
+export type SidebarRightResourceParams = ValuesOf<{
+  declared: SidebarRightResourceParamsMap[keyof SidebarRightResourceParamsMap]
+  none: undefined
+}>
+
+/** Tab kind → the parameters a page of that kind accepts. Merge-extensible. */
+export interface SidebarRightTabParamsMap {}
+
+/**
+ * What `openTab(kind)` accepts as `params` for one kind: its declared parameters,
+ * or `undefined` for none; a kind that declares none accepts only `undefined`.
+ */
+export type SidebarRightTabParamsFor<K extends string> =
+  | (K extends keyof SidebarRightTabParamsMap ? SidebarRightTabParamsMap[K] : never)
+  | undefined
+
+/** Every declared page kind's parameters, or `undefined` for none. */
+export type SidebarRightTabParams = ValuesOf<{
+  declared: SidebarRightTabParamsMap[keyof SidebarRightTabParamsMap]
+  none: undefined
+}>
+
+/** What a body may find in `navigation.params`: either map's values, or `undefined` when the opener gave none. */
+export type SidebarRightNavigationParams = ValuesOf<{
+  resource: SidebarRightResourceParams
+  tab: SidebarRightTabParams
+}>
diff --git a/packages/client/ui-sidebar-right/src/client/contract/seed.ts b/packages/client/ui-sidebar-right/src/client/contract/seed.ts
new file mode 100644
index 0000000000..638801a87e
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/client/contract/seed.ts
@@ -0,0 +1,41 @@
+/**
+ * The guide tab's identity, the page-address scheme, and the seed factory.
+ *
+ * These live in the contract because two sides need them and neither may read
+ * the other: the store seeds every new pane with a guide tab, and the guide
+ * domain registers the type under the same kind.
+ *
+ * The docking kit treats `kind` as opaque, so these strings mean something only
+ * here and in the registry. Both types go through the same two stages any other
+ * type would use — the guide is not special in the machinery, only in being
+ * always available.
+ */
+import type { TabId, TabRecord } from '@deepseek-ai/dsh-client-ui-dockkit'
+
+/** The guide tab's kind. */
+export const GUIDE_KIND = 'guide'
+
+/**
+ * The address a page tab is recorded under: `sidebar://<kind>`. The scheme is
+ * this package's bookkeeping for `openTab`, spelled here and nowhere else; a
+ * caller names the kind and never sees or composes the address.
+ * @param kind - the page type's kind.
+ * @returns the page's address.
+ */
+export function pageAddress(kind: string): string {
+  return `sidebar://${kind}`
+}
+
+/**
+ * Build the guide tab a new pane is seeded with.
+ *
+ * The title is captured at mint time because it goes into the surface's
+ * operation sequence, which records what happened and must not change meaning
+ * later. A language change relabels the type, not tabs already open.
+ * @param id - tab id minted by the caller.
+ * @param title - the guide type's display name at mint time.
+ * @returns the guide tab record.
+ */
+export function makeGuideTab(id: TabId, title: string): TabRecord {
+  return { id, kind: GUIDE_KIND, contentId: pageAddress(GUIDE_KIND), title }
+}
diff --git a/packages/client/ui-sidebar-right/src/client/contract/slots.ts b/packages/client/ui-sidebar-right/src/client/contract/slots.ts
new file mode 100644
index 0000000000..49709181c5
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/client/contract/slots.ts
@@ -0,0 +1,170 @@
+/**
+ * The right Sidebar's extension seats and its copy namespace.
+ *
+ * Four seats, each with a different reason to exist:
+ * - `sidebar.right.pane.tab` is how a tab type contributes a body. It is keyed by
+ *   the type definition's `id`, so adding a type is a registration, never an
+ *   edit here. The key domain stays the open string space because a tab type may
+ *   ship from outside this repository.
+ * - `sidebar.right.pane.tab.title` is the same dispatch for what the chip shows
+ *   as the tab's title. Registering is optional: without an entry the chip shows
+ *   the title the registry captured when the tab opened.
+ * - `sidebar.right.tab.guide` lets a product replace the guide tab's contents
+ *   without replacing the tab. It is a chain because the replacement decides for
+ *   itself whether it applies, and the shipped guide is the owner's fallback.
+ * - `sidebar.right.tab.menu.item` extends a tab's actions menu. The kit owns the
+ *   actions that are gestures on the layout itself; this seat is for actions that
+ *   mean something about the tab's content.
+ *
+ * TYPE HOME RATIONALE: this package declares all four at runtime, and anything
+ * registering into one already depends on it for the declaration. The types
+ * therefore live with their declarer.
+ */
+import type {} from '@deepseek-ai/dsh-client-ui-slots'
+// The locale plugin's own merge carries the shared `common` vocabulary that the
+// lookup chain consults after this namespace misses.
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+import type { PaneId, TabRecord } from '@deepseek-ai/dsh-client-ui-dockkit'
+import type { SlotHookFactory } from '@deepseek-ai/dsh-client-ui-slots'
+import type { TabHookContext } from '../tab-info.ts'
+import type { SidebarRightKey } from '../locales.ts'
+import type { SidebarRightNavigationParams, SidebarRightResourceParams, SidebarRightTabParamsFor } from './params.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap {
+    /** Right-Sidebar chrome, docking-kit vocabulary, and guide copy. */
+    sidebarRight: SidebarRightKey
+  }
+
+  interface SlotMap {
+    /**
+     * One tab's body, dispatched with the `id` of the type in force for
+     * `tab.kind`. A tab type registers here under its definition's `id` and
+     * receives every tab of that kind, in every pane, docked or floating. A kind
+     * with no type in force renders the owner's "nothing can view this" notice
+     * rather than an empty pane.
+     */
+    'sidebar.right.pane.tab': {
+      kind: 'keyed'
+      scope: 'session'
+      hookContext: TabHookContext
+      inject: SidebarRightTabInjected
+    }
+    /**
+     * A tab's title as its chip (and a floating panel's header) shows it,
+     * dispatched with the same key and information hook as the body. A type with a
+     * live title — a terminal named after its shell, a chat after its first
+     * line — registers here and reads its own store; one without registers
+     * nothing and the chip shows the registry's `title(address)` text captured
+     * at open time.
+     */
+    'sidebar.right.pane.tab.title': {
+      kind: 'keyed'
+      scope: 'session'
+      hookContext: TabHookContext
+      inject: SidebarRightTabInjected
+    }
+    /**
+     * The guide tab's body. Selectors run in chain order and the first
+     * non-declining entry replaces the shipped guide entirely; with no entry, or
+     * with every entry declining, the shipped guide renders.
+     */
+    'sidebar.right.tab.guide': {
+      kind: 'chain'
+      scope: 'session'
+      hookContext: UseSidebarRightTabInfo
+      inject: { hooks: { tabInfo: SlotHookFactory<'sidebar.right.tab.guide', UseSidebarRightTabInfo> } }
+    }
+    /**
+     * Extra items at the end of one tab's actions menu, in registration order.
+     * Entries decide their own visibility from the tab they are given. Without a
+     * registrant the menu shows only the kit's own layout actions.
+     */
+    'sidebar.right.tab.menu.item': { kind: 'list'; scope: 'session'; owner: SidebarRightTabMenuOwnerProps }
+  }
+}
+
+/** Where a tab was last navigated to: what the `open` that created or revealed it carried. */
+export interface SidebarRightTabNavigation {
+  /** The address opened; for a tab record this is its `contentId`. */
+  readonly address: string
+  /** The opener's `params` (see `contract/params.ts`); `undefined` when it gave none. */
+  readonly params: SidebarRightNavigationParams
+  /**
+   * Incremented on every navigation to this tab, whether or not `params`
+   * changed, so a body can act on "navigated again" alone. `0` for a record
+   * nobody opened by address: a seeded guide, or a tab restored by undo.
+   */
+  readonly revision: number
+}
+
+/** Where an open from a tab lands. Without any of these it lands in the pane holding the tab at call time. */
+export interface SidebarRightTabPlacement {
+  /** Land a new tab in this pane instead. */
+  readonly paneId?: PaneId
+  /** Defaults to `true`: a tab already showing the same content is focused instead of a second one opening. */
+  readonly revealIfOpened?: boolean
+  /** `true` opens in this tab's place — its pane and strip slot — and closes this tab in the same step. */
+  readonly replaceTab?: boolean
+}
+
+/** The actions one tab may take on itself; each acts on the session the tab is in. */
+export interface SidebarRightTabActions {
+  /**
+   * Open a resource from this tab; see `ISidebarRight.openResource`.
+   * @param address - a `dsh-resource://` address.
+   * @param options - placement and the resource's navigation parameters.
+   */
+  openResource(address: string, options?: SidebarRightTabPlacement & { readonly params?: SidebarRightResourceParams }): void
+  /**
+   * Open a page type from this tab; see `ISidebarRight.openTab`.
+   * @param kind - the page type's kind.
+   * @param options - placement and that kind's navigation parameters.
+   */
+  openTab<K extends string>(kind: K, options?: SidebarRightTabPlacement & { readonly params?: SidebarRightTabParamsFor<K> }): void
+  /** Close this tab. */
+  close(): void
+}
+
+/** Live information shared by a tab's body, title, and guide replacement. */
+export interface SidebarRightTabInfo {
+  readonly sidebar: {
+    readonly expanded: boolean
+    /** Presentation selected by manual mode or viewport width; preserved while collapsed. */
+    readonly fullscreen: boolean
+  }
+  readonly panel: { readonly id: PaneId }
+  readonly tab: TabRecord & {
+    /** Docked bodies need an expanded sidebar and an active tab; expanded titles include inactive tabs. Floats stay visible. */
+    readonly visible: boolean
+    readonly navigation: SidebarRightTabNavigation
+    /** Aborted only when the record disappears or this plugin unloads, not on hide or session switch. */
+    readonly signal: AbortSignal
+    readonly actions: SidebarRightTabActions
+  }
+}
+
+/**
+ * Read current tab information through the slot framework's subscriptions.
+ * @returns the sidebar presentation, containing pane, and live tab record.
+ */
+export type UseSidebarRightTabInfo = () => SidebarRightTabInfo
+
+/** The slot-owned hook shared by every tab body and title registration. */
+export interface SidebarRightTabInjected {
+  hooks: { tabInfo: SlotHookFactory<'sidebar.right.pane.tab', UseSidebarRightTabInfo> }
+}
+
+/** Owner share of one tab-menu item occurrence. */
+export interface SidebarRightTabMenuOwnerProps {
+  /** The tab whose menu is open. */
+  tab: TabRecord
+  /**
+   * Dismiss the menu.
+   *
+   * An item that acts MUST call this: the menu is the kit's, and it closes on
+   * its own actions only. An item that leaves it open leaves a menu floating
+   * over content the action may have just replaced.
+   */
+  dismiss: () => void
+}
diff --git a/packages/client/ui-sidebar-right/src/client/index.ts b/packages/client/ui-sidebar-right/src/client/index.ts
new file mode 100644
index 0000000000..0971b9d21c
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/client/index.ts
@@ -0,0 +1,194 @@
+/**
+ * Browser half: fill the frame's right column with the panel, put the expand
+ * button in the conversation header, and own the seats a tab type registers
+ * into.
+ *
+ * Two seats share one session-scoped store, which the slot runtime allows
+ * because both are session-scoped (a handle may not span scopes). The panel seat
+ * in the frame draws the surface normally or fullscreen, retaining the track
+ * on wide viewports; the header's corner seat draws the way back in
+ * while the panel is hidden. The store is the layout's only source of truth; the docking
+ * kit's pure planners compute every change and the store records them, one
+ * history entry per intent.
+ *
+ * The frame is a base package and never injects this one. What it needs —
+ * whether the panel is shown and whether it wants a track — arrives through its
+ * own `ctx.layout` action face, reported by the seat that knows both facts.
+ *
+ * Tab types register in two stages: the type itself into `ctx.sidebarRightTabs`,
+ * its body into the keyed `sidebar.right.pane.tab` seat under the same kind. The
+ * guide registers through those stages unmodified, exactly as a type shipped
+ * from another package does — `ui-sidebar-textpreview` is the live proof.
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-client-resources/client'
+import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
+import type {} from '@deepseek-ai/dsh-client-ui-session/client'
+import type { ILayout } from '@deepseek-ai/dsh-client-ui-layout/client'
+import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type {} from './contract/slots.ts'
+import { GuideBody, type GuideInjected } from './tabs/guide/GuideBody.tsx'
+import { ExpandButton } from './shell/ExpandButton.tsx'
+import { RightbarSeat, type SidebarRightInjected } from './shell/SidebarRight.tsx'
+import { createSidebarRightController, type SidebarRightController } from './service.ts'
+import { SidebarRightTabRegistry } from './tab-registry.ts'
+import { createSidebarRightStore } from './stores.ts'
+import { en, zh } from './locales.ts'
+import { GUIDE_ID, guideDefinition } from './tabs/guide/definition.ts'
+import { guideTabInfoFactory, tabInfoFactory } from './tab-info.ts'
+import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+
+export type { RightbarSeatProps, SidebarRightInjected, SidebarRightPresentation } from './shell/SidebarRight.tsx'
+export type { GuideBodyProps, GuideInjected } from './tabs/guide/GuideBody.tsx'
+export type { ExpandButtonProps } from './shell/ExpandButton.tsx'
+export type { SidebarRightState, SurfaceState } from './stores.ts'
+export type {
+  ISidebarRight, SidebarRightBinding, SidebarRightOpenResourceOptions, SidebarRightOpenTabOptions,
+  SidebarRightPlacement, SurfaceActions,
+} from './service.ts'
+export type {
+  SidebarRightGuideBox, SidebarRightGuideEntry, SidebarRightTabClaim, SidebarRightTabDefinition,
+  SidebarRightTabPriority,
+} from './tab-registry.ts'
+export type {
+  SidebarRightTabInfo, SidebarRightTabInjected, UseSidebarRightTabInfo, SidebarRightTabActions,
+  SidebarRightTabMenuOwnerProps, SidebarRightTabNavigation, SidebarRightTabPlacement,
+} from './contract/slots.ts'
+export type {
+  SidebarRightNavigationParams, SidebarRightResourceParams, SidebarRightResourceParamsMap,
+  SidebarRightTabParams, SidebarRightTabParamsFor, SidebarRightTabParamsMap,
+} from './contract/params.ts'
+// The layout ids and rectangle the navigation face takes, so a caller needs no import from the kit.
+export type { FloatRect, PaneId, TabId, TabRecord } from '@deepseek-ai/dsh-client-ui-dockkit'
+export type { PinResource, SidebarRightNavigator, TabOccurrence } from './tab-domain.ts'
+export type { SidebarRightKey } from './locales.ts'
+export type { OpenContentIntent } from './stores.ts'
+
+/** This package's copy namespace. */
+const NS = 'sidebarRight'
+
+/** Required browser services: the slot registry, the frame's panel actions, copy, and the resource model. */
+export const inject = ['slots', 'layout', 'locale', 'resources']
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** Right-Sidebar navigation and presentation face. */
+    sidebarRight: SidebarRightController
+    /** Right-Sidebar tab-type registry (stage one of a tab type's registration). */
+    sidebarRightTabs: SidebarRightTabRegistry
+  }
+}
+
+/**
+ * Client plugin body: provide the registry and the navigation face, register the
+ * panel seat and the rail seat over one store with their extension children, and
+ * register the guide type through the same public two-stage path any other type
+ * uses.
+ * @param ctx - client root context carrying the slot registry, the frame's face, and copy.
+ */
+export function apply(ctx: ClientContext): void {
+  // The registry and the face it backs are built here, at apply's top level,
+  // and never inside an effect. A registry other packages register into cannot
+  // have an effect-internal scope as its host: `register()` adds an effect to
+  // this fiber, and doing that from another plugin's apply while the effect is
+  // still the active scope stalls browser boot with no error at all. The
+  // template this follows (ui-conversation's definition registry) is built at
+  // its own apply top level for the same reason.
+  const t = ctx.locale.bind(NS)
+  const tabs = new SidebarRightTabRegistry(ctx)
+  const { controller, adopt } = createSidebarRightController(
+    tabs,
+    (address, signal) => { ctx.resources.pin(address, signal) },
+  )
+  const disposeRegistry = ctx.reflect.provide('sidebarRightTabs', tabs)
+  const disposeService = ctx.reflect.provide('sidebarRight', controller)
+  // Registered first, so it tears down last: the faces outlive every seat and
+  // type that reaches for them. provide()'s disposer settles asynchronously;
+  // teardown is synchronous fire-and-forget, matching ui-layout's root entry.
+  // Unloading aborts every tab occurrence, which releases every pin.
+  ctx.effect(() => () => {
+    controller.tabDomain.dispose()
+    void disposeService()
+    void disposeRegistry()
+  }, 'ui-sidebar-right: service faces')
+
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-sidebar-right: dictionaries')
+
+  ctx.effect(() => {
+    const handle = createSidebarRightStore(() => t('tab.guide.title'))
+    // The runtime mints one instance of this handle per session (the scope key
+    // is the session id) and caches it per key. Each is adopted as it is minted,
+    // so a tab's own action reaches its session's store while another session
+    // is on screen, and that store's commits sync the Tab domain themselves.
+    const adoptions: Array<() => void> = []
+    const store: typeof handle = {
+      ...handle,
+      create: (scopeKey) => {
+        const instance = handle.create(scopeKey)
+        if (scopeKey !== undefined) adoptions.push(adopt(scopeKey as SessionId, instance))
+        return instance
+      },
+    }
+    const layout: ILayout = ctx.layout
+    const injected: Omit<SidebarRightInjected, 'keyedHooks' | 'occurrence'> = {
+      syncPresentation({ shown, track, fullscreen }) {
+        if (shown) layout.openRightbar(track, fullscreen)
+        else layout.closeRightbar()
+      },
+      bindService: binding => controller.bind(binding),
+      openTab: (kind, options) => { controller.openTab(kind, options) },
+      hooks: { tabTypes: { subscribe: listener => tabs.subscribe(listener), getSnapshot: () => tabs.entries() } },
+    }
+
+    const disposeTypes = [tabs.register(guideDefinition(t))]
+    const disposeSeat = ctx.slots.inject('rightbar', () => ctx.slots.register({
+      name: 'rightbar',
+      locale: NS,
+      children: {
+        'sidebar.right.pane.tab': { kind: 'keyed', scope: 'session', inject: { hooks: { tabInfo: tabInfoFactory } } },
+        'sidebar.right.pane.tab.title': { kind: 'keyed', scope: 'session', inject: { hooks: { tabInfo: tabInfoFactory } } },
+        'sidebar.right.tab.menu.item': { kind: 'list', scope: 'session' },
+      },
+      store,
+      inject: (sessionId): SidebarRightInjected => ({
+        ...injected,
+        keyedHooks: { tabNavigation: key => controller.tabDomain.occurrence(sessionId, { id: key as TabId }).navigation },
+        occurrence: tab => controller.tabDomain.occurrence(sessionId, tab),
+      }),
+    }, RightbarSeat))
+    // The expand button shares the panel's store: it only needs to know whether
+    // the panel is expanded, and to ask for it to be. The header's corner seat
+    // is its own place, past the utilities, so showing and hiding it moves
+    // nothing else in the row.
+    const disposeExpand = ctx.slots.inject('conversation.session.header.corner', () => ctx.slots.register({
+      name: 'conversation.session.header.corner',
+      locale: NS,
+      store,
+    }, ExpandButton))
+    // Stage two for the guide: it declares the chain child it hosts and reads
+    // the registry's entry boxes, which an ordinary type has no reason to do.
+    const guideInjected: GuideInjected = {
+      hooks: { guideEntries: { subscribe: listener => tabs.subscribe(listener), getSnapshot: () => tabs.guide() } },
+    }
+    const disposeGuide = ctx.slots.inject('sidebar.right.pane.tab', () => ctx.slots.register({
+      name: 'sidebar.right.pane.tab',
+      key: GUIDE_ID,
+      locale: NS,
+      children: {
+        'sidebar.right.tab.guide': {
+          kind: 'chain', scope: 'session', inject: { hooks: { tabInfo: guideTabInfoFactory } },
+        },
+      },
+      inject: () => guideInjected,
+    }, GuideBody))
+    return () => {
+      disposeGuide()
+      disposeExpand()
+      disposeSeat()
+      for (const dispose of disposeTypes.reverse()) dispose()
+      for (const release of adoptions) release()
+    }
+  }, 'ui-sidebar-right: seats and shipped tab type')
+}
diff --git a/packages/client/ui-sidebar-right/src/client/labels.ts b/packages/client/ui-sidebar-right/src/client/labels.ts
new file mode 100644
index 0000000000..d259eecca7
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/client/labels.ts
@@ -0,0 +1,30 @@
+/**
+ * The docking kit's vocabulary, in the product's language.
+ *
+ * The kit renders no string of its own, so every word a user reads inside it is
+ * handed over from here. This is a projection of the dictionary, not a second
+ * home for copy: the strings live in `locales.ts`.
+ */
+import type { DockLabels } from '@deepseek-ai/dsh-client-ui-dockkit'
+import type { TranslateNS } from '@deepseek-ai/dsh-client-locale/client'
+
+/**
+ * Project the dictionary into the kit's label contract.
+ *
+ * Called during render, so a language change reaches the kit with the next one —
+ * the kit caches no copy to invalidate.
+ * @param t - namespace-bound translate.
+ * @returns every string the kit renders.
+ */
+export function dockLabels(t: TranslateNS<'sidebarRight'>): DockLabels {
+  return {
+    emptyPane: t('dock.emptyPane'),
+    splitPane: t('dock.splitPane'),
+    splitPaneDisabled: t('dock.splitPaneDisabled'),
+    splitPaneNarrow: t('dock.splitPaneNarrow'),
+    closeTab: t('dock.closeTab'),
+    addTab: t('dock.addTab'),
+    dockFloat: t('dock.dockFloat'),
+    closeFloat: t('dock.closeFloat'),
+  }
+}
diff --git a/packages/client/ui-sidebar-right/src/client/locales.ts b/packages/client/ui-sidebar-right/src/client/locales.ts
new file mode 100644
index 0000000000..3e5b697967
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/client/locales.ts
@@ -0,0 +1,50 @@
+/**
+ * `sidebarRight` namespace dictionaries.
+ *
+ * Everything a user reads in this column is here, including the strings handed
+ * to the docking kit — the kit renders no copy of its own, so its whole
+ * vocabulary is this package's to own and translate.
+ */
+
+/** Simplified Chinese dictionary and key-set source of truth. */
+export const zh = {
+  'chrome.expand': '展开侧栏',
+  'chrome.collapse': '收起侧栏',
+  'chrome.toFullscreen': '全屏显示侧栏',
+  'chrome.exitFullscreen': '退出侧栏全屏',
+  'dock.emptyPane': '空面板',
+  'dock.splitPane': '向右分栏',
+  'dock.splitPaneDisabled': '已达两格上限',
+  'dock.splitPaneNarrow': '栏宽不足，拖宽侧栏后再分栏',
+  'dock.closeTab': '关闭',
+  'dock.addTab': '新标签页',
+  'dock.dockFloat': '收回到侧栏',
+  'dock.closeFloat': '关闭',
+  'tab.guide.title': '开始',
+  'tab.unavailable': '这类内容还没有可用的查看方式。',
+  'guide.lead': '侧栏用来放你想一直看着的东西。',
+  'guide.body': '会话里的文件和产物会开在这一栏，也可以从下面的入口打开。',
+} satisfies Record<string, string>
+
+/** Right-Sidebar dictionary key union. */
+export type SidebarRightKey = keyof typeof zh
+
+/** English dictionary, checked against the Chinese key set. */
+export const en = {
+  'chrome.expand': 'Open the sidebar',
+  'chrome.collapse': 'Close the sidebar',
+  'chrome.toFullscreen': 'Show the sidebar fullscreen',
+  'chrome.exitFullscreen': 'Exit sidebar fullscreen',
+  'dock.emptyPane': 'Empty pane',
+  'dock.splitPane': 'Split to the right',
+  'dock.splitPaneDisabled': 'Two panes is the limit',
+  'dock.splitPaneNarrow': 'Not enough width to split; widen the sidebar',
+  'dock.closeTab': 'Close',
+  'dock.addTab': 'New tab',
+  'dock.dockFloat': 'Send back to the sidebar',
+  'dock.closeFloat': 'Close',
+  'tab.guide.title': 'Start',
+  'tab.unavailable': 'Nothing here can view this kind of content yet.',
+  'guide.lead': 'The sidebar holds what you want to keep looking at.',
+  'guide.body': 'Files and artifacts from the conversation open in this column; the entries below open more.',
+} satisfies Record<SidebarRightKey, string>
diff --git a/packages/client/ui-sidebar-right/src/client/service.ts b/packages/client/ui-sidebar-right/src/client/service.ts
new file mode 100644
index 0000000000..25e702b612
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/client/service.ts
@@ -0,0 +1,476 @@
+/**
+ * `ctx.sidebarRight`: what other plugins may ask of this column.
+ *
+ * The surface is per session and its state lives in that session's store
+ * instance, which the slot runtime mints per session and a root service cannot
+ * reach on its own. Two paths lead in. The mounted seat publishes its binding —
+ * session id, bound actions, its surface — for exactly as long as it is mounted,
+ * and every command on the public face goes through that binding; a command
+ * arriving with no seat mounted has no session to act on and fails loudly rather
+ * than writing into a surface nobody is drawing. And the plugin adopts each
+ * session's store instance as the runtime mints it, so the controller reaches
+ * any session's store by id and syncs the Tab domain from that store's commits.
+ *
+ * A tab's own actions (`tabActions`) aim at the session the tab is in, not at
+ * the mounted one: they run through that session's adopted store, so a callback
+ * fired after the user switched sessions still lands where its tab is, and they
+ * do nothing for a session whose store was never minted.
+ *
+ * `openResource` and `openTab` are the navigation controller, and every way
+ * into the column is a call to one of them: the conversation's file links, a
+ * tool row's line reference, the strip's add control, a guide entry box, a file
+ * tree's rows. A resource is claimed through the registry by address; a page is
+ * named by kind and recorded at the address this package composes for it. Both
+ * hand the store one settled intent and record the navigation in the Tab
+ * domain. Placement is the caller's option, never a type's property.
+ *
+ * Wiring follows `LayoutController.attachPanels`: the registration hands the
+ * service its store actions, and the service is the face other plugins hold.
+ */
+import type { FloatRect, PaneId, TabId, TabRecord } from '@deepseek-ai/dsh-client-ui-dockkit'
+import { activeDockPaneId, canSplit, dockPaneIds, findTabPane, getPane } from '@deepseek-ai/dsh-client-ui-dockkit'
+import type { BoundActions } from '@deepseek-ai/dsh-client-ui-slots'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { SidebarRightNavigationParams, SidebarRightResourceParams, SidebarRightTabParamsFor } from './contract/params.ts'
+import { pageAddress } from './contract/seed.ts'
+import type { SidebarRightTabClaim, SidebarRightTabRegistry } from './tab-registry.ts'
+import type { SidebarRightState, SurfaceState } from './stores.ts'
+import type { createSidebarRightStore } from './stores.ts'
+import { TabDomain, type PinResource } from './tab-domain.ts'
+
+/** The seat's bound action set. */
+export type SurfaceActions = BoundActions<ReturnType<typeof createSidebarRightStore>>
+
+/** One session's store instance as the slot runtime minted it: its actions and its observable snapshot. */
+export interface SidebarRightSurfaceStore {
+  readonly actions: SurfaceActions
+  getSnapshot(): SidebarRightState
+  subscribe(listener: () => void): () => void
+}
+
+/** One adoption of a session's store; the token a release compares against. */
+interface Adoption {
+  readonly store: SidebarRightSurfaceStore
+  readonly unsubscribe: () => void
+}
+
+/**
+ * Create the public controller and the plugin-private store adoption callback.
+ * Adoption subscribes without reconciling; the first store commit creates occurrences.
+ * @param tabs - registered tab types.
+ * @param pin - resource retention for an occurrence's lifetime.
+ * @returns the controller and a callback releasing exactly its own adoption.
+ */
+export function createSidebarRightController(tabs: SidebarRightTabRegistry, pin: PinResource): {
+  controller: SidebarRightController
+  adopt: (sessionId: SessionId, store: SidebarRightSurfaceStore) => () => void
+} {
+  const adopted = new Map<SessionId, Adoption>()
+  const controller = new SidebarRightController(tabs, pin, adopted)
+  return {
+    controller,
+    adopt(sessionId, store) {
+      adopted.get(sessionId)?.unsubscribe()
+      const sync = (): void => {
+        const surface = store.getSnapshot().bySession[sessionId]
+        if (surface !== undefined) controller.tabDomain.sync(sessionId, surface.layout)
+      }
+      const adoption: Adoption = { store, unsubscribe: store.subscribe(sync) }
+      adopted.set(sessionId, adoption)
+      return () => {
+        adoption.unsubscribe()
+        if (adopted.get(sessionId) === adoption) adopted.delete(sessionId)
+      }
+    },
+  }
+}
+
+/** Everything a command needs, as the mounted seat sees it. */
+export interface SidebarRightBinding {
+  /** The session the mounted seat is drawing. */
+  readonly sessionId: SessionId
+  /** The seat's store's bound actions; every action names the session it acts on. */
+  readonly actions: SurfaceActions
+  /**
+   * The seat's store surfaces as last committed, keyed by session id; the
+   * mounted session's is `surfaces[sessionId]`, absent before the seat's first
+   * open. The runtime mints one store per session, so this holds that session.
+   */
+  readonly surfaces: Readonly<Record<string, SurfaceState>>
+  /**
+   * The room rule's verdict for a docked pane, as the kit last measured it:
+   * whether two working halves would fit. Unmeasured panes fit.
+   */
+  readonly canSplitPane: (paneId: PaneId) => boolean
+}
+
+/** Where an open lands; every field is optional and the defaults are the common case. */
+export interface SidebarRightPlacement {
+  /** Land a new tab in this pane instead of the active docked one. */
+  readonly paneId?: PaneId
+  /** Take this tab's place — its pane and its strip slot — and close it in the same step. */
+  readonly replaceTab?: TabId
+  /**
+   * Defaults to `true`: a tab already showing the same (kind, contentId) is
+   * focused and handed `params`. `false` opens another tab regardless.
+   */
+  readonly revealIfOpened?: boolean
+}
+
+/** How a caller wants a resource opened. */
+export interface SidebarRightOpenResourceOptions extends SidebarRightPlacement {
+  /** Name the opening type instead of letting the registry rank claims; its `canOpen` still applies. */
+  readonly kind?: string
+  /** The resource's navigation parameters, typed by resource type; delivered as `navigation.params`. */
+  readonly params?: SidebarRightResourceParams
+}
+
+/** How a caller wants a page type opened. */
+export interface SidebarRightOpenTabOptions<K extends string = string> extends SidebarRightPlacement {
+  /** That kind's navigation parameters, typed by kind; delivered as `navigation.params`. */
+  readonly params?: SidebarRightTabParamsFor<K>
+}
+
+/** The scheme every resource address carries; anything else is not a resource this face opens. */
+const RESOURCE_SCHEME = 'dsh-resource://'
+
+/** The outward right-Sidebar face (`ctx.sidebarRight`). */
+export interface ISidebarRight {
+  /**
+   * Open a resource: claim it, place it, reveal the column, record the navigation.
+   *
+   * Without `options.kind` the registry ranks the types whose globs and
+   * `canOpen` accept the address and the best band wins; with it, that kind's
+   * type in force opens the address (its `canOpen` still applies). An address
+   * outside `dsh-resource://`, or one no type will open, is a wiring mistake,
+   * not a user error, so it throws. The column expands in the same step,
+   * because content the user cannot see is not opened.
+   * @param address - a `dsh-resource://<type>/…` address.
+   * @param options - placement, the opening type, and navigation parameters.
+   */
+  openResource(address: string, options?: SidebarRightOpenResourceOptions): void
+  /**
+   * Open a page type by kind: the type in force for it, at the address this
+   * package records pages under. A kind nothing registered throws.
+   * @param kind - the page type's kind.
+   * @param options - placement and that kind's navigation parameters.
+   */
+  openTab<K extends string>(kind: K, options?: SidebarRightOpenTabOptions<K>): void
+  /**
+   * Close one tab of the mounted session.
+   * @param tabId - the tab to close.
+   */
+  close(tabId: TabId): void
+  /**
+   * The active tab of the active pane.
+   * @returns the record, or `undefined` when no seat is mounted.
+   */
+  active(): TabRecord | undefined
+  /**
+   * Whether the column is currently showing its panel.
+   * @returns `true` while expanded; `false` while collapsed to its rail.
+   */
+  isExpanded(): boolean
+  /** Collapse an expanded column, or expand a collapsed one. Recorded in the sequence. */
+  toggleExpanded(): void
+  /**
+   * Focus a tab and the pane holding it, raising a floating one. Recorded.
+   * @param tabId - the tab; one that does not exist is left alone.
+   */
+  focus(tabId: TabId): void
+  /**
+   * Split a docked pane to its right and seed the new pane, under the same
+   * pane budget and room rule as the strip's split control. Recorded when it
+   * splits.
+   * @param paneId - the pane to split; defaults to the active docked pane.
+   * @returns the new pane's id, or `undefined` when nothing was split: the pane
+   *   is missing or floating, the budget is spent, or two halves would not fit.
+   */
+  split(paneId?: PaneId): PaneId | undefined
+  /**
+   * Take a docked tab out into a floating panel. Recorded.
+   * @param tabId - the tab; one that is missing or already floating is left alone.
+   * @param rect - the panel's rectangle; defaults to the cascade from the last panel.
+   */
+  float(tabId: TabId, rect?: FloatRect): void
+  /**
+   * Return a floating panel's tab to the active docked pane. Recorded.
+   * @param paneId - the floating pane; one that is missing or docked is left alone.
+   */
+  dock(paneId: PaneId): void
+}
+
+/** Cross-plugin right-Sidebar face (ctx.sidebarRight). */
+export class SidebarRightController implements ISidebarRight {
+  private binding: SidebarRightBinding | undefined
+
+  /**
+   * The Tab domain this controller navigates into; synced from each adopted
+   * store's commits, read by the seat for each body's owner share.
+   */
+  readonly tabDomain: TabDomain
+
+  /**
+   * @param tabs - the tab-type registry consulted to claim an address.
+   * @param pin - `ctx.resources.pin`, which the Tab domain holds addresses with.
+   * @param adopted - plugin-owned session stores used by occurrence actions.
+   */
+  constructor(
+    private readonly tabs: SidebarRightTabRegistry,
+    pin: PinResource,
+    private readonly adopted = new Map<SessionId, Adoption>(),
+  ) {
+    this.tabDomain = new TabDomain(this, pin)
+  }
+
+  /**
+   * Adopt the mounted seat's binding, replacing any previous one.
+   *
+   * Called from the seat while it is mounted, and released when it leaves.
+   * @param binding - the mounted seat's session, actions, and the store's surfaces.
+   * @returns a release callback that clears exactly this binding.
+   */
+  bind(binding: SidebarRightBinding): () => void {
+    this.binding = binding
+    return () => {
+      // A newer seat may already have taken over; only the binding that is
+      // still ours may be cleared.
+      if (this.binding === binding) this.binding = undefined
+    }
+  }
+
+  /**
+   * Open a resource: claim it, place it, reveal the column, record the navigation.
+   * @param address - a `dsh-resource://<type>/…` address.
+   * @param options - placement, the opening type, and navigation parameters.
+   */
+  openResource(address: string, options: SidebarRightOpenResourceOptions = {}): void {
+    const { sessionId, actions } = this.require()
+    this.placeResource(sessionId, actions, address, options)
+  }
+
+  /**
+   * Open a page type by kind at the address this package records pages under.
+   * @param kind - the page type's kind.
+   * @param options - placement and that kind's navigation parameters.
+   */
+  openTab<K extends string>(kind: K, options: SidebarRightOpenTabOptions<K> = {}): void {
+    const { sessionId, actions } = this.require()
+    this.placeTab(sessionId, actions, kind, options)
+  }
+
+  /**
+   * Open a resource in one session, for a tab's own action; nothing happens
+   * for a session whose store was never adopted or whose adoption was released.
+   * Not part of `ISidebarRight`: the Tab domain's path.
+   * @param sessionId - the session the acting tab is in.
+   * @param address - a `dsh-resource://<type>/…` address.
+   * @param options - placement, the opening type, and navigation parameters.
+   */
+  openResourceIn(sessionId: SessionId, address: string, options: SidebarRightOpenResourceOptions = {}): void {
+    const actions = this.actionsFor(sessionId)
+    if (actions !== undefined) this.placeResource(sessionId, actions, address, options)
+  }
+
+  /**
+   * Open a page type in one session, for a tab's own action; nothing happens
+   * for a session whose store was never adopted or whose adoption was released.
+   * Not part of `ISidebarRight`: the Tab domain's path.
+   * @param sessionId - the session the acting tab is in.
+   * @param kind - the page type's kind.
+   * @param options - placement and that kind's navigation parameters.
+   */
+  openTabIn<K extends string>(sessionId: SessionId, kind: K, options: SidebarRightOpenTabOptions<K> = {}): void {
+    const actions = this.actionsFor(sessionId)
+    if (actions !== undefined) this.placeTab(sessionId, actions, kind, options)
+  }
+
+  /**
+   * Close a tab of one session, for the tab's own action; nothing happens
+   * for a session whose store was never adopted or whose adoption was released.
+   * Not part of `ISidebarRight`: the Tab domain's path.
+   * @param sessionId - the session the tab is in.
+   * @param tabId - the tab to close.
+   */
+  closeIn(sessionId: SessionId, tabId: TabId): void {
+    const actions = this.actionsFor(sessionId)
+    if (actions !== undefined) actions.closeTab(sessionId, tabId)
+  }
+
+  /** Claim a resource and place it in one session; an address outside the scheme or one no type claims throws. */
+  private placeResource(
+    sessionId: SessionId,
+    actions: SurfaceActions,
+    address: string,
+    options: SidebarRightOpenResourceOptions,
+  ): void {
+    if (!address.startsWith(RESOURCE_SCHEME)) {
+      throw new Error(`sidebarRight: no registered tab type claims "${address}"`)
+    }
+    this.place(sessionId, actions, this.tabs.claim(address, options.kind), address, options, options.params)
+  }
+
+  /** Place a page type in one session at the address pages are recorded under; an unregistered kind throws. */
+  private placeTab<K extends string>(
+    sessionId: SessionId,
+    actions: SurfaceActions,
+    kind: K,
+    options: SidebarRightOpenTabOptions<K>,
+  ): void {
+    const definition = this.tabs.get(kind)
+    if (definition === undefined) throw new Error(`sidebarRight: no tab type is registered as "${kind}"`)
+    const address = pageAddress(kind)
+    this.place(sessionId, actions, { kind, contentId: address, title: definition.title(address) }, address, options, options.params)
+  }
+
+  /** The steps both opens share: one store intent, and the navigation record for the tab it settles on. */
+  private place(
+    sessionId: SessionId,
+    actions: SurfaceActions,
+    claim: SidebarRightTabClaim,
+    address: string,
+    placement: SidebarRightPlacement,
+    params: SidebarRightNavigationParams,
+  ): void {
+    actions.openContent(sessionId, {
+      kind: claim.kind,
+      contentId: claim.contentId,
+      title: claim.title,
+      ...placement.paneId === undefined ? {} : { paneId: placement.paneId },
+      ...placement.replaceTab === undefined ? {} : { replaceTab: placement.replaceTab },
+      ...placement.revealIfOpened === undefined ? {} : { revealIfOpened: placement.revealIfOpened },
+    }, (tabId) => { this.tabDomain.navigate(sessionId, tabId, { address, params }) })
+  }
+
+  /**
+   * Close one tab of the mounted session.
+   * @param tabId - the tab to close.
+   */
+  close(tabId: TabId): void {
+    const { sessionId, actions } = this.require()
+    actions.closeTab(sessionId, tabId)
+  }
+
+  /**
+   * The active tab of the active pane.
+   * @returns the record, or `undefined` with no mounted surface.
+   */
+  active(): TabRecord | undefined {
+    const layout = this.mounted()?.layout
+    if (layout === undefined) return undefined
+    const { activeTabId } = getPane(layout, layout.activePaneId)
+    return Object.values(layout.tabs).find(tab => tab.id === activeTabId)
+  }
+
+  /**
+   * Whether the column is currently showing its panel.
+   * @returns `true` while expanded; `false` while collapsed or with no mounted surface.
+   */
+  isExpanded(): boolean {
+    return this.mounted()?.layout.expanded ?? false
+  }
+
+  /** Collapse an expanded column, or expand a collapsed one. */
+  toggleExpanded(): void {
+    const { sessionId, actions } = this.require()
+    actions.toggleExpanded(sessionId)
+  }
+
+  /**
+   * Focus a tab and the pane holding it; a missing tab is left alone.
+   * @param tabId - the tab to focus.
+   */
+  focus(tabId: TabId): void {
+    const { sessionId, actions } = this.require()
+    if (this.mounted()?.layout.tabs[tabId] === undefined) return
+    actions.focusTab(sessionId, tabId)
+  }
+
+  /**
+   * Split a docked pane to its right when the budget and the room rule allow.
+   * @param paneId - the pane to split; defaults to the active docked pane.
+   * @returns the new pane's id, or `undefined` when nothing was split.
+   */
+  split(paneId?: PaneId): PaneId | undefined {
+    const { sessionId, actions, canSplitPane } = this.require()
+    const layout = this.mounted()?.layout
+    if (layout === undefined) return undefined
+    const target = paneId ?? activeDockPaneId(layout)
+    const node = layout.nodes[target]
+    if (node === undefined || node.kind !== 'pane' || node.host !== 'dock') return undefined
+    if (!canSplit(layout) || dockPaneIds(layout).length >= 2 || !canSplitPane(target)) return undefined
+    let created: PaneId | undefined
+    actions.splitPane(sessionId, target, (id) => { created = id })
+    return created
+  }
+
+  /**
+   * Take a docked tab out into a floating panel; a missing or floating tab is left alone.
+   * @param tabId - the tab to float.
+   * @param rect - the panel's rectangle; defaults to the cascade from the last panel.
+   */
+  float(tabId: TabId, rect?: FloatRect): void {
+    const { sessionId, actions } = this.require()
+    const layout = this.mounted()?.layout
+    if (layout === undefined || layout.tabs[tabId] === undefined) return
+    if (findTabPane(layout, tabId).host !== 'dock') return
+    actions.floatTab(sessionId, tabId, rect)
+  }
+
+  /**
+   * Return a floating panel's tab to the active docked pane; a missing or docked pane is left alone.
+   * @param paneId - the floating pane.
+   */
+  dock(paneId: PaneId): void {
+    const { sessionId, actions } = this.require()
+    const node = this.mounted()?.layout.nodes[paneId]
+    if (node === undefined || node.kind !== 'pane' || node.host !== 'float') return
+    actions.unfloatPane(sessionId, paneId)
+  }
+
+  /**
+   * Step the mounted session's surface back one intent.
+   *
+   * @internal Not part of the product: the sequence is an architectural fact
+   * with no user-facing control yet. Kept reachable for tests.
+   */
+  _undo(): void {
+    const { sessionId, actions } = this.require()
+    actions.undo(sessionId)
+  }
+
+  /**
+   * Step the mounted session's surface forward one intent.
+   *
+   * @internal See `_undo`.
+   */
+  _redo(): void {
+    const { sessionId, actions } = this.require()
+    actions.redo(sessionId)
+  }
+
+  /** The mounted session's surface; `undefined` without a seat or before its first open. */
+  private mounted(): SurfaceState | undefined {
+    const { binding } = this
+    return binding === undefined ? undefined : binding.surfaces[binding.sessionId]
+  }
+
+  /**
+   * The store actions a tab's own action on `sessionId` runs through: that
+   * session's adopted store. `undefined` — nothing to act on — for a session
+   * whose store was never minted or whose adoption was released.
+   */
+  private actionsFor(sessionId: SessionId): SurfaceActions | undefined {
+    return this.adopted.get(sessionId)?.store.actions
+  }
+
+  private require(): SidebarRightBinding {
+    // Reads answer for the no-session case (there is nothing expanded), but a
+    // write has no session to write to. Callers are UI gestures and tool
+    // results, both of which belong to a session that is on screen.
+    if (this.binding === undefined) {
+      throw new Error('sidebarRight: no session surface is mounted')
+    }
+    return this.binding
+  }
+}
diff --git a/packages/client/ui-sidebar-right/src/client/shell/ExpandButton.module.css b/packages/client/ui-sidebar-right/src/client/shell/ExpandButton.module.css
new file mode 100644
index 0000000000..d13872a336
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/client/shell/ExpandButton.module.css
@@ -0,0 +1,38 @@
+/*
+ * Sits in the conversation header's corner seat, level with the Session log
+ * control, so it takes that row's 32px height and the same hover fill; square
+ * with the header's corner radius rather than a pill, because it is an icon
+ * button, not a labelled one. The placeholder is the same box with nothing in
+ * it, so the seat's width holds while the panel is shown.
+ */
+.placeholder {
+  display: inline-block;
+  flex: none;
+  width: 32px;
+  height: 32px;
+}
+
+.button {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  padding: 0;
+  color: var(--dsw-alias-label-secondary);
+  background: transparent;
+  border: none;
+  border-radius: 8px;
+  cursor: pointer;
+}
+
+.button:hover {
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+/* The left sidebar's panel icon, mirrored: the divider moves to the right side. */
+.icon {
+  transform: scaleX(-1);
+}
diff --git a/packages/client/ui-sidebar-right/src/client/shell/ExpandButton.tsx b/packages/client/ui-sidebar-right/src/client/shell/ExpandButton.tsx
new file mode 100644
index 0000000000..a106bba675
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/client/shell/ExpandButton.tsx
@@ -0,0 +1,48 @@
+/**
+ * The way into a hidden panel: one button in the conversation header's corner
+ * seat, shown only while the panel is collapsed.
+ *
+ * It lives in the conversation's own header rather than in the frame's right
+ * column so that a collapsed Sidebar costs the conversation nothing — no rail,
+ * no width, and the transcript's scrollbar stays at the column's edge. The
+ * corner seat is its own, past the utilities' edge, so the button neither joins
+ * the utilities row nor moves it: while the panel is shown this renders a
+ * same-size placeholder, and the seat's width stays reserved. It shares the
+ * panel's per-session store, which the slot runtime allows because both seats
+ * are session-scoped.
+ *
+ * The glyph is the left sidebar's collapse icon mirrored: the same affordance,
+ * on the other edge.
+ */
+import type { ReactNode } from 'react'
+import { IconPanelLeftOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { PropsLocale, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots'
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { createSidebarRightStore } from '../stores.ts'
+import css from './ExpandButton.module.css'
+
+/** The button's props: the header corner seat, the shared store, and copy. */
+export type ExpandButtonProps =
+  & PropsRuntime<'conversation.session.header.corner'>
+  & PropsStore<ReturnType<typeof createSidebarRightStore>>
+  & PropsLocale<'sidebarRight'>
+
+/** The expand control while the panel is collapsed; its footprint while it is shown. */
+export function ExpandButton({ sessionId, useStore, actions, t }: ExpandButtonProps): ReactNode {
+  // A session with no surface yet is collapsed: the panel seat materializes the
+  // surface on its own mount, and until then there is nothing expanded.
+  const expanded = useStore(state => state.bySession[sessionId]?.layout.expanded ?? false)
+  if (expanded) return <span className={css.placeholder} aria-hidden data-sidebar-right-expand-placeholder />
+  return (
+    <button
+      type="button"
+      className={css.button}
+      aria-label={t('chrome.expand')}
+      title={t('chrome.expand')}
+      data-sidebar-right-expand
+      onClick={() => { actions.setExpanded(sessionId, true) }}
+    >
+      <IconPanelLeftOutline16 className={css.icon} />
+    </button>
+  )
+}
diff --git a/packages/client/ui-sidebar-right/src/client/shell/SidebarRight.module.css b/packages/client/ui-sidebar-right/src/client/shell/SidebarRight.module.css
new file mode 100644
index 0000000000..1940785098
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/client/shell/SidebarRight.module.css
@@ -0,0 +1,108 @@
+/*
+ * The Sidebar's own chrome only: the panel box, its two strip-end controls, and
+ * the placeholder tab bodies. Everything inside the split tree is styled by the
+ * docking kit; the expand button in the conversation header has its own sheet.
+ * Tokens only.
+ */
+
+/*
+ * One content tree uses the frame's width normally and fills the viewport in
+ * fullscreen. The frame retains a shown wide panel's track in both modes.
+ *
+ * Hidden, the panel is translated off the frame's right edge rather than
+ * unmounted, so showing and hiding are one slide in both presentations. The
+ * transform rides the same variables as the frame's track transition (ui-theme
+ * base.css); while squeezing, the panel's left edge and the conversation's right
+ * edge therefore travel together. Visibility flips after the slide so the box
+ * is out of reach once off-edge, and flips back before the slide starts.
+ *
+ * The normal panel is below frame overlays (20); fullscreen (40) covers the
+ * frame and remains below independently floating panels (60).
+ */
+.panel {
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  z-index: 10;
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  /* The same ground as the conversation: this is a column of the page, not a
+     raised surface. */
+  background: var(--dsw-alias-bg-base);
+  border-left: 0.5px solid var(--dsw-alias-border-l1);
+  transform: translateX(100%);
+  visibility: hidden;
+  transition:
+    transform var(--ds-transition-duration-slow) var(--ds-ease-in-out),
+    visibility 0s linear var(--ds-transition-duration-slow);
+}
+
+.panel[data-sidebar-right-open] {
+  transform: none;
+  visibility: visible;
+  transition: transform var(--ds-transition-duration-slow) var(--ds-ease-in-out);
+}
+
+.panel[data-sidebar-right-panel='fullscreen'] {
+  position: fixed;
+  inset: 0;
+  z-index: 40;
+  border: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .panel,
+  .panel[data-sidebar-right-open] {
+    transition: none;
+  }
+}
+
+.iconButton {
+  display: flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  color: var(--dsw-alias-label-secondary);
+  font-size: 14px;
+  line-height: 1;
+  background: transparent;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+}
+
+.iconButton:hover {
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.panelBody {
+  display: flex;
+  flex: 1 1 auto;
+  min-height: 0;
+}
+
+.unavailable {
+  margin: 0;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: var(--dsh-content-font-size-secondary, 13px);
+}
+
+/*
+ * Host for the portalled floating panels. Panels leave the column so they can
+ * cross it and the conversation, which puts them beside the app root rather than
+ * inside it — and a sibling of the root does not inherit its stacking, so the
+ * level is stated here. The value sits above the frame's own overlay layer;
+ * there is no z-index token layer to draw from yet.
+ */
+.floatHost {
+  position: fixed;
+  inset: 0;
+  z-index: 60;
+  pointer-events: none;
+}
diff --git a/packages/client/ui-sidebar-right/src/client/shell/SidebarRight.tsx b/packages/client/ui-sidebar-right/src/client/shell/SidebarRight.tsx
new file mode 100644
index 0000000000..ec0c9333e4
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/client/shell/SidebarRight.tsx
@@ -0,0 +1,423 @@
+/**
+ * The Sidebar's seat in the frame, and the panel it draws.
+ *
+ * The frame owns the right column's geometry; this package owns one content
+ * tree at the column width or fixed across the viewport. A shown wide panel
+ * retains its track in fullscreen, preserving the conversation width. Below
+ * 768px fullscreen is derived from viewport width, without changing manual mode.
+ *
+ * The panel stays mounted while collapsed, translated off the frame's right
+ * edge, so opening and closing are one gesture in both presentations: a slide
+ * from and to that edge. Normal presentation moves the frame's tracks with
+ * the panel. A fullscreen opening reserves its underlying track only after
+ * the panel covers the frame, without animating those hidden columns.
+ *
+ * The panel has no header of its own: its two controls — presentation switch
+ * and collapse — ride the docking kit's chrome seat at the end of the top-right
+ * pane's tab strip, so the strip is the panel's whole top edge. The way back in
+ * while collapsed is not here either: it is one button in the conversation
+ * header (`ExpandButton.tsx`), because it exists only while this panel is
+ * hidden. Floating panels portal out because they must cross the column and the
+ * conversation, and the kit already positions them in viewport coordinates.
+ *
+ * Tab bodies do not live here. Each one is a registration under its type's kind,
+ * dispatched through the keyed `sidebar.right.pane.tab` seat (and a live chip
+ * title through `sidebar.right.pane.tab.title`), so a new tab type needs no edit
+ * to this file. What a body receives beyond the record — navigation, lifetime
+ * signal, actions — is read through the slot-owned useTabInfo hook. The Tab
+ * domain follows each session's store commits, including sessions off screen.
+ */
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react'
+import type { ReactNode, RefObject } from 'react'
+import { createPortal } from 'react-dom'
+import type {
+  HostObservable, InjectFace, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore,
+} from '@deepseek-ai/dsh-client-ui-slots'
+// The frame declares the `rightbar` seat this component fills.
+import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
+import type { DockIntents, DockMode, FloatRect, TabId, TabRecord, TabRenderer } from '@deepseek-ai/dsh-client-ui-dockkit'
+import { canSplit, dockPaneIds, DockSurface, findPaneContentTab, FloatLayer } from '@deepseek-ai/dsh-client-ui-dockkit'
+import type { HalvesFit, LayoutState, PaneId } from '@deepseek-ai/dsh-client-ui-dockkit'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { GUIDE_KIND, pageAddress } from '../contract/seed.ts'
+import { dockLabels } from '../labels.ts'
+import type { SidebarRightOpenTabOptions } from '../service.ts'
+import type { SidebarRightTabDefinition } from '../tab-registry.ts'
+import type { createSidebarRightStore, SurfaceState } from '../stores.ts'
+import type { TabOccurrence } from '../tab-domain.ts'
+import type { SidebarRightTabNavigation } from '../contract/slots.ts'
+import type { TabHookContext } from '../tab-info.ts'
+import css from './SidebarRight.module.css'
+
+/** The store share the seat receives. */
+type Store = PropsStore<ReturnType<typeof createSidebarRightStore>>
+
+/** The child seats this component renders. */
+type Children = PropsRenderSlots<'sidebar.right.pane.tab' | 'sidebar.right.pane.tab.title' | 'sidebar.right.tab.menu.item'>
+
+/** What the panel reports to the frame: drawn or not, and whether it wants a track. */
+export interface SidebarRightPresentation {
+  /** Whether the panel is drawn at all. */
+  readonly shown: boolean
+  /** Whether the drawn panel wants the conversation to make room for it. */
+  readonly track: boolean
+  /** Whether the panel fills the viewport, independently of its retained track. */
+  readonly fullscreen: boolean
+}
+
+/** What this package needs from its host beyond the framework shares. */
+export interface SidebarRightInjected {
+  /**
+   * Report the panel's presentation to the frame.
+   *
+   * The frame sizes the track and places the resize handle; this only tells it
+   * the composition of the facts this package owns, and is called whenever that
+   * composition changes.
+   */
+  readonly syncPresentation: (presentation: SidebarRightPresentation) => void
+  /**
+   * Publish this seat's session, actions, and the store's surfaces to `ctx.sidebarRight`.
+   *
+   * The service is root-scoped and cannot read a per-entry store, so the only
+   * honest source is the mounted seat. Held for as long as the seat is mounted.
+   * @param binding - what a command needs to act on this session, and what a tab's own action needs to act on its.
+   * @returns a release callback.
+   */
+  readonly bindService: (binding: {
+    sessionId: SessionId
+    actions: Store['actions']
+    /** Every session's surface as last committed; the mounted one is `surfaces[sessionId]`. */
+    surfaces: Readonly<Record<string, SurfaceState>>
+    /** The room rule's verdict for a docked pane, as the kit last measured it. */
+    canSplitPane: (paneId: PaneId) => boolean
+  }) => () => void
+  /**
+   * The navigation face's `openTab`, for the strip's add control: a new tab is
+   * the guide opened by kind, through the same path as every other open.
+   */
+  readonly openTab: (kind: string, options?: SidebarRightOpenTabOptions) => void
+  readonly hooks: {
+    readonly tabTypes: HostObservable<readonly SidebarRightTabDefinition[]>
+  }
+  readonly keyedHooks: {
+    readonly tabNavigation: (key: string) => HostObservable<SidebarRightTabNavigation>
+  }
+  /** Read a committed record's lifetime; never creates an occurrence. */
+  readonly occurrence: (tab: Pick<TabRecord, 'id'>) => TabOccurrence
+}
+
+/** The column seat's props: session scope, so the session arrives as a standard prop. */
+export type RightbarSeatProps =
+  & PropsRuntime<'rightbar'>
+  & Children
+  & Store
+  & PropsLocale<'sidebarRight'>
+  & InjectFace<SidebarRightInjected>
+
+/** Everything the panel needs, already bound to one session. */
+interface PanelProps {
+  readonly sessionId: SessionId
+  readonly surface: SurfaceState
+  readonly actions: Store['actions']
+  readonly t: RightbarSeatProps['t']
+  readonly renderSlot: Children['renderSlot']
+  readonly openTab: SidebarRightInjected['openTab']
+  readonly useTabTypes: RightbarSeatProps['useTabTypes']
+  readonly useTabNavigation: RightbarSeatProps['useTabNavigation']
+  readonly useStore: Store['useStore']
+  readonly occurrence: SidebarRightInjected['occurrence']
+  readonly fullscreen: boolean
+  readonly autoFullscreen: boolean
+  /** Receives the kit's room-rule readings for the service's `split`. */
+  readonly reportRoom: (fits: ReadonlyMap<PaneId, HalvesFit>) => void
+}
+
+/** The guide tab one pane holds, if any: a pane holds at most one. */
+function guideIn(layout: LayoutState, paneId: PaneId): TabId | undefined {
+  return findPaneContentTab(layout, paneId, pageAddress(GUIDE_KIND), GUIDE_KIND)
+}
+
+/**
+ * Build the kit's intent face for one session out of the store's actions.
+ * @param sessionId - the session the seat draws; every action is bound to it.
+ * @param actions - the seat's bound store actions.
+ * @param openTab - the navigation face's `openTab`, which the strip's add control asks for a guide through.
+ * @returns the intents the kit reports gestures to.
+ */
+export function intentsFor(sessionId: SessionId, actions: Store['actions'], openTab: PanelProps['openTab']): DockIntents {
+  return {
+    focusTab: (tabId) => { actions.focusTab(sessionId, tabId) },
+    focusPane: (paneId) => { actions.focusPane(sessionId, paneId) },
+    splitPane: (paneId) => { actions.splitPane(sessionId, paneId) },
+    // The guide is unique per pane: the control is drawn only while its pane
+    // holds none (`canAddTab` below) and asks for one there without regard to
+    // guides in other panes; the store settles the open on a guide the pane
+    // already holds, so the ask is idempotent all the same.
+    addTab: (paneId) => { openTab(GUIDE_KIND, { paneId, revealIfOpened: false }) },
+    closeTab: (tabId) => { actions.closeTab(sessionId, tabId) },
+    duplicateTab: (tabId) => { actions.duplicateTab(sessionId, tabId) },
+    floatTab: (tabId, rect?: FloatRect) => { actions.floatTab(sessionId, tabId, rect) },
+    unfloatPane: (paneId) => { actions.unfloatPane(sessionId, paneId) },
+    placeTab: (tabId, toPaneId, index) => { actions.placeTab(sessionId, tabId, toPaneId, index) },
+    dropTab: (tabId, paneId, zone) => { actions.dropTab(sessionId, tabId, paneId, zone) },
+    moveFloat: (paneId, x, y) => { actions.moveFloat(sessionId, paneId, x, y) },
+    resizeFloat: (paneId, rect) => { actions.resizeFloat(sessionId, paneId, rect) },
+    resizeSplit: (splitId, sizes) => { actions.resizeSplit(sessionId, splitId, sizes) },
+  }
+}
+
+/** One tab's slot dispatch: which seat, and what to render when no type registered. */
+interface TabSlotProps extends Pick<PanelProps, 'renderSlot' | 'occurrence' | 'useTabTypes' | 'useTabNavigation' | 'useStore' | 'fullscreen'> {
+  readonly tab: TabRecord
+  readonly seat: 'sidebar.right.pane.tab' | 'sidebar.right.pane.tab.title'
+  readonly fallback: ReactNode
+}
+
+/**
+ * Dispatch one tab's body or title with stable framework hooks and record lifetime.
+ */
+function TabSlot({
+  renderSlot, occurrence, useTabTypes, useTabNavigation, useStore, fullscreen, tab, seat, fallback,
+}: TabSlotProps): ReactNode {
+  const { signal, tabActions } = occurrence(tab)
+  const definition = useTabTypes(types => types.find(definition => definition.kind === tab.kind))
+  const hookContext = useMemo((): TabHookContext => ({
+    tabId: tab.id,
+    title: seat === 'sidebar.right.pane.tab.title',
+    fullscreen,
+    signal,
+    actions: tabActions,
+    useStore,
+    useTabNavigation,
+  }), [tab.id, seat, fullscreen, signal, tabActions, useStore, useTabNavigation])
+  return renderSlot(seat, {}, { entryKey: definition?.id ?? tab.kind, fallback, hookContext })
+}
+
+/**
+ * Dispatch a tab's body to its registered type.
+ *
+ * A kind with no registrant is a real state, not a defect: a session log can
+ * carry a tab whose type shipped in a plugin that is no longer mounted. Saying so
+ * is better than an empty pane.
+ */
+function bodiesFor(panel: PanelProps): TabRenderer {
+  const { t, ...rest } = panel
+  // Keyed by record: the kit draws one body per pane in one place, and the
+  // keyed slot below keys on the type, so two tabs of one kind would otherwise
+  // share a component instance and its local state (a scroll position, a ref).
+  return tab => (
+    <TabSlot
+      key={tab.id}
+      {...rest}
+      tab={tab}
+      seat="sidebar.right.pane.tab"
+      fallback={<p className={css.unavailable} data-sidebar-right-unavailable>{t('tab.unavailable')}</p>}
+    />
+  )
+}
+
+/** Dispatch a tab's title to its registered type; without one the chip shows the title captured at open time. */
+function titlesFor(panel: PanelProps): TabRenderer {
+  return tab => <TabSlot key={tab.id} {...panel} tab={tab} seat="sidebar.right.pane.tab.title" fallback={tab.title} />
+}
+
+/** Expand-to-viewport glyph. */
+function FullscreenGlyph(): ReactNode {
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="none" aria-hidden="true">
+      <path d="M5 1.5H1.5V5M9 1.5h3.5V5M1.5 9v3.5H5M12.5 9v3.5H9" stroke="currentColor" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+/** Restore-from-fullscreen glyph. */
+function ExitFullscreenGlyph(): ReactNode {
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="none" aria-hidden="true">
+      <path d="M1.5 5H5V1.5M9 1.5V5h3.5M1.5 9H5v3.5M9 12.5V9h3.5" stroke="currentColor" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+/** The collapse glyph. */
+function CloseGlyph(): ReactNode {
+  return (
+    <svg width="12" height="12" viewBox="0 0 12 12" fill="none" aria-hidden="true">
+      <path d="M2 2l8 8M10 2l-8 8" stroke="currentColor" strokeWidth="1.3" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+/** The panel's two controls, placed by the kit at the top-right pane's strip end. */
+function PanelChrome({ sessionId, fullscreen, autoFullscreen, actions, t }: Pick<PanelProps, 'sessionId' | 'actions' | 't' | 'fullscreen' | 'autoFullscreen'>): ReactNode {
+  const next: DockMode = fullscreen ? 'push' : 'fullscreen'
+  return (
+    <>
+      <button
+        type="button"
+        className={css.iconButton}
+        aria-label={fullscreen ? t('chrome.exitFullscreen') : t('chrome.toFullscreen')}
+        title={fullscreen ? t('chrome.exitFullscreen') : t('chrome.toFullscreen')}
+        data-sidebar-right-mode={next}
+        onClick={() => {
+          if (fullscreen && autoFullscreen) actions.setExpanded(sessionId, false)
+          actions.setMode(sessionId, next)
+        }}
+      >
+        {fullscreen ? <ExitFullscreenGlyph /> : <FullscreenGlyph />}
+      </button>
+      <button
+        type="button"
+        className={css.iconButton}
+        aria-label={t('chrome.collapse')}
+        title={t('chrome.collapse')}
+        data-sidebar-right-toggle
+        onClick={() => { actions.toggleExpanded(sessionId) }}
+      >
+        <CloseGlyph />
+      </button>
+    </>
+  )
+}
+
+/**
+ * The panel: the docked surface with the two controls in its top-right strip,
+ * anchored to the frame's right edge and slid off it while collapsed.
+ */
+function SidebarPanel(panel: PanelProps & { width: number; panelRef: RefObject<HTMLDivElement> }): ReactNode {
+  const { sessionId, surface, actions, t, renderSlot, openTab, width, reportRoom, fullscreen, autoFullscreen, panelRef } = panel
+  const { expanded } = surface.layout
+  return (
+    <div
+      ref={panelRef}
+      className={css.panel}
+      style={{ width: fullscreen ? '100%' : width }}
+      data-sidebar-right-panel={fullscreen ? 'fullscreen' : 'push'}
+      data-sidebar-right-open={expanded || undefined}
+      // Off-edge is out of reach: the stylesheet's visibility flip takes the
+      // hidden panel out of the tab order, and this takes it out of the
+      // accessibility tree.
+      aria-hidden={!expanded || undefined}
+    >
+      <div className={css.panelBody}>
+        <DockSurface
+          state={surface.layout}
+          canSplit={canSplit(surface.layout) && dockPaneIds(surface.layout).length < 2}
+          hideSplitAtCapacity
+          dropZones="horizontal"
+          minPaneFraction={0.2}
+          canAddTab={paneId => guideIn(surface.layout, paneId) === undefined}
+          intents={intentsFor(sessionId, actions, openTab)}
+          labels={dockLabels(t)}
+          renderTab={bodiesFor(panel)}
+          renderTabTitle={titlesFor(panel)}
+          renderTabMenuItems={(tab, dismiss) =>
+            renderSlot('sidebar.right.tab.menu.item', { tab, dismiss })}
+          chrome={<PanelChrome sessionId={sessionId} fullscreen={fullscreen} autoFullscreen={autoFullscreen} actions={actions} t={t} />}
+          onRoom={reportRoom}
+        />
+      </div>
+    </div>
+  )
+}
+
+/** Portal the floating layer out of whichever seat rendered it. */
+function Floats(panel: PanelProps): ReactNode {
+  const { sessionId, surface, actions, t, openTab } = panel
+  if (surface.layout.floats.length === 0) return null
+  return createPortal(
+    <div className={css.floatHost} data-sidebar-right-float-host>
+      <FloatLayer
+        state={surface.layout}
+        intents={intentsFor(sessionId, actions, openTab)}
+        labels={dockLabels(t)}
+        renderTab={bodiesFor(panel)}
+        renderTabTitle={titlesFor(panel)}
+      />
+    </div>,
+    document.body,
+  )
+}
+
+/**
+ * The right column's occupant: the panel, anchored to the column's edge and
+ * shown or hidden by sliding, plus the floating layer. It is also where the
+ * frame learns the panel's presentation, and where `ctx.sidebarRight` learns
+ * which session it is acting on, because this is the seat that knows both.
+ */
+export function RightbarSeat({
+  sessionId, width, viewportWidth, canShow, useStore, actions, t, renderSlot, syncPresentation, bindService, openTab,
+  useTabTypes, useTabNavigation, occurrence,
+}: RightbarSeatProps): ReactNode {
+  // One store instance per session, so this map holds this session's surface.
+  // The binding published below serves the public face's commands on the
+  // mounted session; a tab's own actions route through the controller's
+  // adopted stores instead.
+  const surfaces = useStore(state => state.bySession)
+  const surface = surfaces[sessionId]
+  const shown = surface !== undefined && surface.layout.expanded
+  const autoFullscreen = viewportWidth < 768
+  const fullscreen = autoFullscreen || surface?.layout.mode === 'fullscreen'
+  const panelRef = useRef<HTMLDivElement | null>(null)
+  // The kit's room-rule readings, kept in a ref: the service reads them at
+  // call time through the binding, and a reading never re-renders anything.
+  const room = useRef<ReadonlyMap<PaneId, HalvesFit>>(new Map())
+  const reportRoom = useCallback((fits: ReadonlyMap<PaneId, HalvesFit>): void => { room.current = fits }, [])
+  const track = shown && !autoFullscreen
+
+  useEffect(() => {
+    if (surface === undefined) actions.open(sessionId)
+  }, [actions, sessionId, surface])
+
+  useLayoutEffect(() => {
+    if (shown && !fullscreen && !canShow) actions.setExpanded(sessionId, false)
+  }, [actions, sessionId, shown, fullscreen, canShow])
+
+  // Fullscreen leaves the previous column report in force until its own slide
+  // completes. Normal presentation and zero-duration transitions report before paint.
+  useLayoutEffect(() => {
+    let disposed = false
+    const reportWhenCovered = (): void => {
+      if (disposed) return
+      // A shown panel renders unconditionally and attaches its ref before this effect.
+      const entering = shown && fullscreen
+        ? (panelRef.current as HTMLDivElement).getAnimations().filter(animation =>
+          'transitionProperty' in animation && animation.transitionProperty === 'transform'
+          && animation.playState !== 'finished' && animation.playState !== 'idle')
+        : []
+      if (entering.length === 0) {
+        syncPresentation({ shown, track, fullscreen })
+        return
+      }
+      // Cancellation can replace the transition or remove it for reduced motion.
+      void Promise.allSettled(entering.map(animation => animation.finished)).then(reportWhenCovered)
+    }
+    reportWhenCovered()
+    return () => { disposed = true }
+  }, [sessionId, shown, track, fullscreen, syncPresentation])
+  // Leaving is part of that report: a seat that unmounts with its session must
+  // hand the track back rather than leave one sized for a surface nobody draws.
+  useLayoutEffect(() => () => { syncPresentation({ shown: false, track: false, fullscreen: false }) }, [syncPresentation])
+
+  // Republished on every committed change: the service's readers answer from the
+  // last commit, and its commands act on the session actually on screen.
+  useEffect(
+    () => bindService({ sessionId, actions, surfaces, canSplitPane: paneId => room.current.get(paneId)?.row !== false }),
+    [bindService, sessionId, actions, surfaces],
+  )
+  // The Tab domain is not synced here: the controller adopted this session's
+  // store as the runtime minted it and reconciles on the store's own commits,
+  // on screen or not.
+
+  if (surface === undefined) return null
+  const panel: PanelProps = {
+    sessionId, actions, t, renderSlot, surface, openTab, useTabTypes, useTabNavigation, useStore, occurrence,
+    fullscreen, autoFullscreen, reportRoom,
+  }
+  return (
+    <>
+      <SidebarPanel {...panel} width={width} panelRef={panelRef} />
+      <Floats {...panel} />
+    </>
+  )
+}
diff --git a/packages/client/ui-sidebar-right/src/client/stores.ts b/packages/client/ui-sidebar-right/src/client/stores.ts
new file mode 100644
index 0000000000..2301388974
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/client/stores.ts
@@ -0,0 +1,353 @@
+/**
+ * The store shell over the docking kit: one surface per session, held as plain
+ * data so the kit's pure functions are the only thing that ever computes a
+ * layout.
+ *
+ * Every action follows the same steps — mint the ids the intent needs, ask the
+ * kit's planner what operations carry it out, let the settle planner keep every
+ * pane populated, record it all as one history entry — and then assigns the
+ * session's whole surface back in one go. Nothing here reaches into a draft to
+ * edit a layout in place, which is what keeps the kit testable without a store
+ * and keeps snapshot identity honest.
+ *
+ * The settle step is this product's rule, not the kit's: a docked pane never
+ * stays empty, and the last pane reseeds the guide tab, so there is always at
+ * least one tab to look at.
+ *
+ * A focus that changes nothing — a tab already active in its already-active
+ * pane, a pane already active — plans nothing and records nothing, whoever
+ * asks: the kit's chip click and `ctx.sidebarRight.focus` alike.
+ *
+ * So is the guide's uniqueness: a pane holds at most one guide tab. Opening the
+ * guide into a pane that has one focuses it, and a guide dragged, dropped, or
+ * docked into such a pane merges into it — the arriving guide closes and the
+ * pane's own is focused. The kit plans none of this; it is decided here before
+ * its planners run.
+ */
+import { defineStore, type EngineStoreHandle } from '@deepseek-ai/dsh-client-store'
+import type {
+  DockMode, DockZone, FloatRect, History, LayoutOp, LayoutState, Mint, PaneId, SplitId, TabId,
+} from '@deepseek-ai/dsh-client-ui-dockkit'
+import {
+  activeDockPaneId, createInitialState, dockPaneIds, EMPTY_HISTORY, findPaneContentTab, findTabPane,
+  planDropTab, planDuplicateTab, planFloatTab, planOpenContent, planPlaceTab, planResizeSplit, planSetExpanded,
+  planSetMode, planSettle, planSplitPane, planUnfloatPane, record, replay, stepBack, stepForward,
+} from '@deepseek-ai/dsh-client-ui-dockkit'
+import { GUIDE_KIND, makeGuideTab, pageAddress } from './contract/seed.ts'
+
+/** One session's docking surface: the layout, its sequence, and the id counter. */
+export interface SurfaceState {
+  readonly layout: LayoutState
+  readonly history: History
+  /** How many ids this surface has minted; carried so replay stays reproducible. */
+  readonly minted: number
+}
+
+/**
+ * Every session's surface, keyed by session id.
+ *
+ * Written mutable because an action receives this type as its draft; the
+ * immutability that matters is behavioural — actions only ever assign a whole
+ * new map, never reach into one.
+ */
+export interface SidebarRightState {
+  bySession: Record<string, SurfaceState>
+}
+
+/** A planner call, as the store needs it: state and a mint in, operations out. */
+type SurfacePlan = (state: LayoutState, mint: Mint) => readonly LayoutOp[]
+
+/**
+ * What the navigation controller asks the store to open, the address already
+ * claimed. Placement is by `replaceTab` first, then `paneId`, then the active pane.
+ */
+export interface OpenContentIntent {
+  readonly kind: string
+  readonly contentId: string
+  readonly title: string
+  /** Land a new tab in this pane. */
+  readonly paneId?: PaneId
+  /** Take this tab's pane and slot, and close it in the same entry. */
+  readonly replaceTab?: TabId
+  /** `false` opens another tab even when the identity is already shown; defaults to `true`. */
+  readonly revealIfOpened?: boolean
+}
+
+/** A mint that counts, so the surface can carry its position forward. */
+function counting(from: number): { mint: Mint; used: () => number } {
+  let counter = from
+  // The mint is where a string becomes a branded id: the prefix names the kind,
+  // the counter keeps every id of this surface unique.
+  const mint = ((prefix: string): string => {
+    counter += 1
+    return `${prefix}${counter}`
+  }) as Mint
+  return { mint, used: () => counter }
+}
+
+/**
+ * The surface a session starts with: collapsed, one pane, one guide tab.
+ * @param seedTitle - the guide type's display name at mint time.
+ * @returns the initial surface.
+ */
+export function createSurface(seedTitle: () => string): SurfaceState {
+  const counter = counting(0)
+  return {
+    layout: createInitialState({ next: counter.mint }, id => makeGuideTab(id, seedTitle())),
+    history: EMPTY_HISTORY,
+    minted: counter.used(),
+  }
+}
+
+/** The guide tab a pane holds, if any. */
+function paneGuide(state: LayoutState, paneId: PaneId): TabId | undefined {
+  return findPaneContentTab(state, paneId, pageAddress(GUIDE_KIND), GUIDE_KIND)
+}
+
+/** Whether a tab is the guide, which a pane holds at most once and which is therefore never copied. */
+function isGuide(state: LayoutState, tabId: TabId): boolean {
+  return state.tabs[tabId]?.kind === GUIDE_KIND
+}
+
+/** Focus a tab: nothing to plan while it is its pane's active tab and its pane is the active one. */
+function planFocusTab(state: LayoutState, tabId: TabId): readonly LayoutOp[] {
+  const pane = findTabPane(state, tabId)
+  return pane.activeTabId === tabId && state.activePaneId === pane.id ? [] : [{ type: 'focusTab', tabId }]
+}
+
+/** Focus a pane: nothing to plan while it is the active one. */
+function planFocusPane(state: LayoutState, paneId: PaneId): readonly LayoutOp[] {
+  return state.activePaneId === paneId ? [] : [{ type: 'focusPane', paneId }]
+}
+
+/**
+ * Plan a tab's arrival in a docked pane: a guide arriving where one already is
+ * merges into it, anything else plans as the kit does.
+ * @param state - current layout.
+ * @param tabId - the arriving tab.
+ * @param toPaneId - the pane it arrives in.
+ * @param otherwise - the kit's plan for the move.
+ * @returns the operations.
+ */
+function arriving(state: LayoutState, tabId: TabId, toPaneId: PaneId, otherwise: () => readonly LayoutOp[]): readonly LayoutOp[] {
+  if (!isGuide(state, tabId)) return otherwise()
+  const existing = paneGuide(state, toPaneId)
+  if (existing === undefined || existing === tabId) return otherwise()
+  return [{ type: 'closeTab', tabId }, { type: 'focusTab', tabId: existing }]
+}
+
+/**
+ * Run one planner against a surface, settle what it left behind, and record the
+ * whole intent as one history entry.
+ * @param surface - the session's current surface.
+ * @param plan - the kit planner to consult.
+ * @param seedTitle - the guide type's display name, for a reseeded root pane.
+ * @returns the next surface, or the same one when the intent changes nothing.
+ */
+function advance(surface: SurfaceState, plan: SurfacePlan, seedTitle: () => string): SurfaceState {
+  const counter = counting(surface.minted)
+  const planned = plan(surface.layout, counter.mint)
+  if (planned.length === 0) return surface
+  // The settle planner reads the state the intent produces, so it is applied
+  // to a scratch copy first; the record then applies both parts once.
+  const after = replay(surface.layout, planned)
+  const settled = planSettle(after, counter.mint, id => makeGuideTab(id, seedTitle()))
+  const stepped = record(surface.history, surface.layout, [...planned, ...settled])
+  return { layout: stepped.state, history: stepped.history, minted: counter.used() }
+}
+
+/**
+ * Replace one session's surface, leaving every other session by reference.
+ *
+ * A session with no surface yet gets its initial one even when the intent
+ * changes nothing: materializing is itself the change.
+ */
+function seat(
+  state: SidebarRightState,
+  sessionId: string,
+  seedTitle: () => string,
+  next: (surface: SurfaceState) => SurfaceState,
+): Record<string, SurfaceState> {
+  const existing = state.bySession[sessionId]
+  const updated = next(existing ?? createSurface(seedTitle))
+  return updated === existing ? state.bySession : { ...state.bySession, [sessionId]: updated }
+}
+
+/** Declared write set; each entry is one settled intent. */
+type SidebarRightActions = {
+  open: (draft: SidebarRightState, sessionId: string) => void
+  setExpanded: (draft: SidebarRightState, sessionId: string, expanded: boolean) => void
+  toggleExpanded: (draft: SidebarRightState, sessionId: string) => void
+  setMode: (draft: SidebarRightState, sessionId: string, mode: DockMode) => void
+  splitPane: (draft: SidebarRightState, sessionId: string, paneId?: PaneId, settled?: (paneId: PaneId) => void) => void
+  openContent: (
+    draft: SidebarRightState,
+    sessionId: string,
+    intent: OpenContentIntent,
+    settled: (tabId: TabId) => void,
+  ) => void
+  duplicateTab: (draft: SidebarRightState, sessionId: string, tabId: TabId) => void
+  closeTab: (draft: SidebarRightState, sessionId: string, tabId: TabId) => void
+  focusTab: (draft: SidebarRightState, sessionId: string, tabId: TabId) => void
+  focusPane: (draft: SidebarRightState, sessionId: string, paneId: PaneId) => void
+  placeTab: (draft: SidebarRightState, sessionId: string, tabId: TabId, toPaneId: PaneId, index: number) => void
+  dropTab: (draft: SidebarRightState, sessionId: string, tabId: TabId, paneId: PaneId, zone: DockZone) => void
+  floatTab: (draft: SidebarRightState, sessionId: string, tabId: TabId, rect?: FloatRect) => void
+  unfloatPane: (draft: SidebarRightState, sessionId: string, paneId: PaneId) => void
+  moveFloat: (draft: SidebarRightState, sessionId: string, paneId: PaneId, x: number, y: number) => void
+  resizeFloat: (draft: SidebarRightState, sessionId: string, paneId: PaneId, rect: FloatRect) => void
+  resizeSplit: (draft: SidebarRightState, sessionId: string, splitId: SplitId, sizes: readonly number[]) => void
+  undo: (draft: SidebarRightState, sessionId: string) => void
+  redo: (draft: SidebarRightState, sessionId: string) => void
+}
+
+/** One direction through the recorded sequence. */
+type HistoryStepper =
+  (history: History, state: LayoutState) => { history: History; state: LayoutState } | undefined
+
+/** Step a surface through the history in one direction. */
+function stepped(surface: SurfaceState, step: HistoryStepper): SurfaceState {
+  const moved = step(surface.history, surface.layout)
+  return moved === undefined ? surface : { ...surface, layout: moved.state, history: moved.history }
+}
+
+/**
+ * Create the Sidebar store handle.
+ *
+ * The seed title arrives as a thunk rather than a string: a pane is seeded
+ * whenever one is created, which can be long after the store was built and in a
+ * language the user has since changed to.
+ * @param seedTitle - the guide type's display name, read at each mint.
+ * @returns the handle (spec, type, identity, and factory in one).
+ */
+export function createSidebarRightStore(
+  seedTitle: () => string,
+): EngineStoreHandle<SidebarRightState, SidebarRightActions> {
+  return defineStore({
+    init: (): SidebarRightState => ({ bySession: {} }),
+    actions: {
+      // Materialize a session's surface without changing it, so the first read
+      // after a session switch sees the collapsed default rather than nothing.
+      open: (d, sessionId: string) => { d.bySession = seat(d, sessionId, seedTitle, surface => surface) },
+      setExpanded: (d, sessionId: string, expanded: boolean) => {
+        d.bySession = seat(d, sessionId, seedTitle, s => advance(s, state => planSetExpanded(state, expanded), seedTitle))
+      },
+      toggleExpanded: (d, sessionId: string) => {
+        d.bySession = seat(d, sessionId, seedTitle, s => advance(s, state => planSetExpanded(state, !state.expanded), seedTitle))
+      },
+      // Switching presentation is recorded like any other change, so stepping
+      // back through the sequence puts the surface back the way it was drawn.
+      setMode: (d, sessionId: string, mode: DockMode) => {
+        d.bySession = seat(d, sessionId, seedTitle, s => advance(s, state => planSetMode(state, mode), seedTitle))
+      },
+      // `settled` reports the pane the split created, synchronously, because
+      // actions return nothing; it is not called when nothing was split.
+      splitPane: (d, sessionId: string, paneId?: PaneId, settled?: (paneId: PaneId) => void) => {
+        d.bySession = seat(d, sessionId, seedTitle, (s) => {
+          const next = advance(s, (state, mint) => dockPaneIds(state).length >= 2
+            ? []
+            : planSplitPane(state, mint, paneId, id => makeGuideTab(id, seedTitle())), seedTitle)
+          if (settled !== undefined && next !== s) {
+            const before = new Set(dockPaneIds(s.layout))
+            for (const id of dockPaneIds(next.layout)) {
+              if (!before.has(id)) settled(id)
+            }
+          }
+          return next
+        })
+      },
+      // One entry carries the whole open: revealing the column (an open behind
+      // a collapsed panel is not an open), focusing or seating the tab, and
+      // closing the tab it replaces. `settled` reports the tab the planner
+      // landed on, synchronously, because actions return nothing.
+      openContent: (d, sessionId: string, intent, settled) => {
+        d.bySession = seat(d, sessionId, seedTitle, s => advance(s, (state, mint) => {
+          const { kind, contentId, title, replaceTab: replace } = intent
+          const ops: LayoutOp[] = [...planSetExpanded(state, true)]
+          // A replaced tab lends its pane and slot; one that floats cannot (a
+          // floating pane holds one tab), so the new tab lands as if unplaced.
+          const replaced = replace === undefined ? undefined : findTabPane(state, replace)
+          const lent = replace !== undefined && replaced !== undefined && replaced.host === 'dock' ? replaced : undefined
+          const paneId = lent?.id ?? intent.paneId
+          const index = lent === undefined || replace === undefined ? undefined : lent.tabs.indexOf(replace)
+          // The guide is unique per pane: the pane it would land in may already
+          // hold one, which is then the tab this open settles on.
+          const held = kind === GUIDE_KIND ? paneGuide(state, paneId ?? activeDockPaneId(state)) : undefined
+          const planned = held !== undefined
+            ? { ops: [{ type: 'focusTab' as const, tabId: held }], tabId: held }
+            : planOpenContent(state, mint, {
+              kind,
+              contentId,
+              title,
+              ...paneId === undefined ? {} : { paneId },
+              ...index === undefined ? {} : { index },
+              ...intent.revealIfOpened === undefined ? {} : { revealIfOpened: intent.revealIfOpened },
+            })
+          ops.push(...planned.ops)
+          if (replace !== undefined && replace !== planned.tabId) ops.push({ type: 'closeTab', tabId: replace })
+          settled(planned.tabId)
+          return ops
+        }, seedTitle))
+      },
+      // The guide is never copied: the copy would sit beside it in the same pane.
+      duplicateTab: (d, sessionId: string, tabId: TabId) => {
+        d.bySession = seat(d, sessionId, seedTitle, s =>
+          advance(s, (state, mint) => isGuide(state, tabId) ? [] : planDuplicateTab(state, mint, tabId).ops, seedTitle))
+      },
+      // A tab already gone — closed twice by a racing callback and the user — is
+      // left alone rather than handed to the kit, which refuses an unknown tab.
+      closeTab: (d, sessionId: string, tabId: TabId) => {
+        d.bySession = seat(d, sessionId, seedTitle, s =>
+          advance(s, state => state.tabs[tabId] === undefined ? [] : [{ type: 'closeTab', tabId }], seedTitle))
+      },
+      focusTab: (d, sessionId: string, tabId: TabId) => {
+        d.bySession = seat(d, sessionId, seedTitle, s => advance(s, state => planFocusTab(state, tabId), seedTitle))
+      },
+      focusPane: (d, sessionId: string, paneId: PaneId) => {
+        d.bySession = seat(d, sessionId, seedTitle, s => advance(s, state => planFocusPane(state, paneId), seedTitle))
+      },
+      placeTab: (d, sessionId: string, tabId: TabId, toPaneId: PaneId, index: number) => {
+        d.bySession = seat(d, sessionId, seedTitle, s =>
+          advance(s, state => arriving(state, tabId, toPaneId, () => planPlaceTab(state, tabId, toPaneId, index)), seedTitle))
+      },
+      // Only a centre release lands in the target pane; an edge release makes a
+      // new pane, where nothing can already be.
+      dropTab: (d, sessionId: string, tabId: TabId, paneId: PaneId, zone: DockZone) => {
+        d.bySession = seat(d, sessionId, seedTitle, s => advance(s, (state, mint) => {
+          if (zone === 'top' || zone === 'bottom') return []
+          if (zone !== 'center' && dockPaneIds(state).length >= 2) return []
+          const plan = (): readonly LayoutOp[] => planDropTab(state, mint, tabId, paneId, zone)
+          return zone === 'center' ? arriving(state, tabId, paneId, plan) : plan()
+        }, seedTitle))
+      },
+      floatTab: (d, sessionId: string, tabId: TabId, rect?: FloatRect) => {
+        d.bySession = seat(d, sessionId, seedTitle, s =>
+          advance(s, (state, mint) => planFloatTab(state, mint, tabId, rect).ops, seedTitle))
+      },
+      // A floating pane holds one tab; docking it back lands in the active
+      // docked pane, and only a guide is subject to the merge rule there.
+      unfloatPane: (d, sessionId: string, paneId: PaneId) => {
+        d.bySession = seat(d, sessionId, seedTitle, s => advance(s, (state) => {
+          const guide = paneGuide(state, paneId)
+          const plan = (): readonly LayoutOp[] => planUnfloatPane(state, paneId)
+          return guide === undefined ? plan() : arriving(state, guide, activeDockPaneId(state), plan)
+        }, seedTitle))
+      },
+      moveFloat: (d, sessionId: string, paneId: PaneId, x: number, y: number) => {
+        d.bySession = seat(d, sessionId, seedTitle, s => advance(s, () => [{ type: 'moveFloat', paneId, x, y }], seedTitle))
+      },
+      resizeFloat: (d, sessionId: string, paneId: PaneId, rect: FloatRect) => {
+        d.bySession = seat(d, sessionId, seedTitle, s => advance(s, () => [{ type: 'resizeFloat', paneId, rect }], seedTitle))
+      },
+      resizeSplit: (d, sessionId: string, splitId: SplitId, sizes: readonly number[]) => {
+        d.bySession = seat(d, sessionId, seedTitle, s => advance(s, () => planResizeSplit(splitId, sizes, 0.2), seedTitle))
+      },
+      undo: (d, sessionId: string) => {
+        d.bySession = seat(d, sessionId, seedTitle, s => stepped(s, stepBack))
+      },
+      redo: (d, sessionId: string) => {
+        d.bySession = seat(d, sessionId, seedTitle, s => stepped(s, stepForward))
+      },
+    },
+  })
+}
diff --git a/packages/client/ui-sidebar-right/src/client/tab-domain.ts b/packages/client/ui-sidebar-right/src/client/tab-domain.ts
new file mode 100644
index 0000000000..53b259584e
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/client/tab-domain.ts
@@ -0,0 +1,184 @@
+/**
+ * The Tab domain: what a tab record carries that the layout does not.
+ *
+ * One `TabOccurrence` per open record, keyed by (session, tab id): where the
+ * tab was navigated to, an abort signal spanning the record's life, and the
+ * actions the tab may take on itself. Holding a record also pins its address in
+ * the resource model, so switching tabs unmounts a body without dropping its
+ * content.
+ *
+ * `sync` reconciles occurrences against one session's layout after every
+ * commit: a record that appeared is pinned, one that vanished (closed, or its
+ * open undone) is aborted and dropped. A record restored by undo is a new
+ * occurrence and is fetched again if the resource model already let it go. The
+ * controller syncs each session from that session's adopted store on every
+ * commit, on screen or not, so a record closed from another session's seat is
+ * aborted on that commit. The slot framework binds the navigation sources for
+ * each record's `useTabInfo` reader.
+ */
+import type { LayoutState, PaneId, TabId, TabRecord } from '@deepseek-ai/dsh-client-ui-dockkit'
+import { findTabPane } from '@deepseek-ai/dsh-client-ui-dockkit'
+import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-store'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { SidebarRightNavigationParams } from './contract/params.ts'
+import type { SidebarRightTabActions, SidebarRightTabNavigation, SidebarRightTabPlacement } from './contract/slots.ts'
+import type { SidebarRightOpenResourceOptions, SidebarRightOpenTabOptions, SidebarRightPlacement } from './service.ts'
+
+/**
+ * The navigation face a tab's actions call back into, aimed at the session the
+ * tab is in; nothing happens for a session whose store is not adopted.
+ */
+export interface SidebarRightNavigator {
+  /** Open a resource in one session; see `ISidebarRight.openResource`. */
+  openResourceIn(sessionId: SessionId, address: string, options?: SidebarRightOpenResourceOptions): void
+  /** Open a page type in one session; see `ISidebarRight.openTab`. */
+  openTabIn(sessionId: SessionId, kind: string, options?: SidebarRightOpenTabOptions): void
+  /** Close a tab of one session. */
+  closeIn(sessionId: SessionId, tabId: TabId): void
+}
+
+/** `ctx.resources.pin`: hold an address's content open for as long as `signal` lives. */
+export type PinResource = (address: string, signal: AbortSignal) => void
+
+/** What one open tab record holds beyond its layout entry. */
+export interface TabOccurrence {
+  readonly sessionId: SessionId
+  readonly tabId: TabId
+  /** Aborted when the record disappears or this package unloads. */
+  readonly signal: AbortSignal
+  /** The latest navigation aimed at the record; `set` on every `navigate`. */
+  readonly navigation: SnapshotStore<SidebarRightTabNavigation>
+  /** Stable for the occurrence's life, so a body may hold it. */
+  readonly tabActions: SidebarRightTabActions
+}
+
+/** An occurrence plus what only the domain touches. */
+interface Held extends TabOccurrence {
+  readonly controller: AbortController
+  /** The docked pane holding the record at the last sync; `undefined` while it floats or before any sync. */
+  paneId: PaneId | undefined
+  /** Whether the resource model has been asked to hold the address. */
+  pinned: boolean
+}
+
+/** Every session's occurrences. */
+export class TabDomain {
+  private readonly bySession = new Map<SessionId, Map<TabId, Held>>()
+
+  /**
+   * @param navigator - where tab actions go, aimed at the tab's session; the navigation controller.
+   * @param pin - `ctx.resources.pin`, called once per occurrence at its first sync.
+   */
+  constructor(
+    private readonly navigator: SidebarRightNavigator,
+    private readonly pin: PinResource,
+  ) {}
+
+  /**
+   * Reconcile one session's occurrences with its committed layout.
+   *
+   * Called by the seat after every commit, and only then: aborting a vanished
+   * record runs the types' cleanup, which writes their stores.
+   * @param sessionId - the session whose layout committed.
+   * @param layout - that session's layout as committed.
+   */
+  sync(sessionId: SessionId, layout: LayoutState): void {
+    const held = this.session(sessionId)
+    for (const [tabId, occurrence] of held) {
+      if (layout.tabs[tabId] !== undefined) continue
+      held.delete(tabId)
+      occurrence.controller.abort()
+    }
+    for (const tab of Object.values(layout.tabs)) {
+      const occurrence = held.get(tab.id) ?? this.hold(sessionId, tab.id, { address: tab.contentId, params: undefined, revision: 0 })
+      const pane = findTabPane(layout, tab.id)
+      occurrence.paneId = pane.host === 'dock' ? pane.id : undefined
+      if (occurrence.pinned) continue
+      occurrence.pinned = true
+      this.pin(occurrence.navigation.getSnapshot().address, occurrence.signal)
+    }
+  }
+
+  /**
+   * Read an occurrence created by navigation or committed-store reconciliation.
+   * @param sessionId - the session the record is in.
+   * @param tab - the record being drawn.
+   * @returns its occurrence.
+   * @throws when the record has not been reconciled or has disappeared.
+   */
+  occurrence(sessionId: SessionId, tab: Pick<TabRecord, 'id'>): TabOccurrence {
+    const occurrence = this.bySession.get(sessionId)?.get(tab.id)
+    if (occurrence === undefined) throw new Error(`sidebarRight: tab "${tab.id}" has no committed occurrence in session "${sessionId}"`)
+    return occurrence
+  }
+
+  /**
+   * Record that an `open` settled on a tab.
+   *
+   * A record the layout has not yet shown the seat gets its occurrence here, so
+   * the body's first render already carries the opener's `params`.
+   * @param sessionId - the session opened into.
+   * @param tabId - the tab the open settled on.
+   * @param target - the address and the opener's params.
+   */
+  navigate(sessionId: SessionId, tabId: TabId, target: { address: string; params: SidebarRightNavigationParams }): void {
+    const existing = this.session(sessionId).get(tabId)
+    if (existing === undefined) {
+      this.hold(sessionId, tabId, { ...target, revision: 1 })
+      return
+    }
+    existing.navigation.set({ ...target, revision: existing.navigation.getSnapshot().revision + 1 })
+  }
+
+  /** Abort every occurrence of every session; the package is unloading. */
+  dispose(): void {
+    for (const held of this.bySession.values()) {
+      for (const occurrence of held.values()) occurrence.controller.abort()
+    }
+    this.bySession.clear()
+  }
+
+  private session(sessionId: SessionId): Map<TabId, Held> {
+    let held = this.bySession.get(sessionId)
+    if (held === undefined) {
+      held = new Map()
+      this.bySession.set(sessionId, held)
+    }
+    return held
+  }
+
+  private hold(sessionId: SessionId, tabId: TabId, navigation: SidebarRightTabNavigation): Held {
+    const controller = new AbortController()
+    const { navigator } = this
+    // Where an open from this tab lands, read at call time because the tab may
+    // have been dragged since: `replaceTab: true` names this tab; otherwise the
+    // pane holding it, unless the caller named another.
+    const place = (placement: SidebarRightTabPlacement): SidebarRightPlacement => ({
+      ...placement.replaceTab === true
+        ? { replaceTab: tabId }
+        : held.paneId === undefined ? {} : { paneId: held.paneId },
+      ...placement.paneId === undefined ? {} : { paneId: placement.paneId },
+      ...placement.revealIfOpened === undefined ? {} : { revealIfOpened: placement.revealIfOpened },
+    })
+    const held: Held = {
+      sessionId,
+      tabId,
+      controller,
+      signal: controller.signal,
+      navigation: createSnapshotStore(navigation),
+      paneId: undefined,
+      pinned: false,
+      tabActions: {
+        openResource: (address, options = {}) => {
+          navigator.openResourceIn(sessionId, address, { ...place(options), params: options.params })
+        },
+        openTab: (kind, options = {}) => {
+          navigator.openTabIn(sessionId, kind, { ...place(options), params: options.params })
+        },
+        close: () => { navigator.closeIn(sessionId, tabId) },
+      },
+    }
+    this.session(sessionId).set(tabId, held)
+    return held
+  }
+}
diff --git a/packages/client/ui-sidebar-right/src/client/tab-info.ts b/packages/client/ui-sidebar-right/src/client/tab-info.ts
new file mode 100644
index 0000000000..86812e09d1
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/client/tab-info.ts
@@ -0,0 +1,60 @@
+/** Slot-owned tab information derived from framework-bound store and navigation hooks. */
+import { useMemo } from 'react'
+import { findTabPane } from '@deepseek-ai/dsh-client-ui-dockkit'
+import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+import type { KeyedSnapshotSelectorHook, PropsStore, SlotHookFactory } from '@deepseek-ai/dsh-client-ui-slots'
+import type { SidebarRightTabActions, SidebarRightTabNavigation, UseSidebarRightTabInfo } from './contract/slots.ts'
+import type { createSidebarRightStore } from './stores.ts'
+
+/** Stable dispatch identity and framework hooks; never passed as tab component props. */
+export interface TabHookContext {
+  readonly tabId: TabId
+  readonly title: boolean
+  readonly fullscreen: boolean
+  readonly signal: AbortSignal
+  readonly actions: SidebarRightTabActions
+  readonly useStore: PropsStore<ReturnType<typeof createSidebarRightStore>>['useStore']
+  readonly useTabNavigation: KeyedSnapshotSelectorHook<SidebarRightTabNavigation>
+}
+
+/**
+ * Bind a tab occurrence without subscribing or creating records during factory evaluation.
+ * @param standard - framework session identity.
+ * @param context - stable record lifetime and framework-bound readers.
+ * @returns the tab information hook.
+ */
+export const tabInfoFactory: SlotHookFactory<'sidebar.right.pane.tab', UseSidebarRightTabInfo> = (standard, context) => {
+  const { sessionId } = standard
+  const { tabId, title, fullscreen, signal, actions, useStore, useTabNavigation } = context
+  return function useTabInfo() {
+    const layout = useStore(state => state.bySession[sessionId]?.layout)
+    const navigation = useTabNavigation(tabId)
+    return useMemo(() => {
+      const tab = layout?.tabs[tabId]
+      if (layout === undefined || tab === undefined || navigation === undefined) {
+        throw new Error(`sidebarRight: tab "${tabId}" is not committed in session "${sessionId}"`)
+      }
+      const pane = findTabPane(layout, tabId)
+      return {
+        sidebar: { expanded: layout.expanded, fullscreen },
+        panel: { id: pane.id },
+        tab: {
+          ...tab,
+          visible: pane.host === 'float' || (layout.expanded && (title || pane.activeTabId === tabId)),
+          navigation,
+          signal,
+          actions,
+        },
+      }
+    }, [layout, navigation, tabId, title, fullscreen, signal, actions])
+  }
+}
+
+/**
+ * Forward the framework-bound tab hook to a guide replacement.
+ * @param _standard - the guide's framework standard props.
+ * @param useTabInfo - the enclosing tab's framework-bound reader.
+ * @returns the same reader for the replacement.
+ */
+export const guideTabInfoFactory: SlotHookFactory<'sidebar.right.tab.guide', UseSidebarRightTabInfo> =
+  (_standard, useTabInfo) => useTabInfo
diff --git a/packages/client/ui-sidebar-right/src/client/tab-registry.ts b/packages/client/ui-sidebar-right/src/client/tab-registry.ts
new file mode 100644
index 0000000000..9162dc7205
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/client/tab-registry.ts
@@ -0,0 +1,399 @@
+/**
+ * Stage one of tab-type registration: what a type IS.
+ *
+ * A registration is purely static — which addresses the type recognizes, how it
+ * ranks against other types that recognize the same one, what the tab chip says,
+ * and whether the type offers an entry box on the guide page. Nothing here is
+ * per-tab, per-session, or a runtime hook: stage two is the keyed
+ * `sidebar.right.pane.tab` registration that supplies the body under the same
+ * `kind`, and everything a body needs at runtime arrives in its props.
+ *
+ * Address recognition follows VS Code's editor resolver: a glob declaration
+ * narrows the candidates, an optional `canOpen` predicate vetoes, and the
+ * survivors are ranked by priority band, then by matched-pattern length, then by
+ * registration order. Addresses are `scheme://` URIs; the one local change to
+ * VS Code's glob rule is that a pattern containing `:` matches the whole address
+ * (`dsh-resource://file/**`, `sidebar://guide`) rather than the URI's path.
+ *
+ * A kind may carry one `builtin` and one `extension` registration at once: the
+ * extension is the one in force — claims, `get`, the guide page, and the body
+ * and title, which the seat finds under the definition's own `id` — and the
+ * builtin resumes when the extension unregisters. Everything else colliding on
+ * a kind throws, as does a second registration of an `id`.
+ *
+ * Thunked copy (`title`, `guide[].title`) is read again on every use, so a
+ * language change needs no re-registration.
+ */
+import type { ComponentType } from 'react'
+import type { Context } from '@deepseek-ai/cordis'
+import type { IconProps } from '@deepseek-ai/dsh-client-ui-primitives'
+import { notifySubscribers } from '@deepseek-ai/dsh-client-store'
+// The POSIX build: the browser bundle must not reach for node's `path`, and
+// addresses are `/`-separated regardless of the host platform.
+import picomatch from 'picomatch/posix'
+
+/**
+ * How strongly a type wants an address it recognizes, as one of three literal
+ * bands (a string, not an imported constant, so a type shipped from another
+ * package needs no runtime import from here).
+ *
+ * - `extension` — a type from outside the product, and the highest: a type that
+ *   declares nothing outranks every viewer shipped here, exactly as in VS Code.
+ *   It is also the band that may take over a `builtin` kind.
+ * - `builtin` — the ordinary band for types shipped with the product.
+ * - `fallback` — plain-content viewers that anything more specific should beat.
+ *   VS Code's text editor holds this position implicitly; ours is a separate
+ *   package, so it says so.
+ */
+export type SidebarRightTabPriority = 'extension' | 'builtin' | 'fallback'
+
+/** Rank of each band, highest first. */
+const RANKS: Readonly<Record<SidebarRightTabPriority, number>> = {
+  extension: 3,
+  builtin: 2,
+  fallback: 1,
+}
+
+/** The band a definition that names none is in. */
+const DEFAULT_BAND: SidebarRightTabPriority = 'extension'
+
+/** One entry box the guide page offers, contributed by the type it opens (picking it opens that type as a page). */
+export interface SidebarRightGuideEntry {
+  /** Ascending position among every registered type's entries. */
+  readonly order: number
+  /**
+   * The box's heading.
+   * @returns the heading in the current language.
+   */
+  readonly title: () => string
+  /**
+   * One line under the heading.
+   * @returns the line in the current language.
+   */
+  readonly description: () => string
+  /** Optional glyph, drawn at the box's leading edge. */
+  readonly icon?: ComponentType<IconProps>
+}
+
+/** A guide entry as the registry lists it: with the kind of the type that contributed it, which is what picking it opens. */
+export interface SidebarRightGuideBox extends SidebarRightGuideEntry {
+  readonly kind: string
+}
+
+
+/** One registered tab type: its static face, and nothing else. */
+export interface SidebarRightTabDefinition {
+  /**
+   * This implementation's identity in the tab system, unique across every
+   * registration (a package name is the natural value). A kind is not unique —
+   * an extension may take a builtin's over — so the implementation carries its
+   * own name, and it is the key its body and title register under in the
+   * `sidebar.right.pane.tab` and `sidebar.right.pane.tab.title` seats.
+   */
+  readonly id: string
+  /** Type discriminator: what the tabs of this type are, and what `openTab` names. */
+  readonly kind: string
+  /**
+   * Resource-address globs this type recognizes; omit for a page type, which is
+   * opened by kind and recognizes no address.
+   *
+   * A pattern containing `:` is matched against the whole address
+   * (`dsh-resource://file/**`); one without is matched against the URI's path at
+   * any depth (`*.md` matches `dsh-resource://file/session/s1/home/me/notes.md`),
+   * and an address that is not a URI matches no such pattern. Matching ignores
+   * case and does not hide dotfiles.
+   */
+  readonly patterns?: readonly string[]
+  /** Defaults to `extension`: a type that says nothing is one from outside the product. */
+  readonly priority?: SidebarRightTabPriority
+  /**
+   * Veto an address this type's globs matched.
+   *
+   * Synchronous and cheap: it runs on every routing decision. Omit it to accept
+   * every match.
+   * @param address - the matched address.
+   * @returns whether this type will open it.
+   */
+  readonly canOpen?: (address: string) => boolean
+  /**
+   * The tab chip's initial text, captured into the layout record at open time.
+   * @param address - the address being opened.
+   * @returns the title in the current language.
+   */
+  readonly title: (address: string) => string
+  /** Entry boxes for the guide page. Omit to stay off it. */
+  readonly guide?: readonly SidebarRightGuideEntry[]
+}
+
+/** What a routing decision settles on: who draws the address, and as what. */
+export interface SidebarRightTabClaim {
+  /** The claiming type. */
+  readonly kind: string
+  /**
+   * Stable identity of the content, which is the address itself.
+   *
+   * Two opens of the same address are the same tab, which is what makes opening
+   * idempotent.
+   */
+  readonly contentId: string
+  /** Title for the tab chip. */
+  readonly title: string
+}
+
+/** A registered type with its patterns compiled. */
+interface Registered {
+  readonly definition: SidebarRightTabDefinition
+  readonly band: SidebarRightTabPriority
+  /** One matcher per declared pattern, in declaration order. */
+  readonly matchers: readonly { readonly pattern: string; readonly test: (address: string) => boolean }[]
+  /** Registration position across every kind, the last tiebreaker. */
+  readonly order: number
+}
+
+/**
+ * Everything registered under one kind: the registration in force and, while
+ * an `extension` holds a kind a `builtin` also registered, the builtin it
+ * shadows. A kind is in the registry's map exactly while something is in force
+ * for it, so a held slot always answers.
+ */
+interface KindSlot {
+  inForce: Registered
+  shadowed: Registered | undefined
+}
+
+/**
+ * Whether a band may join a held kind: an `extension` and a `builtin` pair up
+ * once, and a `fallback` shares its kind with nothing.
+ */
+function coexists(slot: KindSlot, band: SidebarRightTabPriority): boolean {
+  return band !== 'fallback' && slot.inForce.band !== 'fallback' && slot.inForce.band !== band && slot.shadowed === undefined
+}
+
+/** How a candidate ranked, kept only while `candidates` is sorting. */
+interface Ranked {
+  readonly definition: SidebarRightTabDefinition
+  readonly rank: number
+  /** Length of the longest pattern that matched, VS Code's specificity measure. */
+  readonly length: number
+  /** Registration position, the last tiebreaker. */
+  readonly order: number
+}
+
+/**
+ * The address's URI path: what a pattern with no scheme separator matches
+ * against. `dsh-resource://file/session/s1/home/me/b.md` gives `/session/s1/home/me/b.md`;
+ * `sidebar://guide` gives `''`; an address that is not a URI gives nothing.
+ */
+function pathOf(address: string): string | undefined {
+  try {
+    return new URL(address).pathname
+  } catch {
+    // The only thrower is the URL parser rejecting a non-URI address, which by
+    // the rule above matches no path pattern.
+    return undefined
+  }
+}
+
+/** Compile one declared pattern into the test the router runs. */
+function matcherFor(pattern: string): (address: string) => boolean {
+  // `basename: true` is what makes `*.md` match at any depth; it applies only to
+  // patterns without a separator, which is exactly the path case.
+  const whole = pattern.includes(':')
+  const match = picomatch(pattern, { nocase: true, dot: true, ...whole ? {} : { basename: true } })
+  return (address) => {
+    if (whole) return match(address)
+    const path = pathOf(address)
+    return path !== undefined && match(path)
+  }
+}
+
+/**
+ * The registered tab types.
+ *
+ * Registration order is part of the contract: it breaks ties between types that
+ * recognize an address equally well.
+ */
+export class SidebarRightTabRegistry {
+  private readonly kinds = new Map<string, KindSlot>()
+  private readonly ids = new Set<string>()
+  private readonly listeners = new Set<() => void>()
+  private registrations = 0
+  private cached: readonly SidebarRightTabDefinition[] = []
+  private guideEntries: readonly SidebarRightGuideBox[] = []
+
+  /** @param ctx - Context whose effects own the contributed types. */
+  constructor(private readonly ctx: Context) {}
+
+  /**
+   * Register one tab type for the caller's lifetime.
+   *
+   * The caller holds the returned disposer inside its own `ctx.effect`, so a
+   * type's registration lives exactly as long as the plugin that contributed it.
+   * An `extension` may register a kind a `builtin` already holds and takes it
+   * over until it unregisters; a second registration in the same band, or any
+   * registration meeting a `fallback` of the same kind, is a wiring mistake, and
+   * so is an `id` already in use.
+   * @param definition - the contributed type.
+   * @returns idempotent disposer.
+   * @throws when the id is taken, or the kind is already registered in a way this one cannot coexist with.
+   */
+  register(definition: SidebarRightTabDefinition): () => void {
+    const { id, kind } = definition
+    const band = definition.priority ?? DEFAULT_BAND
+    if (this.ids.has(id)) throw new Error(`sidebarRight: tab type id "${id}" is already registered`)
+    const held = this.kinds.get(kind)
+    if (held !== undefined && !coexists(held, band)) {
+      throw new Error(`sidebarRight: tab kind "${kind}" is already registered (${held.inForce.band})`)
+    }
+    this.registrations += 1
+    const entry: Registered = {
+      definition,
+      band,
+      matchers: (definition.patterns ?? []).map(pattern => ({ pattern, test: matcherFor(pattern) })),
+      order: this.registrations,
+    }
+    const dispose = this.ctx.effect(() => {
+      this.ids.add(id)
+      const slot = this.enter(kind, entry)
+      this.refresh()
+      return () => {
+        this.ids.delete(id)
+        this.leave(kind, slot, entry)
+        this.refresh()
+      }
+    }, `sidebarRight.tabs.register(${JSON.stringify(id)})`)
+    return () => { void dispose() }
+  }
+
+  /** Add a registration to its kind's slot, the higher band in force; `coexists` has already admitted it. */
+  private enter(kind: string, entry: Registered): KindSlot {
+    const held = this.kinds.get(kind)
+    if (held === undefined) {
+      const slot: KindSlot = { inForce: entry, shadowed: undefined }
+      this.kinds.set(kind, slot)
+      return slot
+    }
+    if (RANKS[entry.band] > RANKS[held.inForce.band]) {
+      held.shadowed = held.inForce
+      held.inForce = entry
+    } else {
+      held.shadowed = entry
+    }
+    return held
+  }
+
+  /** Remove a registration from its kind's slot: a shadowed builtin resumes, and an emptied kind is freed. */
+  private leave(kind: string, slot: KindSlot, entry: Registered): void {
+    if (slot.inForce !== entry) {
+      slot.shadowed = undefined
+    } else if (slot.shadowed === undefined) {
+      this.kinds.delete(kind)
+    } else {
+      slot.inForce = slot.shadowed
+      slot.shadowed = undefined
+    }
+  }
+
+  /** Every kind's registration in force, in registration order. */
+  private active(): Registered[] {
+    return [...this.kinds.values()].map(slot => slot.inForce).sort((left, right) => left.order - right.order)
+  }
+
+  /**
+   * Registered types in registration order.
+   * @returns reference-stable entries.
+   */
+  entries(): readonly SidebarRightTabDefinition[] {
+    return this.cached
+  }
+
+  /**
+   * Every type in force's guide entries, in `order`, each naming the kind it opens.
+   * @returns reference-stable entries.
+   */
+  guide(): readonly SidebarRightGuideBox[] {
+    return this.guideEntries
+  }
+
+  /**
+   * The type in force for a kind.
+   * @param kind - the type discriminator.
+   * @returns the type, or `undefined` when nothing registered it.
+   */
+  get(kind: string): SidebarRightTabDefinition | undefined {
+    return this.kinds.get(kind)?.inForce.definition
+  }
+
+  /**
+   * Every type that would open an address, best first.
+   *
+   * Ranked by priority band, then by the length of the pattern that matched,
+   * then by registration order. Types whose `canOpen` vetoes are absent.
+   * @param address - the address a caller wants opened.
+   * @returns the ranked types; empty when nothing recognizes the address.
+   */
+  candidates(address: string): readonly SidebarRightTabDefinition[] {
+    const ranked: Ranked[] = []
+    for (const { definition, band, matchers, order } of this.active()) {
+      let length = -1
+      for (const matcher of matchers) {
+        if (matcher.test(address) && matcher.pattern.length > length) length = matcher.pattern.length
+      }
+      if (length < 0) continue
+      if (definition.canOpen !== undefined && !definition.canOpen(address)) continue
+      ranked.push({ definition, rank: RANKS[band], length, order })
+    }
+    ranked.sort((left, right) =>
+      right.rank - left.rank || right.length - left.length || left.order - right.order)
+    return ranked.map(entry => entry.definition)
+  }
+
+  /**
+   * Decide which type opens an address, and as what.
+   *
+   * Without `kind`, the best candidate wins. With `kind`, that type opens the
+   * address if its `canOpen` agrees — its globs are not consulted, because
+   * naming the type IS the decision.
+   *
+   * An address no type will open is a wiring mistake, not a user error, so this
+   * throws rather than reporting absence.
+   * @param address - the address a caller wants opened.
+   * @param kind - a type named by the caller, overriding the ranking.
+   * @returns the claiming type and the record to open.
+   */
+  claim(address: string, kind?: string): SidebarRightTabClaim {
+    if (kind !== undefined) {
+      const definition = this.get(kind)
+      if (definition === undefined) {
+        throw new Error(`sidebarRight: no tab type is registered as "${kind}"`)
+      }
+      if (definition.canOpen !== undefined && !definition.canOpen(address)) {
+        throw new Error(`sidebarRight: tab type "${kind}" refuses "${address}"`)
+      }
+      return { kind, contentId: address, title: definition.title(address) }
+    }
+    const [chosen] = this.candidates(address)
+    if (chosen === undefined) {
+      throw new Error(`sidebarRight: no registered tab type claims "${address}"`)
+    }
+    return { kind: chosen.kind, contentId: address, title: chosen.title(address) }
+  }
+
+  /**
+   * Observe low-frequency registry changes.
+   * @param listener - synchronous invalidation callback.
+   * @returns unsubscribe callback.
+   */
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  private refresh(): void {
+    this.cached = this.active().map(entry => entry.definition)
+    this.guideEntries = this.cached
+      .flatMap(definition => (definition.guide ?? []).map(entry => ({ ...entry, kind: definition.kind })))
+      .sort((left, right) => left.order - right.order)
+    notifySubscribers(this.listeners, '[ui-sidebar-right] tab registry')
+  }
+}
diff --git a/packages/client/ui-sidebar-right/src/client/tabs/guide/GuideBody.module.css b/packages/client/ui-sidebar-right/src/client/tabs/guide/GuideBody.module.css
new file mode 100644
index 0000000000..db793e261f
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/client/tabs/guide/GuideBody.module.css
@@ -0,0 +1,79 @@
+/* The guide body's own sheet: its domain owns these rules, so the shell's
+   stylesheet does not carry them. Tokens only. */
+.guide {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  align-items: center;
+  padding-top: 24px;
+  text-align: center;
+}
+
+.guideTitle {
+  margin: 0;
+  color: var(--dsw-alias-label-primary);
+  font-size: var(--dsh-content-font-size, 14px);
+  font-weight: 500;
+  line-height: 1.6;
+}
+
+.guideBody {
+  margin: 0;
+  color: var(--dsw-alias-label-secondary);
+  font-size: var(--dsh-content-font-size-secondary, 13px);
+  line-height: 1.6;
+}
+
+/* Entry boxes: as many per row as the pane's width allows. */
+.entries {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(160px, 1fr));
+  gap: 8px;
+  width: 100%;
+  max-width: 480px;
+  margin-top: 16px;
+}
+
+.entry {
+  display: flex;
+  gap: 8px;
+  align-items: flex-start;
+  padding: 10px 12px;
+  color: inherit;
+  font: inherit;
+  text-align: left;
+  background: transparent;
+  border: 0.5px solid var(--dsw-alias-border-l1);
+  border-radius: 8px;
+  cursor: pointer;
+}
+
+.entry:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.entryIcon {
+  display: flex;
+  flex: none;
+  margin-top: 1px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.entryText {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+}
+
+.entryTitle {
+  color: var(--dsw-alias-label-primary);
+  font-size: var(--dsh-content-font-size, 14px);
+  line-height: 1.4;
+}
+
+.entryDescription {
+  color: var(--dsw-alias-label-secondary);
+  font-size: var(--dsh-content-font-size-secondary, 13px);
+  line-height: 1.4;
+}
diff --git a/packages/client/ui-sidebar-right/src/client/tabs/guide/GuideBody.tsx b/packages/client/ui-sidebar-right/src/client/tabs/guide/GuideBody.tsx
new file mode 100644
index 0000000000..46b67581a5
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/client/tabs/guide/GuideBody.tsx
@@ -0,0 +1,84 @@
+/**
+ * The guide tab's body: a chain host, and the guide it falls back to.
+ *
+ * The chain is the replacement seam. A product with its own idea of what an
+ * empty sidebar should say registers into `sidebar.right.tab.guide`, and its entry
+ * takes the whole body; with no entry, or with every entry declining, the guide
+ * below renders. The shipped guide is the owner's fallback rather than a chain
+ * entry of its own, so there is always exactly one body and the shipped one
+ * cannot be outvoted by accident.
+ *
+ * The shipped guide is a centred title, one line under it, and the entry boxes
+ * every registered type contributed. Picking a box opens that type as a page in
+ * this tab's place, so the guide is a doorway rather than a page that stays open.
+ */
+import type { ReactNode } from 'react'
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
+import type { ChainRenderOpts, HookContextOf, InjectFace, PropsLocale, PropsRenderSlots, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type { SidebarRightGuideBox } from '../../tab-registry.ts'
+import css from './GuideBody.module.css'
+
+/** What the guide body needs from its host beyond the framework shares. */
+export interface GuideInjected {
+  /** The registry's guide entries in `order`; observable, so a type registering later appears. */
+  readonly hooks: { readonly guideEntries: ObservableSnapshot<readonly SidebarRightGuideBox[]> }
+}
+
+/** The guide body's composed props: the tab it draws, its chain child, its copy, and the entries. */
+export type GuideBodyProps =
+  & PropsRuntime<'sidebar.right.pane.tab'>
+  & PropsRenderSlots<'sidebar.right.tab.guide'>
+  & PropsLocale<'sidebarRight'>
+  & InjectFace<GuideInjected>
+
+/** One entry box: the contributing type's glyph, heading, and line. */
+function EntryBox({ entry, onPick }: { entry: SidebarRightGuideBox; onPick: (entry: SidebarRightGuideBox) => void }): ReactNode {
+  const Icon = entry.icon
+  return (
+    <button
+      type="button"
+      className={css.entry}
+      data-sidebar-right-guide-entry={entry.kind}
+      onClick={() => { onPick(entry) }}
+    >
+      {Icon !== undefined && <span className={css.entryIcon}><Icon size={16} /></span>}
+      <span className={css.entryText}>
+        <span className={css.entryTitle}>{entry.title()}</span>
+        <span className={css.entryDescription}>{entry.description()}</span>
+      </span>
+    </button>
+  )
+}
+
+/** The shipped guide: what the column is for, and the doors out of it. */
+function ShippedGuide({ entries, onPick, t }: {
+  entries: readonly SidebarRightGuideBox[]
+  onPick: (entry: SidebarRightGuideBox) => void
+  t: GuideBodyProps['t']
+}): ReactNode {
+  return (
+    <div className={css.guide} data-sidebar-right-guide>
+      <p className={css.guideTitle}>{t('guide.lead')}</p>
+      <p className={css.guideBody}>{t('guide.body')}</p>
+      {entries.length > 0 && (
+        <div className={css.entries}>
+          {/* Keyed by position in the ordered list: one type may contribute several boxes, and `order` is not unique. */}
+          {entries.map((entry, index) => <EntryBox key={`${entry.kind}:${index}`} entry={entry} onPick={onPick} />)}
+        </div>
+      )}
+    </div>
+  )
+}
+
+/** The guide tab's body, replaceable through its chain child. */
+export function GuideBody({ useTabInfo, useGuideEntries, renderSlotChain, t }: GuideBodyProps): ReactNode {
+  const { tab } = useTabInfo()
+  const entries = useGuideEntries(entries => entries)
+  const options = {
+    hookContext: useTabInfo,
+    fallback: (
+      <ShippedGuide entries={entries} onPick={(entry) => { tab.actions.openTab(entry.kind, { replaceTab: true }) }} t={t} />
+    ),
+  } satisfies ChainRenderOpts & { hookContext: HookContextOf<'sidebar.right.tab.guide'> }
+  return renderSlotChain('sidebar.right.tab.guide', {}, options)
+}
diff --git a/packages/client/ui-sidebar-right/src/client/tabs/guide/definition.ts b/packages/client/ui-sidebar-right/src/client/tabs/guide/definition.ts
new file mode 100644
index 0000000000..a19be4a7f4
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/client/tabs/guide/definition.ts
@@ -0,0 +1,27 @@
+/**
+ * Stage one of the guide type's registration: what it IS.
+ */
+import type { TranslateNS } from '@deepseek-ai/dsh-client-locale/client'
+import type { SidebarRightTabDefinition } from '../../tab-registry.ts'
+import { GUIDE_KIND } from '../../contract/seed.ts'
+
+/** The shipped guide implementation's identity: the key its body registers under. */
+export const GUIDE_ID = '@deepseek-ai/dsh-client-ui-sidebar-right/guide'
+
+/**
+ * The guide type's registry definition.
+ *
+ * A page type: it recognizes no resource address, because a guide views
+ * nothing, and is opened by kind; `builtin` is the ordinary band for a type
+ * shipped here.
+ * @param t - namespace-bound translate, read fresh on every title call.
+ * @returns the definition to register.
+ */
+export function guideDefinition(t: TranslateNS<'sidebarRight'>): SidebarRightTabDefinition {
+  return {
+    id: GUIDE_ID,
+    kind: GUIDE_KIND,
+    priority: 'builtin',
+    title: () => t('tab.guide.title'),
+  }
+}
diff --git a/packages/client/ui-sidebar-right/src/css-modules.d.ts b/packages/client/ui-sidebar-right/src/css-modules.d.ts
new file mode 100644
index 0000000000..bc5e482353
--- /dev/null
+++ b/packages/client/ui-sidebar-right/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-right/src/index.ts b/packages/client/ui-sidebar-right/src/index.ts
new file mode 100644
index 0000000000..ec75b76799
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/index.ts
@@ -0,0 +1,4 @@
+/** Pure host half; the whole Sidebar lives in the browser export. */
+
+/** Host plugin body: the Sidebar contributes nothing to the host tree. */
+export function apply(): void {}
diff --git a/packages/client/ui-sidebar-right/tests/apply.client.spec.ts b/packages/client/ui-sidebar-right/tests/apply.client.spec.ts
new file mode 100644
index 0000000000..c54f98f2af
--- /dev/null
+++ b/packages/client/ui-sidebar-right/tests/apply.client.spec.ts
@@ -0,0 +1,204 @@
+/**
+ * The plugin's wiring, and its removal when the plugin goes.
+ *
+ * The registry and the navigation controller are real, because "provided"
+ * means what those faces do; the slot, locale, frame, and resource faces are
+ * recorders, because what matters here is what was handed to them — two seats
+ * over one store, the guide's body under its own id, the frame reports, the
+ * service binding — and that every registration is gone after dispose, which
+ * is what makes a reload safe. The seats' components have their own specs.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { apply, inject } from '../src/client/index.ts'
+import type { GuideInjected, SidebarRightInjected } from '../src/client/index.ts'
+import { apply as hostApply } from '../src/index.ts'
+import { SidebarRightController } from '../src/client/service.ts'
+import { SidebarRightTabRegistry } from '../src/client/tab-registry.ts'
+import type { createSidebarRightStore } from '../src/client/stores.ts'
+import { RightbarSeat } from '../src/client/shell/SidebarRight.tsx'
+import { ExpandButton } from '../src/client/shell/ExpandButton.tsx'
+import { GuideBody } from '../src/client/tabs/guide/GuideBody.tsx'
+import { GUIDE_ID } from '../src/client/tabs/guide/definition.ts'
+import { en, zh } from '../src/client/locales.ts'
+
+const SESSION = 's-test' as SessionId
+
+interface Recorded {
+  name: string
+  key?: string
+  locale: string
+  store?: unknown
+  children?: unknown
+  inject?: (sessionId: SessionId) => unknown
+  component: unknown
+}
+
+async function boot() {
+  const ctx = new Context()
+  const registered: Recorded[] = []
+  const slots = {
+    inject: vi.fn((_name: string, register: () => () => void) => register()),
+    register: vi.fn((options: Omit<Recorded, 'component'>, component: unknown) => {
+      const entry: Recorded = { ...options, component }
+      registered.push(entry)
+      return () => { registered.splice(registered.indexOf(entry), 1) }
+    }),
+  }
+  const dictionaries = new Map<string, unknown>()
+  const locale = {
+    // Copy is the dictionary's contract; the key stands in for the translation.
+    bind: vi.fn(() => (key: string) => key),
+    register: vi.fn((ns: string, dicts: unknown) => {
+      dictionaries.set(ns, dicts)
+      return () => { dictionaries.delete(ns) }
+    }),
+  }
+  const layout = { openRightbar: vi.fn(), closeRightbar: vi.fn() }
+  const resources = { pin: vi.fn<(address: string, signal: AbortSignal) => void>() }
+  ctx.provide('slots', slots as never)
+  ctx.provide('locale', locale as never)
+  ctx.provide('layout', layout as never)
+  ctx.provide('resources', resources as never)
+  const fiber = ctx.plugin({ inject: [...inject], apply })
+  await fiber.await()
+  const seat = (name: string): Recorded => {
+    const entry = registered.find(candidate => candidate.name === name)
+    if (entry === undefined) throw new Error(`expected a registration into ${name}`)
+    return entry
+  }
+  const injectedOf = (entry: Recorded): unknown => {
+    if (entry.inject === undefined) throw new Error(`expected ${entry.name} to inject`)
+    return entry.inject(SESSION)
+  }
+  return { ctx, registered, dictionaries, layout, resources, fiber, seat, injectedOf }
+}
+
+describe('ui-sidebar-right apply', () => {
+  it('keeps the host Loader entry inert', () => {
+    expect(hostApply).not.toThrow()
+  })
+
+  it('provides both faces, and registers the guide through the same two-stage path as any other type', async () => {
+    const { ctx, registered, dictionaries, seat } = await boot()
+    expect(ctx.sidebarRightTabs).toBeInstanceOf(SidebarRightTabRegistry)
+    expect(ctx.sidebarRight).toBeInstanceOf(SidebarRightController)
+    expect('adopt' in ctx.sidebarRight).toBe(false)
+    expect(dictionaries.get('sidebarRight')).toEqual({ zh, en })
+    const guide = ctx.sidebarRightTabs.get('guide')
+    expect(guide?.id).toBe(GUIDE_ID)
+    expect(guide?.priority).toBe('builtin')
+    expect(guide?.title('sidebar://guide')).toBe('tab.guide.title')
+    // Three registrations: the panel seat, the header's corner seat, and the
+    // guide body under the guide implementation's id.
+    expect(registered.map(entry => [entry.name, entry.key, entry.locale, entry.component])).toEqual([
+      ['rightbar', undefined, 'sidebarRight', RightbarSeat],
+      ['conversation.session.header.corner', undefined, 'sidebarRight', ExpandButton],
+      ['sidebar.right.pane.tab', GUIDE_ID, 'sidebarRight', GuideBody],
+    ])
+    // The panel declares the extension seats; the guide declares its chain child.
+    expect(Object.keys(seat('rightbar').children as object)).toEqual([
+      'sidebar.right.pane.tab', 'sidebar.right.pane.tab.title', 'sidebar.right.tab.menu.item',
+    ])
+    expect(seat('sidebar.right.pane.tab').children).toMatchObject({ 'sidebar.right.tab.guide': { kind: 'chain', scope: 'session' } })
+    // Both seats read one store: the button only needs to know whether the panel is expanded.
+    expect(seat('rightbar').store).toBeDefined()
+    expect(seat('conversation.session.header.corner').store).toBe(seat('rightbar').store)
+  })
+
+  it('hands the panel seat the frame report, the service binding, the opens, the observable registry, and the Tab domain', async () => {
+    const { ctx, layout, resources, seat, injectedOf } = await boot()
+    const injected = injectedOf(seat('rightbar')) as SidebarRightInjected
+    // The frame learns the composition of expanded and presentation, nothing else.
+    injected.syncPresentation({ shown: true, track: true, fullscreen: false })
+    expect(layout.openRightbar).toHaveBeenLastCalledWith(true, false)
+    injected.syncPresentation({ shown: true, track: true, fullscreen: true })
+    expect(layout.openRightbar).toHaveBeenLastCalledWith(true, true)
+    injected.syncPresentation({ shown: true, track: false, fullscreen: true })
+    expect(layout.openRightbar).toHaveBeenLastCalledWith(false, true)
+    injected.syncPresentation({ shown: false, track: false, fullscreen: false })
+    expect(layout.closeRightbar).toHaveBeenCalledOnce()
+    // The registry, observable: what the seat dispatches a kind to.
+    expect(injected.hooks.tabTypes.getSnapshot().find(type => type.kind === 'guide')?.id).toBe(GUIDE_ID)
+    const seen = vi.fn()
+    const unsubscribe = injected.hooks.tabTypes.subscribe(seen)
+    ctx.sidebarRightTabs.register({ id: 'spec/text', kind: 'text', patterns: ['dsh-resource://file/**'], title: () => 'text' })
+    expect(seen).toHaveBeenCalledOnce()
+    unsubscribe()
+    // The binding makes the service act on this seat's session; the seat's
+    // store instance is minted here from the handle the registration declared.
+    const handle = seat('rightbar').store as ReturnType<typeof createSidebarRightStore>
+    const instance = handle.create()
+    const release = injected.bindService({ sessionId: SESSION, actions: instance.actions, surfaces: {}, canSplitPane: () => true })
+    injected.openTab('guide', { revealIfOpened: false })
+    const surface = instance.getSnapshot().bySession[SESSION]
+    expect(surface?.layout.expanded).toBe(true)
+    expect(Object.values(surface?.layout.tabs ?? {}).map(tab => tab.kind)).toEqual(['guide'])
+    // Holding a record pins its address through the resource model.
+    if (surface === undefined) throw new Error('expected a surface')
+    ctx.sidebarRight.tabDomain.sync(SESSION, surface.layout)
+    expect(resources.pin).toHaveBeenCalledWith('sidebar://guide', expect.any(AbortSignal))
+    release()
+    expect(() => { ctx.sidebarRight.toggleExpanded() }).toThrow('no session surface is mounted')
+  })
+
+  it('adopts each session\'s store instance as the runtime mints it, so a tab\'s own actions land with no seat bound', async () => {
+    const { ctx, resources, seat } = await boot()
+    const handle = seat('rightbar').store as ReturnType<typeof createSidebarRightStore>
+    // Both seats declare the same wrapped handle, so either minting adopts.
+    expect(seat('conversation.session.header.corner').store).toBe(handle)
+    const instance = handle.create(SESSION)
+    instance.actions.open(SESSION)
+    const guide = Object.values(instance.getSnapshot().bySession[SESSION]?.layout.tabs ?? {})[0]
+    if (guide === undefined) throw new Error('expected the seeded guide')
+    // Held and pinned from the store's own commit: no seat synced anything.
+    const occurrence = ctx.sidebarRight.tabDomain.occurrence(SESSION, guide)
+    expect(resources.pin).toHaveBeenCalledWith('sidebar://guide', occurrence.signal)
+    occurrence.tabActions.close()
+    expect(instance.getSnapshot().bySession[SESSION]?.layout.tabs[guide.id]).toBeUndefined()
+    expect(occurrence.signal.aborted).toBe(true)
+  })
+
+  it('hands the guide body the registry\'s entry boxes, observable', async () => {
+    const { ctx, seat, injectedOf } = await boot()
+    const { hooks: { guideEntries } } = injectedOf(seat('sidebar.right.pane.tab')) as GuideInjected
+    expect(guideEntries.getSnapshot()).toEqual([])
+    const seen = vi.fn()
+    guideEntries.subscribe(seen)
+    ctx.sidebarRightTabs.register({
+      id: 'spec/files',
+      kind: 'files',
+      title: () => 'Files',
+      guide: [{ order: 10, title: () => 'Files', description: () => 'The workspace tree' }],
+    })
+    expect(seen).toHaveBeenCalledOnce()
+    expect(guideEntries.getSnapshot().map(entry => entry.kind)).toEqual(['files'])
+  })
+
+  it('takes every registration and both faces back when disposed, aborting the open records, so a reload registers again', async () => {
+    const { ctx, registered, dictionaries, fiber, seat, injectedOf } = await boot()
+    const injected = injectedOf(seat('rightbar')) as SidebarRightInjected
+    const handle = seat('rightbar').store as ReturnType<typeof createSidebarRightStore>
+    // Minted under the session key, so the instance is adopted and the teardown releases it.
+    const instance = handle.create(SESSION)
+    injected.bindService({ sessionId: SESSION, actions: instance.actions, surfaces: {}, canSplitPane: () => true })
+    injected.openTab('guide')
+    const surface = instance.getSnapshot().bySession[SESSION]
+    const guide = Object.values(surface?.layout.tabs ?? {})[0]
+    if (guide === undefined) throw new Error('expected the guide tab')
+    const { signal, tabActions } = ctx.sidebarRight.tabDomain.occurrence(SESSION, guide)
+    await fiber.dispose()
+    expect(signal.aborted).toBe(true)
+    // The adoption went with the plugin: a late action from the dead occurrence changes nothing.
+    tabActions.close()
+    expect(instance.getSnapshot().bySession[SESSION]?.layout.tabs[guide.id]).toBeDefined()
+    expect(ctx.get('sidebarRight')).toBeUndefined()
+    expect(ctx.get('sidebarRightTabs')).toBeUndefined()
+    expect(registered).toEqual([])
+    expect(dictionaries.size).toBe(0)
+    await ctx.plugin({ inject: [...inject], apply }).await()
+    expect(ctx.sidebarRightTabs.get('guide')?.id).toBe(GUIDE_ID)
+    expect(registered).toHaveLength(3)
+  })
+})
diff --git a/packages/client/ui-sidebar-right/tests/expand-button.client.spec.tsx b/packages/client/ui-sidebar-right/tests/expand-button.client.spec.tsx
new file mode 100644
index 0000000000..41a402c8ca
--- /dev/null
+++ b/packages/client/ui-sidebar-right/tests/expand-button.client.spec.tsx
@@ -0,0 +1,68 @@
+// @vitest-environment jsdom
+/**
+ * The way back into a hidden panel: the header's corner button exists exactly
+ * while the panel is collapsed, asks for it to expand, and leaves a same-size
+ * footprint while the panel is shown so the header row never moves.
+ */
+import { describe, expect, it } from 'vitest'
+import { act, cleanup, fireEvent, render } from '@testing-library/react'
+import { useSyncExternalStore } from 'react'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { ExpandButton } from '../src/client/shell/ExpandButton.tsx'
+import type { ExpandButtonProps } from '../src/client/shell/ExpandButton.tsx'
+import { createSidebarRightStore } from '../src/client/stores.ts'
+
+const SESSION = 's-test' as SessionId
+
+/** Test-local selector hook over a framework-neutral store instance. */
+function hookOf<T>(inst: { subscribe: (fn: () => void) => () => void; getSnapshot: () => T }) {
+  return function useSelector<S>(sel: (s: T) => S): S {
+    return sel(useSyncExternalStore(inst.subscribe, inst.getSnapshot))
+  }
+}
+
+/**
+ * Mount the button over a real store instance. It reads four of its props; the
+ * rest of the standard kit is framework-injected and never touched here, so one
+ * documented cast keeps the harness to what is actually exercised.
+ */
+function mountButton() {
+  const instance = createSidebarRightStore(() => 'Start').create()
+  const props = {
+    sessionId: SESSION,
+    useStore: hookOf(instance),
+    actions: instance.actions,
+    // Copy is the dictionary's contract; the key stands in for the translation.
+    t: (key: string) => key,
+  } as unknown as ExpandButtonProps
+  const view = render(<ExpandButton {...props} />)
+  const control = (): HTMLElement | null => view.container.querySelector('[data-sidebar-right-expand]')
+  const placeholder = (): HTMLElement | null => view.container.querySelector('[data-sidebar-right-expand-placeholder]')
+  return { instance, view, control, placeholder }
+}
+
+describe('ExpandButton', () => {
+  it('offers the way in while the session has no surface yet, and asks the panel to expand', () => {
+    const { instance, control, placeholder } = mountButton()
+    const button = control()
+    if (button === null) throw new Error('expected the expand control')
+    expect(button.getAttribute('aria-label')).toBe('chrome.expand')
+    expect(placeholder()).toBeNull()
+    fireEvent.click(button)
+    expect(instance.getSnapshot().bySession[SESSION]?.layout.expanded).toBe(true)
+    // Shown: the control gives way to its footprint, so the seat keeps its width.
+    expect(control()).toBeNull()
+    expect(placeholder()).not.toBeNull()
+    cleanup()
+  })
+
+  it('comes back when the panel collapses again', () => {
+    const { instance, control, placeholder } = mountButton()
+    act(() => { instance.actions.setExpanded(SESSION, true) })
+    expect(control()).toBeNull()
+    act(() => { instance.actions.setExpanded(SESSION, false) })
+    expect(control()).not.toBeNull()
+    expect(placeholder()).toBeNull()
+    cleanup()
+  })
+})
diff --git a/packages/client/ui-sidebar-right/tests/guide-body.client.spec.tsx b/packages/client/ui-sidebar-right/tests/guide-body.client.spec.tsx
new file mode 100644
index 0000000000..3e25bc1b4a
--- /dev/null
+++ b/packages/client/ui-sidebar-right/tests/guide-body.client.spec.tsx
@@ -0,0 +1,110 @@
+// @vitest-environment jsdom
+/**
+ * The guide tab's body: the chain seam, and the shipped guide behind it.
+ *
+ * The contract a type relies on is the entry box: one per guide entry every
+ * registered type contributed, in the registry's order, and picking one opens
+ * that type as a page in the guide's own tab. The chain is asserted through
+ * what the body hands it — the tab and the shipped guide as the fallback.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render } from '@testing-library/react'
+import type { ReactNode } from 'react'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
+import type { IconProps } from '@deepseek-ai/dsh-client-ui-primitives'
+import { GuideBody } from '../src/client/tabs/guide/GuideBody.tsx'
+import type { GuideBodyProps } from '../src/client/tabs/guide/GuideBody.tsx'
+import type { SidebarRightGuideBox } from '../src/client/tab-registry.ts'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-test-runtime'
+
+afterEach(cleanup)
+
+const TAB = { id: 'tab-1', kind: 'guide', contentId: 'sidebar://guide', title: 'Start' }
+
+/** A glyph that marks its box, so a spec can tell an entry with an icon from one without. */
+function Glyph({ size }: IconProps): ReactNode {
+  return <span data-guide-glyph={size} />
+}
+
+/** One entry box as the registry lists it. */
+function box(kind: string, order: number, icon?: SidebarRightGuideBox['icon']): SidebarRightGuideBox {
+  return {
+    kind,
+    order,
+    title: () => `${kind} title`,
+    description: () => `${kind} description`,
+    ...icon === undefined ? {} : { icon },
+  }
+}
+
+/**
+ * Mount the body with the entries observable and a chain that renders its
+ * fallback, which is what the chain does with no registrant.
+ */
+function mountGuide(entries: readonly SidebarRightGuideBox[]) {
+  const guideEntries = createSnapshotStore<readonly SidebarRightGuideBox[]>(entries)
+  const openTab = vi.fn()
+  const renderSlot = vi.fn((_seat: string, _owner: unknown, options: { fallback: ReactNode }) => options.fallback)
+  const props = {
+    useTabInfo: () => ({ tab: { ...TAB, actions: { openResource: vi.fn(), openTab, close: vi.fn() } } }),
+    useGuideEntries: bindSnapshotSelector(guideEntries),
+    renderSlotChain: renderSlot,
+    // Copy is the dictionary's contract; the key stands in for the translation.
+    t: (key: string) => key,
+  } as unknown as GuideBodyProps
+  const view = render(<GuideBody {...props} />)
+  const boxes = (): string[] =>
+    [...view.container.querySelectorAll('[data-sidebar-right-guide-entry]')].map(node => node.getAttribute('data-sidebar-right-guide-entry') ?? '')
+  return { view, guideEntries, openTab, renderSlot, boxes, useTabInfo: props.useTabInfo }
+}
+
+describe('GuideBody', () => {
+  it('renders the chain with the same tab hook, and the shipped guide as its fallback', () => {
+    const { view, renderSlot, boxes, useTabInfo } = mountGuide([box('files', 10, Glyph), box('terminal', 20)])
+    expect(renderSlot).toHaveBeenCalledWith('sidebar.right.tab.guide', {}, {
+      hookContext: useTabInfo, fallback: expect.anything() as ReactNode,
+    })
+    const guide = view.container.querySelector('[data-sidebar-right-guide]')
+    expect(guide?.textContent).toContain('guide.lead')
+    expect(guide?.textContent).toContain('guide.body')
+    // One box per entry, in the registry's order, each with its own words; only the first brought a glyph.
+    expect(boxes()).toEqual(['files', 'terminal'])
+    const [files, terminal] = [...view.container.querySelectorAll('[data-sidebar-right-guide-entry]')]
+    expect(files?.textContent).toBe('files titlefiles description')
+    expect(files?.querySelector('[data-guide-glyph]')?.getAttribute('data-guide-glyph')).toBe('16')
+    expect(terminal?.querySelector('[data-guide-glyph]')).toBeNull()
+    cleanup()
+  })
+
+  it('picking a box opens that type in the guide\'s own place', () => {
+    const { view, openTab } = mountGuide([box('files', 10)])
+    const entry = view.container.querySelector('[data-sidebar-right-guide-entry="files"]')
+    if (entry === null) throw new Error('expected the files box')
+    fireEvent.click(entry)
+    expect(openTab).toHaveBeenCalledWith('files', { replaceTab: true })
+    cleanup()
+  })
+
+  it('draws the words alone while no type contributed an entry, and follows the registry when one does', () => {
+    const { view, guideEntries, boxes } = mountGuide([])
+    expect(view.container.querySelector('[data-sidebar-right-guide]')).not.toBeNull()
+    expect(boxes()).toEqual([])
+    act(() => { guideEntries.set([box('files', 10)]) })
+    expect(boxes()).toEqual(['files'])
+    cleanup()
+  })
+
+  it('keeps two boxes of one type at the same order apart', () => {
+    const errors = vi.spyOn(console, 'error').mockImplementation(() => {})
+    try {
+      const { boxes } = mountGuide([box('notes', 10), box('notes', 10)])
+      expect(boxes()).toEqual(['notes', 'notes'])
+      // React reports colliding keys through console.error; two boxes rendered
+      // without one is the whole assertion.
+      expect(errors).not.toHaveBeenCalled()
+    } finally {
+      errors.mockRestore()
+      cleanup()
+    }
+  })
+})
diff --git a/packages/client/ui-sidebar-right/tests/seat.client.spec.tsx b/packages/client/ui-sidebar-right/tests/seat.client.spec.tsx
new file mode 100644
index 0000000000..adf00ef762
--- /dev/null
+++ b/packages/client/ui-sidebar-right/tests/seat.client.spec.tsx
@@ -0,0 +1,510 @@
+// @vitest-environment jsdom
+/** Sidebar presentation and tab subscriptions through the production slot renderer. */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, fireEvent } from '@testing-library/react'
+import { useState } from 'react'
+import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
+import { LocaleRuntime } from '@deepseek-ai/dsh-client-locale/client'
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type { PaneId, SplitId, TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+import { dockPaneIds, getPane } from '@deepseek-ai/dsh-client-ui-dockkit'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { apply, inject } from '../src/client/index.ts'
+import { intentsFor } from '../src/client/shell/SidebarRight.tsx'
+import type { SidebarRightTabInfo, SidebarRightTabMenuOwnerProps } from '../src/client/contract/slots.ts'
+import type { createSidebarRightStore } from '../src/client/stores.ts'
+
+declare module '../src/client/contract/params.ts' {
+  interface SidebarRightResourceParamsMap {
+    test: { line?: number; x?: number }
+  }
+}
+
+const SESSION = 's-test' as SessionId
+const OTHER = 's-other' as SessionId
+const runtimes: SlotTestRuntime[] = []
+let getAnimationsDescriptor: PropertyDescriptor | undefined
+
+beforeEach(() => {
+  getAnimationsDescriptor = Object.getOwnPropertyDescriptor(Element.prototype, 'getAnimations')
+  Object.defineProperty(Element.prototype, 'getAnimations', { configurable: true, writable: true, value: () => [] })
+})
+
+afterEach(async () => {
+  try {
+    for (const runtime of runtimes.splice(0)) await runtime.dispose()
+  } finally {
+    vi.restoreAllMocks()
+    if (getAnimationsDescriptor === undefined) Reflect.deleteProperty(Element.prototype, 'getAnimations')
+    else Object.defineProperty(Element.prototype, 'getAnimations', getAnimationsDescriptor)
+  }
+})
+
+/** Browser-owned animation completion controlled independently of the test clock. */
+function transition(property = 'transform') {
+  const done = Promise.withResolvers<Animation>()
+  let state: AnimationPlayState = 'running'
+  const animation = {
+    transitionProperty: property,
+    get playState() { return state },
+    finished: done.promise,
+  } as CSSTransition
+  return {
+    animation,
+    finish: () => { state = 'finished'; done.resolve(animation) },
+    cancel: () => { state = 'idle'; done.reject(new DOMException('Transition canceled', 'AbortError')) },
+  }
+}
+
+async function mountSeat(viewportWidth = 1440, canShow = true) {
+  const runtime = await SlotTestRuntime.create()
+  runtimes.push(runtime)
+  const frame = { openRightbar: vi.fn(), closeRightbar: vi.fn() }
+  const pin = vi.fn<(address: string, signal: AbortSignal) => void>()
+  runtime.ctx.provide('layout', frame as never)
+  runtime.ctx.provide('resources', { pin } as never)
+  const locale = new LocaleRuntime(runtime.ctx)
+  runtime.ctx.provide('locale', locale)
+  runtime.slots.installLocale(locale)
+  await runtime.declare({
+    'rightbar': { kind: 'single', scope: 'session' },
+    'conversation.session.header.corner': { kind: 'single', scope: 'session' },
+  })
+  await runtime.sessions.add({ id: SESSION })
+  const feature = await runtime.mount({ inject: [...inject], apply })
+  const bodies = new Map<string, SidebarRightTabInfo>()
+  const titles = new Map<string, SidebarRightTabInfo>()
+  const hooks = new Map<string, PropsRuntime<'sidebar.right.pane.tab'>['useTabInfo']>()
+  let mounts = 0
+  function Body(props: PropsRuntime<'sidebar.right.pane.tab'>) {
+    const info = props.useTabInfo()
+    const [instance] = useState(() => ++mounts)
+    bodies.set(info.tab.id, info)
+    hooks.set(info.tab.id, props.useTabInfo)
+    expect(['tabInfo', 'tab', 'paneId', 'visible', 'navigation', 'signal', 'tabActions'].filter(key => key in props)).toEqual([])
+    return <span data-tab-body={info.tab.id} data-instance={instance} data-revision={info.tab.navigation.revision} />
+  }
+  function Title({ useTabInfo }: PropsRuntime<'sidebar.right.pane.tab.title'>) {
+    const info = useTabInfo()
+    titles.set(info.tab.id, info)
+    return <span data-tab-title={info.tab.id}>{info.tab.title}</span>
+  }
+  await act(async () => {
+    runtime.ctx.sidebarRightTabs.register({
+      id: 'test/text', kind: 'text', priority: 'builtin', patterns: ['dsh-resource://file/**'],
+      title: address => address.slice(address.lastIndexOf('/') + 1),
+    })
+    runtime.slots.register({ name: 'sidebar.right.pane.tab', key: 'test/text' }, Body)
+    runtime.slots.register({ name: 'sidebar.right.pane.tab.title', key: 'test/text' }, Title)
+  })
+  const view = runtime.renderSlot('rightbar', { width: 420, viewportWidth, canShow })
+  const instance = runtime.storeOf('rightbar', SESSION) as ReturnType<ReturnType<typeof createSidebarRightStore>['create']>
+  const controller = runtime.ctx.sidebarRight
+  const layout = () => instance.getSnapshot().bySession[SESSION]!.layout
+  const open = (name = 'a.txt', options?: Parameters<typeof controller.openResource>[1]) => {
+    act(() => { controller.openResource(`dsh-resource://file/session/s-test/${name}`, options) })
+    return controller.active()!
+  }
+  return { runtime, feature, controller, instance, actions: instance.actions, layout, open, frame, pin, bodies, titles, hooks, view }
+}
+
+function element(container: HTMLElement, selector: string): HTMLElement {
+  const node = container.querySelector<HTMLElement>(selector)
+  if (node === null) throw new Error(`expected ${selector}`)
+  return node
+}
+
+describe('RightbarSeat presentation', () => {
+  it('keeps the panel mounted while collapsed and releases the frame on unmount', async () => {
+    const h = await mountSeat()
+    const panel = element(h.view.container, '[data-sidebar-right-panel]')
+    expect(panel.getAttribute('aria-hidden')).toBe('true')
+    expect(h.frame.closeRightbar).toHaveBeenCalled()
+    h.open()
+    expect(element(h.view.container, '[data-sidebar-right-panel]')).toBe(panel)
+    expect(panel.hasAttribute('data-sidebar-right-open')).toBe(true)
+    expect(h.frame.openRightbar).toHaveBeenLastCalledWith(true, false)
+    await h.runtime.dispose()
+    expect(h.frame.closeRightbar).toHaveBeenCalled()
+  })
+
+  it('fills the viewport without replacing the content tree or releasing the wide track', async () => {
+    const h = await mountSeat()
+    const tab = h.open()
+    const panel = element(h.view.container, '[data-sidebar-right-panel]')
+    const body = element(h.view.container, '[data-tab-body]')
+    expect(panel.style.width).toBe('420px')
+    fireEvent.click(element(h.view.container, '[data-sidebar-right-mode]'))
+    expect(h.layout().mode).toBe('fullscreen')
+    expect(panel.style.width).toBe('100%')
+    expect(panel.dataset['sidebarRightPanel']).toBe('fullscreen')
+    expect(element(h.view.container, '[data-tab-body]')).toBe(body)
+    expect(h.frame.openRightbar).toHaveBeenLastCalledWith(true, true)
+    expect(h.bodies.get(tab.id)?.sidebar).toEqual({ expanded: true, fullscreen: true })
+    fireEvent.click(element(h.view.container, '[data-sidebar-right-mode]'))
+    expect(panel.style.width).toBe('420px')
+    expect(element(h.view.container, '[data-tab-body]')).toBe(body)
+    expect(h.frame.openRightbar).toHaveBeenLastCalledWith(true, false)
+    fireEvent.click(element(h.view.container, '[data-sidebar-right-toggle]'))
+    expect(h.layout().expanded).toBe(false)
+    expect(h.frame.closeRightbar).toHaveBeenCalled()
+  })
+
+  it('derives narrow fullscreen without recording mode and returns to normal when widened', async () => {
+    const h = await mountSeat(767, false)
+    h.open()
+    expect(h.layout().mode).toBe('push')
+    expect(h.frame.openRightbar).toHaveBeenLastCalledWith(false, true)
+    const stored = h.instance.getSnapshot()
+    const body = element(h.view.container, '[data-tab-body]')
+    h.view.update({ width: 420, viewportWidth: 768, canShow: true })
+    expect(h.instance.getSnapshot()).toBe(stored)
+    expect(element(h.view.container, '[data-tab-body]')).toBe(body)
+    expect(h.frame.openRightbar).toHaveBeenLastCalledWith(true, false)
+  })
+
+  it('closes on automatic fullscreen exit and stays closed after widening', async () => {
+    const h = await mountSeat(500, false)
+    const tab = h.open()
+    const signal = h.bodies.get(tab.id)!.tab.signal
+    fireEvent.click(element(h.view.container, '[data-sidebar-right-mode]'))
+    expect(h.layout().expanded).toBe(false)
+    expect(h.layout().mode).toBe('push')
+    const stored = h.instance.getSnapshot()
+    h.view.update({ width: 420, viewportWidth: 1440, canShow: true })
+    expect(h.instance.getSnapshot()).toBe(stored)
+    expect(h.layout().tabs[tab.id]).toBeDefined()
+    expect(signal.aborted).toBe(false)
+    expect(h.layout().expanded).toBe(false)
+  })
+
+  it('preserves manual fullscreen through narrow and wide viewport changes', async () => {
+    const h = await mountSeat()
+    h.open()
+    fireEvent.click(element(h.view.container, '[data-sidebar-right-mode]'))
+    const stored = h.instance.getSnapshot()
+    h.view.update({ width: 420, viewportWidth: 500, canShow: false })
+    expect(h.frame.openRightbar).toHaveBeenLastCalledWith(false, true)
+    h.view.update({ width: 420, viewportWidth: 1440, canShow: true })
+    expect(h.frame.openRightbar).toHaveBeenLastCalledWith(true, true)
+    expect(h.instance.getSnapshot()).toBe(stored)
+  })
+
+  it('collapses a normal panel that cannot fit without clearing records or reopening on growth', async () => {
+    const h = await mountSeat()
+    const tab = h.open()
+    const signal = h.bodies.get(tab.id)!.tab.signal
+    h.view.update({ width: 420, viewportWidth: 900, canShow: false })
+    expect(h.layout().expanded).toBe(false)
+    expect(h.layout().tabs[tab.id]).toBeDefined()
+    expect(signal.aborted).toBe(false)
+    const stored = h.instance.getSnapshot()
+    h.view.update({ width: 420, viewportWidth: 1440, canShow: true })
+    expect(h.instance.getSnapshot()).toBe(stored)
+    expect(h.layout().expanded).toBe(false)
+  })
+})
+
+describe('RightbarSeat fullscreen entry', () => {
+  it('retains the previous report until its transform finishes, then leaves the track in place on exit', async () => {
+    const h = await mountSeat()
+    act(() => { h.actions.setMode(SESSION, 'fullscreen') })
+    const panel = element(h.view.container, '[data-sidebar-right-panel]')
+    const slide = transition()
+    const unrelated = transition('opacity')
+    vi.spyOn(panel, 'getAnimations').mockReturnValue([slide.animation, unrelated.animation])
+    h.frame.closeRightbar.mockClear()
+    h.open()
+    expect(panel.hasAttribute('data-sidebar-right-open')).toBe(true)
+    expect(panel.dataset['sidebarRightPanel']).toBe('fullscreen')
+    expect(h.frame.openRightbar).not.toHaveBeenCalled()
+    expect(h.frame.closeRightbar).not.toHaveBeenCalled()
+    await act(async () => { slide.finish(); await slide.animation.finished })
+    expect(h.frame.openRightbar).toHaveBeenCalledExactlyOnceWith(true, true)
+    fireEvent.click(element(h.view.container, '[data-sidebar-right-mode]'))
+    expect(h.frame.openRightbar).toHaveBeenLastCalledWith(true, false)
+    unrelated.finish()
+  })
+
+  it('reports immediately without a transform transition, including zero-duration and reduced-motion entry', async () => {
+    const h = await mountSeat()
+    act(() => { h.actions.setMode(SESSION, 'fullscreen') })
+    const unrelated = transition('opacity')
+    const ended = transition()
+    ended.finish()
+    vi.spyOn(element(h.view.container, '[data-sidebar-right-panel]'), 'getAnimations')
+      .mockReturnValue([unrelated.animation, ended.animation])
+    h.open()
+    expect(h.frame.openRightbar).toHaveBeenCalledExactlyOnceWith(true, true)
+    unrelated.finish()
+  })
+
+  it('reports when reduced motion cancels the entering transition', async () => {
+    const h = await mountSeat(767, false)
+    const slide = transition()
+    vi.spyOn(element(h.view.container, '[data-sidebar-right-panel]'), 'getAnimations').mockReturnValue([slide.animation])
+    h.open()
+    expect(h.frame.openRightbar).not.toHaveBeenCalled()
+    await act(async () => { slide.cancel(); await Promise.allSettled([slide.animation.finished]) })
+    expect(h.frame.openRightbar).toHaveBeenCalledExactlyOnceWith(false, true)
+  })
+
+  it('waits for a replacement transform after cancellation', async () => {
+    const h = await mountSeat(767, false)
+    const first = transition()
+    const replacement = transition()
+    const animations = vi.spyOn(element(h.view.container, '[data-sidebar-right-panel]'), 'getAnimations')
+      .mockReturnValue([first.animation])
+    h.open()
+    animations.mockReturnValue([replacement.animation])
+    await act(async () => { first.cancel(); await Promise.allSettled([first.animation.finished]) })
+    expect(h.frame.openRightbar).not.toHaveBeenCalled()
+    await act(async () => { replacement.finish(); await replacement.animation.finished })
+    expect(h.frame.openRightbar).toHaveBeenCalledExactlyOnceWith(false, true)
+  })
+
+  it.each(['close', 'push', 'session', 'unmount'])('ignores a late completion after %s', async (change) => {
+    const h = await mountSeat()
+    act(() => { h.actions.setMode(SESSION, 'fullscreen') })
+    const slide = transition()
+    vi.spyOn(element(h.view.container, '[data-sidebar-right-panel]'), 'getAnimations').mockReturnValue([slide.animation])
+    h.open()
+    expect(h.frame.openRightbar).not.toHaveBeenCalled()
+    if (change === 'close') fireEvent.click(element(h.view.container, '[data-sidebar-right-toggle]'))
+    else if (change === 'push') fireEvent.click(element(h.view.container, '[data-sidebar-right-mode]'))
+    else if (change === 'session') {
+      await h.runtime.sessions.add({ id: OTHER })
+      act(() => { h.controller.openResource('dsh-resource://file/session/s-other/b.txt') })
+    } else await h.runtime.dispose()
+    const openCalls = [...h.frame.openRightbar.mock.calls]
+    const closeCalls = h.frame.closeRightbar.mock.calls.length
+    await act(async () => { slide.finish(); await slide.animation.finished })
+    expect(h.frame.openRightbar.mock.calls).toEqual(openCalls)
+    expect(h.frame.closeRightbar).toHaveBeenCalledTimes(closeCalls)
+  })
+
+  it('uses the current viewport report when entry crosses the fullscreen breakpoint', async () => {
+    const h = await mountSeat()
+    act(() => { h.actions.setMode(SESSION, 'fullscreen') })
+    const slide = transition()
+    vi.spyOn(element(h.view.container, '[data-sidebar-right-panel]'), 'getAnimations').mockReturnValue([slide.animation])
+    h.open()
+    h.view.update({ width: 420, viewportWidth: 500, canShow: false })
+    expect(h.frame.openRightbar).not.toHaveBeenCalled()
+    await act(async () => { slide.finish(); await slide.animation.finished })
+    expect(h.frame.openRightbar).toHaveBeenCalledExactlyOnceWith(false, true)
+  })
+
+  it('does not delay normal presentation behind its slide', async () => {
+    const h = await mountSeat()
+    const slide = transition()
+    const animations = vi.spyOn(element(h.view.container, '[data-sidebar-right-panel]'), 'getAnimations')
+      .mockReturnValue([slide.animation])
+    h.open()
+    expect(h.frame.openRightbar).toHaveBeenCalledExactlyOnceWith(true, false)
+    expect(animations).not.toHaveBeenCalled()
+    slide.finish()
+  })
+})
+
+describe('slot-owned useTabInfo', () => {
+  it('updates body and title navigation with no layout commit and retains the bound hook', async () => {
+    const h = await mountSeat()
+    const tab = h.open('a.txt', { params: { line: 3 } })
+    const stored = h.instance.getSnapshot()
+    const hook = h.hooks.get(tab.id)
+    const signal = h.bodies.get(tab.id)!.tab.signal
+    act(() => { h.controller.tabDomain.navigate(SESSION, tab.id, { address: tab.contentId, params: { line: 7 } }) })
+    expect(h.instance.getSnapshot()).toBe(stored)
+    expect(h.hooks.get(tab.id)).toBe(hook)
+    expect(h.bodies.get(tab.id)?.tab.navigation).toEqual({ address: tab.contentId, params: { line: 7 }, revision: 2 })
+    expect(h.titles.get(tab.id)?.tab.navigation).toBe(h.bodies.get(tab.id)?.tab.navigation)
+    expect(h.bodies.get(tab.id)?.tab.signal).toBe(signal)
+    expect(element(h.view.container, '[data-tab-body]').dataset['revision']).toBe('2')
+  })
+
+  it('isolates same-kind record state and reports inactive titles, hiding, floating and docking', async () => {
+    const h = await mountSeat()
+    const a = h.open('a.txt')
+    const b = h.open('b.txt')
+    const bodyB = element(h.view.container, '[data-tab-body]')
+    expect(h.titles.get(a.id)?.tab.visible).toBe(true)
+    act(() => { h.actions.focusTab(SESSION, a.id) })
+    const bodyA = element(h.view.container, '[data-tab-body]')
+    expect(bodyA.dataset['instance']).not.toBe(bodyB.dataset['instance'])
+    expect(bodyA.dataset['tabBody']).toBe(a.id)
+    const signal = h.bodies.get(a.id)!.tab.signal
+    act(() => { h.actions.setExpanded(SESSION, false) })
+    expect(h.bodies.get(a.id)?.tab.visible).toBe(false)
+    expect(h.titles.get(a.id)?.tab.visible).toBe(false)
+    expect(h.titles.get(b.id)?.tab.visible).toBe(false)
+    expect(element(h.view.container, '[data-tab-body]')).toBe(bodyA)
+    expect(signal.aborted).toBe(false)
+    act(() => { h.controller.float(a.id) })
+    expect(h.bodies.get(a.id)?.tab.visible).toBe(true)
+    const paneId = h.bodies.get(a.id)!.panel.id
+    expect(h.layout().floats).toContain(paneId)
+    act(() => { h.controller.dock(paneId) })
+    expect(h.layout().floats).toHaveLength(0)
+    expect(h.bodies.get(a.id)?.tab.signal).toBe(signal)
+  })
+
+  it('keeps session records and navigation while unmounted, aborting only removal and plugin unload', async () => {
+    const h = await mountSeat()
+    const own = h.open()
+    const info = h.bodies.get(own.id)!
+    const stored = h.instance.getSnapshot()
+    await h.runtime.sessions.add({ id: OTHER })
+    expect(h.instance.getSnapshot()).toBe(stored)
+    expect(info.tab.signal.aborted).toBe(false)
+    act(() => { h.controller.openResource('dsh-resource://file/session/s-other/other.txt', { params: { line: 9 } }) })
+    const otherTab = h.controller.active()!
+    expect(otherTab.id).toBe(own.id)
+    const otherInfo = h.bodies.get(otherTab.id)!
+    expect(otherInfo.tab.signal).not.toBe(info.tab.signal)
+    act(() => { info.tab.actions.openResource('dsh-resource://file/session/s-test/b.txt') })
+    expect(Object.values(h.layout().tabs).map(tab => tab.title)).toContain('b.txt')
+    expect(h.controller.active()?.contentId).toBe(otherTab.contentId)
+    expect(h.bodies.get(otherTab.id)?.tab.navigation.params).toEqual({ line: 9 })
+    act(() => { info.tab.actions.close() })
+    expect(info.tab.signal.aborted).toBe(true)
+    expect(otherInfo.tab.signal.aborted).toBe(false)
+    await h.runtime.sessions.setCurrent(SESSION)
+    const remaining = h.bodies.get(h.controller.active()!.id)!
+    expect(remaining.tab.navigation.revision).toBe(1)
+    await h.feature.dispose()
+    expect(remaining.tab.signal.aborted).toBe(true)
+    expect(otherInfo.tab.signal.aborted).toBe(true)
+    expect(h.runtime.ctx.get('sidebarRight')).toBeUndefined()
+  })
+
+  it('updates guide replacements through the same hook and guide boxes through framework injection', async () => {
+    const h = await mountSeat()
+    let captured: SidebarRightTabInfo | undefined
+    await act(async () => {
+      h.runtime.ctx.sidebarRightTabs.register({
+        id: 'test/files', kind: 'files', title: () => 'Files',
+        guide: [{ order: 1, title: () => 'Files', description: () => 'Browse' }],
+      })
+    })
+    expect(h.view.container.querySelector('[data-sidebar-right-guide-entry="files"]')).not.toBeNull()
+    await act(async () => {
+      h.runtime.slots.register({ name: 'sidebar.right.tab.guide', select: () => true },
+        ({ useTabInfo }: PropsRuntime<'sidebar.right.tab.guide'>) => {
+          captured = useTabInfo()
+          return <span data-guide-replacement={captured.tab.navigation.revision} />
+        })
+    })
+    expect(h.view.container.querySelector('[data-sidebar-right-guide]')).toBeNull()
+    expect(captured?.tab.kind).toBe('guide')
+    act(() => { h.controller.openTab('guide') })
+    const stored = h.instance.getSnapshot()
+    const guide = h.controller.active()!
+    act(() => { h.controller.tabDomain.navigate(SESSION, guide.id, { address: guide.contentId, params: undefined }) })
+    expect(h.instance.getSnapshot()).toBe(stored)
+    expect(captured?.tab.navigation.revision).toBe(2)
+    expect(element(h.view.container, '[data-guide-replacement]').dataset['guideReplacement']).toBe('2')
+    expect(captured?.sidebar.expanded).toBe(true)
+  })
+
+  it('follows type replacement and returns to the builtin when it leaves', async () => {
+    const h = await mountSeat()
+    h.open()
+    let release = () => {}
+    await act(async () => {
+      release = h.runtime.ctx.sidebarRightTabs.register({ id: 'extension/text', kind: 'text', title: () => 'Extension' })
+      h.runtime.slots.register({ name: 'sidebar.right.pane.tab', key: 'extension/text' },
+        ({ useTabInfo }: PropsRuntime<'sidebar.right.pane.tab'>) => <b data-extension>{useTabInfo().tab.title}</b>)
+    })
+    expect(element(h.view.container, '[data-extension]').textContent).toBe('a.txt')
+    await act(async () => { release() })
+    expect(h.view.container.querySelector('[data-extension]')).toBeNull()
+    expect(h.view.container.querySelector('[data-tab-body]')).not.toBeNull()
+  })
+
+  it('renders unavailable kinds and keeps menu tab/dismiss arguments', async () => {
+    const h = await mountSeat()
+    let menu: SidebarRightTabMenuOwnerProps | undefined
+    await act(async () => {
+      h.runtime.slots.register({ name: 'sidebar.right.tab.menu.item', id: 'test' },
+        (props: PropsRuntime<'sidebar.right.tab.menu.item'>) => { menu = props; return null })
+      h.actions.openContent(SESSION, { kind: 'missing', contentId: 'missing://content', title: 'Missing' }, () => {})
+    })
+    expect(h.view.container.querySelector('[data-sidebar-right-unavailable]')).not.toBeNull()
+    const chip = element(h.view.container, '[data-dockkit-tab]')
+    fireEvent.contextMenu(chip)
+    expect(menu?.tab.id).toBe(chip.getAttribute('data-dockkit-tab'))
+    act(() => { menu?.dismiss() })
+    expect(document.querySelector('[data-dockkit-tab-menu]')).toBeNull()
+  })
+
+  it('hides split controls at two panes and adds a guide only to a pane without one', async () => {
+    const h = await mountSeat()
+    h.open()
+    const splitButtons = () => h.view.container.querySelectorAll<HTMLButtonElement>('[data-dockkit-split-button]')
+    expect(splitButtons()).toHaveLength(1)
+    act(() => { h.controller.split() })
+    expect(dockPaneIds(h.layout())).toHaveLength(2)
+    const stored = h.instance.getSnapshot()
+    act(() => { expect(h.controller.split()).toBeUndefined() })
+    expect(h.instance.getSnapshot()).toBe(stored)
+    expect(splitButtons()).toHaveLength(0)
+    const right = dockPaneIds(h.layout())[1]!
+    h.open('right.txt', { paneId: right })
+    const guide = getPane(h.layout(), right).tabs.find(id => h.layout().tabs[id]?.kind === 'guide')!
+    act(() => { h.actions.closeTab(SESSION, guide) })
+    const add = element(h.view.container, '[data-dockkit-add-tab]')
+    expect(add.closest('[data-dockkit-pane]')?.getAttribute('data-dockkit-pane')).toBe(right)
+    fireEvent.click(add)
+    expect(getPane(h.layout(), right).tabs.filter(id => h.layout().tabs[id]?.kind === 'guide')).toHaveLength(1)
+    const closing = [...getPane(h.layout(), right).tabs]
+    act(() => { for (const tabId of closing) h.actions.closeTab(SESSION, tabId) })
+    expect(dockPaneIds(h.layout())).toHaveLength(1)
+    expect(splitButtons()).toHaveLength(1)
+    expect(splitButtons()[0]?.disabled).toBe(false)
+  })
+})
+
+describe('intentsFor — the kit\'s gestures as one session\'s store actions', () => {
+  it('binds every intent to the session, and asks the navigation face for a guide on add', () => {
+    const actions = {
+      focusTab: vi.fn(), focusPane: vi.fn(), splitPane: vi.fn(), closeTab: vi.fn(), duplicateTab: vi.fn(),
+      floatTab: vi.fn(), unfloatPane: vi.fn(), placeTab: vi.fn(), dropTab: vi.fn(), moveFloat: vi.fn(),
+      resizeFloat: vi.fn(), resizeSplit: vi.fn(),
+    }
+    const openTab = vi.fn()
+    const intents = intentsFor(SESSION, actions as unknown as Parameters<typeof intentsFor>[1], openTab)
+    const rect = { x: 1, y: 2, width: 300, height: 200 }
+    const TAB_1 = 'tab-1' as TabId
+    const PANE_1 = 'pane-1' as PaneId
+    const PANE_2 = 'pane-2' as PaneId
+    const SPLIT_1 = 'split-1' as SplitId
+    intents.focusTab(TAB_1)
+    intents.focusPane(PANE_1)
+    intents.splitPane(PANE_1)
+    intents.closeTab(TAB_1)
+    intents.duplicateTab(TAB_1)
+    intents.floatTab(TAB_1, rect)
+    intents.unfloatPane(PANE_2)
+    intents.placeTab(TAB_1, PANE_1, 0)
+    intents.dropTab(TAB_1, PANE_1, 'right')
+    intents.moveFloat(PANE_2, 30, 40)
+    intents.resizeFloat(PANE_2, rect)
+    intents.resizeSplit(SPLIT_1, [0.3, 0.7])
+    expect(actions.focusTab).toHaveBeenCalledWith(SESSION, TAB_1)
+    expect(actions.focusPane).toHaveBeenCalledWith(SESSION, PANE_1)
+    expect(actions.splitPane).toHaveBeenCalledWith(SESSION, PANE_1)
+    expect(actions.closeTab).toHaveBeenCalledWith(SESSION, TAB_1)
+    expect(actions.duplicateTab).toHaveBeenCalledWith(SESSION, TAB_1)
+    expect(actions.floatTab).toHaveBeenCalledWith(SESSION, TAB_1, rect)
+    expect(actions.unfloatPane).toHaveBeenCalledWith(SESSION, PANE_2)
+    expect(actions.placeTab).toHaveBeenCalledWith(SESSION, TAB_1, PANE_1, 0)
+    expect(actions.dropTab).toHaveBeenCalledWith(SESSION, TAB_1, PANE_1, 'right')
+    expect(actions.moveFloat).toHaveBeenCalledWith(SESSION, PANE_2, 30, 40)
+    expect(actions.resizeFloat).toHaveBeenCalledWith(SESSION, PANE_2, rect)
+    expect(actions.resizeSplit).toHaveBeenCalledWith(SESSION, SPLIT_1, [0.3, 0.7])
+    // The add control is the guide opened by kind, in that pane, beside any guide elsewhere.
+    intents.addTab(PANE_1)
+    expect(openTab).toHaveBeenCalledWith('guide', { paneId: PANE_1, revealIfOpened: false })
+  })
+})
diff --git a/packages/client/ui-sidebar-right/tests/service.client.spec.ts b/packages/client/ui-sidebar-right/tests/service.client.spec.ts
new file mode 100644
index 0000000000..6e1c4025e7
--- /dev/null
+++ b/packages/client/ui-sidebar-right/tests/service.client.spec.ts
@@ -0,0 +1,580 @@
+/**
+ * What `ctx.sidebarRight` promises other plugins.
+ *
+ * The service is root-scoped and the surface is per session, so every command
+ * depends on a binding the mounted seat publishes; the interesting cases are all
+ * about that seam. Opening is asserted against a real store instance, because
+ * "already open" and "in that tab's place" mean whatever the planner means by
+ * them and nothing else, and against the Tab domain, because an open is not
+ * complete until the tab knows how it was navigated to.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { LayoutState, PaneId, TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+import { dockPaneIds, findTabPane, getPane } from '@deepseek-ai/dsh-client-ui-dockkit'
+import { createSidebarRightController } from '../src/client/service.ts'
+import { SidebarRightTabRegistry } from '../src/client/tab-registry.ts'
+import { createSidebarRightStore } from '../src/client/stores.ts'
+import { guideDefinition } from '../src/client/tabs/guide/definition.ts'
+
+// The params map is empty in this package; a test-only scheme lets specs hand
+// parameters through the typed `open`/`navigate` faces.
+declare module '../src/client/contract/params.ts' {
+  interface SidebarRightResourceParamsMap {
+    test: { line?: number; x?: number }
+  }
+}
+
+const SESSION = 's-test' as SessionId
+
+/** Key-echoing translate: this file asserts behaviour, not copy. */
+const t = ((key: string) => key) as Parameters<typeof guideDefinition>[0]
+
+/** A controller over a real registry and a real store, bound as a mounted seat would be. */
+function harness() {
+  const ctx = new Context()
+  const tabs = new SidebarRightTabRegistry(ctx)
+  tabs.register(guideDefinition(t))
+  // A type claiming `file:` addresses, standing in for whatever package owns
+  // them: this service's contract is that SOME registered type claims, not that
+  // a particular one does.
+  tabs.register({
+    id: 'test/text',
+    kind: 'text',
+    patterns: ['dsh-resource://file/**'],
+    priority: 'fallback',
+    title: address => address.slice(address.lastIndexOf('/') + 1),
+  })
+  const pin = vi.fn<(address: string, signal: AbortSignal) => void>()
+  const { controller, adopt } = createSidebarRightController(tabs, pin)
+  const instance = createSidebarRightStore(() => 'seed').create()
+  const layout = (): LayoutState => {
+    const surface = instance.getSnapshot().bySession[SESSION]
+    if (surface === undefined) throw new Error('expected a surface')
+    return surface.layout
+  }
+  /** Republish the way the seat does after each commit, and sync the domain the way it does too. */
+  /** The room rule's verdict the seat would report; a spec flips it to model a narrow pane. */
+  const room = { allowed: true }
+  const publish = (): (() => void) => {
+    const surface = instance.getSnapshot().bySession[SESSION]
+    if (surface !== undefined) controller.tabDomain.sync(SESSION, surface.layout)
+    return controller.bind({
+      sessionId: SESSION, actions: instance.actions, surfaces: instance.getSnapshot().bySession, canSplitPane: () => room.allowed,
+    })
+  }
+  const titles = (): string[] => {
+    const surface = instance.getSnapshot().bySession[SESSION]
+    return surface === undefined ? [] : Object.values(surface.layout.tabs).map(tab => tab.title)
+  }
+  const tabOf = (title: string): TabId => {
+    const found = Object.values(layout().tabs).find(tab => tab.title === title)
+    if (found === undefined) throw new Error(`expected a tab titled ${title}`)
+    return found.id
+  }
+  const entries = (): number => instance.getSnapshot().bySession[SESSION]?.history.entries.length ?? 0
+  return { controller, adopt, tabs, instance, pin, publish, titles, tabOf, layout, entries, room }
+}
+
+describe('SidebarRightController — opening', () => {
+  it('refuses every write while no seat is mounted', () => {
+    const { controller } = harness()
+    expect(() => { controller.openResource('dsh-resource://file/session/s-test/a.txt') }).toThrow('no session surface is mounted')
+    expect(() => { controller.openTab('guide') }).toThrow('no session surface is mounted')
+    expect(() => { controller.close('tab1' as TabId) }).toThrow('no session surface is mounted')
+    expect(() => { controller.toggleExpanded() }).toThrow('no session surface is mounted')
+    expect(() => { controller.focus('tab1' as TabId) }).toThrow('no session surface is mounted')
+    expect(() => { controller.split() }).toThrow('no session surface is mounted')
+    expect(() => { controller.float('tab1' as TabId) }).toThrow('no session surface is mounted')
+    expect(() => { controller.dock('pane1' as PaneId) }).toThrow('no session surface is mounted')
+  })
+
+  it('refuses an address no registered type claims, before touching the surface', () => {
+    const { controller, publish, titles } = harness()
+    publish()
+    expect(() => { controller.openResource('https://example.com') }).toThrow('no registered tab type claims')
+    expect(titles()).toEqual([])
+  })
+
+  it('opens claimed content and reveals the column in one history entry', () => {
+    const { controller, publish, layout, titles, entries } = harness()
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/notes/readme.txt')
+    expect(layout().expanded).toBe(true)
+    expect(titles()).toContain('readme.txt')
+    // One intent, one entry: stepping back removes the tab and re-collapses.
+    expect(entries()).toBe(1)
+    publish()
+    controller._undo()
+    expect(layout().expanded).toBe(false)
+    expect(titles()).not.toContain('readme.txt')
+  })
+
+  it('focuses the tab already showing the same (kind, contentId) instead of opening a second one', () => {
+    const { controller, publish, titles, layout, tabOf } = harness()
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/notes/readme.txt')
+    publish()
+    controller.openTab('guide')
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/notes/readme.txt')
+    expect(titles().filter(title => title === 'readme.txt')).toHaveLength(1)
+    expect(getPane(layout(), layout().activePaneId).activeTabId).toBe(tabOf('readme.txt'))
+  })
+
+  it('opens another tab for the same address when told not to reveal, and when another kind is named', () => {
+    const { controller, tabs, publish, titles } = harness()
+    tabs.register({ id: 'test/hex', kind: 'hex', patterns: [], title: () => 'hex view' })
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/notes/readme.txt')
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/notes/readme.txt', { revealIfOpened: false })
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/notes/readme.txt', { kind: 'hex' })
+    expect(titles().filter(title => title === 'readme.txt')).toHaveLength(2)
+    expect(titles()).toContain('hex view')
+  })
+
+  it('lands a new tab in the pane the caller names', () => {
+    const { controller, instance, publish, layout, tabOf } = harness()
+    publish()
+    instance.actions.splitPane(SESSION)
+    publish()
+    const [left, right] = Object.values(layout().nodes).filter(node => node.kind === 'pane').map(node => node.id)
+    if (left === undefined || right === undefined) throw new Error('expected two panes')
+    controller.openResource('dsh-resource://file/session/s-test/a.txt', { paneId: left })
+    expect(findTabPane(layout(), tabOf('a.txt')).id).toBe(left)
+  })
+
+  it('takes the replaced tab\'s pane and slot, closes it, and records one entry', () => {
+    const { controller, publish, layout, tabOf, entries } = harness()
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/a.txt')
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/b.txt')
+    publish()
+    const a = tabOf('a.txt')
+    const before = entries()
+    controller.openResource('dsh-resource://file/session/s-test/c.txt', { replaceTab: a })
+    const pane = findTabPane(layout(), tabOf('c.txt'))
+    // The seeded guide sits at 0; a took 1; c took a's slot.
+    expect(pane.tabs.indexOf(tabOf('c.txt'))).toBe(1)
+    expect(layout().tabs[a]).toBeUndefined()
+    expect(entries()).toBe(before + 1)
+    publish()
+    controller._undo()
+    expect(layout().tabs[a]).toBeDefined()
+    expect(Object.values(layout().tabs).map(tab => tab.title)).not.toContain('c.txt')
+  })
+
+  it('still closes the replaced tab when the address is already open elsewhere', () => {
+    const { controller, publish, layout, tabOf, titles } = harness()
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/a.txt')
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/b.txt')
+    publish()
+    const spare = tabOf('b.txt')
+    controller.openResource('dsh-resource://file/session/s-test/a.txt', { replaceTab: spare })
+    expect(layout().tabs[spare]).toBeUndefined()
+    expect(titles().filter(title => title === 'a.txt')).toHaveLength(1)
+    expect(getPane(layout(), layout().activePaneId).activeTabId).toBe(tabOf('a.txt'))
+  })
+
+  it('refuses to copy the guide, and records nothing for the attempt', () => {
+    const { controller, instance, publish, layout, tabOf, entries } = harness()
+    instance.actions.open(SESSION)
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/a.txt')
+    publish()
+    const before = entries()
+    instance.actions.duplicateTab(SESSION, tabOf('seed'))
+    expect(Object.values(layout().tabs).filter(tab => tab.contentId === 'sidebar://guide')).toHaveLength(1)
+    expect(entries()).toBe(before)
+    // Any other tab still copies beside itself.
+    instance.actions.duplicateTab(SESSION, tabOf('a.txt'))
+    expect(Object.values(layout().tabs).filter(tab => tab.title === 'a.txt')).toHaveLength(2)
+  })
+
+  it('reveals an open guide for a plain open, as for any address', () => {
+    const { controller, instance, publish, layout, tabOf } = harness()
+    instance.actions.open(SESSION)
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/a.txt')
+    publish()
+    controller.openTab('guide')
+    expect(Object.values(layout().tabs).filter(tab => tab.contentId === 'sidebar://guide')).toHaveLength(1)
+    expect(getPane(layout(), layout().activePaneId).activeTabId).toBe(tabOf('seed'))
+  })
+
+  it('keeps the guide to one per pane: opening it into a pane that holds one settles on that one', () => {
+    const { controller, instance, publish, layout, tabOf } = harness()
+    instance.actions.open(SESSION)
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/a.txt')
+    publish()
+    const root = getPane(layout(), layout().rootId).id
+    let settled: TabId | undefined
+    instance.actions.openContent(SESSION, {
+      kind: 'guide', contentId: 'sidebar://guide', title: 'seed', paneId: root, revealIfOpened: false,
+    }, (tabId) => { settled = tabId })
+    expect(settled).toBe(tabOf('seed'))
+    expect(Object.values(layout().tabs).filter(tab => tab.contentId === 'sidebar://guide')).toHaveLength(1)
+    // A pane without one gets its own.
+    instance.actions.closeTab(SESSION, tabOf('seed'))
+    instance.actions.openContent(SESSION, {
+      kind: 'guide', contentId: 'sidebar://guide', title: 'seed', paneId: root, revealIfOpened: false,
+    }, () => {})
+    expect(Object.values(layout().tabs).filter(tab => tab.contentId === 'sidebar://guide')).toHaveLength(1)
+  })
+
+  it('merges a guide placed, dropped, or docked into a pane that already holds one', () => {
+    const { instance, publish, layout } = harness()
+    instance.actions.open(SESSION)
+    publish()
+    const guides = (): TabId[] => Object.values(layout().tabs).filter(tab => tab.contentId === 'sidebar://guide').map(tab => tab.id)
+    // Place: the split's guide dragged into the first pane's strip.
+    instance.actions.splitPane(SESSION)
+    let [left, right] = dockPaneIds(layout())
+    if (left === undefined || right === undefined) throw new Error('expected two panes')
+    const [own] = getPane(layout(), left).tabs
+    const arrivingByPlace = getPane(layout(), right).tabs[0]
+    if (own === undefined || arrivingByPlace === undefined) throw new Error('expected seeded guides')
+    instance.actions.placeTab(SESSION, arrivingByPlace, left, 0)
+    expect(guides()).toEqual([own])
+    expect(dockPaneIds(layout())).toHaveLength(1)
+    expect(getPane(layout(), left).activeTabId).toBe(own)
+    // Drop on the centre: the same merge. An edge drop makes a new pane and keeps both.
+    instance.actions.splitPane(SESSION)
+    ;[left, right] = dockPaneIds(layout())
+    if (left === undefined || right === undefined) throw new Error('expected two panes')
+    const arrivingByDrop = getPane(layout(), right).tabs[0]
+    if (arrivingByDrop === undefined) throw new Error('expected the seeded guide')
+    instance.actions.dropTab(SESSION, arrivingByDrop, left, 'right')
+    expect(guides()).toHaveLength(2)
+    instance.actions.dropTab(SESSION, arrivingByDrop, left, 'center')
+    expect(guides()).toEqual([own])
+    // Dock: a floating guide returning to a pane that reseeded its own.
+    instance.actions.floatTab(SESSION, own)
+    expect(layout().floats).toHaveLength(1)
+    const reseeded = guides().find(id => id !== own)
+    if (reseeded === undefined) throw new Error('expected the root to reseed a guide')
+    const [float] = layout().floats
+    if (float === undefined) throw new Error('expected the float')
+    instance.actions.unfloatPane(SESSION, float)
+    expect(layout().floats).toHaveLength(0)
+    expect(guides()).toEqual([reseeded])
+  })
+
+  it('records the navigation in the Tab domain: params delivered, revision counting every open', () => {
+    const { controller, publish, tabOf } = harness()
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/a.txt', { params: { line: 3 } })
+    const occurrence = controller.tabDomain.occurrence(SESSION, { id: tabOf('a.txt') })
+    expect(occurrence.navigation.getSnapshot()).toEqual({ address: 'dsh-resource://file/session/s-test/a.txt', params: { line: 3 }, revision: 1 })
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/a.txt')
+    expect(occurrence.navigation.getSnapshot()).toEqual({ address: 'dsh-resource://file/session/s-test/a.txt', params: undefined, revision: 2 })
+  })
+
+  it('closes a tab of the mounted session', () => {
+    const { controller, publish, tabOf, titles } = harness()
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/a.txt')
+    publish()
+    controller.close(tabOf('a.txt'))
+    expect(titles()).not.toContain('a.txt')
+  })
+
+  it('records the presentation switch, so it steps back with everything else', () => {
+    const { controller, instance, publish, layout } = harness()
+    publish()
+    instance.actions.setMode(SESSION, 'fullscreen')
+    expect(layout().mode).toBe('fullscreen')
+    publish()
+    controller._undo()
+    expect(layout().mode).toBe('push')
+    controller._redo()
+    expect(layout().mode).toBe('fullscreen')
+  })
+})
+
+describe('SidebarRightController — the two opens', () => {
+  it('refuses an address outside dsh-resource:// on the same path as an unclaimed one', () => {
+    const { controller, instance, publish, entries } = harness()
+    instance.actions.open(SESSION)
+    publish()
+    const before = entries()
+    expect(() => { controller.openResource('sidebar://guide') }).toThrow('no registered tab type claims')
+    expect(() => { controller.openResource('https://example.com/a.txt') }).toThrow('no registered tab type claims')
+    expect(() => { controller.openResource('dsh-resource://unknown/x') }).toThrow('no registered tab type claims')
+    expect(entries()).toBe(before)
+  })
+
+  it('opens a page by kind at the address the package records it under, and refuses an unregistered kind', () => {
+    const { controller, instance, publish, layout, entries } = harness()
+    instance.actions.open(SESSION)
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/a.txt')
+    publish()
+    // The seeded guide is the page in force: opening it by kind reveals that tab.
+    controller.openTab('guide')
+    publish()
+    expect(Object.values(layout().tabs).filter(tab => tab.contentId === 'sidebar://guide')).toHaveLength(1)
+    expect(controller.active()?.kind).toBe('guide')
+    const before = entries()
+    expect(() => { controller.openTab('nope') }).toThrow('no tab type is registered as "nope"')
+    expect(entries()).toBe(before)
+  })
+
+  it('replaceTab opens in the named tab\'s place and closes it, as one entry', () => {
+    const { controller, instance, publish, layout, tabOf, entries } = harness()
+    instance.actions.open(SESSION)
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/a.txt')
+    publish()
+    const before = entries()
+    controller.openTab('guide', { replaceTab: tabOf('a.txt') })
+    expect(Object.values(layout().tabs).map(tab => tab.title)).toEqual(['seed'])
+    expect(entries()).toBe(before + 1)
+  })
+})
+
+describe('SidebarRightController — layout operations', () => {
+  it('focuses an existing tab and its pane, and leaves a missing tab alone', () => {
+    const { controller, publish, layout, tabOf, entries } = harness()
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/a.txt')
+    publish()
+    expect(getPane(layout(), layout().activePaneId).activeTabId).toBe(tabOf('a.txt'))
+    const before = entries()
+    controller.focus(tabOf('seed'))
+    expect(getPane(layout(), layout().activePaneId).activeTabId).toBe(tabOf('seed'))
+    expect(entries()).toBe(before + 1)
+    controller.focus('tab-nowhere' as TabId)
+    expect(entries()).toBe(before + 1)
+  })
+
+  it('splits nothing before the seat has materialized the surface', () => {
+    const { controller, publish } = harness()
+    publish()
+    expect(controller.split()).toBeUndefined()
+  })
+
+  it('splits the active docked pane and names the new one, or nothing when the budget or the room rule says no', () => {
+    const { controller, instance, publish, layout, entries, room } = harness()
+    instance.actions.open(SESSION)
+    publish()
+    const created = controller.split()
+    expect(created).toBeDefined()
+    expect(dockPaneIds(layout())).toHaveLength(2)
+    expect(dockPaneIds(layout())).toContain(created)
+    publish()
+    // The room rule blocks: nothing is split and nothing is recorded.
+    room.allowed = false
+    const before = entries()
+    expect(controller.split()).toBeUndefined()
+    expect(entries()).toBe(before)
+    room.allowed = true
+    // A floating pane cannot be split.
+    const seed = Object.values(layout().tabs).find(tab => tab.title === 'seed')
+    if (seed === undefined) throw new Error('expected the seeded guide')
+    controller.float(seed.id)
+    publish()
+    const [float] = layout().floats
+    expect(controller.split(float)).toBeUndefined()
+    // The budget: split to two panes, then no more.
+    while (dockPaneIds(layout()).length < 2) {
+      expect(controller.split(dockPaneIds(layout()).at(-1))).toBeDefined()
+      publish()
+    }
+    expect(controller.split()).toBeUndefined()
+  })
+
+  it('floats a docked tab, and leaves a floating or missing tab alone', () => {
+    const { controller, publish, layout, tabOf, entries } = harness()
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/a.txt')
+    publish()
+    controller.float(tabOf('a.txt'), { x: 10, y: 20, width: 300, height: 200 })
+    expect(layout().floats).toHaveLength(1)
+    expect(findTabPane(layout(), tabOf('a.txt')).rect).toEqual({ x: 10, y: 20, width: 300, height: 200 })
+    publish()
+    const before = entries()
+    controller.float(tabOf('a.txt'))
+    controller.float('tab-nowhere' as TabId)
+    expect(entries()).toBe(before)
+    expect(layout().floats).toHaveLength(1)
+  })
+
+  it('docks a floating panel back into the active docked pane, and leaves a docked or missing pane alone', () => {
+    const { controller, publish, layout, tabOf, entries } = harness()
+    publish()
+    controller.openResource('dsh-resource://file/session/s-test/a.txt')
+    publish()
+    controller.float(tabOf('a.txt'))
+    publish()
+    const [float] = layout().floats
+    if (float === undefined) throw new Error('expected a float')
+    controller.dock(float)
+    expect(layout().floats).toHaveLength(0)
+    expect(findTabPane(layout(), tabOf('a.txt')).host).toBe('dock')
+    publish()
+    const before = entries()
+    controller.dock(getPane(layout(), layout().rootId).id)
+    controller.dock('pane-nowhere' as PaneId)
+    expect(entries()).toBe(before)
+  })
+})
+
+describe('SidebarRightController — a tab\'s own actions', () => {
+  const OTHER = 's-other' as SessionId
+  const A_TXT = 'dsh-resource://file/session/s-test/a.txt'
+  const B_TXT = 'dsh-resource://file/session/s-test/b.txt'
+
+  it('land in the session the tab is in through its own adopted store, after another session\'s seat took over', () => {
+    const { controller, adopt, instance, publish, layout } = harness()
+    const releaseOwn = adopt(SESSION, instance)
+    publish()
+    controller.openResource(A_TXT)
+    const own = Object.values(layout().tabs).find(tab => tab.title === 'a.txt')
+    const guide = Object.values(layout().tabs).find(tab => tab.kind === 'guide')
+    if (own === undefined || guide === undefined) throw new Error('expected the opened tab and the seeded guide')
+    const fromOwn = controller.tabDomain.occurrence(SESSION, own).tabActions
+    const guideOccurrence = controller.tabDomain.occurrence(SESSION, guide)
+    // The user switches sessions: the other seat binds with the other session's
+    // own instance, whose store knows nothing of this session.
+    const other = createSidebarRightStore(() => 'seed').create(OTHER)
+    const releaseOther = adopt(OTHER, other)
+    other.actions.open(OTHER)
+    const otherSurface = other.getSnapshot().bySession[OTHER]
+    if (otherSurface === undefined) throw new Error('expected the other surface')
+    controller.bind({ sessionId: OTHER, actions: other.actions, surfaces: other.getSnapshot().bySession, canSplitPane: () => true })
+    fromOwn.openResource(B_TXT)
+    fromOwn.openTab('guide', { revealIfOpened: false })
+    expect(Object.values(layout().tabs).map(tab => tab.title)).toContain('b.txt')
+    expect(other.getSnapshot().bySession[OTHER]).toBe(otherSurface)
+    // Tab ids repeat across sessions: the seeded guides share one. Closing this
+    // session's closes this session's, aborts its occurrence at once although
+    // no seat draws the session, and the other keeps its own.
+    expect(otherSurface.layout.tabs[guide.id]).toBeDefined()
+    guideOccurrence.tabActions.close()
+    expect(layout().tabs[guide.id]).toBeUndefined()
+    expect(guideOccurrence.signal.aborted).toBe(true)
+    expect(other.getSnapshot().bySession[OTHER]).toBe(otherSurface)
+    expect(controller.active()?.kind).toBe('guide')
+    releaseOther()
+    releaseOwn()
+  })
+
+  it('do nothing for a session whose store is not adopted, and again once its adoption is released', () => {
+    const { controller, adopt, instance, publish, layout, titles } = harness()
+    publish()
+    controller.openResource(A_TXT)
+    publish()
+    const own = Object.values(layout().tabs).find(tab => tab.title === 'a.txt')
+    if (own === undefined) throw new Error('expected the opened tab')
+    const { tabActions } = controller.tabDomain.occurrence(SESSION, own)
+    const before = instance.getSnapshot().bySession
+    tabActions.openResource(B_TXT)
+    tabActions.openTab('guide')
+    tabActions.close()
+    expect(instance.getSnapshot().bySession).toBe(before)
+    // Adopted, they land; released, they stop again.
+    const release = adopt(SESSION, instance)
+    tabActions.openResource(B_TXT)
+    expect(titles()).toContain('b.txt')
+    release()
+    tabActions.close()
+    expect(titles()).toContain('a.txt')
+  })
+
+  it('adoption syncs the Tab domain on each commit of that store: the seeded guide is pinned, a closed tab aborted', () => {
+    const { controller, adopt, instance, pin } = harness()
+    const first = adopt(SESSION, instance)
+    // Nothing is synced at adoption, and a commit that materializes another
+    // session leaves this session's occurrences alone.
+    instance.actions.open(OTHER)
+    expect(pin).not.toHaveBeenCalled()
+    instance.actions.open(SESSION)
+    expect(pin).toHaveBeenCalledWith('sidebar://guide', expect.any(AbortSignal))
+    instance.actions.openContent(SESSION, { kind: 'text', contentId: A_TXT, title: 'a' }, () => {})
+    const surface = instance.getSnapshot().bySession[SESSION]
+    const tab = Object.values(surface?.layout.tabs ?? {}).find(record => record.contentId === A_TXT)
+    if (tab === undefined) throw new Error('expected the opened tab')
+    const occurrence = controller.tabDomain.occurrence(SESSION, tab)
+    expect(pin).toHaveBeenCalledWith(A_TXT, occurrence.signal)
+    instance.actions.closeTab(SESSION, tab.id)
+    expect(occurrence.signal.aborted).toBe(true)
+    // A release ends the syncing; a stale release leaves a newer adoption standing.
+    first()
+    const second = adopt(SESSION, instance)
+    first()
+    instance.actions.openContent(SESSION, { kind: 'text', contentId: B_TXT, title: 'b' }, () => {})
+    const again = Object.values(instance.getSnapshot().bySession[SESSION]?.layout.tabs ?? {}).find(record => record.contentId === B_TXT)
+    if (again === undefined) throw new Error('expected the second tab')
+    const held = controller.tabDomain.occurrence(SESSION, again)
+    expect(pin).toHaveBeenCalledWith(B_TXT, held.signal)
+    // Adopting another instance for the session ends the earlier adoption's
+    // subscription with its routing: the old store's commits sync nothing, the
+    // new store's commits reconcile the session against its own layout.
+    const replacement = createSidebarRightStore(() => 'seed').create()
+    const third = adopt(SESSION, replacement)
+    const pins = pin.mock.calls.length
+    instance.actions.openContent(SESSION, { kind: 'text', contentId: 'dsh-resource://file/session/s-test/c.txt', title: 'c' }, () => {})
+    expect(pin.mock.calls.length).toBe(pins)
+    expect(held.signal.aborted).toBe(false)
+    replacement.actions.open(SESSION)
+    expect(held.signal.aborted).toBe(true)
+    second()
+    third()
+  })
+})
+
+describe('SidebarRightController — the readable slice', () => {
+  it('answers for the no-session case rather than throwing', () => {
+    const { controller } = harness()
+    expect(controller.isExpanded()).toBe(false)
+    expect(controller.active()).toBeUndefined()
+  })
+
+  it('reports the last committed surface', () => {
+    const { controller, publish, layout } = harness()
+    publish()
+    controller.toggleExpanded()
+    publish()
+    expect(controller.isExpanded()).toBe(true)
+    controller.openResource('dsh-resource://file/session/s-test/a.txt')
+    publish()
+    expect(Object.values(layout().tabs).filter(tab => tab.contentId === 'dsh-resource://file/session/s-test/a.txt')).toHaveLength(1)
+    expect(controller.active()?.contentId).toBe('dsh-resource://file/session/s-test/a.txt')
+  })
+})
+
+describe('SidebarRightController — binding lifetime', () => {
+  it('acts on the newest binding when a seat republishes', () => {
+    const { controller, publish, layout } = harness()
+    publish()
+    controller.toggleExpanded()
+    publish()
+    expect(controller.isExpanded()).toBe(true)
+    expect(layout().expanded).toBe(true)
+  })
+
+  it('goes back to refusing writes once the seat releases', () => {
+    const { controller, publish } = harness()
+    const release = publish()
+    release()
+    expect(() => { controller.toggleExpanded() }).toThrow('no session surface is mounted')
+    expect(controller.isExpanded()).toBe(false)
+  })
+
+  it('a stale release does not clear a newer binding', () => {
+    const { controller, publish } = harness()
+    const stale = publish()
+    publish()
+    stale()
+    expect(() => { controller.toggleExpanded() }).not.toThrow()
+  })
+})
diff --git a/packages/client/ui-sidebar-right/tests/stores.client.spec.ts b/packages/client/ui-sidebar-right/tests/stores.client.spec.ts
new file mode 100644
index 0000000000..d7a040734c
--- /dev/null
+++ b/packages/client/ui-sidebar-right/tests/stores.client.spec.ts
@@ -0,0 +1,272 @@
+/**
+ * The store shell over the docking kit: every action is one settled intent
+ * recorded as one history entry, or no entry when it changes nothing.
+ *
+ * The opens, the guide's uniqueness, and the merge rule are asserted through
+ * `ctx.sidebarRight` in service.client.spec.ts; here are the intents only the
+ * kit's gestures reach — floating-panel moves and resizes, divider drags — and
+ * the sequence's ends.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import type { LayoutState, PaneId, TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+import { dockPaneIds, findTabPane, getPane, getSplit } from '@deepseek-ai/dsh-client-ui-dockkit'
+import { createSidebarRightStore } from '../src/client/stores.ts'
+
+const SESSION = 's-test'
+
+function harness() {
+  const instance = createSidebarRightStore(() => 'Start').create()
+  instance.actions.open(SESSION)
+  const surface = () => {
+    const held = instance.getSnapshot().bySession[SESSION]
+    if (held === undefined) throw new Error('expected a surface')
+    return held
+  }
+  const layout = (): LayoutState => surface().layout
+  const entries = (): number => surface().history.entries.length
+  const guide = (): TabId => {
+    const seeded = Object.values(layout().tabs)[0]
+    if (seeded === undefined) throw new Error('expected the seeded guide')
+    return seeded.id
+  }
+  return { instance, actions: instance.actions, surface, layout, entries, guide }
+}
+
+describe('createSidebarRightStore — the sequence', () => {
+  it.each(['left', 'right'] as const)('splits one pane at its %s edge and records the tab move as one reversible intent', (zone) => {
+    const { actions, layout, entries, guide } = harness()
+    actions.openContent(SESSION, {
+      kind: 'text', contentId: 'dsh-resource://file/session/s-test/a.txt', title: 'a',
+    }, () => {})
+    const text = Object.values(layout().tabs).find(tab => tab.kind === 'text')
+    if (text === undefined) throw new Error('expected the text tab')
+    const before = layout()
+    const home = getPane(before, before.rootId).id
+    const recorded = entries()
+
+    actions.dropTab(SESSION, text.id, home, zone)
+
+    const split = getSplit(layout(), layout().rootId)
+    const destination = findTabPane(layout(), text.id)
+    expect(split.axis).toBe('row')
+    expect(split.children).toEqual(zone === 'left' ? [destination.id, home] : [home, destination.id])
+    expect(split.sizes).toEqual([0.5, 0.5])
+    expect(destination.tabs).toEqual([text.id])
+    expect(destination.activeTabId).toBe(text.id)
+    expect(getPane(layout(), home).tabs).toEqual([guide()])
+    expect(layout().tabs).toEqual(before.tabs)
+    expect(entries()).toBe(recorded + 1)
+    const dropped = layout()
+
+    actions.undo(SESSION)
+    expect(layout()).toEqual(before)
+    actions.redo(SESSION)
+    expect(layout()).toEqual(dropped)
+  })
+
+  it('allows two docked panes and rejects further splits without recording', () => {
+    const { actions, layout, entries } = harness()
+    actions.splitPane(SESSION)
+    expect(dockPaneIds(layout())).toHaveLength(2)
+    const before = entries()
+    const settled = vi.fn()
+    actions.splitPane(SESSION, undefined, settled)
+    expect(dockPaneIds(layout())).toHaveLength(2)
+    expect(entries()).toBe(before)
+    expect(settled).not.toHaveBeenCalled()
+  })
+
+  it('rejects vertical drops and keeps split ratios within twenty to eighty percent', () => {
+    const { actions, layout, entries, guide } = harness()
+    actions.openContent(SESSION, { kind: 'text', contentId: 'file:a', title: 'a' }, () => {})
+    const before = entries()
+    actions.dropTab(SESSION, guide(), layout().activePaneId, 'top')
+    actions.dropTab(SESSION, guide(), layout().activePaneId, 'bottom')
+    expect(entries()).toBe(before)
+    actions.splitPane(SESSION)
+    const split = getSplit(layout(), layout().rootId).id
+    actions.resizeSplit(SESSION, split, [0.01, 0.99])
+    expect(getSplit(layout(), split).sizes).toEqual([0.2, 0.8])
+    actions.resizeSplit(SESSION, split, [0.99, 0.01])
+    expect(getSplit(layout(), split).sizes).toEqual([0.8, 0.2])
+    const splitCount = entries()
+    actions.dropTab(SESSION, guide(), layout().activePaneId, 'right')
+    expect(entries()).toBe(splitCount)
+  })
+
+  it('materializes a session on open without recording, then records each change of expansion once', () => {
+    const { actions, layout, entries } = harness()
+    expect(layout().expanded).toBe(false)
+    expect(entries()).toBe(0)
+    actions.setExpanded(SESSION, true)
+    expect(layout().expanded).toBe(true)
+    expect(entries()).toBe(1)
+    // Already expanded: nothing to plan, nothing recorded, the surface kept by reference.
+    const before = layout()
+    actions.setExpanded(SESSION, true)
+    expect(layout()).toBe(before)
+    expect(entries()).toBe(1)
+  })
+
+  it('closes a tab once: a second close of a record already gone records nothing and throws nothing', () => {
+    const { actions, layout, entries } = harness()
+    actions.openContent(SESSION, { kind: 'text', contentId: 'dsh-resource://file/session/s-test/a.txt', title: 'a' }, () => {})
+    const tab = Object.values(layout().tabs).find(record => record.title === 'a')
+    if (tab === undefined) throw new Error('expected the opened tab')
+    actions.closeTab(SESSION, tab.id)
+    expect(layout().tabs[tab.id]).toBeUndefined()
+    const recorded = entries()
+    // A racing callback closing what the user already closed.
+    expect(() => { actions.closeTab(SESSION, tab.id) }).not.toThrow()
+    expect(entries()).toBe(recorded)
+  })
+
+  it('steps nowhere before the first entry, and forward again through an undone one', () => {
+    const { actions, surface, layout } = harness()
+    const start = surface()
+    actions.undo(SESSION)
+    expect(surface()).toBe(start)
+    actions.redo(SESSION)
+    expect(surface()).toBe(start)
+    actions.toggleExpanded(SESSION)
+    actions.undo(SESSION)
+    expect(layout().expanded).toBe(false)
+    actions.redo(SESSION)
+    expect(layout().expanded).toBe(true)
+  })
+})
+
+describe('createSidebarRightStore — floating panels and dividers', () => {
+  it('moves and resizes a floating panel, one entry each', () => {
+    const { actions, layout, entries, guide } = harness()
+    actions.floatTab(SESSION, guide(), { x: 10, y: 20, width: 300, height: 200 })
+    const [float] = layout().floats
+    if (float === undefined) throw new Error('expected a floating pane')
+    const recorded = entries()
+    actions.moveFloat(SESSION, float, 40, 60)
+    expect(findTabPane(layout(), guide()).rect).toEqual({ x: 40, y: 60, width: 300, height: 200 })
+    actions.resizeFloat(SESSION, float, { x: 40, y: 60, width: 420, height: 260 })
+    expect(findTabPane(layout(), guide()).rect).toEqual({ x: 40, y: 60, width: 420, height: 260 })
+    expect(entries()).toBe(recorded + 2)
+  })
+
+  it('focuses a pane as one entry, which a click on a floating panel records', () => {
+    const { actions, layout, entries, guide } = harness()
+    actions.floatTab(SESSION, guide(), { x: 10, y: 20, width: 300, height: 200 })
+    const [float] = layout().floats
+    if (float === undefined) throw new Error('expected a floating pane')
+    // The root pane was reseeded when its guide floated away, so it is docked and focusable.
+    const docked = getPane(layout(), layout().rootId).id
+    actions.focusPane(SESSION, docked)
+    expect(layout().activePaneId).toBe(docked)
+    const recorded = entries()
+    actions.focusPane(SESSION, float)
+    expect(layout().activePaneId).toBe(float)
+    expect(entries()).toBe(recorded + 1)
+  })
+
+  it('records a divider drag as the split\'s new fractions', () => {
+    const { actions, layout, entries } = harness()
+    actions.splitPane(SESSION)
+    const rootId = getSplit(layout(), layout().rootId).id
+    expect(getSplit(layout(), rootId).sizes).toEqual([0.5, 0.5])
+    const recorded = entries()
+    actions.resizeSplit(SESSION, rootId, [0.3, 0.7])
+    expect(getSplit(layout(), rootId).sizes).toEqual([0.3, 0.7])
+    expect(entries()).toBe(recorded + 1)
+  })
+
+  it('reports the pane a split created, and only then', () => {
+    const { actions, layout } = harness()
+    const settled = vi.fn<(paneId: PaneId) => void>()
+    const before = dockPaneIds(layout())
+    actions.splitPane(SESSION, undefined, settled)
+    const created = dockPaneIds(layout()).filter(id => !before.includes(id))
+    expect(created).toHaveLength(1)
+    expect(settled).toHaveBeenCalledExactlyOnceWith(created[0])
+    // A floating pane cannot be split: nothing changes and nothing is reported.
+    const [tab] = getPane(layout(), created[0] as PaneId).tabs
+    if (tab === undefined) throw new Error('expected the seeded guide')
+    actions.floatTab(SESSION, tab)
+    const [float] = layout().floats
+    if (float === undefined) throw new Error('expected a floating pane')
+    actions.splitPane(SESSION, float, settled)
+    expect(settled).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('createSidebarRightStore — focus', () => {
+  it('records a focus only when it changes which tab or pane is active, docked or floating', () => {
+    const { actions, layout, entries, guide } = harness()
+    actions.openContent(SESSION, { kind: 'text', contentId: 'dsh-resource://file/session/s-test/a.txt', title: 'a' }, () => {})
+    const text = Object.values(layout().tabs).find(tab => tab.kind === 'text')
+    if (text === undefined) throw new Error('expected the text tab')
+    const home = layout().activePaneId
+    expect(getPane(layout(), home).activeTabId).toBe(text.id)
+    const recorded = entries()
+    // Already the active tab of the active pane, already the active pane: nothing to record.
+    actions.focusTab(SESSION, text.id)
+    actions.focusPane(SESSION, home)
+    expect(entries()).toBe(recorded)
+    // Another tab of the same pane: recorded.
+    actions.focusTab(SESSION, guide())
+    expect(getPane(layout(), home).activeTabId).toBe(guide())
+    expect(entries()).toBe(recorded + 1)
+    // Two panes: the home pane's active tab, focused while the other pane is active, is recorded.
+    actions.splitPane(SESSION)
+    const other = dockPaneIds(layout()).find(id => id !== home)
+    if (other === undefined) throw new Error('expected a second pane')
+    actions.focusPane(SESSION, other)
+    const split = entries()
+    actions.focusTab(SESSION, guide())
+    expect(layout().activePaneId).toBe(home)
+    expect(entries()).toBe(split + 1)
+    // A floating pane: focusing it while it is active records nothing; after
+    // a docked pane took focus, focusing its pane and its tab record again.
+    actions.floatTab(SESSION, text.id)
+    const [float] = layout().floats
+    if (float === undefined) throw new Error('expected a floating pane')
+    expect(layout().activePaneId).toBe(float)
+    const floated = entries()
+    actions.focusPane(SESSION, float)
+    actions.focusTab(SESSION, text.id)
+    expect(entries()).toBe(floated)
+    actions.focusPane(SESSION, home)
+    actions.focusPane(SESSION, float)
+    expect(layout().activePaneId).toBe(float)
+    actions.focusPane(SESSION, home)
+    actions.focusTab(SESSION, text.id)
+    expect(layout().activePaneId).toBe(float)
+    expect(entries()).toBe(floated + 4)
+  })
+})
+
+describe('createSidebarRightStore — the guide\'s uniqueness', () => {
+  it('places and drops any other tab as the kit plans it, guides in the target pane or not', () => {
+    const { actions, layout } = harness()
+    actions.openContent(SESSION, { kind: 'text', contentId: 'dsh-resource://file/session/s-test/a.txt', title: 'a' }, () => {})
+    const text = Object.values(layout().tabs).find(tab => tab.kind === 'text')
+    if (text === undefined) throw new Error('expected the text tab')
+    actions.splitPane(SESSION)
+    const [left, right] = dockPaneIds(layout())
+    if (left === undefined || right === undefined) throw new Error('expected two panes')
+    // Placed beside the right pane's guide: both stay, the text tab at the named slot.
+    actions.placeTab(SESSION, text.id, right, 0)
+    expect(getPane(layout(), right).tabs[0]).toBe(text.id)
+    expect(getPane(layout(), right).tabs).toHaveLength(2)
+    // Dropped on the left pane's centre: it moves in beside that pane's guide too.
+    actions.dropTab(SESSION, text.id, left, 'center')
+    expect(getPane(layout(), left).tabs).toContain(text.id)
+    expect(Object.values(layout().tabs).filter(tab => tab.kind === 'guide')).toHaveLength(2)
+  })
+
+  it('reorders the guide within its own pane as a plain place', () => {
+    const { actions, layout, guide } = harness()
+    const pane = layout().activePaneId
+    actions.openContent(SESSION, { kind: 'text', contentId: 'dsh-resource://file/session/s-test/a.txt', title: 'a' }, () => {})
+    expect(getPane(layout(), pane).tabs[0]).toBe(guide())
+    actions.placeTab(SESSION, guide(), pane, 2)
+    expect(getPane(layout(), pane).tabs.at(-1)).toBe(guide())
+    expect(Object.values(layout().tabs).filter(tab => tab.kind === 'guide')).toHaveLength(1)
+  })
+})
diff --git a/packages/client/ui-sidebar-right/tests/tab-domain.client.spec.ts b/packages/client/ui-sidebar-right/tests/tab-domain.client.spec.ts
new file mode 100644
index 0000000000..793bda8083
--- /dev/null
+++ b/packages/client/ui-sidebar-right/tests/tab-domain.client.spec.ts
@@ -0,0 +1,210 @@
+/**
+ * The Tab domain: what a record carries that the layout does not, and how long.
+ *
+ * Every assertion here is a lifetime rule a tab type relies on through its
+ * owner props: the signal aborts exactly when the record is gone, the pin lasts
+ * exactly as long, an undone close is a new occurrence, another session's
+ * records are left alone, and a tab's own actions name the tab's session and land where the tab is now.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { LayoutState, TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+import { DockController, getPane } from '@deepseek-ai/dsh-client-ui-dockkit'
+import { TabDomain } from '../src/client/tab-domain.ts'
+import type { SidebarRightNavigator } from '../src/client/tab-domain.ts'
+
+// The params map is empty in this package; a test-only scheme lets specs hand
+// parameters through the typed `open`/`navigate` faces.
+declare module '../src/client/contract/params.ts' {
+  interface SidebarRightResourceParamsMap {
+    test: { line?: number; x?: number }
+  }
+}
+
+const SESSION = 's-one' as SessionId
+const OTHER = 's-two' as SessionId
+
+/** A layout driven by the kit's own controller; the domain only ever reads snapshots. */
+function layouts() {
+  const controller = new DockController({
+    makeInitialTab: id => ({ id, kind: 'guide', contentId: 'sidebar://guide', title: 'Start' }),
+    makePaneTab: id => ({ id, kind: 'guide', contentId: 'sidebar://guide', title: 'Start' }),
+  })
+  const current = (): LayoutState => controller.getSnapshot().state
+  return { controller, current }
+}
+
+function harness() {
+  const navigator = { openResourceIn: vi.fn(), openTabIn: vi.fn(), closeIn: vi.fn() } satisfies
+    SidebarRightNavigator & Record<string, ReturnType<typeof vi.fn>>
+  const pin = vi.fn<(address: string, signal: AbortSignal) => void>()
+  const domain = new TabDomain(navigator, pin)
+  return { domain, navigator, pin, ...layouts() }
+}
+
+/** The record for a tab id, as the seat would hand it over. */
+function recordOf(state: LayoutState, tabId: TabId) {
+  const tab = state.tabs[tabId]
+  if (tab === undefined) throw new Error(`expected tab ${tabId}`)
+  return tab
+}
+
+describe('TabDomain — occurrences follow records', () => {
+  it('pins a record\'s address when it first appears, with the occurrence\'s signal', () => {
+    const { domain, pin, controller, current } = harness()
+    const tabId = controller.openContent({ kind: 'text', contentId: 'dsh-resource://file/session/s-one/a.txt', title: 'a' })
+    domain.sync(SESSION, current())
+    const occurrence = domain.occurrence(SESSION, recordOf(current(), tabId))
+    expect(pin).toHaveBeenCalledWith('dsh-resource://file/session/s-one/a.txt', occurrence.signal)
+    expect(occurrence.signal.aborted).toBe(false)
+    // Seeded records are occurrences too; the guide is pinned like anything else.
+    expect(pin).toHaveBeenCalledWith('sidebar://guide', expect.any(AbortSignal))
+    expect(pin).toHaveBeenCalledTimes(2)
+  })
+
+  it('pins once per occurrence, however many times the layout commits', () => {
+    const { domain, pin, controller, current } = harness()
+    controller.openContent({ kind: 'text', contentId: 'dsh-resource://file/session/s-one/a.txt', title: 'a' })
+    domain.sync(SESSION, current())
+    controller.setExpanded(true)
+    domain.sync(SESSION, current())
+    expect(pin).toHaveBeenCalledTimes(2)
+  })
+
+  it('aborts the occurrence when its record vanishes, and builds a new one when undo restores it', () => {
+    const { domain, pin, controller, current } = harness()
+    const tabId = controller.openContent({ kind: 'text', contentId: 'dsh-resource://file/session/s-one/a.txt', title: 'a' })
+    domain.sync(SESSION, current())
+    const first = domain.occurrence(SESSION, recordOf(current(), tabId))
+    controller.closeTab(tabId)
+    domain.sync(SESSION, current())
+    expect(first.signal.aborted).toBe(true)
+    controller.undo()
+    domain.sync(SESSION, current())
+    const second = domain.occurrence(SESSION, recordOf(current(), tabId))
+    expect(second).not.toBe(first)
+    expect(second.signal.aborted).toBe(false)
+    expect(second.navigation.getSnapshot()).toEqual({ address: 'dsh-resource://file/session/s-one/a.txt', params: undefined, revision: 0 })
+    expect(pin.mock.calls.filter(([address]) => address === 'dsh-resource://file/session/s-one/a.txt')).toHaveLength(2)
+  })
+
+  it('leaves another session\'s occurrences alone when a session is synced', () => {
+    const { domain, controller, current } = harness()
+    const tabId = controller.openContent({ kind: 'text', contentId: 'dsh-resource://file/session/s-one/a.txt', title: 'a' })
+    domain.sync(SESSION, current())
+    const held = domain.occurrence(SESSION, recordOf(current(), tabId))
+    const other = layouts()
+    domain.sync(OTHER, other.current())
+    expect(held.signal.aborted).toBe(false)
+  })
+
+  it('aborts every occurrence of every session on dispose', () => {
+    const { domain, controller, current } = harness()
+    const tabId = controller.openContent({ kind: 'text', contentId: 'dsh-resource://file/session/s-one/a.txt', title: 'a' })
+    domain.sync(SESSION, current())
+    domain.sync(OTHER, layouts().current())
+    const held = domain.occurrence(SESSION, recordOf(current(), tabId))
+    domain.dispose()
+    expect(held.signal.aborted).toBe(true)
+  })
+})
+
+describe('TabDomain — navigation', () => {
+  it('creates the occurrence for a tab the seat has not shown yet, at revision 1, and pins it on the next sync', () => {
+    const { domain, pin, controller, current } = harness()
+    const tabId = controller.openContent({ kind: 'text', contentId: 'dsh-resource://file/session/s-one/a.txt', title: 'a' })
+    domain.navigate(SESSION, tabId, { address: 'dsh-resource://file/session/s-one/a.txt', params: { line: 7 } })
+    expect(pin).not.toHaveBeenCalled()
+    const occurrence = domain.occurrence(SESSION, recordOf(current(), tabId))
+    expect(occurrence.navigation.getSnapshot()).toEqual({ address: 'dsh-resource://file/session/s-one/a.txt', params: { line: 7 }, revision: 1 })
+    domain.sync(SESSION, current())
+    expect(domain.occurrence(SESSION, recordOf(current(), tabId))).toBe(occurrence)
+    expect(pin).toHaveBeenCalledWith('dsh-resource://file/session/s-one/a.txt', occurrence.signal)
+  })
+
+  it('steps the revision on every navigation, params changed or not, and notifies', () => {
+    const { domain, controller, current } = harness()
+    const tabId = controller.openContent({ kind: 'text', contentId: 'dsh-resource://file/session/s-one/a.txt', title: 'a' })
+    domain.sync(SESSION, current())
+    const occurrence = domain.occurrence(SESSION, recordOf(current(), tabId))
+    const seen = vi.fn()
+    occurrence.navigation.subscribe(seen)
+    domain.navigate(SESSION, tabId, { address: 'dsh-resource://file/session/s-one/a.txt', params: { line: 3 } })
+    domain.navigate(SESSION, tabId, { address: 'dsh-resource://file/session/s-one/a.txt', params: { line: 3 } })
+    expect(occurrence.navigation.getSnapshot()).toEqual({ address: 'dsh-resource://file/session/s-one/a.txt', params: { line: 3 }, revision: 2 })
+    expect(seen).toHaveBeenCalledTimes(2)
+  })
+
+  it('refuses an uncommitted occurrence without creating it during a read', () => {
+    const { domain, pin, controller, current } = harness()
+    const tabId = controller.openContent({ kind: 'text', contentId: 'dsh-resource://file/session/s-one/a.txt', title: 'a' })
+    expect(() => domain.occurrence(SESSION, { id: tabId })).toThrow('has no committed occurrence')
+    expect(pin).not.toHaveBeenCalled()
+    domain.sync(SESSION, current())
+    const occurrence = domain.occurrence(SESSION, { id: tabId })
+    expect(domain.occurrence(SESSION, { id: tabId })).toBe(occurrence)
+    expect(pin).toHaveBeenCalledWith('dsh-resource://file/session/s-one/a.txt', occurrence.signal)
+    controller.closeTab(tabId)
+    domain.sync(SESSION, current())
+    expect(() => domain.occurrence(SESSION, { id: tabId })).toThrow('has no committed occurrence')
+  })
+})
+
+describe('TabDomain — a tab\'s own actions', () => {
+  it('opens into the pane holding the tab at call time, including after it was moved', () => {
+    const { domain, navigator, controller, current } = harness()
+    controller.setExpanded(true)
+    const tabId = controller.openContent({ kind: 'text', contentId: 'dsh-resource://file/session/s-one/a.txt', title: 'a' })
+    controller.splitPane()
+    domain.sync(SESSION, current())
+    const occurrence = domain.occurrence(SESSION, recordOf(current(), tabId))
+    const home = current().nodes[current().rootId]
+    if (home?.kind !== 'split') throw new Error('expected a split root')
+    const [left, right] = home.children
+    if (left === undefined || right === undefined) throw new Error('expected two panes')
+    const leftPane = getPane(current(), left).id
+    const rightPane = getPane(current(), right).id
+    occurrence.tabActions.openResource('dsh-resource://file/session/s-one/b.txt')
+    expect(navigator.openResourceIn).toHaveBeenLastCalledWith(SESSION, 'dsh-resource://file/session/s-one/b.txt', { paneId: leftPane })
+    controller.placeTab(tabId, rightPane, 0)
+    domain.sync(SESSION, current())
+    occurrence.tabActions.openResource('dsh-resource://file/session/s-one/b.txt', { params: { line: 1 } })
+    expect(navigator.openResourceIn).toHaveBeenLastCalledWith(SESSION, 'dsh-resource://file/session/s-one/b.txt', { paneId: rightPane, params: { line: 1 } })
+    // The caller's pane wins over the default.
+    occurrence.tabActions.openResource('dsh-resource://file/session/s-one/b.txt', { paneId: leftPane })
+    expect(navigator.openResourceIn).toHaveBeenLastCalledWith(SESSION, 'dsh-resource://file/session/s-one/b.txt', { paneId: leftPane })
+  })
+
+  it('opens unplaced from a floating tab, since a floating pane holds one tab', () => {
+    const { domain, navigator, controller, current } = harness()
+    const tabId = controller.openContent({ kind: 'text', contentId: 'dsh-resource://file/session/s-one/a.txt', title: 'a' })
+    controller.floatTab(tabId)
+    domain.sync(SESSION, current())
+    domain.occurrence(SESSION, recordOf(current(), tabId)).tabActions.openResource('dsh-resource://file/session/s-one/b.txt')
+    expect(navigator.openResourceIn).toHaveBeenLastCalledWith(SESSION, 'dsh-resource://file/session/s-one/b.txt', {})
+  })
+
+  it('replaces itself and closes itself through the navigator', () => {
+    const { domain, navigator, controller, current } = harness()
+    const tabId = controller.openContent({ kind: 'text', contentId: 'dsh-resource://file/session/s-one/a.txt', title: 'a' })
+    domain.sync(SESSION, current())
+    const { tabActions } = domain.occurrence(SESSION, recordOf(current(), tabId))
+    tabActions.openTab('files', { replaceTab: true })
+    expect(navigator.openTabIn).toHaveBeenLastCalledWith(SESSION, 'files', { replaceTab: tabId })
+    tabActions.close()
+    expect(navigator.closeIn).toHaveBeenCalledWith(SESSION, tabId)
+  })
+
+  it('passes revealIfOpened through, so a tab may open a second copy beside itself', () => {
+    const { domain, navigator, controller, current } = harness()
+    const tabId = controller.openContent({ kind: 'text', contentId: 'dsh-resource://file/session/s-one/a.txt', title: 'a' })
+    domain.sync(SESSION, current())
+    const { tabActions } = domain.occurrence(SESSION, recordOf(current(), tabId))
+    tabActions.openResource('dsh-resource://file/session/s-one/a.txt', { revealIfOpened: false })
+    expect(navigator.openResourceIn).toHaveBeenLastCalledWith(
+      SESSION,
+      'dsh-resource://file/session/s-one/a.txt',
+      { paneId: current().rootId, revealIfOpened: false },
+    )
+  })
+})
diff --git a/packages/client/ui-sidebar-right/tests/tab-info.client.spec.tsx b/packages/client/ui-sidebar-right/tests/tab-info.client.spec.tsx
new file mode 100644
index 0000000000..81c495f20b
--- /dev/null
+++ b/packages/client/ui-sidebar-right/tests/tab-info.client.spec.tsx
@@ -0,0 +1,121 @@
+// @vitest-environment jsdom
+/** Tab information refuses readers whose committed record and navigation binding disagree. */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, renderHook } from '@testing-library/react'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-test-runtime'
+import { keyedObservableHook } from '@deepseek-ai/dsh-client-ui-renderer/src/client/bindings.tsx'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+import type { UseSidebarRightTabInfo } from '../src/client/contract/slots.ts'
+import { createSidebarRightStore } from '../src/client/stores.ts'
+import { TabDomain, type TabOccurrence } from '../src/client/tab-domain.ts'
+import { tabInfoFactory, type TabHookContext } from '../src/client/tab-info.ts'
+
+const SESSION = 's-info' as SessionId
+const ADDRESS = 'dsh-resource://file/session/s-info/a.txt'
+const domains: TabDomain[] = []
+
+afterEach(() => {
+  cleanup()
+  for (const domain of domains.splice(0)) domain.dispose()
+})
+
+function harness() {
+  const instance = createSidebarRightStore(() => 'Start').create()
+  const domain = new TabDomain({ openResourceIn: vi.fn(), openTabIn: vi.fn(), closeIn: vi.fn() }, vi.fn())
+  domains.push(domain)
+  const navigationSources = new Map<string, TabOccurrence['navigation']>()
+  const useStore = bindSnapshotSelector(instance)
+  // The renderer erases the keyed snapshot type; this family contains only tab navigation sources.
+  const useTabNavigation = keyedObservableHook(key => navigationSources.get(key)) as TabHookContext['useTabNavigation']
+  // Only sessionId is read from the standard share by this internal factory.
+  const standard = { sessionId: SESSION } as Parameters<typeof tabInfoFactory>[0]
+  const layout = () => instance.getSnapshot().bySession[SESSION]?.layout
+  const sync = (): void => {
+    const committed = layout()
+    if (committed === undefined) throw new Error('expected the layout to commit')
+    domain.sync(SESSION, committed)
+  }
+  const bind = (tabId: TabId): UseSidebarRightTabInfo => {
+    const occurrence = domain.occurrence(SESSION, { id: tabId })
+    navigationSources.set(tabId, occurrence.navigation)
+    return tabInfoFactory(standard, {
+      tabId, title: false, fullscreen: false, signal: occurrence.signal, actions: occurrence.tabActions, useStore, useTabNavigation,
+    })
+  }
+  const open = (beforeCommit?: (tabId: TabId) => void): TabId => {
+    let opened: TabId | undefined
+    instance.actions.openContent(SESSION, { kind: 'text', contentId: ADDRESS, title: 'a' }, (tabId) => {
+      opened = tabId
+      domain.navigate(SESSION, tabId, { address: ADDRESS, params: undefined })
+      beforeCommit?.(tabId)
+    })
+    if (opened === undefined) throw new Error('expected the tab to open')
+    sync()
+    return opened
+  }
+  return { instance, domain, navigationSources, layout, sync, bind, open }
+}
+
+function expectUncommitted(useTabInfo: UseSidebarRightTabInfo, tabId: TabId): void {
+  const message = `sidebarRight: tab "${tabId}" is not committed in session "${SESSION}"`
+  const suppressExpected = (event: ErrorEvent): void => {
+    if (event.error instanceof Error && event.error.message === message) event.preventDefault()
+  }
+  const report = vi.spyOn(console, 'error').mockImplementation(() => {})
+  window.addEventListener('error', suppressExpected)
+  try {
+    expect(() => renderHook(useTabInfo)).toThrow(message)
+  } finally {
+    window.removeEventListener('error', suppressExpected)
+    report.mockRestore()
+  }
+}
+
+describe('tabInfoFactory committed-record relation', () => {
+  it('rejects a navigation before the first layout commit and reads the same record after commit', () => {
+    const h = harness()
+    const tabId = h.open((opened) => {
+      expect(h.layout()).toBeUndefined()
+      expectUncommitted(h.bind(opened), opened)
+    })
+    const view = renderHook(h.bind(tabId))
+    expect(view.result.current.tab).toMatchObject({ id: tabId, contentId: ADDRESS })
+    expect(view.result.current.tab.signal.aborted).toBe(false)
+    expect(view.result.current.tab.navigation.revision).toBe(1)
+  })
+
+  it('rejects a retained reader after its record closes, even while its navigation snapshot is held', () => {
+    const h = harness()
+    const tabId = h.open()
+    const useTabInfo = h.bind(tabId)
+    const view = renderHook(useTabInfo)
+    const { signal, navigation } = view.result.current.tab
+    view.unmount()
+
+    h.instance.actions.closeTab(SESSION, tabId)
+    h.sync()
+
+    expect(signal.aborted).toBe(true)
+    expect(h.layout()?.tabs[tabId]).toBeUndefined()
+    expect(h.navigationSources.get(tabId)?.getSnapshot()).toBe(navigation)
+    expectUncommitted(useTabInfo, tabId)
+  })
+
+  it('rejects a retained record after its keyed navigation binding is released', () => {
+    const h = harness()
+    const tabId = h.open()
+    const useTabInfo = h.bind(tabId)
+    const view = renderHook(useTabInfo)
+    expect(view.result.current.tab.id).toBe(tabId)
+    view.unmount()
+    const committed = h.layout()
+
+    h.domain.dispose()
+    h.navigationSources.clear()
+
+    expect(h.layout()).toBe(committed)
+    expect(h.layout()?.tabs[tabId]).toBeDefined()
+    expectUncommitted(useTabInfo, tabId)
+  })
+})
diff --git a/packages/client/ui-sidebar-right/tests/tab-registry.client.spec.ts b/packages/client/ui-sidebar-right/tests/tab-registry.client.spec.ts
new file mode 100644
index 0000000000..2576115f33
--- /dev/null
+++ b/packages/client/ui-sidebar-right/tests/tab-registry.client.spec.ts
@@ -0,0 +1,286 @@
+/**
+ * Stage one of tab-type registration: how the registry decides who opens an
+ * address.
+ *
+ * The decision follows VS Code's editor resolver — declared globs narrow, an
+ * optional predicate vetoes, and survivors rank by band, matched-pattern length,
+ * then registration order — and every step is contract: a type shipped from
+ * another package relies on each one. So each is asserted, not assumed.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import { SidebarRightTabRegistry } from '../src/client/tab-registry.ts'
+import type { SidebarRightTabDefinition } from '../src/client/tab-registry.ts'
+
+/** A type recognizing `patterns`, titled by its kind. */
+function typeFor(
+  kind: string,
+  patterns: readonly string[],
+  extra: Partial<Omit<SidebarRightTabDefinition, 'kind' | 'patterns'>> = {},
+): SidebarRightTabDefinition {
+  return { id: `test/${kind}`, kind, patterns, title: address => `${kind}:${address}`, ...extra }
+}
+
+/** Kinds of the ranked candidates, best first. */
+function ranked(registry: SidebarRightTabRegistry, address: string): string[] {
+  return registry.candidates(address).map(definition => definition.kind)
+}
+
+describe('SidebarRightTabRegistry — recognition', () => {
+  it('matches a pattern containing ":" against the whole address', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register(typeFor('guide', ['sidebar://guide']))
+    registry.register(typeFor('text', ['dsh-resource://file/**']))
+    expect(registry.claim('sidebar://guide').kind).toBe('guide')
+    expect(registry.claim('dsh-resource://file/session/s/notes/a.txt').kind).toBe('text')
+    expect(ranked(registry, 'sidebar://files')).toEqual([])
+  })
+
+  it('matches a pattern without ":" against the URI path at any depth, ignoring case', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register(typeFor('image', ['*.png']))
+    expect(registry.claim('dsh-resource://file/session/s/deep/er/shot.PNG').kind).toBe('image')
+    expect(ranked(registry, 'dsh-resource://file/session/s/shot.png.txt')).toEqual([])
+  })
+
+  it('matches no path pattern for an address that is not a URI', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register(typeFor('image', ['*.png']))
+    registry.register(typeFor('raw', ['raw:*']))
+    expect(ranked(registry, 'shot.png')).toEqual([])
+    expect(ranked(registry, 'not a uri/shot.png')).toEqual([])
+    // A whole-address pattern still reads the string as given.
+    expect(registry.claim('raw:thing').kind).toBe('raw')
+  })
+
+  it('does not hide dotfiles from a path pattern', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register(typeFor('env', ['.env*']))
+    expect(registry.claim('dsh-resource://file/session/s/proj/.env.local').kind).toBe('env')
+  })
+})
+
+describe('SidebarRightTabRegistry — ranking', () => {
+  it('ranks by band: extension over builtin over fallback, whatever the registration order', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register(typeFor('text', ['dsh-resource://file/**'], { priority: 'fallback' }))
+    registry.register(typeFor('markdown', ['*.md'], { priority: 'builtin' }))
+    registry.register(typeFor('third', ['*.md']))
+    expect(ranked(registry, 'dsh-resource://file/session/s/a.md')).toEqual(['third', 'markdown', 'text'])
+    expect(registry.claim('dsh-resource://file/session/s/a.md').kind).toBe('third')
+  })
+
+  it('lets a more specific builtin beat the fallback viewer despite the viewer\'s longer pattern', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register(typeFor('text', ['dsh-resource://file/**'], { priority: 'fallback' }))
+    registry.register(typeFor('image', ['*.png'], { priority: 'builtin' }))
+    expect(registry.claim('dsh-resource://file/session/s/shot.png').kind).toBe('image')
+    expect(registry.claim('dsh-resource://file/session/s/notes.txt').kind).toBe('text')
+  })
+
+  it('lets an extension take over a builtin kind, and hands it back when the extension leaves', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register(typeFor('text', ['dsh-resource://file/**'], { priority: 'builtin', title: () => 'builtin text' }))
+    const release = registry.register(typeFor('text', ['*.txt'], { id: 'ext/text', title: () => 'extension text' }))
+    // The extension is the type in force: lookups, claims, and the listing.
+    expect(registry.get('text')?.title('x')).toBe('extension text')
+    expect(registry.claim('dsh-resource://file/session/s/a.txt').title).toBe('extension text')
+    expect(registry.entries().map(definition => definition.title('x'))).toEqual(['extension text'])
+    // The shadowed builtin's globs no longer count.
+    expect(ranked(registry, 'dsh-resource://file/session/s/a.bin')).toEqual([])
+    release()
+    expect(registry.get('text')?.title('x')).toBe('builtin text')
+    expect(registry.claim('dsh-resource://file/session/s/a.bin').title).toBe('builtin text')
+  })
+
+  it('lets a builtin register under an extension already holding its kind, shadowed until the extension leaves', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register(typeFor('text', ['dsh-resource://file/**'], { id: 'third-party/text' }))
+    const releaseBuiltin = registry.register(typeFor('text', ['dsh-resource://file/**'], { id: 'shipped/text', priority: 'builtin' }))
+    expect(registry.get('text')?.id).toBe('third-party/text')
+    expect(ranked(registry, 'dsh-resource://file/session/s/a.txt')).toEqual(['text'])
+    // The shadowed builtin leaving changes nothing in force, and its band is free again.
+    releaseBuiltin()
+    expect(registry.get('text')?.id).toBe('third-party/text')
+    expect(() => registry.register(typeFor('text', ['*.md'], { id: 'other/text', priority: 'builtin' }))).not.toThrow()
+  })
+
+  it('refuses a second registration in the same band, and any meeting a fallback of the kind', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register(typeFor('text', ['dsh-resource://file/**'], { id: 'a/text', priority: 'builtin' }))
+    expect(() => registry.register(typeFor('text', ['dsh-resource://file/**'], { id: 'b/text', priority: 'builtin' }))).toThrow('already registered')
+    registry.register(typeFor('text', ['dsh-resource://file/**'], { id: 'c/text' }))
+    expect(() => registry.register(typeFor('text', ['dsh-resource://file/**'], { id: 'd/text' }))).toThrow('already registered')
+    expect(() => registry.register(typeFor('text', ['dsh-resource://file/**'], { id: 'e/text', priority: 'fallback' }))).toThrow('already registered')
+    registry.register(typeFor('hex', ['dsh-resource://file/**'], { id: 'a/hex', priority: 'fallback' }))
+    expect(() => registry.register(typeFor('hex', ['dsh-resource://file/**'], { id: 'b/hex', priority: 'builtin' }))).toThrow('already registered')
+    expect(() => registry.register(typeFor('hex', ['dsh-resource://file/**'], { id: 'c/hex' }))).toThrow('already registered')
+  })
+
+  it('refuses a second registration of an id, whatever its kind', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    const dispose = registry.register(typeFor('text', ['dsh-resource://file/**'], { id: 'pkg/viewer', priority: 'builtin' }))
+    expect(() => registry.register(typeFor('hex', ['*.bin'], { id: 'pkg/viewer' }))).toThrow('tab type id "pkg/viewer" is already registered')
+    dispose()
+    expect(() => registry.register(typeFor('hex', ['*.bin'], { id: 'pkg/viewer' }))).not.toThrow()
+  })
+
+  it('within a band, the longer matched pattern wins', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register(typeFor('markdown', ['*.md'], { priority: 'builtin' }))
+    registry.register(typeFor('readme', ['README.md'], { priority: 'builtin' }))
+    expect(ranked(registry, 'dsh-resource://file/session/s/proj/README.md')).toEqual(['readme', 'markdown'])
+    expect(ranked(registry, 'dsh-resource://file/session/s/proj/notes.md')).toEqual(['markdown'])
+  })
+
+  it('then registration order', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register(typeFor('first', ['dsh-resource://file/**']))
+    registry.register(typeFor('second', ['dsh-resource://file/**']))
+    expect(ranked(registry, 'dsh-resource://file/session/s/a.txt')).toEqual(['first', 'second'])
+  })
+
+  it('measures specificity by the longest pattern that matched, not the longest declared', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register(typeFor('wide', ['*.txt', 'some/very/long/**/never.matches']))
+    registry.register(typeFor('narrow', ['notes.txt']))
+    expect(ranked(registry, 'dsh-resource://file/session/s/notes.txt')).toEqual(['narrow', 'wide'])
+  })
+})
+
+describe('SidebarRightTabRegistry — claiming', () => {
+  it('lets canOpen veto an address its globs matched', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register(typeFor('image', ['*.png'], { canOpen: address => address.startsWith('dsh-resource://file/') }))
+    expect(registry.claim('dsh-resource://file/session/s/shot.png').kind).toBe('image')
+    expect(ranked(registry, 'https://example.com/shot.png')).toEqual([])
+  })
+
+  it('opens with a named type, skipping its globs but honouring its canOpen', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register(typeFor('text', ['dsh-resource://file/**'], { canOpen: address => !address.endsWith('.bin') }))
+    expect(registry.claim('sidebar://guide', 'text').kind).toBe('text')
+    expect(() => registry.claim('dsh-resource://file/session/s/a.bin', 'text')).toThrow('tab type "text" refuses')
+    expect(() => registry.claim('dsh-resource://file/session/s/a.txt', 'nope')).toThrow('no tab type is registered as "nope"')
+  })
+
+  it('answers with the address as contentId and the type\'s title', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register(typeFor('text', ['dsh-resource://file/**']))
+    expect(registry.claim('dsh-resource://file/session/s/a.txt')).toEqual({
+      kind: 'text',
+      contentId: 'dsh-resource://file/session/s/a.txt',
+      title: 'text:dsh-resource://file/session/s/a.txt',
+    })
+  })
+
+  it('reads the title fresh, so a language change needs no re-registration', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    let language = 'zh'
+    registry.register({ id: 'shipped/guide', kind: 'guide', title: () => language === 'zh' ? '开始' : 'Start' })
+    expect(registry.get('guide')?.title('sidebar://guide')).toBe('开始')
+    language = 'en'
+    expect(registry.get('guide')?.title('sidebar://guide')).toBe('Start')
+  })
+})
+
+describe('SidebarRightTabRegistry — ids and page types', () => {
+  it('answers by kind with the definition in force, whose id is where its body lives', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    const disposeBuiltin = registry.register(typeFor('text', ['dsh-resource://file/**'], { id: 'shipped/text', priority: 'builtin' }))
+    expect(registry.get('text')?.id).toBe('shipped/text')
+    const disposeExtension = registry.register(typeFor('text', ['*.txt'], { id: 'third-party/text' }))
+    expect(registry.get('text')?.id).toBe('third-party/text')
+    disposeExtension()
+    expect(registry.get('text')?.id).toBe('shipped/text')
+    disposeBuiltin()
+    expect(registry.get('text')).toBeUndefined()
+  })
+
+  it('lets a page type omit patterns: it claims no address but is found by kind, and its guide entries carry its kind', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register({
+      id: 'shipped/files',
+      kind: 'files',
+      priority: 'builtin',
+      title: () => 'Files',
+      guide: [{ order: 10, title: () => 'Files', description: () => 'Browse' }],
+    })
+    expect(ranked(registry, 'dsh-resource://file/session/s/a.txt')).toEqual([])
+    expect(registry.get('files')?.title('x')).toBe('Files')
+    expect(registry.guide().map(entry => [entry.kind, entry.order])).toEqual([['files', 10]])
+  })
+})
+
+describe('SidebarRightTabRegistry — lifetime', () => {
+  it('lists registered types in registration order', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register(typeFor('guide', ['sidebar://guide']))
+    registry.register(typeFor('text', ['dsh-resource://file/**']))
+    expect(registry.entries().map(entry => entry.kind)).toEqual(['guide', 'text'])
+  })
+
+  it('refuses a second type for the same kind in the same band', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register(typeFor('text', ['dsh-resource://file/**']))
+    expect(() => registry.register(typeFor('text', ['other://**'], { id: 'other/text' })))
+      .toThrow('tab kind "text" is already registered')
+  })
+
+  it('drops a type when its owner disposes, and frees the kind again', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    const dispose = registry.register(typeFor('text', ['dsh-resource://file/**']))
+    dispose()
+    expect(registry.entries()).toEqual([])
+    expect(registry.get('text')).toBeUndefined()
+    expect(() => registry.register(typeFor('text', ['other://**']))).not.toThrow()
+  })
+
+  it('drops a type registered inside another plugin\'s effect when that plugin is disposed', async () => {
+    const ctx = new Context()
+    const registry = new SidebarRightTabRegistry(ctx)
+    const fiber = ctx.plugin({
+      apply(inner: Context) {
+        inner.effect(() => registry.register(typeFor('text', ['dsh-resource://file/**'])), 'test: text type')
+      },
+    })
+    await fiber.await()
+    expect(registry.get('text')).toBeDefined()
+    await fiber.dispose()
+    expect(registry.get('text')).toBeUndefined()
+  })
+
+  it('collects every type\'s guide entries in order, reference-stable between changes', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    const entry = (order: number) => ({ order, title: () => `#${order}`, description: () => '' })
+    registry.register(typeFor('files', [], { guide: [entry(10)] }))
+    const first = registry.guide()
+    expect(registry.guide()).toBe(first)
+    registry.register(typeFor('artifacts', [], { guide: [entry(5)] }))
+    registry.register(typeFor('text', ['dsh-resource://file/**']))
+    expect(registry.guide().map(item => item.kind)).toEqual(['artifacts', 'files'])
+    expect(registry.guide()).not.toBe(first)
+  })
+
+  it('notifies subscribers on registration and on disposal', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    const seen = vi.fn()
+    const unsubscribe = registry.subscribe(seen)
+    const dispose = registry.register(typeFor('text', ['dsh-resource://file/**']))
+    expect(seen).toHaveBeenCalledTimes(1)
+    dispose()
+    expect(seen).toHaveBeenCalledTimes(2)
+    unsubscribe()
+    registry.register(typeFor('other', ['other://**']))
+    expect(seen).toHaveBeenCalledTimes(2)
+  })
+
+  it('keeps entries reference-stable between changes', () => {
+    const registry = new SidebarRightTabRegistry(new Context())
+    registry.register(typeFor('text', ['dsh-resource://file/**']))
+    const first = registry.entries()
+    expect(registry.entries()).toBe(first)
+    registry.register(typeFor('guide', ['sidebar://guide']))
+    expect(registry.entries()).not.toBe(first)
+  })
+})
diff --git a/packages/client/ui-sidebar-right/tsconfig.json b/packages/client/ui-sidebar-right/tsconfig.json
new file mode 100644
index 0000000000..d1878df260
--- /dev/null
+++ b/packages/client/ui-sidebar-right/tsconfig.json
@@ -0,0 +1,48 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../api/session-controller/tsconfig.client.json"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../resources"
+    },
+    {
+      "path": "../store"
+    },
+    {
+      "path": "../ui-conversation"
+    },
+    {
+      "path": "../ui-dockkit"
+    },
+    {
+      "path": "../ui-layout"
+    },
+    {
+      "path": "../ui-primitives"
+    },
+    {
+      "path": "../ui-renderer"
+    },
+    {
+      "path": "../ui-session"
+    },
+    {
+      "path": "../ui-slots"
+    }
+  ]
+}
diff --git a/packages/client/ui-sidebar-right/tsdown.config.ts b/packages/client/ui-sidebar-right/tsdown.config.ts
new file mode 100644
index 0000000000..559865cdcd
--- /dev/null
+++ b/packages/client/ui-sidebar-right/tsdown.config.ts
@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-ui-sidebar-right', ['lib/types/index.js'])
diff --git a/packages/client/ui-sidebar-textpreview/README.i18n.yaml b/packages/client/ui-sidebar-textpreview/README.i18n.yaml
new file mode 100644
index 0000000000..3336e9ce03
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/client/ui-sidebar-textpreview/README.md
+README.md: aa8364023637598ca84635321376fed07eef90cf
+README.zh.md: ab157cb83045f414bf9cc9547c838d5c41cfd286
diff --git a/packages/client/ui-sidebar-textpreview/README.md b/packages/client/ui-sidebar-textpreview/README.md
new file mode 100644
index 0000000000..aa83640236
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/README.md
@@ -0,0 +1,81 @@
+---
+description: "The right Sidebar's plain-text viewer tab type for the dsh web client: paged reads of one workspace file, line navigation, wrap, reload, and the fallback claim on every file resource address."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-client-ui-sidebar-textpreview
+
+English | [中文](README.zh.md)
+
+## Summary
+
+The right Sidebar's plain-text viewer: one workspace text file, read one page of lines at a time, with line navigation, wrap, and reload. It is the fallback type for every `file` resource address, and the template for a tab type shipped from outside `ui-sidebar-right`: every import from the Sidebar is a type, the file's metadata comes from the shared `file` resource, the text is the type's own business, and the type's controls live in its own body.
+
+## Table of Contents
+
+- [What it registers](#what-it-registers)
+- [Addresses](#addresses)
+- [How it reads](#how-it-reads)
+- [Navigation](#navigation)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="what-it-registers"></a>
+## What it registers
+
+- **The type** — `ctx.sidebarRightTabs.register(...)` with id `@deepseek-ai/dsh-client-ui-sidebar-textpreview` (this implementation's identity in the tab system, and the key its body registers under), kind `text`, pattern `dsh-resource://file/**`, band `fallback`. A type registered at the `extension` or `builtin` band for a narrower pattern (say `*.png`) takes those addresses; everything else lands here. The whole address is the content identity, so two files with one name in different directories, or one path under two sessions, are two tabs; the decoded basename is the tab title.
+- **The body** — the keyed `sidebar.right.pane.tab` seat under the type's id. Its header row shows the Host's absolute path and exposes its full value in a tooltip, with the type's two controls at its end: a wrap toggle (on by default; long lines wrap until the reader turns it off, per tab) and a reload button. The Sidebar's tab strip carries no controls of this type. The body takes the pane body's full height: the header row stays put and the file body below is the one scroller, so a short file leaves no unstyled space and a long file scrolls under a fixed path. Until metadata provides an absolute path, the header uses the requested path.
+- **One store and one face**, session-scoped and bucketed by tab id. The store holds the pages read so far (keyed by the 1-based line each starts at, with the file version they belong to), the end-of-file flag, the read in flight or its failure, and the view: scroll offset, wrap (initially on), and the navigation revision the body last answered. The face (`loadPage`, `reloadPages`) performs the reads and writes through the store's actions. The bucket is forgotten when the owner's `signal` aborts, which is when the tab record is gone.
+
+<a id="addresses"></a>
+## Addresses
+
+A tab's address is `dsh-resource://file/session/<sessionId>/<path relative to that session's workspace root>` or `dsh-resource://file/absolute/<absolute path without its leading />` (a URI whose authority is the resource protocol, `file`, and whose path opens with the scope), built by `fileAddressFor` in `@deepseek-ai/dsh-util-workspace-path` and read back by `parseFileAddress`; every segment is component-encoded, and this package never splits the string itself. `hostFileOf` in `rpc.ts` turns the address into the session and path the endpoint takes: a `session` address reads under the session it names, with the relative path the Host resolves against that session's workspace root; an `absolute` address reads under the session the slot was mounted for, with the absolute path, and the Host's workspace confinement still applies. A malformed address throws, because the registry routes every `file` address to this type and a caller building one is expected to use the helper.
+
+<a id="how-it-reads"></a>
+## How it reads
+
+The body reads its record, navigation and lifetime through `useTabInfo().tab`. Metadata and content come from different places:
+
+- `useResource<'file'>(tab.contentId)`, the standard hook from `@deepseek-ai/dsh-client-resources`, yields `{ absolutePath, version, bytes, changed }` from the `file` provider in `@deepseek-ai/dsh-api-workspace-files`. The body reads `changed` and the failed state: when the agent wrote the file after the last `stat`, a bar announces it with a reload button, and when the resource is `failed` — the file gone, or the Host refusing it — a failure bar takes that place with the failure's line and the same reload button, ahead of any pending `changed`. Either way the pages already read stay on screen: the text is never replaced under the reader.
+- Pages come from `remote.workspaceFiles.read(sessionId, path, { offset }, signal)`, bound in `rpc.ts` and called by the face with the session and path the address names. The first mount reads the first page; a **Load more** button at the end of the loaded text reads the next until `eof`. Each page carries its line count (`lines`), which is how one empty line and a page past the end read differently. A first page from a newer file version replaces the pages of the older one; a later page from a newer version is not adopted — the walk restarts from the first page, so the body never mixes two versions. A failed page shows one sentence per `workspace-file/*` code (`not-found`, `outside-workspace`, `too-large` for a page over the byte cap, `not-text`, `not-regular-file`) or the transport's own message, with a retry for the same page.
+- **Reload** — the change bar's button and the header's reload control both call the resource's `reload()` (a fresh `stat`, which clears `changed`) and the face's `reloadPages` (drop the pages, read the first one again). A reload retires the reads still in flight — the face keeps a request generation per tab, and a page settling from an older generation writes nothing. The scroll offset is kept, so the reader stays where they were.
+
+Copy comes from the `sidebarTextpreview` locale namespace.
+
+<a id="navigation"></a>
+## Navigation
+
+`ctx.sidebarRight.openResource(address, { params: { line } })` — the `read` tool row passes its `offset` this way — arrives as `navigation.params`, which the body narrows to the `file` resource type's declared parameters (`SidebarRightResourceParamsMap['file']`, `{ line?: number }`, 1-based) without runtime validation: `params` is a typed same-process value. If the loaded pages do not reach that line, the body reads the next page, again, until they do or the file ends; then it scrolls the line to the top and marks it, once per `navigation.revision`. A body remounting for the same revision restores the reader's scroll offset instead. Opening the same file again without `revealIfOpened: false` focuses the existing tab and delivers the new parameters as a new revision.
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as the preview is a browser-only viewer that registers no tool, prompt section, or session event.
+
+#### KV Cache effect
+
+No direct effect; what the user reads here never enters a model request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+- **Plain text only.** No syntax highlighting, images, rendered markdown, or search; a directory address fails with `not-regular-file`.
+- **Sequential pages.** A line far into a large file loads every page before it; there is no seek to an arbitrary offset.
+- **Package-local wrap glyph.** `IconWrapOutline16` lives in `src/client/icons.tsx` until the shared icon set carries one; the props contract already matches.
+- **Scroll writes are unthrottled.** Every scroll event records its offset in the store; the line blocks are memoized so the resulting re-render hands React the same elements back.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>
+
+**Runtime invariant:** No companion is published. The type's only runtime state is one Slot store per tab, written by the body that owns it and forgotten on the tab's abort signal; there is no second observation of it to compare against.
diff --git a/packages/client/ui-sidebar-textpreview/README.zh.md b/packages/client/ui-sidebar-textpreview/README.zh.md
new file mode 100644
index 0000000000..ab157cb830
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/README.zh.md
@@ -0,0 +1,81 @@
+---
+description: "dsh Web 客户端右侧 Sidebar 的纯文本查看器 tab 类型：对一个工作区文件分页读取，带行导航、换行、重新读取，并兜底认领每个 file 资源地址。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-client-ui-sidebar-textpreview
+
+[English](README.md) | 中文
+
+## 概述
+
+右侧 Sidebar 的纯文本查看器：一个工作区文本文件，一次读一页行，带行号导航、换行与重新读取。它是每个 `file` 资源地址的兜底类型，也是 `ui-sidebar-right` 之外交付的 tab 类型的样板：来自 Sidebar 的每个 import 都是类型，文件的元数据来自共享的 `file` 资源，正文是类型自己的事，类型的控件住在自己的体里。
+
+## 目录
+
+- [注册了什么](#what-it-registers)
+- [地址](#addresses)
+- [怎么读](#how-it-reads)
+- [导航](#navigation)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="what-it-registers"></a>
+## 注册了什么
+
+- **类型** —— `ctx.sidebarRightTabs.register(...)`，id 为 `@deepseek-ai/dsh-client-ui-sidebar-textpreview`（这个实现在 tab 系统里的唯一键，也是其体注册所用的 key），kind `text`，pattern `dsh-resource://file/**`，档位 `fallback`。在 `extension` 或 `builtin` 档以更窄 pattern（比如 `*.png`）注册的类型接走那些地址；其余一切落到这里。整个地址就是内容身份，所以不同目录下同名的两个文件、或同一路径在两个会话之下，是两个 tab；解码后的 basename 是 tab 标题。
+- **体** —— keyed 坑位 `sidebar.right.pane.tab`，键为类型的 id。它的头部行显示 Host 的绝对路径，并在提示中保留完整值，末端是类型的两个控件：换行开关（默认开；长行折行直到读者关掉它，按 tab 记）与重新读取按钮。Sidebar 的 tab 条不承载这个类型的任何控件。体占满 pane 体的全部高度：头部行不动，其下的文件体是唯一的滚动者，于是短文件不留没有样式的空白，长文件在固定的路径下滚动。 元数据尚未提供绝对路径时，头部使用请求路径。
+- **一个 store 与一个 face**，会话作用域、按 tab id 分桶。store 持有已读的页（以每页起始的 1 起行号为键，连同它们所属的文件版本）、文件末尾标志、进行中的读取或其失败，以及视图：滚动位置、换行（初始为开）、体最近答过的导航 revision。face（`loadPage`、`reloadPages`）执行读取并经 store 的 action 写入。owner 的 `signal` abort 时——即 tab 记录消失时——桶被忘掉。
+
+<a id="addresses"></a>
+## 地址
+
+tab 的地址是 `dsh-resource://file/session/<sessionId>/<相对该会话工作区根的路径>` 或 `dsh-resource://file/absolute/<去掉前导 / 的绝对路径>`（一个 URI，authority 是资源协议 `file`，路径以作用域开头），由 `@deepseek-ai/dsh-util-workspace-path` 的 `fileAddressFor` 构造、`parseFileAddress` 读回；每段都做 component 编码，本包从不自己拆这个串。`rpc.ts` 里的 `hostFileOf` 把地址变成端点所需的会话与路径：`session` 地址在它命名的会话下读取，相对路径由 Host 对该会话的工作区根解析；`absolute` 地址在坑位被挂载的会话下以绝对路径读取，Host 的工作区限制照样适用。畸形地址直接抛错，因为注册表把每个 `file` 地址都路由给这个类型，造地址的调用方本应使用助手。
+
+<a id="how-it-reads"></a>
+## 怎么读
+
+正文通过 `useTabInfo().tab` 读取记录、导航和生命周期。元数据与内容来自不同的地方：
+
+- `useResource<'file'>(tab.contentId)`——来自 `@deepseek-ai/dsh-client-resources` 的标准 hook——从 `@deepseek-ai/dsh-api-workspace-files` 的 `file` 提供方得到 `{ absolutePath, version, bytes, changed }`。体读 `changed` 与失败态：agent 在上次 `stat` 之后写了文件时，一条提示带着重新载入按钮出现；资源为 `failed` 时——文件没了，或 Host 拒绝——一条失败条占据同一位置，显示失败句与同一个重新载入按钮，并优先于尚未处理的 `changed`。两种情况下已读的页都留在屏幕上：正文绝不在读者眼前被替换。
+- 页来自 `remote.workspaceFiles.read(sessionId, path, { offset }, signal)`，在 `rpc.ts` 绑定、由 face 以地址所命名的会话与路径调用。首次挂载读第一页；已加载文本末尾的 **加载更多** 按钮读下一页直到 `eof`。每页带着自己的行数（`lines`），单个空行与越过文件末尾的页由此区分。来自更新文件版本的第一页替换旧版本的页；更新版本的后续页不被采用——从第一页重新走一遍，于是体永不混合两个版本。失败的页按 `workspace-file/*` 错误码各显示一句（`not-found`、`outside-workspace`、超过字节上限的页 `too-large`、`not-text`、`not-regular-file`）或传输层自己的消息，并带一个重读同一页的重试。
+- **重新载入** —— 变更提示条的按钮与头部的重新读取控件都调用资源的 `reload()`（重新 `stat`，清掉 `changed`）与 face 的 `reloadPages`（丢掉所有页，重读第一页）。重载淘汰仍在飞的读取——face 按 tab 记请求代次，旧代次结算的页什么也不写。滚动位置保留，读者停在原处。
+
+文案来自 `sidebarTextpreview` locale 命名空间。
+
+<a id="navigation"></a>
+## 导航
+
+`ctx.sidebarRight.openResource(address, { params: { line } })`——`read` 工具行以此传它的 `offset`——以 `navigation.params` 到达，体把它收窄为 `file` 资源类型声明的参数（`SidebarRightResourceParamsMap['file']`，`{ line?: number }`，1 起），不做运行时校验：`params` 是同进程的类型化值。已加载的页够不到该行时，体读下一页，再读，直到覆盖它或文件结束；然后把该行滚到顶部并标记，每个 `navigation.revision` 一次。同一 revision 下重新挂载的体恢复读者的滚动位置而不再跳。不带 `revealIfOpened: false` 再次打开同一文件时聚焦已有 tab，并把新参数作为新 revision 送达。
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为预览是纯浏览器侧的查看器，不注册工具、提示词段或会话事件。
+
+#### KV Cache 影响
+
+无直接影响；用户在这里读到的东西永不进入模型请求。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+- **只有纯文本。** 没有语法高亮、图片、Markdown 渲染或搜索；目录地址以 `not-regular-file` 失败。
+- **页按顺序加载。** 大文件深处的一行要先加载它之前的每一页；没有到任意偏移的 seek。
+- **换行图标为包内自绘。** `IconWrapOutline16` 住在 `src/client/icons.tsx`，直到共享图标集提供为止；props 契约已经一致。
+- **滚动写入未节流。** 每次滚动事件都把偏移记进 store；行块已 memo 化，于是由此引发的重渲染交还给 React 的是同一批元素。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文——点击展开</summary>
+
+无。
+
+</details>
+
+**运行时不变量：** 不发布 companion。该类型唯一的运行时状态是每 tab 一份的 Slot store，由持有它的正文写入、随 tab 的中止信号忘掉；没有第二个观测源可与之比对。
diff --git a/packages/client/ui-sidebar-textpreview/package.json b/packages/client/ui-sidebar-textpreview/package.json
new file mode 100644
index 0000000000..5df323e5a0
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/package.json
@@ -0,0 +1,77 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-sidebar-textpreview",
+  "description": "Text preview tab type for the right Sidebar: the fallback viewer for file: addresses, drawn from the file resource with line navigation, wrap, and reload",
+  "version": "0.1.3-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/ui-sidebar-textpreview"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-api-workspace-files",
+        "@deepseek-ai/dsh-client-ui-sidebar-right",
+        "@deepseek-ai/dsh-client-ui-session",
+        "@deepseek-ai/dsh-api-remotes"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "clsx": "^2.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "workspace:^"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "workspace:^",
+    "@deepseek-ai/dsh-api-remotes": "workspace:^",
+    "@deepseek-ai/dsh-api-workspace-files": "workspace:^",
+    "@deepseek-ai/dsh-client-locale": "workspace:^",
+    "@deepseek-ai/dsh-client-resources": "workspace:^",
+    "@deepseek-ai/dsh-client-store": "workspace:^",
+    "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-dockkit": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-renderer": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-session": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-util-workspace-path": "workspace:^",
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ]
+}
diff --git a/packages/client/ui-sidebar-textpreview/src/client/TextPreview.module.css b/packages/client/ui-sidebar-textpreview/src/client/TextPreview.module.css
new file mode 100644
index 0000000000..1bd16a6a23
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/src/client/TextPreview.module.css
@@ -0,0 +1,169 @@
+/* The pane body is a block scroller with a definite height, not a flex
+   container, so the preview takes that height outright: the header row stays
+   put and the file body below is the one scroller, however short the file. */
+.preview {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+}
+
+/* One row: the path, then the type's controls at its end. */
+.header {
+  display: flex;
+  flex: 0 0 auto;
+  gap: 2px;
+  align-items: center;
+  padding: 3px 6px 3px 10px;
+  border-bottom: 0.5px solid var(--dsw-alias-border-l1);
+}
+
+.path {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 12px;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+/* Announced, not applied: the reader keeps the text they are looking at. */
+.changed {
+  display: flex;
+  flex: 0 0 auto;
+  gap: 10px;
+  align-items: center;
+  margin: 0;
+  padding: 6px 10px;
+  color: var(--dsw-alias-label-secondary);
+  font-size: 12px;
+  background: var(--dsw-alias-bg-layer-2);
+  border-bottom: 0.5px solid var(--dsw-alias-border-l1);
+}
+
+.body {
+  /* Lines are positioned against the scroller, so a line's offset is its scroll target. */
+  position: relative;
+  flex: 1 1 auto;
+  min-height: 0;
+  padding: 10px 0;
+  overflow: auto;
+  /* The notice and retry surfaces in this sheet are elevated, so the file body's
+     scroller rebinds the thumb indirection in a complete pair. */
+  --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
+  --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
+  color: var(--dsw-alias-label-primary);
+  font-size: var(--dsh-content-font-size-secondary, 13px);
+  font-family: var(--dsw-font-mono, ui-monospace, monospace);
+  line-height: 1.6;
+  white-space: pre;
+}
+
+.wrap {
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+/* One page of lines; pages abut so the file reads as one. */
+.page {
+  margin: 0;
+  font: inherit;
+  white-space: inherit;
+}
+
+.line {
+  padding: 0 10px;
+}
+
+.lineTarget {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.statusLine {
+  display: flex;
+  gap: 10px;
+  align-items: center;
+  margin: 0;
+  padding: 6px 10px;
+  color: var(--dsw-alias-label-secondary);
+  font-size: var(--dsh-content-font-size-secondary, 13px);
+  line-height: 1.6;
+  white-space: normal;
+}
+
+.status {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  align-items: flex-start;
+  padding: 12px 10px;
+}
+
+.action {
+  padding: 4px 10px;
+  color: var(--dsw-alias-label-primary);
+  font-size: var(--dsh-content-font-size-secondary, 13px);
+  font-family: var(--dsw-font, inherit);
+  white-space: normal;
+  background: var(--dsw-alias-bg-layer-2);
+  border: 0.5px solid var(--dsw-alias-border-l2);
+  border-radius: 6px;
+  cursor: pointer;
+}
+
+.action:hover {
+  background: var(--dsw-alias-bg-layer-3);
+}
+
+/* The next page, asked for where the loaded text ends. */
+.more {
+  display: block;
+  margin: 8px 10px;
+  padding: 4px 10px;
+  color: var(--dsw-alias-label-secondary);
+  font-size: 12px;
+  font-family: var(--dsw-font, inherit);
+  white-space: normal;
+  background: var(--dsw-alias-bg-layer-2);
+  border: 0.5px solid var(--dsw-alias-border-l2);
+  border-radius: 6px;
+  cursor: pointer;
+}
+
+.more:hover:not(:disabled) {
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-alias-bg-layer-3);
+}
+
+.more:disabled {
+  color: var(--dsw-alias-label-tertiary);
+  cursor: default;
+}
+
+/* Controls in the header row, sized like the docking kit's own pane controls. */
+.tool {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  color: var(--dsw-alias-label-secondary);
+  line-height: 1;
+  background: transparent;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+}
+
+.tool:hover {
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.toolOn {
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-alias-interactive-bg-hover);
+}
diff --git a/packages/client/ui-sidebar-textpreview/src/client/TextPreview.tsx b/packages/client/ui-sidebar-textpreview/src/client/TextPreview.tsx
new file mode 100644
index 0000000000..83ce3b5459
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/src/client/TextPreview.tsx
@@ -0,0 +1,265 @@
+/**
+ * The text preview's body: a file's pages, or the reason the next one is not showing.
+ *
+ * Two sources meet here. The standard `useResource` hook gives the file's
+ * metadata — its version and whether the agent wrote it since — and this type's
+ * own store holds the pages it read through its face. A Host-reported change is
+ * announced, not applied: reloading under a reader would lose their place, so
+ * the bar waits for a click. A failed metadata frame — the file gone, its
+ * workspace unknown — takes the same bar's place over the pages already loaded,
+ * with the same reload. The type's controls, wrap and reload, sit at the end of
+ * the path row; the Sidebar's strip carries none of them.
+ */
+import { useEffect, useMemo, useRef } from 'react'
+import type { ReactNode } from 'react'
+import clsx from 'clsx'
+import type { InjectFace, PropsLocale, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots'
+import { IconRefreshOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { TextInjected } from './face.ts'
+import { failureLine } from './failure-line.ts'
+import { IconWrapOutline16 } from './icons.tsx'
+import { hostFileOf } from './rpc.ts'
+import type { TextPage, TextStore } from './store.ts'
+import css from './TextPreview.module.css'
+
+/** The body's composed props: the tab, its navigation, the shared store and face, and copy. */
+export type TextPreviewProps =
+  & PropsRuntime<'sidebar.right.pane.tab'>
+  & PropsStore<TextStore>
+  & InjectFace<TextInjected>
+  & PropsLocale<'sidebarTextpreview'>
+
+/**
+ * A page's lines. The Host joins a page's lines with `\n` without a terminator
+ * and counts them, so a page past the file's last line (`lines: 0`) has none
+ * and a page holding one empty line (`lines: 1`, `text: ''`) has one; a
+ * trailing `\n` ends an empty last line.
+ * @param page - the page's text and line count.
+ * @returns the lines in order.
+ */
+export function linesOf(page: TextPage): string[] {
+  return page.lines === 0 ? [] : page.text.split('\n')
+}
+
+/** One loaded page: the 1-based line it starts at, its text, and its line count. */
+export interface LoadedPage extends TextPage {
+  readonly offset: number
+}
+
+/**
+ * The loaded pages in file order.
+ * @param pages - the store's page table.
+ * @returns the pages, ascending by offset.
+ */
+export function loadedPages(pages: Record<number, TextPage>): LoadedPage[] {
+  return Object.entries(pages)
+    .map(([offset, page]) => ({ offset: Number(offset), ...page }))
+    .sort((left, right) => left.offset - right.offset)
+}
+
+/**
+ * The last line the loaded pages reach, by the Host's line counts; 0 before the first page.
+ * @param pages - the loaded pages, ascending.
+ * @returns the 1-based last loaded line.
+ */
+export function lastLineLoaded(pages: readonly LoadedPage[]): number {
+  const last = pages.at(-1)
+  return last === undefined ? 0 : last.offset + last.lines - 1
+}
+
+/**
+ * Scroll the body so one line sits at its top. A line the pages do not hold
+ * leaves the body where it is.
+ * @param body - the scrolling container; lines are positioned against it.
+ * @param line - 1-based line.
+ */
+export function scrollToLine(body: HTMLElement, line: number): void {
+  const row = body.querySelector(`[data-textpreview-line="${line}"]`)
+  if (row instanceof HTMLElement) body.scrollTop = row.offsetTop
+}
+
+/**
+ * The text type's body, registered under `sidebar.right.pane.tab` as `text`.
+ * @param props - composed slot props.
+ * @returns the pages read so far with their controls, or a progress line.
+ */
+export function TextPreview({
+  useTabInfo, sessionId, useResource, useStore, actions, loadPage, reloadPages, t,
+}: TextPreviewProps): ReactNode {
+  const { tab } = useTabInfo()
+  const { navigation, signal } = tab
+  const meta = useResource<'file'>(tab.contentId)
+  const file = useMemo(() => hostFileOf(tab.contentId, sessionId), [tab.contentId, sessionId])
+  const state = useStore(s => s.byTab[tab.id])
+  const bodyRef = useRef<HTMLDivElement>(null)
+  // Every tab of this type is a `file` resource address, so its params are the
+  // `file` type's; the union is narrowed on the one field read, not validated.
+  const line = navigation.params !== undefined && 'line' in navigation.params ? navigation.params.line : undefined
+  const pages = state?.pages
+  const loaded = useMemo(() => loadedPages(pages ?? {}), [pages])
+  const loadedThrough = lastLineLoaded(loaded)
+  const hasPages = loaded.length > 0
+
+  // First mount reads the first page; a body coming back to a tab with pages
+  // reads nothing, because the store outlives the body.
+  const started = state !== undefined
+  useEffect(() => {
+    if (!started) loadPage(tab.id, file, 1, signal)
+  }, [started, tab.id, file, signal, loadPage])
+
+  // Come back where the reader was once there are pages to scroll: on a remount,
+  // and after a reload rebuilt the pages. Keyed on page presence only, so a
+  // scroll write never re-lands.
+  useEffect(() => {
+    const body = bodyRef.current
+    if (hasPages && body !== null && state !== undefined) body.scrollTop = state.scrollTop
+  }, [hasPages])
+
+  // Answer a navigation once: a line the pages do not reach yet loads the next
+  // page (again, until the pages cover it or the file ends); a line they hold
+  // is scrolled to and marked. The store remembers the answer, so a remount
+  // restores the reader's place instead.
+  useEffect(() => {
+    const body = bodyRef.current
+    if (state === undefined || body === null || state.revision === navigation.revision) return
+    if (line === undefined) {
+      actions.navigated(tab.id, navigation.revision)
+      return
+    }
+    if (line > loadedThrough && !state.eof) {
+      if (!state.loading && state.failure === undefined) loadPage(tab.id, file, loadedThrough + 1, signal)
+      return
+    }
+    scrollToLine(body, line)
+    actions.navigated(tab.id, navigation.revision)
+    // Recorded here as well as by the scroll event, so the store holds the
+    // landing before any later navigation reads it.
+    actions.scrolled(tab.id, body.scrollTop)
+  }, [navigation.revision, line, loadedThrough, state?.eof, state?.loading, state?.failure, started])
+
+  // One block per line inside one block per page, so a line has an offset to
+  // scroll to and a target can be marked. The trailing newline keeps an empty
+  // line one line tall. Memoized so a scroll write's re-render hands React the
+  // same elements back.
+  const rows = useMemo(() => loaded.map(page => (
+    <pre key={page.offset} className={css.page} data-textpreview-page={page.offset}>
+      {linesOf(page).map((content, index) => {
+        const number = page.offset + index
+        const target = number === line
+        return (
+          <div
+            key={number}
+            className={clsx(css.line, target && css.lineTarget)}
+            data-textpreview-line={number}
+            {...target ? { 'data-textpreview-target': number } : {}}
+          >
+            {content}{'\n'}
+          </div>
+        )
+      })}
+    </pre>
+  )), [loaded, line])
+
+  if (state === undefined) {
+    return (
+      <div className={css.status} data-textpreview-state="loading">
+        <p className={css.statusLine}>{t('loading')}</p>
+      </div>
+    )
+  }
+  const next = loadedThrough + 1
+  const displayPath = meta.value?.absolutePath ?? file.path
+  // Reload does two things at once: stat again through the resource (which
+  // clears `changed`, or a failed frame) and read the pages again through the face.
+  const reload = (): void => { meta.reload(); reloadPages(tab.id, file, signal) }
+  return (
+    <div className={css.preview} data-textpreview-state="text" data-textpreview-url={tab.contentId}>
+      {meta.failure !== undefined
+        ? (
+          // The file's metadata failed — gone, or its workspace unknown — which
+          // outranks a pending change; the pages already read stay under it.
+          <p className={css.changed} data-textpreview-meta-failed={meta.failure.code}>
+            <span>{failureLine(t, meta.failure)}</span>
+            <button
+              type="button"
+              className={css.action}
+              data-textpreview-reload-now
+              onClick={reload}
+            >
+              {t('reloadNow')}
+            </button>
+          </p>
+        )
+        : meta.value?.changed === true && (
+          <p className={css.changed} data-textpreview-changed>
+            <span>{t('changed')}</span>
+            <button
+              type="button"
+              className={css.action}
+              data-textpreview-reload-now
+              onClick={reload}
+            >
+              {t('reloadNow')}
+            </button>
+          </p>
+        )}
+      <div className={css.header}>
+        <div className={css.path} title={displayPath} data-textpreview-path>{displayPath}</div>
+        <button
+          type="button"
+          className={clsx(css.tool, state.wrap && css.toolOn)}
+          aria-pressed={state.wrap}
+          aria-label={t('wrap')}
+          title={t('wrap')}
+          data-textpreview-tool="wrap"
+          onClick={() => { actions.toggledWrap(tab.id) }}
+        >
+          <IconWrapOutline16 />
+        </button>
+        <button
+          type="button"
+          className={css.tool}
+          aria-label={t('reload')}
+          title={t('reload')}
+          data-textpreview-tool="reload"
+          onClick={reload}
+        >
+          <IconRefreshOutline16 />
+        </button>
+      </div>
+      <div
+        ref={bodyRef}
+        className={clsx(css.body, state.wrap && css.wrap)}
+        data-textpreview-body
+        data-textpreview-wrap={state.wrap ? '' : undefined}
+        onScroll={(event) => { actions.scrolled(tab.id, event.currentTarget.scrollTop) }}
+      >
+        {rows}
+        {state.failure !== undefined && (
+          <p className={css.statusLine} data-textpreview-failed={state.failure.code}>
+            <span>{failureLine(t, state.failure)}</span>
+            <button
+              type="button"
+              className={css.action}
+              data-textpreview-retry
+              onClick={() => { loadPage(tab.id, file, next, signal) }}
+            >
+              {t('retry')}
+            </button>
+          </p>
+        )}
+        {!state.eof && state.failure === undefined && (
+          <button
+            type="button"
+            className={css.more}
+            disabled={state.loading}
+            data-textpreview-more
+            onClick={() => { loadPage(tab.id, file, next, signal) }}
+          >
+            {state.loading ? t('loading') : t('loadMore')}
+          </button>
+        )}
+      </div>
+    </div>
+  )
+}
diff --git a/packages/client/ui-sidebar-textpreview/src/client/definition.ts b/packages/client/ui-sidebar-textpreview/src/client/definition.ts
new file mode 100644
index 0000000000..9a6cf946b8
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/src/client/definition.ts
@@ -0,0 +1,54 @@
+/**
+ * Stage one of this package's registration: what the `text` tab type IS.
+ *
+ * The type claims every `dsh-resource://file/` address in either scope —
+ * `session/<sessionId>/<path>` or `absolute/<path>` — at the `fallback` band: it
+ * is the plain viewer that any more specific type for the same address should
+ * beat, the position VS Code's text editor holds among its editors. `canOpen`
+ * refuses an address `parseFileAddress` rejects at claim time, where an
+ * unclaimed address is the documented wiring error.
+ */
+import type { SidebarRightTabDefinition } from '@deepseek-ai/dsh-client-ui-sidebar-right/client'
+import { parseFileAddress } from '@deepseek-ai/dsh-util-workspace-path'
+
+/** The tab kind this package owns. */
+export const TEXTPREVIEW_KIND = 'text'
+
+/** This implementation's identity in the tab system: the key its body registers under. */
+export const TEXTPREVIEW_ID = '@deepseek-ai/dsh-client-ui-sidebar-textpreview'
+
+/**
+ * The tab title for one `file:` address: its decoded basename.
+ *
+ * The whole address stays the content identity, so two files with one name in
+ * different directories are two tabs; only the chip text is shortened. Decoding
+ * is per segment, matching how the address was built, so a name carrying `#`,
+ * `?`, or a space reads as itself.
+ * @param address - a `file:`-shaped address.
+ * @returns the decoded last path segment, or the address itself when it has none.
+ */
+export function basenameOf(address: string): string {
+  const name = address.slice(address.lastIndexOf('/') + 1)
+  if (name === '') return address
+  try {
+    return decodeURIComponent(name)
+  } catch {
+    // A malformed percent sequence is still a name; showing it raw beats refusing the address.
+    return name
+  }
+}
+
+/**
+ * The text type's registry definition.
+ * @returns the definition to register.
+ */
+export function textDefinition(): SidebarRightTabDefinition {
+  return {
+    id: TEXTPREVIEW_ID,
+    kind: TEXTPREVIEW_KIND,
+    patterns: ['dsh-resource://file/**'],
+    priority: 'fallback',
+    canOpen: address => parseFileAddress(address) !== undefined,
+    title: basenameOf,
+  }
+}
diff --git a/packages/client/ui-sidebar-textpreview/src/client/face.ts b/packages/client/ui-sidebar-textpreview/src/client/face.ts
new file mode 100644
index 0000000000..fdf5f1d282
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/src/client/face.ts
@@ -0,0 +1,111 @@
+/**
+ * The preview's asynchronous half: reading pages into the store.
+ *
+ * The component never awaits anything. It asks for a page and this face performs
+ * the read and writes the outcome through the store's own actions — the
+ * Slot-standard `inject` form, so the write set stays the store's. The session
+ * the read runs under comes from the file's address, not from the slot's
+ * session: the address is the read's whole authority.
+ *
+ * A tab's pages are one file version walked from the first line. Dropping them
+ * — a reload, or a page of a newer version arriving past the first line, which
+ * restarts the walk — retires every read still in flight for the tab: a
+ * settlement from before the drop writes nothing. Cleanup rides the owner's
+ * `signal`, armed once per tab by its first read: the abort forgets the tab's
+ * bucket and this bookkeeping, a request is not made for a record that already
+ * ended, and a settlement arriving after the record is gone has nothing left to
+ * write to. A tab that never read has no bucket to forget.
+ */
+import type { BoundActions } from '@deepseek-ai/dsh-client-store'
+import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { ReadWorkspaceFilePage, SessionFile } from './rpc.ts'
+import type { TextStore } from './store.ts'
+
+/** The preview's injected business face, as the body receives it. */
+export interface TextInjected {
+  /**
+   * Read one page into the store. A page of a newer file version than the pages
+   * held, arriving past the first line, is not kept: the tab's pages are dropped
+   * and the first page read again. The tab's first read arms the abort listener
+   * that forgets its bucket when the record ends.
+   * @param tabId - the tab being drawn.
+   * @param file - the session and workspace path the tab's address names.
+   * @param offset - 1-based line the page starts at.
+   * @param signal - the tab record's lifetime.
+   */
+  readonly loadPage: (tabId: TabId, file: SessionFile, offset: number, signal: AbortSignal) => void
+  /**
+   * Drop every page and read the first one again, for a file the Host reports
+   * changed. The view is kept, so the reader stays where they were; a page read
+   * still in flight writes nothing when it settles.
+   * @param tabId - the tab being drawn.
+   * @param file - the session and workspace path the tab's address names.
+   * @param signal - the tab record's lifetime.
+   */
+  readonly reloadPages: (tabId: TabId, file: SessionFile, signal: AbortSignal) => void
+}
+
+/**
+ * What the face remembers of one tab: the read generation a settlement must
+ * match, and the version of the pages held. Created by the tab's first read,
+ * which also arms the one abort listener that forgets the tab.
+ */
+interface TabReads {
+  generation: number
+  version: string | undefined
+}
+
+/**
+ * Bind the preview's face to one paged read.
+ * @param read - the bound `workspaceFiles.read` call.
+ * @returns the Slot `inject` factory: bound actions in, face out. The slot's session id is unused because the address carries its own.
+ */
+export function textFace(read: ReadWorkspaceFilePage): (sessionId: SessionId, actions: BoundActions<TextStore>) => TextInjected {
+  return (_sessionId: SessionId, actions: BoundActions<TextStore>): TextInjected => {
+    const tabs = new Map<TabId, TabReads>()
+    // Reached with a live signal only: the record's end forgets the tab's
+    // bucket and this bookkeeping in one listener, however often its body mounts.
+    const readsOf = (tabId: TabId, signal: AbortSignal): TabReads => {
+      const held = tabs.get(tabId)
+      if (held !== undefined) return held
+      const created: TabReads = { generation: 0, version: undefined }
+      tabs.set(tabId, created)
+      signal.addEventListener('abort', () => {
+        tabs.delete(tabId)
+        actions.forget(tabId)
+      }, { once: true })
+      return created
+    }
+    const loadPage = (tabId: TabId, file: SessionFile, offset: number, signal: AbortSignal): void => {
+      if (signal.aborted) return
+      const reads = readsOf(tabId, signal)
+      const { generation } = reads
+      actions.loading(tabId)
+      void read(file.sessionId, file.path, offset, signal).then((result) => {
+        if (signal.aborted || reads.generation !== generation) return
+        if (!result.ok) {
+          actions.failed(tabId, result.error)
+          return
+        }
+        // Pages of two versions never meet: a newer file past the first line
+        // restarts the walk from line 1, where the store adopts the new version.
+        if (offset !== 1 && reads.version !== undefined && result.value.version !== reads.version) {
+          restart(tabId, file, signal)
+          return
+        }
+        reads.version = result.value.version
+        actions.page(tabId, result.value)
+      })
+    }
+    const restart = (tabId: TabId, file: SessionFile, signal: AbortSignal): void => {
+      if (signal.aborted) return
+      const reads = readsOf(tabId, signal)
+      reads.generation += 1
+      reads.version = undefined
+      actions.reset(tabId)
+      loadPage(tabId, file, 1, signal)
+    }
+    return { loadPage, reloadPages: restart }
+  }
+}
diff --git a/packages/client/ui-sidebar-textpreview/src/client/failure-line.ts b/packages/client/ui-sidebar-textpreview/src/client/failure-line.ts
new file mode 100644
index 0000000000..a8caee1e1c
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/src/client/failure-line.ts
@@ -0,0 +1,36 @@
+/**
+ * The failure line one Remote code deserves.
+ *
+ * Kept apart from the component so the mapping is testable on its own. Codes
+ * this reader does not name fall to the generic line carrying the carrier's
+ * message.
+ */
+import type { RemoteFailure } from '@deepseek-ai/dsh-api-remotes/client'
+import type { TranslateNS } from '@deepseek-ai/dsh-client-locale/client'
+
+/** Render a byte count the way a person reads one. */
+function humanBytes(bytes: number): string {
+  if (bytes >= 1024 * 1024) return `${Math.round(bytes / (1024 * 1024))} MB`
+  if (bytes >= 1024) return `${Math.round(bytes / 1024)} KB`
+  return `${bytes} B`
+}
+
+/**
+ * Say what went wrong, in terms of the file rather than of the transport.
+ * @param t - namespace-bound translate.
+ * @param failure - the settled Remote failure.
+ * @returns the line to show in place of the file.
+ */
+export function failureLine(t: TranslateNS<'sidebarTextpreview'>, failure: RemoteFailure): string {
+  switch (failure.code) {
+    case 'workspace-file/not-found': return t('error.notFound')
+    case 'workspace-file/outside-workspace': return t('error.outsideWorkspace')
+    case 'workspace-file/too-large':
+      return t('error.tooLarge', { limit: humanBytes(failure.details.limit) })
+    case 'workspace-file/not-text': return t('error.notText')
+    case 'workspace-file/not-regular-file': return t('error.notRegularFile')
+    // Carrier and unclassified host failures reach the reader as themselves:
+    // this panel knows nothing useful to add to a transport-level message.
+    default: return t('error.unavailable', { message: failure.message })
+  }
+}
diff --git a/packages/client/ui-sidebar-textpreview/src/client/icons.tsx b/packages/client/ui-sidebar-textpreview/src/client/icons.tsx
new file mode 100644
index 0000000000..10428efb52
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/src/client/icons.tsx
@@ -0,0 +1,27 @@
+/**
+ * Glyphs this package draws that the shared icon set does not carry yet.
+ * Same props contract as `@deepseek-ai/dsh-client-ui-primitives` icons, so a
+ * shared replacement is a one-line import change.
+ */
+import type { IconProps } from '@deepseek-ai/dsh-client-ui-primitives'
+
+/** Three text lines, the middle one turning back under itself. */
+export const IconWrapOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg
+    width={size}
+    height={size}
+    className={className}
+    viewBox="0 0 16 16"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="1.3"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    xmlns="http://www.w3.org/2000/svg"
+  >
+    <path d="M2.5 4h11" />
+    <path d="M2.5 8h8.5a2.5 2.5 0 0 1 0 5H9.5" />
+    <path d="M11 11.5 9.5 13l1.5 1.5" />
+    <path d="M2.5 12h3.5" />
+  </svg>
+)
diff --git a/packages/client/ui-sidebar-textpreview/src/client/index.ts b/packages/client/ui-sidebar-textpreview/src/client/index.ts
new file mode 100644
index 0000000000..ee3fd06ac2
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/src/client/index.ts
@@ -0,0 +1,73 @@
+/**
+ * Browser half: register `text` as a right-Sidebar tab type.
+ *
+ * The type reaches the Sidebar through its public path only: the definition into
+ * `ctx.sidebarRightTabs` and the body into the keyed `sidebar.right.pane.tab`
+ * seat under the definition's `id`. Nothing here reaches into the Sidebar's store, its
+ * panes, or its sequence. The file's metadata comes from the standard
+ * `useResource`, served by the `file` provider; the text is this type's own
+ * business, read one page at a time through its face. Every import from another
+ * client plugin is a type.
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-api-remotes/client'
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+import type {} from '@deepseek-ai/dsh-client-resources/client'
+import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
+import type {} from '@deepseek-ai/dsh-client-ui-session/client'
+import type {} from '@deepseek-ai/dsh-client-ui-sidebar-right/client'
+import type { WorkspaceFileParams } from '@deepseek-ai/dsh-api-workspace-files/client'
+import { TextPreview } from './TextPreview.tsx'
+import { TEXTPREVIEW_ID, textDefinition } from './definition.ts'
+import { textFace } from './face.ts'
+import { createReadPage } from './rpc.ts'
+import { createTextStore } from './store.ts'
+import { en, zh } from './locales.ts'
+
+// Values stay package-private unless another package needs them; the plugin
+// surface is `apply`, `inject`, and the store factory another registration may
+// share, plus the types a consumer of the seat or the store names.
+export type { SidebarTextpreviewKey } from './locales.ts'
+export type { TextPreviewProps } from './TextPreview.tsx'
+export type { TextInjected } from './face.ts'
+export type { ReadWorkspaceFilePage, SessionFile, WorkspaceFilesReadRemote } from './rpc.ts'
+export type { TextPage, TextState, TextStore, TextTabState } from './store.ts'
+
+/** This package's copy namespace. */
+const NS = 'sidebarTextpreview'
+
+declare module '@deepseek-ai/dsh-client-ui-sidebar-right/client' {
+  interface SidebarRightResourceParamsMap {
+    /** File line navigation supported by the text preview. */
+    file: WorkspaceFileParams
+  }
+}
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap {
+    /** Text-preview progress, paging, change, control, and failure lines. */
+    sidebarTextpreview: import('./locales.ts').SidebarTextpreviewKey
+  }
+}
+
+/**
+ * Required browser services: the tab registry, the slot registry, copy, and the
+ * Remote carrier with its `workspaceFiles` namespace.
+ */
+export const inject = ['slots', 'locale', 'sidebarRightTabs', 'remote', 'remote.workspaceFiles']
+
+/**
+ * Client plugin body: register the type, its dictionaries, and its body.
+ * @param ctx - client root context carrying the registry, the slots, copy, and the Remote face.
+ */
+export function apply(ctx: ClientContext): void {
+  ctx.effect(() => ctx.sidebarRightTabs.register(textDefinition()), 'ui-sidebar-textpreview: text type')
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-sidebar-textpreview: dictionaries')
+
+  const store = createTextStore()
+  const face = textFace(createReadPage(ctx.remote))
+  ctx.effect(() => ctx.slots.inject('sidebar.right.pane.tab', () => ctx.slots.register(
+    { name: 'sidebar.right.pane.tab', key: TEXTPREVIEW_ID, locale: NS, store, inject: face },
+    TextPreview,
+  )), 'ui-sidebar-textpreview: text body')
+}
diff --git a/packages/client/ui-sidebar-textpreview/src/client/locales.ts b/packages/client/ui-sidebar-textpreview/src/client/locales.ts
new file mode 100644
index 0000000000..f0456c952e
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/src/client/locales.ts
@@ -0,0 +1,44 @@
+/**
+ * `sidebarTextpreview` namespace dictionaries.
+ *
+ * The failure lines are the point of this file: a preview that cannot show a
+ * page has to say which of several different things went wrong, and each one
+ * suggests a different next step for the reader.
+ */
+
+/** Simplified Chinese dictionary and key-set source of truth. */
+export const zh = {
+  loading: '正在读取…',
+  loadMore: '加载更多',
+  changed: '文件已被修改，显示的还是旧内容。',
+  reloadNow: '重新载入',
+  reload: '重新读取文件',
+  wrap: '自动换行',
+  'error.notFound': '这个文件不在了。可能已被移动或删除。',
+  'error.outsideWorkspace': '这个文件在工作区之外，侧栏不会读取它。',
+  'error.tooLarge': '这一页太大，侧栏不读取超过 {limit} 的页。',
+  'error.notText': '这不是文本文件，没法在这里查看。',
+  'error.notRegularFile': '这不是一个普通文件，没有可显示的文本。',
+  'error.unavailable': '读取失败：{message}',
+  retry: '重试',
+} satisfies Record<string, string>
+
+/** Text-preview dictionary key union. */
+export type SidebarTextpreviewKey = keyof typeof zh
+
+/** English dictionary, checked against the Chinese key set. */
+export const en = {
+  loading: 'Reading…',
+  loadMore: 'Load more',
+  changed: 'The file has changed; this is the older text.',
+  reloadNow: 'Reload',
+  reload: 'Read the file again',
+  wrap: 'Wrap lines',
+  'error.notFound': 'That file is gone. It may have been moved or deleted.',
+  'error.outsideWorkspace': 'That file is outside the workspace, so the sidebar will not read it.',
+  'error.tooLarge': 'That page is too large; the sidebar does not read pages above {limit}.',
+  'error.notText': 'That is not a text file, so it cannot be shown here.',
+  'error.notRegularFile': 'That is not a regular file, so it has no text to show.',
+  'error.unavailable': 'Read failed: {message}',
+  retry: 'Retry',
+} satisfies Record<SidebarTextpreviewKey, string>
diff --git a/packages/client/ui-sidebar-textpreview/src/client/rpc.ts b/packages/client/ui-sidebar-textpreview/src/client/rpc.ts
new file mode 100644
index 0000000000..1f5547b5bf
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/src/client/rpc.ts
@@ -0,0 +1,86 @@
+/**
+ * The paged read this type performs, bound to the Client Remote.
+ *
+ * Content is the consumer's business: the `file` resource carries metadata only,
+ * and the text arrives here one page of lines at a time. The endpoint takes a
+ * session and a workspace path while a tab carries a `dsh-resource://file/`
+ * address in one of two scopes, so this module also owns that translation.
+ */
+import type { RemoteResult } from '@deepseek-ai/dsh-api-remotes/client'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { WorkspaceFileRange, WorkspaceFileText } from '@deepseek-ai/dsh-api-workspace-files/types'
+import { parseFileAddress } from '@deepseek-ai/dsh-util-workspace-path'
+
+/** The slice of the Client Remote this package calls. */
+export interface WorkspaceFilesReadRemote {
+  readonly workspaceFiles: {
+    /**
+     * Read one page of lines.
+     * @param sessionId - the session whose workspace resolves `path`.
+     * @param path - workspace path, absolute or relative to the workspace root.
+     * @param range - 1-based start line; the Host's page cap applies when `limit` is absent.
+     * @param signal - cancels the call.
+     * @returns the page, or the failure the Host declares.
+     */
+    read(
+      sessionId: SessionId,
+      path: string,
+      range: WorkspaceFileRange,
+      signal?: AbortSignal,
+    ): Promise<RemoteResult<WorkspaceFileText>>
+  }
+}
+
+/**
+ * The read one page performs, injected so the face stays host-free.
+ *
+ * The session travels with the call because the endpoint resolves the workspace
+ * root from it: the same path means different files in different sessions. A
+ * Remote call does not reject: the result carries the failure.
+ */
+export type ReadWorkspaceFilePage = (
+  sessionId: SessionId,
+  path: string,
+  offset: number,
+  signal: AbortSignal,
+) => Promise<RemoteResult<WorkspaceFileText>>
+
+/** The file one tab reads: the session the read runs under and the path handed to the Host. */
+export interface SessionFile {
+  /** The session whose workspace confines the read. */
+  readonly sessionId: SessionId
+  /** The path the Host receives: workspace-relative for a `session` address, absolute for an `absolute` one. */
+  readonly path: string
+}
+
+/**
+ * The session and path one `dsh-resource://file/…` address names.
+ *
+ * A `session` address names its own session and a workspace-relative path, so
+ * a tab addressed into another session reads from that session. An `absolute`
+ * address carries no session and is read through the seat's own, which the
+ * Host confines to that session's workspace. The registry routes every
+ * parseable `file` address to this type, so an address `parseFileAddress`
+ * rejects is a programming error and throws.
+ * @param address - a tab's `dsh-resource://file/…` address.
+ * @param sessionId - the seat's session, which an `absolute` address is read through.
+ * @returns the session and the path to hand the endpoint.
+ */
+export function hostFileOf(address: string, sessionId: SessionId): SessionFile {
+  const parsed = parseFileAddress(address)
+  if (parsed === undefined) throw new Error(`ui-sidebar-textpreview: not a file address "${address}"`)
+  // The address is a string boundary: its id segment is the Session id it names.
+  return parsed.scope === 'session'
+    ? { sessionId: parsed.sessionId as SessionId, path: parsed.path }
+    : { sessionId, path: parsed.path }
+}
+
+/**
+ * Bind the paged read to one Remote face. The page length is the Host's
+ * configured cap, so no `limit` travels.
+ * @param remote - the Client Remote carrying the `workspaceFiles` namespace.
+ * @returns the read the face performs.
+ */
+export function createReadPage(remote: WorkspaceFilesReadRemote): ReadWorkspaceFilePage {
+  return (sessionId, path, offset, signal) => remote.workspaceFiles.read(sessionId, path, { offset }, signal)
+}
diff --git a/packages/client/ui-sidebar-textpreview/src/client/store.ts b/packages/client/ui-sidebar-textpreview/src/client/store.ts
new file mode 100644
index 0000000000..e3f9705314
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/src/client/store.ts
@@ -0,0 +1,193 @@
+/**
+ * The preview's own state: the pages it has read, and how the reader views them.
+ *
+ * The `file` resource carries metadata only, so the text is this type's to fetch
+ * and keep — page by page, keyed by the 1-based line each page starts at. The
+ * view state (scroll offset, wrap, the navigation already answered) must outlive
+ * the body: a tab switched away from unmounts its body and must come back where
+ * it was rather than re-read or jump to its opening line again. Bucketed by tab
+ * id because two tabs of one file scroll independently.
+ *
+ * A bucket lives as long as its tab record: the face's first read of a tab arms
+ * one listener on the owner's `signal` that forgets the bucket when the record
+ * ends, and a tab that never read has no bucket to forget.
+ */
+import type { RemoteFailure } from '@deepseek-ai/dsh-api-remotes/client'
+import { defineStore, type EngineStoreHandle } from '@deepseek-ai/dsh-client-store'
+import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+import type { WorkspaceFileText } from '@deepseek-ai/dsh-api-workspace-files/types'
+
+/**
+ * One page as the store keeps it: its text and the Host's line count, which
+ * tells a page past the file's last line (`lines: 0`) from a page holding one
+ * empty line (`lines: 1`, `text: ''`).
+ */
+export interface TextPage {
+  readonly text: string
+  readonly lines: number
+}
+
+/** One tab's pages and view. */
+export interface TextTabState {
+  /** The file version the loaded pages belong to; absent before the first page. */
+  version: string | undefined
+  /** Pages by the 1-based line each starts at. */
+  pages: Record<number, TextPage>
+  /** Whether the last loaded page reached the end of the file. */
+  eof: boolean
+  /** A page read is in flight. */
+  loading: boolean
+  /** Why the last page read failed; cleared by the next page. */
+  failure: RemoteFailure | undefined
+  /** Scroll offset of the body, in px. */
+  scrollTop: number
+  /** Whether long lines wrap instead of scrolling horizontally; on until the reader turns it off. */
+  wrap: boolean
+  /** The `navigation.revision` the body already answered; absent before the first. */
+  revision: number | undefined
+}
+
+/** Every tab's state, keyed by tab id. */
+export interface TextState {
+  byTab: Record<TabId, TextTabState>
+}
+
+/**
+ * A tab's state before it reads, scrolls, toggles, or answers anything.
+ * @returns the empty bucket.
+ */
+export function fresh(): TextTabState {
+  return {
+    version: undefined,
+    pages: {},
+    eof: false,
+    loading: false,
+    failure: undefined,
+    scrollTop: 0,
+    wrap: true,
+    revision: undefined,
+  }
+}
+
+/** The bucket for one tab, created on first write. */
+function bucket(state: TextState, tabId: TabId): TextTabState {
+  return state.byTab[tabId] ??= fresh()
+}
+
+/** The preview store's write set; every action names the tab it writes. */
+type TextActions = {
+  loading: (draft: TextState, tabId: TabId) => void
+  page: (draft: TextState, tabId: TabId, page: WorkspaceFileText) => void
+  failed: (draft: TextState, tabId: TabId, failure: RemoteFailure) => void
+  reset: (draft: TextState, tabId: TabId) => void
+  scrolled: (draft: TextState, tabId: TabId, scrollTop: number) => void
+  toggledWrap: (draft: TextState, tabId: TabId) => void
+  navigated: (draft: TextState, tabId: TabId, revision: number) => void
+  forget: (draft: TextState, tabId: TabId) => void
+}
+
+/**
+ * Declare the preview's store.
+ *
+ * Constructed once in apply and shared by the body and the tools registrations,
+ * which the slot runtime allows because both are session-scoped.
+ * @returns the store handle to declare on both registrations.
+ */
+export function createTextStore(): EngineStoreHandle<TextState, TextActions> {
+  return defineStore({
+    init: (): TextState => ({ byTab: {} }),
+    actions: {
+      /**
+       * Mark a page read as in flight.
+       * @param d - draft state.
+       * @param tabId - the tab being drawn.
+       */
+      loading: (d, tabId: TabId) => {
+        bucket(d, tabId).loading = true
+      },
+      /**
+       * Keep one page. A page from a newer file version invalidates the pages
+       * of the older one, so the body never shows two versions at once.
+       * @param d - draft state.
+       * @param tabId - the tab being drawn.
+       * @param page - the page the Host returned.
+       */
+      page: (d, tabId: TabId, page: WorkspaceFileText) => {
+        const state = bucket(d, tabId)
+        if (state.version !== undefined && state.version !== page.version) state.pages = {}
+        state.version = page.version
+        state.pages[page.offset] = { text: page.text, lines: page.lines }
+        state.eof = page.eof
+        state.loading = false
+        state.failure = undefined
+      },
+      /**
+       * Record why a page read failed; the pages already held stay.
+       * @param d - draft state.
+       * @param tabId - the tab being drawn.
+       * @param failure - the settled Remote failure.
+       */
+      failed: (d, tabId: TabId, failure: RemoteFailure) => {
+        const state = bucket(d, tabId)
+        state.loading = false
+        state.failure = failure
+      },
+      /**
+       * Drop every page, keeping the view, for a re-read from the first line.
+       * @param d - draft state.
+       * @param tabId - the tab being drawn.
+       */
+      reset: (d, tabId: TabId) => {
+        const state = bucket(d, tabId)
+        state.pages = {}
+        state.eof = false
+        state.version = undefined
+        state.failure = undefined
+      },
+      /**
+       * Record where one tab's body is scrolled to.
+       * @param d - draft state.
+       * @param tabId - the tab being drawn.
+       * @param scrollTop - the body's scroll offset, in px.
+       */
+      scrolled: (d, tabId: TabId, scrollTop: number) => {
+        bucket(d, tabId).scrollTop = scrollTop
+      },
+      /**
+       * Switch one tab between wrapped and unwrapped lines.
+       * @param d - draft state.
+       * @param tabId - the tab being drawn.
+       */
+      toggledWrap: (d, tabId: TabId) => {
+        const state = bucket(d, tabId)
+        state.wrap = !state.wrap
+      },
+      /**
+       * Record that the body answered one navigation, so a remount restores the
+       * reader's position instead of jumping again.
+       * @param d - draft state.
+       * @param tabId - the tab being drawn.
+       * @param revision - the `navigation.revision` answered.
+       */
+      navigated: (d, tabId: TabId, revision: number) => {
+        bucket(d, tabId).revision = revision
+      },
+      /**
+       * Drop one tab's state, for a tab record that is gone.
+       * @param d - draft state.
+       * @param tabId - the tab that went away.
+       */
+      forget: (d, tabId: TabId) => {
+        const byTab: TextState['byTab'] = {}
+        // Keys were written from tab ids; reading them back as ids is exact.
+        for (const [id, state] of Object.entries(d.byTab) as [TabId, TextTabState][]) {
+          if (id !== tabId) byTab[id] = state
+        }
+        d.byTab = byTab
+      },
+    },
+  })
+}
+
+/** The store handle type both registrations declare. */
+export type TextStore = ReturnType<typeof createTextStore>
diff --git a/packages/client/ui-sidebar-textpreview/src/css-modules.d.ts b/packages/client/ui-sidebar-textpreview/src/css-modules.d.ts
new file mode 100644
index 0000000000..bc5e482353
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/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-textpreview/src/index.ts b/packages/client/ui-sidebar-textpreview/src/index.ts
new file mode 100644
index 0000000000..a8b3f761b9
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/src/index.ts
@@ -0,0 +1,4 @@
+/** Pure host half; the whole preview lives in the browser export. */
+
+/** Host plugin body: the preview contributes nothing to the host tree. */
+export function apply(): void {}
diff --git a/packages/client/ui-sidebar-textpreview/tests/apply.client.spec.ts b/packages/client/ui-sidebar-textpreview/tests/apply.client.spec.ts
new file mode 100644
index 0000000000..a8687153da
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/tests/apply.client.spec.ts
@@ -0,0 +1,84 @@
+/**
+ * The plugin's registrations, and their removal when the plugin goes.
+ *
+ * The registry is real, because "registered" means what it says a type is; the
+ * slot, locale, and Remote faces are recorders, because what matters here is
+ * what was handed to them — one body seat under the type's kind with its store
+ * and face — and that every registration is gone after dispose, which is what
+ * makes a reload safe.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import { SidebarRightTabRegistry } from '@deepseek-ai/dsh-client-ui-sidebar-right/src/client/tab-registry.ts'
+import { TEXTPREVIEW_ID, TEXTPREVIEW_KIND } from '../src/client/definition.ts'
+import { apply, inject } from '../src/client/index.ts'
+import { apply as hostApply } from '../src/index.ts'
+import { TextPreview } from '../src/client/TextPreview.tsx'
+import { en, zh } from '../src/client/locales.ts'
+
+interface Recorded {
+  name: string
+  key: string
+  locale: string
+  store: unknown
+  inject: unknown
+  component: unknown
+}
+
+async function boot() {
+  const ctx = new Context()
+  const tabs = new SidebarRightTabRegistry(ctx)
+  const registered: Recorded[] = []
+  const slots = {
+    inject: vi.fn((_name: string, register: () => () => void) => register()),
+    register: vi.fn((options: Omit<Recorded, 'component'>, component: unknown) => {
+      const entry: Recorded = { ...options, component }
+      registered.push(entry)
+      return () => { registered.splice(registered.indexOf(entry), 1) }
+    }),
+  }
+  const dictionaries = new Map<string, unknown>()
+  const locale = {
+    register: vi.fn((ns: string, dicts: unknown) => {
+      dictionaries.set(ns, dicts)
+      return () => { dictionaries.delete(ns) }
+    }),
+  }
+  const workspaceFiles = { read: vi.fn() }
+  ctx.provide('sidebarRightTabs', tabs as never)
+  ctx.provide('slots', slots as never)
+  ctx.provide('locale', locale as never)
+  ctx.provide('remote', { workspaceFiles } as never)
+  ctx.provide('remote.workspaceFiles', workspaceFiles as never)
+  const fiber = ctx.plugin({ inject: [...inject], apply })
+  await fiber.await()
+  return { tabs, registered, dictionaries, fiber }
+}
+
+describe('ui-sidebar-textpreview apply', () => {
+  it('keeps the host Loader entry inert', () => {
+    expect(hostApply).not.toThrow()
+  })
+
+  it('registers the type, its dictionaries, and the body seat under the type\'s id with a store and a face', async () => {
+    const { tabs, registered, dictionaries } = await boot()
+    expect(tabs.get(TEXTPREVIEW_KIND)?.priority).toBe('fallback')
+    expect(tabs.get(TEXTPREVIEW_KIND)?.id).toBe(TEXTPREVIEW_ID)
+    expect(dictionaries.get('sidebarTextpreview')).toEqual({ zh, en })
+    // The seat key is the implementation's id, not the kind: an extension may
+    // take the kind over, and the seat must still find this body.
+    expect(registered.map(entry => [entry.name, entry.key, entry.locale, entry.component])).toEqual([
+      ['sidebar.right.pane.tab', TEXTPREVIEW_ID, 'sidebarTextpreview', TextPreview],
+    ])
+    expect(registered[0]?.store).toBeDefined()
+    expect(typeof registered[0]?.inject).toBe('function')
+  })
+
+  it('takes every registration back when the plugin is disposed', async () => {
+    const { tabs, registered, dictionaries, fiber } = await boot()
+    await fiber.dispose()
+    expect(tabs.get(TEXTPREVIEW_KIND)).toBeUndefined()
+    expect(registered).toEqual([])
+    expect(dictionaries.size).toBe(0)
+  })
+})
diff --git a/packages/client/ui-sidebar-textpreview/tests/definition.client.spec.ts b/packages/client/ui-sidebar-textpreview/tests/definition.client.spec.ts
new file mode 100644
index 0000000000..97fb367e10
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/tests/definition.client.spec.ts
@@ -0,0 +1,88 @@
+/**
+ * What the `text` type claims, and how it yields.
+ *
+ * The type is the fallback viewer for every `file` resource address, so the contract
+ * worth asserting is the yielding: a narrower type registered at a higher
+ * band takes its addresses, and everything else still lands here. Routing is
+ * exercised through the real registry, because "fallback" means whatever the
+ * registry's ranking means by it.
+ */
+import { describe, expect, it } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import { SidebarRightTabRegistry } from '@deepseek-ai/dsh-client-ui-sidebar-right/src/client/tab-registry.ts'
+import { TEXTPREVIEW_ID, TEXTPREVIEW_KIND, basenameOf, textDefinition } from '../src/client/definition.ts'
+
+describe('basenameOf', () => {
+  it('decodes the last segment, so an escaped name reads as itself', () => {
+    expect(basenameOf('dsh-resource://file/session/s-1/work/notes/a%20b%23c.md')).toBe('a b#c.md')
+  })
+
+  it('falls back to the whole address when there is no last segment', () => {
+    expect(basenameOf('dsh-resource://file/session/s-1/')).toBe('dsh-resource://file/session/s-1/')
+  })
+
+  it('keeps a malformed percent escape as it is rather than refusing the address', () => {
+    expect(basenameOf('dsh-resource://file/session/s-1/work/%E0%A4%A')).toBe('%E0%A4%A')
+  })
+})
+
+describe('textDefinition', () => {
+  it('is the fallback claimant of every file: address, titled by basename', () => {
+    const definition = textDefinition()
+    expect(definition.id).toBe(TEXTPREVIEW_ID)
+    expect(definition.kind).toBe(TEXTPREVIEW_KIND)
+    expect(definition.patterns).toEqual(['dsh-resource://file/**'])
+    expect(definition.priority).toBe('fallback')
+    expect(definition.title('dsh-resource://file/session/s-1/work/README.md')).toBe('README.md')
+    // Both scopes have a read endpoint here; anything the grammar rejects is refused.
+    expect(definition.canOpen?.('dsh-resource://file/session/s-1/work/README.md')).toBe(true)
+    expect(definition.canOpen?.('dsh-resource://file/absolute/home/me/README.md')).toBe(true)
+    expect(definition.canOpen?.('dsh-resource://file/shared/team/README.md')).toBe(false)
+    expect(definition.canOpen?.('dsh-resource://file/session')).toBe(false)
+  })
+})
+
+describe('text type in the registry', () => {
+  function registry() {
+    const tabs = new SidebarRightTabRegistry(new Context())
+    tabs.register(textDefinition())
+    return tabs
+  }
+
+  it('claims files of any extension, depth, and dot-prefix in either scope', () => {
+    const tabs = registry()
+    for (const address of [
+      'dsh-resource://file/session/s-1/a.md',
+      'dsh-resource://file/session/s-1/deep/er/path/x.py',
+      'dsh-resource://file/session/s-1/w/.env',
+      'dsh-resource://file/session/s-1/w/Makefile',
+      'dsh-resource://file/absolute/home/me/notes.md',
+      'dsh-resource://file/absolute/C:/w/x.ts',
+    ]) {
+      expect(tabs.claim(address)).toEqual({ kind: TEXTPREVIEW_KIND, contentId: address, title: basenameOf(address) })
+    }
+  })
+
+  it('refuses a file address in no known scope at claim time, named or ranked', () => {
+    const tabs = registry()
+    const shared = 'dsh-resource://file/shared/team/notes.md'
+    expect(tabs.candidates(shared)).toEqual([])
+    expect(() => tabs.claim(shared)).toThrow('no registered tab type claims')
+    expect(() => tabs.claim(shared, TEXTPREVIEW_KIND)).toThrow(`tab type "${TEXTPREVIEW_KIND}" refuses`)
+  })
+
+  it('yields an address to a narrower type at the extension band, and keeps the rest', () => {
+    const tabs = registry()
+    tabs.register({ id: 'test/image', kind: 'image', patterns: ['*.png'], priority: 'extension', title: () => 'image' })
+    expect(tabs.claim('dsh-resource://file/session/s-1/w/logo.png').kind).toBe('image')
+    expect(tabs.claim('dsh-resource://file/session/s-1/w/logo.md').kind).toBe(TEXTPREVIEW_KIND)
+    // Still listed for the picture: a caller naming the kind may open it as text.
+    expect(tabs.candidates('dsh-resource://file/session/s-1/w/logo.png').map(type => type.kind)).toEqual(['image', TEXTPREVIEW_KIND])
+  })
+
+  it('does not claim addresses of other schemes', () => {
+    const tabs = registry()
+    expect(() => tabs.claim('sidebar://guide')).toThrow('no registered tab type claims')
+    expect(() => tabs.claim('https://example.com/a.md')).toThrow('no registered tab type claims')
+  })
+})
diff --git a/packages/client/ui-sidebar-textpreview/tests/face.client.spec.ts b/packages/client/ui-sidebar-textpreview/tests/face.client.spec.ts
new file mode 100644
index 0000000000..289109a507
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/tests/face.client.spec.ts
@@ -0,0 +1,157 @@
+/**
+ * The face's contract with the store: a read in flight is visible, its outcome
+ * lands as a page or a failure, a read outlived by its tab writes nothing, a
+ * reload starts over from the first line and retires the reads still out, and
+ * a newer file version arriving past the first line restarts the walk. The read
+ * runs under the session the file names, not the one the face was injected for.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import type { RemoteResult } from '@deepseek-ai/dsh-api-remotes/client'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { WorkspaceFileText } from '@deepseek-ai/dsh-api-workspace-files/types'
+import { textFace } from '../src/client/face.ts'
+import type { ReadWorkspaceFilePage } from '../src/client/rpc.ts'
+import { createTextStore } from '../src/client/store.ts'
+import { FILE, PATH, SESSION, failure, page } from './fixtures.client.ts'
+import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+
+const TAB_1 = 'tab-1' as TabId
+
+/** One read awaiting the spec's answer. */
+interface PendingRead {
+  readonly offset: number
+  resolve(result: RemoteResult<WorkspaceFileText>): void
+}
+
+function bench() {
+  const instance = createTextStore().create()
+  const pending: PendingRead[] = []
+  const read = vi.fn<ReadWorkspaceFilePage>((_session, _path, offset) =>
+    new Promise((resolve) => { pending.push({ offset, resolve }) }))
+  // The store's own `forget`, counted: the record's end must forget a tab exactly once.
+  const forget = vi.fn(instance.actions.forget)
+  // Injected for another session on purpose: the address's session must win.
+  const face = textFace(read)('other-session' as SessionId, { ...instance.actions, forget })
+  /** Settle the oldest outstanding read, or the oldest one for `offset`. */
+  const settle = (result: RemoteResult<WorkspaceFileText>, offset?: number): void => {
+    const at = offset === undefined ? 0 : pending.findIndex(call => call.offset === offset)
+    const [call] = pending.splice(at, 1)
+    if (call === undefined) throw new Error('no outstanding read to settle')
+    call.resolve(result)
+  }
+  return {
+    instance, read, face, forget, settle,
+    outstanding: () => pending.map(call => call.offset),
+    tab: () => instance.getSnapshot().byTab[TAB_1],
+  }
+}
+
+const flush = (): Promise<void> => new Promise((resolve) => { setTimeout(resolve, 0) })
+
+describe('textFace', () => {
+  it('marks the read in flight, then keeps the page', async () => {
+    const { read, face, settle, tab } = bench()
+    const controller = new AbortController()
+    face.loadPage(TAB_1, FILE, 1, controller.signal)
+    expect(read).toHaveBeenCalledWith(SESSION, PATH, 1, controller.signal)
+    expect(tab()?.loading).toBe(true)
+    settle(page(1, ['a', 'b'], false))
+    await flush()
+    expect(tab()).toMatchObject({ loading: false, pages: { 1: { text: 'a\nb', lines: 2 } }, eof: false })
+  })
+
+  it('records a failed read', async () => {
+    const { face, settle, tab } = bench()
+    face.loadPage(TAB_1, FILE, 1, new AbortController().signal)
+    settle(failure('workspace-file/outside-workspace', { path: PATH }))
+    await flush()
+    expect(tab()?.failure?.code).toBe('workspace-file/outside-workspace')
+    expect(tab()?.loading).toBe(false)
+  })
+
+  it('forgets the tab when its record ends, once, however many reads armed it, and writes nothing afterwards', async () => {
+    const { read, face, forget, settle, tab } = bench()
+    const controller = new AbortController()
+    const armed = vi.spyOn(controller.signal, 'addEventListener')
+    face.loadPage(TAB_1, FILE, 1, controller.signal)
+    settle(page(1, ['a'], false))
+    await flush()
+    face.loadPage(TAB_1, FILE, 2, controller.signal)
+    face.reloadPages(TAB_1, FILE, controller.signal)
+    expect(armed.mock.calls.filter(([type]) => type === 'abort')).toHaveLength(1)
+    expect(tab()).toBeDefined()
+    controller.abort()
+    expect(forget).toHaveBeenCalledExactlyOnceWith(TAB_1)
+    expect(tab()).toBeUndefined()
+    // The reads still out settle into nothing, and no request is made for the ended record.
+    settle(page(1, ['A'], true))
+    await flush()
+    expect(tab()).toBeUndefined()
+    face.loadPage(TAB_1, FILE, 1, controller.signal)
+    face.reloadPages(TAB_1, FILE, controller.signal)
+    expect(read).toHaveBeenCalledTimes(3)
+    expect(tab()).toBeUndefined()
+  })
+
+  it('reloads from the first line, dropping the pages and keeping the view', async () => {
+    const { instance, read, face, settle, tab } = bench()
+    const controller = new AbortController()
+    face.loadPage(TAB_1, FILE, 1, controller.signal)
+    settle(page(1, ['a'], false))
+    await flush()
+    instance.actions.scrolled(TAB_1, 77)
+    face.reloadPages(TAB_1, FILE, controller.signal)
+    expect(tab()).toMatchObject({ pages: {}, eof: false, version: undefined, loading: true, scrollTop: 77 })
+    expect(read).toHaveBeenLastCalledWith(SESSION, PATH, 1, controller.signal)
+  })
+
+  it('drops a page that settles after a reload retired it, whichever lands first', async () => {
+    const { face, settle, outstanding, tab } = bench()
+    const signal = new AbortController().signal
+    face.loadPage(TAB_1, FILE, 1, signal)
+    settle(page(1, ['a', 'b', 'c'], false))
+    await flush()
+    // Load-more is out when the reader reloads: the new first page lands first.
+    face.loadPage(TAB_1, FILE, 4, signal)
+    face.reloadPages(TAB_1, FILE, signal)
+    expect(outstanding()).toEqual([4, 1])
+    settle(page(1, ['A'], false, 'v2'), 1)
+    await flush()
+    expect(tab()).toMatchObject({ pages: { 1: { text: 'A', lines: 1 } }, version: 'v2', eof: false, loading: false })
+    // The retired page lands afterwards and changes nothing, not even the end flag.
+    settle(page(4, ['d'], true), 4)
+    await flush()
+    expect(tab()).toMatchObject({ pages: { 1: { text: 'A', lines: 1 } }, version: 'v2', eof: false, loading: false })
+  })
+
+  it('starts the walk over when a page of a newer version arrives past the first line', async () => {
+    const { read, face, settle, outstanding, tab } = bench()
+    const signal = new AbortController().signal
+    face.loadPage(TAB_1, FILE, 1, signal)
+    settle(page(1, ['a', 'b', 'c'], false))
+    await flush()
+    face.loadPage(TAB_1, FILE, 4, signal)
+    // The file changed between the two reads: the page is not kept beside the older ones.
+    settle(page(4, ['D'], true, 'v2'))
+    await flush()
+    expect(tab()).toMatchObject({ pages: {}, version: undefined, eof: false, loading: true })
+    expect(read).toHaveBeenCalledTimes(3)
+    expect(outstanding()).toEqual([1])
+    settle(page(1, ['A', 'B'], true, 'v2'))
+    await flush()
+    expect(tab()).toMatchObject({ pages: { 1: { text: 'A\nB', lines: 2 } }, version: 'v2', eof: true, loading: false })
+  })
+
+  it('keeps a first page of a newer version, since the store drops the older pages for it', async () => {
+    const { face, settle, tab } = bench()
+    const signal = new AbortController().signal
+    face.loadPage(TAB_1, FILE, 1, signal)
+    settle(page(1, ['a'], false))
+    await flush()
+    // A retry of the first page after the file changed lands as the new version.
+    face.loadPage(TAB_1, FILE, 1, signal)
+    settle(page(1, ['A'], true, 'v2'))
+    await flush()
+    expect(tab()).toMatchObject({ pages: { 1: { text: 'A', lines: 1 } }, version: 'v2', eof: true })
+  })
+})
diff --git a/packages/client/ui-sidebar-textpreview/tests/failure-line.client.spec.ts b/packages/client/ui-sidebar-textpreview/tests/failure-line.client.spec.ts
new file mode 100644
index 0000000000..3e8a9935ee
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/tests/failure-line.client.spec.ts
@@ -0,0 +1,36 @@
+/**
+ * One sentence per endpoint code, and the transport's own words for anything else.
+ */
+import { describe, expect, it } from 'vitest'
+import type { RemoteFailure } from '@deepseek-ai/dsh-api-remotes/client'
+import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
+// The namespace declaration `TranslateNS<'sidebarTextpreview'>` resolves against.
+import type {} from '../src/client/index.ts'
+import { failureLine } from '../src/client/failure-line.ts'
+
+/** Key-echoing translate that also shows its parameters, so a formatted value is visible. */
+const t: TranslateNS<'sidebarTextpreview'> = (key, params) =>
+  params === undefined ? key : `${key}(${Object.entries(params).map(([k, v]) => `${k}=${String(v)}`).join(',')})`
+
+function failure(code: string, details: Record<string, unknown> = {}, message = 'boom'): RemoteFailure {
+  return { code, message, details } as unknown as RemoteFailure
+}
+
+describe('failureLine', () => {
+  it('names each workspace-file code', () => {
+    expect(failureLine(t, failure('workspace-file/not-found'))).toBe('error.notFound')
+    expect(failureLine(t, failure('workspace-file/outside-workspace'))).toBe('error.outsideWorkspace')
+    expect(failureLine(t, failure('workspace-file/not-text'))).toBe('error.notText')
+    expect(failureLine(t, failure('workspace-file/not-regular-file'))).toBe('error.notRegularFile')
+  })
+
+  it('states the byte cap the way a person reads one', () => {
+    expect(failureLine(t, failure('workspace-file/too-large', { limit: 512 }))).toBe('error.tooLarge(limit=512 B)')
+    expect(failureLine(t, failure('workspace-file/too-large', { limit: 4096 }))).toBe('error.tooLarge(limit=4 KB)')
+    expect(failureLine(t, failure('workspace-file/too-large', { limit: 3 * 1024 * 1024 }))).toBe('error.tooLarge(limit=3 MB)')
+  })
+
+  it('passes any other failure through in its own words', () => {
+    expect(failureLine(t, failure('gateway/internal', {}, 'socket closed'))).toBe('error.unavailable(message=socket closed)')
+  })
+})
diff --git a/packages/client/ui-sidebar-textpreview/tests/fixtures.client.ts b/packages/client/ui-sidebar-textpreview/tests/fixtures.client.ts
new file mode 100644
index 0000000000..72c480ae00
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/tests/fixtures.client.ts
@@ -0,0 +1,147 @@
+/**
+ * Shared harness for the body specs: a real store instance, a real face over a
+ * scripted paged read, a scripted `useResource`, and the owner props a tab
+ * record carries.
+ *
+ * The framework's standard kit is replaced by the few members these components
+ * read, behind one documented cast, so the specs exercise the components and
+ * not the slot runtime.
+ */
+import { vi } from 'vitest'
+import type { Mock } from 'vitest'
+import { act } from '@testing-library/react'
+import { useSyncExternalStore } from 'react'
+import type { RemoteFailure, RemoteResult } from '@deepseek-ai/dsh-api-remotes/client'
+import type { ResourceSnapshot } from '@deepseek-ai/dsh-client-resources/client'
+import type { WorkspaceFileResource } from '@deepseek-ai/dsh-api-workspace-files/client'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { WorkspaceFileText } from '@deepseek-ai/dsh-api-workspace-files/types'
+import type { TextPreviewProps } from '../src/client/TextPreview.tsx'
+import { textFace } from '../src/client/face.ts'
+import type { TextInjected } from '../src/client/face.ts'
+import type { ReadWorkspaceFilePage, SessionFile } from '../src/client/rpc.ts'
+import { createTextStore } from '../src/client/store.ts'
+import type { TextStore } from '../src/client/store.ts'
+import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+
+export const TAB_ID = 'tab-1' as TabId
+export const SESSION = 's-1' as SessionId
+/** The path relative to the session's workspace root, as the Host receives it. */
+export const PATH = 'work/notes.md'
+export const ABSOLUTE_PATH = '/host/project/work/notes.md'
+/** The tab's address: the file under this session's scope. */
+export const ADDRESS = 'dsh-resource://file/session/s-1/work/notes.md'
+/** What the address names, as the face receives it. */
+export const FILE: SessionFile = { sessionId: SESSION, path: PATH }
+
+/** One page the Host would return: the lines joined without a terminator, and their count. */
+export function page(offset: number, lines: readonly string[], eof: boolean, version = 'v1'): RemoteResult<WorkspaceFileText> {
+  return { ok: true, value: { absolutePath: ABSOLUTE_PATH, version, offset, text: lines.join('\n'), lines: lines.length, eof, bytes: 100 } }
+}
+
+/** One failed page read. */
+export function failure(code: string, details: Record<string, unknown> = {}): RemoteResult<WorkspaceFileText> {
+  return { ok: false, error: { code, message: 'boom', details } as unknown as RemoteFailure }
+}
+
+/** The `file` resource's metadata: live, or failed beside the last live value. */
+function meta(changed: boolean, failure: RemoteFailure | undefined, reload: () => void): ResourceSnapshot<WorkspaceFileResource> {
+  const value: WorkspaceFileResource = { absolutePath: ABSOLUTE_PATH, version: 'v1', bytes: 100, changed }
+  return failure === undefined
+    ? { status: 'live', value, failure: undefined, reload }
+    : { status: 'failed', value, failure, reload }
+}
+
+/** Test-local selector hook over a framework-neutral store instance. */
+function hookOf<T>(inst: { subscribe: (fn: () => void) => () => void; getSnapshot: () => T }) {
+  return function useSelector<S>(sel: (s: T) => S): S {
+    return sel(useSyncExternalStore(inst.subscribe, inst.getSnapshot))
+  }
+}
+
+/** Key-echoing translate that also shows its parameters. */
+export function t(key: string, params?: Record<string, unknown>): string {
+  return params === undefined ? key : `${key}(${Object.entries(params).map(([k, v]) => `${k}=${String(v)}`).join(',')})`
+}
+
+/** Flush page reads that resolved since the last render, then React's work. */
+export async function settle(): Promise<void> {
+  await act(async () => {
+    await Promise.resolve()
+    await Promise.resolve()
+  })
+}
+
+/** What one tab record's harness hands a spec. Named so the helper's declaration stays portable. */
+export interface Harness {
+  /** The live store instance both components read. */
+  instance: ReturnType<TextStore['create']>
+  /** The face bound to the scripted read. */
+  face: TextInjected
+  /** The scripted paged read. */
+  read: Mock<ReadWorkspaceFilePage>
+  /** The resource's `reload`. */
+  reload: Mock<() => void>
+  /** The tab record's lifetime. */
+  controller: AbortController
+  /** The scripted `useResource`. */
+  useResource: Mock<() => ResourceSnapshot<WorkspaceFileResource>>
+  /** Composed props for one navigation state. */
+  props: (navigation?: { params?: unknown; revision: number }) => TextPreviewProps
+  /** Script what one offset resolves to from now on. */
+  script(offset: number, result: RemoteResult<WorkspaceFileText>): void
+  /** Script whether the next render's `useResource` reports a pending change. */
+  setChanged(changed: boolean): void
+  /** Script the next render's `useResource` as failed with `failure`, or live again with `undefined`. */
+  setFailure(failure: RemoteFailure | undefined): void
+}
+
+/**
+ * One tab record's harness.
+ * @param script - the page each offset resolves to; an unscripted offset fails `not-found`.
+ * @returns the store, the scripted faces, and a props builder.
+ */
+export function harness(script: Record<number, RemoteResult<WorkspaceFileText>> = {}): Harness {
+  const instance = createTextStore().create()
+  const pages: Record<number, RemoteResult<WorkspaceFileText>> = { ...script }
+  const read = vi.fn<ReadWorkspaceFilePage>((_session, _path, offset) =>
+    Promise.resolve(pages[offset] ?? failure('workspace-file/not-found', { path: PATH })))
+  const face = textFace(read)(SESSION, instance.actions)
+  const reload = vi.fn<() => void>()
+  const current = { changed: false, failure: undefined as RemoteFailure | undefined, snapshot: meta(false, undefined, reload) }
+  const refresh = (): void => { current.snapshot = meta(current.changed, current.failure, reload) }
+  const useResource = vi.fn<() => ResourceSnapshot<WorkspaceFileResource>>(() => current.snapshot)
+  const controller = new AbortController()
+  const tabActions = { openResource: vi.fn(), openTab: vi.fn(), close: vi.fn(), replace: vi.fn() }
+  const props = (navigation: { params?: unknown; revision: number } = { revision: 1 }) => ({
+    useTabInfo: () => ({
+      sidebar: { expanded: true, fullscreen: false },
+      panel: { id: 'pane-1' },
+      tab: {
+        id: TAB_ID, kind: 'text', contentId: ADDRESS, title: 'notes.md', visible: true,
+        navigation: { address: ADDRESS, params: navigation.params, revision: navigation.revision },
+        signal: controller.signal,
+        actions: tabActions,
+      },
+    }),
+    sessionId: SESSION,
+    useResource,
+    useStore: hookOf(instance),
+    actions: instance.actions,
+    loadPage: face.loadPage,
+    reloadPages: face.reloadPages,
+    t,
+  }) as unknown as TextPreviewProps
+  return {
+    instance,
+    face,
+    read,
+    reload,
+    controller,
+    useResource,
+    props,
+    script(offset, result) { pages[offset] = result },
+    setChanged(changed) { current.changed = changed; refresh() },
+    setFailure(failure) { current.failure = failure; refresh() },
+  }
+}
diff --git a/packages/client/ui-sidebar-textpreview/tests/lines.client.spec.ts b/packages/client/ui-sidebar-textpreview/tests/lines.client.spec.ts
new file mode 100644
index 0000000000..40b3822395
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/tests/lines.client.spec.ts
@@ -0,0 +1,43 @@
+/**
+ * The body's page arithmetic: how a page's text and line count become lines,
+ * how the store's page table becomes the pages in file order, and how far they
+ * reach.
+ */
+import { describe, expect, it } from 'vitest'
+import { lastLineLoaded, linesOf, loadedPages } from '../src/client/TextPreview.tsx'
+import type { TextPage } from '../src/client/store.ts'
+
+const held = (text: string, lines: number): TextPage => ({ text, lines })
+
+describe('linesOf', () => {
+  it('splits on newlines, so a trailing one ends an empty last line as the Host counted it', () => {
+    expect(linesOf(held('a\nb', 2))).toEqual(['a', 'b'])
+    expect(linesOf(held('a\n', 2))).toEqual(['a', ''])
+    expect(linesOf(held('a\nb\n', 3))).toEqual(['a', 'b', ''])
+    expect(linesOf(held('a\n\nb', 3))).toEqual(['a', '', 'b'])
+  })
+
+  it('tells a page holding one empty line from a page past the file\'s last line by the count', () => {
+    expect(linesOf(held('', 1))).toEqual([''])
+    expect(linesOf(held('', 0))).toEqual([])
+  })
+})
+
+describe('loadedPages', () => {
+  it('orders the store\'s page table by the line each page starts at', () => {
+    expect(loadedPages({})).toEqual([])
+    expect(loadedPages({ 4: held('d\ne', 2), 1: held('a\nb\nc', 3) })).toEqual([
+      { offset: 1, text: 'a\nb\nc', lines: 3 },
+      { offset: 4, text: 'd\ne', lines: 2 },
+    ])
+  })
+})
+
+describe('lastLineLoaded', () => {
+  it('is 0 before the first page and the last line of the last page after, by the Host\'s count', () => {
+    expect(lastLineLoaded([])).toBe(0)
+    expect(lastLineLoaded(loadedPages({ 4: held('d\ne', 2), 1: held('a\nb\nc', 3) }))).toBe(5)
+    expect(lastLineLoaded(loadedPages({ 1: held('', 1) }))).toBe(1)
+    expect(lastLineLoaded(loadedPages({ 1: held('a', 1), 2: held('', 0) }))).toBe(1)
+  })
+})
diff --git a/packages/client/ui-sidebar-textpreview/tests/rpc.client.spec.ts b/packages/client/ui-sidebar-textpreview/tests/rpc.client.spec.ts
new file mode 100644
index 0000000000..5a26f699e7
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/tests/rpc.client.spec.ts
@@ -0,0 +1,40 @@
+/**
+ * The address-to-read translation: a `dsh-resource://file/session/<id>/<path>`
+ * address names the session the read runs under and the workspace-relative path
+ * it hands the Host; a `dsh-resource://file/absolute/<path>` address is read
+ * through the seat's own session; anything else fails loud.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { createReadPage, hostFileOf } from '../src/client/rpc.ts'
+import type { WorkspaceFilesReadRemote } from '../src/client/rpc.ts'
+import { ADDRESS, FILE, PATH, SESSION, page } from './fixtures.client.ts'
+
+const SEAT = 's-seat' as SessionId
+
+describe('hostFileOf', () => {
+  it('reads the session and the decoded relative path out of a session file address, whatever the seat\'s session', () => {
+    expect(hostFileOf(ADDRESS, SEAT)).toEqual(FILE)
+    expect(hostFileOf('dsh-resource://file/session/s%2F1/work/a%20b%23c.md', SEAT)).toEqual({ sessionId: 's/1', path: 'work/a b#c.md' })
+  })
+
+  it('reads an absolute address through the seat\'s session with the decoded absolute path', () => {
+    expect(hostFileOf('dsh-resource://file/absolute/etc/hosts', SEAT)).toEqual({ sessionId: SEAT, path: '/etc/hosts' })
+    expect(hostFileOf('dsh-resource://file/absolute/C:/w/a%20b.md', SEAT)).toEqual({ sessionId: SEAT, path: 'C:/w/a b.md' })
+  })
+
+  it('throws for an address that is not a file address', () => {
+    for (const address of ['dsh-resource://file/shared/team/notes.md', 'dsh-resource://file/session', 'file:///work/notes.md', 'sidebar://guide']) {
+      expect(() => hostFileOf(address, SEAT)).toThrow('not a file address')
+    }
+  })
+})
+
+describe('createReadPage', () => {
+  it('binds the paged read to the Remote with the offset as the only range', async () => {
+    const read = vi.fn<WorkspaceFilesReadRemote['workspaceFiles']['read']>(() => Promise.resolve(page(4, ['d'], true)))
+    const signal = new AbortController().signal
+    await expect(createReadPage({ workspaceFiles: { read } })(SESSION, PATH, 4, signal)).resolves.toEqual(page(4, ['d'], true))
+    expect(read).toHaveBeenCalledWith(SESSION, PATH, { offset: 4 }, signal)
+  })
+})
diff --git a/packages/client/ui-sidebar-textpreview/tests/store.client.spec.ts b/packages/client/ui-sidebar-textpreview/tests/store.client.spec.ts
new file mode 100644
index 0000000000..a5d7b2b054
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/tests/store.client.spec.ts
@@ -0,0 +1,84 @@
+/**
+ * The store's write set: pages keyed by their first line, invalidated by a newer
+ * file version; a view that survives a reset; one bucket per tab, dropped on
+ * `forget` so a closed tab leaves nothing behind.
+ */
+import { describe, expect, it } from 'vitest'
+import type { RemoteFailure } from '@deepseek-ai/dsh-api-remotes/client'
+import { createTextStore, fresh } from '../src/client/store.ts'
+import { page } from './fixtures.client.ts'
+import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+
+const TAB_1 = 'tab-1' as TabId
+const TAB_2 = 'tab-2' as TabId
+const TAB_9 = 'tab-9' as TabId
+
+function pageValue(offset: number, lines: readonly string[], eof: boolean, version = 'v1') {
+  const result = page(offset, lines, eof, version)
+  if (!result.ok) throw new Error('fixture')
+  return result.value
+}
+
+describe('text store', () => {
+  it('starts empty and mints a bucket on the first write', () => {
+    const instance = createTextStore().create()
+    expect(instance.getSnapshot().byTab).toEqual({})
+    instance.actions.loading(TAB_1)
+    expect(instance.getSnapshot().byTab[TAB_1]).toEqual({ ...fresh(), loading: true })
+  })
+
+  it('keeps pages by their first line and reports the end of the file', () => {
+    const instance = createTextStore().create()
+    instance.actions.loading(TAB_1)
+    instance.actions.page(TAB_1, pageValue(1, ['a', 'b'], false))
+    instance.actions.page(TAB_1, pageValue(3, ['c'], true))
+    const state = instance.getSnapshot().byTab[TAB_1]
+    expect(state?.pages).toEqual({ 1: { text: 'a\nb', lines: 2 }, 3: { text: 'c', lines: 1 } })
+    expect(state?.version).toBe('v1')
+    expect(state?.eof).toBe(true)
+    expect(state?.loading).toBe(false)
+  })
+
+  it('drops the pages of an older version when a newer page arrives', () => {
+    const instance = createTextStore().create()
+    instance.actions.page(TAB_1, pageValue(1, ['a'], false))
+    instance.actions.page(TAB_1, pageValue(2, ['B'], true, 'v2'))
+    expect(instance.getSnapshot().byTab[TAB_1]?.pages).toEqual({ 2: { text: 'B', lines: 1 } })
+    expect(instance.getSnapshot().byTab[TAB_1]?.version).toBe('v2')
+  })
+
+  it('records a failure beside the pages already held, and the next page clears it', () => {
+    const instance = createTextStore().create()
+    instance.actions.page(TAB_1, pageValue(1, ['a'], false))
+    const failure = { code: 'workspace-file/too-large', message: 'x', details: {} } as unknown as RemoteFailure
+    instance.actions.failed(TAB_1, failure)
+    expect(instance.getSnapshot().byTab[TAB_1]?.failure).toBe(failure)
+    expect(instance.getSnapshot().byTab[TAB_1]?.pages).toEqual({ 1: { text: 'a', lines: 1 } })
+    instance.actions.page(TAB_1, pageValue(2, ['b'], true))
+    expect(instance.getSnapshot().byTab[TAB_1]?.failure).toBeUndefined()
+  })
+
+  it('resets the pages but keeps the view', () => {
+    const instance = createTextStore().create()
+    instance.actions.page(TAB_1, pageValue(1, ['a'], true))
+    instance.actions.scrolled(TAB_1, 120)
+    instance.actions.toggledWrap(TAB_1)
+    instance.actions.navigated(TAB_1, 3)
+    instance.actions.reset(TAB_1)
+    expect(instance.getSnapshot().byTab[TAB_1]).toEqual({
+      ...fresh(), scrollTop: 120, wrap: false, revision: 3,
+    })
+  })
+
+  it('forgets one tab and keeps the rest', () => {
+    const instance = createTextStore().create()
+    instance.actions.toggledWrap(TAB_1)
+    instance.actions.toggledWrap(TAB_2)
+    instance.actions.forget(TAB_1)
+    expect(Object.keys(instance.getSnapshot().byTab)).toEqual([TAB_2])
+    // Forgetting an unknown tab is a no-op, not a fault: the abort listener may
+    // fire for a tab that never wrote anything.
+    instance.actions.forget(TAB_9)
+    expect(Object.keys(instance.getSnapshot().byTab)).toEqual([TAB_2])
+  })
+})
diff --git a/packages/client/ui-sidebar-textpreview/tests/text-preview.client.spec.tsx b/packages/client/ui-sidebar-textpreview/tests/text-preview.client.spec.tsx
new file mode 100644
index 0000000000..464fe67303
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/tests/text-preview.client.spec.tsx
@@ -0,0 +1,327 @@
+// @vitest-environment jsdom
+/**
+ * What the body draws from its pages and the file's metadata, and what it does
+ * with a navigation: load until the asked line is held, jump to it once, then
+ * keep the reader's place.
+ *
+ * jsdom lays nothing out, so two geometry facts are supplied here: a line's
+ * offset is its number times one line height, and `scrollTop` holds what it is
+ * set to. Both are the browser's job; the specs assert the body's arithmetic
+ * over them.
+ */
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render } from '@testing-library/react'
+import { RemoteError } from '@deepseek-ai/dsh-client-test-runtime'
+import { TextPreview } from '../src/client/TextPreview.tsx'
+import { ABSOLUTE_PATH, ADDRESS, PATH, SESSION, TAB_ID, failure, harness, page, settle } from './fixtures.client.ts'
+
+const LINE_HEIGHT = 20
+
+const originals = {
+  offsetTop: Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'offsetTop'),
+  scrollTop: Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'scrollTop'),
+}
+
+beforeAll(() => {
+  Object.defineProperty(HTMLElement.prototype, 'offsetTop', {
+    configurable: true,
+    get(this: HTMLElement) {
+      const line = this.getAttribute('data-textpreview-line')
+      return line === null ? 0 : (Number(line) - 1) * LINE_HEIGHT
+    },
+  })
+  Object.defineProperty(HTMLElement.prototype, 'scrollTop', {
+    configurable: true,
+    get(this: HTMLElement & { __scrollTop?: number }) { return this.__scrollTop ?? 0 },
+    set(this: HTMLElement & { __scrollTop?: number }, value: number) { this.__scrollTop = value },
+  })
+})
+
+afterAll(() => {
+  for (const [name, descriptor] of Object.entries(originals)) {
+    if (descriptor === undefined) Reflect.deleteProperty(HTMLElement.prototype, name)
+    else Object.defineProperty(HTMLElement.prototype, name, descriptor)
+  }
+})
+
+afterEach(cleanup)
+
+function body(container: HTMLElement): HTMLElement {
+  const element = container.querySelector<HTMLElement>('[data-textpreview-body]')
+  if (element === null) throw new Error('expected the file body')
+  return element
+}
+
+function lines(container: HTMLElement): string[] {
+  return Array.from(container.querySelectorAll('[data-textpreview-line]'), row => row.textContent ?? '')
+}
+
+function target(container: HTMLElement): string | null {
+  return container.querySelector('[data-textpreview-target]')?.getAttribute('data-textpreview-target') ?? null
+}
+
+function click(container: HTMLElement, selector: string): void {
+  const button = container.querySelector<HTMLButtonElement>(selector)
+  if (button === null) throw new Error(`expected ${selector}`)
+  fireEvent.click(button)
+}
+
+describe('TextPreview — pages', () => {
+  it.each([ABSOLUTE_PATH, 'C:\\work\\project\\notes.md', '\\\\host\\share\\notes.md'])(
+    'shows the Host path %s in the header and tooltip even when text cannot be read',
+    async (absolutePath) => {
+      const h = harness({ 1: failure('workspace-file/not-text', { path: PATH }) })
+      h.useResource.mockReturnValue({
+        status: 'live', value: { absolutePath, version: 'v1', changed: false }, failure: undefined, reload: h.reload,
+      })
+      const view = render(<TextPreview {...h.props()} />)
+      await settle()
+      const path = view.container.querySelector('[data-textpreview-path]')
+      expect(path?.textContent).toBe(absolutePath)
+      expect(path?.getAttribute('title')).toBe(absolutePath)
+      expect(h.read).toHaveBeenCalledWith(SESSION, PATH, 1, h.controller.signal)
+    },
+  )
+
+  it('shows the requested path until Host metadata supplies its absolute path', async () => {
+    const h = harness({ 1: page(1, ['one'], true) })
+    const metadata = h.useResource()
+    h.useResource.mockReturnValue({ status: 'loading', value: undefined, failure: undefined, reload: h.reload })
+    const view = render(<TextPreview {...h.props()} />)
+    await settle()
+    expect(view.container.querySelector('[data-textpreview-path]')?.textContent).toBe(PATH)
+    h.useResource.mockReturnValue(metadata)
+    view.rerender(<TextPreview {...h.props()} />)
+    expect(view.container.querySelector('[data-textpreview-path]')?.textContent).toBe(ABSOLUTE_PATH)
+    expect(view.container.querySelector('[data-textpreview-path]')?.getAttribute('title')).toBe(ABSOLUTE_PATH)
+  })
+
+  it('reads the first page on first mount and draws its lines, offering the next', async () => {
+    const h = harness({ 1: page(1, ['one', 'two', 'three'], false) })
+    const view = render(<TextPreview {...h.props()} />)
+    // The read is in flight from the mount effect on: the body is up with no
+    // lines yet, and its next-page control reports the progress.
+    const pending = view.container.querySelector<HTMLButtonElement>('[data-textpreview-more]')
+    expect(pending?.disabled).toBe(true)
+    expect(pending?.textContent).toBe('loading')
+    expect(lines(view.container)).toEqual([])
+    await settle()
+    expect(h.read).toHaveBeenCalledTimes(1)
+    expect(h.read).toHaveBeenCalledWith(SESSION, PATH, 1, h.controller.signal)
+    expect(lines(view.container)).toEqual(['one\n', 'two\n', 'three\n'])
+    expect(view.container.querySelector('[data-textpreview-url]')?.getAttribute('data-textpreview-url')).toBe(ADDRESS)
+    expect(view.container.textContent).toContain(PATH)
+    expect(view.container.querySelector('[data-textpreview-more]')).not.toBeNull()
+    expect(view.container.querySelector('[data-textpreview-changed]')).toBeNull()
+  })
+
+  it('reads nothing on a remount while the store holds the pages', async () => {
+    const h = harness({ 1: page(1, ['one'], true) })
+    const first = render(<TextPreview {...h.props()} />)
+    await settle()
+    first.unmount()
+    const second = render(<TextPreview {...h.props()} />)
+    await settle()
+    expect(h.read).toHaveBeenCalledTimes(1)
+    expect(lines(second.container)).toEqual(['one\n'])
+  })
+
+  it('loads the next page where the loaded text ends, until the file ends', async () => {
+    const h = harness({ 1: page(1, ['a', 'b', 'c'], false), 4: page(4, ['d', 'e'], true) })
+    const view = render(<TextPreview {...h.props()} />)
+    await settle()
+    click(view.container, '[data-textpreview-more]')
+    await settle()
+    expect(h.read).toHaveBeenLastCalledWith(SESSION, PATH, 4, h.controller.signal)
+    expect(lines(view.container)).toEqual(['a\n', 'b\n', 'c\n', 'd\n', 'e\n'])
+    expect(view.container.querySelectorAll('[data-textpreview-page]').length).toBe(2)
+    expect(view.container.querySelector('[data-textpreview-more]')).toBeNull()
+  })
+
+  it('says why a page failed and retries the same page', async () => {
+    const h = harness({ 1: failure('workspace-file/not-text', { path: PATH }) })
+    const view = render(<TextPreview {...h.props()} />)
+    await settle()
+    expect(view.container.querySelector('[data-textpreview-failed]')?.getAttribute('data-textpreview-failed')).toBe('workspace-file/not-text')
+    expect(view.container.textContent).toContain('error.notText')
+    expect(view.container.querySelector('[data-textpreview-more]')).toBeNull()
+    h.script(1, page(1, ['one'], true))
+    click(view.container, '[data-textpreview-retry]')
+    await settle()
+    expect(h.read).toHaveBeenLastCalledWith(SESSION, PATH, 1, h.controller.signal)
+    expect(lines(view.container)).toEqual(['one\n'])
+    expect(view.container.querySelector('[data-textpreview-failed]')).toBeNull()
+  })
+
+  it('announces a change and, on request, re-reads the pages keeping the reader\'s place', async () => {
+    const h = harness({ 1: page(1, ['a', 'b'], true) })
+    const view = render(<TextPreview {...h.props()} />)
+    await settle()
+    fireEvent.scroll(body(view.container), { target: { scrollTop: 50 } })
+    h.setChanged(true)
+    view.rerender(<TextPreview {...h.props()} />)
+    expect(view.container.querySelector('[data-textpreview-changed]')?.textContent).toContain('changed')
+    expect(lines(view.container)).toEqual(['a\n', 'b\n'])
+    h.script(1, page(1, ['A', 'B', 'C'], true, 'v2'))
+    click(view.container, '[data-textpreview-reload-now]')
+    expect(h.reload).toHaveBeenCalledTimes(1)
+    await settle()
+    expect(h.read).toHaveBeenLastCalledWith(SESSION, PATH, 1, h.controller.signal)
+    expect(lines(view.container)).toEqual(['A\n', 'B\n', 'C\n'])
+    expect(body(view.container).scrollTop).toBe(50)
+  })
+})
+
+describe('TextPreview — the file\'s metadata', () => {
+  it('announces a failed metadata frame over the pages already loaded, ahead of a pending change, until a reload stats it live again', async () => {
+    const h = harness({ 1: page(1, ['a', 'b'], true) })
+    const view = render(<TextPreview {...h.props()} />)
+    await settle()
+    h.setChanged(true)
+    h.setFailure(new RemoteError('workspace-file/not-found', 'gone', { path: PATH }))
+    view.rerender(<TextPreview {...h.props()} />)
+    const bar = view.container.querySelector('[data-textpreview-meta-failed]')
+    expect(bar?.getAttribute('data-textpreview-meta-failed')).toBe('workspace-file/not-found')
+    expect(bar?.textContent).toContain('error.notFound')
+    expect(view.container.querySelector('[data-textpreview-changed]')).toBeNull()
+    expect(lines(view.container)).toEqual(['a\n', 'b\n'])
+    // The bar's reload is the same gesture: stat again through the resource and re-read the pages.
+    h.script(1, page(1, ['A'], true, 'v2'))
+    click(view.container, '[data-textpreview-reload-now]')
+    expect(h.reload).toHaveBeenCalledTimes(1)
+    await settle()
+    expect(lines(view.container)).toEqual(['A\n'])
+    // The stat succeeds: the next frame is live and the bar is gone.
+    h.setChanged(false)
+    h.setFailure(undefined)
+    view.rerender(<TextPreview {...h.props()} />)
+    expect(view.container.querySelector('[data-textpreview-meta-failed]')).toBeNull()
+    expect(view.container.querySelector('[data-textpreview-changed]')).toBeNull()
+  })
+
+  it('draws a page holding one empty line as one line, and nothing for a page past the end', async () => {
+    const h = harness({ 1: page(1, [''], false), 2: page(2, [], true) })
+    const view = render(<TextPreview {...h.props()} />)
+    await settle()
+    expect(lines(view.container)).toEqual(['\n'])
+    click(view.container, '[data-textpreview-more]')
+    await settle()
+    expect(h.read).toHaveBeenLastCalledWith(SESSION, PATH, 2, h.controller.signal)
+    expect(lines(view.container)).toEqual(['\n'])
+    expect(view.container.querySelector('[data-textpreview-more]')).toBeNull()
+  })
+})
+
+describe('TextPreview — navigation and view', () => {
+  it('loads until the navigated line is held, then jumps to it once and marks it', async () => {
+    const h = harness({ 1: page(1, ['a', 'b', 'c'], false), 4: page(4, ['d', 'e', 'f'], true) })
+    const view = render(<TextPreview {...h.props({ params: { line: 5 }, revision: 1 })} />)
+    await settle()
+    // The first page does not reach line 5, so the body asks for the next on its own.
+    await settle()
+    expect(h.read).toHaveBeenCalledTimes(2)
+    expect(h.read).toHaveBeenLastCalledWith(SESSION, PATH, 4, h.controller.signal)
+    expect(body(view.container).scrollTop).toBe(4 * LINE_HEIGHT)
+    expect(target(view.container)).toBe('5')
+    expect(h.instance.getSnapshot().byTab[TAB_ID]?.revision).toBe(1)
+    expect(h.instance.getSnapshot().byTab[TAB_ID]?.scrollTop).toBe(4 * LINE_HEIGHT)
+  })
+
+  it('comes back where the reader was on a remount, instead of jumping again', async () => {
+    const h = harness({ 1: page(1, ['a', 'b', 'c'], true) })
+    const first = render(<TextPreview {...h.props({ params: { line: 3 }, revision: 1 })} />)
+    await settle()
+    expect(body(first.container).scrollTop).toBe(2 * LINE_HEIGHT)
+    fireEvent.scroll(body(first.container), { target: { scrollTop: 300 } })
+    first.unmount()
+    const second = render(<TextPreview {...h.props({ params: { line: 3 }, revision: 1 })} />)
+    await settle()
+    expect(body(second.container).scrollTop).toBe(300)
+  })
+
+  it('jumps again for a new navigation to the same tab', async () => {
+    const h = harness({ 1: page(1, ['a', 'b', 'c'], true) })
+    const view = render(<TextPreview {...h.props({ params: { line: 3 }, revision: 1 })} />)
+    await settle()
+    fireEvent.scroll(body(view.container), { target: { scrollTop: 300 } })
+    view.rerender(<TextPreview {...h.props({ params: { line: 2 }, revision: 2 })} />)
+    expect(body(view.container).scrollTop).toBe(1 * LINE_HEIGHT)
+    expect(target(view.container)).toBe('2')
+    expect(h.instance.getSnapshot().byTab[TAB_ID]?.revision).toBe(2)
+  })
+
+  it('stops at the end of the file for a line past it, and answers a navigation without a line', async () => {
+    const h = harness({ 1: page(1, ['a', 'b'], true) })
+    const view = render(<TextPreview {...h.props({ params: { line: 99 }, revision: 1 })} />)
+    await settle()
+    expect(h.read).toHaveBeenCalledTimes(1)
+    expect(target(view.container)).toBeNull()
+    expect(body(view.container).scrollTop).toBe(0)
+    expect(h.instance.getSnapshot().byTab[TAB_ID]?.revision).toBe(1)
+    view.rerender(<TextPreview {...h.props({ params: {}, revision: 2 })} />)
+    expect(target(view.container)).toBeNull()
+    expect(h.instance.getSnapshot().byTab[TAB_ID]?.revision).toBe(2)
+  })
+
+  it('wraps by default and stops when the shared store says so', async () => {
+    const h = harness({ 1: page(1, ['a'], true) })
+    const view = render(<TextPreview {...h.props()} />)
+    await settle()
+    expect(body(view.container).hasAttribute('data-textpreview-wrap')).toBe(true)
+    act(() => { h.instance.actions.toggledWrap(TAB_ID) })
+    expect(body(view.container).hasAttribute('data-textpreview-wrap')).toBe(false)
+  })
+})
+
+describe('TextPreview — header controls', () => {
+  it('toggles wrap off from the header, reporting the pressed state', async () => {
+    const h = harness({ 1: page(1, ['a'], true) })
+    const view = render(<TextPreview {...h.props()} />)
+    await settle()
+    const wrap = view.container.querySelector<HTMLButtonElement>('[data-textpreview-tool="wrap"]')
+    if (wrap === null) throw new Error('expected the wrap control')
+    expect(wrap.getAttribute('aria-pressed')).toBe('true')
+    fireEvent.click(wrap)
+    expect(h.instance.getSnapshot().byTab[TAB_ID]?.wrap).toBe(false)
+    expect(wrap.getAttribute('aria-pressed')).toBe('false')
+    expect(body(view.container).hasAttribute('data-textpreview-wrap')).toBe(false)
+  })
+
+  it('reloads from the header through the resource and the face, without a change announced', async () => {
+    const h = harness({ 1: page(1, ['one'], true) })
+    const view = render(<TextPreview {...h.props()} />)
+    await settle()
+    expect(h.useResource).toHaveBeenCalledWith(ADDRESS)
+    expect(view.container.querySelector('[data-textpreview-changed]')).toBeNull()
+    h.script(1, page(1, ['uno'], true, 'v2'))
+    click(view.container, '[data-textpreview-tool="reload"]')
+    expect(h.reload).toHaveBeenCalledTimes(1)
+    await settle()
+    expect(h.read).toHaveBeenLastCalledWith(SESSION, PATH, 1, h.controller.signal)
+    expect(lines(view.container)).toEqual(['uno\n'])
+  })
+
+  it('forgets at once when mounted for a record that has already ended', async () => {
+    const h = harness({ 1: page(1, ['a'], true) })
+    h.controller.abort()
+    render(<TextPreview {...h.props()} />)
+    await settle()
+    expect(h.instance.getSnapshot().byTab[TAB_ID]).toBeUndefined()
+  })
+
+  it('forgets its state when the record ends, even with the body unmounted, through one listener however often it mounted', async () => {
+    const h = harness({ 1: page(1, ['a'], true) })
+    const armed = vi.spyOn(h.controller.signal, 'addEventListener')
+    const first = render(<TextPreview {...h.props()} />)
+    await settle()
+    expect(h.instance.getSnapshot().byTab[TAB_ID]).toBeDefined()
+    // Switched away and back: the store outlives the body, so nothing re-arms.
+    first.unmount()
+    const second = render(<TextPreview {...h.props()} />)
+    await settle()
+    second.unmount()
+    expect(armed.mock.calls.filter(([type]) => type === 'abort')).toHaveLength(1)
+    h.controller.abort()
+    expect(h.instance.getSnapshot().byTab[TAB_ID]).toBeUndefined()
+  })
+})
diff --git a/packages/client/ui-sidebar-textpreview/tsconfig.json b/packages/client/ui-sidebar-textpreview/tsconfig.json
new file mode 100644
index 0000000000..c576ab9943
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/tsconfig.json
@@ -0,0 +1,54 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../api/remotes/tsconfig.client.json"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../locale"
+    },
+    {
+      "path": "../resources"
+    },
+    {
+      "path": "../store"
+    },
+    {
+      "path": "../ui-dockkit"
+    },
+    {
+      "path": "../ui-primitives"
+    },
+    {
+      "path": "../ui-renderer"
+    },
+    {
+      "path": "../ui-session"
+    },
+    {
+      "path": "../ui-sidebar-right"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../../api/workspace-files/tsconfig.client.json"
+    },
+    {
+      "path": "../../util/workspace-path"
+    }
+  ]
+}
diff --git a/packages/client/ui-sidebar-textpreview/tsdown.config.ts b/packages/client/ui-sidebar-textpreview/tsdown.config.ts
new file mode 100644
index 0000000000..01c1b9a440
--- /dev/null
+++ b/packages/client/ui-sidebar-textpreview/tsdown.config.ts
@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-ui-sidebar-textpreview', ['lib/types/index.js'])
diff --git a/packages/client/ui-sidebar/tests/pointer-scrollbars.client.spec.tsx b/packages/client/ui-sidebar/tests/pointer-scrollbars.client.spec.tsx
index 9adc7b51df..ed5b687e73 100644
--- a/packages/client/ui-sidebar/tests/pointer-scrollbars.client.spec.tsx
+++ b/packages/client/ui-sidebar/tests/pointer-scrollbars.client.spec.tsx
@@ -5,12 +5,16 @@
  * asserted in scrollbar-quiet-styles.spec.ts (node environment — a jsdom spec
  * has no file: module URL to read the sheet through).
  */
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
 import type { SidebarRootComponentProps, SidebarSectionOwnerProps } from '../src/client/contract/slots.ts'
 import { SidebarRoot } from '../src/client/SidebarRoot.tsx'
 import { en } from '../src/client/locales.ts'
 
+// Every fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 /** Pinned column box; the shell compares pointer coordinates against it. */
 const COLUMN_WIDTH = 280
 const COLUMN_HEIGHT = 600
@@ -35,7 +39,8 @@ function mountColumn(): { column: HTMLElement; quiet: () => boolean } {
   const view = render(
     <SidebarRoot
       collapsed={false} width={300}
-      useSessions={neverHook} useSessionPendingInteraction={useSessionPendingInteraction} useWorkspaces={neverHook}
+      useSessions={neverHook} useSessionPendingInteraction={useSessionPendingInteraction}
+      useResource={useResource} useWorkspaces={neverHook}
       startSession={vi.fn()} toggleSidebar={vi.fn()} t={t}
       renderSlot={((_key: string, owner: SidebarSectionOwnerProps) =>
         <div data-testid="region" data-wide={owner.wide} />) as SidebarRootComponentProps['renderSlot']}
diff --git a/packages/client/ui-sidebar/tests/sidebar-root.client.spec.tsx b/packages/client/ui-sidebar/tests/sidebar-root.client.spec.tsx
index 0f5edce0de..9973a1958b 100644
--- a/packages/client/ui-sidebar/tests/sidebar-root.client.spec.tsx
+++ b/packages/client/ui-sidebar/tests/sidebar-root.client.spec.tsx
@@ -1,4 +1,5 @@
 // @vitest-environment jsdom
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import type { ReactNode } from 'react'
@@ -10,6 +11,9 @@ import { SidebarRoot } from '../src/client/SidebarRoot.tsx'
 import { en } from '../src/client/locales.ts'
 import { en as commonEn } from '@deepseek-ai/dsh-client-locale/src/locales/en.ts'
 
+// Every fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 // English-dictionary translate stub: the shell renders the same copy the
 // assertions below query by accessible name.
 const t: SidebarRootComponentProps['t'] = key =>
@@ -40,7 +44,8 @@ function mountShell({ collapsed = false, width = 300 }: { collapsed?: boolean; w
   const root = () => (
     <SidebarRoot
       collapsed={current.collapsed} width={current.width}
-      useSessions={neverHook} useSessionPendingInteraction={useSessionPendingInteraction} useWorkspaces={neverHook}
+      useSessions={neverHook} useSessionPendingInteraction={useSessionPendingInteraction}
+      useResource={useResource} useWorkspaces={neverHook}
       startSession={startSession} toggleSidebar={toggleSidebar} t={t}
       renderSlot={((
         key: string,
@@ -104,7 +109,8 @@ describe('SidebarRoot shell', () => {
     vi.stubEnv('DSH_CLIENT_VERSION', '1.2.3-rc.4')
     const { container } = render(<SidebarRoot
       collapsed={false} width={300}
-      useSessions={neverHook} useSessionPendingInteraction={useSessionPendingInteraction} useWorkspaces={neverHook}
+      useSessions={neverHook} useSessionPendingInteraction={useSessionPendingInteraction}
+      useResource={useResource} useWorkspaces={neverHook}
       startSession={vi.fn()} toggleSidebar={vi.fn()} t={t}
       renderSlot={((_key: string, _owner: unknown, options?: { fallback?: ReactNode }) =>
         options?.fallback ?? null) as SidebarRootComponentProps['renderSlot']}
@@ -122,7 +128,8 @@ describe('SidebarRoot shell', () => {
     for (const [name, value] of Object.entries(environment)) vi.stubEnv(name, value)
     render(<SidebarRoot
       collapsed={false} width={300}
-      useSessions={neverHook} useSessionPendingInteraction={useSessionPendingInteraction} useWorkspaces={neverHook}
+      useSessions={neverHook} useSessionPendingInteraction={useSessionPendingInteraction}
+      useResource={useResource} useWorkspaces={neverHook}
       startSession={vi.fn()} toggleSidebar={vi.fn()} t={t}
       renderSlot={((_key: string, _owner: unknown, options?: { fallback?: ReactNode }) =>
         options?.fallback ?? null) as SidebarRootComponentProps['renderSlot']}
@@ -135,7 +142,8 @@ describe('SidebarRoot shell', () => {
   it('retains the local-build fallback without complete build metadata', () => {
     render(<SidebarRoot
       collapsed={false} width={300}
-      useSessions={neverHook} useSessionPendingInteraction={useSessionPendingInteraction} useWorkspaces={neverHook}
+      useSessions={neverHook} useSessionPendingInteraction={useSessionPendingInteraction}
+      useResource={useResource} useWorkspaces={neverHook}
       startSession={vi.fn()} toggleSidebar={vi.fn()} t={t}
       renderSlot={((_key: string, _owner: unknown, options?: { fallback?: ReactNode }) =>
         options?.fallback ?? null) as SidebarRootComponentProps['renderSlot']}
diff --git a/packages/client/ui-slots/src/index.ts b/packages/client/ui-slots/src/index.ts
index 56a8234ce1..834b2a2b85 100644
--- a/packages/client/ui-slots/src/index.ts
+++ b/packages/client/ui-slots/src/index.ts
@@ -35,6 +35,14 @@ export interface SlotMap {}
  */
 export interface LocaleNamespaceMap {}
 
+/**
+ * Resource protocol (URL scheme) → the value its provider streams. Declared
+ * empty here, the zero-dependency merge point; each protocol owner merges its
+ * own member (`file`, later `chat`), and `useResource<P>(address)` narrows its
+ * value by `P`. The resource service itself lives in `dsh-client-resources`.
+ */
+export interface ResourceProtocolMap {}
+
 /**
  * Translate a dictionary key with optional `{name}` template params.
  * `K` narrows the accepted keys to the owning namespace's dictionary union
diff --git a/packages/client/ui-theme/tests/appearance-row.client.spec.tsx b/packages/client/ui-theme/tests/appearance-row.client.spec.tsx
index c42d6aa3b6..4e6b61616e 100644
--- a/packages/client/ui-theme/tests/appearance-row.client.spec.tsx
+++ b/packages/client/ui-theme/tests/appearance-row.client.spec.tsx
@@ -1,4 +1,5 @@
 // @vitest-environment jsdom
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 import type { SessionListState } from '@deepseek-ai/dsh-api-session-controller/client'
@@ -10,6 +11,9 @@ import type { AppearanceRowComponentProps } from '../src/client/AppearanceRow.ts
 import { createAppearanceRowStore } from '../src/client/settings-store.ts'
 import type { ThemePreference } from '../src/client/index.ts'
 
+// Every fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 afterEach(cleanup)
 
 const COPY: Record<string, string> = {
@@ -43,6 +47,7 @@ function mount(preference: ThemePreference = 'system') {
   const props: AppearanceRowComponentProps = {
     useSessions: emptySessions(),
     useSessionPendingInteraction,
+    useResource,
     useWorkspaces: emptyWorkspaces(),
     useStore: bindSnapshotSelector(store),
     actions: store.actions,
diff --git a/packages/client/ui-theme/tests/font-size-row.client.spec.tsx b/packages/client/ui-theme/tests/font-size-row.client.spec.tsx
index 314576d572..3c4601e1f8 100644
--- a/packages/client/ui-theme/tests/font-size-row.client.spec.tsx
+++ b/packages/client/ui-theme/tests/font-size-row.client.spec.tsx
@@ -1,6 +1,7 @@
 // @vitest-environment jsdom
 /** FontSizeRow behavior: value display, arrow clicks drive setFontSize,
  * bound-value arrows disable, display follows the store mirror. */
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 import type { SessionListState } from '@deepseek-ai/dsh-api-session-controller/client'
@@ -11,6 +12,9 @@ import { FontSizeRow } from '../src/client/FontSizeRow.tsx'
 import type { FontSizeRowComponentProps } from '../src/client/FontSizeRow.tsx'
 import { createFontSizeRowStore } from '../src/client/settings-store.ts'
 
+// Every fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 afterEach(cleanup)
 
 const COPY: Record<string, string> = {
@@ -45,6 +49,7 @@ function mount(fontSize = 14) {
   const props: FontSizeRowComponentProps = {
     useSessions: emptySessions(),
     useSessionPendingInteraction,
+    useResource,
     useWorkspaces: emptyWorkspaces(),
     useStore: bindSnapshotSelector(store),
     actions: store.actions,
diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml
index 09a763f5b8..4bbf0f2d15 100644
--- a/packages/client/ui-tool/README.i18n.yaml
+++ b/packages/client/ui-tool/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-tool/README.md
-README.md: e0b49a3b582f5f1e6e9aa19e0b026dedb9ba2a18
-README.zh.md: 032f048f2501923c4c9f010b76afe27d98fe7889
+README.md: b8dd2a5e3c6743e496d585a2de238714f00e9f6b
+README.zh.md: 49e82c9fa70953d73171d466f36995ff2870c6b2
diff --git a/packages/client/ui-tool/README.md b/packages/client/ui-tool/README.md
index e0b49a3b58..b8dd2a5e3c 100644
--- a/packages/client/ui-tool/README.md
+++ b/packages/client/ui-tool/README.md
@@ -57,12 +57,12 @@ The package realizes one dispatch rule: atomic Tool views are keyed by wire Tool
 
 ### Rendering contract
 
-`ToolCallTree` receives one root `ToolCallBlock` that already contains recursive `subCalls`, selection state, the session `cwd`, and Host callbacks for opening files and inspecting calls. It recursively walks the standard call blocks and sends the root and children at every depth through the same atomic dispatch path, without subscribing to a separate parent-to-children map. Each root and child wrapper preserves the `data-chat-anchor-key="call:<id>"` and `data-chat-call-id` DOM contract used for paging and selection.
+`ToolCallTree` receives one root `ToolCallBlock` that already contains recursive `subCalls`, the session `cwd`, and the owner's callbacks for opening files and inspecting calls. It recursively walks the standard call blocks and sends the root and children at every depth through the same atomic dispatch path, without subscribing to a separate parent-to-children map. Each root and child wrapper preserves the `data-chat-anchor-key="call:<id>"` and `data-chat-call-id` DOM contract used for paging and selection.
 
-### Details and cards
+### Cards
 
 
-The package fills `conversation.details.tool` with `ToolDetails`. Row and Details renderers share one pure card model for each terminal, read, diff, search, and web card; the image card is row-only because its gallery renders through the tool-owned `tool.call.images` slot the details panel does not declare. These models validate raw call arguments, result content, failure state, persisted metadata, and Session path facts. Diff, read, search, and web models also reject Code Dispatch children; terminal eligibility does not depend on `parentCallId`. Unsupported or malformed inputs use flattened Tool result text. Card-specific limits and fallback rules for the terminal, diff, read, search, and web cards remain in [the ui-primitives README](../ui-primitives/README.md); the image card's model in this package carries its own fallback rules.
+Every card is read in place in the call tree; there is no second, full-height presentation of a selected call. Row renderers share one pure card model for each terminal, read, diff, search, and web card, and the image card's gallery renders through the tool-owned `tool.call.images` slot. These models validate raw call arguments, result content, failure state, persisted metadata, Code Dispatch `parentCallId`, and Session path facts. Unsupported or malformed inputs use flattened Tool result text. A file-path summary opens the file through the owner's `openFile`, which the chat view routes to the right Sidebar's text preview; `inspect` opens the trajectory view. Card-specific limits and fallback rules for the terminal, diff, read, search, and web cards remain in [the ui-primitives README](../ui-primitives/README.md); the image card's model in this package carries its own fallback rules.
 
 The terminal model uses `hasSpillNotice` from the browser-safe `@deepseek-ai/dsh-spill-policy/notice` entry, not an independent UI pattern. The [spill-policy README](../../spill/spill-policy/README.md#shared-notice-ownership) owns notice formatting and recognition. This check conservatively selects generic output; matching text cannot authenticate its source, and replay leaves recorded result bytes untouched.
 </details>
diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md
index 032f048f25..49e82c9fa7 100644
--- a/packages/client/ui-tool/README.zh.md
+++ b/packages/client/ui-tool/README.zh.md
@@ -57,12 +57,12 @@ owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`
 
 ### 渲染约定
 
-`ToolCallTree` 接收一个已经包含递归 `subCalls` 的 root `ToolCallBlock`、selection 状态、会话 `cwd`，以及用于打开文件和检查调用的 Host 回调。它递归遍历标准调用块，让 root 与任意深度的 child 经过同一条原子分发路径，不订阅独立的 parent-to-children map。每个 root 和 child 包装层都保留 `data-chat-anchor-key="call:<id>"` 与 `data-chat-call-id` DOM 约定，供分页和 selection 使用。
+`ToolCallTree` 接收一个已经包含递归 `subCalls` 的 root `ToolCallBlock`、会话 `cwd`，以及属主用于打开文件和检查调用的回调。它递归遍历标准调用块，让 root 与任意深度的 child 经过同一条原子分发路径，不订阅独立的 parent-to-children map。每个 root 和 child 包装层都保留 `data-chat-anchor-key="call:<id>"` 与 `data-chat-call-id` DOM 约定，供分页和 selection 使用。
 
-### 详情与卡片
+### 卡片
 
 
-本包通过 `ToolDetails` 填充 `conversation.details.tool`。行 renderer 与 Details renderer 分别为 terminal、read、diff、search 和 web 卡片复用同一个纯 card model；image 卡片仅属于行，因为其图库经由工具自有 `tool.call.images` 槽位渲染，而 details 面板不声明该槽位。这些 model 校验原始调用参数、结果内容、失败状态、持久 metadata 与 Session 路径事实。diff、read、search 和 web model 还会拒绝 Code Dispatch 子调用；terminal 适用性不依赖 `parentCallId`。不受支持或格式错误的输入使用压平的工具结果文本。terminal、diff、read、search 与 web 卡片的上限与 fallback 规则仍由 [ui-primitives README](../ui-primitives/README.zh.md) 负责；image 卡片的 fallback 规则由本包内的 card model 自行承载。
+每张卡片都在调用树里就地阅读；不存在选中调用的第二个全高展示面。行 renderer 为 terminal、read、diff、search 和 web 卡片各复用同一个纯 card model，image 卡片的图库经由工具自有 `tool.call.images` 槽位渲染。这些 model 校验原始调用参数、结果内容、失败状态、持久 metadata、Code Dispatch 的 `parentCallId` 与 Session 路径事实。不受支持或格式错误的输入使用压平的工具结果文本。文件路径摘要经属主的 `openFile` 打开文件，chat 视图把它路由到右侧 Sidebar 的文本预览；`inspect` 打开轨迹视图。terminal、diff、read、search 与 web 卡片的上限与 fallback 规则仍由 [ui-primitives README](../ui-primitives/README.zh.md) 负责；image 卡片的 fallback 规则由本包内的 card model 自行承载。
 
 terminal model 使用浏览器安全入口 `@deepseek-ai/dsh-spill-policy/notice` 的 `hasSpillNotice`，而非独立的 UI 匹配规则。[spill-policy README](../../spill/spill-policy/README.zh.md#shared-notice-ownership) 负责通知的格式化与识别。该检查保守地选择通用输出；匹配文本不能认证其来源，回放也不改变已记录的结果字节。
 </details>
diff --git a/packages/client/ui-tool/src/client/apply.ts b/packages/client/ui-tool/src/client/apply.ts
index 7c153dc515..28bc6e51fe 100644
--- a/packages/client/ui-tool/src/client/apply.ts
+++ b/packages/client/ui-tool/src/client/apply.ts
@@ -7,7 +7,6 @@ import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
 import type {} from '@deepseek-ai/dsh-client-ui-session/client'
 import { ToolCallTree } from './tool/ToolCallTree.tsx'
-import { ToolDetails } from './tool/ToolDetails.tsx'
 import { CONVERSATION_NS as NS } from './locale.ts'
 import { askQuestionToolview } from './tool/toolviews/ask-question-row.tsx'
 import { bashToolviewSample } from './tool/toolviews/bash-sample.tsx'
@@ -41,12 +40,6 @@ export function apply(ctx: ClientContext): void {
     inject: toolInject,
   }, ToolCallTree))
 
-  ctx.slots.inject('conversation.details.tool', () => ctx.slots.register({
-    name: 'conversation.details.tool',
-    locale: NS,
-    inject: toolInject,
-  }, ToolDetails))
-
   ctx.plugin(bashToolviewSample)
   ctx.plugin(readToolview)
   ctx.plugin(readImageToolview)
diff --git a/packages/client/ui-tool/src/client/contract/slots.ts b/packages/client/ui-tool/src/client/contract/slots.ts
index 7e6aaa675c..512c6880bb 100644
--- a/packages/client/ui-tool/src/client/contract/slots.ts
+++ b/packages/client/ui-tool/src/client/contract/slots.ts
@@ -3,7 +3,7 @@ import type {
   HostObservable, InjectFace, PropsLocale, PropsRenderSlots, PropsRuntime,
 } from '@deepseek-ai/dsh-client-ui-slots'
 import type { RemoteHostFacts } from '@deepseek-ai/dsh-api-remotes/client'
-import type { ToolCallBlock } from '@deepseek-ai/dsh-client-ui-chat/client'
+import type { OpenFileOptions, ToolCallBlock } from '@deepseek-ai/dsh-client-ui-chat/client'
 import type { MessageImageLoader, MessageImageSource } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 
@@ -63,8 +63,11 @@ export interface ToolCallOwnerProps {
   cwd?: string | undefined
   /** Host account home; POSIX home-rooted summaries display as `~`. */
   home?: string | undefined
-  /** Open a Tool argument path through the Host. */
-  openFile: (path: string) => void
+  /**
+   * Open a Tool argument path. A view that knows which line the call was about
+   * passes it, and the opened surface lands there.
+   */
+  openFile: (path: string, options?: OpenFileOptions) => void
   /**
    * Session-authorized image loader for the `tool.call.images` slot, supplied
    * by the chat node that owns this call. A composed chat node always
@@ -98,8 +101,3 @@ export type ToolTreeProps = PropsRuntime<'conversation.chat.node', 'tool-call'>
   & PropsRenderSlots<'tool.call.toolview'>
   & PropsLocale<'conversation'>
   & InjectFace<ToolHostInfoInjected>
-
-/** Full props of the selected Tool output renderer in the details panel. */
-export type ToolDetailsProps = PropsRuntime<'conversation.details.tool'>
-  & PropsLocale<'conversation'>
-  & InjectFace<ToolHostInfoInjected>
diff --git a/packages/client/ui-tool/src/client/index.ts b/packages/client/ui-tool/src/client/index.ts
index fc65940d0f..c2b2f61fa3 100644
--- a/packages/client/ui-tool/src/client/index.ts
+++ b/packages/client/ui-tool/src/client/index.ts
@@ -1,5 +1,5 @@
 /** Browser Tool plugin: whole-call composition and keyed atomic Tool views. */
 export { apply, inject } from './apply.ts'
 export type {
-  ToolCallOwnerProps, ToolCallViewProps, ToolDetailsProps, ToolHostInfoInjected, ToolTreeProps,
+  ToolCallOwnerProps, ToolCallViewProps, ToolHostInfoInjected, ToolTreeProps,
 } from './contract/slots.ts'
diff --git a/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx b/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
index d8288fa71a..2212278bd5 100644
--- a/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
+++ b/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
@@ -12,12 +12,11 @@ function callName(node: ToolCallBlock): string {
 
 /** One atomic call dispatched through the Tool-owned keyed slot. */
 const ToolCall = memo(function ToolCall({
-  renderSlot, callId, toolName, block, openFile, selected, cwd, home, inspectCall, loadImage, t, children,
+  renderSlot, callId, toolName, block, openFile, cwd, home, inspectCall, loadImage, t, children,
 }: Pick<ToolTreeProps, 'renderSlot' | 'openFile' | 'cwd' | 'inspectCall' | 'loadImage' | 't'> & {
   callId: string
   toolName: string
   block: ToolCallBlock
-  selected: boolean
   home?: string | undefined
   children?: ReactNode
 }) {
@@ -36,7 +35,6 @@ const ToolCall = memo(function ToolCall({
       className={css.callRow}
       data-chat-anchor-key={`call:${callId}`}
       data-chat-call-id={callId}
-      data-selected={selected || undefined}
     >
       {renderSlot('tool.call.toolview', owner, {
         entryKey: toolName,
@@ -48,8 +46,8 @@ const ToolCall = memo(function ToolCall({
 })
 
 const ToolCallBranch = memo(function ToolCallBranch({
-  renderSlot, block, selectedCallId, cwd, home, openFile, inspectCall, loadImage, t,
-}: Pick<ToolTreeProps, 'renderSlot' | 'selectedCallId' | 'cwd' | 'openFile' | 'inspectCall' | 'loadImage' | 't'> & {
+  renderSlot, block, cwd, home, openFile, inspectCall, loadImage, t,
+}: Pick<ToolTreeProps, 'renderSlot' | 'cwd' | 'openFile' | 'inspectCall' | 'loadImage' | 't'> & {
   block: ToolCallBlock
   home?: string | undefined
 }) {
@@ -60,7 +58,6 @@ const ToolCallBranch = memo(function ToolCallBranch({
       toolName={callName(block)}
       block={block}
       openFile={openFile}
-      selected={block.callId === selectedCallId}
       cwd={cwd}
       home={home}
       inspectCall={inspectCall}
@@ -74,7 +71,6 @@ const ToolCallBranch = memo(function ToolCallBranch({
               key={child.callId}
               renderSlot={renderSlot}
               block={child}
-              selectedCallId={selectedCallId}
               cwd={cwd}
               home={home}
               openFile={openFile}
@@ -96,7 +92,7 @@ const ToolCallBranch = memo(function ToolCallBranch({
  * @returns the Tool call tree.
  */
 export function ToolCallTree({
-  renderSlot, node, selectedCallId, cwd, openFile, inspectCall, loadImage, useHostInfo, t,
+  renderSlot, node, cwd, openFile, inspectCall, loadImage, useHostInfo, t,
 }: ToolTreeProps) {
   const home = useHostInfo(info => info.home)
   const block = node.data.root
@@ -104,7 +100,6 @@ export function ToolCallTree({
     <ToolCallBranch
       renderSlot={renderSlot}
       block={block}
-      selectedCallId={selectedCallId}
       cwd={cwd}
       home={home}
       openFile={openFile}
diff --git a/packages/client/ui-tool/src/client/tool/ToolDetails.module.css b/packages/client/ui-tool/src/client/tool/ToolDetails.module.css
deleted file mode 100644
index ebfb3afb07..0000000000
--- a/packages/client/ui-tool/src/client/tool/ToolDetails.module.css
+++ /dev/null
@@ -1,46 +0,0 @@
-.description {
-  margin: 0 0 6px;
-  color: var(--dsw-alias-label-secondary);
-  font: var(--dsw-font-xs-13);
-}
-
-.cardBody {
-  margin: 0;
-}
-
-.recovery {
-  margin: 6px 0 0;
-  white-space: pre-wrap;
-  overflow-wrap: anywhere;
-  color: var(--dsw-alias-label-tertiary);
-  font: var(--dsw-font-xs-13);
-}
-
-.code {
-  margin: 0;
-  padding: 16px;
-  border-radius: 12px;
-  background: var(--dsw-alias-markdown-code-block);
-  font-family: var(--ds-font-family-code);
-  font-size: 13px;
-  line-height: 22px;
-  color: var(--dsw-alias-label-primary);
-  white-space: pre-wrap;
-  word-break: break-word;
-}
-
-.code[data-error] {
-  color: var(--dsw-alias-state-error-primary);
-}
-
-.read,
-.web {
-  margin: 0;
-}
-
-.empty {
-  padding: 8px 0;
-  font-size: 13px;
-  line-height: 20px;
-  color: var(--dsw-alias-label-tertiary);
-}
diff --git a/packages/client/ui-tool/src/client/tool/ToolDetails.tsx b/packages/client/ui-tool/src/client/tool/ToolDetails.tsx
deleted file mode 100644
index 6b4ea3b103..0000000000
--- a/packages/client/ui-tool/src/client/tool/ToolDetails.tsx
+++ /dev/null
@@ -1,68 +0,0 @@
-/** Card-aware output body for the selected Tool call in details. */
-import { DiffBlock, ReadBlock, SearchBlock, TerminalBlock, WebBlock } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { ToolDetailsProps } from '../contract/slots.ts'
-import { diffCardModel } from './models/diff-card-model.ts'
-import { readCardModel } from './models/read-card-model.ts'
-import { searchCardModel } from './models/search-card-model.ts'
-import {
-  localizeTerminalCardModel, terminalBlockLabels, terminalCardModel,
-} from './models/terminal-card-model.ts'
-import {
-  diffBlockLabels, readBlockLabels, searchBlockLabels, webBlockLabels,
-} from './models/primitive-labels.ts'
-import { resultText } from './models/tool-call-model.ts'
-import { webCardModel } from './models/web-card-model.ts'
-import css from './ToolDetails.module.css'
-
-/**
- * Render the selected Tool call's structured output when its raw fields form a
- * supported card, otherwise preserve the flattened result text.
- * @param props - selected call slice, workspace root, host home, and locale seat.
- * @returns the details output body.
- */
-export function ToolDetails({
-  block, cwd, useHostInfo, t,
-}: Pick<ToolDetailsProps, 'block' | 'cwd' | 'useHostInfo' | 't'>) {
-  const home = useHostInfo(info => info.home)
-  const terminalModel = terminalCardModel(block, cwd)
-  if (terminalModel !== null) {
-    const terminal = localizeTerminalCardModel(terminalModel, t)
-    return (
-      <>
-        {terminal.description !== undefined ? (
-          <div className={css.description}>{terminal.description}</div>
-        ) : null}
-        <TerminalBlock {...terminal.card} labels={terminalBlockLabels(t)} className={css.cardBody} />
-      </>
-    )
-  }
-  const read = readCardModel(block, cwd, home)
-  if (read !== null) return <ReadBlock {...read} labels={readBlockLabels(t)} className={css.read} />
-  const diff = diffCardModel(block)
-  if (diff !== null) return <DiffBlock {...diff.card} labels={diffBlockLabels(t)} className={css.cardBody} />
-  const search = searchCardModel(block)
-  if (search !== null) {
-    return (
-      <>
-        <SearchBlock {...search.card} labels={searchBlockLabels(t)} className={css.cardBody} />
-        {search.recovery !== undefined ? <div className={css.recovery}>{search.recovery}</div> : null}
-      </>
-    )
-  }
-  const web = webCardModel(block)
-  if (web !== null) {
-    const body = 'kind' in block ? resultText(block) : ''
-    return (
-      <>
-        <WebBlock {...web} labels={webBlockLabels(t)} className={css.web} />
-        {body !== '' ? <pre className={css.code}>{body}</pre> : null}
-      </>
-    )
-  }
-  if (!('kind' in block)) return <div className={css.empty}>{t('details.running')}</div>
-  return (
-    <pre className={css.code} data-error={block.isError || undefined}>
-      {resultText(block)}
-    </pre>
-  )
-}
diff --git a/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx b/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx
index 44bbafb6e9..ca5becec3b 100644
--- a/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx
+++ b/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx
@@ -5,6 +5,7 @@ import {
   diffTotals,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsRenderSlots, TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
+import type { OpenFileOptions } from '@deepseek-ai/dsh-client-ui-chat/client'
 import type { MessageImageLoader } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { CHAT_DIFF_MAX_LINES, type DiffCardModel } from '../models/diff-card-model.ts'
 import { CHAT_READ_MAX_LINES, type ReadCardModel } from '../models/read-card-model.ts'
@@ -75,8 +76,10 @@ export interface ToolRowProps {
    * renders as a hover-underline link that opens the host default app.
    */
   filePath?: string | undefined
-  /** Open the path with the host OS default application (already cwd-resolved). */
-  onOpenFile?: ((path: string) => void) | undefined
+  /** 1-based line the call was about; absent = open the file at its beginning. */
+  filePathLine?: number | undefined
+  /** Open the path (already cwd-resolved), landing on `filePathLine` when given. */
+  onOpenFile?: ((path: string, options?: OpenFileOptions) => void) | undefined
   /**
    * Jump to this call in the trajectory view: a hover-revealed Inspect pill
    * over the expanded body. Absent = no affordance.
@@ -127,6 +130,7 @@ export function ToolRow({
   web,
   state,
   filePath,
+  filePathLine,
   onOpenFile,
   inspect,
 }: ToolRowProps) {
@@ -174,7 +178,9 @@ export function ToolRow({
   }
   const openFile = (event: MouseEvent<HTMLButtonElement>) => {
     event.stopPropagation()
-    if (filePath !== undefined) onOpenFile?.(filePath)
+    if (filePath === undefined || onOpenFile === undefined) return
+    if (filePathLine === undefined) onOpenFile(filePath)
+    else onOpenFile(filePath, { line: filePathLine })
   }
   // Keep Enter/Space on the focused path link from bubbling to the row's
   // keydown handler, which would preventDefault() the key and toggle expand
diff --git a/packages/client/ui-tool/src/client/tool/models/read-card-model.ts b/packages/client/ui-tool/src/client/tool/models/read-card-model.ts
index a5a8fffdfe..7afcd40263 100644
--- a/packages/client/ui-tool/src/client/tool/models/read-card-model.ts
+++ b/packages/client/ui-tool/src/client/tool/models/read-card-model.ts
@@ -31,13 +31,18 @@ interface ReadMeta {
   lang?: string
 }
 
+/** Whether a model-supplied argument is a 1-based line position or count: an integer of at least 1. */
+function positiveInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 1
+}
+
 function validReadCall(block: ToolCallBlock): boolean {
   const call = parsedToolCall(block)
   if (call?.name !== 'read') return false
   const { file_path: path, offset, limit } = call.args
   if (typeof path !== 'string' || path.trim() === '') return false
-  if (offset !== undefined && (typeof offset !== 'number' || !Number.isInteger(offset) || offset < 1)) return false
-  if (limit !== undefined && (typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1)) return false
+  if (offset !== undefined && !positiveInteger(offset)) return false
+  if (limit !== undefined && !positiveInteger(limit)) return false
   return true
 }
 
@@ -66,6 +71,23 @@ function readMeta(meta: unknown): ReadMeta | null {
   }
 }
 
+/**
+ * The line one `read` call was about, from its arguments.
+ *
+ * `offset` is the read tool's own 1-based start line, so opening the path can
+ * land where the model looked. Available while the call is still running,
+ * unlike the persisted metadata, because the arguments carry it. The arguments
+ * are model-produced JSON: only an integer of at least 1 is a line, and a call
+ * whose `offset` is anything else names none.
+ * @param block - running or settled Tool block.
+ * @returns the 1-based line, or undefined when the call named none.
+ */
+export function readCallLine(block: ToolCallBlock): number | undefined {
+  if (!validReadCall(block)) return undefined
+  const { offset } = parsedToolCall(block)?.args ?? {}
+  return positiveInteger(offset) ? offset : undefined
+}
+
 /**
  * Derive a settled root read card after validating its persisted metadata and
  * model-facing read envelope.
diff --git a/packages/client/ui-tool/src/client/tool/toolviews/read-family-row.tsx b/packages/client/ui-tool/src/client/tool/toolviews/read-family-row.tsx
index 006ba643f1..40553313d2 100644
--- a/packages/client/ui-tool/src/client/tool/toolviews/read-family-row.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/read-family-row.tsx
@@ -21,10 +21,11 @@ export type ReadImageRowProps = ReadFamilyRowProps & PropsRenderSlots<'tool.call
 
 /**
  * The card material one read-family row contributes: exactly the ToolRow card
- * props that row owns. `read` supplies `read`; `read_image` supplies `image`
- * together with the slot dispatcher and loader that draw it.
+ * props that row owns. `read` supplies `read` and the line its call named;
+ * `read_image` supplies `image` together with the slot dispatcher and loader
+ * that draw it.
  */
-export type ReadFamilyCard = Pick<ToolRowProps, 'read' | 'image' | 'renderSlot' | 'loadImage'>
+export type ReadFamilyCard = Pick<ToolRowProps, 'read' | 'image' | 'renderSlot' | 'loadImage' | 'filePathLine'>
 
 /**
  * Compose a read-family row: the shared chrome and model-derived fields, plus the
diff --git a/packages/client/ui-tool/src/client/tool/toolviews/read-row.tsx b/packages/client/ui-tool/src/client/tool/toolviews/read-row.tsx
index 06c0d12ba3..a6a8a64b28 100644
--- a/packages/client/ui-tool/src/client/tool/toolviews/read-row.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/read-row.tsx
@@ -1,18 +1,22 @@
 import type { Context } from '@deepseek-ai/cordis'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
 import type { ToolCallViewProps } from '../../contract/slots.ts'
-import { readCardModel } from '../models/read-card-model.ts'
+import { readCallLine, readCardModel } from '../models/read-card-model.ts'
 import { readFamilyRow } from './read-family-row.tsx'
 import { CONVERSATION_NS as NS } from '../../locale.ts'
 
 type ReadRowProps = ToolCallViewProps & PropsLocale<'conversation'>
 
 /**
- * Lets users expand a completed read result and open its reported path.
+ * Lets users expand a completed read result and open its reported path at the
+ * line the call started from.
  */
 export function ReadRow(props: ReadRowProps) {
   const { block, cwd, home } = props
-  return readFamilyRow(props, { read: readCardModel(block, cwd, home) })
+  return readFamilyRow(props, {
+    read: readCardModel(block, cwd, home),
+    filePathLine: readCallLine(block),
+  })
 }
 
 /** Registers the read tool's conversation row. */
diff --git a/packages/client/ui-tool/tests/assembly-surfaces.client.spec.tsx b/packages/client/ui-tool/tests/assembly-surfaces.client.spec.tsx
index be428ebf19..636124555e 100644
--- a/packages/client/ui-tool/tests/assembly-surfaces.client.spec.tsx
+++ b/packages/client/ui-tool/tests/assembly-surfaces.client.spec.tsx
@@ -1,3 +1,4 @@
+import { toolSessionEvents } from './tool-fixtures.client.ts'
 // @vitest-environment jsdom
 /** Tool assembly acceptance through the real ui-conversation host. */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
@@ -13,7 +14,6 @@ import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotTestRuntime, TestRemote, usePinnedBrowserLanguages, stubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime'
 import { apply as applyConversation, inject as injectConversation } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { apply as applyTool, inject as injectTool } from '../src/client/apply.ts'
-import { toolSessionEvents } from './tool-details-render.client.tsx'
 
 // The service reads its initial locale from the browser; these specs assert
 // the shipped Chinese copy, so they state the browser they assume.
@@ -59,14 +59,13 @@ const bashResult = (seq: number, callId: string, over?: Partial<ToolResultNode>)
 })
 
 /** Test-owned AppFrame role: declares and renders the resident conversation area. */
-type AppRootProps = PropsRenderSlots<'conversation' | 'details'>
+type AppRootProps = PropsRenderSlots<'conversation'>
 function AppRoot({ renderSlot }: AppRootProps) {
   return <>{renderSlot('conversation', {})}</>
 }
 
 const LAYOUT_CHILDREN = {
   'conversation': { kind: 'single', scope: 'session-maybe' },
-  'details': { kind: 'single', scope: 'session' },
 } as const
 
 async function bench(nodes: ToolResultNode[]) {
@@ -78,6 +77,7 @@ async function bench(nodes: ToolResultNode[]) {
   })
   runtime.ctx.provide('settingsScope', { bind: () => stubSettingsScope().scope } as never)
   runtime.ctx.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
+  runtime.ctx.provide('sidebarRight', { openResource: vi.fn() } as never)
   runtime.ctx.provide('uiWorkspace', {
     connectWorkspace: vi.fn(async () => SID),
   } as never)
diff --git a/packages/client/ui-tool/tests/chat-code-subcalls.client.spec.tsx b/packages/client/ui-tool/tests/chat-code-subcalls.client.spec.tsx
index 36b9886b89..94db65688d 100644
--- a/packages/client/ui-tool/tests/chat-code-subcalls.client.spec.tsx
+++ b/packages/client/ui-tool/tests/chat-code-subcalls.client.spec.tsx
@@ -16,7 +16,7 @@ import {
 import { en as conversationEn, NS as CONVERSATION_NS, zh as conversationZh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 import { apply as applyChat, inject as injectChat } from '@deepseek-ai/dsh-client-ui-chat/client'
 import { apply as applyTool, inject as injectTool } from '../src/client/apply.ts'
-import { toolChatSnapshot } from './tool-details-render.client.tsx'
+import { toolChatSnapshot } from './tool-fixtures.client.ts'
 
 const SID = 's1' as SessionId
 
@@ -112,12 +112,14 @@ async function bench(snapshot: ChatSnapshot) {
 
   await runtime.sessions.add({
     id: SID,
-    summary: { title: 'S', displayTitle: 'S' },
+    summary: { title: 'S', displayTitle: 'S', cwd: '/w' },
     snapshot: { running: snapshot.legacy.runningCalls.length > 0 },
   })
   const layout = { openDetails: vi.fn(), closeDetails: vi.fn() }
   const openWorkspacePath = vi.fn(async () => ({ ok: true, value: { opened: true } }))
   ctx.provide('layout', layout as never)
+  const sidebarRight = { openResource: vi.fn<(address: string) => void>() }
+  ctx.provide('sidebarRight', sidebarRight as never)
   ctx.provide('uiWorkspace', {} as never)
   new TestRemote(ctx, { session: { openWorkspacePath } })
   const locale = new LocaleRuntime(ctx)
@@ -128,7 +130,7 @@ async function bench(snapshot: ChatSnapshot) {
   await runtime.root.declare(ROOT_CHILDREN, AppRoot)
   await runtime.mount({ inject: [...injectChat], apply: applyChat })
   await runtime.mount({ inject: [...injectTool], apply: applyTool })
-  return { runtime, layout, openWorkspacePath }
+  return { runtime, layout, openWorkspacePath, sidebarRight }
 }
 
 function mountApp(runtime: SlotTestRuntime) {
@@ -214,7 +216,7 @@ describe('run_code sub-calls through the real chat machinery', () => {
     expect(nested).not.toBeNull()
   })
 
-  it('a file sub-row click opens the host path; bash sub-rows do not open details', async () => {
+  it('a file sub-row click opens the file in the Sidebar; bash sub-rows open nothing', async () => {
     const parent = 'call-64'
     const subCalls = [
       subCall(11, parent, 1, 'read', { path: 'notes/demo.txt' }, 'ok'),
@@ -223,12 +225,12 @@ describe('run_code sub-calls through the real chat machinery', () => {
     const b = await bench(snapshotWith([codeResult(10, parent)], subCalls))
     const view = mountApp(b.runtime)
     view.getByText('notes/demo.txt').click()
-    expect(b.layout.openDetails).not.toHaveBeenCalled()
     await vi.waitFor(() => {
-      expect(b.openWorkspacePath).toHaveBeenCalledWith({ path: 'notes/demo.txt' })
+      expect(b.sidebarRight.openResource).toHaveBeenCalledWith('dsh-resource://file/session/s1/notes/demo.txt')
     })
+    expect(b.openWorkspacePath).not.toHaveBeenCalled()
     view.getByText('List notes').click()
-    expect(b.layout.openDetails).not.toHaveBeenCalled()
+    expect(b.sidebarRight.openResource).toHaveBeenCalledTimes(1)
   })
 
   it('a RUNNING run_code call nests its so-far dispatches under the spinner row', async () => {
diff --git a/packages/client/ui-tool/tests/diff-card.client.spec.tsx b/packages/client/ui-tool/tests/diff-card.client.spec.tsx
index be039beb46..1e8b2fdef6 100644
--- a/packages/client/ui-tool/tests/diff-card.client.spec.tsx
+++ b/packages/client/ui-tool/tests/diff-card.client.spec.tsx
@@ -2,25 +2,17 @@
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
-import {
-  bindSnapshotSelector, conversationSnapshot, sessionSnapshot, workspaceSnapshot,
-} from '@deepseek-ai/dsh-client-test-runtime'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-test-runtime'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
-import type {
-  ChatSnapshot, ConversationNode, RunningToolCall, SelectionTarget, ToolResultNode,
-} from '@deepseek-ai/dsh-client-ui-chat/client'
+import type { RunningToolCall, ToolResultNode } from '@deepseek-ai/dsh-client-ui-chat/client'
 import type { SessionListState } from '@deepseek-ai/dsh-api-session-controller/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { CHAT_DIFF_MAX_LINES, diffCardModel } from '../src/client/tool/models/diff-card-model.ts'
-import { createChatStore } from '@deepseek-ai/dsh-client-ui-chat/src/client/stores.ts'
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
-import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-chat/src/client/details/DetailsPanel.tsx'
 import { FileMutationRow, fileMutationToolview } from '../src/client/tool/toolviews/file-mutation-row.tsx'
-import { renderToolDetails, toolChatSnapshot, useEmptyTrajectory } from './tool-details-render.client.tsx'
 import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
-import { zh as chatZh } from '@deepseek-ai/dsh-client-ui-chat/src/client/locale.ts'
 
 afterEach(cleanup)
 
@@ -29,7 +21,6 @@ type FileMutationRowProps = Parameters<typeof FileMutationRow>[0]
 const SID = 's1' as SessionId
 
 const t = makeTranslate(zh, commonZh)
-const chatT = makeTranslate(chatZh, commonZh)
 
 const ARGS = '{"file_path":"notes/demo.txt","old_string":"hello","new_string":"hello fixture"}'
 
@@ -356,87 +347,3 @@ describe('fileMutationToolview registration', () => {
     expect(registered.every(r => r.disposed)).toBe(true)
   })
 })
-
-describe('DetailsPanel diff Output section', () => {
-  function mount(snapshot: ChatSnapshot, selection: SelectionTarget | null, cwd?: string) {
-    localStorage.clear()
-    const chat = createChatStore().create()
-    if (selection !== null) chat.actions.select(selection)
-    const sessions = createSnapshotStore<SessionListState>(cwd === undefined
-      ? { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined }
-      : {
-        ids: [SID],
-        byId: { [SID]: { id: SID, displayTitle: 'r', running: false, blank: false, updatedAt: 0, cwd } },
-        current: SID,
-        phase: 'ready',
-        subagentsByParent: {}, jobsBySession: {},
-        currentAddress: undefined,
-      })
-    const session = createSnapshotStore(sessionSnapshot(SID))
-    const conversation = createSnapshotStore(conversationSnapshot())
-    const workspaces = createSnapshotStore(workspaceSnapshot())
-    const attention = createSnapshotStore(new Map())
-    return render(
-      <DetailsPanel
-        renderSlot={renderToolDetails(t)}
-        SessionProvider={({ children }) => children}
-        sessionId={SID}
-        useSession={bindSnapshotSelector(session)}
-        useSessions={bindSnapshotSelector(sessions)}
-        useSessionPendingInteraction={bindSnapshotSelector(attention)}
-        useWorkspaces={bindSnapshotSelector(workspaces)}
-        useConversation={bindSnapshotSelector(conversation)}
-        useChat={bindSnapshotSelector({ getSnapshot: () => snapshot, subscribe: () => () => {} })}
-        useTrajectory={useEmptyTrajectory}
-        useInput={(() => { throw new Error('unused') })}
-        inputActions={{
-          setDraft: () => {},
-          addAttachments: () => true,
-          removeAttachment: () => {},
-          pruneAttachments: () => {},
-          submit: () => {},
-        }}
-        useProjection={(() => undefined)}
-        useStore={bindSnapshotSelector(chat)}
-        actions={chat.actions}
-        closeDetails={vi.fn()}
-        t={chatT}
-      />,
-    )
-  }
-
-  function snapshot(over: {
-    nodes?: readonly ConversationNode[]
-    runningCalls?: readonly RunningToolCall[]
-  } = {}): ChatSnapshot {
-    const nodes = over.nodes ?? []
-    const runningCalls = over.runningCalls ?? []
-    return toolChatSnapshot(nodes, runningCalls)
-  }
-
-  const target: SelectionTarget = { turnSeq: 10, callId: 'c1', toolName: 'edit' }
-
-  it('renders the applied diff at full height, keeping the JSON Input section', () => {
-    const view = mount(snapshot({ nodes: [settled()] }), target)
-    expect(view.getByText(/"file_path"/)).toBeTruthy()
-    expect(view.container.querySelector('[data-diff]')).not.toBeNull()
-    expect(view.getByText('hello fixture')).toBeTruthy()
-  })
-
-  it('a running diff call renders its intended change, not the 运行中… placeholder', () => {
-    const view = mount(snapshot({ runningCalls: [running()] }), target)
-    expect(view.container.querySelector('[data-diff]')).not.toBeNull()
-    expect(view.queryByText('运行中…')).toBeNull()
-  })
-
-  it('a non-diff result keeps the flattened pre', () => {
-    const view = mount(snapshot({
-      nodes: [settled({
-        meta: undefined,
-        content: [{ type: 'text', text: 'permission denied' }],
-      })],
-    }), target)
-    expect(view.container.querySelector('[data-diff]')).toBeNull()
-    expect(view.getByText('输出').closest('section')?.querySelector('pre')?.textContent).toBe('permission denied')
-  })
-})
diff --git a/packages/client/ui-tool/tests/read-card.client.spec.tsx b/packages/client/ui-tool/tests/read-card.client.spec.tsx
index 5f172891c0..21ace19335 100644
--- a/packages/client/ui-tool/tests/read-card.client.spec.tsx
+++ b/packages/client/ui-tool/tests/read-card.client.spec.tsx
@@ -3,24 +3,16 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
 import { Context } from '@deepseek-ai/cordis'
-import {
-  bindSnapshotSelector, conversationSnapshot, makeTranslate, sessionSnapshot, workspaceSnapshot,
-} from '@deepseek-ai/dsh-client-test-runtime'
+import { bindSnapshotSelector, makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
-import type {
-  ChatSnapshot, ConversationNode, RunningToolCall, SelectionTarget, ToolResultNode,
-} from '@deepseek-ai/dsh-client-ui-chat/client'
+import type { RunningToolCall, ToolResultNode } from '@deepseek-ai/dsh-client-ui-chat/client'
 import type { SessionListState } from '@deepseek-ai/dsh-api-session-controller/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
-import { CHAT_READ_MAX_LINES, readCardModel } from '../src/client/tool/models/read-card-model.ts'
-import { createChatStore } from '@deepseek-ai/dsh-client-ui-chat/src/client/stores.ts'
+import { CHAT_READ_MAX_LINES, readCallLine, readCardModel } from '../src/client/tool/models/read-card-model.ts'
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
 import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
-import { zh as chatZh } from '@deepseek-ai/dsh-client-ui-chat/src/client/locale.ts'
-import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-chat/src/client/details/DetailsPanel.tsx'
 import { ReadRow, readToolview } from '../src/client/tool/toolviews/read-row.tsx'
-import { renderToolDetails, toolChatSnapshot, useEmptyTrajectory } from './tool-details-render.client.tsx'
 
 afterEach(cleanup)
 
@@ -28,7 +20,6 @@ const SID = 's1' as SessionId
 
 /** The chat-view locale seat: this package's namespace over the common fallback. */
 const t: GenericToolCardProps['t'] = makeTranslate(zh, commonZh)
-const chatT = makeTranslate(chatZh, commonZh)
 
 // The read tool's real schema key is `file_path`; the top-level read samples
 // use it so the row exercises a production-shaped call. `web_fetch` (below) has
@@ -149,6 +140,28 @@ describe('readCardModel', () => {
   })
 })
 
+describe('readCallLine', () => {
+  it('reads the 1-based offset a well-formed read call started from, running or settled', () => {
+    expect(readCallLine(running())).toBe(41)
+    expect(readCallLine(settled())).toBe(41)
+  })
+
+  it.each([
+    ['no offset', '{"file_path":"src/a.ts"}'],
+    ['a string offset', '{"file_path":"src/a.ts","offset":"41"}'],
+    ['zero', '{"file_path":"src/a.ts","offset":0}'],
+    ['a negative offset', '{"file_path":"src/a.ts","offset":-3}'],
+    ['a fraction', '{"file_path":"src/a.ts","offset":2.5}'],
+    ['a read without a path', '{"offset":3}'],
+  ])('names no line for %s', (_label, argsRaw) => {
+    expect(readCallLine(running({ argsRaw }))).toBeUndefined()
+  })
+
+  it('names no line for a call that is not read', () => {
+    expect(readCallLine(running({ name: 'echo', argsRaw: '{"offset":3}' }))).toBeUndefined()
+  })
+})
+
 describe('GenericToolCard read body', () => {
   const ownerProps = (block: RunningToolCall | ToolResultNode): GenericToolCardProps => ({
     loadImage: vi.fn(() => Promise.reject(new Error('not used'))),
@@ -228,13 +241,14 @@ describe('ReadRow keyed toolview', () => {
     expect(view.getAllByText('src/a.ts').length).toBe(1)
   })
 
-  it('the path summary opens the file through the host', () => {
+  it('the path summary opens the file at the line the call started from', () => {
     const openFile = vi.fn()
     const view = render(<ReadRow {...{ ...rowProps(settled()), openFile }} />)
     fireEvent.click(view.getByRole('button', { name: 'src/a.ts' }))
-    // The row derives the file path from args; the chat view resolves it against
-    // the cwd before this callback opens it, so the arg path is what arrives.
-    expect(openFile).toHaveBeenCalledWith('src/a.ts')
+    // The row derives the file path and the `offset` line from args; the chat
+    // view resolves the path against the cwd before this callback opens it, so
+    // the arg path is what arrives.
+    expect(openFile).toHaveBeenCalledWith('src/a.ts', { line: 41 })
   })
 
   it('a running read renders the summary row alone, and its state', () => {
@@ -271,104 +285,3 @@ describe('ReadRow keyed toolview', () => {
     expect(readToolview.inject).toEqual(['slots'])
   })
 })
-
-describe('DetailsPanel Output section (read)', () => {
-  function mount(
-    snapshot: ChatSnapshot,
-    selection: SelectionTarget | null,
-    cwd?: string,
-    description?: Parameters<typeof renderToolDetails>[1],
-  ) {
-    localStorage.clear()
-    const chat = createChatStore().create()
-    if (selection !== null) chat.actions.select(selection)
-    const sessions = createSnapshotStore<SessionListState>(cwd === undefined
-      ? { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined }
-      : {
-        ids: [SID],
-        byId: { [SID]: { id: SID, displayTitle: 'r', running: false, blank: false, updatedAt: 0, cwd } },
-        current: SID,
-        phase: 'ready',
-        subagentsByParent: {}, jobsBySession: {},
-        currentAddress: undefined,
-      })
-    const session = createSnapshotStore(sessionSnapshot(SID))
-    const conversation = createSnapshotStore(conversationSnapshot())
-    const workspaces = createSnapshotStore(workspaceSnapshot())
-    const attention = createSnapshotStore(new Map())
-    return render(
-      <DetailsPanel
-        renderSlot={renderToolDetails(t, description)}
-        SessionProvider={({ children }) => children}
-        sessionId={SID}
-        t={chatT}
-        useSession={bindSnapshotSelector(session)}
-        useSessions={bindSnapshotSelector(sessions)}
-        useSessionPendingInteraction={bindSnapshotSelector(attention)}
-        useWorkspaces={bindSnapshotSelector(workspaces)}
-        useConversation={bindSnapshotSelector(conversation)}
-        useChat={bindSnapshotSelector({ getSnapshot: () => snapshot, subscribe: () => () => {} })}
-        useTrajectory={useEmptyTrajectory}
-        useInput={(() => { throw new Error('unused') })}
-        inputActions={{
-          setDraft: () => {},
-          addAttachments: () => true,
-          removeAttachment: () => {},
-          pruneAttachments: () => {},
-          submit: () => {},
-        }}
-        useProjection={(() => undefined)}
-        useStore={bindSnapshotSelector(chat)}
-        actions={chat.actions}
-        closeDetails={vi.fn()}
-      />,
-    )
-  }
-
-  function snapshot(over: {
-    nodes?: readonly ConversationNode[]
-    runningCalls?: readonly RunningToolCall[]
-  } = {}): ChatSnapshot {
-    const nodes = over.nodes ?? []
-    const runningCalls = over.runningCalls ?? []
-    return toolChatSnapshot(nodes, runningCalls)
-  }
-
-  const target: SelectionTarget = { turnSeq: 10, callId: 'c1', toolName: 'read' }
-
-  it('renders the read card at full height, keeping the JSON Input section', () => {
-    const long = Array.from({ length: 20 }, (_, i) => ({ number: i + 1, text: `row-${i}` }))
-    const view = mount(snapshot({
-      nodes: [settled({ meta: readMeta({ offset: 1, lines: long, totalLines: 20 }) })],
-    }), target)
-    expect(view.getByText(/"file_path"/)).toBeTruthy()
-    expect(view.container.querySelector('[data-read]')).not.toBeNull()
-    // The panel takes the primitive's own default cap (16), not the row's.
-    expect(view.getByText(`… 其余 ${20 - 16} 行`)).toBeTruthy()
-    expect(contentTexts(view.container)).toContain('row-0')
-  })
-
-  it('a non-read result keeps the flattened pre form', () => {
-    const view = mount(snapshot({
-      nodes: [settled({
-        meta: undefined,
-        content: [{ type: 'text', text: 'plain result' }],
-      })],
-    }), target)
-    expect(view.container.querySelector('[data-read]')).toBeNull()
-    expect(view.getByText('输出').closest('section')?.querySelector('pre')?.textContent).toBe('plain result')
-  })
-
-  it('abbreviates a leftover POSIX home path on the read card label', () => {
-    const view = mount(snapshot({
-      nodes: [settled({ meta: readMeta({ path: '/Users/u/notes.md' }) })],
-    }), target, '/tmp/ws', '/Users/u')
-    expect(view.getByText('~/notes.md')).toBeTruthy()
-  })
-
-  it('a running read keeps the 运行中… placeholder (no result metadata)', () => {
-    const view = mount(snapshot({ runningCalls: [running()] }), target)
-    expect(view.getByText('运行中…')).toBeTruthy()
-    expect(view.container.querySelector('[data-read]')).toBeNull()
-  })
-})
diff --git a/packages/client/ui-tool/tests/search-card.client.spec.tsx b/packages/client/ui-tool/tests/search-card.client.spec.tsx
index 963bf18e49..b189b6f6a8 100644
--- a/packages/client/ui-tool/tests/search-card.client.spec.tsx
+++ b/packages/client/ui-tool/tests/search-card.client.spec.tsx
@@ -2,32 +2,20 @@
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
-import {
-  bindSnapshotSelector, conversationSnapshot, sessionSnapshot, workspaceSnapshot,
-} from '@deepseek-ai/dsh-client-test-runtime'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
-import type {
-  ChatSnapshot, ConversationNode, RunningToolCall, SelectionTarget, ToolResultNode,
-} from '@deepseek-ai/dsh-client-ui-chat/client'
-import type { SessionListState } from '@deepseek-ai/dsh-api-session-controller/client'
+import type { RunningToolCall, ToolResultNode } from '@deepseek-ai/dsh-client-ui-chat/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { CHAT_SEARCH_MAX_LINES, searchCardModel } from '../src/client/tool/models/search-card-model.ts'
 import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
-import { zh as chatZh } from '@deepseek-ai/dsh-client-ui-chat/src/client/locale.ts'
-import { createChatStore } from '@deepseek-ai/dsh-client-ui-chat/src/client/stores.ts'
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
-import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-chat/src/client/details/DetailsPanel.tsx'
 import { SearchRow, searchToolview } from '../src/client/tool/toolviews/search-row.tsx'
-import { renderToolDetails, toolChatSnapshot, useEmptyTrajectory } from './tool-details-render.client.tsx'
 
 type SearchRowProps = Parameters<typeof SearchRow>[0]
 
 afterEach(cleanup)
 
 const t: GenericToolCardProps['t'] = makeTranslate(zh, commonZh)
-const chatT = makeTranslate(chatZh, commonZh)
 
 /** The rendered search card's kind attribute, so a render site cannot silently drop it. */
 function searchKindOf(container: HTMLElement): string | null {
@@ -367,89 +355,3 @@ describe('SearchRow keyed card', () => {
     expect(searchToolview.inject).toEqual(['slots'])
   })
 })
-
-describe('DetailsPanel Output section (search)', () => {
-  function mount(snapshot: ChatSnapshot, selection: SelectionTarget | null) {
-    localStorage.clear()
-    const chat = createChatStore().create()
-    if (selection !== null) chat.actions.select(selection)
-    const sessions = createSnapshotStore<SessionListState>({
-      ids: [], byId: {}, current: undefined, phase: 'ready',
-      subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined,
-    })
-    const session = createSnapshotStore(sessionSnapshot(SID))
-    const conversation = createSnapshotStore(conversationSnapshot())
-    const workspaces = createSnapshotStore(workspaceSnapshot())
-    const attention = createSnapshotStore(new Map())
-    return render(
-      <DetailsPanel
-        renderSlot={renderToolDetails(t)}
-        SessionProvider={({ children }) => children}
-        sessionId={SID}
-        useSession={bindSnapshotSelector(session)}
-        useSessions={bindSnapshotSelector(sessions)}
-        useSessionPendingInteraction={bindSnapshotSelector(attention)}
-        useWorkspaces={bindSnapshotSelector(workspaces)}
-        useConversation={bindSnapshotSelector(conversation)}
-        useChat={bindSnapshotSelector({ getSnapshot: () => snapshot, subscribe: () => () => {} })}
-        useTrajectory={useEmptyTrajectory}
-        useInput={(() => { throw new Error('unused') })}
-        inputActions={{
-          setDraft: () => {},
-          addAttachments: () => true,
-          removeAttachment: () => {},
-          pruneAttachments: () => {},
-          submit: () => {},
-        }}
-        useProjection={(() => undefined)}
-        useStore={bindSnapshotSelector(chat)}
-        actions={chat.actions}
-        closeDetails={vi.fn()}
-        t={chatT}
-      />,
-    )
-  }
-
-  function snapshot(over: {
-    nodes?: readonly ConversationNode[]
-    runningCalls?: readonly RunningToolCall[]
-  } = {}): ChatSnapshot {
-    const nodes = over.nodes ?? []
-    const runningCalls = over.runningCalls ?? []
-    return toolChatSnapshot(nodes, runningCalls)
-  }
-
-  const grepTarget: SelectionTarget = { turnSeq: 10, callId: 'c1', toolName: 'grep' }
-  const globTarget: SelectionTarget = { turnSeq: 11, callId: 'c2', toolName: 'glob' }
-
-  it('renders the grep matches card at full height, keeping the JSON Input section', () => {
-    const view = mount(snapshot({ nodes: [settledGrep()] }), grepTarget)
-    expect(view.getByText(/"pattern"/)).toBeTruthy()
-    expect(searchRows(view.container)).toContain('12: const foo = 1')
-    expect(searchKindOf(view.container)).toBe('matches')
-  })
-
-  it('renders the glob path card', () => {
-    const view = mount(snapshot({ nodes: [settledGlob()] }), globTarget)
-    expect(view.getByText('src/a.ts')).toBeTruthy()
-    expect(searchKindOf(view.container)).toBe('paths')
-  })
-
-  it('renders the recovery footer below the card for a capped search', () => {
-    const recovery = 'src/a.ts\nsrc/b.ts\n\n(Showing 2 of 23 paths. Full sorted result stored at: spill://glob-7.)'
-    const view = mount(snapshot({
-      nodes: [settledGlob({ content: [{ type: 'text', text: recovery }], meta: pathsMeta({ truncated: true, total: 23 }) })],
-    }), globTarget)
-    expect(searchKindOf(view.container)).toBe('paths')
-    expect(view.getByText(/Full sorted result stored at: spill:\/\/glob-7/)).toBeTruthy()
-  })
-
-  it('a non-search result keeps the flattened pre form', () => {
-    const view = mount(snapshot({
-      nodes: [settledGrep({ meta: undefined })],
-    }), grepTarget)
-    expect(searchKindOf(view.container)).toBeNull()
-    const output = view.getByText('输出').closest('section')
-    expect(output?.querySelector('pre')?.textContent).toContain('const foo = 1')
-  })
-})
diff --git a/packages/client/ui-tool/tests/terminal-card.client.spec.tsx b/packages/client/ui-tool/tests/terminal-card.client.spec.tsx
index 9476de0ce5..1cfe3b869c 100644
--- a/packages/client/ui-tool/tests/terminal-card.client.spec.tsx
+++ b/packages/client/ui-tool/tests/terminal-card.client.spec.tsx
@@ -2,13 +2,9 @@
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
-import {
-  bindSnapshotSelector, conversationSnapshot, sessionSnapshot, workspaceSnapshot,
-} from '@deepseek-ai/dsh-client-test-runtime'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-test-runtime'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
-import type {
-  ChatSnapshot, ConversationNode, RunningToolCall, SelectionTarget, ToolResultNode,
-} from '@deepseek-ai/dsh-client-ui-chat/client'
+import type { RunningToolCall, ToolResultNode } from '@deepseek-ai/dsh-client-ui-chat/client'
 import type { SessionListState } from '@deepseek-ai/dsh-api-session-controller/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
@@ -17,19 +13,14 @@ import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts
 import {
   localizeTerminalCardModel, terminalCardModel, terminalFailed,
 } from '../src/client/tool/models/terminal-card-model.ts'
-import { createChatStore } from '@deepseek-ai/dsh-client-ui-chat/src/client/stores.ts'
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
-import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-chat/src/client/details/DetailsPanel.tsx'
 import { BashRow } from '../src/client/tool/toolviews/bash-sample.tsx'
-import { renderToolDetails, toolChatSnapshot, useEmptyTrajectory } from './tool-details-render.client.tsx'
 import { en, zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
-import { zh as chatZh } from '@deepseek-ai/dsh-client-ui-chat/src/client/locale.ts'
 
 type BashRowProps = Parameters<typeof BashRow>[0]
 
 const t: GenericToolCardProps['t'] = makeTranslate(zh, commonZh)
 const enT: GenericToolCardProps['t'] = makeTranslate(en, commonEn)
-const chatT = makeTranslate(chatZh, commonZh)
 
 afterEach(cleanup)
 
@@ -531,261 +522,3 @@ describe('BashRow terminal card', () => {
     expect(view.container.querySelector('[data-error]')?.textContent).toBe('Error: command aborted')
   })
 })
-
-describe('DetailsPanel Output section', () => {
-  function mount(snapshot: ChatSnapshot, selection: SelectionTarget | null, cwd?: string) {
-    localStorage.clear()
-    const chat = createChatStore().create()
-    if (selection !== null) chat.actions.select(selection)
-    const sessions = createSnapshotStore<SessionListState>(cwd === undefined
-      ? { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined }
-      : {
-        ids: [SID],
-        byId: { [SID]: { id: SID, displayTitle: 'r', running: false, blank: false, updatedAt: 0, cwd } },
-        current: SID,
-        phase: 'ready',
-        subagentsByParent: {}, jobsBySession: {},
-        currentAddress: undefined,
-      })
-    const session = createSnapshotStore(sessionSnapshot(SID))
-    const conversation = createSnapshotStore(conversationSnapshot())
-    const workspaces = createSnapshotStore(workspaceSnapshot())
-    const attention = createSnapshotStore(new Map())
-    return render(
-      <DetailsPanel
-        renderSlot={renderToolDetails(t)}
-        SessionProvider={({ children }) => children}
-        sessionId={SID}
-        useSession={bindSnapshotSelector(session)}
-        useSessions={bindSnapshotSelector(sessions)}
-        useSessionPendingInteraction={bindSnapshotSelector(attention)}
-        useWorkspaces={bindSnapshotSelector(workspaces)}
-        useConversation={bindSnapshotSelector(conversation)}
-        useChat={bindSnapshotSelector({ getSnapshot: () => snapshot, subscribe: () => () => {} })}
-        useTrajectory={useEmptyTrajectory}
-        useInput={(() => { throw new Error('unused') })}
-        inputActions={{
-          setDraft: () => {}, addAttachments: () => true, removeAttachment: () => {},
-          pruneAttachments: () => {}, submit: () => {},
-        }}
-        useProjection={(() => undefined)}
-        useStore={bindSnapshotSelector(chat)}
-        actions={chat.actions}
-        closeDetails={vi.fn()}
-        t={chatT}
-      />,
-    )
-  }
-
-  function snapshot(over: {
-    nodes?: readonly ConversationNode[]
-    runningCalls?: readonly RunningToolCall[]
-  } = {}): ChatSnapshot {
-    const nodes = over.nodes ?? []
-    const runningCalls = over.runningCalls ?? []
-    return toolChatSnapshot(nodes, runningCalls)
-  }
-
-  const target: SelectionTarget = { turnSeq: 10, callId: 'c1', toolName: 'bash' }
-
-  // The panel never unmounts between selections, so per-call view state has to
-  // be keyed off the selected call or it leaks into the next one.
-  it('resets the card\'s expand state when the selected call changes', () => {
-    const long = Array.from({ length: 20 }, (_, i) => `row-${i}`)
-    const view = mount(snapshot({
-      nodes: [settled({ content: [{ type: 'text', text: `${long.join('\n')}\n` }] })],
-    }), target)
-    fireEvent.click(view.getByRole('button', { name: '展开其余 4 行输出' }))
-    expect(view.getByRole('button', { name: '收起输出' })).toBeTruthy()
-    // A second call, selected without unmounting the panel, starts collapsed.
-    cleanup()
-    const second = mount(snapshot({
-      nodes: [settled({
-        callId: 'c2', content: [{ type: 'text', text: `${long.join('\n')}\n` }],
-      })],
-    }), { turnSeq: 10, callId: 'c2', toolName: 'bash' })
-    expect(second.getByRole('button', { name: '展开其余 4 行输出' })).toBeTruthy()
-  })
-
-  it('renders the raw call description above the card', () => {
-    const view = mount(snapshot({
-      nodes: [settled({ call: { name: 'bash', argsRaw: shellArgs({ description: 'Terminal 3' }) } })],
-    }), target)
-    const description = view.getByText('Terminal 3')
-    const card = view.container.querySelector('[data-terminal]')
-    expect(card).not.toBeNull()
-    // Above, not below: document order is what places it as the card's heading.
-    expect(description.compareDocumentPosition(card!) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy()
-  })
-
-  it('localizes terminal_send copy in Details', () => {
-    const argsRaw = JSON.stringify({ sessionId: 'pty-3', text: '' })
-    const view = mount(snapshot({
-      nodes: [settled({
-        call: { name: 'terminal_send', argsRaw },
-        content: [{ type: 'text', text: 'ok' }],
-      })],
-    }), { ...target, toolName: 'terminal_send' })
-    expect(view.getByText('终端 pty-3')).toBeTruthy()
-    expect(view.getByText('（发送输入）')).toBeTruthy()
-  })
-
-  it('resolves the prompt cwd against the session workspace', () => {
-    const view = mount(snapshot({ nodes: [settled()] }), target, '/w/app')
-    // No workdir in the call args: the prompt label is the workspace basename.
-    expect(view.getByText('app')).toBeTruthy()
-  })
-
-  it('renders the terminal card at full height, keeping the JSON Input section', () => {
-    const long = Array.from({ length: 20 }, (_, i) => `row-${i}`)
-    const view = mount(snapshot({
-      nodes: [settled({ content: [{ type: 'text', text: `${long.join('\n')}\n` }] })],
-    }), target)
-    expect(view.getByText(/"command"/)).toBeTruthy()
-    expect(view.getByText('ls -la')).toBeTruthy()
-    // The panel takes the primitive's own default cap (16), not the row's.
-    expect(view.getByText(`… 其余 ${20 - 16} 行`)).toBeTruthy()
-    expect(view.getByText('row-0')).toBeTruthy()
-  })
-
-  it('a running terminal call shows the prompt line, not the 运行中… placeholder', () => {
-    const view = mount(snapshot({ runningCalls: [running()] }), target)
-    expect(view.getByText('ls -la')).toBeTruthy()
-    expect(view.queryByText('运行中…')).toBeNull()
-    expect(runStateOf(view.container)).toBe('ongoing')
-  })
-
-  it('a running non-terminal call keeps the 运行中… placeholder', () => {
-    const view = mount(snapshot({ runningCalls: [running({ argsRaw: shellArgs({ run_in_background: true }) })] }), target)
-    expect(view.getByText('运行中…')).toBeTruthy()
-  })
-
-  it('a non-terminal result keeps the flattened pre with its error styling', () => {
-    const view = mount(snapshot({
-      nodes: [settled({
-        isError: true,
-        content: [{ type: 'text', text: 'permission denied' }],
-      })],
-    }), target)
-    const pre = view.container.querySelector('pre[data-error]')
-    expect(pre?.textContent).toBe('permission denied')
-  })
-
-  it('a Code Dispatch child renders its terminal output in Details', () => {
-    const child = settled({ callId: 'c1', parentCallId: 'p1' })
-    const view = mount(snapshot({
-      runningCalls: [running({ callId: 'p1', subCalls: [child] })],
-    }), target)
-    expect(view.container.querySelector('[data-terminal]')?.textContent).toContain('a.ts  b.ts')
-    expect(view.getByText('ls -la')).toBeTruthy()
-    expect(runStateOf(view.container)).toBe('done')
-  })
-
-  it('a running Code Dispatch child renders its terminal prompt in Details', () => {
-    const view = mount(snapshot({
-      // The leading non-matching sub-call exercises the scan's skip.
-      runningCalls: [running({
-        callId: 'p1',
-        subCalls: [
-          running({ callId: 'other', parentCallId: 'p1' }),
-          running({ parentCallId: 'p1' }),
-        ],
-      })],
-    }), target)
-    expect(view.queryByText('运行中…')).toBeNull()
-    expect(view.getByText('ls -la')).toBeTruthy()
-    expect(runStateOf(view.container)).toBe('ongoing')
-  })
-
-  it('a window-truncated call head titles the panel by callId and drops the Input section', () => {
-    const view = mount(snapshot({
-      nodes: [settled({ call: null })],
-    }), target)
-    expect(view.getByText('c1')).toBeTruthy()
-    expect(view.queryByText('输入')).toBeNull()
-    expect(view.getByText('输出')).toBeTruthy()
-  })
-
-  it('scans past other nodes and other calls before reporting the call out of window', () => {
-    const view = mount(snapshot({
-      nodes: [
-        { kind: 'assistant', seq: 1, time: 1_000, turn: 1, step: 1, blocks: [] },
-        settled({ callId: 'elsewhere' }),
-      ],
-      runningCalls: [running({ callId: 'also-elsewhere' })],
-    }), target)
-    expect(view.getByText('该调用不在当前窗口内')).toBeTruthy()
-  })
-
-  it('no selection at all renders the guidance line and the default title', () => {
-    const view = mount(snapshot(), null)
-    expect(view.getByText('详情')).toBeTruthy()
-    expect(view.getByText('点击消息流中的工具行查看详情')).toBeTruthy()
-  })
-
-  it('a step selection without a callId renders the guidance line too', () => {
-    const view = mount(snapshot(), { turnSeq: 3, stepSeq: 1 })
-    expect(view.getByText('点击消息流中的工具行查看详情')).toBeTruthy()
-  })
-
-  it('the close button reaches closeDetails', () => {
-    localStorage.clear()
-    const chat = createChatStore().create()
-    const closeDetails = vi.fn()
-    const snap = snapshot()
-    const session = createSnapshotStore(sessionSnapshot(SID))
-    const conversation = createSnapshotStore(conversationSnapshot())
-    const workspaces = createSnapshotStore(workspaceSnapshot())
-    const attention = createSnapshotStore(new Map())
-    const view = render(
-      <DetailsPanel
-        renderSlot={renderToolDetails(t)}
-        SessionProvider={({ children }) => children}
-        sessionId={SID}
-        useSession={bindSnapshotSelector(session)}
-        useSessions={bindSnapshotSelector(createSnapshotStore<SessionListState>(
-          {
-            ids: [], byId: {}, current: undefined, phase: 'ready',
-            subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined,
-          }))}
-        useSessionPendingInteraction={bindSnapshotSelector(attention)}
-        useWorkspaces={bindSnapshotSelector(workspaces)}
-        useConversation={bindSnapshotSelector(conversation)}
-        useChat={bindSnapshotSelector({ getSnapshot: () => snap, subscribe: () => () => {} })}
-        useTrajectory={useEmptyTrajectory}
-        useInput={(() => { throw new Error('unused') })}
-        inputActions={{
-          setDraft: () => {}, addAttachments: () => true, removeAttachment: () => {},
-          pruneAttachments: () => {}, submit: () => {},
-        }}
-        useProjection={(() => undefined)}
-        useStore={bindSnapshotSelector(chat)}
-        actions={chat.actions}
-        closeDetails={closeDetails}
-        t={chatT}
-      />,
-    )
-    fireEvent.click(view.getByRole('button', { name: '关闭详情' }))
-    expect(closeDetails).toHaveBeenCalledTimes(1)
-  })
-
-  it('a non-text result block renders as JSON, and an empty result falls back to its error', () => {
-    const nonText = mount(snapshot({
-      nodes: [settled({
-        content: [{ type: 'reasoning', text: 'why' }],
-      })],
-    }), target)
-    // Scope to the Output section: the Input section's CodeBlock renders a
-    // <pre> of its own, and it comes first in document order.
-    expect(nonText.getByText('输出').closest('section')?.querySelector('pre')?.textContent)
-      .toBe('{\n  "type": "reasoning",\n  "text": "why"\n}')
-    cleanup()
-    const empty = mount(snapshot({
-      nodes: [settled({
-        content: [], isError: true,
-        error: { name: 'ToolError', code: 'interrupted' },
-      })],
-    }), target)
-    expect(empty.getByText('ToolError: interrupted')).toBeTruthy()
-  })
-})
diff --git a/packages/client/ui-tool/tests/tool-call-tree.client.spec.tsx b/packages/client/ui-tool/tests/tool-call-tree.client.spec.tsx
index 4cbd33e0d1..db048abc4b 100644
--- a/packages/client/ui-tool/tests/tool-call-tree.client.spec.tsx
+++ b/packages/client/ui-tool/tests/tool-call-tree.client.spec.tsx
@@ -56,46 +56,15 @@ function props(
 }
 
 describe('ToolCallTree', () => {
-  it('owns the root marker, generic fallback, and selected state for a window-truncated call', () => {
+  it('owns the root marker and the generic fallback for a window-truncated call', () => {
     const block = root('w1', null)
     const view = render(<ToolCallTree {...props(block, 'w1')} />)
     const row = view.container.querySelector('[data-chat-call-id="w1"]')
     expect(row?.getAttribute('data-chat-anchor-key')).toBe('call:w1')
-    expect(row?.getAttribute('data-selected')).toBe('true')
     expect(view.container.querySelector('[data-variant="others"]')).not.toBeNull()
     expect(view.getByText('w1')).toBeTruthy()
   })
 
-  it('recursively renders a selected leaf without selecting its ancestors', () => {
-    const owners: ToolCallOwnerProps[] = []
-    const leaf = {
-      ...root('parent:code:1:code:1', { name: 'read', argsRaw: '{"path":"a.ts"}' }),
-      parentCallId: 'parent:code:1',
-    }
-    const child = {
-      ...root('parent:code:1', { name: 'run_code', argsRaw: '{"code":"return 1"}' }),
-      parentCallId: 'parent',
-      subCalls: [leaf],
-    }
-    const block = {
-      ...root('parent', { name: 'run_code', argsRaw: '{"code":"return 1"}' }),
-      subCalls: [child],
-    }
-    const view = render(<ToolCallTree {...props(block, leaf.callId, undefined, owners)} />)
-    const nests = view.container.querySelectorAll('[data-subcalls]')
-    expect(nests[0]?.parentElement).toBe(view.container.querySelector('[data-chat-call-id="parent"]'))
-    expect(nests[1]?.parentElement).toBe(view.container.querySelector('[data-chat-call-id="parent:code:1"]'))
-    expect(view.container.querySelector('[data-chat-call-id="parent"]')?.hasAttribute('data-selected')).toBe(false)
-    expect(view.container.querySelector('[data-chat-call-id="parent:code:1"]')?.hasAttribute('data-selected')).toBe(false)
-    expect(view.container.querySelector('[data-chat-call-id="parent:code:1:code:1"]')?.getAttribute('data-selected')).toBe('true')
-    expect(nests).toHaveLength(2)
-    expect(owners.map(owner => [owner.callId, owner.block.parentCallId ?? null])).toEqual([
-      ['parent', null],
-      ['parent:code:1', 'parent'],
-      ['parent:code:1:code:1', 'parent:code:1'],
-    ])
-  })
-
   it('abbreviates a POSIX home path in the generic tool summary', () => {
     const block = root('w1', { name: 'read', argsRaw: '{"path":"/h/docs/a.ts"}' })
     const view = render(<ToolCallTree {...props(block, 'w1', '/h')} />)
diff --git a/packages/client/ui-tool/tests/tool-details-render.client.tsx b/packages/client/ui-tool/tests/tool-fixtures.client.ts
similarity index 71%
rename from packages/client/ui-tool/tests/tool-details-render.client.tsx
rename to packages/client/ui-tool/tests/tool-fixtures.client.ts
index 29f8ef954f..dfb73e25a5 100644
--- a/packages/client/ui-tool/tests/tool-details-render.client.tsx
+++ b/packages/client/ui-tool/tests/tool-fixtures.client.ts
@@ -1,27 +1,10 @@
-/** Test adapter for the production conversation.details.tool registration. */
+/** Shared Chat-slice and Session-event fixtures for Tool row tests. */
 import type { SessionLiveEventEntry } from '@deepseek-ai/dsh-api-session-controller/client'
 import { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import { isJsonValue, type JsonValue } from '@deepseek-ai/dsh-util-values'
 import type {
-  ChatConversationViewNode, ChatSnapshot, ConversationNode, DetailsSlotProps,
-  DetailsToolOwnerProps, RunningToolCall, ToolResultNode,
+  ChatConversationViewNode, ChatSnapshot, ConversationNode, RunningToolCall, ToolResultNode,
 } from '@deepseek-ai/dsh-client-ui-chat/client'
-import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
-import { ToolDetails } from '../src/client/tool/ToolDetails.tsx'
-
-type TrajectorySnapshot = Parameters<Parameters<DetailsSlotProps['useTrajectory']>[0]>[0]
-
-const emptyTrajectory: TrajectorySnapshot = {
-  eventNodes: [],
-  eventLocations: new Map(),
-  requests: [],
-  callSchemas: new Map(),
-  partial: null,
-  runningCalls: [],
-}
-
-/** Stable empty Trajectory source for DetailsPanel fixtures. */
-export const useEmptyTrajectory: DetailsSlotProps['useTrajectory'] = selector => selector(emptyTrajectory)
 
 function jsonFixture(value: unknown): JsonValue {
   if (!isJsonValue(value)) throw new Error('tool event fixture must be lossless JSON')
@@ -142,26 +125,3 @@ export function toolSessionEvents(nodes: readonly ToolResultNode[]): readonly Se
   }
   return entries
 }
-
-/**
- * Bind ui-tool's details renderer to the conversation slot callback shape.
- * @param t - conversation locale seat used by Tool cards.
- * @param home - optional Host account home for POSIX `~` summaries.
- * @returns a direct-test renderSlot implementation.
- */
-export function renderToolDetails(
-  t: TranslateNS<'conversation'>,
-  home?: string,
-): DetailsSlotProps['renderSlot'] {
-  return (_key, owner) => {
-    // PropsRenderSlots keeps its key generic even for this one-key share;
-    // recover the concrete owner selected by the adapter's fixed slot.
-    const details = owner as unknown as DetailsToolOwnerProps
-    return <ToolDetails
-      block={details.block}
-      cwd={details.cwd}
-      useHostInfo={selector => selector({ home, isLoopback: true })}
-      t={t}
-    />
-  }
-}
diff --git a/packages/client/ui-tool/tests/toolview-slot.client.spec.tsx b/packages/client/ui-tool/tests/toolview-slot.client.spec.tsx
index 2409fd0b9c..bb471caff9 100644
--- a/packages/client/ui-tool/tests/toolview-slot.client.spec.tsx
+++ b/packages/client/ui-tool/tests/toolview-slot.client.spec.tsx
@@ -13,7 +13,7 @@ import { LocaleRuntime } from '@deepseek-ai/dsh-client-locale/client'
 import { apply as applyConversation, inject as injectConversation } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { apply as applyTool, inject as injectTool } from '@deepseek-ai/dsh-client-ui-tool/client'
 import type { ToolCallViewProps } from '@deepseek-ai/dsh-client-ui-tool/client'
-import { toolSessionEvents } from './tool-details-render.client.tsx'
+import { toolSessionEvents } from './tool-fixtures.client.ts'
 
 const SID = 's1' as SessionId
 
@@ -42,14 +42,13 @@ const toolResult = (seq: number, callId: string, name: string, args = '{"command
 })
 
 /** Test-owned AppFrame role: declares and renders the resident conversation area. */
-type AppRootProps = PropsRenderSlots<'conversation' | 'details'>
+type AppRootProps = PropsRenderSlots<'conversation'>
 function AppRoot({ renderSlot }: AppRootProps) {
   return <>{renderSlot('conversation', {})}</>
 }
 
 const LAYOUT_CHILDREN = {
   'conversation': { kind: 'single', scope: 'session-maybe' },
-  'details': { kind: 'single', scope: 'session' },
 } as const
 
 /**
@@ -64,6 +63,8 @@ async function bench(nodes: ToolResultNode[]) {
   runtime.ctx.provide('settingsScope', { bind: () => stubSettingsScope().scope } as never)
   const layout = { openDetails: vi.fn(), closeDetails: vi.fn() }
   runtime.ctx.provide('layout', layout)
+  const sidebarRight = { openResource: vi.fn<(address: string) => void>() }
+  runtime.ctx.provide('sidebarRight', sidebarRight as never)
   runtime.ctx.provide('uiWorkspace', {
     connectWorkspace: vi.fn(async () => SID),
   } as never)
@@ -72,7 +73,7 @@ async function bench(nodes: ToolResultNode[]) {
   runtime.slots.installLocale(locale)
   await runtime.sessions.add({
     id: SID,
-    summary: { title: 'S', displayTitle: 'S' },
+    summary: { title: 'S', displayTitle: 'S', cwd: '/w' },
     events: toolSessionEvents(nodes),
     session: {
       loadOlder: vi.fn<ISession['loadOlder']>(),
@@ -83,7 +84,7 @@ async function bench(nodes: ToolResultNode[]) {
   await runtime.mount({ inject: [...injectConversation], apply: applyConversation })
   await runtime.mount({ inject: [...injectChat], apply: applyChat })
   await runtime.mount({ inject: [...injectTool], apply: applyTool })
-  return { runtime, slots: runtime.slots, layout, openWorkspacePath }
+  return { runtime, slots: runtime.slots, layout, openWorkspacePath, sidebarRight }
 }
 
 describe('keyed toolview hole through the real machinery', () => {
@@ -126,22 +127,23 @@ describe('keyed toolview hole through the real machinery', () => {
     await b.runtime.dispose()
   })
 
-  it('file-path clicks travel owner openFile → chat inject → session.openWorkspacePath', async () => {
+  it('file-path clicks travel owner openFile → chat inject → the right Sidebar', async () => {
     const b = await bench([toolResult(3, 'c1', 'read', '{"path":"src/a.ts"}')])
     const view = b.runtime.renderRoot()
     view.getByText('src/a.ts').click()
-    expect(b.layout.openDetails).not.toHaveBeenCalled()
     await vi.waitFor(() => {
-      expect(b.openWorkspacePath).toHaveBeenCalledWith({ path: 'src/a.ts' })
+      expect(b.sidebarRight.openResource).toHaveBeenCalledWith('dsh-resource://file/session/s1/src/a.ts')
     })
+    // Nothing on this path reaches the local machine any more.
+    expect(b.openWorkspacePath).not.toHaveBeenCalled()
     await b.runtime.dispose()
   })
 
-  it('bash summary clicks do not open details or host paths', async () => {
+  it('bash summary clicks open nothing at all', async () => {
     const b = await bench([toolResult(3, 'c1', 'bash')])
     const view = b.runtime.renderRoot()
     view.getByText('Build').click()
-    expect(b.layout.openDetails).not.toHaveBeenCalled()
+    expect(b.sidebarRight.openResource).not.toHaveBeenCalled()
     expect(b.openWorkspacePath).not.toHaveBeenCalled()
     await b.runtime.dispose()
   })
@@ -208,6 +210,7 @@ describe('registrant declaration injection', () => {
     })
     runtime.ctx.provide('settingsScope', { bind: () => stubSettingsScope().scope } as never)
     runtime.ctx.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
+    runtime.ctx.provide('sidebarRight', { openResource: vi.fn() } as never)
     runtime.ctx.provide('uiWorkspace', {
       connectWorkspace: vi.fn(async () => SID),
     } as never)
diff --git a/packages/client/ui-tool/tests/web-card.client.spec.tsx b/packages/client/ui-tool/tests/web-card.client.spec.tsx
index 473ac1c7a4..28f5c8c2d3 100644
--- a/packages/client/ui-tool/tests/web-card.client.spec.tsx
+++ b/packages/client/ui-tool/tests/web-card.client.spec.tsx
@@ -2,34 +2,20 @@
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
-import type {
-  ChatSnapshot, ConversationNode, RunningToolCall, SelectionTarget, ToolResultNode,
-} from '@deepseek-ai/dsh-client-ui-chat/client'
-import type { SessionListState } from '@deepseek-ai/dsh-api-session-controller/client'
-import type { SessionId } from '@deepseek-ai/dsh-session/types'
-import {
-  bindSnapshotSelector, conversationSnapshot, sessionSnapshot, workspaceSnapshot,
-} from '@deepseek-ai/dsh-client-test-runtime'
+import type { RunningToolCall, ToolResultNode } from '@deepseek-ai/dsh-client-ui-chat/client'
 import type { ToolCallOwnerProps } from '@deepseek-ai/dsh-client-ui-tool/client'
 import { IconGlobeOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import { webCardModel } from '../src/client/tool/models/web-card-model.ts'
-import { createChatStore } from '@deepseek-ai/dsh-client-ui-chat/src/client/stores.ts'
 import { GenericToolCard } from '../src/client/tool/toolviews/GenericToolCard.tsx'
-import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-chat/src/client/details/DetailsPanel.tsx'
 import { WebRow, webToolview } from '../src/client/tool/toolviews/web-row.tsx'
-import { renderToolDetails, toolChatSnapshot, useEmptyTrajectory } from './tool-details-render.client.tsx'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
-import { zh as chatZh } from '@deepseek-ai/dsh-client-ui-chat/src/client/locale.ts'
 
 afterEach(cleanup)
 
-const SID = 's1' as SessionId
 
 const t = makeTranslate(zh, commonZh)
-const chatT = makeTranslate(chatZh, commonZh)
 
 const SEARCH_ARGS = '{"queries":["deepseek harness"]}'
 const FETCH_ARGS = '{"url":"https://example.com/page"}'
@@ -215,86 +201,6 @@ describe('chat row web body', () => {
   })
 })
 
-describe('DetailsPanel web Output section', () => {
-  function mount(snapshot: ChatSnapshot, selection: SelectionTarget | null) {
-    localStorage.clear()
-    const chat = createChatStore().create()
-    if (selection !== null) chat.actions.select(selection)
-    const sessions = createSnapshotStore<SessionListState>({
-      ids: [], byId: {}, current: undefined, phase: 'ready',
-      subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined,
-    })
-    const session = createSnapshotStore(sessionSnapshot(SID))
-    const conversation = createSnapshotStore(conversationSnapshot())
-    const workspaces = createSnapshotStore(workspaceSnapshot())
-    const attention = createSnapshotStore(new Map())
-    return render(
-      <DetailsPanel
-        renderSlot={renderToolDetails(t)}
-        SessionProvider={({ children }) => children}
-        sessionId={SID}
-        useSession={bindSnapshotSelector(session)}
-        useSessions={bindSnapshotSelector(sessions)}
-        useSessionPendingInteraction={bindSnapshotSelector(attention)}
-        useWorkspaces={bindSnapshotSelector(workspaces)}
-        useConversation={bindSnapshotSelector(conversation)}
-        useChat={bindSnapshotSelector({ getSnapshot: () => snapshot, subscribe: () => () => {} })}
-        useTrajectory={useEmptyTrajectory}
-        useInput={(() => { throw new Error('unused') })}
-        inputActions={{
-          setDraft: () => {},
-          addAttachments: () => true,
-          removeAttachment: () => {},
-          pruneAttachments: () => {},
-          submit: () => {},
-        }}
-        useProjection={(() => undefined)}
-        useStore={bindSnapshotSelector(chat)}
-        actions={chat.actions}
-        closeDetails={vi.fn()}
-        t={chatT}
-      />,
-    )
-  }
-
-  function snapshot(over: {
-    nodes?: readonly ConversationNode[]
-    runningCalls?: readonly RunningToolCall[]
-  } = {}): ChatSnapshot {
-    const nodes = over.nodes ?? []
-    const runningCalls = over.runningCalls ?? []
-    return toolChatSnapshot(nodes, runningCalls)
-  }
-
-  it('renders the search card at full source allowance', () => {
-    const view = mount(snapshot({ nodes: [settledSearch()] }), { turnSeq: 10, callId: 'c1', toolName: 'web_search' })
-    expect(view.getByText('Titled')).toBeTruthy()
-    expect(view.getByText('excerpt')).toBeTruthy()
-    // The Input JSON section survives beside it.
-    expect(view.getByText(/"queries"/)).toBeTruthy()
-  })
-
-  it('renders the fetch card and keeps the fetched body below it', () => {
-    const view = mount(snapshot({ nodes: [settledFetch()] }), { turnSeq: 11, callId: 'c2', toolName: 'web_fetch' })
-    const card = view.container.querySelector('[data-web="fetch"]')
-    expect(card?.querySelector('a')?.getAttribute('href')).toBe('https://example.com/page')
-    expect(view.getByText('HTTP 200')).toBeTruthy()
-    // The card is a summary (URL + status only); the panel is the single-call
-    // reading surface, so the fetched body still renders below the card.
-    const output = view.getByText('输出').closest('section')
-    expect(output?.querySelector('pre')?.textContent).toContain('fetch body')
-  })
-
-  it('a non-web result keeps the flattened pre form', () => {
-    const view = mount(snapshot({
-      nodes: [settledSearch({ meta: undefined })],
-    }), { turnSeq: 10, callId: 'c1', toolName: 'web_search' })
-    expect(view.container.querySelector('[data-web]')).toBeNull()
-    const output = view.getByText('输出').closest('section')
-    expect(output?.querySelector('pre')?.textContent).toContain('search text')
-  })
-})
-
 describe('web toolview registration', () => {
   it('registers one WebRow under both web_search and web_fetch', () => {
     const registered: { key: string; locale: unknown; component: unknown }[] = []
diff --git a/packages/client/ui-trajectory/tests/views.client.spec.tsx b/packages/client/ui-trajectory/tests/views.client.spec.tsx
index e8288cb0fa..91ba0468f1 100644
--- a/packages/client/ui-trajectory/tests/views.client.spec.tsx
+++ b/packages/client/ui-trajectory/tests/views.client.spec.tsx
@@ -7,6 +7,7 @@
  * event ledger with its timing overview, and fiber disposal removes the tab.
  * Timeline projection and inclusive focus edge cases ride along.
  */
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { createElement, type ComponentProps, type FC, type ReactNode } from 'react'
@@ -52,12 +53,16 @@ import type { TrajectorySnapshot } from '../src/client/trajectory-contract.ts'
 import { deriveTrajectoryTimeline } from '../src/client/timeline.ts'
 import { t as tTrajectory, tZh } from './locale.client.ts'
 
+// Every session-scope fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 function TrajectoryTimeline(
   props: Omit<ComponentProps<typeof LocalizedTrajectoryTimeline>, 't'>,
 ) {
   return <LocalizedTrajectoryTimeline {...props} t={tTrajectory} />
 }
 
+
 const SID = 's1' as SessionId
 const tConversation: ConversationSessionHeaderProps['t'] =
   key => (conversationZh as Record<string, string>)[key] ?? key
@@ -219,6 +224,7 @@ function standaloneProps(
     sessionId: SID,
     useChat: bindSnapshotSelector(createSnapshotStore(EMPTY_CHAT_SNAPSHOT)),
     useSessions: emptySessions(),
+    useResource,
     useSessionPendingInteraction: bindSnapshotSelector(
       createSnapshotStore<SessionPendingInteractionSnapshot>(new Map()),
     ),
@@ -345,6 +351,7 @@ function mount(fixture: Awaited<ReturnType<typeof bench>>) {
     useConversation,
     useConversationViews,
     useSessions,
+    useResource,
     useSessionPendingInteraction,
     useWorkspaces,
     useProjection,
diff --git a/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx b/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx
index e303ae5aa8..f3cc685d4d 100644
--- a/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx
+++ b/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx
@@ -1,4 +1,5 @@
 // @vitest-environment jsdom
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
@@ -11,8 +12,12 @@ import { en, zh } from '../src/client/locales.ts'
 import { en as commonEn } from '@deepseek-ai/dsh-client-locale/src/locales/en.ts'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 
+// Every session-scope fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 afterEach(cleanup)
 
+
 const SID = 's1' as SessionId
 
 const seatOver = (dict: Record<string, string>, common: Record<string, string>): QuestionComposerProps['t'] =>
@@ -110,6 +115,7 @@ const kit: Omit<QuestionComposerProps, 'matched'> = {
   pendingInteraction: undefined,
   useSession: selector => selector(sessionState),
   useSessions: selector => selector(sessionList),
+  useResource,
   useSessionPendingInteraction: selector => selector(attentionState),
   useWorkspaces: selector => selector(workspaceState),
   useConversation: selector => selector(conversationState),
diff --git a/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx b/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx
index 42313fc802..80d7d9307c 100644
--- a/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx
+++ b/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx
@@ -1,4 +1,5 @@
 // @vitest-environment jsdom
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { useSyncExternalStore } from 'react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render, screen } from '@testing-library/react'
@@ -10,8 +11,12 @@ import { en, zh } from '../src/client/locales.ts'
 import { en as commonEn } from '@deepseek-ai/dsh-client-locale/src/locales/en.ts'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 
+// Every session-scope fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 afterEach(cleanup)
 
+
 const SID = 's1' as SessionId
 
 const seatOver = (dict: Record<string, string>, common: Record<string, string>): QuestionComposerProps['t'] =>
@@ -109,6 +114,7 @@ const kitBase: Omit<QuestionComposerProps, 'matched' | 'useStore' | 'actions'> =
   pendingInteraction: undefined,
   useSession: selector => selector(sessionState),
   useSessions: selector => selector(sessionList),
+  useResource,
   useSessionPendingInteraction: selector => selector(attentionState),
   useWorkspaces: selector => selector(workspaceState),
   useConversation: selector => selector(conversationState),
diff --git a/packages/client/ui-workflow-run/tests/workflow-run.client.spec.tsx b/packages/client/ui-workflow-run/tests/workflow-run.client.spec.tsx
index 123d08ef84..e6b38074a5 100644
--- a/packages/client/ui-workflow-run/tests/workflow-run.client.spec.tsx
+++ b/packages/client/ui-workflow-run/tests/workflow-run.client.spec.tsx
@@ -1,4 +1,5 @@
 // @vitest-environment jsdom
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { Context, Service } from '@deepseek-ai/cordis'
 import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -31,8 +32,12 @@ import {
 import { apply as applyNode } from '../src/index.ts'
 import type {} from '../src/client/index.ts'
 
+// Every session-scope fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 afterEach(cleanup)
 
+
 const PARENT_ID = 'parent' as SessionId
 const CHILD_ID = 'child-1' as SessionId
 const SECOND_ID = 'child-2' as SessionId
@@ -309,6 +314,7 @@ function panelProps(data: WorkflowRunChatData, sessions = listState(), openSessi
     node: node(data),
     sessionId: PARENT_ID,
     useSessions: selector => selector(sessions),
+    useResource,
     useSessionPendingInteraction: selector => selector(panelAttention),
     useSession: selector => selector(panelSession),
     useProjection: () => undefined,
diff --git a/packages/client/ui-workspace/tests/workspace-browser.client.spec.tsx b/packages/client/ui-workspace/tests/workspace-browser.client.spec.tsx
index 99437341f3..6958423e5f 100644
--- a/packages/client/ui-workspace/tests/workspace-browser.client.spec.tsx
+++ b/packages/client/ui-workspace/tests/workspace-browser.client.spec.tsx
@@ -1,4 +1,5 @@
 // @vitest-environment jsdom
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, createEvent, fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { bindSnapshotSelector, makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
@@ -15,6 +16,9 @@ import { UNGROUPED_KEY } from '../src/client/tree.ts'
 import { WorkspaceBrowser } from '../src/client/rows/WorkspaceBrowser.tsx'
 import { zh } from '../src/client/locales.ts'
 
+// Every fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 afterEach(cleanup)
 const scrollIntoView = vi.fn()
 beforeEach(() => {
@@ -74,6 +78,7 @@ function mount(overrides: Partial<WorkspaceBrowserProps> = {}) {
     expandSidebar: vi.fn(),
     useSessions: hook(sessionState([])),
     useSessionPendingInteraction: hook(noPendingInteraction),
+    useResource,
     useWorkspaces: hook(workspaceState([])),
     useStore: bindSnapshotSelector(store),
     actions: store.actions,
diff --git a/packages/client/ui-workspace/tests/workspace-picker.client.spec.tsx b/packages/client/ui-workspace/tests/workspace-picker.client.spec.tsx
index 1c76b8b25f..b2ac4a6d1a 100644
--- a/packages/client/ui-workspace/tests/workspace-picker.client.spec.tsx
+++ b/packages/client/ui-workspace/tests/workspace-picker.client.spec.tsx
@@ -1,4 +1,5 @@
 // @vitest-environment jsdom
+import type { GlobalStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
 import type { SessionListState } from '@deepseek-ai/dsh-api-session-controller/client'
@@ -13,6 +14,9 @@ import type { DirectoryFlowOwnerProps, WorkspacePickerProps } from '../src/clien
 import { WorkspacePicker } from '../src/client/WorkspacePicker.tsx'
 import { zh } from '../src/client/locales.ts'
 
+// Every fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
+const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
+
 afterEach(cleanup)
 
 // The seat's key domain is workspace ∪ common; the stub mirrors the real
@@ -94,6 +98,7 @@ function mount(
       anchorRef={anchorRef}
       useSessions={hook(sessions)}
       useSessionPendingInteraction={hook(noPendingInteraction)}
+      useResource={useResource}
       useWorkspaces={hook(workspaceState(nextItems))}
       onPick={onPick}
       onClose={onClose}
@@ -215,6 +220,7 @@ describe('WorkspacePicker', () => {
       <WorkspacePicker
         open useSessions={hook(sessions)} useWorkspaces={hook(workspaceState([workspace('alpha', 'Alpha')]))}
         useSessionPendingInteraction={hook(noPendingInteraction)}
+        useResource={useResource}
         onPick={vi.fn()} onClose={vi.fn()} createWorkspace={vi.fn()}
         useDirectoryFlow={occupancySource().useDirectoryFlow} renderSlot={renderSlot} t={t}
       />,
@@ -231,6 +237,7 @@ describe('WorkspacePicker', () => {
       <WorkspacePicker
         open anchorRef={anchor()} useSessions={hook(sessions)} useWorkspaces={hook(state)}
         useSessionPendingInteraction={hook(noPendingInteraction)}
+        useResource={useResource}
         onPick={vi.fn()} onClose={vi.fn()} createWorkspace={vi.fn()}
         useDirectoryFlow={occupancySource().useDirectoryFlow} renderSlot={renderSlot} t={t}
       />,
diff --git a/packages/client/web/package.json b/packages/client/web/package.json
index 320151d47f..d2c132a525 100644
--- a/packages/client/web/package.json
+++ b/packages/client/web/package.json
@@ -26,6 +26,7 @@
     "@deepseek-ai/cordis-plugin-loader": "workspace:^",
     "@deepseek-ai/dsh-client-modules": "workspace:^",
     "@deepseek-ai/dsh-client-store": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-dockkit": "workspace:^",
     "@deepseek-ai/dsh-client-ui-renderer": "workspace:^",
     "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
diff --git a/packages/client/web/src/platform.ts b/packages/client/web/src/platform.ts
index 197776cb6d..2549966986 100644
--- a/packages/client/web/src/platform.ts
+++ b/packages/client/web/src/platform.ts
@@ -10,6 +10,7 @@ export const PLATFORM_MODULES = [
   '@deepseek-ai/dsh-client-store',
   '@deepseek-ai/dsh-client-ui-slots',
   '@deepseek-ai/dsh-client-ui-primitives',
+  '@deepseek-ai/dsh-client-ui-dockkit',
 ] as const
 
 /** Client-bundle specifiers whose factories the parser preloads before the shell starts. */
diff --git a/packages/client/web/src/seed.ts b/packages/client/web/src/seed.ts
index 1f213641ca..d41f338d42 100644
--- a/packages/client/web/src/seed.ts
+++ b/packages/client/web/src/seed.ts
@@ -14,6 +14,7 @@ import * as Cordis from '@deepseek-ai/cordis'
 import * as ClientStore from '@deepseek-ai/dsh-client-store'
 import * as UiSlots from '@deepseek-ai/dsh-client-ui-slots'
 import * as UiPrimitives from '@deepseek-ai/dsh-client-ui-primitives'
+import * as UiDockkit from '@deepseek-ai/dsh-client-ui-dockkit'
 import type { PlatformModule } from './platform.ts'
 
 /**
@@ -33,5 +34,6 @@ export function getStaticModules(): Record<string, unknown> {
     '@deepseek-ai/dsh-client-store': ClientStore,
     '@deepseek-ai/dsh-client-ui-slots': UiSlots,
     '@deepseek-ai/dsh-client-ui-primitives': UiPrimitives,
+    '@deepseek-ai/dsh-client-ui-dockkit': UiDockkit,
   } satisfies Record<PlatformModule, unknown>
 }
diff --git a/packages/client/web/tsconfig.json b/packages/client/web/tsconfig.json
index d0a5a37049..03d273ce53 100644
--- a/packages/client/web/tsconfig.json
+++ b/packages/client/web/tsconfig.json
@@ -26,6 +26,9 @@
     {
       "path": "../ui-primitives"
     },
+    {
+      "path": "../ui-dockkit"
+    },
     {
       "path": "../ui-renderer"
     }
diff --git a/packages/context/agent-instructions/README.i18n.yaml b/packages/context/agent-instructions/README.i18n.yaml
index 481606e8b5..4f3b7417ea 100644
--- a/packages/context/agent-instructions/README.i18n.yaml
+++ b/packages/context/agent-instructions/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/context/agent-instructions/README.md
-README.md: d69a989a455512177798446e4a3e07b95b5f44d1
-README.zh.md: 96a456bd576cacb06382de4b8e34db4b5976327f
+README.md: ffde23b2144109d69da6070225999936e03bdd91
+README.zh.md: 0d1313f2d72bb80f73e633ed75b6b7b5b1f82062
diff --git a/packages/context/agent-instructions/README.md b/packages/context/agent-instructions/README.md
index d69a989a45..ffde23b214 100644
--- a/packages/context/agent-instructions/README.md
+++ b/packages/context/agent-instructions/README.md
@@ -35,6 +35,8 @@ The first request includes one durable baseline message with the user-global `$D
 
 The defaults suit a typical checkout: `.git` marks the project root, `AGENTS.md` and `CLAUDE.md` are the base candidates, and `AGENTS.local.md` and `CLAUDE.local.md` are additive local overlays. Only `maxBytes` is required — it caps the complete rendered baseline so each deployment chooses its prompt budget explicitly.
 
+Root discovery climbs only when a marker probe confirms that the marker is absent. A permission or I/O failure stops discovery and surfaces the host or filesystem-provider error instead of selecting an ancestor project. The [root-marker metadata decision](../../../.agents/notes/implemented/bug-fix/2026-09-03-root-marker-metadata-failures.md) records why discovery fails instead of substituting another root.
+
 ```yaml
 - name: '@deepseek-ai/dsh-agent-instructions'
   config:
diff --git a/packages/context/agent-instructions/README.zh.md b/packages/context/agent-instructions/README.zh.md
index 96a456bd57..0d1313f2d7 100644
--- a/packages/context/agent-instructions/README.zh.md
+++ b/packages/context/agent-instructions/README.zh.md
@@ -35,6 +35,8 @@ kind: "package-reference"
 
 默认设置适合典型检出：`.git` 标记项目根目录，`AGENTS.md` 与 `CLAUDE.md` 是基础候选，`AGENTS.local.md` 与 `CLAUDE.local.md` 是叠加的本地 overlay。只有 `maxBytes` 必填——它限制完整渲染后的基线，让每个部署显式选择自己的提示词预算。
 
+只有确认项目根标记不存在时，项目根发现才会继续上溯。权限或 I/O 失败会停止发现，并抛出宿主或文件系统提供方的原始错误，而不会选择祖先项目。[根标记元数据决策](../../../.agents/notes/implemented/bug-fix/2026-09-03-root-marker-metadata-failures.zh.md)说明发现为何必须失败，而不能替换为其他根目录。
+
 ```yaml
 - name: '@deepseek-ai/dsh-agent-instructions'
   config:
diff --git a/packages/context/agent-instructions/src/files.ts b/packages/context/agent-instructions/src/files.ts
index 01492e3e91..b91cab12a1 100644
--- a/packages/context/agent-instructions/src/files.ts
+++ b/packages/context/agent-instructions/src/files.ts
@@ -95,6 +95,10 @@ function isMissingPathError(error: unknown): boolean {
   return error instanceof Error && 'code' in error && (error.code === 'ENOENT' || error.code === 'ENOTDIR')
 }
 
+function isMissingProviderPathError(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'FS_NOT_FOUND'
+}
+
 async function nodeStatFile(path: string, signal?: AbortSignal): Promise<StatFileProbe> {
   try {
     signal?.throwIfAborted()
@@ -147,11 +151,10 @@ async function existsAsMarker(path: string, fileSystem?: FileSystem, signal?: Ab
     try {
       const target = await fileSystem.resolve(path, signalOptions(signal))
       return await fileSystem.stat(target, signal) !== undefined
-    } catch {
+    } catch (error: unknown) {
       signal?.throwIfAborted()
-      // TODO(root-marker-unavailable): preserve provider failure separately from
-      // absence and stop discovery; continuing upward can cross into an ancestor project.
-      return false
+      if (isMissingProviderPathError(error)) return false
+      throw error
     }
   }
   try {
@@ -159,9 +162,10 @@ async function existsAsMarker(path: string, fileSystem?: FileSystem, signal?: Ab
     await stat(path)
     signal?.throwIfAborted()
     return true
-  } catch {
+  } catch (error: unknown) {
     signal?.throwIfAborted()
-    return false
+    if (isMissingPathError(error)) return false
+    throw error
   }
 }
 
@@ -172,6 +176,7 @@ async function existsAsMarker(path: string, fileSystem?: FileSystem, signal?: Ab
  * @param fileSystem - optional provider used instead of host filesystem probes.
  * @param signal - cancellation for provider and host probes.
  * @returns the discovered project root, or `cwd` when no marker exists.
+ * @throws the original marker metadata error or cancellation reason when a probe is unavailable.
  */
 export async function findProjectRoot(
   cwd: string,
@@ -314,6 +319,8 @@ async function discoverInstructionFiles(
  * duplicates are collapsed later, once content is read.
  * @param options - cwd, home, root marker, and candidate configuration.
  * @returns path-deduplicated instruction candidates in model precedence order.
+ * @throws the original root-marker metadata error or cancellation reason when
+ * discovery cannot identify the project root.
  */
 export async function discoverBaselineInstructionFiles(options: DiscoverOptions): Promise<InstructionFile[]> {
   return (await discoverInstructionFiles(options)).map(({ absolutePath, displayPath }) => ({ absolutePath, displayPath }))
@@ -388,6 +395,8 @@ export function dedupInstructionFilesByDirectory(files: LoadedInstructionFile[])
  * @param options - discovery, source-size, byte-budget, and cancellation configuration.
  * @param fileSystem - optional provider used instead of host filesystem reads.
  * @returns rendered baseline context, or undefined when nothing can be loaded.
+ * @throws the original root-marker metadata error or cancellation reason when
+ * discovery cannot identify the project root.
  */
 export async function loadBaselineInstructions(
   options: LoadOptions,
diff --git a/packages/context/agent-instructions/tests/agent-instructions.spec.ts b/packages/context/agent-instructions/tests/agent-instructions.spec.ts
index 7e3586faeb..90a38fc62d 100644
--- a/packages/context/agent-instructions/tests/agent-instructions.spec.ts
+++ b/packages/context/agent-instructions/tests/agent-instructions.spec.ts
@@ -77,6 +77,7 @@ async function write(path: string, content: string): Promise<void> {
 
 class RecordingFileSystem extends FileSystem {
   entries = new Map<string, { type: FsInfo['type']; content?: string; version?: FsVersion }>()
+  missingOnResolve = new Set<string>()
   throwOnStat = new Set<string>()
   throwOnRead = new Set<string>()
   omitSizes = new Set<string>()
@@ -90,6 +91,9 @@ class RecordingFileSystem extends FileSystem {
     // resolve(), not join(): entries are seeded with host join() keys, and on
     // Windows a joined '/'-rooted prefix would not match a resolved drive path.
     const absolute = resolve(opts?.cwd ?? '/', path)
+    if (this.missingOnResolve.has(absolute)) {
+      throw Object.assign(new Error(`not found: ${absolute}`), { code: 'FS_NOT_FOUND' })
+    }
     return { targetKey: FsTargetKey(absolute), displayPath: absolute }
   }
 
@@ -140,6 +144,10 @@ class RecordingFileSystem extends FileSystem {
     throw new Error('not needed in agent-instructions tests')
   }
 
+  override async readByteRange(_target: FsTarget, _range: { offset: number; length: number }, _signal?: AbortSignal): Promise<Uint8Array> {
+    throw new Error('not needed in agent-instructions tests')
+  }
+
   override async streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>> {
     if (signal !== undefined) this.signals.push(signal)
     signal?.throwIfAborted()
@@ -2069,6 +2077,30 @@ describe('workspace context request injection', () => {
     }
   })
 
+  it('continues provider root discovery when a marker is confirmed absent', async () => {
+    const root = join(await tempRepo(), 'virtual-repo')
+    const cwd = join(root, 'pkg')
+    const home = join(await tempRepo(), 'virtual-home')
+    const ctx = new Context()
+    try {
+      await ctx.plugin(RecordingFileSystem)
+      const fs = ctx.fs as RecordingFileSystem
+      fs.missingOnResolve.add(join(cwd, '.git'))
+      fs.entries.set(join(root, '.git'), { type: 'directory' })
+      fs.entries.set(join(root, 'AGENTS.md'), { type: 'file', content: 'provider parent rule' })
+      await mountWorkspaceContextPlugin(ctx, { dshHome: home, maxBytes: 65536 })
+      const agent = await stubAgent(cwd)
+
+      await composeBaselinePrefix(ctx, agent)
+
+      expect(derivedText(agent)).toContain('provider parent rule')
+    } finally {
+      await ctx.fiber.dispose()
+      await rm(dirname(root), { recursive: true, force: true })
+      await rm(dirname(home), { recursive: true, force: true })
+    }
+  })
+
   it('keeps the direct provider API usable without an operation signal', async () => {
     const root = resolve('/virtual/no-signal-repo')
     const home = resolve('/virtual/no-signal-home')
@@ -2287,23 +2319,24 @@ describe('workspace context request injection', () => {
     }
   })
 
-  it('treats ctx.fs marker lookup failures as absent root markers', async () => {
+  it('surfaces ctx.fs marker lookup failures instead of crossing into an ancestor project', async () => {
     const root = await tempRepo()
+    const cwd = join(root, 'pkg')
     const home = await tempRepo()
     try {
-      await mkdir(join(root, '.git'), { recursive: true })
-      await write(join(root, 'AGENTS.md'), 'repo rule')
       const ctx = new Context()
       await ctx.plugin(RecordingFileSystem)
       const fs = ctx.fs as RecordingFileSystem
-      fs.throwOnStat.add(join(root, '.git'))
-      fs.entries.set(join(root, 'AGENTS.md'), { type: 'file', content: 'repo rule' })
+      fs.throwOnStat.add(join(cwd, '.git'))
+      fs.entries.set(join(root, '.git'), { type: 'directory' })
+      fs.entries.set(join(root, 'AGENTS.md'), { type: 'file', content: 'ancestor rule must not load' })
       await mountWorkspaceContextPlugin(ctx, { dshHome: home, maxBytes: 65536 })
-      const agent = await stubAgent(root)
+      const agent = await stubAgent(cwd)
 
-      await composeBaselinePrefix(ctx, agent)
+      await expect(composeBaselinePrefix(ctx, agent))
+        .rejects.toThrow(`stat failed: ${join(cwd, '.git')}`)
 
-      expect(derivedText(agent)).toContain('repo rule')
+      expectNoDerivedMessages(agent)
     } finally {
       await rm(root, { recursive: true, force: true })
       await rm(home, { recursive: true, force: true })
@@ -2536,6 +2569,42 @@ describe('workspace context request injection', () => {
       await rm(home, { recursive: true, force: true })
     }
   })
+
+  it('surfaces host marker metadata failures instead of crossing into an ancestor project', async () => {
+    const root = await tempRepo()
+    const home = await tempRepo()
+    try {
+      const cwd = join(root, 'pkg')
+      const markerPath = join(cwd, '.git')
+      const failure = Object.assign(new Error(`permission denied: ${markerPath}`), {
+        code: 'EACCES',
+        path: markerPath,
+      })
+      await mkdir(join(root, '.git'), { recursive: true })
+      await write(join(root, 'AGENTS.md'), 'ancestor rule must not load')
+      await mkdir(cwd, { recursive: true })
+      vi.resetModules()
+      vi.doMock('node:fs/promises', async (importOriginal) => {
+        const actual = await importOriginal<typeof import('node:fs/promises')>()
+        return {
+          ...actual,
+          stat: async (path: string) => {
+            if (path === markerPath) throw failure
+            return actual.stat(path)
+          },
+        }
+      })
+      const isolated = await import('@deepseek-ai/dsh-agent-instructions')
+
+      await expect(isolated.loadBaselineInstructions({ cwd, dshHome: home, maxBytes: 65536 }))
+        .rejects.toBe(failure)
+    } finally {
+      vi.doUnmock('node:fs/promises')
+      vi.resetModules()
+      await rm(root, { recursive: true, force: true })
+      await rm(home, { recursive: true, force: true })
+    }
+  })
 })
 
 describe('dynamic nested workspace context injection', () => {
diff --git a/packages/e2b/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
index dd50944ac8..f14ed73cd9 100644
--- a/packages/e2b/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/e2b/fs-e2b/README.md
-README.md: 3219bd55425da17781c84b69564bb71adccaf077
-README.zh.md: 3bd31796c4d49af72c1795da1feea4efb9407318
+README.md: 5a6106fb0a87fcab515207b38b4ae3d9aab7c5d6
+README.zh.md: 0d2d796d69f3c934e9f518b9ce4c2c0cdb356241
diff --git a/packages/e2b/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
index 3219bd5542..5a6106fb0a 100644
--- a/packages/e2b/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -44,7 +44,7 @@ Mounting it does not copy or mirror your local files — the sandbox's working d
 
 ### Reading files
 
-The agent can read a file's whole contents, stream large files, or read raw bytes up to a size cap. Binary files and files that are not valid UTF-8 text are refused with a clear message instead of being garbled; reads past the size cap fail with a message naming the limit.
+The agent can read a file's whole contents, stream large files, or read raw bytes up to a size cap or as one byte window. Binary files and files that are not valid UTF-8 text are refused with a clear message instead of being garbled; reads past the size cap fail with a message naming the limit.
 
 ### Writing and editing files
 
diff --git a/packages/e2b/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
index 3bd31796c4..0d2d796d69 100644
--- a/packages/e2b/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -44,7 +44,7 @@ kind: "package-reference"
 
 ### 读取文件
 
-agent 可以读取文件的完整内容、流式读取大文件，或在大小上限内读取原始字节。二进制文件与不是有效 UTF-8 文本的文件会被明确拒绝而不是乱码显示；超过大小上限的读取会以指明上限的消息失败。
+agent 可以读取文件的完整内容、流式读取大文件，或在大小上限内或按字节窗口读取原始字节。二进制文件与不是有效 UTF-8 文本的文件会被明确拒绝而不是乱码显示；超过大小上限的读取会以指明上限的消息失败。
 
 ### 写入与编辑文件
 
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index f78a382495..2d879adb0c 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -292,6 +292,52 @@ export class E2BFileSystem extends FileSystem {
     return whole
   }
 
+  override async readByteRange(target: FsTarget, range: { offset: number; length: number }, signal?: AbortSignal): Promise<Uint8Array> {
+    const sandbox = await this.ctx.e2b.getSandbox()
+    await this.requireRegular(target, signal)
+    if (range.length === 0) return new Uint8Array(0)
+    // The SDK streams only from the file's start: skip to `offset`, keep
+    // `length` bytes, and cancel the stream there, so no more than the window
+    // beyond the skipped prefix is ever transferred.
+    const stream = await openReadStream(sandbox, target, signal)
+    const reader = stream.getReader()
+    const window = new Uint8Array(range.length)
+    const end = range.offset + range.length
+    let position = 0
+    let filled = 0
+    let drained = false
+    try {
+      while (filled < range.length) {
+        assertNotAborted(signal, 'read')
+        const next = await reader.read()
+        if (next.done) {
+          drained = true
+          break
+        }
+        const from = Math.max(range.offset, position)
+        const to = Math.min(end, position + next.value.byteLength)
+        if (to > from) {
+          window.set(next.value.subarray(from - position, to - position), filled)
+          filled += to - from
+        }
+        position += next.value.byteLength
+      }
+    } catch (error: unknown) {
+      throw mapError(error, 'read', target.displayPath, signal)
+    } finally {
+      if (!drained) {
+        try {
+          await reader.cancel()
+        } catch (_streamCancellationFailure) {
+          // The window is complete or the read already failed; a cancellation
+          // failure on the abandoned remote stream adds nothing actionable.
+        }
+      }
+      reader.releaseLock()
+    }
+    return filled === range.length ? window : window.subarray(0, filled)
+  }
+
   override async streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>> {
     const sandbox = await this.ctx.e2b.getSandbox()
     await this.requireRegular(target, signal)
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 516e3e6e39..09b0a8e26b 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -171,6 +171,8 @@ class FakeRemote {
           start: (controller) => {
             for (const chunk of chunks) controller.enqueue(chunk)
             if (!this.streamKeepOpen) controller.close()
+            // SDK fidelity: an abort of the request signal fails the open stream.
+            options.signal?.addEventListener('abort', () => { controller.error(new DOMException('aborted', 'AbortError')) }, { once: true })
           },
           cancel: () => { this.streamCancel() },
         })
@@ -508,6 +510,57 @@ describe('E2BFileSystem identity, metadata, and reads', () => {
     expect((await fs.readBytes(await fs.resolve('empty.bin'), undefined, 4)).byteLength).toBe(0)
   })
 
+  it('readByteRange skips to the offset, keeps the window, and cancels the stream there', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/ramp.bin', [1, 2, 3, 4, 5, 6, 7, 8, 9])
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('ramp.bin')
+    remote.streamChunks = [bytes([1, 2, 3]), bytes([4, 5, 6]), bytes([7, 8, 9])]
+    remote.streamKeepOpen = true
+    expect(Array.from(await fs.readByteRange(target, { offset: 4, length: 3 }))).toEqual([5, 6, 7])
+    expect(remote.reads).toEqual([{ path: '/workspace/ramp.bin', format: 'stream' }])
+    expect(remote.streamCancel).toHaveBeenCalledOnce()
+  })
+
+  it('readByteRange shortens at the end, empties past it, and skips the read for length 0', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/ramp.bin', [1, 2, 3, 4, 5, 6, 7, 8, 9])
+    remote.dir('/workspace/directory')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('ramp.bin')
+    remote.streamChunks = [bytes([1, 2, 3]), bytes([4, 5, 6]), bytes([7, 8, 9])]
+    expect(Array.from(await fs.readByteRange(target, { offset: 7, length: 10 }))).toEqual([8, 9])
+    expect(remote.streamCancel).not.toHaveBeenCalled()
+    expect((await fs.readByteRange(target, { offset: 9, length: 2 })).byteLength).toBe(0)
+    remote.reads.length = 0
+    expect((await fs.readByteRange(target, { offset: 0, length: 0 })).byteLength).toBe(0)
+    expect(remote.reads).toEqual([])
+    await expectCode(fs.readByteRange(await fs.resolve('missing'), { offset: 0, length: 1 }), 'FS_NOT_FOUND')
+    await expectCode(fs.readByteRange(await fs.resolve('directory'), { offset: 0, length: 1 }), 'FS_NOT_REGULAR_FILE')
+  })
+
+  it('readByteRange maps a failing open, an abort mid-stream, and tolerates a failing cancel', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/ramp.bin', [1, 2, 3, 4])
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('ramp.bin')
+    remote.nextReadError = new DOMException('aborted', 'AbortError')
+    await expectCode(fs.readByteRange(target, { offset: 0, length: 2 }), 'FS_ABORTED')
+
+    // The window wants more than the one chunk delivered; the abort fails the open stream.
+    remote.streamChunks = [bytes([1])]
+    remote.streamKeepOpen = true
+    const controller = new AbortController()
+    const pending = fs.readByteRange(target, { offset: 0, length: 4 }, controller.signal)
+    await new Promise<void>((resolve) => { setTimeout(resolve, 0) })
+    controller.abort()
+    await expectCode(pending, 'FS_ABORTED')
+
+    remote.streamChunks = [bytes([1, 2, 3, 4])]
+    remote.streamCancel.mockRejectedValueOnce(new Error('cancel failed'))
+    expect(Array.from(await fs.readByteRange(target, { offset: 1, length: 2 }))).toEqual([2, 3])
+  })
+
   it('honors aborts before and during remote reads', async () => {
     const remote = new FakeRemote()
     remote.file('/workspace/a', 'a')
diff --git a/packages/extensions/cordis-client-runner/src/client/api-catalog.ts b/packages/extensions/cordis-client-runner/src/client/api-catalog.ts
index 4fc5def3e6..47bf4af64a 100644
--- a/packages/extensions/cordis-client-runner/src/client/api-catalog.ts
+++ b/packages/extensions/cordis-client-runner/src/client/api-catalog.ts
@@ -92,13 +92,13 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         parameters: [],
       },
       {
-        signature: 'openDetails(): void',
-        description: 'Open the details panel (no-op when already open).',
-        parameters: [],
+        signature: 'openRightbar(track: boolean, fullscreen: boolean): void',
+        description: 'Report the right panel\'s presentation without changing its expanded state.',
+        parameters: [{ name: 'track', description: 'whether the normal panel width reserves a grid track, including beneath a fullscreen overlay.' }, { name: 'fullscreen', description: 'whether the panel covers the frame and hides its outer resize handle; independent of the underlying grid track.' }],
       },
       {
-        signature: 'closeDetails(): void',
-        description: 'Close the details panel.',
+        signature: 'closeRightbar(): void',
+        description: 'Report the right panel as hidden: no track, no handle.',
         parameters: [],
       },
     ],
diff --git a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
index 4fa57cbf0e..eff4345ddf 100644
--- a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
+++ b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
@@ -91,6 +91,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -125,6 +126,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -182,6 +184,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
       'MessageId',
     ],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -204,7 +207,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.chat.assistant-actions\', () => ctx.slots.register(\n      { name: \'conversation.chat.assistant-actions\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:227',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:212',
   },
   {
     key: 'conversation.chat.commandview',
@@ -229,6 +232,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
       'CompactionSummaryNode',
     ],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -249,7 +253,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.chat.commandview\', () => ctx.slots.register(\n      { name: \'conversation.chat.commandview\', key: \'<one key the owner dispatches>\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:215',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:200',
   },
   {
     key: 'conversation.chat.node',
@@ -266,16 +270,18 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
       },
     ],
     ownerProps: [
-      '/** Stable owner currency delivered to a keyed Chat renderer. */\nexport interface ChatNodeOwnerProps {\n  selectedCallId?: ToolCallId | undefined\n  cwd?: string | undefined\n  openFile: (path: string) => void\n  inspectCall: (callId: ToolCallId) => void\n  forkAt: (seq: number) => void\n  /**\n   * Session-authorized image loader, down-threaded from the Chat view so a\n   * chat-node renderer can render the attachment presentation slot directly\n   * with only the durable references plus this loader, instead of receiving a\n   * rendering closure.\n   */\n  loadImage: MessageImageLoader\n  renderMessageImages: RenderMessageImages\n  fileMentions: (owner: TurnTailOwnerProps) => MarkdownFileMentions | undefined\n  /** Turn-process state when this Node belongs to a projected Turn. */\n  turnProcess?: TurnProcessOwnerProps | undefined\n}',
+      '/** Stable owner currency delivered to a keyed Chat renderer. */\nexport interface ChatNodeOwnerProps {\n  cwd?: string | undefined\n  openFile: (path: string, options?: OpenFileOptions) => void\n  inspectCall: (callId: ToolCallId) => void\n  forkAt: (seq: number) => void\n  /**\n   * Session-authorized image loader, down-threaded from the Chat view so a\n   * chat-node renderer can render the attachment presentation slot directly\n   * with only the durable references plus this loader, instead of receiving a\n   * rendering closure.\n   */\n  loadImage: MessageImageLoader\n  renderMessageImages: RenderMessageImages\n  fileMentions: (owner: TurnTailOwnerProps) => MarkdownFileMentions | undefined\n  /** Turn-process state when this Node belongs to a projected Turn. */\n  turnProcess?: TurnProcessOwnerProps | undefined\n}',
     ],
     ownerPropsReferences: [
       'MarkdownFileMentions',
       'MessageImageLoader',
+      'OpenFileOptions',
       'RenderMessageImages',
       'TurnProcessOwnerProps',
       'TurnTailOwnerProps',
     ],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -314,7 +320,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.chat.node\', () => ctx.slots.register(\n      { name: \'conversation.chat.node\', key: \'<one key the owner dispatches>\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:196',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:181',
   },
   {
     key: 'conversation.chat.turnTail',
@@ -337,6 +343,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
       'TurnLocation',
     ],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -359,7 +366,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.chat.turnTail\', () => ctx.slots.register(\n      { name: \'conversation.chat.turnTail\', select: owner => null },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:221',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:206',
   },
   {
     key: 'conversation.composer',
@@ -384,6 +391,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
       'SessionSnapshot',
     ],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -408,7 +416,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.composer\', () => ctx.slots.register(\n      { name: \'conversation.composer\', select: owner => null },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:145',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:157',
   },
   {
     key: 'conversation.composer.bar',
@@ -424,6 +432,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
       'Workspace',
     ],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -444,7 +453,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.composer.bar\', () => ctx.slots.register(\n      { name: \'conversation.composer.bar\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:163',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:175',
   },
   {
     key: 'conversation.composer.dock',
@@ -475,6 +484,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ownerProps: [],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -493,47 +503,11 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     slotInject: '',
     declaredBy: 'an entry in \'conversation.composer.bar\' (client-ui-conversation), so it exists while that entry is mounted',
     occupants: [
-      'client-ui-chat StatsLine id \'stats\'',
+      'client-ui-chat StatsPills id \'stats\'',
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.composer.dock\', () => ctx.slots.register(\n      { name: \'conversation.composer.dock\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:157',
-  },
-  {
-    key: 'conversation.details.tool',
-    kind: 'single',
-    scope: 'session',
-    summary: 'Whole details-panel body for the selected Tool call.',
-    doc: 'Whole details-panel body for the selected Tool call. The component receives\nthe running or settled block and optional workspace root. A registration\nreplaces the shipped Tool details renderer; absence uses the raw fallback.',
-    registerOptions: [],
-    ownerProps: [
-      '/** Tool block rendered in the details panel. */\nexport interface DetailsToolOwnerProps {\n  block: ToolCallBlock\n  cwd?: string | undefined\n}',
-    ],
-    ownerPropsReferences: [],
-    standardProps: [
-      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
-      'useSessions: UseSessions',
-      'useSessionPendingInteraction: UseSessionPendingInteraction',
-      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
-      'useChat: UseChat',
-      'useConversation: UseConversation',
-      'useInput: SnapshotSelectorHook<InputState>',
-      'inputActions: InputActions',
-      'useSession: SessionSnapshotSelector',
-      'sessionId: SessionId',
-      'useProjection: UseProjection',
-      'useTrajectory: UseTrajectory',
-    ],
-    keyDomain: '',
-    hookContext: '',
-    slotInject: '',
-    declaredBy: 'an entry in \'details\' (client-ui-chat), so it exists while that entry is mounted',
-    occupants: [
-      'client-ui-tool ToolDetails',
-    ],
-    replaceRisk: 'shadows-shipped-ui',
-    example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.details.tool\', () => ctx.slots.register(\n      { name: \'conversation.details.tool\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:233',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:169',
   },
   {
     key: 'conversation.hero.agentPreset',
@@ -547,6 +521,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -561,7 +536,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.hero.agentPreset\', () => ctx.slots.register(\n      { name: \'conversation.hero.agentPreset\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:151',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:163',
   },
   {
     key: 'conversation.hero.brand.mark',
@@ -575,6 +550,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -587,7 +563,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.hero.brand.mark\', () => ctx.slots.register(\n      { name: \'conversation.hero.brand.mark\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:149',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:161',
   },
   {
     key: 'conversation.hero.workspace',
@@ -603,6 +579,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
       'Workspace',
     ],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -617,7 +594,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.hero.workspace\', () => ctx.slots.register(\n      { name: \'conversation.hero.workspace\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:147',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:159',
   },
   {
     key: 'conversation.hero.workspace.directoryFlow',
@@ -631,6 +608,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -664,6 +642,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
       'DraftFileUploads',
     ],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -684,7 +663,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.attachments\', () => ctx.slots.register(\n      { name: \'conversation.input.attachments\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:165',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:177',
   },
   {
     key: 'conversation.input.dock',
@@ -720,6 +699,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
       'SessionSnapshot',
     ],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -744,7 +724,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.dock\', () => ctx.slots.register(\n      { name: \'conversation.input.dock\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:153',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:165',
   },
   {
     key: 'conversation.input.left',
@@ -775,6 +755,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ownerProps: [],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -795,7 +776,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.left\', () => ctx.slots.register(\n      { name: \'conversation.input.left\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:159',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:171',
   },
   {
     key: 'conversation.input.model',
@@ -809,6 +790,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -831,7 +813,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.model\', () => ctx.slots.register(\n      { name: \'conversation.input.model\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:173',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:185',
   },
   {
     key: 'conversation.input.overlay',
@@ -862,6 +844,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ownerProps: [],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -885,7 +868,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.overlay\', () => ctx.slots.register(\n      { name: \'conversation.input.overlay\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:155',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:167',
   },
   {
     key: 'conversation.input.plan',
@@ -899,6 +882,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -921,7 +905,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.plan\', () => ctx.slots.register(\n      { name: \'conversation.input.plan\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:171',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:183',
   },
   {
     key: 'conversation.input.right',
@@ -952,6 +936,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ownerProps: [],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -972,7 +957,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.right\', () => ctx.slots.register(\n      { name: \'conversation.input.right\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:161',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:173',
   },
   {
     key: 'conversation.message.images',
@@ -990,6 +975,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
       'MessageImageSource',
     ],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1012,7 +998,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.message.images\', () => ctx.slots.register(\n      { name: \'conversation.message.images\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:209',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:194',
   },
   {
     key: 'conversation.session',
@@ -1024,6 +1010,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ownerProps: [],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1058,6 +1045,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ownerProps: [],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1113,6 +1101,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1140,6 +1129,43 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.session.header.actions\', () => ctx.slots.register(\n      { name: \'conversation.session.header.actions\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
     source: 'packages/client/ui-conversation/src/client/contract/slots.ts:131',
   },
+  {
+    key: 'conversation.session.header.corner',
+    kind: 'single',
+    scope: 'session',
+    summary: 'The header\'s far-right corner, past the utilities\' edge and into the header\'s own padding, for one control that must keep its place whether or not it currently shows anything.',
+    doc: 'The header\'s far-right corner, past the utilities\' edge and into the\nheader\'s own padding, for one control that must keep its place whether or\nnot it currently shows anything. The corner reserves its width while an\noccupant is registered, so the utilities beside it never move; an\noccupant with nothing to show renders a same-size placeholder.',
+    registerOptions: [],
+    ownerProps: [
+      '/** The header corner\'s occupant derives its state from standard Session props. */\nexport interface ConversationHeaderCornerOwnerProps {\n  /** Marker field: the occupant receives no owner-specific values. */\n  children?: never\n}',
+    ],
+    ownerPropsReferences: [],
+    standardProps: [
+      'useResource: UseResource',
+      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
+      'useSessions: UseSessions',
+      'useSessionPendingInteraction: UseSessionPendingInteraction',
+      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
+      'useChat: UseChat',
+      'useConversation: UseConversation',
+      'useInput: SnapshotSelectorHook<InputState>',
+      'inputActions: InputActions',
+      'useSession: SessionSnapshotSelector',
+      'sessionId: SessionId',
+      'useProjection: UseProjection',
+      'useTrajectory: UseTrajectory',
+    ],
+    keyDomain: '',
+    hookContext: '',
+    slotInject: '',
+    declaredBy: 'an entry in \'conversation.session.header\' (client-ui-conversation), so it exists while that entry is mounted',
+    occupants: [
+      'client-ui-sidebar-right ExpandButton',
+    ],
+    replaceRisk: 'shadows-shipped-ui',
+    example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.session.header.corner\', () => ctx.slots.register(\n      { name: \'conversation.session.header.corner\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:149',
+  },
   {
     key: 'conversation.session.header.lineage',
     kind: 'single',
@@ -1154,6 +1180,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
       'SessionId',
     ],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1209,6 +1236,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1250,6 +1278,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
       'MessageImageSource',
     ],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1307,6 +1336,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
       'ConversationViewRequest',
     ],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1330,20 +1360,21 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.view\', () => ctx.slots.register(\n      { name: \'conversation.view\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:143',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:155',
   },
   {
-    key: 'details',
+    key: 'rightbar',
     kind: 'single',
     scope: 'session',
-    summary: 'The right details column, shown when the layout opens it.',
-    doc: 'The right details column, shown when the layout opens it. OCCUPIED by\nui-conversation\'s DetailsPanel, which declares the tool-details seat\ninside it — registering here replaces the column and takes that seat\nwith it. Absent an occupant the column renders nothing.\n\nNo owner props: the framework injects the session id and hooks for the\n`session` scope, and `ctx.layout` owns whether the column is open.',
+    summary: 'The right column: a track the centre makes room for, or nothing.',
+    doc: 'The right column: a track the centre makes room for, or nothing. OCCUPIED\nby the right Sidebar, which uses the resolved column width in normal\nmode and covers the viewport in fullscreen, retaining the wide-screen\ncolumn reservation underneath.\n\nWhether the panel is shown, and whether it takes a track, is the\noccupant\'s own recorded business — it reports the composition of its\nexpanded and presentation state through `ctx.layout`, and the frame sizes\nthe track and places the resize handle from that. The expand control is\nnot this column\'s: it is a button in the conversation header. With no\ncurrent session nothing is mounted here.',
     registerOptions: [],
     ownerProps: [
-      '/** Details owner share: empty — sessionId arrives as a framework-standard prop. */\nexport interface DetailsOwnerProps {}',
+      '/** Right column owner share: resolved normal geometry and opening eligibility. */\nexport interface RightbarOwnerProps {\n  /** Resolved normal panel width in px, not the saved preference; zero if it cannot fit. */\n  width: number\n  /** Current frame width in px. */\n  viewportWidth: number\n  /**\n   * Whether a normal right panel can retain 300px beside a 400px center.\n   * Before a narrow opening, includes the space from collapsing the left sidebar.\n   */\n  canShow: boolean\n}',
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1362,11 +1393,11 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     slotInject: '',
     declaredBy: 'an entry in \'root\' (client-ui-layout), so it exists while that entry is mounted',
     occupants: [
-      'client-ui-chat DetailsPanel',
+      'client-ui-sidebar-right RightbarSeat',
     ],
     replaceRisk: 'shadows-shipped-ui',
-    example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'details\', () => ctx.slots.register(\n      { name: \'details\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-layout/src/client/index.ts:75',
+    example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'rightbar\', () => ctx.slots.register(\n      { name: \'rightbar\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
+    source: 'packages/client/ui-layout/src/client/index.ts:79',
   },
   {
     key: 'root',
@@ -1380,6 +1411,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1427,6 +1459,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1455,6 +1488,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1502,6 +1536,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1535,6 +1570,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1582,6 +1618,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1617,6 +1654,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
       'ProviderDirectoryEntry',
     ],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1662,6 +1700,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1698,6 +1737,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1748,6 +1788,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1796,6 +1837,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1827,6 +1869,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1872,6 +1915,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ownerProps: [],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1884,7 +1928,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'shell.overlay\', () => ctx.slots.register(\n      { name: \'shell.overlay\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-layout/src/client/index.ts:86',
+    source: 'packages/client/ui-layout/src/client/index.ts:90',
   },
   {
     key: 'sidebar',
@@ -1898,6 +1942,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1926,6 +1971,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -1954,6 +2000,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -2001,6 +2048,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -2017,6 +2065,186 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'sidebar.footer.action\', () => ctx.slots.register(\n      { name: \'sidebar.footer.action\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
     source: 'packages/client/ui-sidebar/src/client/contract/slots.ts:46',
   },
+  {
+    key: 'sidebar.right.pane.tab',
+    kind: 'keyed',
+    scope: 'session',
+    summary: 'One tab\'s body, dispatched with the `id` of the type in force for `tab.kind`.',
+    doc: 'One tab\'s body, dispatched with the `id` of the type in force for\n`tab.kind`. A tab type registers here under its definition\'s `id` and\nreceives every tab of that kind, in every pane, docked or floating. A kind\nwith no type in force renders the owner\'s "nothing can view this" notice\nrather than an empty pane.',
+    registerOptions: [
+      {
+        name: 'key',
+        requirement: 'required',
+        type: 'string',
+        doc: 'Your cell key: the entry renders where the owner dispatches this exact key. Registering an already-occupied key replaces that occupant.',
+      },
+    ],
+    ownerProps: [],
+    ownerPropsReferences: [],
+    standardProps: [
+      'useResource: UseResource',
+      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
+      'useSessions: UseSessions',
+      'useSessionPendingInteraction: UseSessionPendingInteraction',
+      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
+      'useChat: UseChat',
+      'useConversation: UseConversation',
+      'useInput: SnapshotSelectorHook<InputState>',
+      'inputActions: InputActions',
+      'useSession: SessionSnapshotSelector',
+      'sessionId: SessionId',
+      'useProjection: UseProjection',
+      'useTrajectory: UseTrajectory',
+    ],
+    keyDomain: 'open: any string the owner dispatches (no compile-time key set), none are taken yet',
+    hookContext: 'TabHookContext',
+    slotInject: 'SidebarRightTabInjected',
+    declaredBy: 'an entry in \'rightbar\' (client-ui-sidebar-right), so it exists while that entry is mounted',
+    occupants: [
+      'client-ui-sidebar-files FilesBody',
+      'client-ui-sidebar-right GuideBody',
+      'client-ui-sidebar-textpreview TextPreview',
+    ],
+    replaceRisk: 'none',
+    example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'sidebar.right.pane.tab\', () => ctx.slots.register(\n      { name: \'sidebar.right.pane.tab\', key: \'<one key the owner dispatches>\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
+    source: 'packages/client/ui-sidebar-right/src/client/contract/slots.ts:47',
+  },
+  {
+    key: 'sidebar.right.pane.tab.title',
+    kind: 'keyed',
+    scope: 'session',
+    summary: 'A tab\'s title as its chip (and a floating panel\'s header) shows it, dispatched with the same key and information hook as the body.',
+    doc: 'A tab\'s title as its chip (and a floating panel\'s header) shows it,\ndispatched with the same key and information hook as the body. A type with a\nlive title — a terminal named after its shell, a chat after its first\nline — registers here and reads its own store; one without registers\nnothing and the chip shows the registry\'s `title(address)` text captured\nat open time.',
+    registerOptions: [
+      {
+        name: 'key',
+        requirement: 'required',
+        type: 'string',
+        doc: 'Your cell key: the entry renders where the owner dispatches this exact key. Registering an already-occupied key replaces that occupant.',
+      },
+    ],
+    ownerProps: [],
+    ownerPropsReferences: [],
+    standardProps: [
+      'useResource: UseResource',
+      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
+      'useSessions: UseSessions',
+      'useSessionPendingInteraction: UseSessionPendingInteraction',
+      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
+      'useChat: UseChat',
+      'useConversation: UseConversation',
+      'useInput: SnapshotSelectorHook<InputState>',
+      'inputActions: InputActions',
+      'useSession: SessionSnapshotSelector',
+      'sessionId: SessionId',
+      'useProjection: UseProjection',
+      'useTrajectory: UseTrajectory',
+    ],
+    keyDomain: 'open: any string the owner dispatches (no compile-time key set), none are taken yet',
+    hookContext: 'TabHookContext',
+    slotInject: 'SidebarRightTabInjected',
+    declaredBy: 'an entry in \'rightbar\' (client-ui-sidebar-right), so it exists while that entry is mounted',
+    occupants: [],
+    replaceRisk: 'none',
+    example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'sidebar.right.pane.tab.title\', () => ctx.slots.register(\n      { name: \'sidebar.right.pane.tab.title\', key: \'<one key the owner dispatches>\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
+    source: 'packages/client/ui-sidebar-right/src/client/contract/slots.ts:61',
+  },
+  {
+    key: 'sidebar.right.tab.guide',
+    kind: 'chain',
+    scope: 'session',
+    summary: 'The guide tab\'s body.',
+    doc: 'The guide tab\'s body. Selectors run in chain order and the first\nnon-declining entry replaces the shipped guide entirely; with no entry, or\nwith every entry declining, the shipped guide renders.',
+    registerOptions: [
+      {
+        name: 'select',
+        requirement: 'required',
+        type: '(owner) => unknown | null',
+        doc: 'Pure routing selector. Entries are tried in ascending order; the first non-null result wins and arrives as the component\'s `matched` prop. All-null falls through to the owner\'s fallback.',
+      },
+    ],
+    ownerProps: [],
+    ownerPropsReferences: [],
+    standardProps: [
+      'useResource: UseResource',
+      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
+      'useSessions: UseSessions',
+      'useSessionPendingInteraction: UseSessionPendingInteraction',
+      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
+      'useChat: UseChat',
+      'useConversation: UseConversation',
+      'useInput: SnapshotSelectorHook<InputState>',
+      'inputActions: InputActions',
+      'useSession: SessionSnapshotSelector',
+      'sessionId: SessionId',
+      'useProjection: UseProjection',
+      'useTrajectory: UseTrajectory',
+    ],
+    keyDomain: '',
+    hookContext: 'UseSidebarRightTabInfo',
+    slotInject: '{ hooks: { tabInfo: SlotHookFactory<\'sidebar.right.tab.guide\', UseSidebarRightTabInfo> } }',
+    declaredBy: 'an entry in \'sidebar.right.pane.tab\' (client-ui-sidebar-right), so it exists while that entry is mounted',
+    occupants: [],
+    replaceRisk: 'none',
+    example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'sidebar.right.tab.guide\', () => ctx.slots.register(\n      { name: \'sidebar.right.tab.guide\', select: owner => null },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
+    source: 'packages/client/ui-sidebar-right/src/client/contract/slots.ts:72',
+  },
+  {
+    key: 'sidebar.right.tab.menu.item',
+    kind: 'list',
+    scope: 'session',
+    summary: 'Extra items at the end of one tab\'s actions menu, in registration order.',
+    doc: 'Extra items at the end of one tab\'s actions menu, in registration order.\nEntries decide their own visibility from the tab they are given. Without a\nregistrant the menu shows only the kit\'s own layout actions.',
+    registerOptions: [
+      {
+        name: 'id',
+        requirement: 'required',
+        type: 'string',
+        doc: 'Your cell key. Use an id of your own: a fresh id is added beside the shipped entries, while reusing a shipped id puts you in THAT cell and replaces it. Owners that filter by id address you by it.',
+      },
+      {
+        name: 'order',
+        requirement: 'optional',
+        type: 'number',
+        doc: 'Position among the entries, ascending (default 0).',
+      },
+      {
+        name: 'label',
+        requirement: 'optional',
+        type: 'string | (() => string)',
+        doc: 'Display text where the owner projects one (nav rows, tabs). A thunk is re-read on every projection, so localized text follows the active locale without re-registering.',
+      },
+    ],
+    ownerProps: [
+      '/** Owner share of one tab-menu item occurrence. */\nexport interface SidebarRightTabMenuOwnerProps {\n  /** The tab whose menu is open. */\n  tab: TabRecord\n  /**\n   * Dismiss the menu.\n   *\n   * An item that acts MUST call this: the menu is the kit\'s, and it closes on\n   * its own actions only. An item that leaves it open leaves a menu floating\n   * over content the action may have just replaced.\n   */\n  dismiss: () => void\n}',
+    ],
+    ownerPropsReferences: [
+      'TabRecord',
+    ],
+    standardProps: [
+      'useResource: UseResource',
+      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
+      'useSessions: UseSessions',
+      'useSessionPendingInteraction: UseSessionPendingInteraction',
+      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
+      'useChat: UseChat',
+      'useConversation: UseConversation',
+      'useInput: SnapshotSelectorHook<InputState>',
+      'inputActions: InputActions',
+      'useSession: SessionSnapshotSelector',
+      'sessionId: SessionId',
+      'useProjection: UseProjection',
+      'useTrajectory: UseTrajectory',
+    ],
+    keyDomain: '',
+    hookContext: '',
+    slotInject: '',
+    declaredBy: 'an entry in \'rightbar\' (client-ui-sidebar-right), so it exists while that entry is mounted',
+    occupants: [],
+    replaceRisk: 'none',
+    example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'sidebar.right.tab.menu.item\', () => ctx.slots.register(\n      { name: \'sidebar.right.tab.menu.item\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
+    source: 'packages/client/ui-sidebar-right/src/client/contract/slots.ts:83',
+  },
   {
     key: 'sidebar.settings',
     kind: 'single',
@@ -2029,6 +2257,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -2057,6 +2286,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -2085,6 +2315,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     ownerPropsReferences: [],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -2117,6 +2348,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
       'MessageImageSource',
     ],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -2156,13 +2388,15 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
       },
     ],
     ownerProps: [
-      '/** Standard owner currency supplied to every atomic Tool view. */\nexport interface ToolCallOwnerProps {\n  /** Tool call identity, stable across running and settled forms. */\n  callId: string\n  /** Wire Tool name and keyed dispatch value. */\n  toolName: string\n  /** Frozen running call or settled result node. */\n  block: ToolCallBlock\n  /** Session workspace root for relative summaries. */\n  cwd?: string | undefined\n  /** Host account home; POSIX home-rooted summaries display as `~`. */\n  home?: string | undefined\n  /** Open a Tool argument path through the Host. */\n  openFile: (path: string) => void\n  /**\n   * Session-authorized image loader for the `tool.call.images` slot, supplied\n   * by the chat node that owns this call. A composed chat node always\n   * supplies it (`ChatNodeOwnerProps.loadImage` is required), so the tool\n   * layer never imports an attachment implementation nor handles URL\n   * authorization.\n   */\n  loadImage: MessageImageLoader\n  /** Inspect this call in the trajectory view when available. */\n  inspect?: (() => void) | undefined\n}',
+      '/** Standard owner currency supplied to every atomic Tool view. */\nexport interface ToolCallOwnerProps {\n  /** Tool call identity, stable across running and settled forms. */\n  callId: string\n  /** Wire Tool name and keyed dispatch value. */\n  toolName: string\n  /** Frozen running call or settled result node. */\n  block: ToolCallBlock\n  /** Session workspace root for relative summaries. */\n  cwd?: string | undefined\n  /** Host account home; POSIX home-rooted summaries display as `~`. */\n  home?: string | undefined\n  /**\n   * Open a Tool argument path. A view that knows which line the call was about\n   * passes it, and the opened surface lands there.\n   */\n  openFile: (path: string, options?: OpenFileOptions) => void\n  /**\n   * Session-authorized image loader for the `tool.call.images` slot, supplied\n   * by the chat node that owns this call. A composed chat node always\n   * supplies it (`ChatNodeOwnerProps.loadImage` is required), so the tool\n   * layer never imports an attachment implementation nor handles URL\n   * authorization.\n   */\n  loadImage: MessageImageLoader\n  /** Inspect this call in the trajectory view when available. */\n  inspect?: (() => void) | undefined\n}',
     ],
     ownerPropsReferences: [
       'ChatNodeOwnerProps',
       'MessageImageLoader',
+      'OpenFileOptions',
     ],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
@@ -2225,6 +2459,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
       'CordisDynamicPluginRunId',
     ],
     standardProps: [
+      'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
       'useSessions: UseSessions',
       'useSessionPendingInteraction: UseSessionPendingInteraction',
diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts
index d1eb6cf914..a9e44e0353 100644
--- a/packages/extensions/tool-cordis/src/api-catalog.ts
+++ b/packages/extensions/tool-cordis/src/api-catalog.ts
@@ -1014,6 +1014,12 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         parameters: [{ name: 'target', description: 'the resolved target to read.' }, { name: 'signal', description: 'aborts the read.' }, { name: 'maxBytes', description: 'inclusive byte cap on the complete content.' }],
         returns: 'the full raw content, at most `maxBytes` long.',
       },
+      {
+        signature: 'abstract readByteRange(target: FsTarget, range: { offset: number; length: number }, signal?: AbortSignal): Promise<Uint8Array>',
+        description: 'Read one byte window of the regular file as raw bytes with no decoding or binary rejection: the bytes at `[offset, offset + length)`, shorter when the file ends inside the window and empty when `offset` lies at or past its end. The window is the bound here, not the file: a backend transfers at most `length` bytes of content beyond the prefix it skips to reach `offset` and never buffers the whole file, so the caller\'s cap on `length` is the guard against unbounded buffering.',
+        parameters: [{ name: 'target', description: 'the resolved target to read.' }, { name: 'range', description: '`offset`, the 0-based first byte, and `length`, the largest byte count; both non-negative integers.' }, { name: 'signal', description: 'aborts the read.' }],
+        returns: 'the window\'s bytes, at most `length` long.',
+      },
       {
         signature: 'abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>',
         description: 'List direct children of a directory in stable name order. Returns resolved child targets plus cheap metadata only; never reads file contents.',
@@ -1040,7 +1046,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     description: 'Goal service (`ctx.goals`) backed exclusively by the owning session log.',
     methods: [
       {
-        signature: 'get(agent: Agent): GoalView | undefined',
+        signature: '@Remote(\'get\') get(agent: Agent): GoalView | undefined',
         description: 'Read the current goal for one exact live agent.',
         parameters: [{ name: 'agent', description: 'owning live agent.' }],
         returns: 'a fresh view or `undefined` when no goal is current.',
@@ -2891,6 +2897,43 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
     ],
   },
+  {
+    key: 'workspaceFiles',
+    summary: 'Host Remote service over the composed filesystem, confined to one workspace.',
+    description: 'Host Remote service over the composed filesystem, confined to one workspace.',
+    methods: [
+      {
+        signature: '@Remote async read(agent: Agent, path: string, range: WorkspaceFileRange, signal: AbortSignal): Promise<WorkspaceFileText>',
+        description: 'Read one page of lines from a UTF-8 text file inside the Agent\'s workspace.',
+        parameters: [{ name: 'agent', description: 'target Agent resolved from the Session identity on the wire.' }, { name: 'path', description: 'workspace path, absolute or relative to the workspace root.' }, { name: 'range', description: 'the line window; omitted fields take the page defaults.' }, { name: 'signal', description: 'caller cancellation.' }],
+        returns: 'the page, the file\'s version at the stat before it, and whether it reaches the last line.',
+      },
+      {
+        signature: '@Remote async readBytes(agent: Agent, path: string, range: WorkspaceByteRange, signal: AbortSignal): Promise<WorkspaceFileBytes>',
+        description: 'Read one byte window of a regular file inside the Agent\'s workspace: raw bytes, no text decoding and no binary rejection.',
+        parameters: [{ name: 'agent', description: 'target Agent resolved from the Session identity on the wire.' }, { name: 'path', description: 'workspace path, absolute or relative to the workspace root.' }, { name: 'range', description: 'the byte window; omitted fields take the window defaults.' }, { name: 'signal', description: 'caller cancellation.' }],
+        returns: 'the window in base64, the file\'s version and size at the stat before it, and whether it reaches the last byte.',
+      },
+      {
+        signature: '@Remote async stat(agent: Agent, path: string, signal: AbortSignal): Promise<WorkspaceFileStat>',
+        description: 'Report one regular file\'s identity, version, and size without its content.',
+        parameters: [{ name: 'agent', description: 'target Agent resolved from the Session identity on the wire.' }, { name: 'path', description: 'workspace path, absolute or relative to the workspace root.' }, { name: 'signal', description: 'caller cancellation.' }],
+        returns: 'the file\'s absolute path, current version, and byte size.',
+      },
+      {
+        signature: '@Remote async list(agent: Agent, path: string, signal: AbortSignal): Promise<WorkspaceDirectoryListing>',
+        description: 'List the direct children of one directory inside the Agent\'s workspace.',
+        parameters: [{ name: 'agent', description: 'target Agent resolved from the Session identity on the wire.' }, { name: 'path', description: 'workspace path, absolute or relative to the workspace root.' }, { name: 'signal', description: 'caller cancellation.' }],
+        returns: 'the directory\'s children in the backend\'s stable name order, bounded by the entry cap.',
+      },
+      {
+        signature: '@Remote({ mode: \'stream\' }) changes(agent: Agent, signal: AbortSignal): AsyncIterable<WorkspaceFileWatchFrame>',
+        description: 'Stream every `fs/observed` observation of a file inside the Agent\'s workspace. Only Agent filesystem operations report here; the OS is not watched.',
+        parameters: [{ name: 'agent', description: 'target Agent resolved from the Session identity on the wire.' }, { name: 'signal', description: 'generation cancellation.' }],
+        returns: '`ready` once the Host observation queue is active and the workspace root is resolved, then queued and live observations in emission order.',
+      },
+    ],
+  },
   {
     key: 'workspaceRegistry',
     summary: 'Durable workspace registry.',
@@ -3232,6 +3275,14 @@ export const EVENT_API: readonly EventApiEntry[] = [
     description: 'Single-slot decision for the next FileSystem.writeText. Calling `next()` yields the bare provider\'s unconditional write; the first listener that returns an intent owns the decision rather than composing with peers.',
     parameters: [{ name: 'target', description: 'the resolved target about to be written.' }, { name: 'actor', description: 'the opaque tool-execution context the decider keys off.' }],
   },
+  {
+    name: 'goal/activation-changed',
+    mode: 'emit',
+    signature: '\'goal/activation-changed\'(payload: GoalActivationChanged): void',
+    summary: 'Process-local goal activation changed for one session.',
+    description: 'Process-local goal activation changed for one session.',
+    parameters: [{ name: 'payload', description: 'session id and the exact current goal activation, or no goal after a clear.' }],
+  },
   {
     name: 'goal/changed',
     mode: 'emit',
@@ -4216,6 +4267,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'GoalActivation',
     declaration: 'export type GoalActivation = \'armed\' | \'disarmed\';',
   },
+  {
+    name: 'GoalActivationChanged',
+    declaration: 'export interface GoalActivationChanged {\n    readonly sessionId: SessionId;\n    readonly goal?: {\n        readonly id: GoalId;\n        readonly revision: number;\n        readonly activation: GoalActivation;\n    };\n}',
+  },
   {
     name: 'GoalBlockReason',
     declaration: 'export interface GoalBlockReason {\n    readonly code: string;\n    readonly message: string;\n}',
@@ -6312,6 +6367,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'WorkspaceBaseline',
     declaration: 'export interface WorkspaceBaseline {\n    readonly items: readonly WorkspaceView[];\n    readonly archivedSessionIds: readonly SessionId[];\n}',
   },
+  {
+    name: 'WorkspaceByteRange',
+    declaration: 'export interface WorkspaceByteRange {\n    readonly offset?: number;\n    readonly length?: number;\n}',
+  },
   {
     name: 'WorkspaceCreateRequest',
     declaration: 'export interface WorkspaceCreateRequest {\n    readonly path: string;\n}',
@@ -6328,6 +6387,38 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'WorkspaceDeleteValue',
     declaration: 'export interface WorkspaceDeleteValue {\n    readonly deleted: true;\n}',
   },
+  {
+    name: 'WorkspaceDirectoryEntry',
+    declaration: 'export interface WorkspaceDirectoryEntry {\n    readonly name: string;\n    readonly type: \'file\' | \'directory\' | \'other\';\n    readonly size?: number;\n}',
+  },
+  {
+    name: 'WorkspaceDirectoryListing',
+    declaration: 'export interface WorkspaceDirectoryListing {\n    readonly path: string;\n    readonly entries: readonly WorkspaceDirectoryEntry[];\n    readonly truncated: boolean;\n}',
+  },
+  {
+    name: 'WorkspaceFileBytes',
+    declaration: 'export interface WorkspaceFileBytes extends WorkspaceFileStat {\n    readonly offset: number;\n    readonly data: string;\n    readonly eof: boolean;\n}',
+  },
+  {
+    name: 'WorkspaceFileChange',
+    declaration: 'export type WorkspaceFileChange = {\n    readonly absolutePath: string;\n    readonly version: string;\n} | {\n    readonly absolutePath: string;\n    readonly absent: true;\n};',
+  },
+  {
+    name: 'WorkspaceFileRange',
+    declaration: 'export interface WorkspaceFileRange {\n    readonly offset?: number;\n    readonly limit?: number;\n}',
+  },
+  {
+    name: 'WorkspaceFileStat',
+    declaration: 'export interface WorkspaceFileStat {\n    readonly absolutePath: string;\n    readonly version: string;\n    readonly bytes?: number;\n}',
+  },
+  {
+    name: 'WorkspaceFileText',
+    declaration: 'export interface WorkspaceFileText extends WorkspaceFileStat {\n    readonly offset: number;\n    readonly text: string;\n    readonly lines: number;\n    readonly eof: boolean;\n}',
+  },
+  {
+    name: 'WorkspaceFileWatchFrame',
+    declaration: 'export type WorkspaceFileWatchFrame = {\n    readonly kind: \'ready\';\n} | {\n    readonly kind: \'change\';\n    readonly change: WorkspaceFileChange;\n};',
+  },
   {
     name: 'WorkspaceFollowFrame',
     declaration: 'export type WorkspaceFollowFrame = {\n    readonly type: \'baseline\';\n    readonly value: WorkspaceBaseline;\n} | WorkspaceFollowIncrement;',
diff --git a/packages/fs/fs-local/README.i18n.yaml b/packages/fs/fs-local/README.i18n.yaml
index 265af90b94..bd66fe68e1 100644
--- a/packages/fs/fs-local/README.i18n.yaml
+++ b/packages/fs/fs-local/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/fs/fs-local/README.md
-README.md: 07fb96d457abd3807e892d37d473e92093078664
-README.zh.md: 4980de0c7fe771f75e38d896644d62c29c352c04
+README.md: 24ca13b384e8a3d123b77ce916b86656bc3bd114
+README.zh.md: a23ba0c7bb87309d1fd093a6f55e4505776f02ed
diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md
index 07fb96d457..24ca13b384 100644
--- a/packages/fs/fs-local/README.md
+++ b/packages/fs/fs-local/README.md
@@ -50,7 +50,7 @@ The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-a
 
 ### What you can do
 
-Read any regular UTF-8 text file whole or as a stream, read raw bytes up to a cap you choose, and list one directory level in stable name order. Create or replace a file atomically, and apply a literal text edit atomically; both mutations serialize per file, so concurrent writers never interleave. The version guard is optional: omit it for unconditional create-or-overwrite, or supply it to fail when the file changed since you last observed it.
+Read any regular UTF-8 text file whole or as a stream, read raw bytes up to a cap you choose or as one byte window, and list one directory level in stable name order. Create or replace a file atomically, and apply a literal text edit atomically; both mutations serialize per file, so concurrent writers never interleave. The version guard is optional: omit it for unconditional create-or-overwrite, or supply it to fail when the file changed since you last observed it.
 
 Failures are typed `FsError`s with stable codes — `FS_NOT_FOUND`, `FS_NOT_TEXT` (binary content), `FS_STALE_VERSION` (changed since observation), `FS_EDIT_NOT_FOUND` or `FS_AMBIGUOUS_EDIT` (no unique literal match), and others — so callers branch on the code, never on message text. A missing target on a guarded edit reports `FS_STALE_VERSION` either way.
 
diff --git a/packages/fs/fs-local/README.zh.md b/packages/fs/fs-local/README.zh.md
index 4980de0c7f..a23ba0c7bb 100644
--- a/packages/fs/fs-local/README.zh.md
+++ b/packages/fs/fs-local/README.zh.md
@@ -50,7 +50,7 @@ kind: "package-reference"
 
 ### 你能做什么
 
-完整或流式读取任意普通 UTF-8 文本文件，按你选择的上限读取原始字节，并按稳定名称顺序列出一层目录。原子地创建或替换文件，并原子地应用字面量文本编辑；两个变更操作都按文件串行化，并发写入方绝不会交错。版本防护是可选的：省略它即无条件创建或覆盖，提供它则在文件自上次观察以来发生变化时失败。
+完整或流式读取任意普通 UTF-8 文本文件，按你选择的上限或按字节窗口读取原始字节，并按稳定名称顺序列出一层目录。原子地创建或替换文件，并原子地应用字面量文本编辑；两个变更操作都按文件串行化，并发写入方绝不会交错。版本防护是可选的：省略它即无条件创建或覆盖，提供它则在文件自上次观察以来发生变化时失败。
 
 失败是携带稳定错误码的类型化 `FsError`——`FS_NOT_FOUND`、`FS_NOT_TEXT`（二进制内容）、`FS_STALE_VERSION`（自观察以来已变化）、`FS_EDIT_NOT_FOUND` 或 `FS_AMBIGUOUS_EDIT`（无唯一字面量匹配）等——因此调用方依据错误码分支，绝不解析消息文本。带防护的编辑遇到缺失目标时，无论哪种情况都报告 `FS_STALE_VERSION`。
 
diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts
index 17bfb6115b..e07567e0e3 100644
--- a/packages/fs/fs-local/src/fsio.ts
+++ b/packages/fs/fs-local/src/fsio.ts
@@ -426,6 +426,44 @@ export async function readWholeBytes(
   return Buffer.concat(chunks, bytes)
 }
 
+/**
+ * Read the bytes at `[offset, offset + length)` of a regular file with no
+ * decoding or binary rejection. The window is the bound: the stream opens at
+ * `offset` and closes after `length` bytes, so no more than the window is ever
+ * buffered whatever the file's size; a window at or past the end is empty.
+ * @param target - the resolved file to read.
+ * @param range - `offset`, the 0-based first byte, and `length`, the largest byte count.
+ * @param signal - aborts the read (`FS_ABORTED`).
+ * @returns the window's bytes, at most `length` long.
+ */
+export async function readByteWindow(
+  target: LocalTarget,
+  range: { offset: number; length: number },
+  signal?: AbortSignal,
+): Promise<Uint8Array> {
+  await statRegularFile(target, 'read', signal)
+  if (range.length === 0) return new Uint8Array(0)
+  const stream = createReadStream(target.targetKey, {
+    start: range.offset,
+    end: range.offset + range.length - 1,
+    ...signal ? { signal } : {},
+  })
+  const chunks: Buffer[] = []
+  let bytes = 0
+  try {
+    for await (const chunk of stream as AsyncIterable<Buffer>) {
+      chunks.push(chunk)
+      bytes += chunk.length
+    }
+  } catch (error: unknown) {
+    /* v8 ignore next 2 -- a mid-stream abort needs cancellation racing an active read; pre-abort is deterministic. */
+    if (isAbortError(error)) throw new FsError('read aborted', 'FS_ABORTED')
+    /* v8 ignore next -- any other stream failure needs an I/O fault after a successful stat. */
+    throw error
+  }
+  return Buffer.concat(chunks, bytes)
+}
+
 /**
  * Stream a whole regular UTF-8 text file as decoded text chunks. Same text
  * semantics as {@link readWholeText} (regular-file check, binary/NUL rejection,
diff --git a/packages/fs/fs-local/src/index.ts b/packages/fs/fs-local/src/index.ts
index 7c50532a0e..22fc6310fb 100644
--- a/packages/fs/fs-local/src/index.ts
+++ b/packages/fs/fs-local/src/index.ts
@@ -27,6 +27,7 @@ import {
   probe,
   probeNoFollow,
   readForEdit,
+  readByteWindow,
   readTextForDiff,
   readWholeBytes,
   readWholeText,
@@ -156,6 +157,10 @@ export class LocalFileSystem extends FileSystem {
     return readWholeBytes({ displayPath: target.displayPath, targetKey: target.targetKey }, signal, maxBytes, this.internals)
   }
 
+  override async readByteRange(target: FsTarget, range: { offset: number; length: number }, signal?: AbortSignal): Promise<Uint8Array> {
+    return readByteWindow({ displayPath: target.displayPath, targetKey: target.targetKey }, range, signal)
+  }
+
   override async listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]> {
     const entries = await listDirectory({ displayPath: target.displayPath, targetKey: target.targetKey }, signal)
     return entries.map(entry => ({
diff --git a/packages/fs/fs-local/tests/filesystem.spec.ts b/packages/fs/fs-local/tests/filesystem.spec.ts
index b791b424fb..9b88e4cad3 100644
--- a/packages/fs/fs-local/tests/filesystem.spec.ts
+++ b/packages/fs/fs-local/tests/filesystem.spec.ts
@@ -308,6 +308,45 @@ describe('readBytes', () => {
   })
 })
 
+describe('readByteRange', () => {
+  /** 256 bytes, each equal to its offset. */
+  const ramp = Buffer.from(Array.from({ length: 256 }, (_, i) => i))
+
+  it('reads a window from the middle of a file larger than the window', async () => {
+    await writeFile(join(dir, 'ramp.bin'), ramp)
+    const window = await fs.readByteRange(await fs.resolve('ramp.bin'), { offset: 100, length: 4 })
+    expect([...window]).toEqual([100, 101, 102, 103])
+  })
+
+  it('shortens a window the file ends inside and empties one at or past the end', async () => {
+    await writeFile(join(dir, 'ramp.bin'), ramp)
+    const target = await fs.resolve('ramp.bin')
+    expect([...await fs.readByteRange(target, { offset: 253, length: 10 })]).toEqual([253, 254, 255])
+    expect((await fs.readByteRange(target, { offset: 256, length: 10 })).length).toBe(0)
+    expect((await fs.readByteRange(target, { offset: 1000, length: 10 })).length).toBe(0)
+  })
+
+  it('returns an empty window for length 0 without touching content', async () => {
+    await writeFile(join(dir, 'ramp.bin'), ramp)
+    expect((await fs.readByteRange(await fs.resolve('ramp.bin'), { offset: 0, length: 0 })).length).toBe(0)
+  })
+
+  it('carries NUL and invalid UTF-8 untouched', async () => {
+    const raw = Buffer.from([0x00, 0xff, 0xfe, 0x41])
+    await writeFile(join(dir, 'a.bin'), raw)
+    expect(Buffer.from(await fs.readByteRange(await fs.resolve('a.bin'), { offset: 0, length: 4 }))).toEqual(raw)
+  })
+
+  it('rejects a missing file, a directory, and an already-aborted signal', async () => {
+    await expect(fs.readByteRange(await fs.resolve('nope'), { offset: 0, length: 1 })).rejects.toMatchObject({ code: 'FS_NOT_FOUND' })
+    await expect(fs.readByteRange(await fs.resolve('.'), { offset: 0, length: 1 })).rejects.toMatchObject({ code: 'FS_NOT_REGULAR_FILE' })
+    await writeFile(join(dir, 'a.bin'), 'data')
+    const controller = new AbortController()
+    controller.abort()
+    await expect(fs.readByteRange(await fs.resolve('a.bin'), { offset: 0, length: 1 }, controller.signal)).rejects.toMatchObject({ code: 'FS_ABORTED' })
+  })
+})
+
 describe('listDir', () => {
   it('lists files and directories in stable name order with resolved child targets', async () => {
     await mkdir(join(dir, 'skills', 'dir-skill'), { recursive: true })
diff --git a/packages/fs/fs-sandbox/tests/fs-sandbox.spec.ts b/packages/fs/fs-sandbox/tests/fs-sandbox.spec.ts
index 95ae891808..e445c47553 100644
--- a/packages/fs/fs-sandbox/tests/fs-sandbox.spec.ts
+++ b/packages/fs/fs-sandbox/tests/fs-sandbox.spec.ts
@@ -11,7 +11,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 { tmpdir } from 'node:os'
 import { join, parse } from 'node:path'
 import { Context } from '@deepseek-ai/cordis'
 import { FsError, FsTargetKey } from '@deepseek-ai/dsh-fs'
@@ -20,6 +20,7 @@ import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import { SandboxedFileSystem } from '@deepseek-ai/dsh-fs-sandbox'
+import { assertWorkspaceOutsideTemp, outsideTempWorkspaceParent } from '../../../../scripts/snapshot-workspace-parent.ts'
 
 let base: string
 let workspace: string
@@ -36,13 +37,12 @@ async function boot(mode: SandboxMode): Promise<void> {
   fs = ctx.fs as SandboxedFileSystem
 }
 
-beforeEach(async () => {
-  // Base under HOME, deliberately NOT tmpdir: `workspace-write` grants /tmp and
-  // os.tmpdir() (parity with the bash runner), so an "outside" dir under tmpdir
-  // would be legitimately writable. Sibling dirs under HOME are outside every
-  // grant, so containment failures are real denials. (The bwrap e2e roots its
-  // workspaces under HOME for the same reason.)
-  base = await mkdtemp(join(homedir(), '.dsh-fssbx-'))
+beforeEach(async ({ onTestFinished }) => {
+  // Both siblings must be outside automatic temp grants for containment denials to be meaningful.
+  const directory = await mkdtemp(join(outsideTempWorkspaceParent(), '.dsh-fssbx-'))
+  onTestFinished(async () => { await rm(directory, { recursive: true, force: true }) })
+  base = directory
+  assertWorkspaceOutsideTemp(base)
   workspace = join(base, 'ws')
   outside = join(base, 'out')
   await mkdir(workspace)
@@ -50,7 +50,6 @@ beforeEach(async () => {
 })
 afterEach(async () => {
   await fiber?.dispose()
-  await rm(base, { recursive: true, force: true })
 })
 
 /** Resolve a path through the backend and return its target. */
@@ -183,7 +182,7 @@ describe('workspace-write with the filesystem root as the workspace (a root endi
     const rootFiber = await rootCtx.plugin(SandboxedFileSystem, { cwd: workspace })
     const rootFs = rootCtx.fs as SandboxedFileSystem
     try {
-      const path = join(base, 'anywhere.txt') // under HOME, outside temp — allowed only via the filesystem root
+      const path = join(base, 'anywhere.txt') // outside temp — allowed only via the filesystem root
       await rootFs.writeText(await rootFs.resolve(path), 'anywhere')
       expect(await readFile(path, 'utf8')).toBe('anywhere')
     } finally {
diff --git a/packages/fs/fs/README.i18n.yaml b/packages/fs/fs/README.i18n.yaml
index 52604a6ba0..5086ed032f 100644
--- a/packages/fs/fs/README.i18n.yaml
+++ b/packages/fs/fs/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/fs/fs/README.md
-README.md: cba98c41a77d6fc3508ef2d4ac81a231120f1836
-README.zh.md: 0a8b3f7198f93592603a37c749b58d8735e7d24f
+README.md: b7d0231c87de9073a1ec8eb819872c1d12e247a1
+README.zh.md: 202b71a893950e3d7bd9a49bb13d5b69710f3194
diff --git a/packages/fs/fs/README.md b/packages/fs/fs/README.md
index cba98c41a7..b7d0231c87 100644
--- a/packages/fs/fs/README.md
+++ b/packages/fs/fs/README.md
@@ -52,7 +52,7 @@ The contract is built on one separation and three commitments:
 - **Contract over mechanism.** The service names what a storage layer can do — resolve, stat, read, list, write, edit — and never how it stores bytes. Backends own target identity, execution-world coordinates, decoding, binary rejection, and atomicity.
 - **Policy stays off the base class.** Observed-state, read-before-edit, and version-guarded mutations are a plugin's job (`dsh-fs-observation-policy`), added by supplying the optional guard — so a sandboxed or remote backend inherits no model-facing observation policy.
 - **`editText` stays on the seam.** Version check, literal match, and atomic rewrite share one critical section, so error attribution and one-wins/one-stale concurrency stay correct; a remote backend may implement it as a native compare-and-edit.
-- **Bounds live at this seam.** `readBytes` requires `maxBytes` and fails with `FS_TOO_LARGE` rather than truncating, so no backend ever buffers an unbounded file.
+- **Bounds live at this seam.** `readBytes` requires `maxBytes` and fails with `FS_TOO_LARGE` rather than truncating, so no backend ever buffers an unbounded file. `readByteRange` is bounded by its window instead: a backend transfers at most the requested `length` beyond the prefix it skips, so the caller's cap on `length` is the guard.
 
 ### Source map
 
@@ -63,7 +63,7 @@ The contract is built on one separation and three commitments:
 
 ### How a call flows
 
-Every ordinary operation starts with `resolve(path, { cwd })`, which produces a stable `FsTarget` (an opaque `targetKey` plus a `displayPath` for model/UI output); the same file reached through different paths yields the same key. `processPathFromHostPath(hostPath)` separately maps an absolute host file into this execution world when the backend shares or explicitly maps it, and otherwise returns `undefined`. Reads then go `stat` → `readText`/`streamText`/`readBytes`, listings go `listDir`, and mutations go through one per-target critical section: the optional guard is checked, the new content is applied, and the result is published atomically.
+Every ordinary operation starts with `resolve(path, { cwd })`, which produces a stable `FsTarget` (an opaque `targetKey` plus a `displayPath` for model/UI output); the same file reached through different paths yields the same key. `processPathFromHostPath(hostPath)` separately maps an absolute host file into this execution world when the backend shares or explicitly maps it, and otherwise returns `undefined`. Reads then go `stat` → `readText`/`streamText`/`readBytes`/`readByteRange`, listings go `listDir`, and mutations go through one per-target critical section: the optional guard is checked, the new content is applied, and the result is published atomically.
 
 ### The `fs/*` policy events
 
@@ -109,7 +109,7 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 These limits define when the contract is a poor fit or needs special operational care. They are current package constraints, not a general filesystem comparison or a task backlog.
 
-- **Text-only mutations by contract** — text reads and both mutations reject binary or non-UTF-8 content with `FS_NOT_TEXT`; `readBytes` is the single raw-byte primitive, and binary-safe mutations remain deferred.
+- **Text-only mutations by contract** — text reads and both mutations reject binary or non-UTF-8 content with `FS_NOT_TEXT`; `readBytes` and `readByteRange` are the raw-byte primitives, and binary-safe mutations remain deferred.
 - **Thirteen primitives only** — no delete, rename, copy, or watch; `listDir` lists a single level, with recursion, globbing, pagination, and search out of scope ([directory-listing note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)).
 - **No I/O deadline** — the seam arms no timeout; cancellation is a best-effort optional `AbortSignal` per primitive ([fs family stance](../README.md)).
 - **Resolve-then-operate costs a remote backend two round-trips per tool call** — folding or caching resolution is left to such a backend.
diff --git a/packages/fs/fs/README.zh.md b/packages/fs/fs/README.zh.md
index 0a8b3f7198..202b71a893 100644
--- a/packages/fs/fs/README.zh.md
+++ b/packages/fs/fs/README.zh.md
@@ -52,7 +52,7 @@ kind: "package-reference"
 - **约定高于机制。** 服务只命名存储层能做什么——解析、stat、读取、列出、写入、编辑——绝不规定如何存储字节。后端拥有目标身份、执行世界坐标、解码、二进制拒绝与原子性。
 - **策略不放在基类上。** 已观察状态、编辑前读取与版本防护的变更是插件（`dsh-fs-observation-policy`）的职责，通过提供可选防护来添加——因此沙箱化或远程后端不会继承任何面向模型的观察策略。
 - **`editText` 留在 seam 上。** 版本校验、字面量匹配与原子重写共享同一个临界区，错误归因与一方胜出/一方陈旧的并发语义因此保持正确；远程后端也可以将其实现为原生比较并编辑操作。
-- **界限制在此 seam 上。** `readBytes` 要求 `maxBytes`，并以 `FS_TOO_LARGE` 失败而不是截断，因此任何后端都不会无界缓冲文件。
+- **界限制在此 seam 上。** `readBytes` 要求 `maxBytes`，并以 `FS_TOO_LARGE` 失败而不是截断，因此任何后端都不会无界缓冲文件。`readByteRange` 则以窗口为界：后端最多传输所请求的 `length` 字节（外加为到达 `offset` 而跳过的前缀），因此由调用方对 `length` 的上限承担防护。
 
 ### 源码地图
 
@@ -63,7 +63,7 @@ kind: "package-reference"
 
 ### 调用流程
 
-每个普通操作都以 `resolve(path, { cwd })` 开始，它产生稳定的 `FsTarget`（不透明 `targetKey` 加用于模型/UI 输出的 `displayPath`）；经不同路径到达同一文件会产生相同 key。`processPathFromHostPath(hostPath)` 在后端共享或显式映射宿主文件时，单独把绝对宿主文件映射进此执行世界，否则返回 `undefined`。读取随后执行 `stat` → `readText`/`streamText`/`readBytes`，列出执行 `listDir`，变更则经过每个目标一个临界区：先检查可选防护，应用新内容，再原子发布结果。
+每个普通操作都以 `resolve(path, { cwd })` 开始，它产生稳定的 `FsTarget`（不透明 `targetKey` 加用于模型/UI 输出的 `displayPath`）；经不同路径到达同一文件会产生相同 key。`processPathFromHostPath(hostPath)` 在后端共享或显式映射宿主文件时，单独把绝对宿主文件映射进此执行世界，否则返回 `undefined`。读取随后执行 `stat` → `readText`/`streamText`/`readBytes`/`readByteRange`，列出执行 `listDir`，变更则经过每个目标一个临界区：先检查可选防护，应用新内容，再原子发布结果。
 
 ### `fs/*` 策略事件
 
@@ -109,7 +109,7 @@ kind: "package-reference"
 
 这些限制说明该约定何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是通用文件系统对比或任务积压。
 
-- **变更操作约定只支持文本**：文本读取和两个变更操作都以 `FS_NOT_TEXT` 拒绝二进制/非 UTF-8 内容；`readBytes` 是唯一的原始字节原语，二进制安全的变更操作仍延期。
+- **变更操作约定只支持文本**：文本读取和两个变更操作都以 `FS_NOT_TEXT` 拒绝二进制/非 UTF-8 内容；`readBytes` 与 `readByteRange` 是原始字节原语，二进制安全的变更操作仍延期。
 - **只有十三个原语**：没有删除、重命名、复制或监视；`listDir` 只列出一层，递归、glob、分页与搜索不在范围内（见[目录列出笔记](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)）。
 - **没有 I/O deadline**：该 seam 不启动超时；取消只是每个原语上尽力而为的可选 `AbortSignal`（见[fs 能力族立场](../README.zh.md)）。
 - **先解析后操作使远程后端每次工具调用需要两次往返**：折叠或缓存解析由这种后端自行决定。
diff --git a/packages/fs/fs/src/index.ts b/packages/fs/fs/src/index.ts
index e32890d732..bfa05bf257 100644
--- a/packages/fs/fs/src/index.ts
+++ b/packages/fs/fs/src/index.ts
@@ -211,6 +211,21 @@ export abstract class FileSystem extends Service {
    */
   abstract readBytes(target: FsTarget, signal: AbortSignal | undefined, maxBytes: number): Promise<Uint8Array>
 
+  /**
+   * Read one byte window of the regular file as raw bytes with no decoding or
+   * binary rejection: the bytes at `[offset, offset + length)`, shorter when
+   * the file ends inside the window and empty when `offset` lies at or past
+   * its end. The window is the bound here, not the file: a backend transfers
+   * at most `length` bytes of content beyond the prefix it skips to reach
+   * `offset` and never buffers the whole file, so the caller's cap on `length`
+   * is the guard against unbounded buffering.
+   * @param target - the resolved target to read.
+   * @param range - `offset`, the 0-based first byte, and `length`, the largest byte count; both non-negative integers.
+   * @param signal - aborts the read.
+   * @returns the window's bytes, at most `length` long.
+   */
+  abstract readByteRange(target: FsTarget, range: { offset: number; length: number }, signal?: AbortSignal): Promise<Uint8Array>
+
   /**
    * List direct children of a directory in stable name order. Returns resolved
    * child targets plus cheap metadata only; never reads file contents.
diff --git a/packages/fs/fs/tests/service.spec.ts b/packages/fs/fs/tests/service.spec.ts
index 6fbe1268af..f1b4800042 100644
--- a/packages/fs/fs/tests/service.spec.ts
+++ b/packages/fs/fs/tests/service.spec.ts
@@ -57,6 +57,9 @@ class FakeFileSystem extends FileSystem {
     }
     return bytes
   }
+  override async readByteRange(target: FsTarget, range: { offset: number; length: number }): Promise<Uint8Array> {
+    return new TextEncoder().encode(await this.readText(target)).subarray(range.offset, range.offset + range.length)
+  }
   override async listDir(target: FsTarget): Promise<FsDirEntry[]> {
     if (target.targetKey !== 'skills') throw new FsError(`not a directory: ${target.displayPath}`, 'FS_NOT_DIRECTORY')
     return [
@@ -120,6 +123,17 @@ describe('FileSystem provider seam', () => {
     expect(streamed).toBe(await fs.readText(target))
   })
 
+  it('readByteRange returns the window, shorter at the end and empty past it', async () => {
+    const ctx = new Context()
+    await ctx.plugin(FakeFileSystem)
+    const fs = ctx.fs as FakeFileSystem
+    fs.files.set('a.bin', 'hello')
+    const target = await fs.resolve('a.bin')
+    expect(await fs.readByteRange(target, { offset: 1, length: 3 })).toEqual(new TextEncoder().encode('ell'))
+    expect(await fs.readByteRange(target, { offset: 3, length: 10 })).toEqual(new TextEncoder().encode('lo'))
+    expect(await fs.readByteRange(target, { offset: 9, length: 2 })).toHaveLength(0)
+  })
+
   it('readBytes returns raw content and enforces the byte cap with FS_TOO_LARGE', async () => {
     const ctx = new Context()
     await ctx.plugin(FakeFileSystem)
diff --git a/packages/fs/tool-fs/tests/tools.spec.ts b/packages/fs/tool-fs/tests/tools.spec.ts
index ebb9cf18de..46d0e7dcc3 100644
--- a/packages/fs/tool-fs/tests/tools.spec.ts
+++ b/packages/fs/tool-fs/tests/tools.spec.ts
@@ -81,6 +81,9 @@ class FakeFs extends FileSystem {
     }
     return bytes
   }
+  override async readByteRange(target: FsTarget, range: { offset: number; length: number }): Promise<Uint8Array> {
+    return new TextEncoder().encode(this.files.get(target.targetKey) ?? '').subarray(range.offset, range.offset + range.length)
+  }
   override async listDir(_target: FsTarget): Promise<FsDirEntry[]> {
     return []
   }
diff --git a/packages/goal/goal/README.i18n.yaml b/packages/goal/goal/README.i18n.yaml
index 012470cb5c..95f486f789 100644
--- a/packages/goal/goal/README.i18n.yaml
+++ b/packages/goal/goal/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/goal/goal/README.md
-README.md: 119c5e246494c7cb14c84b18e03ca04155f2158c
-README.zh.md: f17d9fa6b84fff50c3c7263c92725959bde99775
+README.md: c5852d16f3d6a1ebea338a103fc0afceb035df9b
+README.zh.md: c4c9d98e919f65e6c873e6dfe03cc13ec80d3f9d
diff --git a/packages/goal/goal/README.md b/packages/goal/goal/README.md
index 119c5e2464..c5852d16f3 100644
--- a/packages/goal/goal/README.md
+++ b/packages/goal/goal/README.md
@@ -106,14 +106,14 @@ This section explains how the service realizes the behavior above; the observabl
 |---|---|
 | [`src/index.ts`](src/index.ts) | Plugin entry: `GoalService`, config schema, mutations, activation cache, projection unit |
 | [`src/domain.ts`](src/domain.ts) | Durable change payloads, `goal/changed` event, goal message-source attribution |
-| [`src/types.ts`](src/types.ts) | Pure client-safe types: `GoalView`, `GoalSnapshot`, projection-key declaration |
+| [`src/types.ts`](src/types.ts) | Pure client-safe types: `GoalView`, `GoalSnapshot`, `GoalActivationChanged`, projection-key declaration |
 | [`src/fold.ts`](src/fold.ts) | Strict replay fold and decoder for durable goal changes |
 | [`src/runtime.ts`](src/runtime.ts) | `GoalId` brand, `GoalError` codes, change-version constant |
 | [`src/invariant.ts`](src/invariant.ts) | Invariant companion: independent incremental fold over every attached session |
 
 ### Events and attribution
 
-`goal/changed` fires after the durable event commits, with listener failures contained; the payload carries the operation, the exact ref, and the fresh view (absent for a clear tombstone). Admitted continuation rounds are attributed through `GoalMessageSource { goalId, revision, round }` on the `user/message` event, which the strict fold validates as the next admitted round of the current goal.
+`goal/changed` fires after the durable event commits, with listener failures contained; the payload carries the operation, the exact ref, and the fresh view (absent for a clear tombstone). `goal/activation-changed` forwards a process-local `armed`/`disarmed` edge with the exact current ref, or no goal after a clear, without changing durable state. Admitted continuation rounds are attributed through `GoalMessageSource { goalId, revision, round }` on the `user/message` event, which the strict fold validates as the next admitted round of the current goal.
 
 </details>
 
diff --git a/packages/goal/goal/README.zh.md b/packages/goal/goal/README.zh.md
index f17d9fa6b8..c4c9d98e91 100644
--- a/packages/goal/goal/README.zh.md
+++ b/packages/goal/goal/README.zh.md
@@ -106,14 +106,14 @@ view.activation                        // 'armed' | 'disarmed' — not persisted
 |---|---|
 | [`src/index.ts`](src/index.ts) | 插件入口：`GoalService`、config schema、变更、续行启用缓存、投影单元 |
 | [`src/domain.ts`](src/domain.ts) | 持久变更载荷、`goal/changed` 事件、goal 消息来源归属 |
-| [`src/types.ts`](src/types.ts) | 纯客户端安全类型：`GoalView`、`GoalSnapshot`、投影键声明 |
+| [`src/types.ts`](src/types.ts) | 纯客户端安全类型：`GoalView`、`GoalSnapshot`、`GoalActivationChanged`、投影键声明 |
 | [`src/fold.ts`](src/fold.ts) | 持久 goal 变更的严格回放折叠与解码器 |
 | [`src/runtime.ts`](src/runtime.ts) | `GoalId` 品牌、`GoalError` 代码、变更版本常量 |
 | [`src/invariant.ts`](src/invariant.ts) | 不变式伴生：对每个已挂接会话的独立增量折叠 |
 
 ### 事件与归属
 
-`goal/changed` 在持久事件提交后触发，监听器失败会被隔离；载荷携带操作、精确 ref 与最新视图（clear tombstone 时省略）。已准入的续行 Round 通过 `user/message` 事件上的 `GoalMessageSource { goalId, revision, round }` 归属，严格折叠会将其验证为当前 goal 的下一个已准入 Round。
+`goal/changed` 在持久事件提交后触发，监听器失败会被隔离；载荷携带操作、精确 ref 与最新视图（clear tombstone 时省略）。`goal/activation-changed` 在不改变持久状态的情况下，转发携带精确当前 ref 的进程本地 `armed`／`disarmed` 边界；clear 后则不携带 goal。已准入的续行 Round 通过 `user/message` 事件上的 `GoalMessageSource { goalId, revision, round }` 归属，严格折叠会将其验证为当前 goal 的下一个已准入 Round。
 
 </details>
 
diff --git a/packages/goal/goal/src/index.ts b/packages/goal/goal/src/index.ts
index 77a8a2495e..8fa9f6d39b 100644
--- a/packages/goal/goal/src/index.ts
+++ b/packages/goal/goal/src/index.ts
@@ -253,16 +253,17 @@ export class GoalService extends TypertRemoteService {
       defaultMaxGoalRounds: resolveMaxGoalRounds(config.defaultMaxGoalRounds ?? 256),
     }
     ctx.on('agent/session-start', ({ agent }) => {
-      this.runtimeState(agent.session).activation = 'disarmed'
+      this.setActivation(agent.session, 'disarmed')
     })
     ctx.sessionProjections.register(goalProjectionDefinition)
     ctx.on('session/event', (session, event) => {
       if (event.type !== 'goal/change') return
       const runtime = this.runtimeState(session)
-      runtime.activation = runtime.pendingActivation !== undefined
+      const activation = runtime.pendingActivation !== undefined
         && SessionSeq(runtime.pendingActivation.offset) === event.seq
         ? runtime.pendingActivation.activation
         : 'disarmed'
+      this.setActivation(session, activation)
     })
   }
 
@@ -272,6 +273,7 @@ export class GoalService extends TypertRemoteService {
    * @returns a fresh view or `undefined` when no goal is current.
    * @throws {@link GoalError} when the agent is not the registry's live instance.
    */
+  @Remote('get')
   get(agent: Agent): GoalView | undefined {
     this.assertLive(agent)
     return this.view(this.state(agent.session), this.runtimeState(agent.session))
@@ -286,8 +288,8 @@ export class GoalService extends TypertRemoteService {
    */
   disarm(agent: Agent): GoalView | undefined {
     this.assertLive(agent)
+    this.setActivation(agent.session, 'disarmed')
     const runtime = this.runtimeState(agent.session)
-    runtime.activation = 'disarmed'
     return this.view(this.state(agent.session), runtime)
   }
 
@@ -490,6 +492,28 @@ export class GoalService extends TypertRemoteService {
     return runtime
   }
 
+  /** Publish one process-local activation edge when it actually changes. */
+  private setActivation(session: Session, activation: GoalActivation): void {
+    const runtime = this.runtimeState(session)
+    if (runtime.activation === activation) return
+    runtime.activation = activation
+    const state = this.ctx.sessionProjections.stateOf(session, 'goal')
+    /* v8 ignore next -- static inject requires the projection registry before this service activates. */
+    if (state === undefined) return
+    if (state.failure !== null) return
+    const goal = this.view(state.current, runtime)
+    this.ctx.emit('goal/activation-changed', {
+      sessionId: session.id,
+      ...goal === undefined ? {} : {
+        goal: {
+          id: goal.id,
+          revision: goal.revision,
+          activation: goal.activation,
+        },
+      },
+    })
+  }
+
   /** Build a new revision with one replacement phase. */
   private withPhase(current: GoalSnapshot, phase: GoalPhase): GoalSnapshot {
     return {
diff --git a/packages/goal/goal/src/types.ts b/packages/goal/goal/src/types.ts
index bb7d8b9e1c..eb7cd602ed 100644
--- a/packages/goal/goal/src/types.ts
+++ b/packages/goal/goal/src/types.ts
@@ -11,6 +11,7 @@
  */
 
 import type { Branded } from '@deepseek-ai/dsh-brand'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
 
 /** Identifies one goal across its durable revisions. */
 export type GoalId = Branded<'GoalId'>
@@ -70,6 +71,21 @@ export interface GoalSnapshot extends GoalRef {
 /** Whether this live process may automatically continue an active goal. */
 export type GoalActivation = 'armed' | 'disarmed'
 
+/** Live process-local activation update forwarded to UI clients. */
+export interface GoalActivationChanged {
+  /** Session whose live goal activation changed. */
+  readonly sessionId: SessionId
+  /** Current exact activation, absent when no goal is current. */
+  readonly goal?: {
+    /** Exact current goal identity. */
+    readonly id: GoalId
+    /** Exact current goal revision. */
+    readonly revision: number
+    /** Current process-local continuation state. */
+    readonly activation: GoalActivation
+  }
+}
+
 /** Current goal projection, including values derived from the session log. */
 export interface GoalView extends GoalSnapshot {
   /** Highest admitted round number for this goal. */
@@ -123,3 +139,14 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
     goal: GoalProjection | null
   }
 }
+
+declare module '@deepseek-ai/cordis' {
+  interface Events {
+    /**
+     * Process-local goal activation changed for one session.
+     * @mode emit
+     * @param payload - session id and the exact current goal activation, or no goal after a clear.
+     */
+    'goal/activation-changed'(payload: GoalActivationChanged): void
+  }
+}
diff --git a/packages/goal/goal/tests/goal.spec.ts b/packages/goal/goal/tests/goal.spec.ts
index e3140e9231..ac32cd3765 100644
--- a/packages/goal/goal/tests/goal.spec.ts
+++ b/packages/goal/goal/tests/goal.spec.ts
@@ -227,12 +227,19 @@ describe('GoalService creation and replay', () => {
 
   it('disarms live activation on every session-start edge', async () => {
     const { ctx, agent, session } = await harness()
+    const activations: Array<{ activation: string | undefined; id: string | undefined; revision: number | undefined }> = []
+    ctx.on('goal/activation-changed', ({ goal }) => {
+      activations.push({ activation: goal?.activation, id: goal?.id, revision: goal?.revision })
+    })
     let goal = ctx.goals.create(agent, { objective: 'stay stopped after resume' })
     expect(goal.activation).toBe('armed')
     agentEvents(ctx, agent).emit('agent/session-start', { source: 'resume' })
     expect(ctx.goals.get(agent)?.activation).toBe('disarmed')
     goal = ctx.goals.resume(agent, goal)
     expect(goal).toMatchObject({ phase: 'active', activation: 'armed', revision: 2 })
+    expect(activations.map(entry => entry.activation)).toEqual(['armed', 'disarmed', 'armed'])
+    expect(activations.map(entry => entry.id)).toEqual([goal.id, goal.id, goal.id])
+    expect(activations.map(entry => entry.revision)).toEqual([1, 1, 2])
     expect(() => foldGoal(session.snapshotEvents())).not.toThrow()
   })
 
diff --git a/packages/goal/goal/tests/projection.spec.ts b/packages/goal/goal/tests/projection.spec.ts
index 840141a1da..45cd1ddb37 100644
--- a/packages/goal/goal/tests/projection.spec.ts
+++ b/packages/goal/goal/tests/projection.spec.ts
@@ -10,7 +10,7 @@
 
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
-import AgentRegistry from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { agentEvents } from '@deepseek-ai/dsh-agent'
 import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import SessionStore from '@deepseek-ai/dsh-session'
@@ -212,6 +212,9 @@ describe('goal projection unit', () => {
     const foreignKind = { type: 'goal/change', seq: 4, time: 5, data: { kind: 'not-a-goal-change' } } as never
     expect(applyGoalProjection(state, foreignKind).failure).toMatch(/invalid kind/)
 
+    const failed = { ...state, failure: 'stop replay' }
+    expect(applyGoalProjection(failed, foreignKind)).toBe(failed)
+
     const missingTimestamps = {
       ...state,
       current: { ...current, createdAt: undefined, updatedAt: undefined },
@@ -222,13 +225,17 @@ describe('goal projection unit', () => {
 
   it('fails host goal access when the projection retained a replay failure', async () => {
     const bench = await harness(true)
+    bench.ctx.goals.create(bench.agent, { objective: 'poisoned replay' })
     const failure = 'goal replay failed at session event 0: invalid restored goal stream'
     const state = bench.ctx.sessionProjections.stateOf(bench.session, 'goal')
     expect(state).toBeDefined()
     Object.assign(state!, { failure })
 
+    expect(() => {
+      agentEvents(bench.ctx, bench.agent).emit('agent/session-start', { source: 'resume' })
+    }).not.toThrow()
     expect(() => bench.ctx.goals.get(bench.agent)).toThrow(failure)
-    expect(bench.tailValues().goal).toBeNull()
+    expect(bench.tailValues().goal).toMatchObject({ goal: { objective: 'poisoned replay' } })
   })
 
   it('has no goal key when the goal service is not composed', async () => {
diff --git a/packages/goal/tool-goal/README.i18n.yaml b/packages/goal/tool-goal/README.i18n.yaml
index 1bee722d66..36ecf3798c 100644
--- a/packages/goal/tool-goal/README.i18n.yaml
+++ b/packages/goal/tool-goal/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/goal/tool-goal/README.md
-README.md: 4a63c19352bceb9776a3d2cec003db8d234f6b43
-README.zh.md: b44fcabc5567436348130b0456bc6103a6466d6f
+README.md: 7b088356029021383f4d02e61b3f10b980504ec3
+README.zh.md: f785b58cf915ae545fdf904f9f10bc06c3f98a74
diff --git a/packages/goal/tool-goal/README.md b/packages/goal/tool-goal/README.md
index 4a63c19352..7b08835602 100644
--- a/packages/goal/tool-goal/README.md
+++ b/packages/goal/tool-goal/README.md
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-tool-goal` gives the model three tools over the persisted goal service: `get_goal` reads the current goal, `create_goal` starts a new one, and `update_goal` edits, pauses, resumes, completes, or blocks it. The model may infer a long-running objective from a direct human request and create a goal; updates must carry the exact id and revision read beforehand. Authority is enforced at execution: create, edit, pause, and resume require a direct human turn on a top-level agent, while complete and blocked also accept the current goal round during automatic continuation. A configured threshold (default 3) bounds how soon an autonomous round may self-report `blocked`. Mount it with `dsh-goal` whenever the model should manage goals itself.
+`dsh-tool-goal` gives the model three tools over the persisted goal service: `get_goal` reads the current goal, `create_goal` starts a new one, and `update_goal` edits, pauses, resumes, completes, or blocks it. The model may infer a long-running objective from a direct human request and create a goal; updates must carry the exact id and revision read beforehand. Authority is enforced at execution: create, edit, pause, and resume require a direct human turn on a top-level agent, while complete and blocked also accept the current goal round during automatic continuation. `resume` rearms an active-but-disarmed or blocked goal; the user resumes a durable paused goal through the Web strip or `/goal resume`. A configured threshold (default 3) bounds how soon an autonomous round may self-report `blocked`. Mount it with `dsh-goal` whenever the model should manage goals itself.
 
 ## Table of Contents
 
@@ -52,7 +52,7 @@ The value must be a positive safe integer. It supplies both the hard lower bound
 
 ### Authority rules
 
-The tools execute only for the exact live calling agent inside its active driver with an open turn. `create`, `edit`, `pause`, and `resume` additionally require a direct human message in a runtime-root agent's current turn — a subagent or a non-human producer cannot create or edit goals. `complete` and `blocked` also accept the exact current goal round: a goal-sourced round may complete the goal immediately, but a blocked call is mechanically rejected until the configured number of consecutive rounds has passed — the model judges whether the same condition actually persisted and must describe it in `blocked_reason`. A direct human request may stop a goal immediately.
+The tools execute only for the exact live calling agent inside its active driver with an open turn. `create`, `edit`, `pause`, and `resume` additionally require a direct human message in a runtime-root agent's current turn — a subagent or a non-human producer cannot create or edit goals. `resume` rejects a durable paused goal before the goal service runs; that state belongs to the user-facing resume path. `complete` and `blocked` also accept the exact current goal round: a goal-sourced round may complete the goal immediately, but a blocked call is mechanically rejected until the configured number of consecutive rounds has passed — the model judges whether the same condition actually persisted and must describe it in `blocked_reason`. A direct human request may stop a goal immediately.
 
 An autonomous round that successfully reports `complete` or `blocked` also ends the physical turn after that step, and the model receives a closing instruction to write the final message to the user. Direct-human mutations never trigger that stop: the assistant may acknowledge the change and the loop keeps concurrent human steering available.
 
@@ -68,7 +68,7 @@ This section explains how the tools enforce authority and render output; the obs
 
 ### Design
 
-- **Authority at execution.** Every call resolves the exact live agent, its inherited `AgentRegistry` initiator, running status, and an open turn; `create`, `edit`, `pause`, and `resume` additionally require an accepted `{ kind: 'user' }` message or steering event in a runtime-root agent's current turn. Durable fork lineage does not demote a resumed root; live subagent ownership does.
+- **Authority at execution.** Every call resolves the exact live agent, its inherited `AgentRegistry` initiator, running status, and an open turn; `create`, `edit`, `pause`, and `resume` additionally require an accepted `{ kind: 'user' }` message or steering event in a runtime-root agent's current turn. A durable paused goal fails the `resume` action with `GOAL_TOOL_RESUME_PAUSED`; the user-facing command or Web control owns that transition. Durable fork lineage does not demote a resumed root; live subagent ownership does.
 - **Host attestation of human input.** `{ kind: 'user' }` is assigned by `Agent.followup()` and `steer()` when their caller omits a source, so plugins, schedulers, and other non-human producers must pass their own source rather than inheriting human authority.
 - **System-prompt guidance with the configured threshold.** The package registers one `tool:goal` system-prompt section whose fixed text interpolates `blockedAfterConsecutiveRounds`; the same value is the hard lower bound enforced at execution.
 - **Wrap-up context for terminal rounds.** A successful autonomous `complete` or `blocked` defers a closing `<goal_complete>` or `<goal_blocked>` instruction so the model addresses the user once before the turn ends; direct-human mutations never defer this context.
@@ -109,7 +109,7 @@ The tools are the model-facing half of the goal surface; read these pages for th
 
 #### What the model sees
 
-A fixed goal policy says when semantic human intent warrants creation, requires exact read-before-update refs, explains rearming after resume/fork, and limits completion/blocking claims. The configured threshold is interpolated into that guidance.
+A fixed goal policy says when semantic human intent warrants creation, requires exact read-before-update refs, explains rearming after resume/fork, and limits completion/blocking claims. Durable paused resume is rejected at execution with `GOAL_TOOL_RESUME_PAUSED`; the user-facing goal control owns that transition. The configured threshold is interpolated into that guidance.
 
 ##### Goal policy
 
diff --git a/packages/goal/tool-goal/README.zh.md b/packages/goal/tool-goal/README.zh.md
index b44fcabc55..f785b58cf9 100644
--- a/packages/goal/tool-goal/README.zh.md
+++ b/packages/goal/tool-goal/README.zh.md
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-tool-goal` 为模型提供基于持久 goal 服务的三个工具：`get_goal` 读取当前 goal，`create_goal` 创建新 goal，`update_goal` 编辑、暂停、恢复、完成或阻塞它。模型可以从人类直接请求中推断长期目标并创建 goal；更新必须携带先前读取到的精确 id 与 revision。权限在执行时强制：create、edit、pause 和 resume 要求顶层 agent 的当前轮次中存在人类直接消息；complete 和 blocked 在自动续行期间还接受当前 Goal Round。可配置的阈值（默认 3）约束自主 Round 多快可以自行报告 `blocked`。当模型需要自行管理 goal 时，与 `dsh-goal` 一起挂载它。
+`dsh-tool-goal` 为模型提供基于持久 goal 服务的三个工具：`get_goal` 读取当前 goal，`create_goal` 创建新 goal，`update_goal` 编辑、暂停、恢复、完成或阻塞它。模型可以从人类直接请求中推断长期目标并创建 goal；更新必须携带先前读取到的精确 id 与 revision。权限在执行时强制：create、edit、pause 和 resume 要求顶层 agent 的当前轮次中存在人类直接消息；complete 和 blocked 在自动续行期间还接受当前 Goal Round。`resume` 只重新启用 active-but-disarmed 或 blocked 的 goal；持久的 paused goal 由用户通过 Web 条带或 `/goal resume` 恢复。可配置的阈值（默认 3）约束自主 Round 多快可以自行报告 `blocked`。当模型需要自行管理 goal 时，与 `dsh-goal` 一起挂载它。
 
 ## 目录
 
@@ -52,7 +52,7 @@ kind: "package-reference"
 
 ### 权限规则
 
-工具只为活跃驱动器内、处于开放轮次中的精确活跃调用 agent 执行。`create`、`edit`、`pause` 和 `resume` 还要求运行时根 agent（智能体）的当前轮次中存在人类直接消息——subagent 或非人类生产方不能创建或编辑 goal。`complete` 和 `blocked` 还接受完全一致的当前 Goal Round：来源为 goal 的 Round 可以立即完成 goal，但 blocked 调用在达到配置的连续 Round 数量之前会被机械拒绝——模型判断同一条件是否确实持续，并必须在 `blocked_reason` 中说明。人类直接请求可以立即停止 goal。
+工具只为活跃驱动器内、处于开放轮次中的精确活跃调用 agent 执行。`create`、`edit`、`pause` 和 `resume` 还要求运行时根 agent（智能体）的当前轮次中存在人类直接消息——subagent 或非人类生产方不能创建或编辑 goal。`resume` 会在 goal 服务执行前拒绝持久的 paused goal；该状态只属于面向用户的恢复路径。`complete` 和 `blocked` 还接受完全一致的当前 Goal Round：来源为 goal 的 Round 可以立即完成 goal，但 blocked 调用在达到配置的连续 Round 数量之前会被机械拒绝——模型判断同一条件是否确实持续，并必须在 `blocked_reason` 中说明。人类直接请求可以立即停止 goal。
 
 成功报告 `complete` 或 `blocked` 的自主 Round 还会在该步骤后结束物理轮次，模型会收到一条结束指令，要求向用户写出最终消息。人类直接变更绝不会触发这种停止：assistant 可以确认变更，循环仍可接收并发的人类 steering（中途引导）。
 
@@ -68,7 +68,7 @@ kind: "package-reference"
 
 ### 设计
 
-- **执行时权限。** 每次调用都解析精确活跃 agent、其继承的 `AgentRegistry` initiator、running 状态与开放轮次；`create`、`edit`、`pause` 和 `resume` 还要求运行时根 agent 的当前轮次中存在已接受的 `{ kind: 'user' }` 消息或 steering 事件。持久 fork 谱系不会降低已恢复根 agent 的等级；活跃 subagent 所有权会降低。
+- **执行时权限。** 每次调用都解析精确活跃 agent、其继承的 `AgentRegistry` initiator、running 状态与开放轮次；`create`、`edit`、`pause` 和 `resume` 还要求运行时根 agent 的当前轮次中存在已接受的 `{ kind: 'user' }` 消息或 steering 事件。持久的 paused goal 会让 `resume` 以 `GOAL_TOOL_RESUME_PAUSED` 失败；面向用户的命令或 Web 控件拥有该转换。持久 fork 谱系不会降低已恢复根 agent 的等级；活跃 subagent 所有权会降低。
 - **人类输入的宿主证明。** `Agent.followup()` 与 `steer()` 会在调用方省略 source 时分配 `{ kind: 'user' }`，因此插件、调度器与其他非人类生产方必须传入自己的 source，不能继承人类权限。
 - **带配置阈值的系统提示词指引。** 本包注册一个 `tool:goal` 系统提示词章节，其固定文本插入 `blockedAfterConsecutiveRounds`；同一数值就是执行时强制执行的硬下限。
 - **终局 Round 的结束上下文。** 成功的自主 `complete` 或 `blocked` 会延后一条 `<goal_complete>` 或 `<goal_blocked>` 结束指令，让模型在轮次结束前向用户做一次交代；人类直接变更绝不会延后该上下文。
@@ -109,7 +109,7 @@ kind: "package-reference"
 
 #### 模型看到的内容
 
-固定 goal 策略说明何种用户语义意图值得创建 goal，要求更新前先精确读取 ref，解释会话 resume／fork 后如何重新启用续行，并限制完成／阻塞声明。配置的阈值会插入该指引。
+固定 goal 策略说明何种用户语义意图值得创建 goal，要求更新前先精确读取 ref，解释会话 resume／fork 后如何重新启用续行，并限制完成／阻塞声明。持久 paused 的 resume 会在执行时以 `GOAL_TOOL_RESUME_PAUSED` 拒绝；面向用户的 goal 控件拥有该转换。配置的阈值会插入该指引。
 
 ##### Goal 策略
 
diff --git a/packages/goal/tool-goal/src/index.ts b/packages/goal/tool-goal/src/index.ts
index 4a650ccdef..a63f066aa4 100644
--- a/packages/goal/tool-goal/src/index.ts
+++ b/packages/goal/tool-goal/src/index.ts
@@ -276,6 +276,14 @@ export function apply(ctx: Context, config: Config): void {
             'GOAL_TOOL_INVALID_UPDATE',
           )
         }
+        const current = ctx.goals.get(execution.agent)
+        if (args.action === 'resume' && current?.id === ref.id && current.revision === ref.revision
+          && current.phase === 'paused') {
+          throw new HarnessError(
+            'the model cannot resume a paused goal; the user must resume it',
+            'GOAL_TOOL_RESUME_PAUSED',
+          )
+        }
         const goal = args.action === 'pause'
           ? ctx.goals.pause(execution.agent, ref)
           : ctx.goals.resume(execution.agent, ref)
diff --git a/packages/goal/tool-goal/tests/tool-goal.spec.ts b/packages/goal/tool-goal/tests/tool-goal.spec.ts
index 533b6aa6c6..b4b4d54808 100644
--- a/packages/goal/tool-goal/tests/tool-goal.spec.ts
+++ b/packages/goal/tool-goal/tests/tool-goal.spec.ts
@@ -353,7 +353,7 @@ describe('goal tool execution authority', () => {
 })
 
 describe('goal tool state transitions', () => {
-  it('reads null, then edits, pauses, and resumes by exact revision in one human turn', async () => {
+  it('reads null, then edits and pauses by exact revision in one human turn', async () => {
     const { ctx, root } = await harness()
     openTurn(root, { kind: 'user' })
     expect(resultJson(await execute(ctx, 'get_goal', {}, root.agent))).toEqual({ goal: null })
@@ -367,10 +367,31 @@ describe('goal tool state transitions', () => {
       goal_id: goal['id'], revision: goal['revision'], action: 'pause',
     }, root.agent))
     expect(goal).toMatchObject({ phase: 'paused', revision: 3 })
-    goal = resultGoal(await execute(ctx, 'update_goal', {
+    const rejected = await execute(ctx, 'update_goal', {
       goal_id: goal['id'], revision: goal['revision'], action: 'resume',
+    }, root.agent)
+    expect(rejected.error?.info?.code).toBe('GOAL_TOOL_RESUME_PAUSED')
+    const resumed = ctx.goals.resume(root.agent, {
+      id: GoalId(goal['id'] as string), revision: goal['revision'] as number,
+    })
+    expect(resumed).toMatchObject({ phase: 'active', revision: 4 })
+  })
+
+  it('rejects update_goal resume of a durable paused goal in a later human turn', async () => {
+    const { ctx, root } = await harness()
+    const firstTurn = openTurn(root, { kind: 'user' })
+    let goal = resultGoal(await execute(ctx, 'create_goal', { objective: 'pause me' }, root.agent))
+    goal = resultGoal(await execute(ctx, 'update_goal', {
+      goal_id: goal['id'], revision: goal['revision'], action: 'pause',
     }, root.agent))
-    expect(goal).toMatchObject({ phase: 'active', revision: 4 })
+    closeTurn(root, firstTurn)
+
+    openTurn(root, { kind: 'user' }, 'later unrelated request')
+    const rejected = await execute(ctx, 'update_goal', {
+      goal_id: goal['id'], revision: goal['revision'], action: 'resume',
+    }, root.agent)
+    expect(rejected.error?.info?.code).toBe('GOAL_TOOL_RESUME_PAUSED')
+    expect(ctx.goals.get(root.agent)).toMatchObject({ phase: 'paused', activation: 'disarmed' })
   })
 
   it('injects one wrap-up instruction for an autonomous completion but leaves a human pause interactive', async () => {
@@ -383,13 +404,11 @@ describe('goal tool state transitions', () => {
     expect(resultGoal(paused)).toMatchObject({ phase: 'paused' })
     expect(paused.concludesTurn).toBeUndefined()
     expect(paused.additionalContexts).toBeUndefined()
-    const resumed = resultGoal(await execute(ctx, 'update_goal', {
-      goal_id: created.id, revision: 2, action: 'resume',
-    }, root.agent))
+    const resumed = ctx.goals.resume(root.agent, { id: created.id, revision: 2 })
     closeTurn(root, humanTurn)
 
     openTurn(root, {
-      kind: 'goal', goalId: created.id, revision: resumed['revision'] as number, round: 1,
+      kind: 'goal', goalId: created.id, revision: resumed['revision'], round: 1,
     })
     const complete = await execute(ctx, 'update_goal', {
       goal_id: created.id, revision: resumed['revision'], action: 'complete',
@@ -522,6 +541,8 @@ describe('goal tool state transitions', () => {
     }, root.agent)
     expect(resultGoal(paused)).toMatchObject({ phase: 'paused', objective: 'edited' })
     goal = ctx.goals.get(root.agent)!
+    goal = ctx.goals.resume(root.agent, { id: goal.id, revision: goal.revision })
+    goal = ctx.goals.disarm(root.agent)!
 
     const resumed = await execute(ctx, 'update_goal', {
       goal_id: goal.id,
diff --git a/packages/skill/skill-filesystem/tests/skill-filesystem.spec.ts b/packages/skill/skill-filesystem/tests/skill-filesystem.spec.ts
index 054535d7e7..005c89b10c 100644
--- a/packages/skill/skill-filesystem/tests/skill-filesystem.spec.ts
+++ b/packages/skill/skill-filesystem/tests/skill-filesystem.spec.ts
@@ -108,6 +108,10 @@ class TestFileSystem extends FileSystem {
     throw new Error('not needed in skill tests')
   }
 
+  override async readByteRange(_target: FsTarget, _range: { offset: number; length: number }, _signal?: AbortSignal): Promise<Uint8Array> {
+    throw new Error('not needed in skill tests')
+  }
+
   override async listDir(target: FsTarget): Promise<FsDirEntry[]> {
     this.listDirCalls += 1
     if (this.failListDirPaths.has(target.displayPath)) throw new Error('list temporarily failed')
diff --git a/packages/subagent/subagent-acp/tests/mock-acp-server.ts b/packages/subagent/subagent-acp/tests/mock-acp-server.ts
index 8cda16b3f5..ac591431f5 100644
--- a/packages/subagent/subagent-acp/tests/mock-acp-server.ts
+++ b/packages/subagent/subagent-acp/tests/mock-acp-server.ts
@@ -34,6 +34,8 @@
  *                        handler is in flight (it has streamed its chunk). A test
  *                        polls for this file to cancel on a CONDITION rather than
  *                        an arbitrary timeout (subprocess cold-start is variable).
+ * - `MOCK_PROMPT_HOLD` — if set, prompt waits while this file exists; removing
+ *                        it releases the response without a timing assumption.
  * - `MOCK_MISSING_SESSION_ID` — if `1`, return a malformed empty `session/new`
  *                        response to exercise startup rollback.
  * - `MOCK_FLUSH_ON_EOF` — if set, on stdin EOF the agent takes an async beat
@@ -59,7 +61,8 @@
  */
 
 import { randomUUID } from 'node:crypto'
-import { existsSync, writeFileSync } from 'node:fs'
+import { existsSync, watch, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
 import { Readable, Writable } from 'node:stream'
 import {
   agent as createAcpAgentApp,
@@ -141,6 +144,19 @@ function makeAgent() {
     },
     async prompt(params: PromptRequest, conn: AgentContext): Promise<PromptResponse> {
       if (CRASH_ON_PROMPT) process.exit(1)
+      const hold = process.env.MOCK_PROMPT_HOLD
+      if (hold !== undefined) {
+        const released = Promise.withResolvers<undefined>()
+        const check = (): void => { if (!existsSync(hold)) released.resolve(undefined) }
+        const watcher = watch(dirname(hold), check)
+        watcher.on('error', released.reject)
+        try {
+          check()
+          await released.promise
+        } finally {
+          watcher.close()
+        }
+      }
       if (WANT_PERMISSION) {
         // Ask the client to approve before answering; honor its decision. Under
         // MOCK_NO_ALLOW the only options are reject-shaped, so an `allow`-policy
diff --git a/packages/test-support/session-snapshot/README.i18n.yaml b/packages/test-support/session-snapshot/README.i18n.yaml
index 139ccadd3e..46d058dadf 100644
--- a/packages/test-support/session-snapshot/README.i18n.yaml
+++ b/packages/test-support/session-snapshot/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/test-support/session-snapshot/README.md
-README.md: 12acb8d426a2966a852f98d85843d3c246ffeb5f
-README.zh.md: 0b30cbf205f6055ef7b11b791d47adb38f6f704d
+README.md: f1126920969cead7844712ad3b2c7213cce19ed9
+README.zh.md: 65e04f252a13c22351b450da2df44f244d484811
diff --git a/packages/test-support/session-snapshot/README.md b/packages/test-support/session-snapshot/README.md
index 12acb8d426..f112692096 100644
--- a/packages/test-support/session-snapshot/README.md
+++ b/packages/test-support/session-snapshot/README.md
@@ -72,7 +72,7 @@ Each recorded-session directory carries a closed `snapshot.yml` manifest plus ca
 
 `normalizeSessionSnapshot` retains the complete Session header and event payloads but omits top-level `seq`/`time` envelopes from committed fixtures after normalizing paths and scrubbing request headers; it also normalizes embedded stream clocks and historical packed-row `seq0`/`time0` envelopes. Replay synthesizes the top-level envelopes in memory, while runtime persistence continues to write complete logs. Multi-session comparison restores every selected persisted or projected fixture through the current build-static Session format catalog before identity redaction and normalization, so retained v0/v1 replay input and fresh `session.v2.jsonl` writer output compare as one v2 logical Session without rewriting or renaming historical files. Expected and harvested logs use the same strict restoration path; source filenames cannot alter format validation. Versionless protocol-adapter unit fixtures remain outside the released Session format corpus. Current v2 fixtures use one row per event; retained v0/v1 fixtures may use canonical packed rows. The [temporary repository migrator](../../../scripts/migrate-packed-session-fixtures.ts) (`pnpm run migrate:packed-session-fixtures`) rewrites older historical layouts, and its [removal proposal](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md) owns its deletion.
 
-Known snapshot spill paths normalize to stable locator tokens, including paths quoted inside JSON omission notices with JSON-escaped Windows separators. Refresh extraction preserves the matched serialized path spelling for literal replacement. Normalization changes only the locator: saved byte lengths and omission counts remain comparison evidence.
+Spill scenarios save through the real local provider under a private temporary root. Their fixture adapter exposes fixed-length logical locators and maps only this run’s saved locators back to real files for retrieval, preserving preview budgets without writing into a shared logical path. Known snapshot spill paths normalize to stable locator tokens, including paths quoted inside JSON omission notices with JSON-escaped Windows separators. Refresh extraction preserves the matched serialized path spelling for literal replacement. Normalization changes only the locator: saved byte lengths and omission counts remain comparison evidence.
 
 ### Record, replay, and refresh
 
@@ -84,7 +84,7 @@ A pin owns its generated `system-prompt.expected.md` or `tool-schemas.expected.j
 
 ### Platform and composition variants
 
-A scenario requiring a non-Windows host declares `posixOnly`, which skips its run test on Windows while the fixture guards keep covering its committed files everywhere; a scenario whose composition needs a usable `pwsh` declares `pwshOnly`. `workspaceParent` moves the generated child cwd outside the platform temp directory when temporary-directory grants are themselves under test; a scenario's committed `workspace/` is copied into that child first, then `prepareWorkspace` runs against the generated cwd before the agent starts. Default generated workspaces are stored in session fixtures as `{{cwd}}`, so platform temp roots and random basenames do not affect recordings.
+A scenario requiring a non-Windows host declares `posixOnly`, which skips its run test on Windows while the fixture guards keep covering its committed files everywhere; a scenario whose composition needs a usable `pwsh` declares `pwshOnly`. `workspaceParent` moves the generated child cwd outside the platform temp directory when temporary-directory grants are themselves under test; a scenario's committed `workspace/` is copied into that child first, then `prepareWorkspace` runs against the generated cwd before the agent starts. Default generated workspaces are stored in session fixtures as `{{cwd}}`, so platform temp roots and random basenames do not affect recordings. Headless manifests use `workspace.parent: outside-temp` when the Session workspace grant itself is under test. The adapter allocates beside the platform temp root when its parent is writable and outside system temporary grants, otherwise under home, and rejects any generated cwd already covered by automatic temporary write grants.
 
 ### What can go wrong
 
diff --git a/packages/test-support/session-snapshot/README.zh.md b/packages/test-support/session-snapshot/README.zh.md
index 0b30cbf205..65e04f252a 100644
--- a/packages/test-support/session-snapshot/README.zh.md
+++ b/packages/test-support/session-snapshot/README.zh.md
@@ -72,7 +72,7 @@ defineAcpSnapshotSuite({
 
 `normalizeSessionSnapshot` 在规范化路径并清理 request header 后，会保留完整 Session header 与事件 payload，但从已提交 fixture 中省略顶层 `seq`/`time` envelope；它还会规范化嵌入式 stream clock 与历史 packed-row 的 `seq0`/`time0` envelope。Replay 只在内存中合成顶层 envelope，而运行时持久化仍写入完整日志。多 Session 比较会先通过当前构建期静态 Session 格式目录恢复每个选定的持久化或投影 fixture，再进行身份脱敏与规范化，因此保留的 v0/v1 replay 输入与新生成的 `session.v2.jsonl` writer 输出会作为同一个 v2 logical Session 比较，且不会重写或重命名历史文件。预期日志与收集日志使用同一条严格恢复路径；来源文件名不能改变格式校验。无版本的协议适配器单元测试 fixture 不属于已发布 Session 格式语料。当前 v2 fixture 每个事件占一行；保留的 v0/v1 fixture 可以使用规范 packed row。[临时仓库迁移器](../../../scripts/migrate-packed-session-fixtures.ts)（`pnpm run migrate:packed-session-fixtures`）会改写更旧的历史布局，由其[移除提案](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.zh.md)负责删除该迁移器。
 
-已知的快照 spill 路径会规范化为稳定的定位信息 token，包括 JSON 省略通知中带引号、使用 JSON 转义 Windows 分隔符的路径。刷新提取会保留匹配路径的序列化写法，以便进行字面替换。规范化只改变定位信息：保存字节数与省略计数仍作为比较证据。
+Spill 场景通过真实本地 provider 保存到私有临时根目录。夹具适配器提供固定长度的逻辑定位符，并仅将本次运行已保存的定位符映射回实际文件以供检索，在不写入共享逻辑路径的情况下保留预览预算。已知的快照 spill 路径会规范化为稳定的定位信息 token，包括 JSON 省略通知中带引号、使用 JSON 转义 Windows 分隔符的路径。刷新提取会保留匹配路径的序列化写法，以便进行字面替换。规范化只改变定位信息：保存字节数与省略计数仍作为比较证据。
 
 ### 录制、回放与刷新
 
@@ -84,7 +84,7 @@ defineAcpSnapshotSuite({
 
 ### 平台与组合变体
 
-需要非 Windows 主机的场景声明 `posixOnly`，在 Windows 上跳过运行测试，但 fixture 保护仍在所有平台覆盖其已提交文件；组合需要可用 `pwsh` 的场景声明 `pwshOnly`。当临时目录授权自身待测时，`workspaceParent` 将生成子级 cwd 移出平台临时区域；场景签入的 `workspace/` 会先复制到该子级，随后 `prepareWorkspace` 在 agent 启动前针对生成 cwd 运行。默认生成的 workspace 在会话 fixture 中存储为 `{{cwd}}`，使平台临时根目录与随机 basename 不影响录制。
+需要非 Windows 主机的场景声明 `posixOnly`，在 Windows 上跳过运行测试，但 fixture 保护仍在所有平台覆盖其已提交文件；组合需要可用 `pwsh` 的场景声明 `pwshOnly`。当临时目录授权自身待测时，`workspaceParent` 将生成子级 cwd 移出平台临时区域；场景签入的 `workspace/` 会先复制到该子级，随后 `prepareWorkspace` 在 agent 启动前针对生成 cwd 运行。默认生成的 workspace 在会话 fixture 中存储为 `{{cwd}}`，使平台临时根目录与随机 basename 不影响录制。 Headless manifest 在测试 Session workspace 授权本身时使用 `workspace.parent: outside-temp`。适配器在父目录可写且位于系统临时授权之外时，于平台临时根目录旁分配目录，否则使用 home，并拒绝已被自动临时写授权覆盖的生成 cwd。
 
 ### 可能出什么问题
 
diff --git a/packages/test-support/session-snapshot/src/harness.ts b/packages/test-support/session-snapshot/src/harness.ts
index 4490e08df9..cd54f516ae 100644
--- a/packages/test-support/session-snapshot/src/harness.ts
+++ b/packages/test-support/session-snapshot/src/harness.ts
@@ -210,7 +210,7 @@ export interface RunOptions {
 }
 
 /**
- * Derive one stable, fixed-length spill root owned by this scenario.
+ * Derive the stable, fixed-length logical spill prefix; never allocate files here.
  * Windows uses a two-character-shorter root because drive resolution adds its drive prefix.
  * @param fixtureFile - The scenario fixture whose parent directory provides the stable identity.
  * @param platform - the host platform, injectable for unit coverage.
@@ -239,17 +239,14 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise
   const cwd = await mkdtemp(join(opts.workspaceParent ?? tmpdir(), 'acp-snap-cwd-'))
   const cwdAliases = [...new Set([realpathSync(cwd), realpathSync.native(cwd)])]
   const sessionsRoot = await mkdtemp(join(tmpdir(), 'acp-snap-sessions-'))
-  // Fixed path length: spill-policy budgets the preview against the REAL path
-  // before stdout normalization, so tmpdir() length differences churn expected outputs.
-  // Scenario ownership also matters: replay runs concurrently, and one teardown
-  // must never delete another scenario's in-flight full-output recovery file.
-  const spillRoot = snapshotSpillRoot(opts.fixtureFile)
+  let spillRoot: string | undefined
   // Everything past the temp-dir creation is followed by failure-safe cleanup,
   // so a failure in workspace seeding, spawn, or any step never leaks resources.
   let launched: LaunchedAcpTestAgent | undefined
   let sessionId: string | undefined
   let sessionLogs: HarvestedLog[] = []
   const outcome = await (async (): Promise<RunResult> => {
+    spillRoot = await mkdtemp(join(tmpdir(), 'acp-snap-spill-'))
     // Seed the workspace if the scenario ships one (a file the agent reads/edits).
     // Copied into the generated cwd so the agent's bash tools see it; the expected outputs
     // normalize the cwd, so the seeded paths stay stable across runs.
@@ -272,6 +269,7 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise
       DSH_SNAPSHOT_FILE: opts.fixtureFile,
       DSH_SNAPSHOT_SESSIONS_ROOT: sessionsRoot,
       DSH_SNAPSHOT_SPILL_ROOT: spillRoot,
+      DSH_SNAPSHOT_SPILL_LOCATOR_ROOT: snapshotSpillRoot(opts.fixtureFile),
       DSH_HOME: join(cwd, '.dsh'),
       DSH_AGENTS_HOME: join(cwd, '.agents'),
       ...opts.overrideFile !== undefined ? { DSH_SNAPSHOT_OVERRIDE: opts.overrideFile } : {},
@@ -383,7 +381,8 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise
   await cleanup(() => launched?.close('SIGKILL') ?? Promise.resolve())
   await cleanup(() => rm(cwd, { recursive: true, force: true }))
   await cleanup(() => rm(sessionsRoot, { recursive: true, force: true }))
-  await cleanup(() => rm(spillRoot, { recursive: true, force: true }))
+  const allocatedSpillRoot = spillRoot
+  if (allocatedSpillRoot !== undefined) await cleanup(() => rm(allocatedSpillRoot, { recursive: true, force: true }))
 
   const cleanupFailures = cleanupResults
     .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
diff --git a/packages/test-support/session-snapshot/src/manifest.ts b/packages/test-support/session-snapshot/src/manifest.ts
index 1294af0d50..80f46b5ec1 100644
--- a/packages/test-support/session-snapshot/src/manifest.ts
+++ b/packages/test-support/session-snapshot/src/manifest.ts
@@ -45,8 +45,8 @@ export interface SnapshotWorkspaceManifest {
   setup?: string
   /** Whether `workspace.expected/` owns the complete final world state. */
   final?: true
-  /** Place the generated cwd under the user's home instead of a temporary root. */
-  parent?: 'home'
+  /** Place the generated cwd outside automatically writable temporary roots. */
+  parent?: 'outside-temp'
 }
 
 /** Controller input that cannot enter a session because admission rejects it. */
@@ -314,13 +314,13 @@ export function parseSnapshotManifest(source: string, path = 'snapshot.yml'): Sn
       if (value.final !== undefined && value.final !== true) {
         throw new Error('manifest.workspace.final must equal true when present')
       }
-      if (value.parent !== undefined && value.parent !== 'home') {
-        throw new Error('manifest.workspace.parent must equal home')
+      if (value.parent !== undefined && value.parent !== 'outside-temp') {
+        throw new Error('manifest.workspace.parent must equal outside-temp')
       }
       workspace = {
         ...(value.setup === undefined ? {} : { setup: name(value.setup, 'manifest.workspace.setup') }),
         ...(value.final === true ? { final: true as const } : {}),
-        ...(value.parent === 'home' ? { parent: 'home' as const } : {}),
+        ...(value.parent === 'outside-temp' ? { parent: 'outside-temp' as const } : {}),
       }
       if (Object.keys(workspace).length === 0) throw new Error('manifest.workspace must not be empty')
     }
diff --git a/packages/test-support/session-snapshot/tests/harness.spec.ts b/packages/test-support/session-snapshot/tests/harness.spec.ts
index 508fd2b635..089b68526c 100644
--- a/packages/test-support/session-snapshot/tests/harness.spec.ts
+++ b/packages/test-support/session-snapshot/tests/harness.spec.ts
@@ -8,12 +8,22 @@ import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
 import { runScenario, snapshotSpillRoot, type AgentUnderTest, type InputStep } from '../src/harness.ts'
 import { launchAcpTestAgent } from '../src/launcher.ts'
 
-const fsControl = vi.hoisted(() => ({ cleanupFailure: undefined as Error | undefined }))
+const fsControl = vi.hoisted(() => ({
+  cleanupFailure: undefined as Error | undefined,
+  spillAllocationFailure: undefined as { error: Error; allocated: string[] } | undefined,
+}))
 
 vi.mock('node:fs/promises', async (importOriginal) => {
   const actual = await importOriginal<typeof import('node:fs/promises')>()
   return {
     ...actual,
+    async mkdtemp(prefix: string): Promise<string> {
+      const failure = fsControl.spillAllocationFailure
+      if (prefix.endsWith('acp-snap-spill-') && failure !== undefined) throw failure.error
+      const path = await actual.mkdtemp(prefix)
+      failure?.allocated.push(path)
+      return path
+    },
     async rm(...args: Parameters<typeof actual.rm>): Promise<void> {
       if (String(args[0]).includes('acp-snap-cwd-') && fsControl.cleanupFailure !== undefined) {
         const failure = fsControl.cleanupFailure
@@ -569,9 +579,28 @@ describe('runScenario', () => {
     expect(env.childFiles).toBe(childFiles.join(delimiter))
   })
 
-  it('gives concurrent scenarios distinct equal-length spill roots', { timeout: 20_000 }, async () => {
-    const [first, second] = await Promise.all([scenario({ echoEnv: true }), scenario({ echoEnv: true })])
-    const results = await Promise.all([first, second].map(({ fixtureFile }) => runScenario(
+  it('cleans acquired workspace and session roots when spill allocation fails', async () => {
+    const { fixtureFile } = await scenario({})
+    const failure = { error: Object.assign(new Error('spill allocation failed'), { code: 'ENOSPC' }), allocated: [] as string[] }
+    fsControl.spillAllocationFailure = failure
+    try {
+      await expect(runScenario(
+        { steps: boot },
+        { agent: AGENT, mode: 'replay', fixtureFile },
+      )).rejects.toBe(failure.error)
+      expect(failure.allocated).toHaveLength(2)
+      for (const root of failure.allocated) {
+        await expect(readdir(root)).rejects.toMatchObject({ code: 'ENOENT' })
+      }
+    } finally {
+      fsControl.spillAllocationFailure = undefined
+      await Promise.all(failure.allocated.map(root => rm(root, { recursive: true, force: true })))
+    }
+  })
+
+  it('gives concurrent runs of the same scenario private temporary spill roots', { timeout: 20_000 }, async () => {
+    const fixture = await scenario({ echoEnv: true })
+    const results = await Promise.all([fixture, fixture].map(({ fixtureFile }) => runScenario(
       { steps: [...boot, { op: 'prompt', text: 'env?' }] },
       { agent: AGENT, mode: 'replay', fixtureFile },
     )))
@@ -579,10 +608,11 @@ describe('runScenario', () => {
     expect(roots.every(root => typeof root === 'string')).toBe(true)
     expect(new Set(roots).size).toBe(2)
     expect((roots[0] as string).length).toBe((roots[1] as string).length)
-    expect(roots).toEqual([
-      snapshotSpillRoot(first.fixtureFile),
-      snapshotSpillRoot(second.fixtureFile),
-    ])
+    for (const root of roots as string[]) {
+      expect(relative(tmpdir(), root)).toMatch(/^acp-snap-spill-[^/\\]+$/)
+      expect(root).not.toBe(snapshotSpillRoot(fixture.fixtureFile))
+      await expect(readdir(root)).rejects.toMatchObject({ code: 'ENOENT' })
+    }
   })
 
   it('seeds the workspace dir into the temp cwd before the run', { timeout: 20_000 }, async () => {
diff --git a/packages/test-support/session-snapshot/tests/manifest.spec.ts b/packages/test-support/session-snapshot/tests/manifest.spec.ts
index 6b4c4a45bd..dfb84ab588 100644
--- a/packages/test-support/session-snapshot/tests/manifest.spec.ts
+++ b/packages/test-support/session-snapshot/tests/manifest.spec.ts
@@ -89,7 +89,7 @@ describe('snapshot manifest', () => {
       'workspace:',
       '  setup: fixed-mtimes',
       '  final: true',
-      '  parent: home',
+      '  parent: outside-temp',
       'input:',
       '  task: Rejected before persistence.',
       '  attachments:',
@@ -116,7 +116,7 @@ describe('snapshot manifest', () => {
       platform: 'posix',
       permission: 'workspace-write',
       environment: { DSH_SNAPSHOT_FAILURE: 'enabled' },
-      workspace: { setup: 'fixed-mtimes', final: true, parent: 'home' },
+      workspace: { setup: 'fixed-mtimes', final: true, parent: 'outside-temp' },
       input: {
         task: 'Rejected before persistence.',
         attachments: [{ id: 'sha256:abc', mediaType: 'image/png', data: 'aGVsbG8=' }],
@@ -174,7 +174,7 @@ describe('snapshot manifest', () => {
     ['version: 1\nprofile: acp\nenvironment:\n  lower: value\n', 'manifest.environment must map uppercase environment names to strings'],
     ['version: 1\nprofile: acp\nworkspace: {}\n', 'manifest.workspace must not be empty'],
     ['version: 1\nprofile: acp\nworkspace:\n  final: false\n', 'manifest.workspace.final must equal true when present'],
-    ['version: 1\nprofile: acp\nworkspace:\n  parent: temp\n', 'manifest.workspace.parent must equal home'],
+    ['version: 1\nprofile: acp\nworkspace:\n  parent: temp\n', 'manifest.workspace.parent must equal outside-temp'],
     ['version: 1\nprofile: acp\ninput:\n  task: ""\n', 'manifest.input.task must be a non-empty string when present'],
     ['version: 1\nprofile: acp\ninput: {}\n', 'manifest.input must declare task or attachments'],
     ['version: 1\nprofile: acp\ninput:\n  attachments: []\n', 'manifest.input.attachments must be a non-empty array'],
diff --git a/packages/util/workspace-path/README.i18n.yaml b/packages/util/workspace-path/README.i18n.yaml
index bfff3060b8..e3c4c1a31d 100644
--- a/packages/util/workspace-path/README.i18n.yaml
+++ b/packages/util/workspace-path/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/util/workspace-path/README.md
-README.md: 1b09bda74c8836655789c57fa05d03a2892c16b9
-README.zh.md: 25128e5fec504e1724f5cc7952fed976985912d5
+README.md: 0b820992dffe0ce52530f45b01fa73ad8f1c9a23
+README.zh.md: 5648d9e37f1fd6bde8a8c0237051c3f801b01a72
diff --git a/packages/util/workspace-path/README.md b/packages/util/workspace-path/README.md
index 1b09bda74c..0b820992df 100644
--- a/packages/util/workspace-path/README.md
+++ b/packages/util/workspace-path/README.md
@@ -9,15 +9,25 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-Browser-safe path helpers shared by Workspace-facing client and controller packages. The package joins Workspace-relative paths, abbreviates POSIX home directories for display, and derives Workspace titles from POSIX or Windows paths. It has no Cordis service or runtime state.
+Browser-safe path helpers shared by Workspace-facing client and controller packages. The package joins Workspace-relative paths, abbreviates POSIX home directories for display, derives Workspace titles from POSIX or Windows paths, and owns the `dsh-resource://file/…` address grammar that names a workspace file across the Sidebar and the resource model. It has no Cordis service or runtime state.
 
 ## Table of Contents
 
+- [File addresses](#file-addresses)
 - [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
 - [Dev Note](#dev-note)
 
 -----
 
+<a id="file-addresses"></a>
+## File addresses
+
+A resource address is `dsh-resource://<type>/…`, and the type — the URI host — is the resource protocol key (`file`, or one a plugin declares in `ResourceProtocolMap`); any other scheme is a navigation protocol, defined elsewhere. A file address has one of two scopes. `dsh-resource://file/session/<sessionId>/<path>` names a file by its path relative to that Session's workspace root (`dsh-resource://file/session/abc123/src/notes.txt`), which the Host resolves against the root it holds for the Session. `dsh-resource://file/absolute/<path>` names a file by its absolute path with the leading `/` dropped (`dsh-resource://file/absolute/home/ys/notes.txt` on POSIX, `dsh-resource://file/absolute/C:/x/y.txt` for a Windows drive, `dsh-resource://file/absolute//server/share/y.txt` for a UNC path, whose empty first segment keeps its identity); it carries no Session, so the reader's own Session resolves it, and the Host's workspace confinement still applies. The grammar lives in [`src/file-address.ts`](src/file-address.ts); the path helpers stay in [`src/index.ts`](src/index.ts), which re-exports it.
+
+`sessionFileAddress(sessionId, relativePath)` and `absoluteFileAddress(absolutePath)` build one: `\` becomes `/`, a leading `./` or `/` is dropped, and every id and path segment is component-encoded with `:` kept literal, so `#`, `?`, and spaces in a name survive while a drive letter reads as written. `fileAddressFor(sessionId, cwd, path)` chooses the scope for a path as a caller holds it: a relative path, or an absolute path inside `cwd`, becomes `session`-relative; any other absolute path becomes `absolute`. `parseFileAddress(address)` reads one back through `new URL()`: the scheme must be `dsh-resource` and the host exactly `file`; a `session` address yields `{ scope, sessionId, path }` with the workspace-relative path, an `absolute` address yields `{ scope, path }` with the leading `/` restored (`//` for a UNC path) unless the path starts with a drive letter. It returns `undefined` for another type or scheme, an unknown scope, a missing id or path, a non-URL, or a malformed escape — the caller decides whether that is a failure.
+
+-----
+
 ## Known Limitations and Deferred Work
 
 <a id="known-limitations-and-deferred-work"></a>
diff --git a/packages/util/workspace-path/README.zh.md b/packages/util/workspace-path/README.zh.md
index 25128e5fec..5648d9e37f 100644
--- a/packages/util/workspace-path/README.zh.md
+++ b/packages/util/workspace-path/README.zh.md
@@ -9,15 +9,25 @@ kind: "package-library"
 
 ## 概述
 
-供 Workspace 相关客户端和控制器包共享、可在浏览器使用的路径辅助函数。该包负责拼接 Workspace 相对路径、缩写用于展示的 POSIX 主目录，以及从 POSIX 或 Windows 路径提取 Workspace 标题；它不提供 Cordis service，也不持有运行时状态。
+供 Workspace 相关客户端和控制器包共享、可在浏览器使用的路径辅助函数。该包负责拼接 Workspace 相对路径、缩写用于展示的 POSIX 主目录、从 POSIX 或 Windows 路径提取 Workspace 标题，并拥有在 Sidebar 与资源模型之间命名工作区文件的 `dsh-resource://file/…` 地址语法；它不提供 Cordis service，也不持有运行时状态。
 
 ## 目录
 
+- [文件地址](#file-addresses)
 - [已知限制与暂缓事项](#known-limitations-and-deferred-work)
 - [开发备注](#dev-note)
 
 -----
 
+<a id="file-addresses"></a>
+## 文件地址
+
+资源地址 = `dsh-resource://<type>/…`，type（URI 的 host）即资源协议键（`file`，或插件在 `ResourceProtocolMap` 中声明的键）；其他 scheme 属导航协议，另行定义。文件地址有两种作用域。`dsh-resource://file/session/<sessionId>/<path>` 以相对该 Session 工作区根的路径命名文件（`dsh-resource://file/session/abc123/src/notes.txt`），由 Host 对它为该 Session 持有的根解析。`dsh-resource://file/absolute/<path>` 以去掉前导 `/` 的绝对路径命名文件（POSIX 上为 `dsh-resource://file/absolute/home/ys/notes.txt`，Windows 盘符为 `dsh-resource://file/absolute/C:/x/y.txt`，UNC 路径为 `dsh-resource://file/absolute//server/share/y.txt`，其空的首段保留 UNC 身份）；它不带 Session，由读者自己的 Session 解析，Host 的工作区限制照样适用。语法住在 [`src/file-address.ts`](src/file-address.ts)；路径辅助函数留在 [`src/index.ts`](src/index.ts) 并再导出它。
+
+`sessionFileAddress(sessionId, relativePath)` 与 `absoluteFileAddress(absolutePath)` 构造地址：`\` 归一为 `/`，去掉前导 `./` 或 `/`，id 与每个路径段做组件编码但 `:` 保持字面，因此名字里的 `#`、`?`、空格都能保留，盘符也照原样可读。`fileAddressFor(sessionId, cwd, path)` 按调用方手里的路径选作用域：相对路径或落在 `cwd` 内的绝对路径成为 `session` 相对地址，其他绝对路径成为 `absolute` 地址。`parseFileAddress(address)` 用 `new URL()` 读回：scheme 必须是 `dsh-resource`、host 必须恰为 `file`；`session` 地址得到 `{ scope, sessionId, path }`（path 为工作区相对路径），`absolute` 地址得到 `{ scope, path }` 并还原前导 `/`（UNC 路径还原为 `//`），以盘符开头者除外。对其他 type 或 scheme、未知作用域、缺 id 或路径、非 URL、或转义格式错误的输入返回 `undefined`，是否算失败由调用方决定。
+
+-----
+
 ## 已知限制与暂缓事项
 
 <a id="known-limitations-and-deferred-work"></a>
diff --git a/packages/util/workspace-path/src/file-address.ts b/packages/util/workspace-path/src/file-address.ts
new file mode 100644
index 0000000000..34dfc5aceb
--- /dev/null
+++ b/packages/util/workspace-path/src/file-address.ts
@@ -0,0 +1,113 @@
+/**
+ * The `dsh-resource://file/…` address grammar: how a file is named across the
+ * Sidebar and the resource model, built and parsed without touching a
+ * filesystem.
+ * @module
+ */
+
+/**
+ * A file resource address, in one of two scopes.
+ *
+ * Every resource address is `dsh-resource://<type>/…`, the URI host naming the
+ * resource protocol; for `file` the path opens with the scope:
+ *
+ * - `dsh-resource://file/session/<sessionId>/<path>` names a file by its path
+ *   relative to that Session's workspace root (`src/a.ts`, no leading `/`); the
+ *   Host resolves it against the root it holds for the Session.
+ * - `dsh-resource://file/absolute/<path>` names a file by its absolute path with
+ *   the leading `/` dropped (`dsh-resource://file/absolute/home/ys/notes.txt`;
+ *   Windows `dsh-resource://file/absolute/C:/x/y.txt`; a UNC path keeps an empty
+ *   first segment, `dsh-resource://file/absolute//server/share/x.txt`). It carries
+ *   no Session: the reader's own Session resolves it, and the Host's workspace
+ *   confinement still applies.
+ *
+ * Every id and path segment is component-encoded, so a name carrying `#`, `?`,
+ * or a space survives the round trip; `:` stays literal so a drive letter reads
+ * as written.
+ */
+export type FileAddress =
+  | {
+    readonly scope: 'session'
+    /** The Session whose workspace root the path is relative to. */
+    readonly sessionId: string
+    /** Workspace-relative `/`-separated path, no leading `/`; empty for the root itself. */
+    readonly path: string
+  }
+  | {
+    readonly scope: 'absolute'
+    /** Absolute `/`-separated path: `/a/b` on POSIX, `C:/a/b` for a Windows drive, `//server/share/a` for a UNC path. */
+    readonly path: string
+  }
+
+/** The scheme and type every file address opens with. */
+const FILE_ADDRESS_PREFIX = 'dsh-resource://file/'
+
+/** Component-encode one id or path segment, keeping `:` literal for drive letters. */
+function encodeSegment(segment: string): string {
+  return encodeURIComponent(segment).replace(/%3A/gi, ':')
+}
+
+/** Encode a `/`-separated path segment by segment. */
+function encodePath(path: string): string {
+  return path.split('/').map(encodeSegment).join('/')
+}
+
+/** Whether a decoded first path segment is a Windows drive (`C:`). */
+function isDriveSegment(segment: string | undefined): boolean {
+  return segment !== undefined && /^[A-Za-z]:$/.test(segment)
+}
+
+/**
+ * Build the address of a file inside one Session's workspace.
+ * @param sessionId - the Session whose workspace root the path is relative to.
+ * @param path - workspace-relative path; backslashes are normalized to `/`, and a leading `./` or `/` is dropped.
+ * @returns the `dsh-resource://file/session/<sessionId>/<path>` address.
+ */
+export function sessionFileAddress(sessionId: string, path: string): string {
+  const relative = path.replace(/\\/g, '/').replace(/^(?:\.\/)+/, '').replace(/^\/+/, '')
+  return `${FILE_ADDRESS_PREFIX}session/${encodeSegment(sessionId)}/${encodePath(relative)}`
+}
+
+/**
+ * Build the address of a file by its absolute path.
+ * @param path - absolute path; backslashes are normalized to `/` and the leading `/` is dropped,
+ *   except that a UNC path (`\\server\share`) keeps one empty first segment.
+ * @returns the `dsh-resource://file/absolute/<path>` address.
+ */
+export function absoluteFileAddress(path: string): string {
+  const normalized = path.replace(/\\/g, '/')
+  const unc = normalized.startsWith('//')
+  const absolute = normalized.replace(/^\/+/, '')
+  return `${FILE_ADDRESS_PREFIX}absolute/${unc ? '/' : ''}${encodePath(absolute)}`
+}
+
+/**
+ * Read a file address back into its parts.
+ * @param address - a candidate address.
+ * @returns the parts, or `undefined` when the string is not a `dsh-resource://file/` URI in a known scope with a path, or a segment is not validly encoded.
+ */
+export function parseFileAddress(address: string): FileAddress | undefined {
+  try {
+    const url = new URL(address)
+    if (url.protocol !== 'dsh-resource:' || url.host !== 'file') return undefined
+    const [, scope, ...rest] = url.pathname.split('/')
+    if (scope === 'session') {
+      const [id, ...segments] = rest
+      if (id === undefined || id === '' || segments.length === 0) return undefined
+      return { scope, sessionId: decodeURIComponent(id), path: segments.map(decodeURIComponent).join('/') }
+    }
+    if (scope === 'absolute') {
+      // An empty first segment with more behind it is a UNC path's `//`; alone it is no path.
+      const unc = rest[0] === '' && rest.length > 1
+      const segments = (unc ? rest.slice(1) : rest).map(decodeURIComponent)
+      if (segments.length === 0 || segments[0] === '') return undefined
+      if (unc) return { scope, path: `//${segments.join('/')}` }
+      return { scope, path: isDriveSegment(segments[0]) ? segments.join('/') : `/${segments.join('/')}` }
+    }
+    return undefined
+  } catch {
+    // `new URL` throws TypeError on a non-URL and `decodeURIComponent` throws
+    // URIError on a malformed escape; both mean "not a file address".
+    return undefined
+  }
+}
diff --git a/packages/util/workspace-path/src/index.ts b/packages/util/workspace-path/src/index.ts
index 9fe3435573..6f859782e9 100644
--- a/packages/util/workspace-path/src/index.ts
+++ b/packages/util/workspace-path/src/index.ts
@@ -2,12 +2,22 @@
  * Browser-safe Workspace path and display helpers.
  * @module @deepseek-ai/dsh-util-workspace-path
  */
+import { absoluteFileAddress, sessionFileAddress } from './file-address.ts'
 
 /** Whether a path uses a Windows drive or UNC prefix. */
 function isWindowsStylePath(value: string): boolean {
   return /^[A-Za-z]:[/\\]/.test(value) || value.startsWith('\\\\')
 }
 
+/**
+ * Whether a path is absolute in either spelling the Host accepts: POSIX (`/a/b`) or Windows drive or UNC.
+ * @param path - the path to classify.
+ * @returns `true` for an absolute path; `false` for a Workspace-relative one.
+ */
+export function isAbsoluteWorkspacePath(path: string): boolean {
+  return path.startsWith('/') || isWindowsStylePath(path)
+}
+
 /**
  * Resolve a Workspace-relative path into the Host-facing spelling used by path operations.
  * @param cwd - Session Workspace root, when known.
@@ -15,7 +25,7 @@ function isWindowsStylePath(value: string): boolean {
  * @returns an absolute path when a Workspace root is available, otherwise the original path.
  */
 export function resolveWorkspacePath(cwd: string | undefined, path: string): string {
-  if (path.startsWith('/') || isWindowsStylePath(path)) return path
+  if (isAbsoluteWorkspacePath(path)) return path
   if (cwd === undefined || cwd === '') return path
   const separator = isWindowsStylePath(cwd) && cwd.includes('\\') ? '\\' : '/'
   const base = cwd.replace(/[/\\]+$/, '')
@@ -50,3 +60,24 @@ export function workspaceTitleOf(path: string): string {
   const separator = Math.max(trimmed.lastIndexOf('/'), trimmed.lastIndexOf('\\'))
   return trimmed.slice(separator + 1)
 }
+
+export * from './file-address.ts'
+
+/**
+ * The address for a path as a caller holds it: a relative path, or an absolute
+ * path inside the Session's workspace, becomes a `session`-scoped address; an
+ * absolute path outside it, or one whose workspace root is unknown, becomes an
+ * `absolute`-scoped address.
+ * @param sessionId - the Session the path is read in.
+ * @param cwd - that Session's workspace root, when known.
+ * @param path - absolute or workspace-relative path, in either separator spelling.
+ * @returns the `dsh-resource://file/…` address.
+ */
+export function fileAddressFor(sessionId: string, cwd: string | undefined, path: string): string {
+  const normalized = path.replace(/\\/g, '/')
+  if (!isAbsoluteWorkspacePath(normalized)) return sessionFileAddress(sessionId, normalized)
+  const root = cwd === undefined ? '' : cwd.replace(/\\/g, '/').replace(/\/+$/, '')
+  if (root !== '' && normalized === root) return sessionFileAddress(sessionId, '')
+  if (root !== '' && normalized.startsWith(`${root}/`)) return sessionFileAddress(sessionId, normalized.slice(root.length + 1))
+  return absoluteFileAddress(normalized)
+}
diff --git a/packages/util/workspace-path/tests/file-address.spec.ts b/packages/util/workspace-path/tests/file-address.spec.ts
new file mode 100644
index 0000000000..3021cb8f58
--- /dev/null
+++ b/packages/util/workspace-path/tests/file-address.spec.ts
@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest'
+import { absoluteFileAddress, parseFileAddress, sessionFileAddress } from '../src/file-address.ts'
+
+describe('file addresses', () => {
+  it('round-trips a session-relative path with encoded segments', () => {
+    const address = sessionFileAddress('s 1', 'w/a b#c?.txt')
+    expect(address).toBe('dsh-resource://file/session/s%201/w/a%20b%23c%3F.txt')
+    expect(parseFileAddress(address)).toEqual({ scope: 'session', sessionId: 's 1', path: 'w/a b#c?.txt' })
+  })
+
+  it('drops a leading ./ or / from a session-relative path and names the root with an empty path', () => {
+    expect(sessionFileAddress('s', './src/a.ts')).toBe('dsh-resource://file/session/s/src/a.ts')
+    expect(sessionFileAddress('s', '/src/a.ts')).toBe('dsh-resource://file/session/s/src/a.ts')
+    expect(sessionFileAddress('s', 'src\\a.ts')).toBe('dsh-resource://file/session/s/src/a.ts')
+    expect(sessionFileAddress('s', '')).toBe('dsh-resource://file/session/s/')
+    expect(parseFileAddress('dsh-resource://file/session/s/')).toEqual({ scope: 'session', sessionId: 's', path: '' })
+  })
+
+  it('round-trips an absolute POSIX path with the leading slash dropped', () => {
+    const address = absoluteFileAddress('/home/me/notes.md')
+    expect(address).toBe('dsh-resource://file/absolute/home/me/notes.md')
+    expect(parseFileAddress(address)).toEqual({ scope: 'absolute', path: '/home/me/notes.md' })
+  })
+
+  it('round-trips an absolute Windows drive path with backslashes normalized and the colon literal', () => {
+    const address = absoluteFileAddress('C:\\w\\x.ts')
+    expect(address).toBe('dsh-resource://file/absolute/C:/w/x.ts')
+    expect(parseFileAddress(address)).toEqual({ scope: 'absolute', path: 'C:/w/x.ts' })
+  })
+
+  it('keeps a UNC path\'s identity in an absolute address', () => {
+    const address = absoluteFileAddress('\\\\server\\share\\x.ts')
+    expect(address).toBe('dsh-resource://file/absolute//server/share/x.ts')
+    expect(parseFileAddress(address)).toEqual({ scope: 'absolute', path: '//server/share/x.ts' })
+  })
+
+  it('decodes either spelling of a path segment', () => {
+    expect(parseFileAddress('dsh-resource://file/session/s/w/a+b.txt')?.path).toBe('w/a+b.txt')
+    expect(parseFileAddress('dsh-resource://file/session/s/w/a%2Bb.txt')?.path).toBe('w/a+b.txt')
+    expect(parseFileAddress('dsh-resource://file/absolute/w/a%2Bb.txt')?.path).toBe('/w/a+b.txt')
+  })
+
+  it.each([
+    ['another resource type', 'dsh-resource://terminal/session/s/1'],
+    ['a type spelled with another case', 'dsh-resource://File/session/s/w/x.ts'],
+    ['an unknown scope', 'dsh-resource://file/shared/s/w/x'],
+    ['the retired file:// grammar', 'file://sessions/s/w/x.ts'],
+    ['a host-less file URL', 'file:///w/x.ts'],
+    ['a session address with no path', 'dsh-resource://file/session/s'],
+    ['a session address with no id', 'dsh-resource://file/session'],
+    ['an absolute address with no path', 'dsh-resource://file/absolute'],
+    ['an absolute address with an empty path', 'dsh-resource://file/absolute/'],
+    ['a UNC marker with no host behind it', 'dsh-resource://file/absolute//'],
+    ['no scope', 'dsh-resource://file'],
+    ['another scheme', 'sidebar://files'],
+    ['not a URL', 'notes.txt'],
+    ['a malformed escape', 'dsh-resource://file/session/s/%E0%A4%A'],
+  ])('rejects %s', (_, address) => {
+    expect(parseFileAddress(address)).toBeUndefined()
+  })
+})
diff --git a/packages/util/workspace-path/tests/index.spec.ts b/packages/util/workspace-path/tests/index.spec.ts
index 0044e4b088..5695187336 100644
--- a/packages/util/workspace-path/tests/index.spec.ts
+++ b/packages/util/workspace-path/tests/index.spec.ts
@@ -1,9 +1,31 @@
 import { describe, expect, it } from 'vitest'
 import {
-  abbreviateHomePath, resolveWorkspacePath, workspaceTitleOf,
+  abbreviateHomePath, fileAddressFor, isAbsoluteWorkspacePath, resolveWorkspacePath, workspaceTitleOf,
 } from '@deepseek-ai/dsh-util-workspace-path'
 
 describe('Workspace path helpers', () => {
+  it('addresses a relative or in-workspace path by session and any other absolute path by itself', () => {
+    expect(fileAddressFor('s', '/w', 'src/a.ts')).toBe('dsh-resource://file/session/s/src/a.ts')
+    expect(fileAddressFor('s', undefined, 'src/a.ts')).toBe('dsh-resource://file/session/s/src/a.ts')
+    expect(fileAddressFor('s', '/w/', '/w/src/a.ts')).toBe('dsh-resource://file/session/s/src/a.ts')
+    expect(fileAddressFor('s', '/w', '/w')).toBe('dsh-resource://file/session/s/')
+    expect(fileAddressFor('s', '/w', '/work/a.ts')).toBe('dsh-resource://file/absolute/work/a.ts')
+    expect(fileAddressFor('s', undefined, '/etc/hosts')).toBe('dsh-resource://file/absolute/etc/hosts')
+    expect(fileAddressFor('s', 'C:\\w', 'C:\\w\\x.ts')).toBe('dsh-resource://file/session/s/x.ts')
+    expect(fileAddressFor('s', 'C:\\w', 'D:\\x.ts')).toBe('dsh-resource://file/absolute/D:/x.ts')
+    expect(fileAddressFor('s', undefined, '\\\\server\\share\\x.ts')).toBe('dsh-resource://file/absolute//server/share/x.ts')
+    expect(fileAddressFor('s', '\\\\server\\share', '\\\\server\\share\\x.ts')).toBe('dsh-resource://file/session/s/x.ts')
+  })
+
+  it('classifies POSIX, Windows drive, and UNC paths as absolute and everything else as relative', () => {
+    expect(isAbsoluteWorkspacePath('/a/b')).toBe(true)
+    expect(isAbsoluteWorkspacePath('C:\\x\\a.ts')).toBe(true)
+    expect(isAbsoluteWorkspacePath('C:/x/a.ts')).toBe(true)
+    expect(isAbsoluteWorkspacePath('\\\\server\\share')).toBe(true)
+    expect(isAbsoluteWorkspacePath('src/a.ts')).toBe(false)
+    expect(isAbsoluteWorkspacePath('')).toBe(false)
+  })
+
   it('resolves relative paths without changing absolute paths', () => {
     expect(resolveWorkspacePath('/w', 'src/a.ts')).toBe('/w/src/a.ts')
     expect(resolveWorkspacePath('/w/', '/abs/a.ts')).toBe('/abs/a.ts')
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index fa5cbd9ef1..3a819e8180 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -591,6 +591,9 @@ importers:
       '@deepseek-ai/dsh-client-store':
         specifier: workspace:^
         version: link:../../packages/client/store
+      '@deepseek-ai/dsh-client-ui-dockkit':
+        specifier: workspace:^
+        version: link:../../packages/client/ui-dockkit
       '@deepseek-ai/dsh-client-ui-primitives':
         specifier: workspace:^
         version: link:../../packages/client/ui-primitives
@@ -889,6 +892,9 @@ importers:
       '@deepseek-ai/dsh-api-workspace-controller':
         specifier: workspace:^
         version: link:../workspace-controller
+      '@deepseek-ai/dsh-api-workspace-files':
+        specifier: workspace:^
+        version: link:../workspace-files
       '@deepseek-ai/dsh-client-connection':
         specifier: workspace:^
         version: link:../../client/connection
@@ -1136,6 +1142,52 @@ importers:
         specifier: workspace:^
         version: link:../../workspace/workspace
 
+  packages/api/workspace-files:
+    dependencies:
+      '@deepseek-ai/dsh-deque':
+        specifier: workspace:^
+        version: link:../../util/deque
+      '@deepseek-ai/dsh-typert-protocol':
+        specifier: workspace:^
+        version: link:../../typert/protocol
+      '@deepseek-ai/schemastery':
+        specifier: link:../../../vendor/schemastery
+        version: link:../../../vendor/schemastery
+      zod:
+        specifier: ^4.4.3
+        version: 4.4.3
+    devDependencies:
+      '@deepseek-ai/cordis':
+        specifier: workspace:^
+        version: link:../../../vendor/cordis
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-api-gateway':
+        specifier: workspace:^
+        version: link:../gateway
+      '@deepseek-ai/dsh-api-session-controller':
+        specifier: workspace:^
+        version: link:../session-controller
+      '@deepseek-ai/dsh-client-resources':
+        specifier: workspace:^
+        version: link:../../client/resources
+      '@deepseek-ai/dsh-client-ui-slots':
+        specifier: workspace:^
+        version: link:../../client/ui-slots
+      '@deepseek-ai/dsh-fs':
+        specifier: workspace:^
+        version: link:../../fs/fs
+      '@deepseek-ai/dsh-sandbox-policy':
+        specifier: workspace:^
+        version: link:../../sandbox/sandbox-policy
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-util-workspace-path':
+        specifier: workspace:^
+        version: link:../../util/workspace-path
+
   packages/attachment/attachment:
     devDependencies:
       '@deepseek-ai/cordis':
@@ -1673,6 +1725,9 @@ importers:
       '@deepseek-ai/dsh-api-workspace-controller':
         specifier: workspace:^
         version: link:../../api/workspace-controller
+      '@deepseek-ai/dsh-api-workspace-files':
+        specifier: workspace:^
+        version: link:../../api/workspace-files
       '@deepseek-ai/dsh-app-boot':
         specifier: workspace:^
         version: link:../../boot/app-boot
@@ -1691,6 +1746,9 @@ importers:
       '@deepseek-ai/dsh-client-modules':
         specifier: workspace:^
         version: link:../../client/modules
+      '@deepseek-ai/dsh-client-resources':
+        specifier: workspace:^
+        version: link:../../client/resources
       '@deepseek-ai/dsh-client-ui-agent-preset':
         specifier: workspace:^
         version: link:../../client/ui-agent-preset
@@ -1781,6 +1839,15 @@ importers:
       '@deepseek-ai/dsh-client-ui-sidebar':
         specifier: workspace:^
         version: link:../../client/ui-sidebar
+      '@deepseek-ai/dsh-client-ui-sidebar-files':
+        specifier: workspace:^
+        version: link:../../client/ui-sidebar-files
+      '@deepseek-ai/dsh-client-ui-sidebar-right':
+        specifier: workspace:^
+        version: link:../../client/ui-sidebar-right
+      '@deepseek-ai/dsh-client-ui-sidebar-textpreview':
+        specifier: workspace:^
+        version: link:../../client/ui-sidebar-textpreview
       '@deepseek-ai/dsh-client-ui-skill':
         specifier: workspace:^
         version: link:../../client/ui-skill
@@ -2069,6 +2136,27 @@ importers:
         specifier: workspace:^
         version: link:../../util/package-manifest
 
+  packages/client/resources:
+    devDependencies:
+      '@deepseek-ai/cordis':
+        specifier: workspace:^
+        version: link:../../../vendor/cordis
+      '@deepseek-ai/dsh-client-store':
+        specifier: workspace:^
+        version: link:../store
+      '@deepseek-ai/dsh-client-test-runtime':
+        specifier: workspace:^
+        version: link:../../test-support/client-runtime
+      '@deepseek-ai/dsh-client-ui-renderer':
+        specifier: workspace:^
+        version: link:../ui-renderer
+      '@deepseek-ai/dsh-client-ui-slots':
+        specifier: workspace:^
+        version: link:../ui-slots
+      '@deepseek-ai/dsh-typert-protocol':
+        specifier: workspace:^
+        version: link:../../typert/protocol
+
   packages/client/store:
     dependencies:
       immer:
@@ -2278,6 +2366,9 @@ importers:
       '@deepseek-ai/dsh-api-workspace-controller':
         specifier: workspace:^
         version: link:../../api/workspace-controller
+      '@deepseek-ai/dsh-api-workspace-files':
+        specifier: workspace:^
+        version: link:../../api/workspace-files
       '@deepseek-ai/dsh-attachment':
         specifier: workspace:^
         version: link:../../attachment/attachment
@@ -2308,6 +2399,12 @@ importers:
       '@deepseek-ai/dsh-client-ui-settings':
         specifier: workspace:^
         version: link:../ui-settings
+      '@deepseek-ai/dsh-client-ui-sidebar-right':
+        specifier: workspace:^
+        version: link:../ui-sidebar-right
+      '@deepseek-ai/dsh-client-ui-sidebar-textpreview':
+        specifier: workspace:^
+        version: link:../ui-sidebar-textpreview
       '@deepseek-ai/dsh-client-ui-slots':
         specifier: workspace:^
         version: link:../ui-slots
@@ -2666,6 +2763,34 @@ importers:
         specifier: ^18.2.0
         version: 18.3.1(react@18.3.1)
 
+  packages/client/ui-dockkit:
+    dependencies:
+      clsx:
+        specifier: ^2.0.0
+        version: 2.1.1
+      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/cordis':
+        specifier: workspace:^
+        version: link:../../../vendor/cordis
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
+      '@testing-library/react':
+        specifier: ^16.1.0
+        version: 16.3.2(@testing-library/dom@10.4.1)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@types/react':
+        specifier: ~18.3.1
+        version: 18.3.31
+      '@types/react-dom':
+        specifier: ~18.3.0
+        version: 18.3.7(@types/react@18.3.31)
+
   packages/client/ui-goal:
     devDependencies:
       '@deepseek-ai/cordis':
@@ -2955,9 +3080,15 @@ importers:
       '@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)
       react:
         specifier: ^18.2.0
         version: 18.3.1
+      react-dom:
+        specifier: ^18.2.0
+        version: 18.3.1(react@18.3.1)
 
   packages/client/ui-open-in-app:
     devDependencies:
@@ -3579,6 +3710,207 @@ importers:
         specifier: ^18.2.0
         version: 18.3.1
 
+  packages/client/ui-sidebar-files:
+    dependencies:
+      clsx:
+        specifier: ^2.0.0
+        version: 2.1.1
+      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/cordis':
+        specifier: workspace:^
+        version: link:../../../vendor/cordis
+      '@deepseek-ai/dsh-api-remotes':
+        specifier: workspace:^
+        version: link:../../api/remotes
+      '@deepseek-ai/dsh-api-workspace-files':
+        specifier: workspace:^
+        version: link:../../api/workspace-files
+      '@deepseek-ai/dsh-client-locale':
+        specifier: workspace:^
+        version: link:../locale
+      '@deepseek-ai/dsh-client-store':
+        specifier: workspace:^
+        version: link:../store
+      '@deepseek-ai/dsh-client-test-runtime':
+        specifier: workspace:^
+        version: link:../../test-support/client-runtime
+      '@deepseek-ai/dsh-client-ui-dockkit':
+        specifier: workspace:^
+        version: link:../ui-dockkit
+      '@deepseek-ai/dsh-client-ui-primitives':
+        specifier: workspace:^
+        version: link:../ui-primitives
+      '@deepseek-ai/dsh-client-ui-renderer':
+        specifier: workspace:^
+        version: link:../ui-renderer
+      '@deepseek-ai/dsh-client-ui-session':
+        specifier: workspace:^
+        version: link:../ui-session
+      '@deepseek-ai/dsh-client-ui-sidebar-right':
+        specifier: workspace:^
+        version: link:../ui-sidebar-right
+      '@deepseek-ai/dsh-client-ui-slots':
+        specifier: workspace:^
+        version: link:../ui-slots
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-util-workspace-path':
+        specifier: workspace:^
+        version: link:../../util/workspace-path
+      '@testing-library/react':
+        specifier: ^16.1.0
+        version: 16.3.2(@testing-library/dom@10.4.1)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@types/react':
+        specifier: ~18.3.1
+        version: 18.3.31
+      '@types/react-dom':
+        specifier: ~18.3.0
+        version: 18.3.7(@types/react@18.3.31)
+
+  packages/client/ui-sidebar-right:
+    dependencies:
+      clsx:
+        specifier: ^2.0.0
+        version: 2.1.1
+      picomatch:
+        specifier: ^4.0.4
+        version: 4.0.4
+      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/cordis':
+        specifier: workspace:^
+        version: link:../../../vendor/cordis
+      '@deepseek-ai/dsh-api-session-controller':
+        specifier: workspace:^
+        version: link:../../api/session-controller
+      '@deepseek-ai/dsh-client-locale':
+        specifier: workspace:^
+        version: link:../locale
+      '@deepseek-ai/dsh-client-resources':
+        specifier: workspace:^
+        version: link:../resources
+      '@deepseek-ai/dsh-client-store':
+        specifier: workspace:^
+        version: link:../store
+      '@deepseek-ai/dsh-client-test-runtime':
+        specifier: workspace:^
+        version: link:../../test-support/client-runtime
+      '@deepseek-ai/dsh-client-ui-conversation':
+        specifier: workspace:^
+        version: link:../ui-conversation
+      '@deepseek-ai/dsh-client-ui-dockkit':
+        specifier: workspace:^
+        version: link:../ui-dockkit
+      '@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-renderer':
+        specifier: workspace:^
+        version: link:../ui-renderer
+      '@deepseek-ai/dsh-client-ui-session':
+        specifier: workspace:^
+        version: link:../ui-session
+      '@deepseek-ai/dsh-client-ui-slots':
+        specifier: workspace:^
+        version: link:../ui-slots
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@testing-library/react':
+        specifier: ^16.1.0
+        version: 16.3.2(@testing-library/dom@10.4.1)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@types/picomatch':
+        specifier: ^4.0.2
+        version: 4.0.3
+      '@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)
+
+  packages/client/ui-sidebar-textpreview:
+    dependencies:
+      clsx:
+        specifier: ^2.0.0
+        version: 2.1.1
+      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/cordis':
+        specifier: workspace:^
+        version: link:../../../vendor/cordis
+      '@deepseek-ai/dsh-api-remotes':
+        specifier: workspace:^
+        version: link:../../api/remotes
+      '@deepseek-ai/dsh-api-workspace-files':
+        specifier: workspace:^
+        version: link:../../api/workspace-files
+      '@deepseek-ai/dsh-client-locale':
+        specifier: workspace:^
+        version: link:../locale
+      '@deepseek-ai/dsh-client-resources':
+        specifier: workspace:^
+        version: link:../resources
+      '@deepseek-ai/dsh-client-store':
+        specifier: workspace:^
+        version: link:../store
+      '@deepseek-ai/dsh-client-test-runtime':
+        specifier: workspace:^
+        version: link:../../test-support/client-runtime
+      '@deepseek-ai/dsh-client-ui-dockkit':
+        specifier: workspace:^
+        version: link:../ui-dockkit
+      '@deepseek-ai/dsh-client-ui-primitives':
+        specifier: workspace:^
+        version: link:../ui-primitives
+      '@deepseek-ai/dsh-client-ui-renderer':
+        specifier: workspace:^
+        version: link:../ui-renderer
+      '@deepseek-ai/dsh-client-ui-session':
+        specifier: workspace:^
+        version: link:../ui-session
+      '@deepseek-ai/dsh-client-ui-sidebar-right':
+        specifier: workspace:^
+        version: link:../ui-sidebar-right
+      '@deepseek-ai/dsh-client-ui-slots':
+        specifier: workspace:^
+        version: link:../ui-slots
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-util-workspace-path':
+        specifier: workspace:^
+        version: link:../../util/workspace-path
+      '@testing-library/react':
+        specifier: ^16.1.0
+        version: 16.3.2(@testing-library/dom@10.4.1)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@types/react':
+        specifier: ~18.3.1
+        version: 18.3.31
+      '@types/react-dom':
+        specifier: ~18.3.0
+        version: 18.3.7(@types/react@18.3.31)
+
   packages/client/ui-skill:
     devDependencies:
       '@deepseek-ai/cordis':
@@ -4105,6 +4437,9 @@ importers:
       '@deepseek-ai/dsh-client-store':
         specifier: workspace:^
         version: link:../store
+      '@deepseek-ai/dsh-client-ui-dockkit':
+        specifier: workspace:^
+        version: link:../ui-dockkit
       '@deepseek-ai/dsh-client-ui-primitives':
         specifier: workspace:^
         version: link:../ui-primitives
@@ -13548,6 +13883,9 @@ packages:
   '@types/picomatch@3.0.2':
     resolution: {integrity: sha512-n0i8TD3UDB7paoMMxA3Y65vUncFJXjcUf7lQY7YyKGl6031FNjfsLs6pdLFCy2GNFxItPJG8GvvpbZc2skH7WA==}
 
+  '@types/picomatch@4.0.3':
+    resolution: {integrity: sha512-iG0T6+nYJ9FAPmx9SsUlnwcq1ZVRuCXcVEvWnntoPlrOpwtSTKNDC9uVAxTsC3PUvJ+99n4RpAcNgBbHX3JSnQ==}
+
   '@types/prop-types@15.7.15':
     resolution: {integrity: sha512-F6bEyamV9jKGAFBEmlQnesRPGOQqS2+Uwi0Em15xenOxHaf2hv6L8YCVn3rPdPJOiJfPiCnLIRyvwVaqMY3MIw==}
 
@@ -20080,6 +20418,8 @@ snapshots:
 
   '@types/picomatch@3.0.2': {}
 
+  '@types/picomatch@4.0.3': {}
+
   '@types/prop-types@15.7.15': {}
 
   '@types/qs@6.15.1': {}
diff --git a/python/sdk/tests/test_smoke_model.py b/python/sdk/tests/test_smoke_model.py
index 55570501a9..f2d2a4cb11 100644
--- a/python/sdk/tests/test_smoke_model.py
+++ b/python/sdk/tests/test_smoke_model.py
@@ -3,6 +3,7 @@ from __future__ import annotations
 import runpy
 import subprocess
 from pathlib import Path
+from types import SimpleNamespace
 
 import pytest
 
@@ -11,6 +12,88 @@ ROOT = Path(__file__).resolve().parents[3]
 SMOKE = runpy.run_path(ROOT / "scripts" / "smoke-python-runtime.py")
 
 
+@pytest.mark.parametrize(
+    ("behavior", "error"),
+    [
+        ("read-current", None),
+        ("no-verify-tool", "verify turn made no model-requested tool call"),
+        ("no-create-tool", "create turn made no model-requested tool call"),
+        ("create-error", "create turn ended with.*AUTH.*401"),
+        ("stale-answer", "verify turn returned"),
+        ("missing-create", "real-model tool turn did not create"),
+        ("wrong-create", "real-model tool turn wrote unexpected text"),
+        ("modify-verify", "real-model tool turn wrote unexpected text"),
+    ],
+)
+def test_live_smoke_requires_fresh_file_observation(
+    monkeypatch: pytest.MonkeyPatch, behavior: str, error: str | None,
+) -> None:
+    import deepseek_harness
+
+    smoke_live = SMOKE["smoke_sdk_live"]
+    sentinel = SMOKE["LIVE_API_SENTINEL"]
+    prompts: list[str] = []
+    session_ids: list[str] = []
+    log_checks: list[Path] = []
+
+    class ScriptedHarness:
+        def __init__(self, *, cwd: str, **_kwargs: object) -> None:
+            self.marker = Path(cwd) / "live-api-marker.txt"
+
+        def __enter__(self) -> ScriptedHarness:
+            return self
+
+        def __exit__(self, *_args: object) -> None:
+            pass
+
+        def run(self, prompt: str, *, session_id: str) -> SimpleNamespace:
+            prompts.append(prompt)
+            session_ids.append(session_id)
+            events = [{"type": "tool/call"}]
+            if len(prompts) == 1:
+                assert not self.marker.exists()
+                if behavior == "create-error":
+                    return SimpleNamespace(finish_reason="error", final_response="", events=[{
+                        "type": "turn/end",
+                        "data": {"turn": 1, "reason": {
+                            "kind": "error", "error": {"code": "AUTH", "status": 401},
+                        }},
+                    }])
+                if behavior == "no-create-tool":
+                    events = []
+                if behavior != "missing-create":
+                    self.marker.write_text(
+                        ("wrong" if behavior == "wrong-create" else sentinel) + "\n",
+                        encoding="utf-8",
+                    )
+                response = sentinel
+            else:
+                current = self.marker.read_text(encoding="utf-8").strip()
+                assert current != sentinel, "verification must require new world state"
+                assert all(current not in text for text in prompts), "prompts must not reveal the answer"
+                response = sentinel if behavior == "stale-answer" else current
+                if behavior == "no-verify-tool":
+                    events = []
+                if behavior == "modify-verify":
+                    self.marker.write_text("changed\n", encoding="utf-8")
+            return SimpleNamespace(finish_reason="completed", final_response=response, events=events)
+
+    monkeypatch.setenv("DEEPSEEK_API_KEY", "fixture-key")
+    monkeypatch.setenv("DEEPSEEK_BASE_URL", "https://fixture.invalid")
+    monkeypatch.setattr(deepseek_harness, "DeepSeekHarness", ScriptedHarness)
+    monkeypatch.setitem(smoke_live.__globals__, "assert_zstd_session_log", log_checks.append)
+
+    if error is None:
+        smoke_live()
+        assert len(prompts) == 2
+        assert session_ids[0] == session_ids[1]
+        assert len(log_checks) == 1
+    else:
+        with pytest.raises(AssertionError, match=error):
+            smoke_live()
+        assert not log_checks
+
+
 @pytest.mark.parametrize(
     ("prompt_name", "expected"),
     [
diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts
index ca8bc07bcb..1620e29b03 100644
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -153,6 +153,7 @@ const packageFileExtras: Readonly<Record<string, readonly string[]>> = {
   // The glob covers whichever sheets a package emits; sourcemaps stay
   // unpublished, as everywhere else in the repository.
   '@deepseek-ai/dsh-client-ui-primitives': ['lib/**/*.css'],
+  '@deepseek-ai/dsh-client-ui-dockkit': ['lib/**/*.css'],
   '@deepseek-ai/dsh-client-web': ['lib/**/*.css'],
   '@deepseek-ai/dsh-client-ui-theme': ['lib/styles'],
   // The CPython side ships as source .py files, published as-is rather than built.
diff --git a/scripts/ci-workflow.spec.ts b/scripts/ci-workflow.spec.ts
index 02ffac7aba..6ddc533c5f 100644
--- a/scripts/ci-workflow.spec.ts
+++ b/scripts/ci-workflow.spec.ts
@@ -36,6 +36,45 @@ describe('CI workflow', () => {
     }
   })
 
+  it.each(['node-24', 'node-24-coverage', 'node-24-consumers'])(
+    '%s keeps tool and fixture temporary files under runner cleanup',
+    (jobName) => {
+      const job = workflowJob(loadWorkflow('.github/workflows/ci.yml'), jobName)
+      if (!Array.isArray(job.steps)) throw new TypeError(`${jobName} must define steps`)
+      expect(job.steps[0]).toEqual({
+        name: 'Use runner-owned temporary storage',
+        run: [
+          'echo "TMPDIR=${{ runner.temp }}" >> "$GITHUB_ENV"',
+          ...(jobName === 'node-24-consumers'
+            ? ['echo "PLAYWRIGHT_BROWSERS_PATH=${RUNNER_TEMP%/*}/ms-playwright" >> "$GITHUB_ENV"']
+            : []),
+          '',
+        ].join('\n'),
+      })
+      if (jobName === 'node-24-consumers') {
+        const browserCache: unknown = job.steps.find(step => isRecord(step) && isRecord(step.with)
+          && step.with.path === '${{ env.PLAYWRIGHT_BROWSERS_PATH }}')
+        expect(browserCache).toMatchObject({ uses: 'actions/cache/restore@v4' })
+      }
+      const store: unknown = job.steps.find(step => isRecord(step) && step.name === 'Configure pnpm store path')
+      expect(store).toMatchObject({
+        run: [
+          'store_root="$HOME/.local/share/pnpm/store"',
+          'echo "PNPM_CONFIG_STORE_DIR=$store_root" >> "$GITHUB_ENV"',
+          'store_path=$(PNPM_CONFIG_STORE_DIR="$store_root" pnpm store path --silent)',
+          'echo "path=$store_path" >> "$GITHUB_OUTPUT"',
+          '',
+        ].join('\n'),
+      })
+      for (const step of job.steps) {
+        if (isRecord(step) && isRecord(step.env)) {
+          expect(step.env.TMPDIR).toBeUndefined()
+          expect(step.env.npm_config_cache).toBeUndefined()
+        }
+      }
+    },
+  )
+
   it('isolates the python SDK exe pnpm setup destination per job', () => {
     const workflow: unknown = yaml.load(readFileSync(resolve(root, '.github/workflows/build-exe-for-python-sdk.yml'), 'utf8'))
     if (!isRecord(workflow) || !isRecord(workflow.jobs)) throw new TypeError('build-exe-for-python-sdk.yml must define jobs')
@@ -735,6 +774,47 @@ describe('Python release workflows', () => {
   })
 })
 
+describe('Request review workflow', () => {
+  it('runs trusted routing on reviewable pull request updates', () => {
+    const workflow = loadWorkflow('.github/workflows/request-review.yml')
+    const event = workflowEvent(workflow, 'pull_request_target')
+    const job = workflowJob(workflow, 'request-review')
+    if (!isRecord(workflow.on)) throw new TypeError('request-review workflow must define events')
+    if (!Array.isArray(job.steps)) throw new TypeError('request-review job must define steps')
+    const steps = job.steps.filter(isRecord)
+    const checkout = steps.find(step => step.name === 'Check out trusted review policy')
+    const request = steps.find(step => step.name === 'Request reviewers')
+
+    expect(workflow.name).toBe('request-review')
+    expect(Object.keys(workflow.on)).toEqual(['pull_request_target'])
+    expect(event.types).toEqual(['opened', 'synchronize', 'reopened', 'ready_for_review'])
+    expect(workflow.permissions).toEqual({ contents: 'read', 'pull-requests': 'write' })
+    expect(workflow.concurrency).toEqual({
+      group: 'request-review-${{ github.event.pull_request.number }}',
+      'cancel-in-progress': true,
+    })
+    expect(job).toMatchObject({
+      name: 'request-review',
+      if: '${{ !github.event.pull_request.draft }}',
+      'runs-on': 'ubuntu-latest',
+      'timeout-minutes': 5,
+    })
+    expect(checkout).toMatchObject({
+      uses: 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1',
+      with: {
+        ref: '${{ github.event.repository.default_branch }}',
+        'persist-credentials': false,
+      },
+    })
+    expect(request).toMatchObject({
+      env: { GITHUB_TOKEN: '${{ github.token }}' },
+      run: 'node .github/review-ownership/request-review.mjs',
+    })
+    expect(JSON.stringify(workflow)).not.toContain('github.event.pull_request.head')
+    expect(JSON.stringify(workflow)).not.toContain('secrets.')
+  })
+})
+
 describe('Issue lifecycle workflow', () => {
   it('runs the lifecycle job on every PR/review event but gates token and board steps', () => {
     const lifecycle = loadWorkflow('.github/workflows/issue-lifecycle.yml')
diff --git a/scripts/fixtures/python-snapshot-workflow-order.mjs b/scripts/fixtures/python-snapshot-workflow-order.mjs
new file mode 100644
index 0000000000..ccef5b8d37
--- /dev/null
+++ b/scripts/fixtures/python-snapshot-workflow-order.mjs
@@ -0,0 +1,47 @@
+/** Hold the advanced workflow child's first step until its parent records membership. */
+export const name = 'python-snapshot-workflow-order'
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx - Scenario-local host context.
+ * @param {{ parentSessionId: string, prompt: string }} config - Exact advanced scenario identities.
+ */
+export function apply(ctx, config) {
+  const started = new Set()
+  const pending = new Map()
+  let disposed = false
+
+  ctx.effect(() => async () => {
+    disposed = true
+    const waits = [...pending.values()]
+    for (const wait of waits) wait.reject(new Error('workflow snapshot barrier disposed'))
+    await Promise.allSettled(waits.map(wait => wait.done))
+    started.clear()
+  })
+  ctx.on('session/event', (session, event) => {
+    if (disposed || session.id !== config.parentSessionId || event.type !== 'tool-workflow/agent-start') return
+    started.add(event.data.childId)
+    pending.get(event.data.childId)?.resolve()
+  })
+  ctx.on('agent/pre-step', async ({ agent, messages, turn, step, signal }, next) => {
+    if (agent.session.header.parentSession !== config.parentSessionId || turn !== 1 || step !== 1
+      || !messages.some(message => message.content.some(block => block.type === 'text' && block.text === config.prompt))) {
+      return next()
+    }
+    signal.throwIfAborted()
+    if (disposed) throw new Error('workflow snapshot barrier disposed')
+    if (!started.has(agent.id)) {
+      const wait = Promise.withResolvers()
+      const abort = () => { wait.reject(signal.reason) }
+      signal.addEventListener('abort', abort, { once: true })
+      wait.done = wait.promise.finally(() => {
+        signal.removeEventListener('abort', abort)
+        pending.delete(agent.id)
+      })
+      pending.set(agent.id, wait)
+      await wait.done
+    }
+    signal.throwIfAborted()
+    if (disposed) throw new Error('workflow snapshot barrier disposed')
+    return next()
+  })
+}
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 2300ddf7b3..1e2907457d 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -123,6 +123,7 @@ export const SERVICE_PAGE: Record<string, string> = {
   webhookRuntime: 'webhook.md',
   workspaceRegistry: 'workspace.md',
   workspaceController: 'workspace.md',
+  workspaceFiles: 'workspace.md',
   directoryPickerController: 'workspace.md',
 }
 
@@ -175,6 +176,9 @@ export const SERVICE_WALK_EXEMPTIONS: Record<string, string> = {
   slots: 'client-side interface-typed browser service — packages/client/ui-renderer/README.md owns the API',
   theme: 'client-side interface-typed browser service — packages/client/ui-theme/README.md owns the API',
   workspaces: 'client-side interface-typed browser service — packages/api/workspace-controller/README.md owns the API',
+  resources: 'client-side resource model (protocol providers, pins, live sources) — packages/client/resources/README.md owns the API',
+  sidebarRight: 'client-side right-Sidebar navigation face — packages/client/ui-sidebar-right/README.md owns the API',
+  sidebarRightTabs: 'client-side right-Sidebar tab-type registry — packages/client/ui-sidebar-right/README.md owns the API',
 }
 
 /**
@@ -408,6 +412,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   CreateGoalRequest: 'goal.md',
   EditGoalRequest: 'goal.md',
   GoalBlockReason: 'goal.md',
+  GoalActivationChanged: 'goal.md',
   GoalChanged: 'goal.md',
   GoalRef: 'goal.md',
   GoalView: 'goal.md',
@@ -755,6 +760,14 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   WorkflowAgentEndInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
   WorkflowAgentInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
   WorkflowResultInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
+  WorkspaceByteRange: 'Host workspace file endpoint contract is owned by packages/api/workspace-files/README.md',
+  WorkspaceDirectoryListing: 'Host workspace file endpoint contract is owned by packages/api/workspace-files/README.md',
+  WorkspaceFileBytes: 'Host workspace file endpoint contract is owned by packages/api/workspace-files/README.md',
+  WorkspaceFileChange: 'Host workspace file endpoint contract is owned by packages/api/workspace-files/README.md',
+  WorkspaceFileWatchFrame: 'Host workspace file endpoint contract is owned by packages/api/workspace-files/README.md',
+  WorkspaceFileRange: 'Host workspace file endpoint contract is owned by packages/api/workspace-files/README.md',
+  WorkspaceFileStat: 'Host workspace file endpoint contract is owned by packages/api/workspace-files/README.md',
+  WorkspaceFileText: 'Host workspace file endpoint contract is owned by packages/api/workspace-files/README.md',
 }
 
 /** Repository data policy consumed by the Cordis catalog projector. */
diff --git a/scripts/gen-cordis-inspect-catalog.ts b/scripts/gen-cordis-inspect-catalog.ts
index cb5ae60b65..552ac07733 100644
--- a/scripts/gen-cordis-inspect-catalog.ts
+++ b/scripts/gen-cordis-inspect-catalog.ts
@@ -10,7 +10,7 @@ const root = resolve(import.meta.dirname, '..')
 const CLIENT_OUT = 'packages/extensions/cordis-client-runner/src/client/api-catalog.ts'
 
 const CLIENT_SERVICES: Readonly<Record<string, readonly string[]>> = {
-  layout: ['toggleSidebar', 'openDetails', 'closeDetails'],
+  layout: ['toggleSidebar', 'openRightbar', 'closeRightbar'],
   locale: ['getLocale', 'getSnapshot', 'subscribe', 'setLocale', 'addLanguage', 'register', 'bind'],
   sessions: ['open', 'openSubagent', 'setSubagentCatalogOpen', 'refreshSubagents', 'search', 'fork', 'scope', 'binding'],
   slots: ['register', 'inject'],
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 0df05a31df..52f3706d6b 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -192,6 +192,13 @@ const SERVICE_ROLES: ServiceRole[] = [
     mode: 'core',
     note: 'Projects the user-settings seam onto the generated Remote namespace: the read is always redacted and every refusal is classified here, not on the seam Definition.',
   },
+  {
+    key: 'workspaceFiles',
+    pkg: 'api-workspace-files',
+    title: 'Host workspace file Remote service',
+    mode: 'core',
+    note: 'Serves stat, paged text, byte windows, directory listings, and the change feed for files inside a Session\'s workspace root, confined by lstat, containment, and a stat re-check.',
+  },
   {
     key: 'workspaceController',
     pkg: 'api-workspace-controller',
diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index f7062c2659..9a16919d36 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -450,7 +450,7 @@ describe('docsPages locale routes', () => {
     const translated = rootPages.filter(page => page.contentLocale === 'zh-CN')
     const fallbacks = rootPages.filter(page => page.contentLocale === 'en-US')
 
-    expect(translated).toHaveLength(46)
+    expect(translated).toHaveLength(48)
     expect(translated.every(page => page.source.endsWith('.zh.md'))).toBe(true)
     expect(fallbacks).toEqual([])
   })
diff --git a/scripts/python-snapshot-workflow-order.spec.ts b/scripts/python-snapshot-workflow-order.spec.ts
new file mode 100644
index 0000000000..964244f5da
--- /dev/null
+++ b/scripts/python-snapshot-workflow-order.spec.ts
@@ -0,0 +1,167 @@
+import { getEventListeners } from 'node:events'
+import { Context } from '@deepseek-ai/cordis'
+import { agentEvents, type Agent, type PreStepDecision } from '@deepseek-ai/dsh-agent'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import { WorkflowRunId } from '@deepseek-ai/dsh-workflow'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
+import SubagentRuntime from '@deepseek-ai/dsh-subagent'
+import * as spawn from '@deepseek-ai/dsh-subagent-spawn-in-process'
+import { MockAdapter, textResponse } from '../packages/core/agent-loop/tests/mock-adapter.ts'
+import type {} from '@deepseek-ai/dsh-tool-workflow'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+// @ts-expect-error Scenario plugins are runtime JavaScript without declaration artifacts.
+import * as fixtureModule from './fixtures/python-snapshot-workflow-order.mjs'
+
+const config = { parentSessionId: 'advanced-parent', prompt: 'workflow child prompt' }
+const fixture = fixtureModule as unknown as {
+  name: string
+  apply(ctx: Context, config: { parentSessionId: string; prompt: string }): void
+}
+const cleanups: (() => Promise<unknown>)[] = []
+afterEach(async () => { for (const cleanup of cleanups.splice(0).reverse()) await cleanup() })
+
+async function harness() {
+  const ctx = new Context()
+  const store = ctx.plugin(SessionStore)
+  await store
+  cleanups.push(() => store.dispose())
+  const fiber = ctx.plugin(fixture, config)
+  await fiber
+  cleanups.push(() => fiber.dispose())
+  const parent = ctx.sessions.create(SessionId(config.parentSessionId))
+  const other = ctx.sessions.create(SessionId('other-parent'))
+  const session = ctx.sessions.create(SessionId('workflow-child'), { meta: { parentSession: parent.id } })
+  // The dispatcher needs only the subject identity; the fixture reads its Session.
+  const agent = { id: session.id, session } as Agent
+  const controller = new AbortController()
+  const messages = [createUserMessage({ content: [{ type: 'text', text: config.prompt }], source: { kind: 'user' } })]
+  const decision: PreStepDecision = { kind: 'enter', messages }
+  const next = vi.fn(async () => decision)
+  const start = (owner = parent, childId = agent.id) => owner.append('tool-workflow/agent-start', {
+    runId: WorkflowRunId('run'), seq: 1, label: 'workflow-child', childId,
+  })
+  const step = (overrides = {}) => agentEvents(ctx, agent).waterfall('agent/pre-step', {
+    turn: 1, step: 1, messages, signal: controller.signal, ...overrides,
+  }, next)
+  return { ctx, fiber, parent, other, session, agent, controller, decision, next, start, step }
+}
+
+describe('advanced Python snapshot workflow ordering', () => {
+  it('blocks a real spawned child before its descriptor and first model request', async () => {
+    const ctx = new Context()
+    const entered = Promise.withResolvers<Agent>()
+    const order: string[] = []
+    const adapter = new MockAdapter([textResponse('child complete')])
+    const assembly = ctx.plugin({
+      name: 'workflow-order-driver-test',
+      async apply(inner: Context) {
+        await mountAgentLoopTestDependencies(inner)
+        await inner.plugin(AgentLoop, { agents: [] })
+        await inner.plugin(SubagentRuntime)
+        await inner.plugin(spawn, { providerName: 'spawn' })
+        inner.on('agent/pre-step', ({ agent }, next) => {
+          if (agent.session.header.parentSession === config.parentSessionId) entered.resolve(agent)
+          return next()
+        })
+        inner.on('session/event', (_session, event) => {
+          if (event.type === 'tool-workflow/agent-start' || event.type === 'subagent/descriptor') order.push(event.type)
+        })
+        await inner.plugin(fixture, config)
+      },
+    })
+    cleanups.push(() => assembly.dispose())
+    await assembly
+    ctx.llm.registerAdapter(['mock'], adapter)
+    const parent = await ctx.agentLoop.create(SessionId(config.parentSessionId), { provider: 'mock', model: 'mock' })
+    const run = await ctx.subagents.start('spawn', {
+      parent, prompt: [{ type: 'text', text: config.prompt }], signal: new AbortController().signal,
+    })
+    cleanups.push(() => run.dispose())
+    const child = await entered.promise
+    expect(child.id).toBe(run.id)
+    expect(adapter.requests).toHaveLength(0)
+    expect(child.session.snapshotEvents().some(event => event.type === 'subagent/descriptor')).toBe(false)
+    parent.session.append('tool-workflow/agent-start', {
+      runId: WorkflowRunId('run'), seq: 1, label: 'workflow-child', childId: child.id,
+    })
+    expect((await run.result).output).toEqual([{ type: 'text', text: 'child complete' }])
+    expect(adapter.requests).toHaveLength(1)
+    expect(order).toEqual(['tool-workflow/agent-start', 'subagent/descriptor'])
+  })
+
+  it('holds the child until the exact parent records the exact member', async () => {
+    const h = await harness()
+    const pending = h.step()
+    expect(h.next).not.toHaveBeenCalled()
+    expect(getEventListeners(h.controller.signal, 'abort')).toHaveLength(1)
+    h.start(h.other)
+    h.start(h.parent, SessionId('other-child'))
+    h.parent.append('tool-workflow/run-start', { runId: WorkflowRunId('run'), name: 'workflow' })
+    await Promise.resolve()
+    expect(h.next).not.toHaveBeenCalled()
+    h.start()
+    expect(await pending).toBe(h.decision)
+    expect(h.next).toHaveBeenCalledOnce()
+    expect(getEventListeners(h.controller.signal, 'abort')).toHaveLength(0)
+  })
+
+  it('retains a start recorded before the child reaches its first step', async () => {
+    const h = await harness()
+    h.start()
+    expect(await h.step()).toBe(h.decision)
+    expect(h.next).toHaveBeenCalledOnce()
+    expect(getEventListeners(h.controller.signal, 'abort')).toHaveLength(0)
+  })
+
+  it.each(['prompt', 'parent', 'turn', 'step'])('does not hold an unrelated %s', async (difference) => {
+    const h = await harness()
+    const overrides = difference === 'prompt' ? { messages: [] }
+      : difference === 'turn' ? { turn: 2 }
+        : difference === 'step' ? { step: 2 } : {}
+    if (difference === 'parent') {
+      const session = h.ctx.sessions.create(SessionId('unrelated-child'), { meta: { parentSession: h.other.id } })
+      Object.assign(h.agent, { session })
+    }
+    expect(await h.step(overrides)).toBe(h.decision)
+    expect(h.next).toHaveBeenCalledOnce()
+  })
+
+  it.each([false, true])('rejects cancellation and detaches the waiter (already aborted: %s)', async (alreadyAborted) => {
+    const h = await harness()
+    const reason = new Error('cancelled child')
+    if (alreadyAborted) h.controller.abort(reason)
+    const pending = h.step()
+    const rejected = expect(pending).rejects.toBe(reason)
+    h.controller.abort(reason)
+    await rejected
+    h.start()
+    expect(h.next).not.toHaveBeenCalled()
+    expect(getEventListeners(h.controller.signal, 'abort')).toHaveLength(0)
+  })
+
+  it('does not admit a cancelled child when start and cancellation share a tick', async () => {
+    const h = await harness()
+    const reason = new Error('cancelled after membership')
+    const pending = h.step()
+    const rejected = expect(pending).rejects.toBe(reason)
+    h.start()
+    h.controller.abort(reason)
+    await rejected
+    expect(h.next).not.toHaveBeenCalled()
+    expect(getEventListeners(h.controller.signal, 'abort')).toHaveLength(0)
+  })
+
+  it('settles pending waits before disposal completes and removes both listeners', async () => {
+    const h = await harness()
+    const pending = h.step()
+    const rejected = expect(pending).rejects.toThrow('workflow snapshot barrier disposed')
+    await h.fiber.dispose()
+    await rejected
+    h.start()
+    expect(h.next).not.toHaveBeenCalled()
+    expect(getEventListeners(h.controller.signal, 'abort')).toHaveLength(0)
+    expect(await h.step()).toBe(h.decision)
+  })
+})
diff --git a/scripts/run-gates.spec.ts b/scripts/run-gates.spec.ts
index 120a976863..f34e4897ab 100644
--- a/scripts/run-gates.spec.ts
+++ b/scripts/run-gates.spec.ts
@@ -240,6 +240,15 @@ describe('gate graph validation', () => {
     },
   )
 
+  it.each(['ci-primary', 'ci-static', 'check-all'] as const)(
+    'keeps review request policy tests in %s',
+    (mode) => {
+      const ids = withPnpmEntrypoint(() => gatesForMode(mode).map(subject => subject.id))
+
+      expect(ids).toContain('request-review')
+    },
+  )
+
   it.each(['ci-primary', 'ci-static', 'check-all', 'hygiene'] as const)(
     'keeps hard-coded Client UI copy enforcement in %s',
     (mode) => {
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 53a01d604e..c5ede4c195 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -267,6 +267,7 @@ export function gatesForMode(selected: Mode): Gate[] {
         pnpmScript('client-domain-graph', 'verify-client-domain-graph', { label: 'client domain graph' }),
         pnpmScript('test', 'test'),
         pnpmScript('issue-management', 'test:issue-management', { label: 'Issue management policy' }),
+        pnpmScript('request-review', 'test:request-review', { label: 'Review request policy' }),
         pnpmScript('duplication', 'duplication'),
         snapshotGate(),
         expectedOutputGate(),
@@ -310,6 +311,7 @@ function ciSharedStaticGates(): Gate[] {
     pnpmScript('client-ui-i18n', 'verify-client-ui-i18n', { label: 'client UI i18n' }),
     pnpmScript('no-bare-dispatcher', 'verify-no-bare-dispatcher', { label: 'proxy-aware dispatchers' }),
     pnpmScript('issue-management', 'test:issue-management', { label: 'Issue management policy' }),
+    pnpmScript('request-review', 'test:request-review', { label: 'Review request policy' }),
   ]
 }
 
diff --git a/scripts/smoke-python-runtime.py b/scripts/smoke-python-runtime.py
index 860d469a64..f6749f4403 100644
--- a/scripts/smoke-python-runtime.py
+++ b/scripts/smoke-python-runtime.py
@@ -11,6 +11,7 @@ import json
 import os
 import queue
 import re
+import secrets
 import shutil
 import subprocess
 import sys
@@ -879,8 +880,9 @@ def smoke_sdk_live() -> None:
             f"containing {LIVE_API_SENTINEL}. Then reply with exactly {LIVE_API_SENTINEL}.\n{marker}"
         )
         verify_prompt = (
-            "Use a tool to read the file created in the previous turn. "
-            f"If its only line is {LIVE_API_SENTINEL}, reply with exactly {LIVE_API_SENTINEL}."
+            "The file created in the previous turn now contains a new value written by the test. "
+            "Use a tool to read its current contents without modifying it. "
+            "Reply with exactly its current single line, not the value from the previous turn."
         )
         with DeepSeekHarness(
             provider="deepseek-official",
@@ -896,34 +898,46 @@ def smoke_sdk_live() -> None:
             request_timeout_seconds=180,
         ) as harness:
             created = harness.run(create_prompt, session_id=session_id)
+            assert_live_turn("create", created, LIVE_API_SENTINEL)
+            if not marker.is_file():
+                raise AssertionError(f"real-model tool turn did not create {marker}")
+            if marker.read_text(encoding="utf-8").splitlines() != [LIVE_API_SENTINEL]:
+                raise AssertionError(f"real-model tool turn wrote unexpected text to {marker}")
+            # Only a fresh filesystem observation can reveal the verification answer.
+            verification_value = secrets.token_hex(16)
+            marker.write_text(verification_value + "\n", encoding="utf-8")
             verified = harness.run(verify_prompt, session_id=session_id)
+            assert_live_turn("verify", verified, verification_value)
 
-        for label, result in (("create", created), ("verify", verified)):
-            if result.finish_reason != "completed":
-                event_types = [event.get("type") for event in result.events]
-                turn_end_data = next(
-                    (event.get("data") for event in reversed(result.events) if event.get("type") == "turn/end"),
-                    None,
-                )
-                turn_end = safe_turn_end(turn_end_data)
-                raise AssertionError(
-                    f"{label} turn ended with {result.finish_reason!r}; "
-                    f"final={result.final_response!r}; turn_end={turn_end!r}; events={event_types}"
-                )
-            if not any(event.get("type") == "tool/call" for event in result.events):
-                raise AssertionError(
-                    f"{label} turn made no model-requested tool call; "
-                    f"final={result.final_response!r}"
-                )
-            if result.final_response.strip() != LIVE_API_SENTINEL:
-                raise AssertionError(f"{label} turn returned {result.final_response!r}")
         if not marker.is_file():
             raise AssertionError(f"real-model tool turn did not create {marker}")
-        if marker.read_text(encoding="utf-8").splitlines() != [LIVE_API_SENTINEL]:
+        if marker.read_text(encoding="utf-8").splitlines() != [verification_value]:
             raise AssertionError(f"real-model tool turn wrote unexpected text to {marker}")
         assert_zstd_session_log(sessions)
 
 
+def assert_live_turn(label: str, result: RunResult, expected: str) -> None:
+    """Require a completed model-requested tool turn with the expected response."""
+    if result.finish_reason != "completed":
+        event_types = [event.get("type") for event in result.events]
+        turn_end_data = next(
+            (event.get("data") for event in reversed(result.events) if event.get("type") == "turn/end"),
+            None,
+        )
+        turn_end = safe_turn_end(turn_end_data)
+        raise AssertionError(
+            f"{label} turn ended with {result.finish_reason!r}; "
+            f"final={result.final_response!r}; turn_end={turn_end!r}; events={event_types}"
+        )
+    if not any(event.get("type") == "tool/call" for event in result.events):
+        raise AssertionError(
+            f"{label} turn made no model-requested tool call; "
+            f"final={result.final_response!r}"
+        )
+    if result.final_response.strip() != expected:
+        raise AssertionError(f"{label} turn returned {result.final_response!r}")
+
+
 def safe_turn_end(value: object) -> object:
     """Project a live-provider failure without retaining credential-bearing text."""
     if not isinstance(value, dict):
@@ -1238,6 +1252,11 @@ def smoke_sdk_snapshot(base_url: str, executable: Path, update_snapshots: bool)
         sessions = dsh_home / "sessions"
         patch = write_advanced_profile_patch(root, "snapshot.patch.yml", sessions)
         feedback_patch = write_profile_patch(root, "feedback.patch.yml", sessions, [{"insert": [
+            {"id": "snapshot-workflow-order", "name": (
+                Path(__file__).resolve().parent / "fixtures/python-snapshot-workflow-order.mjs"
+            ).as_uri(), "config": {
+                "parentSessionId": SNAPSHOT_SESSION_ID, "prompt": SNAPSHOT_WORKFLOW_CHILD_PROMPT,
+            }},
             {"id": "snapshot-message-feedback", "name": "@deepseek-ai/dsh-message-feedback",
              "config": {"maxNoteBytes": 1024}},
             {"id": "snapshot-feedback-producer", "name": (
diff --git a/scripts/snapshot-shell-path.spec.ts b/scripts/snapshot-shell-path.spec.ts
new file mode 100644
index 0000000000..7f32e9cbe8
--- /dev/null
+++ b/scripts/snapshot-shell-path.spec.ts
@@ -0,0 +1,42 @@
+import { Context } from '@deepseek-ai/cordis'
+import LocalSubprocessRuntime from '@deepseek-ai/dsh-subprocess-local'
+import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
+import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { expect, it } from 'vitest'
+import * as adapter from './snapshot-shell-path.ts'
+
+it.skipIf(process.platform === 'win32')('translates only the exact fixture command and preserves real shell failures', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'snapshot-shell-'))
+  const ctx = new Context()
+  const disposers: (() => Promise<void>)[] = []
+  try {
+    const subprocess = ctx.plugin(LocalSubprocessRuntime)
+    disposers.push(() => subprocess.dispose())
+    await subprocess
+    const bash = ctx.plugin(LocalBashExecutor)
+    disposers.push(() => bash.dispose())
+    await bash
+    const command = "printf 'actual bytes' > /fixture/recorded.txt"
+    const livePath = join(root, "space and 'quote.txt")
+    const fork = ctx.plugin(adapter, { command, recordedPath: '/fixture/recorded.txt', livePath })
+    disposers.push(() => fork.dispose())
+    await fork
+    const outcome = await ctx.shell.run(ctx.shell.resolve({ command }))
+    expect(outcome.timedOut).toBe(false)
+    expect(outcome.exitCode).toBe(0)
+    expect(await readFile(livePath, 'utf8')).toBe('actual bytes')
+    const untouched = await ctx.shell.run(ctx.shell.resolve({ command: "printf '/fixture/recorded.txt'; exit 7" }))
+    expect(untouched.exitCode).toBe(7)
+    expect(untouched.stdout.text).toBe('/fixture/recorded.txt')
+    await fork.dispose()
+    await rm(livePath)
+    const restored = await ctx.shell.run(ctx.shell.resolve({ command }))
+    expect(restored.exitCode).not.toBe(0)
+    await expect(readFile(livePath)).rejects.toMatchObject({ code: 'ENOENT' })
+  } finally {
+    for (const dispose of disposers.reverse()) await dispose()
+    await rm(root, { recursive: true, force: true })
+  }
+})
diff --git a/scripts/snapshot-shell-path.ts b/scripts/snapshot-shell-path.ts
new file mode 100644
index 0000000000..42287fabdd
--- /dev/null
+++ b/scripts/snapshot-shell-path.ts
@@ -0,0 +1,30 @@
+/** Exact recorded shell-command path translation; execution and reported outcomes remain real. */
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-shell'
+
+export const name = 'snapshot-shell-path'
+export const inject = ['shell']
+
+/** One recorded command and its isolated live filesystem target. */
+export interface Config {
+  command: string
+  recordedPath: string
+  livePath: string
+}
+
+/**
+ * Translate one exact fixture command after tool logging and approval.
+ * @param ctx - profile context with its real shell executor.
+ * @param config - recorded command/path and allocated live target.
+ */
+export function apply(ctx: Context, config: Config): void {
+  const shell = ctx.shell
+  // oxlint-disable-next-line typescript/unbound-method -- preserve method identity for restoration; calls bind the receiver.
+  const run = shell.run
+  ctx.effect(() => {
+    shell.run = spec => run.call(shell, spec.command === config.command
+      ? { ...spec, command: spec.command.replaceAll(config.recordedPath, "'" + config.livePath.replaceAll("'", "'\"'\"'") + "'") }
+      : spec)
+    return () => { shell.run = run }
+  })
+}
diff --git a/scripts/snapshot-spill-locators.spec.ts b/scripts/snapshot-spill-locators.spec.ts
new file mode 100644
index 0000000000..6bd0f2ef81
--- /dev/null
+++ b/scripts/snapshot-spill-locators.spec.ts
@@ -0,0 +1,68 @@
+import { Context } from '@deepseek-ai/cordis'
+import { LocalSpillStore } from '@deepseek-ai/dsh-spill-local'
+import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import { ToolCallId } from '@deepseek-ai/dsh-llm'
+import { mkdtemp, readFile, realpath, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { expect, it } from 'vitest'
+import * as locators from './snapshot-spill-locators.ts'
+
+it.each([false, true])('keeps concurrent physical spill files private while retaining logical locator length and bytes (reverse allocation=%s)', async (reverseAllocation) => {
+  const roots: string[] = []
+  const disposers: (() => Promise<void>)[] = []
+  const secondAllocated = Promise.withResolvers<undefined>()
+  try {
+    const runs = await Promise.all([0, 1].map(async (index) => {
+      if (reverseAllocation && index === 0) await secondAllocated.promise
+      const root = await mkdtemp(join(tmpdir(), 'snapshot-locator-'))
+      roots.push(root)
+      if (index === 1) secondAllocated.resolve(undefined)
+      const ctx = new Context()
+      const storeFiber = ctx.plugin(LocalSpillStore, { root, cleanupPeriodDays: 0 })
+      disposers.push(() => storeFiber.dispose())
+      await storeFiber
+      const fsFiber = ctx.plugin(LocalFileSystem, { cwd: root })
+      disposers.push(() => fsFiber.dispose())
+      await fsFiber
+
+
+      const locatorRoot = resolve('/tmp/dsh-acp-snap-123456789')
+      const fork = ctx.plugin(locators, { root, locatorRoot })
+      disposers.push(() => fork.dispose())
+      await fork
+      const content = `physical UTF-8 内容 ${index}`
+      const ref = await ctx.spillStore.saveText({
+        owner: { sessionId: SessionId('same-session') },
+        source: { kind: 'tool', toolName: 'bash', callId: ToolCallId('same-call'), label: 'result' },
+        suggestedName: 'bash.txt', content,
+      })
+      expect(ref.bytes).toBe(Buffer.byteLength(content))
+      expect(ref.locator.startsWith(locatorRoot)).toBe(true)
+      const target = await ctx.fs.resolve(ref.locator)
+      expect(target.displayPath).toBe(ref.locator)
+      const physicalPath = ctx.fs.processPath(target)
+      expect(physicalPath.startsWith(await realpath(root))).toBe(true)
+      expect(await readFile(physicalPath, 'utf8')).toBe(content)
+      expect(await ctx.fs.readText(target)).toBe(content)
+      await expect(ctx.fs.resolve(join(locatorRoot, 'missing.txt'))).rejects.toThrow('not saved by this run')
+      const ordinary = join(root, 'ordinary.txt')
+      await writeFile(ordinary, 'ordinary')
+      expect(await ctx.fs.readText(await ctx.fs.resolve(ordinary))).toBe('ordinary')
+      await fork.dispose()
+      const restored = await ctx.fs.resolve(ref.locator)
+      expect(ctx.fs.processPath(restored)).not.toBe(physicalPath)
+      expect(await ctx.fs.stat(restored)).toBeUndefined()
+      return { root, physicalPath, locator: ref.locator, content }
+    }))
+    expect(runs[0]?.physicalPath).not.toBe(runs[1]?.physicalPath)
+    expect(runs[0]?.locator.length).toBe(runs[1]?.locator.length)
+    // Promise.all preserves input order; allocation completion order may differ.
+    await rm(runs[0]!.root, { recursive: true, force: true })
+    expect(await readFile(runs[1]?.physicalPath as string, 'utf8')).toBe(runs[1]?.content)
+  } finally {
+    for (const dispose of disposers.reverse()) await dispose()
+    await Promise.all(roots.map(root => rm(root, { recursive: true, force: true })))
+  }
+})
diff --git a/scripts/snapshot-spill-locators.ts b/scripts/snapshot-spill-locators.ts
new file mode 100644
index 0000000000..7c0762c289
--- /dev/null
+++ b/scripts/snapshot-spill-locators.ts
@@ -0,0 +1,59 @@
+/** Fixture-only logical locators over real local spill files; preview budgets retain recorded path lengths. */
+import type { Context } from '@deepseek-ai/cordis'
+import { join, relative, resolve, sep } from 'node:path'
+import type { SpillLocator } from '@deepseek-ai/dsh-spill'
+import type {} from '@deepseek-ai/dsh-fs'
+
+export const name = 'snapshot-spill-locators'
+export const inject = ['spillStore', 'fs']
+
+/** Live storage and recorded locator prefixes supplied by the snapshot owner. */
+export interface Config {
+  root: string
+  locatorRoot: string
+}
+
+/**
+ * Translate only locators returned by this fixture's real spill backend.
+ * @param ctx - profile context with real spill and filesystem providers.
+ * @param config - per-run storage and stable logical prefix.
+ */
+export function apply(ctx: Context, config: Config): void {
+  const root = resolve(config.root)
+  const locatorRoot = resolve(config.locatorRoot)
+  const paths = new Map<string, string>()
+  const store = ctx.spillStore
+  const fs = ctx.fs
+  // oxlint-disable-next-line typescript/unbound-method -- preserve method identity for restoration; calls bind the receiver.
+  const saveText = store.saveText
+  // oxlint-disable-next-line typescript/unbound-method -- preserve method identity for restoration; calls bind the receiver.
+  const resolvePath = fs.resolve
+  ctx.effect(() => {
+    store.saveText = async (input) => {
+      const saved = await saveText.call(store, input)
+      const suffix = relative(root, saved.locator)
+      if (suffix.startsWith('..') || resolve(root, suffix) !== saved.locator) {
+        throw new Error('snapshot spill backend returned a locator outside its live root')
+      }
+      const locator = join(locatorRoot, suffix) as SpillLocator
+      paths.set(locator, saved.locator)
+      return { ...saved, locator }
+    }
+    fs.resolve = async (path, opts) => {
+      const live = paths.get(path)
+      if (live !== undefined) {
+        const target = await resolvePath.call(fs, live, opts)
+        return { ...target, displayPath: path }
+      }
+      if (path.startsWith(locatorRoot + sep)) {
+        throw new Error('snapshot spill locator was not saved by this run')
+      }
+      return resolvePath.call(fs, path, opts)
+    }
+    return () => {
+      store.saveText = saveText
+      fs.resolve = resolvePath
+      paths.clear()
+    }
+  })
+}
diff --git a/scripts/snapshot-workspace-parent.spec.ts b/scripts/snapshot-workspace-parent.spec.ts
new file mode 100644
index 0000000000..ec4ebf551c
--- /dev/null
+++ b/scripts/snapshot-workspace-parent.spec.ts
@@ -0,0 +1,78 @@
+import { existsSync } from 'node:fs'
+import { chmod, mkdir, mkdtemp, readFile, rm, stat, symlink } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
+import { dirname, join, parse } from 'node:path'
+import { Context } from '@deepseek-ai/cordis'
+import { SandboxedFileSystem } from '@deepseek-ai/dsh-fs-sandbox'
+import { canonicalPath } from '@deepseek-ai/dsh-sandbox'
+import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
+import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
+import { describe, expect, it } from 'vitest'
+import { assertWorkspaceOutsideTemp, outsideTempWorkspaceParent } from './snapshot-workspace-parent.ts'
+
+// Host disk exhaustion is not simulated: placement and the real write fence are the regression oracles.
+describe('snapshot workspace parent', () => {
+  // Windows directory permissions and root bypass do not enforce POSIX write bits.
+  it.skipIf(process.platform === 'win32' || process.getuid?.() === 0)('uses home when the temp parent is not writable', async () => {
+    const base = await mkdtemp(join(outsideTempWorkspaceParent(), '.dsh-snapshot-readonly-'))
+    try {
+      const temporary = join(base, '_temp')
+      await mkdir(temporary)
+      await chmod(base, 0o500)
+      expect(outsideTempWorkspaceParent(temporary)).toBe(homedir())
+    } finally {
+      await chmod(base, 0o700)
+      await rm(base, { recursive: true, force: true })
+    }
+  })
+
+  it('uses home when a temp sibling would require a system directory or inherit its grant', () => {
+    expect(outsideTempWorkspaceParent('/tmp')).toBe(homedir())
+    expect(outsideTempWorkspaceParent(parse(tmpdir()).root)).toBe(homedir())
+    expect(outsideTempWorkspaceParent(join(canonicalPath('/tmp'), 'runner', '_temp'))).toBe(homedir())
+  })
+
+  it('rejects automatically writable temporary workspaces, including symlink aliases', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-snapshot-parent-'))
+    try {
+      expect(() => { assertWorkspaceOutsideTemp(root) }).toThrow('must be outside temporary writable root')
+      const alias = join(root, 'alias')
+      await symlink(tmpdir(), alias, process.platform === 'win32' ? 'junction' : 'dir')
+      expect(() => { assertWorkspaceOutsideTemp(alias) }).toThrow('must be outside temporary writable root')
+    } finally {
+      await rm(root, { recursive: true, force: true })
+    }
+  })
+
+  it('allows the allocated workspace but denies sibling writes and cleans the complete tree', async () => {
+    const base = await mkdtemp(join(outsideTempWorkspaceParent(), 'dsh-snapshot-parent-'))
+    const ctx = new Context()
+    const fibers: Awaited<ReturnType<Context['plugin']>>[] = []
+    try {
+      const temporary = join(base, '_temp')
+      await mkdir(temporary)
+      expect(outsideTempWorkspaceParent(temporary)).toBe(canonicalPath(base))
+      const workspace = await mkdtemp(join(outsideTempWorkspaceParent(temporary), 'workspace-'))
+      const outside = join(base, 'outside.txt')
+      assertWorkspaceOutsideTemp(workspace)
+      expect(dirname(workspace)).toBe(canonicalPath(base))
+      expect((await stat(workspace)).dev).toBe((await stat(temporary)).dev)
+      fibers.push(await ctx.plugin(SessionProjectionRegistry))
+      fibers.push(await ctx.plugin(SandboxPolicyService, { mode: 'workspace-write', workspaceRoot: workspace }))
+      fibers.push(await ctx.plugin(SandboxedFileSystem, { cwd: workspace }))
+      const inside = join(workspace, 'inside.txt')
+      await ctx.fs.writeText(await ctx.fs.resolve(inside), 'inside')
+      expect(await readFile(inside, 'utf8')).toBe('inside')
+      await expect(ctx.fs.writeText(await ctx.fs.resolve(outside), 'outside'))
+        .rejects.toMatchObject({ code: 'FS_SANDBOX_DENIED' })
+      expect(existsSync(outside)).toBe(false)
+    } finally {
+      try {
+        for (const fiber of fibers.reverse()) await fiber.dispose()
+      } finally {
+        await rm(base, { recursive: true, force: true })
+      }
+    }
+    expect(existsSync(base)).toBe(false)
+  })
+})
diff --git a/scripts/snapshot-workspace-parent.ts b/scripts/snapshot-workspace-parent.ts
new file mode 100644
index 0000000000..4a56ab5754
--- /dev/null
+++ b/scripts/snapshot-workspace-parent.ts
@@ -0,0 +1,46 @@
+/** Workspace placement for snapshots that must not inherit temporary-directory write grants. */
+
+import { accessSync, constants } from 'node:fs'
+import { homedir, tmpdir } from 'node:os'
+import { dirname, isAbsolute, parse, relative, sep } from 'node:path'
+import { canonicalPath, writableRoots } from '@deepseek-ai/dsh-sandbox'
+
+function contains(root: string, path: string): boolean {
+  const suffix = relative(root, path)
+  return suffix === '' || suffix !== '..' && !suffix.startsWith('..' + sep) && !isAbsolute(suffix)
+}
+
+/**
+ * Select a writable temp sibling parent, or home when that parent is unavailable for writes.
+ * The caller atomically allocates and owns cleanup of the generated workspace.
+ * @param tempRoot - platform temporary directory.
+ * @param home - fallback when temp siblings require a system directory or a non-writable parent.
+ * @returns existing parent outside the automatic temporary write grants.
+ */
+export function outsideTempWorkspaceParent(tempRoot = tmpdir(), home = homedir()): string {
+  const temporary = canonicalPath(tempRoot)
+  const systemTemporary = canonicalPath('/tmp')
+  const parent = dirname(temporary)
+  if (temporary === systemTemporary || parent === parse(parent).root || contains(systemTemporary, parent)) return home
+  try {
+    accessSync(parent, constants.W_OK)
+  } catch (error) {
+    // A non-writable parent cannot host siblings; allocation failures still propagate from mkdtemp.
+    const code = (error as NodeJS.ErrnoException).code
+    if (code === 'EACCES' || code === 'EPERM' || code === 'EROFS') return home
+    throw error
+  }
+  return parent
+}
+
+/**
+ * Reject a workspace whose write could succeed without the session's workspace grant.
+ * @param cwd - allocated workspace to check, with symlinks resolved before comparison.
+ * @returns nothing; throws when an automatic temporary write grant contains the workspace.
+ */
+export function assertWorkspaceOutsideTemp(cwd: string): void {
+  const path = canonicalPath(cwd)
+  for (const root of writableRoots({ mode: 'workspace-write', workspaceRoot: '/tmp' })) {
+    if (contains(root, path)) throw new Error('snapshot workspace ' + cwd + ' must be outside temporary writable root ' + root)
+  }
+}
diff --git a/scripts/tests/ci-release-selfhosted.spec.ts b/scripts/tests/ci-release-selfhosted.spec.ts
index 99ce317248..4a357114ba 100644
--- a/scripts/tests/ci-release-selfhosted.spec.ts
+++ b/scripts/tests/ci-release-selfhosted.spec.ts
@@ -38,6 +38,12 @@ function evaluate(expression: string, context: Record<string, string | boolean>)
   return runInNewContext(source, { fromJSON: JSON.parse }, { timeout: 1000 }) as unknown
 }
 
+function assertSharedPersistentStore(run: string | undefined): void {
+  expect(run).toContain('store_root="$HOME/.local/share/pnpm/store"')
+  expect(run).toContain('echo "PNPM_CONFIG_STORE_DIR=$store_root" >> "$GITHUB_ENV"')
+  expect(run).toContain('store_path=$(PNPM_CONFIG_STORE_DIR="$store_root" pnpm store path --silent)')
+}
+
 const trustedPr = {
   'vars.DSH_CI_FAILOVER_LINUX': 'selfhosted',
   'github.repository': repository,
@@ -108,8 +114,18 @@ for (const [file, jobIds] of [['release.yml', ['dependencies', 'pack']], ['relea
             .toBe('${{ runner.temp }}/setup-pnpm-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}')
           expect(job.steps.find(step => step.name === 'Install (immutable)')?.run).toBe('pnpm install --frozen-lockfile')
         })
-        it('uses the persistent store without remote cache reads or writes on self-hosted', () => {
-          expect(job.steps.find(step => step.name === 'Configure pnpm store path')?.run).toContain('store_root="$HOME/.local/share/pnpm/store"')
+        it('retains the configured shared npm cache', () => {
+          expect(JSON.stringify(release)).not.toMatch(/npm_config_cache/i)
+        })
+        it.each(['', 'store_root="${RUNNER_TEMP%/*}/pnpm-store"', 'store_root="$RUNNER_TEMP/pnpm-store"'])(
+          'rejects missing, runner-private, or job-temporary store placement: %s', (replacement) => {
+            const run = job.steps.find(step => step.name === 'Configure pnpm store path')?.run
+              ?.replace('store_root="$HOME/.local/share/pnpm/store"', replacement)
+            expect(() => { assertSharedPersistentStore(run) }).toThrow()
+          },
+        )
+        it('uses the shared persistent store without remote cache reads or writes on self-hosted', () => {
+          assertSharedPersistentStore(job.steps.find(step => step.name === 'Configure pnpm store path')?.run)
           const caches = job.steps.filter(step => step.uses?.startsWith('actions/cache'))
           expect(caches.map(step => step.uses)).toEqual(['actions/cache/restore@v4'])
           for (const step of caches) {
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index c843a901ed..0c5df1b9e2 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -207,6 +207,11 @@
       "symbol": "GoalView",
       "source": "packages/goal/goal/src/types.ts"
     },
+    {
+      "doc": "docs/subsystems/goal.md",
+      "symbol": "GoalActivationChanged",
+      "source": "packages/goal/goal/src/types.ts"
+    },
     {
       "doc": "docs/subsystems/goal.md",
       "symbol": "GoalSnapshotChangeMeta",
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index e2300ec26d..449ee7322a 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -84,6 +84,8 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/experimental/agent-team-web-profile': { kind: 'indirect', reason: 'The private Web layer delegates model composition to the Host-side Agent Teams profile.' },
   'packages/experimental/client-ui-agent-team': { kind: 'none', reason: 'The browser projection and task controls register no model-facing input.' },
   'packages/client/ui-layout': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-dockkit': { kind: 'none', reason: 'Browser-side docking layout engine and components; registers nothing model-facing.' },
+  'packages/client/ui-sidebar-right': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
   'packages/client/ui-sidebar': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
   'packages/client/ui-brand-official': { kind: 'none', reason: 'Browser-side presentation occupants; registers nothing model-facing.' },
   'packages/client/ui-conversation': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
@@ -109,6 +111,9 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/client/ui-directory-picker-browse': { kind: 'none', reason: 'Browser-side directory-browsing surface; registers nothing model-facing.' },
   'packages/client/ui-directory-picker-native': { kind: 'none', reason: 'Browser-side surface driving the host OS chooser; registers nothing model-facing.' },
   'packages/client/ui-theme': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-sidebar-textpreview': { kind: 'none', reason: 'Browser-only text viewer; registers no tool, prompt section, or session event, and what the user reads never enters a model request.' },
+  'packages/client/ui-sidebar-files': { kind: 'none', reason: 'Browser-only workspace file tree; registers no tool, prompt section, or session event.' },
+  'packages/client/resources': { kind: 'none', reason: 'Browser-side resource model (providers, pinning, useResource); registers nothing model-facing.' },
   'packages/client/ui-settings': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
   'packages/client/ui-settings-general': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
   'packages/client/ui-settings-models': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
@@ -173,6 +178,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/api/session-controller': { kind: 'none', reason: 'Session API and transport owner; invoked Agent commands own any model-visible effect.' },
   'packages/api/settings-controller': { kind: 'none', reason: 'Configuration-surface API owner; it registers no prompt, tool, or session event.' },
   'packages/api/workspace-controller': { kind: 'none', reason: 'Workspace API and state projection owner; it registers no prompt, tool, or session event.' },
+  'packages/api/workspace-files': { kind: 'none', reason: 'Workspace file read API and its Client resource provider; it registers no prompt, tool, or session event.' },
   'packages/typert/protocol': { kind: 'none', reason: 'Compiler-independent Remote protocol declarations; registers nothing model-facing.' },
   'packages/typert/generator': { kind: 'none', reason: 'The build-time generator runs outside any agent runtime and touches no model request.' },
   'packages/jobs/jobs': { kind: 'indirect', reason: 'Producer and controller plugins own all model rendering over the job registry.' },
diff --git a/snapshots/acp/escalation-approved/cordis.snapshot.yml b/snapshots/acp/escalation-approved/cordis.snapshot.yml
index 512708ce64..20f54d6390 100644
--- a/snapshots/acp/escalation-approved/cordis.snapshot.yml
+++ b/snapshots/acp/escalation-approved/cordis.snapshot.yml
@@ -42,3 +42,11 @@
 
     - id: subagent-settlement-marker
       name: './subagent-settlement-marker.ts'
+
+- insert:
+    - id: snapshot-shell-path
+      name: ../../../scripts/snapshot-shell-path.ts
+      config:
+        command: "printf 'escalated\\n' > /tmp/dsh-escalated.txt && cat /tmp/dsh-escalated.txt && rm /tmp/dsh-escalated.txt"
+        recordedPath: /tmp/dsh-escalated.txt
+        livePath: !!js process.env.DSH_SNAPSHOT_SPILL_ROOT + '/dsh-escalated.txt'
diff --git a/snapshots/sdk/subagent-dsh-sdk-diagnostic/notifications.expected.jsonl b/snapshots/sdk/subagent-dsh-sdk-diagnostic/notifications.expected.jsonl
index 1d8c48d2a0..fd046fa342 100644
--- a/snapshots/sdk/subagent-dsh-sdk-diagnostic/notifications.expected.jsonl
+++ b/snapshots/sdk/subagent-dsh-sdk-diagnostic/notifications.expected.jsonl
@@ -8,25 +8,25 @@
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"session/title","seq":9,"time":0,"data":{"title":"Observe the DSH SDK diagnostic","messageSeqs":[7],"source":{"kind":"fallback"}}}}}
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"request/header","seq":10,"time":0,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}}}
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"request/context","seq":11,"time":0,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}}}
-{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"session-log-deepseek/delivery-accepted","seq":12,"time":0,"data":{"sessionId":"{{sessionId}}"}}}}
+{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"session-log-deepseek/delivery-accepted","seq":12,"time":0,"data":{"sessionId":"{{sessionId}}","throughSeq":11}}}}
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":13,"time":0,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_dsh_sdk_foreground","name":"subagent_dsh_sdk","arguments":"{\"description\":\"Observe DSH SDK foreground failure\",\"prompt\":\"Return the scripted DSH SDK failure.\",\"run_in_background\":false}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{sessionId}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"call_dsh_sdk_foreground","name":"subagent_dsh_sdk","args":["{\"description\":\"Observe DSH SDK foreground failure\",\"prompt\":\"Return the scripted DSH SDK failure.\",\"run_in_background\":false}"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_dsh_sdk_foreground","name":"subagent_dsh_sdk","arguments":"{\"description\":\"Observe DSH SDK foreground failure\",\"prompt\":\"Return the scripted DSH SDK failure.\",\"run_in_background\":false}"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}}}
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"tool/call","seq":14,"time":0,"data":{"turn":1,"step":1,"callId":"call_dsh_sdk_foreground","name":"subagent_dsh_sdk","arguments":"{\"description\":\"Observe DSH SDK foreground failure\",\"prompt\":\"Return the scripted DSH SDK failure.\",\"run_in_background\":false}"}}}}
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"tool/result","seq":15,"time":0,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_dsh_sdk_foreground"},"content":[{"type":"tool-result","toolCallId":"call_dsh_sdk_foreground","content":[{"type":"text","text":"Error: subagent run failed\nDiagnostic: Subagent failure (provider: DSH SDK; stage: session-run; category: child-error)\nPartial output before the run ended:\npartial child loader answer"}],"isError":true}],"role":"user","id":"{{sessionId}}"}},"sourceEventSeqs":[14],"surfaceOp":"append"}}}
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"step/end","seq":16,"time":0,"data":{"turn":1,"step":1}}}}
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"step/start","seq":17,"time":0,"data":{"turn":1,"step":2}}}}
-{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"session-log-deepseek/delivery-accepted","seq":18,"time":0,"data":{"sessionId":"{{sessionId}}"}}}}
+{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"session-log-deepseek/delivery-accepted","seq":18,"time":0,"data":{"sessionId":"{{sessionId}}","throughSeq":17}}}}
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":19,"time":0,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_dsh_sdk_background","name":"subagent_dsh_sdk_background","arguments":"{\"description\":\"Observe DSH SDK background failure\",\"prompt\":\"Return the scripted DSH SDK failure.\",\"run_in_background\":true}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{sessionId}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"call_dsh_sdk_background","name":"subagent_dsh_sdk_background","args":["{\"description\":\"Observe DSH SDK background failure\",\"prompt\":\"Return the scripted DSH SDK failure.\",\"run_in_background\":true}"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_dsh_sdk_background","name":"subagent_dsh_sdk_background","arguments":"{\"description\":\"Observe DSH SDK background failure\",\"prompt\":\"Return the scripted DSH SDK failure.\",\"run_in_background\":true}"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}}}
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"tool/call","seq":20,"time":0,"data":{"turn":1,"step":2,"callId":"call_dsh_sdk_background","name":"subagent_dsh_sdk_background","arguments":"{\"description\":\"Observe DSH SDK background failure\",\"prompt\":\"Return the scripted DSH SDK failure.\",\"run_in_background\":true}"}}}}
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"tool/result","seq":21,"time":0,"data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"call_dsh_sdk_background"},"content":[{"type":"tool-result","toolCallId":"call_dsh_sdk_background","content":[{"type":"text","text":"started background subagent job subagent-1"}],"isError":false}],"role":"user","id":"{{sessionId}}"}},"sourceEventSeqs":[20],"surfaceOp":"append"}}}
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"step/end","seq":22,"time":0,"data":{"turn":1,"step":2}}}}
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"step/start","seq":23,"time":0,"data":{"turn":1,"step":3}}}}
-{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"session-log-deepseek/delivery-accepted","seq":24,"time":0,"data":{"sessionId":"{{sessionId}}"}}}}
+{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"session-log-deepseek/delivery-accepted","seq":24,"time":0,"data":{"sessionId":"{{sessionId}}","throughSeq":23}}}}
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":25,"time":0,"data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_dsh_sdk_output","name":"job_output","arguments":"{\"job_id\":\"subagent-1\",\"wait\":true}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{sessionId}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"call_dsh_sdk_output","name":"job_output","args":["{\"job_id\":\"subagent-1\",\"wait\":true}"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_dsh_sdk_output","name":"job_output","arguments":"{\"job_id\":\"subagent-1\",\"wait\":true}"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}}}
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"tool/call","seq":26,"time":0,"data":{"turn":1,"step":3,"callId":"call_dsh_sdk_output","name":"job_output","arguments":"{\"job_id\":\"subagent-1\",\"wait\":true}"}}}}
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"tool/result","seq":27,"time":0,"data":{"turn":1,"step":3,"message":{"source":{"kind":"tool","callId":"call_dsh_sdk_output"},"content":[{"type":"tool-result","toolCallId":"call_dsh_sdk_output","content":[{"type":"text","text":"(no new output)\n[status: failed, error; diagnostic: Subagent failure (provider: DSH SDK; stage: session-run; category: child-error)]"}],"isError":false}],"role":"user","id":"{{sessionId}}"}},"sourceEventSeqs":[26],"surfaceOp":"append"}}}
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"step/end","seq":28,"time":0,"data":{"turn":1,"step":3}}}}
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"step/start","seq":29,"time":0,"data":{"turn":1,"step":4}}}}
-{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"session-log-deepseek/delivery-accepted","seq":30,"time":0,"data":{"sessionId":"{{sessionId}}"}}}}
+{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"session-log-deepseek/delivery-accepted","seq":30,"time":0,"data":{"sessionId":"{{sessionId}}","throughSeq":29}}}}
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":31,"time":0,"data":{"turn":1,"step":4,"message":{"role":"assistant","content":[{"type":"text","text":"PARENT_OBSERVED_DSH_SDK_DIAGNOSTIC"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{sessionId}}"},"usage":{"inputTokens":10,"outputTokens":2},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":0,"index":0,"dt":[],"texts":["PARENT_OBSERVED_DSH_SDK_DIAGNOSTIC"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"PARENT_OBSERVED_DSH_SDK_DIAGNOSTIC"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":2}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}}}
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"step/end","seq":32,"time":0,"data":{"turn":1,"step":4}}}}
 {"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"turn/end","seq":33,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}}}
diff --git a/snapshots/session/fs-glob-sampling/cordis.snapshot.yml b/snapshots/session/fs-glob-sampling/cordis.snapshot.yml
index 2df89dc41f..2a1eacf554 100644
--- a/snapshots/session/fs-glob-sampling/cordis.snapshot.yml
+++ b/snapshots/session/fs-glob-sampling/cordis.snapshot.yml
@@ -79,3 +79,10 @@
   name: '@deepseek-ai/dsh-spill-local'
   config:
     root: !!js process.env.DSH_SNAPSHOT_SPILL_ROOT ?? './.spill'
+
+- insert:
+    - id: snapshot-spill-locators
+      name: ../../../scripts/snapshot-spill-locators.ts
+      config:
+        root: !!js process.env.DSH_SNAPSHOT_SPILL_ROOT
+        locatorRoot: !!js process.env.DSH_SNAPSHOT_SPILL_LOCATOR_ROOT
diff --git a/snapshots/session/fs-glob-sampling/cordis.yml b/snapshots/session/fs-glob-sampling/cordis.yml
index efb2b7a1a2..42151991b5 100644
--- a/snapshots/session/fs-glob-sampling/cordis.yml
+++ b/snapshots/session/fs-glob-sampling/cordis.yml
@@ -71,3 +71,10 @@
   name: '@deepseek-ai/dsh-spill-local'
   config:
     root: !!js process.env.DSH_SNAPSHOT_SPILL_ROOT ?? './.spill'
+
+- insert:
+    - id: snapshot-spill-locators
+      name: ../../../scripts/snapshot-spill-locators.ts
+      config:
+        root: !!js process.env.DSH_SNAPSHOT_SPILL_ROOT
+        locatorRoot: !!js process.env.DSH_SNAPSHOT_SPILL_LOCATOR_ROOT
diff --git a/snapshots/session/headless.snapshot.ts b/snapshots/session/headless.snapshot.ts
index aa58c005e8..e775b689cf 100644
--- a/snapshots/session/headless.snapshot.ts
+++ b/snapshots/session/headless.snapshot.ts
@@ -3,11 +3,12 @@
 import { cp, copyFile, mkdir, mkdtemp, readFile, readdir, rm, utimes, writeFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { spawnSync } from 'node:child_process'
-import { homedir, tmpdir } from 'node:os'
+import { tmpdir } from 'node:os'
 import { basename, delimiter, dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 import ts from 'typescript'
+import { assertWorkspaceOutsideTemp, outsideTempWorkspaceParent } from '../../scripts/snapshot-workspace-parent.ts'
 import {
   assertPersistedSessionVersion,
   assertSessionFixtureVersion,
@@ -846,14 +847,13 @@ describe('headless recorded-session snapshots', () => {
       let actualLogs: SessionLog[] = []
       let initialWorkspace: WorkspaceSnapshotEntry[] | undefined
       let finalWorkspace: WorkspaceSnapshotEntry[] | undefined
-      const spillRoot = snapshotSpillRoot(join(scenario.dir, fixtureFiles[0] as string))
-      await rm(spillRoot, { recursive: true, force: true })
+      const spillRoot = await mkdtemp(join(tmpdir(), 'acp-snap-spill-'))
       let result: Awaited<ReturnType<typeof runLoaderSmoke>>
       try {
         result = await runLoaderSmoke({
           label: `${scenario.name} headless snapshot`,
           tempDirPrefix: 'dsh-log-snap-',
-          ...(scenario.manifest.workspace?.parent === 'home' ? { tempDirParent: homedir() } : {}),
+          ...(scenario.manifest.workspace?.parent === 'outside-temp' ? { tempDirParent: outsideTempWorkspaceParent() } : {}),
           binScript: dshBin,
           configPath: join(baseComposition.dir, 'cordis.yml'),
           binArgs: [
@@ -871,6 +871,7 @@ describe('headless recorded-session snapshots', () => {
             DSH_SNAPSHOT_PROVIDER: model.provider,
             DSH_SNAPSHOT_MODEL: model.model,
             DSH_SNAPSHOT_SPILL_ROOT: spillRoot,
+            DSH_SNAPSHOT_SPILL_LOCATOR_ROOT: snapshotSpillRoot(join(scenario.dir, fixtureFiles[0] as string)),
             DSH_SNAPSHOT_FILE: join(scenario.dir, fixtureFiles[0] as string),
             ...(replaying && fixtureFiles.length > 1
               ? { DSH_SNAPSHOT_CHILD_FILES: fixtureFiles.slice(1).map(file => join(scenario.dir, file)).join(delimiter) }
@@ -886,6 +887,7 @@ describe('headless recorded-session snapshots', () => {
             DSH_TELEMETRY_DISABLED: '1',
           },
           prepare: async (cwd) => {
+            if (scenario.manifest.workspace?.parent === 'outside-temp') assertWorkspaceOutsideTemp(cwd)
             await mkdir(join(cwd, patchRoot), { recursive: true })
             patchSources.forEach((source, index) => {
               if (source.endsWith('.snapshot.yml')) {
diff --git a/snapshots/session/parallel-tool-calls/cordis.snapshot.yml b/snapshots/session/parallel-tool-calls/cordis.snapshot.yml
index 464c92d071..88e3e67c99 100644
--- a/snapshots/session/parallel-tool-calls/cordis.snapshot.yml
+++ b/snapshots/session/parallel-tool-calls/cordis.snapshot.yml
@@ -50,3 +50,10 @@
   name: '@deepseek-ai/dsh-spill-policy'
   config:
     maxInlineBytes: 800
+
+- insert:
+    - id: snapshot-spill-locators
+      name: ../../../scripts/snapshot-spill-locators.ts
+      config:
+        root: !!js process.env.DSH_SNAPSHOT_SPILL_ROOT
+        locatorRoot: !!js process.env.DSH_SNAPSHOT_SPILL_LOCATOR_ROOT
diff --git a/snapshots/session/parallel-tool-calls/cordis.yml b/snapshots/session/parallel-tool-calls/cordis.yml
index 940fb9bd21..3782b6ea8d 100644
--- a/snapshots/session/parallel-tool-calls/cordis.yml
+++ b/snapshots/session/parallel-tool-calls/cordis.yml
@@ -11,3 +11,10 @@
   name: '@deepseek-ai/dsh-spill-policy'
   config:
     maxInlineBytes: !!js process.env.DSH_SNAPSHOT && 800 || 50000
+
+- insert:
+    - id: snapshot-spill-locators
+      name: ../../../scripts/snapshot-spill-locators.ts
+      config:
+        root: !!js process.env.DSH_SNAPSHOT_SPILL_ROOT
+        locatorRoot: !!js process.env.DSH_SNAPSHOT_SPILL_LOCATOR_ROOT
diff --git a/snapshots/session/session-query-spill/cordis.snapshot.yml b/snapshots/session/session-query-spill/cordis.snapshot.yml
index b433f0726f..a1e24b3518 100644
--- a/snapshots/session/session-query-spill/cordis.snapshot.yml
+++ b/snapshots/session/session-query-spill/cordis.snapshot.yml
@@ -58,3 +58,18 @@
 
 - id: timeout-policy
   name: '@deepseek-ai/dsh-tool-call-timeout-policy'
+
+- insert:
+    - id: snapshot-spill-locators
+      name: ../../../scripts/snapshot-spill-locators.ts
+      config:
+        root: !!js process.env.DSH_SNAPSHOT_SPILL_ROOT
+        locatorRoot: !!js process.env.DSH_SNAPSHOT_SPILL_LOCATOR_ROOT
+
+- insert:
+    - id: snapshot-shell-path
+      name: ../../../scripts/snapshot-shell-path.ts
+      config:
+        command: "file=$(find /tmp/dsh-acp-snap-035d1d054 -name '*-session_event_read.txt' -type f); grep -q request/header \"$file\" && grep -q session_event_search \"$file\" && echo SPILL_CANONICAL_OK"
+        recordedPath: /tmp/dsh-acp-snap-035d1d054
+        livePath: !!js process.env.DSH_SNAPSHOT_SPILL_ROOT
diff --git a/snapshots/session/session-query-spill/cordis.yml b/snapshots/session/session-query-spill/cordis.yml
index ce9d627e93..ef6a8b3a1c 100644
--- a/snapshots/session/session-query-spill/cordis.yml
+++ b/snapshots/session/session-query-spill/cordis.yml
@@ -20,3 +20,10 @@
 
 - id: timeout-policy
   name: '@deepseek-ai/dsh-tool-call-timeout-policy'
+
+- insert:
+    - id: snapshot-spill-locators
+      name: ../../../scripts/snapshot-spill-locators.ts
+      config:
+        root: !!js process.env.DSH_SNAPSHOT_SPILL_ROOT
+        locatorRoot: !!js process.env.DSH_SNAPSHOT_SPILL_LOCATOR_ROOT
diff --git a/snapshots/session/session-reference-spill/cordis.snapshot.yml b/snapshots/session/session-reference-spill/cordis.snapshot.yml
index aa1b3be225..3a57fbac17 100644
--- a/snapshots/session/session-reference-spill/cordis.snapshot.yml
+++ b/snapshots/session/session-reference-spill/cordis.snapshot.yml
@@ -52,3 +52,10 @@
         maxReferenceBytes: 360
     - id: reference-source-fixture
       name: ../../../packages/context/session-reference/tests/fixtures/source-session.ts
+
+- insert:
+    - id: snapshot-spill-locators
+      name: ../../../scripts/snapshot-spill-locators.ts
+      config:
+        root: !!js process.env.DSH_SNAPSHOT_SPILL_ROOT
+        locatorRoot: !!js process.env.DSH_SNAPSHOT_SPILL_LOCATOR_ROOT
diff --git a/snapshots/session/session-reference-spill/cordis.yml b/snapshots/session/session-reference-spill/cordis.yml
index 91bed4b866..51d0fc224b 100644
--- a/snapshots/session/session-reference-spill/cordis.yml
+++ b/snapshots/session/session-reference-spill/cordis.yml
@@ -11,3 +11,10 @@
         maxReferenceBytes: 360
     - id: reference-source-fixture
       name: ../../../packages/context/session-reference/tests/fixtures/source-session.ts
+
+- insert:
+    - id: snapshot-spill-locators
+      name: ../../../scripts/snapshot-spill-locators.ts
+      config:
+        root: !!js process.env.DSH_SNAPSHOT_SPILL_ROOT
+        locatorRoot: !!js process.env.DSH_SNAPSHOT_SPILL_LOCATOR_ROOT
diff --git a/snapshots/session/session-sandbox-root/cordis.yml b/snapshots/session/session-sandbox-root/cordis.yml
index 4de9db569e..a112279e06 100644
--- a/snapshots/session/session-sandbox-root/cordis.yml
+++ b/snapshots/session/session-sandbox-root/cordis.yml
@@ -1,5 +1,5 @@
 # Session-root sandbox snapshot overlay. The generated session cwd lives
-# under the user's home, while this deployment fallback deliberately points at
+# outside the automatic temp grants, while this deployment fallback points at
 # /tmp. A workspace-write mutation can therefore succeed only when the calling
 # session's cwd replaces the process-level fallback root.
 - id: sandbox-policy
diff --git a/snapshots/session/session-sandbox-root/snapshot.yml b/snapshots/session/session-sandbox-root/snapshot.yml
index f0c3fd48aa..da9bf201af 100644
--- a/snapshots/session/session-sandbox-root/snapshot.yml
+++ b/snapshots/session/session-sandbox-root/snapshot.yml
@@ -13,4 +13,4 @@ replay:
 permission: workspace-write
 workspace:
   final: true
-  parent: home
+  parent: outside-temp
diff --git a/snapshots/session/subagent-acp-diagnostic/cordis.snapshot.yml b/snapshots/session/subagent-acp-diagnostic/cordis.snapshot.yml
index 7af2ad3390..560d94e743 100644
--- a/snapshots/session/subagent-acp-diagnostic/cordis.snapshot.yml
+++ b/snapshots/session/subagent-acp-diagnostic/cordis.snapshot.yml
@@ -5,6 +5,8 @@
   disabled: true
 
 - insert:
+    - id: acp-diagnostic-release-on-job-output
+      name: './release-on-job-output.mjs'
     - id: llm-replay
       name: '@deepseek-ai/dsh-llm-replay'
       config:
@@ -25,6 +27,7 @@
         env:
           MOCK_PERMISSION: '1'
           MOCK_TOOL_KIND: execute
+          MOCK_PROMPT_HOLD: .dsh/acp-diagnostic-prompt-hold
     - id: tool-subagent-acp-diagnostic
       name: '@deepseek-ai/dsh-tool-subagent'
       config:
diff --git a/snapshots/session/subagent-acp-diagnostic/cordis.yml b/snapshots/session/subagent-acp-diagnostic/cordis.yml
index 197f8d4be7..f647366902 100644
--- a/snapshots/session/subagent-acp-diagnostic/cordis.yml
+++ b/snapshots/session/subagent-acp-diagnostic/cordis.yml
@@ -2,6 +2,8 @@
 # execute permission returns `cancelled` and exercises diagnostic-bearing
 # remote-abort parity.
 - insert:
+    - id: acp-diagnostic-release-on-job-output
+      name: './release-on-job-output.mjs'
     - id: subagent-acp-diagnostic
       name: '@deepseek-ai/dsh-subagent-acp'
       config:
@@ -13,6 +15,7 @@
         env:
           MOCK_PERMISSION: '1'
           MOCK_TOOL_KIND: execute
+          MOCK_PROMPT_HOLD: .dsh/acp-diagnostic-prompt-hold
     - id: tool-subagent-acp-diagnostic
       name: '@deepseek-ai/dsh-tool-subagent'
       config:
diff --git a/snapshots/session/subagent-acp-diagnostic/release-on-job-output.mjs b/snapshots/session/subagent-acp-diagnostic/release-on-job-output.mjs
new file mode 100644
index 0000000000..5704cf5625
--- /dev/null
+++ b/snapshots/session/subagent-acp-diagnostic/release-on-job-output.mjs
@@ -0,0 +1,31 @@
+/** Hold the scripted ACP background response until job_output owns its wait. */
+import { rmSync, writeFileSync } from 'node:fs'
+
+export const name = 'acp-diagnostic-release-on-job-output'
+export const inject = ['tools', 'jobs']
+
+const HOLD = '.dsh/acp-diagnostic-prompt-hold'
+
+/** Install the scenario-local response barrier without changing tool output. */
+export function apply(ctx) {
+  ctx.on('tools/execute', (exec, next) => {
+    if (exec.name === 'subagent_acp' && exec.arguments.run_in_background === true) {
+      writeFileSync(HOLD, '', { flag: 'wx' })
+    }
+    return next()
+  })
+  ctx.effect(() => {
+    const jobs = ctx.jobs
+    const wait = jobs.wait
+    jobs.wait = function (...args) {
+      // The registry registers its waiter synchronously, unlike the tool middleware.
+      const pending = wait.apply(this, args)
+      rmSync(HOLD)
+      return pending
+    }
+    return () => {
+      jobs.wait = wait
+      rmSync(HOLD, { force: true })
+    }
+  })
+}
diff --git a/snapshots/session/subagent-acp-diagnostic/replay.override.json b/snapshots/session/subagent-acp-diagnostic/replay.override.json
index 302125db53..c1abbc7283 100644
--- a/snapshots/session/subagent-acp-diagnostic/replay.override.json
+++ b/snapshots/session/subagent-acp-diagnostic/replay.override.json
@@ -15,16 +15,9 @@
       { "type": "block-start", "index": 0, "blockType": "tool-call" },
       { "type": "tool-call-delta", "index": 0, "id": "call_acp_background", "name": "subagent_acp", "argumentsDelta": "{\"description\":\"Observe ACP background failure\",\"prompt\":\"Return the scripted ACP failure.\",\"run_in_background\":true}" },
       { "type": "block-end", "index": 0, "block": { "type": "tool-call", "id": "call_acp_background", "name": "subagent_acp", "arguments": "{\"description\":\"Observe ACP background failure\",\"prompt\":\"Return the scripted ACP failure.\",\"run_in_background\":true}" } },
-      { "type": "usage", "usage": { "inputTokens": 10, "outputTokens": 5 } },
-      { "type": "finish", "reason": { "kind": "tool-calls" } }
-    ]
-  },
-  {
-    "kind": "chunks",
-    "chunks": [
-      { "type": "block-start", "index": 0, "blockType": "tool-call" },
-      { "type": "tool-call-delta", "index": 0, "id": "call_acp_output", "name": "job_output", "argumentsDelta": "{\"job_id\":\"subagent-1\",\"wait\":true}" },
-      { "type": "block-end", "index": 0, "block": { "type": "tool-call", "id": "call_acp_output", "name": "job_output", "arguments": "{\"job_id\":\"subagent-1\",\"wait\":true}" } },
+      { "type": "block-start", "index": 1, "blockType": "tool-call" },
+      { "type": "tool-call-delta", "index": 1, "id": "call_acp_output", "name": "job_output", "argumentsDelta": "{\"job_id\":\"subagent-1\",\"wait\":true}" },
+      { "type": "block-end", "index": 1, "block": { "type": "tool-call", "id": "call_acp_output", "name": "job_output", "arguments": "{\"job_id\":\"subagent-1\",\"wait\":true}" } },
       { "type": "usage", "usage": { "inputTokens": 10, "outputTokens": 5 } },
       { "type": "finish", "reason": { "kind": "tool-calls" } }
     ]
diff --git a/snapshots/session/subagent-acp-diagnostic/session.v2.jsonl b/snapshots/session/subagent-acp-diagnostic/session.v2.jsonl
index 11a350dd73..02e0ac900a 100644
--- a/snapshots/session/subagent-acp-diagnostic/session.v2.jsonl
+++ b/snapshots/session/subagent-acp-diagnostic/session.v2.jsonl
@@ -11,21 +11,18 @@
 {"type":"session/title","data":{"title":"Observe the ACP diagnostic twice","messageSeqs":[7],"source":{"kind":"fallback"}}}
 {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-pro"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
 {"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-pro"}}
-{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_acp_foreground","name":"subagent_acp","arguments":"{\"description\":\"Observe ACP foreground failure\",\"prompt\":\"Return the scripted ACP failure.\",\"run_in_background\":false}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-pro"},"id":"{{message:3}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":1788233522846,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788233522846,"index":0,"dt":[],"id":"call_acp_foreground","name":"subagent_acp","args":["{\"description\":\"Observe ACP foreground failure\",\"prompt\":\"Return the scripted ACP failure.\",\"run_in_background\":false}"]},{"type":"chunk","time":1788233522846,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_acp_foreground","name":"subagent_acp","arguments":"{\"description\":\"Observe ACP foreground failure\",\"prompt\":\"Return the scripted ACP failure.\",\"run_in_background\":false}"}}},{"type":"chunk","time":1788233522846,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":1788233522846,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
+{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_acp_foreground","name":"subagent_acp","arguments":"{\"description\":\"Observe ACP foreground failure\",\"prompt\":\"Return the scripted ACP failure.\",\"run_in_background\":false}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-pro"},"id":"{{message:3}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":1788754752687,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788754752687,"index":0,"dt":[],"id":"call_acp_foreground","name":"subagent_acp","args":["{\"description\":\"Observe ACP foreground failure\",\"prompt\":\"Return the scripted ACP failure.\",\"run_in_background\":false}"]},{"type":"chunk","time":1788754752687,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_acp_foreground","name":"subagent_acp","arguments":"{\"description\":\"Observe ACP foreground failure\",\"prompt\":\"Return the scripted ACP failure.\",\"run_in_background\":false}"}}},{"type":"chunk","time":1788754752687,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":1788754752687,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
 {"type":"tool/call","data":{"turn":1,"step":1,"callId":"call_acp_foreground","name":"subagent_acp","arguments":"{\"description\":\"Observe ACP foreground failure\",\"prompt\":\"Return the scripted ACP failure.\",\"run_in_background\":false}"}}
 {"type":"tool/result","data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_acp_foreground"},"content":[{"type":"tool-result","toolCallId":"call_acp_foreground","content":[{"type":"text","text":"Error: subagent run was cancelled\nDiagnostic: ACP unattended decision (policy: reject; request: execute; decision: denied)"}],"isError":true}],"role":"user","id":"{{message:4}}"}},"sourceEventSeqs":[13],"surfaceOp":"append"}
 {"type":"step/end","data":{"turn":1,"step":1}}
 {"type":"step/start","data":{"turn":1,"step":2}}
-{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_acp_background","name":"subagent_acp","arguments":"{\"description\":\"Observe ACP background failure\",\"prompt\":\"Return the scripted ACP failure.\",\"run_in_background\":true}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-pro"},"id":"{{message:5}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":1788233523007,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788233523007,"index":0,"dt":[],"id":"call_acp_background","name":"subagent_acp","args":["{\"description\":\"Observe ACP background failure\",\"prompt\":\"Return the scripted ACP failure.\",\"run_in_background\":true}"]},{"type":"chunk","time":1788233523007,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_acp_background","name":"subagent_acp","arguments":"{\"description\":\"Observe ACP background failure\",\"prompt\":\"Return the scripted ACP failure.\",\"run_in_background\":true}"}}},{"type":"chunk","time":1788233523007,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":1788233523007,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
+{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_acp_background","name":"subagent_acp","arguments":"{\"description\":\"Observe ACP background failure\",\"prompt\":\"Return the scripted ACP failure.\",\"run_in_background\":true}"},{"type":"tool-call","id":"call_acp_output","name":"job_output","arguments":"{\"job_id\":\"subagent-1\",\"wait\":true}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-pro"},"id":"{{message:5}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":1788754752804,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788754752804,"index":0,"dt":[],"id":"call_acp_background","name":"subagent_acp","args":["{\"description\":\"Observe ACP background failure\",\"prompt\":\"Return the scripted ACP failure.\",\"run_in_background\":true}"]},{"type":"chunk","time":1788754752804,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_acp_background","name":"subagent_acp","arguments":"{\"description\":\"Observe ACP background failure\",\"prompt\":\"Return the scripted ACP failure.\",\"run_in_background\":true}"}}},{"type":"chunk","time":1788754752804,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788754752804,"index":1,"dt":[],"id":"call_acp_output","name":"job_output","args":["{\"job_id\":\"subagent-1\",\"wait\":true}"]},{"type":"chunk","time":1788754752804,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_acp_output","name":"job_output","arguments":"{\"job_id\":\"subagent-1\",\"wait\":true}"}}},{"type":"chunk","time":1788754752804,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":1788754752804,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
 {"type":"tool/call","data":{"turn":1,"step":2,"callId":"call_acp_background","name":"subagent_acp","arguments":"{\"description\":\"Observe ACP background failure\",\"prompt\":\"Return the scripted ACP failure.\",\"run_in_background\":true}"}}
 {"type":"tool/result","data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"call_acp_background"},"content":[{"type":"tool-result","toolCallId":"call_acp_background","content":[{"type":"text","text":"started background subagent job subagent-1"}],"isError":false}],"role":"user","id":"{{message:6}}"}},"sourceEventSeqs":[18],"surfaceOp":"append"}
+{"type":"tool/call","data":{"turn":1,"step":2,"callId":"call_acp_output","name":"job_output","arguments":"{\"job_id\":\"subagent-1\",\"wait\":true}"}}
+{"type":"tool/result","data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"call_acp_output"},"content":[{"type":"tool-result","toolCallId":"call_acp_output","content":[{"type":"text","text":"(no new output)\n[status: failed, aborted; diagnostic: ACP unattended decision (policy: reject; request: execute; decision: denied)]"}],"isError":false}],"role":"user","id":"{{message:7}}"}},"sourceEventSeqs":[20],"surfaceOp":"append"}
 {"type":"step/end","data":{"turn":1,"step":2}}
 {"type":"step/start","data":{"turn":1,"step":3}}
-{"type":"assistant/message","data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_acp_output","name":"job_output","arguments":"{\"job_id\":\"subagent-1\",\"wait\":true}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-pro"},"id":"{{message:7}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":1788233523025,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788233523025,"index":0,"dt":[],"id":"call_acp_output","name":"job_output","args":["{\"job_id\":\"subagent-1\",\"wait\":true}"]},{"type":"chunk","time":1788233523025,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_acp_output","name":"job_output","arguments":"{\"job_id\":\"subagent-1\",\"wait\":true}"}}},{"type":"chunk","time":1788233523025,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":1788233523025,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
-{"type":"tool/call","data":{"turn":1,"step":3,"callId":"call_acp_output","name":"job_output","arguments":"{\"job_id\":\"subagent-1\",\"wait\":true}"}}
-{"type":"tool/result","data":{"turn":1,"step":3,"message":{"source":{"kind":"tool","callId":"call_acp_output"},"content":[{"type":"tool-result","toolCallId":"call_acp_output","content":[{"type":"text","text":"(no new output)\n[status: failed, aborted; diagnostic: ACP unattended decision (policy: reject; request: execute; decision: denied)]"}],"isError":false}],"role":"user","id":"{{message:8}}"}},"sourceEventSeqs":[23],"surfaceOp":"append"}
+{"type":"assistant/message","data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"text","text":"PARENT_OBSERVED_ACP_DIAGNOSTIC"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-pro"},"id":"{{message:8}}"},"usage":{"inputTokens":10,"outputTokens":2},"stream":[{"type":"chunk","time":1788754752915,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":1788754752916,"index":0,"dt":[],"texts":["PARENT_OBSERVED_ACP_DIAGNOSTIC"]},{"type":"chunk","time":1788754752916,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"PARENT_OBSERVED_ACP_DIAGNOSTIC"}}},{"type":"chunk","time":1788754752916,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":2}}},{"type":"chunk","time":1788754752916,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
 {"type":"step/end","data":{"turn":1,"step":3}}
-{"type":"step/start","data":{"turn":1,"step":4}}
-{"type":"assistant/message","data":{"turn":1,"step":4,"message":{"role":"assistant","content":[{"type":"text","text":"PARENT_OBSERVED_ACP_DIAGNOSTIC"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-pro"},"id":"{{message:9}}"},"usage":{"inputTokens":10,"outputTokens":2},"stream":[{"type":"chunk","time":1788233523164,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":1788233523164,"index":0,"dt":[],"texts":["PARENT_OBSERVED_ACP_DIAGNOSTIC"]},{"type":"chunk","time":1788233523164,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"PARENT_OBSERVED_ACP_DIAGNOSTIC"}}},{"type":"chunk","time":1788233523164,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":2}}},{"type":"chunk","time":1788233523165,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
-{"type":"step/end","data":{"turn":1,"step":4}}
 {"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/snapshots/web/approval-composer/session.v2.jsonl b/snapshots/web/approval-composer/session.v2.jsonl
index 3de94bf22b..6665815599 100644
--- a/snapshots/web/approval-composer/session.v2.jsonl
+++ b/snapshots/web/approval-composer/session.v2.jsonl
@@ -6,11 +6,11 @@
 {"type":"permission/preset","data":{"preset":"read-only"}}
 {"type":"sandbox/mode","data":{"mode":"read-only"}}
 {"type":"command/done","data":{"commandId":"{{command:1}}","kind":"success","text":"preset read-only"}}
-{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Write a file named notes.txt in the workspace containing exactly this text on one line: tok63z tokc7y tokibx tokofw tokujv tok10nu tok16rt tok1cvs tok1izr tok1p3q tok1v7p tok21bo tok2a4 tok8e3 tokei2 tokkm1 tokqq0 tokwtz tok12xy tok191x tok1f5w tok1l9v tok1rdu tok1xht tok23ls tok4k8 tokao7 tokgs6 tokmw5 tokt04 tokz43 tok1582 tok1bc1 tok1hg0 tok1njz tok1tny tok1zrx tokqd tok6uc tokcyb tokj2a tokp69 tokva8 tok11e7 tok17i6 tok1dm5 tok1jq4 tok1pu3 tok1vy2 tok2221 tok30h tok94g tokf8f toklce tokrgd tokxkc tok13ob tok19sa tok1fw9 tok1m08 tok1s47 tok1y86 tok24c5 tok5al tokbek tokhij toknmi toktqh tokzug tok15yf tok1c2e tok1i6d tok1oac tok1ueb tok20ia tok1gq tok7kp tokdoo tokjsn tokpwm tokw0l tok124k tok188j tok1eci tok1kgh tok1qkg tok1wof tok22se tok3qu tok9ut tokfys tokm2r toks6q tokyap tok14eo tok1ain tok1gmm tok1mql tok1suk tok1yyj tok252i tok60y tokc4x toki8w tokocv tokugu tok10kt tok16os tok1csr tok1iwq tok1p0p tok1v4o tok218n tok273 tok8b2 tokef1 tokkj0 tokqmz tokwqy tok12ux tok18yw tok1f2v tok1l6u tok1rat tok1xes tok23ir tok4h7 tokal6 tokgp5 tokmt4 toksx3 tokz12 tok1551 tok1b90 tok1hcz tok1ngy tok1tkx tok1zow toknc tok6rb tokcva tokiz9 tokp38 tokv77 tok11b6 tok17f5 tok1dj4 tok1jn3 tok1pr2 tok1vv1 tok21z0 tok2xg tok91f tokf5e tokl9d tokrdc tokxhb tok13la tok19p9 tok1ft8 tok1lx7 tok1s16 tok1y55 tok2494 tok57k tokbbj tokhfi toknjh toktng tokzrf tok15ve tok1bzd tok1i3c tok1o7b tok1uba tok20f9 tok1dp tok7ho tokdln tokjpm tokptl tokvxk tok121j tok185i tok1e9h tok1kdg tok1qhf tok1wle tok22pd tok3nt tok9rs tokfvr toklzq toks3p toky7o tok14bn tok1afm tok1gjl tok1mnk tok1srj tok1yvi tok24zh tok5xx tokc1w toki5v toko9u tokudt tok10hs tok16lr tok1cpq tok1itp tok1oxo tok1v1n tok215m tok242 tok881 tokec0 tokkfz tokqjy tokwnx. Use one bash command with the literal text inline. Then reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Write a file named notes.txt in the workspace containing exactly this text on one line: tok63z tokc7y tokibx tokofw tokujv tok10nu tok16rt tok1cvs tok1izr tok1p3q tok1v7p tok21bo tok2a4 tok8e3 tokei2 tokkm1 tokqq0 tokwtz tok12xy tok191x tok1f5w tok1l9v tok1rdu tok1xht tok23ls tok4k8 tokao7 tokgs6 tokmw5 tokt04 tokz43 tok1582 tok1bc1 tok1hg0 tok1njz tok1tny tok1zrx tokqd tok6uc tokcyb tokj2a tokp69 tokva8 tok11e7 tok17i6 tok1dm5 tok1jq4 tok1pu3 tok1vy2 tok2221 tok30h tok94g tokf8f toklce tokrgd tokxkc tok13ob tok19sa tok1fw9 tok1m08 tok1s47 tok1y86 tok24c5 tok5al tokbek tokhij toknmi toktqh tokzug tok15yf tok1c2e tok1i6d tok1oac tok1ueb tok20ia tok1gq tok7kp tokdoo tokjsn tokpwm tokw0l tok124k tok188j tok1eci tok1kgh tok1qkg tok1wof tok22se tok3qu tok9ut tokfys tokm2r toks6q tokyap tok14eo tok1ain tok1gmm tok1mql tok1suk tok1yyj tok252i tok60y tokc4x toki8w tokocv tokugu tok10kt tok16os tok1csr tok1iwq tok1p0p tok1v4o tok218n tok273 tok8b2 tokef1 tokkj0 tokqmz tokwqy tok12ux tok18yw tok1f2v tok1l6u tok1rat tok1xes tok23ir tok4h7 tokal6 tokgp5 tokmt4 toksx3 tokz12 tok1551 tok1b90 tok1hcz tok1ngy tok1tkx tok1zow toknc tok6rb tokcva tokiz9 tokp38 tokv77 tok11b6 tok17f5 tok1dj4 tok1jn3 tok1pr2 tok1vv1 tok21z0 tok2xg tok91f tokf5e tokl9d tokrdc tokxhb tok13la tok19p9 tok1ft8 tok1lx7 tok1s16 tok1y55 tok2494 tok57k tokbbj tokhfi toknjh toktng tokzrf tok15ve tok1bzd tok1i3c tok1o7b tok1uba tok20f9 tok1dp tok7ho tokdln tokjpm tokptl tokvxk tok121j tok185i tok1e9h tok1kdg tok1qhf tok1wle tok22pd tok3nt tok9rs tokfvr toklzq toks3p toky7o tok14bn tok1afm tok1gjl tok1mnk tok1srj tok1yvi tok24zh tok5xx tokc1w toki5v toko9u tokudt tok10hs tok16lr tok1cpq tok1itp tok1oxo tok1v1n tok215m tok242 tok881 tokec0 tokkfz tokqjy tokwnx. Use one bash command with the literal text inline. Then reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"}]}}
 {"type":"turn/start","data":{"turn":1}}
 {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","data":{"turn":1,"step":1}}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Write a file named notes.txt in the workspace containing exactly this text on one line: tok63z tokc7y tokibx tokofw tokujv tok10nu tok16rt tok1cvs tok1izr tok1p3q tok1v7p tok21bo tok2a4 tok8e3 tokei2 tokkm1 tokqq0 tokwtz tok12xy tok191x tok1f5w tok1l9v tok1rdu tok1xht tok23ls tok4k8 tokao7 tokgs6 tokmw5 tokt04 tokz43 tok1582 tok1bc1 tok1hg0 tok1njz tok1tny tok1zrx tokqd tok6uc tokcyb tokj2a tokp69 tokva8 tok11e7 tok17i6 tok1dm5 tok1jq4 tok1pu3 tok1vy2 tok2221 tok30h tok94g tokf8f toklce tokrgd tokxkc tok13ob tok19sa tok1fw9 tok1m08 tok1s47 tok1y86 tok24c5 tok5al tokbek tokhij toknmi toktqh tokzug tok15yf tok1c2e tok1i6d tok1oac tok1ueb tok20ia tok1gq tok7kp tokdoo tokjsn tokpwm tokw0l tok124k tok188j tok1eci tok1kgh tok1qkg tok1wof tok22se tok3qu tok9ut tokfys tokm2r toks6q tokyap tok14eo tok1ain tok1gmm tok1mql tok1suk tok1yyj tok252i tok60y tokc4x toki8w tokocv tokugu tok10kt tok16os tok1csr tok1iwq tok1p0p tok1v4o tok218n tok273 tok8b2 tokef1 tokkj0 tokqmz tokwqy tok12ux tok18yw tok1f2v tok1l6u tok1rat tok1xes tok23ir tok4h7 tokal6 tokgp5 tokmt4 toksx3 tokz12 tok1551 tok1b90 tok1hcz tok1ngy tok1tkx tok1zow toknc tok6rb tokcva tokiz9 tokp38 tokv77 tok11b6 tok17f5 tok1dj4 tok1jn3 tok1pr2 tok1vv1 tok21z0 tok2xg tok91f tokf5e tokl9d tokrdc tokxhb tok13la tok19p9 tok1ft8 tok1lx7 tok1s16 tok1y55 tok2494 tok57k tokbbj tokhfi toknjh toktng tokzrf tok15ve tok1bzd tok1i3c tok1o7b tok1uba tok20f9 tok1dp tok7ho tokdln tokjpm tokptl tokvxk tok121j tok185i tok1e9h tok1kdg tok1qhf tok1wle tok22pd tok3nt tok9rs tokfvr toklzq toks3p toky7o tok14bn tok1afm tok1gjl tok1mnk tok1srj tok1yvi tok24zh tok5xx tokc1w toki5v toko9u tokudt tok10hs tok16lr tok1cpq tok1itp tok1oxo tok1v1n tok215m tok242 tok881 tokec0 tokkfz tokqjy tokwnx. Use one bash command with the literal text inline. Then reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Write a file named notes.txt in the workspace containing exactly this text on one line: tok63z tokc7y tokibx tokofw tokujv tok10nu tok16rt tok1cvs tok1izr tok1p3q tok1v7p tok21bo tok2a4 tok8e3 tokei2 tokkm1 tokqq0 tokwtz tok12xy tok191x tok1f5w tok1l9v tok1rdu tok1xht tok23ls tok4k8 tokao7 tokgs6 tokmw5 tokt04 tokz43 tok1582 tok1bc1 tok1hg0 tok1njz tok1tny tok1zrx tokqd tok6uc tokcyb tokj2a tokp69 tokva8 tok11e7 tok17i6 tok1dm5 tok1jq4 tok1pu3 tok1vy2 tok2221 tok30h tok94g tokf8f toklce tokrgd tokxkc tok13ob tok19sa tok1fw9 tok1m08 tok1s47 tok1y86 tok24c5 tok5al tokbek tokhij toknmi toktqh tokzug tok15yf tok1c2e tok1i6d tok1oac tok1ueb tok20ia tok1gq tok7kp tokdoo tokjsn tokpwm tokw0l tok124k tok188j tok1eci tok1kgh tok1qkg tok1wof tok22se tok3qu tok9ut tokfys tokm2r toks6q tokyap tok14eo tok1ain tok1gmm tok1mql tok1suk tok1yyj tok252i tok60y tokc4x toki8w tokocv tokugu tok10kt tok16os tok1csr tok1iwq tok1p0p tok1v4o tok218n tok273 tok8b2 tokef1 tokkj0 tokqmz tokwqy tok12ux tok18yw tok1f2v tok1l6u tok1rat tok1xes tok23ir tok4h7 tokal6 tokgp5 tokmt4 toksx3 tokz12 tok1551 tok1b90 tok1hcz tok1ngy tok1tkx tok1zow toknc tok6rb tokcva tokiz9 tokp38 tokv77 tok11b6 tok17f5 tok1dj4 tok1jn3 tok1pr2 tok1vv1 tok21z0 tok2xg tok91f tokf5e tokl9d tokrdc tokxhb tok13la tok19p9 tok1ft8 tok1lx7 tok1s16 tok1y55 tok2494 tok57k tokbbj tokhfi toknjh toktng tokzrf tok15ve tok1bzd tok1i3c tok1o7b tok1uba tok20f9 tok1dp tok7ho tokdln tokjpm tokptl tokvxk tok121j tok185i tok1e9h tok1kdg tok1qhf tok1wle tok22pd tok3nt tok9rs tokfvr toklzq toks3p toky7o tok14bn tok1afm tok1gjl tok1mnk tok1srj tok1yvi tok24zh tok5xx tokc1w toki5v toko9u tokudt tok10hs tok16lr tok1cpq tok1itp tok1oxo tok1v1n tok215m tok242 tok881 tokec0 tokkfz tokqjy tokwnx. Use one bash command with the literal text inline. Then reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
 {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: read-only. Any available operation enforced by the DSH file sandbox cannot modify files in the standing mode. Do not refuse a required modification from this policy alone: try an available tool normally and follow any denial and escalation guidance it returns.\n\nApproval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: read-only. Any available operation enforced by the DSH file sandbox cannot modify files in the standing mode. Do not refuse a required modification from this policy alone: try an available tool normally and follow any denial and escalation guidance it returns."},{"name":"approval:policy","text":"Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}]},"role":"user","id":"{{message:2}}"},"surfaceOp":"append"}
 {"type":"session/title","data":{"title":"Write a file named notes.txt","messageSeqs":[11],"source":{"kind":"fallback"}}}
 {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
diff --git a/snapshots/web/bash-abort-row/ui.expected.md b/snapshots/web/bash-abort-row/ui.expected.md
index fb3437d266..4af682fdb2 100644
--- a/snapshots/web/bash-abort-row/ui.expected.md
+++ b/snapshots/web/bash-abort-row/ui.expected.md
@@ -4,6 +4,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -26,7 +28,7 @@
 - 'button "Failed Bash Error: tool call aborted before dispatch"':
   - img
   - text: "Failed Bash Error: tool call aborted before dispatch"
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -36,4 +38,9 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 0% Input 10 tok · Output 10 tok
+- button "1 turns 1 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 1 steps{{throughput}} tok/s
+- button "20 tok · Cache hit 0%":
+  - img
+  - text: 20 tokCache hit 0%
diff --git a/snapshots/web/cordis-tool-round/session.v2.jsonl b/snapshots/web/cordis-tool-round/session.v2.jsonl
index 9ab9e7f787..33c4875ded 100644
--- a/snapshots/web/cordis-tool-round/session.v2.jsonl
+++ b/snapshots/web/cordis-tool-round/session.v2.jsonl
@@ -2,11 +2,11 @@
 {"type":"permission/preset","data":{"preset":"workspace-write"}}
 {"type":"sandbox/mode","data":{"mode":"workspace-write"}}
 {"type":"approval/policy","data":{"policy":"ask"}}
-{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use only Cordis tools. First call cordis_inspect_self with no arguments. Then call cordis_define with plugin kind \"new\", idPrefix \"snap\", name \"snapshot noop\", purpose \"does nothing, for the snapshot\", code.host exactly \"return { name: \\\"snapshot-noop\\\", apply(ctx) {} }\" and code.client exactly \"return { inject: [\\\"slots\\\"], apply(ctx) { ctx.slots.register({ name: \\\"shell.overlay\\\", id: \\\"snapshot-probe\\\" }, () => React.createElement(\\\"div\\\", { \\\"data-snapshot-probe\\\": \\\"loaded\\\" })) } }\". Read its returned pluginId and packageId, then call cordis_run with those exact IDs and mode \"run\". After the run request returns, reply exactly CORDIS_UI_READY and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use only Cordis tools. First call cordis_inspect_self with no arguments. Then call cordis_define with plugin kind \"new\", idPrefix \"snap\", name \"snapshot noop\", purpose \"does nothing, for the snapshot\", code.host exactly \"return { name: \\\"snapshot-noop\\\", apply(ctx) {} }\" and code.client exactly \"return { inject: [\\\"slots\\\"], apply(ctx) { ctx.slots.register({ name: \\\"shell.overlay\\\", id: \\\"snapshot-probe\\\" }, () => React.createElement(\\\"div\\\", { \\\"data-snapshot-probe\\\": \\\"loaded\\\" })) } }\". Read its returned pluginId and packageId, then call cordis_run with those exact IDs and mode \"run\". After the run request returns, reply exactly CORDIS_UI_READY and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"}]}}
 {"type":"turn/start","data":{"turn":1}}
 {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","data":{"turn":1,"step":1}}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Use only Cordis tools. First call cordis_inspect_self with no arguments. Then call cordis_define with plugin kind \"new\", idPrefix \"snap\", name \"snapshot noop\", purpose \"does nothing, for the snapshot\", code.host exactly \"return { name: \\\"snapshot-noop\\\", apply(ctx) {} }\" and code.client exactly \"return { inject: [\\\"slots\\\"], apply(ctx) { ctx.slots.register({ name: \\\"shell.overlay\\\", id: \\\"snapshot-probe\\\" }, () => React.createElement(\\\"div\\\", { \\\"data-snapshot-probe\\\": \\\"loaded\\\" })) } }\". Read its returned pluginId and packageId, then call cordis_run with those exact IDs and mode \"run\". After the run request returns, reply exactly CORDIS_UI_READY and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Use only Cordis tools. First call cordis_inspect_self with no arguments. Then call cordis_define with plugin kind \"new\", idPrefix \"snap\", name \"snapshot noop\", purpose \"does nothing, for the snapshot\", code.host exactly \"return { name: \\\"snapshot-noop\\\", apply(ctx) {} }\" and code.client exactly \"return { inject: [\\\"slots\\\"], apply(ctx) { ctx.slots.register({ name: \\\"shell.overlay\\\", id: \\\"snapshot-probe\\\" }, () => React.createElement(\\\"div\\\", { \\\"data-snapshot-probe\\\": \\\"loaded\\\" })) } }\". Read its returned pluginId and packageId, then call cordis_run with those exact IDs and mode \"run\". After the run request returns, reply exactly CORDIS_UI_READY and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
 {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable.\n\nApproval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable."},{"name":"approval:policy","text":"Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}]},"role":"user","id":"{{message:2}}"},"surfaceOp":"append"}
 {"type":"session/title","data":{"title":"Use only Cordis tools. First","messageSeqs":[7],"source":{"kind":"fallback"}}}
 {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
@@ -37,11 +37,11 @@
 {"type":"assistant/message","data":{"turn":2,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"The Cordis Plugin is running."}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:11}}"},"usage":{"inputTokens":3,"outputTokens":3},"stream":[{"type":"chunk","time":1788240680404,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"chunk","time":1788240680420,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"The Cordis Plugin is running."}}},{"type":"chunk","time":1788240680437,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}},{"type":"chunk","time":1788240680454,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
 {"type":"step/end","data":{"turn":2,"step":1}}
 {"type":"turn/end","data":{"turn":2,"reason":{"kind":"completed"}}}
-{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use only Cordis tools. Call cordis_stop with pluginId \"snap-1\". After it succeeds, reply exactly CORDIS_UI_DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:2}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:12}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use only Cordis tools. Call cordis_stop with pluginId \"snap-1\". After it succeeds, reply exactly CORDIS_UI_DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:2}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:12}}"}]}}
 {"type":"turn/start","data":{"turn":3}}
 {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","data":{"turn":3,"step":1}}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Use only Cordis tools. Call cordis_stop with pluginId \"snap-1\". After it succeeds, reply exactly CORDIS_UI_DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:2}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:12}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Use only Cordis tools. Call cordis_stop with pluginId \"snap-1\". After it succeeds, reply exactly CORDIS_UI_DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:2}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:12}}"},"surfaceOp":"append"}
 {"type":"assistant/message","data":{"turn":3,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"cordis-stop","name":"cordis_stop","arguments":"{\"pluginId\":\"snap-1\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:13}}"},"usage":{"inputTokens":3,"outputTokens":3},"stream":[{"type":"chunk","time":1788240680509,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"chunk","time":1788240680526,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"cordis-stop","name":"cordis_stop","arguments":"{\"pluginId\":\"snap-1\"}"}}},{"type":"chunk","time":1788240680543,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}},{"type":"chunk","time":1788240680558,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
 {"type":"tool/call","data":{"turn":3,"step":1,"callId":"cordis-stop","name":"cordis_stop","arguments":"{\"pluginId\":\"snap-1\"}"}}
 {"type":"tool/result","data":{"turn":3,"step":1,"message":{"source":{"kind":"tool","callId":"cordis-stop"},"content":[{"type":"tool-result","toolCallId":"cordis-stop","content":[{"type":"text","text":"Dynamic Plugin snap-1 is stopped; its definition and versions remain."}],"isError":false}],"role":"user","id":"{{message:14}}"}},"sourceEventSeqs":[44],"surfaceOp":"append"}
diff --git a/snapshots/web/cordis-tool-round/ui.expected.md b/snapshots/web/cordis-tool-round/ui.expected.md
index 07b054429a..aa741273ff 100644
--- a/snapshots/web/cordis-tool-round/ui.expected.md
+++ b/snapshots/web/cordis-tool-round/ui.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -114,7 +116,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -125,4 +127,9 @@
   - img
 - button "0% of context used"
 - button "Send message" [disabled]
-- text: 3 turns · 7 steps LLM {{duration}} · Tool call {{duration}} Cache hit 77% Input 66.5K tok · Output 321 tok
+- button "3 turns 7 steps":
+  - img
+  - text: 3 turns 7 steps
+- button "66.8K tok · Cache hit 77%":
+  - img
+  - text: 66.8K tokCache hit 77%
diff --git a/snapshots/web/details-session-lifecycle/sidebar.expected.md b/snapshots/web/details-session-lifecycle/sidebar.expected.md
new file mode 100644
index 0000000000..318b30c209
--- /dev/null
+++ b/snapshots/web/details-session-lifecycle/sidebar.expected.md
@@ -0,0 +1,507 @@
+# Recorded-session Sidebar states
+
+## A normal: two panes
+
+```json
+{
+  "viewport": [
+    1680,
+    1000
+  ],
+  "columns": [
+    280,
+    644,
+    756
+  ],
+  "columnTransition": "grid-template-columns",
+  "expanded": true,
+  "mode": "push",
+  "panelContentWidth": 756,
+  "panelOuterWidth": 757,
+  "coversViewport": false,
+  "resizeHandleWidth": 8,
+  "expandedDirectories": [],
+  "panes": [
+    {
+      "active": true,
+      "tabs": [
+        {
+          "title": "Files",
+          "selected": true
+        },
+        {
+          "title": "Start",
+          "selected": false
+        }
+      ]
+    },
+    {
+      "active": false,
+      "tabs": [
+        {
+          "title": "Start",
+          "selected": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+## A manual fullscreen: underlying columns retained
+
+```json
+{
+  "viewport": [
+    1680,
+    1000
+  ],
+  "columns": [
+    280,
+    644,
+    756
+  ],
+  "columnTransition": "none",
+  "expanded": true,
+  "mode": "fullscreen",
+  "panelContentWidth": 1680,
+  "panelOuterWidth": 1680,
+  "coversViewport": true,
+  "resizeHandleWidth": 0,
+  "expandedDirectories": [],
+  "panes": [
+    {
+      "active": true,
+      "tabs": [
+        {
+          "title": "Files",
+          "selected": true
+        },
+        {
+          "title": "Start",
+          "selected": false
+        }
+      ]
+    },
+    {
+      "active": false,
+      "tabs": [
+        {
+          "title": "Start",
+          "selected": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+## A closed with manual fullscreen retained
+
+```json
+{
+  "viewport": [
+    1680,
+    1000
+  ],
+  "columns": [
+    280,
+    1400,
+    0
+  ],
+  "columnTransition": "none",
+  "expanded": false,
+  "mode": "fullscreen",
+  "panelContentWidth": 0,
+  "panelOuterWidth": 0,
+  "coversViewport": false,
+  "resizeHandleWidth": 0,
+  "expandedDirectories": [],
+  "panes": [
+    {
+      "active": true,
+      "tabs": [
+        {
+          "title": "Files",
+          "selected": true
+        },
+        {
+          "title": "Start",
+          "selected": false
+        }
+      ]
+    },
+    {
+      "active": false,
+      "tabs": [
+        {
+          "title": "Start",
+          "selected": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+## B closed: independent pane and expanded workspace directory
+
+```json
+{
+  "viewport": [
+    1680,
+    1000
+  ],
+  "columns": [
+    280,
+    1400,
+    0
+  ],
+  "columnTransition": "grid-template-columns",
+  "expanded": false,
+  "mode": "push",
+  "panelContentWidth": 0,
+  "panelOuterWidth": 0,
+  "coversViewport": false,
+  "resizeHandleWidth": 0,
+  "expandedDirectories": [
+    "workspace"
+  ],
+  "panes": [
+    {
+      "active": true,
+      "tabs": [
+        {
+          "title": "Files",
+          "selected": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+## A restored: manual fullscreen, tabs, and panes
+
+```json
+{
+  "viewport": [
+    1680,
+    1000
+  ],
+  "columns": [
+    280,
+    644,
+    756
+  ],
+  "columnTransition": "none",
+  "expanded": true,
+  "mode": "fullscreen",
+  "panelContentWidth": 1680,
+  "panelOuterWidth": 1680,
+  "coversViewport": true,
+  "resizeHandleWidth": 0,
+  "expandedDirectories": [],
+  "panes": [
+    {
+      "active": true,
+      "tabs": [
+        {
+          "title": "Files",
+          "selected": true
+        },
+        {
+          "title": "Start",
+          "selected": false
+        }
+      ]
+    },
+    {
+      "active": false,
+      "tabs": [
+        {
+          "title": "Start",
+          "selected": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+## B restored: normal mode and Files directory state
+
+```json
+{
+  "viewport": [
+    1680,
+    1000
+  ],
+  "columns": [
+    280,
+    644,
+    756
+  ],
+  "columnTransition": "grid-template-columns",
+  "expanded": true,
+  "mode": "push",
+  "panelContentWidth": 756,
+  "panelOuterWidth": 757,
+  "coversViewport": false,
+  "resizeHandleWidth": 8,
+  "expandedDirectories": [
+    "workspace"
+  ],
+  "panes": [
+    {
+      "active": true,
+      "tabs": [
+        {
+          "title": "Files",
+          "selected": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+## A restored: expanded normal panel
+
+```json
+{
+  "viewport": [
+    1680,
+    1000
+  ],
+  "columns": [
+    280,
+    644,
+    756
+  ],
+  "columnTransition": "grid-template-columns",
+  "expanded": true,
+  "mode": "push",
+  "panelContentWidth": 756,
+  "panelOuterWidth": 757,
+  "coversViewport": false,
+  "resizeHandleWidth": 8,
+  "expandedDirectories": [],
+  "panes": [
+    {
+      "active": true,
+      "tabs": [
+        {
+          "title": "Files",
+          "selected": true
+        },
+        {
+          "title": "Start",
+          "selected": false
+        }
+      ]
+    },
+    {
+      "active": false,
+      "tabs": [
+        {
+          "title": "Start",
+          "selected": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+## A capacity-closed: wide left preference protected
+
+```json
+{
+  "viewport": [
+    1024,
+    1000
+  ],
+  "columns": [
+    420,
+    604,
+    0
+  ],
+  "columnTransition": "grid-template-columns",
+  "expanded": false,
+  "mode": "push",
+  "panelContentWidth": 0,
+  "panelOuterWidth": 0,
+  "coversViewport": false,
+  "resizeHandleWidth": 0,
+  "expandedDirectories": [],
+  "panes": [
+    {
+      "active": true,
+      "tabs": [
+        {
+          "title": "Files",
+          "selected": true
+        },
+        {
+          "title": "Start",
+          "selected": false
+        }
+      ]
+    },
+    {
+      "active": false,
+      "tabs": [
+        {
+          "title": "Start",
+          "selected": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+## A widened: remains closed
+
+```json
+{
+  "viewport": [
+    1680,
+    1000
+  ],
+  "columns": [
+    420,
+    1260,
+    0
+  ],
+  "columnTransition": "grid-template-columns",
+  "expanded": false,
+  "mode": "push",
+  "panelContentWidth": 0,
+  "panelOuterWidth": 0,
+  "coversViewport": false,
+  "resizeHandleWidth": 0,
+  "expandedDirectories": [],
+  "panes": [
+    {
+      "active": true,
+      "tabs": [
+        {
+          "title": "Files",
+          "selected": true
+        },
+        {
+          "title": "Start",
+          "selected": false
+        }
+      ]
+    },
+    {
+      "active": false,
+      "tabs": [
+        {
+          "title": "Start",
+          "selected": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+## A automatic fullscreen at 767px
+
+```json
+{
+  "viewport": [
+    767,
+    1000
+  ],
+  "columns": [
+    56,
+    711,
+    0
+  ],
+  "columnTransition": "none",
+  "expanded": true,
+  "mode": "fullscreen",
+  "panelContentWidth": 767,
+  "panelOuterWidth": 767,
+  "coversViewport": true,
+  "resizeHandleWidth": 0,
+  "expandedDirectories": [],
+  "panes": [
+    {
+      "active": true,
+      "tabs": [
+        {
+          "title": "Files",
+          "selected": true
+        },
+        {
+          "title": "Start",
+          "selected": false
+        }
+      ]
+    },
+    {
+      "active": false,
+      "tabs": [
+        {
+          "title": "Start",
+          "selected": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+## A automatic fullscreen exited: widening does not reopen
+
+```json
+{
+  "viewport": [
+    1680,
+    1000
+  ],
+  "columns": [
+    420,
+    1260,
+    0
+  ],
+  "columnTransition": "grid-template-columns",
+  "expanded": false,
+  "mode": "push",
+  "panelContentWidth": 0,
+  "panelOuterWidth": 0,
+  "coversViewport": false,
+  "resizeHandleWidth": 0,
+  "expandedDirectories": [],
+  "panes": [
+    {
+      "active": true,
+      "tabs": [
+        {
+          "title": "Files",
+          "selected": true
+        },
+        {
+          "title": "Start",
+          "selected": false
+        }
+      ]
+    },
+    {
+      "active": false,
+      "tabs": [
+        {
+          "title": "Start",
+          "selected": true
+        }
+      ]
+    }
+  ]
+}
+```
diff --git a/snapshots/web/feedback-command/ack-expanded.expected.md b/snapshots/web/feedback-command/ack-expanded.expected.md
index 4d6f0f24c0..6939707ba4 100644
--- a/snapshots/web/feedback-command/ack-expanded.expected.md
+++ b/snapshots/web/feedback-command/ack-expanded.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -44,7 +46,7 @@
   - img
   - img
   - text: "feedback Feedback recorded for session session-{{uuid}} Anonymous user: {{uuid}}."
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -55,4 +57,9 @@
   - img
 - button "6% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 99% Input 7.8K tok · Output 21 tok
+- button "1 turns 1 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 1 steps{{throughput}} tok/s
+- button "7.8K tok · Cache hit 99%":
+  - img
+  - text: 7.8K tokCache hit 99%
diff --git a/snapshots/web/feedback-command/ack.expected.md b/snapshots/web/feedback-command/ack.expected.md
index 7dfd7fe123..75bd8bad1b 100644
--- a/snapshots/web/feedback-command/ack.expected.md
+++ b/snapshots/web/feedback-command/ack.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -36,7 +38,7 @@
   - img
   - img
   - text: "feedback Feedback recorded for session session-{{uuid}} Anonymous user: {{uuid}}."
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -47,4 +49,9 @@
   - img
 - button "6% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 99% Input 7.8K tok · Output 21 tok
+- button "1 turns 1 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 1 steps{{throughput}} tok/s
+- button "7.8K tok · Cache hit 99%":
+  - img
+  - text: 7.8K tokCache hit 99%
diff --git a/snapshots/web/feedback-command/session.v2.jsonl b/snapshots/web/feedback-command/session.v2.jsonl
index 200aa74579..13afa38e79 100644
--- a/snapshots/web/feedback-command/session.v2.jsonl
+++ b/snapshots/web/feedback-command/session.v2.jsonl
@@ -2,11 +2,11 @@
 {"type":"permission/preset","data":{"preset":"workspace-write"}}
 {"type":"sandbox/mode","data":{"mode":"workspace-write"}}
 {"type":"approval/policy","data":{"policy":"ask"}}
-{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Reply with the single word LIGHTHOUSE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Reply with the single word LIGHTHOUSE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"}]}}
 {"type":"turn/start","data":{"turn":1}}
 {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","data":{"turn":1,"step":1}}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Reply with the single word LIGHTHOUSE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Reply with the single word LIGHTHOUSE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
 {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable.\n\nApproval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable."},{"name":"approval:policy","text":"Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}]},"role":"user","id":"{{message:2}}"},"surfaceOp":"append"}
 {"type":"session/title","data":{"title":"Reply with the single word","messageSeqs":[7],"source":{"kind":"fallback"}}}
 {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
diff --git a/snapshots/web/feedback-release/ack-expanded.expected.md b/snapshots/web/feedback-release/ack-expanded.expected.md
index 4d6f0f24c0..6939707ba4 100644
--- a/snapshots/web/feedback-release/ack-expanded.expected.md
+++ b/snapshots/web/feedback-release/ack-expanded.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -44,7 +46,7 @@
   - img
   - img
   - text: "feedback Feedback recorded for session session-{{uuid}} Anonymous user: {{uuid}}."
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -55,4 +57,9 @@
   - img
 - button "6% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 99% Input 7.8K tok · Output 21 tok
+- button "1 turns 1 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 1 steps{{throughput}} tok/s
+- button "7.8K tok · Cache hit 99%":
+  - img
+  - text: 7.8K tokCache hit 99%
diff --git a/snapshots/web/feedback-release/ack.expected.md b/snapshots/web/feedback-release/ack.expected.md
index 7dfd7fe123..75bd8bad1b 100644
--- a/snapshots/web/feedback-release/ack.expected.md
+++ b/snapshots/web/feedback-release/ack.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -36,7 +38,7 @@
   - img
   - img
   - text: "feedback Feedback recorded for session session-{{uuid}} Anonymous user: {{uuid}}."
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -47,4 +49,9 @@
   - img
 - button "6% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 99% Input 7.8K tok · Output 21 tok
+- button "1 turns 1 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 1 steps{{throughput}} tok/s
+- button "7.8K tok · Cache hit 99%":
+  - img
+  - text: 7.8K tokCache hit 99%
diff --git a/snapshots/web/file-upload-round/session.v2.jsonl b/snapshots/web/file-upload-round/session.v2.jsonl
index 0a2dc6ed92..7392f54115 100644
--- a/snapshots/web/file-upload-round/session.v2.jsonl
+++ b/snapshots/web/file-upload-round/session.v2.jsonl
@@ -3,11 +3,11 @@
 {"type":"sandbox/mode","data":{"mode":"workspace-write"}}
 {"type":"approval/policy","data":{"policy":"ask"}}
 {"type":"model/selection","data":{"provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp","reasoningEffort":"high"}}
-{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"file","attachment":{"attachmentId":"sha256:29a0837077f6f3cbddd98c0605897cc6f2b4e5833fb8e1ca4a8045d89b2c8c60","name":"poem.txt","bytes":16}},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","width":1,"height":1,"bytes":69,"name":"reference-1.png"}},{"type":"text","text":"Read the attached file with the read tool, reply with exactly the single word it contains, and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"file","attachment":{"attachmentId":"sha256:29a0837077f6f3cbddd98c0605897cc6f2b4e5833fb8e1ca4a8045d89b2c8c60","name":"poem.txt","bytes":16}},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","width":1,"height":1,"bytes":69,"name":"reference-1.png"}},{"type":"text","text":"Read the attached file with the read tool, reply with exactly the single word it contains, and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"}]}}
 {"type":"turn/start","data":{"turn":1}}
 {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","data":{"turn":1,"step":1}}
-{"type":"user/message","data":{"content":[{"type":"file","attachment":{"attachmentId":"sha256:29a0837077f6f3cbddd98c0605897cc6f2b4e5833fb8e1ca4a8045d89b2c8c60","name":"poem.txt","bytes":16}},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","width":1,"height":1,"bytes":69,"name":"reference-1.png"}},{"type":"text","text":"Read the attached file with the read tool, reply with exactly the single word it contains, and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"file","attachment":{"attachmentId":"sha256:29a0837077f6f3cbddd98c0605897cc6f2b4e5833fb8e1ca4a8045d89b2c8c60","name":"poem.txt","bytes":16}},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","width":1,"height":1,"bytes":69,"name":"reference-1.png"}},{"type":"text","text":"Read the attached file with the read tool, reply with exactly the single word it contains, and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
 {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable.\n\nApproval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable."},{"name":"approval:policy","text":"Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}]},"role":"user","id":"{{message:2}}"},"surfaceOp":"append"}
 {"type":"session/title","data":{"title":"Read the attached file with","messageSeqs":[8],"source":{"kind":"fallback"}}}
 {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp","reasoningEffort":"high","maxTokens":256000},"adapterDefaults":{"maxTokens":true},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
diff --git a/snapshots/web/file-upload-round/ui.expected.md b/snapshots/web/file-upload-round/ui.expected.md
index 2541ec1c4a..cbddcb3d63 100644
--- a/snapshots/web/file-upload-round/ui.expected.md
+++ b/snapshots/web/file-upload-round/ui.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -38,7 +40,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -49,4 +51,9 @@
   - img
 - button "1% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 51% Input 17.2K tok · Output 155 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "17.3K tok · Cache hit 51%":
+  - img
+  - text: 17.3K tokCache hit 51%
diff --git a/snapshots/web/fresh-round-trip/session.v2.jsonl b/snapshots/web/fresh-round-trip/session.v2.jsonl
index 3483237dcb..7733975e22 100644
--- a/snapshots/web/fresh-round-trip/session.v2.jsonl
+++ b/snapshots/web/fresh-round-trip/session.v2.jsonl
@@ -2,11 +2,11 @@
 {"type":"permission/preset","data":{"preset":"workspace-write"}}
 {"type":"sandbox/mode","data":{"mode":"workspace-write"}}
 {"type":"approval/policy","data":{"policy":"ask"}}
-{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo WEB_E2E_OK. Then reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo WEB_E2E_OK. Then reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"}]}}
 {"type":"turn/start","data":{"turn":1}}
 {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","data":{"turn":1,"step":1}}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo WEB_E2E_OK. Then reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: echo WEB_E2E_OK. Then reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
 {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable.\n\nApproval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable."},{"name":"approval:policy","text":"Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}]},"role":"user","id":"{{message:2}}"},"surfaceOp":"append"}
 {"type":"session/title","data":{"title":"Use the bash tool to","messageSeqs":[7],"source":{"kind":"fallback"}}}
 {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
diff --git a/snapshots/web/fresh-round-trip/ui-expanded.expected.md b/snapshots/web/fresh-round-trip/ui-expanded.expected.md
index b65f5d2ae3..0d877cc2e6 100644
--- a/snapshots/web/fresh-round-trip/ui-expanded.expected.md
+++ b/snapshots/web/fresh-round-trip/ui-expanded.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -48,7 +50,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -59,4 +61,9 @@
   - img
 - button "6% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 99% Input 15.7K tok · Output 111 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "15.8K tok · Cache hit 99%":
+  - img
+  - text: 15.8K tokCache hit 99%
diff --git a/snapshots/web/fresh-round-trip/ui.expected.md b/snapshots/web/fresh-round-trip/ui.expected.md
index f0449b34f2..61079e8d61 100644
--- a/snapshots/web/fresh-round-trip/ui.expected.md
+++ b/snapshots/web/fresh-round-trip/ui.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -32,7 +34,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -43,4 +45,9 @@
   - img
 - button "6% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 99% Input 15.7K tok · Output 111 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "15.8K tok · Cache hit 99%":
+  - img
+  - text: 15.8K tokCache hit 99%
diff --git a/snapshots/web/goal-multi-turn-actions/ui-expanded.expected.md b/snapshots/web/goal-multi-turn-actions/ui-expanded.expected.md
index aeb9ecd7a9..c88d6d3c40 100644
--- a/snapshots/web/goal-multi-turn-actions/ui-expanded.expected.md
+++ b/snapshots/web/goal-multi-turn-actions/ui-expanded.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -226,7 +228,7 @@
 - text: {{clock}}
 - button "Back to bottom":
   - img
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -237,4 +239,9 @@
   - img
 - button "9% of context used"
 - button "Send message" [disabled]
-- text: 2 turns · 12 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 91% Input 113K tok · Output 2.4K tok
+- button "2 turns 12 steps · {{throughput}} tok/s":
+  - img
+  - text: 2 turns 12 steps{{throughput}} tok/s
+- button "115K tok · Cache hit 91%":
+  - img
+  - text: 115K tokCache hit 91%
diff --git a/snapshots/web/goal-multi-turn-actions/ui.expected.md b/snapshots/web/goal-multi-turn-actions/ui.expected.md
index eeaf7d1cca..bcd881ffef 100644
--- a/snapshots/web/goal-multi-turn-actions/ui.expected.md
+++ b/snapshots/web/goal-multi-turn-actions/ui.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -114,7 +116,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -125,4 +127,9 @@
   - img
 - button "9% of context used"
 - button "Send message" [disabled]
-- text: 2 turns · 12 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 91% Input 113K tok · Output 2.4K tok
+- button "2 turns 12 steps · {{throughput}} tok/s":
+  - img
+  - text: 2 turns 12 steps{{throughput}} tok/s
+- button "115K tok · Cache hit 91%":
+  - img
+  - text: 115K tokCache hit 91%
diff --git a/snapshots/web/lifecycle-chrome/hero.expected.md b/snapshots/web/lifecycle-chrome/hero.expected.md
index a4694918d4..aa7c6a7728 100644
--- a/snapshots/web/lifecycle-chrome/hero.expected.md
+++ b/snapshots/web/lifecycle-chrome/hero.expected.md
@@ -29,7 +29,7 @@
   - img
   - text: Standard mode
   - img
-- textbox "Describe what you want to build... / commands, @ files or sessions":
+- textbox "Describe what you want to build, / commands, @ files or sessions":
   - paragraph
 - button "Commands":
   - img
@@ -40,6 +40,3 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: Details
-- button "Close details"
-- text: Click a tool row in the message flow to view its details
diff --git a/snapshots/web/lifecycle-chrome/plan-active.expected.md b/snapshots/web/lifecycle-chrome/plan-active.expected.md
index e886dd913e..bda1b957d8 100644
--- a/snapshots/web/lifecycle-chrome/plan-active.expected.md
+++ b/snapshots/web/lifecycle-chrome/plan-active.expected.md
@@ -29,7 +29,7 @@
   - img
   - text: Standard mode
   - img
-- textbox "Describe what you want to build... / commands, @ files or sessions"
+- textbox "Describe what you want to build, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -40,6 +40,3 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: Details
-- button "Close details"
-- text: Click a tool row in the message flow to view its details
diff --git a/snapshots/web/lifecycle-chrome/reloaded-expanded.expected.md b/snapshots/web/lifecycle-chrome/reloaded-expanded.expected.md
index 6cde9ddcba..f7e902be44 100644
--- a/snapshots/web/lifecycle-chrome/reloaded-expanded.expected.md
+++ b/snapshots/web/lifecycle-chrome/reloaded-expanded.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -40,7 +42,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -51,4 +53,9 @@
   - img
 - button "8% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 99.5% Input 10K tok · Output 21 tok
+- button "1 turns 1 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 1 steps{{throughput}} tok/s
+- button "10K tok · Cache hit 99.5%":
+  - img
+  - text: 10K tokCache hit 99.5%
diff --git a/snapshots/web/lifecycle-chrome/reloaded.expected.md b/snapshots/web/lifecycle-chrome/reloaded.expected.md
index dff102b7cb..47c78b4156 100644
--- a/snapshots/web/lifecycle-chrome/reloaded.expected.md
+++ b/snapshots/web/lifecycle-chrome/reloaded.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -32,7 +34,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -43,4 +45,9 @@
   - img
 - button "8% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 99.5% Input 10K tok · Output 21 tok
+- button "1 turns 1 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 1 steps{{throughput}} tok/s
+- button "10K tok · Cache hit 99.5%":
+  - img
+  - text: 10K tokCache hit 99.5%
diff --git a/snapshots/web/lifecycle-chrome/session.v2.jsonl b/snapshots/web/lifecycle-chrome/session.v2.jsonl
index b381ad3973..526a8d915e 100644
--- a/snapshots/web/lifecycle-chrome/session.v2.jsonl
+++ b/snapshots/web/lifecycle-chrome/session.v2.jsonl
@@ -2,11 +2,11 @@
 {"type":"permission/preset","data":{"preset":"workspace-write"}}
 {"type":"sandbox/mode","data":{"mode":"workspace-write"}}
 {"type":"approval/policy","data":{"policy":"ask"}}
-{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Reply with the single word LIGHTHOUSE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Reply with the single word LIGHTHOUSE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"}]}}
 {"type":"turn/start","data":{"turn":1}}
 {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","data":{"turn":1,"step":1}}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Reply with the single word LIGHTHOUSE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Reply with the single word LIGHTHOUSE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
 {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable.\n\nApproval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable."},{"name":"approval:policy","text":"Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}]},"role":"user","id":"{{message:2}}"},"surfaceOp":"append"}
 {"type":"session/title","data":{"title":"Reply with the single word","messageSeqs":[7],"source":{"kind":"fallback"}}}
 {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
diff --git a/snapshots/web/live-interactions/cancel-expanded.expected.md b/snapshots/web/live-interactions/cancel-expanded.expected.md
index 635ddf6d9f..906f3a9ed3 100644
--- a/snapshots/web/live-interactions/cancel-expanded.expected.md
+++ b/snapshots/web/live-interactions/cancel-expanded.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -37,7 +39,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -47,4 +49,6 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}} TTFT avg {{duration}}
+- button "1 turns 1 steps":
+  - img
+  - text: 1 turns 1 steps
diff --git a/snapshots/web/live-interactions/cancel.expected.md b/snapshots/web/live-interactions/cancel.expected.md
index 84320a45d0..d50dc2c162 100644
--- a/snapshots/web/live-interactions/cancel.expected.md
+++ b/snapshots/web/live-interactions/cancel.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -33,7 +35,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -43,4 +45,6 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}} TTFT avg {{duration}}
+- button "1 turns 1 steps":
+  - img
+  - text: 1 turns 1 steps
diff --git a/snapshots/web/live-interactions/error-auth.expected.md b/snapshots/web/live-interactions/error-auth.expected.md
index e5b3c6ca64..d6cd35dcb3 100644
--- a/snapshots/web/live-interactions/error-auth.expected.md
+++ b/snapshots/web/live-interactions/error-auth.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -23,7 +25,7 @@
 - status:
   - text: This turn failedAPI key is invalid
   - code: AUTH
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -33,4 +35,5 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps
+- img
+- text: 1 turns 1 steps
diff --git a/snapshots/web/live-interactions/loading.expected.md b/snapshots/web/live-interactions/loading.expected.md
index a16ba7d1ee..3dfa3da484 100644
--- a/snapshots/web/live-interactions/loading.expected.md
+++ b/snapshots/web/live-interactions/loading.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -22,7 +24,7 @@
   - text: Context injection @deepseek-ai/dsh-system-prompt
 - paragraph: partial
 - status: Deep diving...
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
diff --git a/snapshots/web/live-interactions/retry-exhausted.expected.md b/snapshots/web/live-interactions/retry-exhausted.expected.md
index 237543a043..a9c40b178e 100644
--- a/snapshots/web/live-interactions/retry-exhausted.expected.md
+++ b/snapshots/web/live-interactions/retry-exhausted.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -25,7 +27,7 @@
 - status:
   - text: This turn failedupstream 503
   - code: SERVER
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -35,4 +37,5 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps
+- img
+- text: 1 turns 1 steps
diff --git a/snapshots/web/live-interactions/retry-expanded.expected.md b/snapshots/web/live-interactions/retry-expanded.expected.md
index 3919ce3dfc..6c3591cc67 100644
--- a/snapshots/web/live-interactions/retry-expanded.expected.md
+++ b/snapshots/web/live-interactions/retry-expanded.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -42,7 +44,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -53,4 +55,9 @@
   - img
 - button "6% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 99% Input 7.8K tok · Output 79 tok
+- button "1 turns 1 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 1 steps{{throughput}} tok/s
+- button "7.9K tok · Cache hit 99%":
+  - img
+  - text: 7.9K tokCache hit 99%
diff --git a/snapshots/web/live-interactions/retry.expected.md b/snapshots/web/live-interactions/retry.expected.md
index 1cfe5382f5..21ce478e78 100644
--- a/snapshots/web/live-interactions/retry.expected.md
+++ b/snapshots/web/live-interactions/retry.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -32,7 +34,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -43,4 +45,9 @@
   - img
 - button "6% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 99% Input 7.8K tok · Output 79 tok
+- button "1 turns 1 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 1 steps{{throughput}} tok/s
+- button "7.9K tok · Cache hit 99%":
+  - img
+  - text: 7.9K tokCache hit 99%
diff --git a/snapshots/web/live-interactions/running-draft.expected.md b/snapshots/web/live-interactions/running-draft.expected.md
index fa61237f73..505805bc35 100644
--- a/snapshots/web/live-interactions/running-draft.expected.md
+++ b/snapshots/web/live-interactions/running-draft.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -22,7 +24,7 @@
   - text: Context injection @deepseek-ai/dsh-system-prompt
 - paragraph: partial
 - status: Deep diving...
-- textbox "Message or run a task... / commands, @ files or sessions":
+- textbox "Message or run a task, / commands, @ files or sessions":
   - paragraph: Queue this follow-up while the current turn is running.
 - button "Commands":
   - img
@@ -32,4 +34,4 @@
 - button "Select model, current DeepSeek-V4-Flash":
   - text: DeepSeek-V4-Flash
   - img
-- button "Send message"
+- button "Queue message"
diff --git a/snapshots/web/live-interactions/session.v2.jsonl b/snapshots/web/live-interactions/session.v2.jsonl
index b180b60107..410f5d9ad1 100644
--- a/snapshots/web/live-interactions/session.v2.jsonl
+++ b/snapshots/web/live-interactions/session.v2.jsonl
@@ -2,11 +2,11 @@
 {"type":"permission/preset","data":{"preset":"workspace-write"}}
 {"type":"sandbox/mode","data":{"mode":"workspace-write"}}
 {"type":"approval/policy","data":{"policy":"ask"}}
-{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Reply with a one-sentence description of event sourcing, then stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Reply with a one-sentence description of event sourcing, then stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"}]}}
 {"type":"turn/start","data":{"turn":1}}
 {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","data":{"turn":1,"step":1}}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Reply with a one-sentence description of event sourcing, then stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Reply with a one-sentence description of event sourcing, then stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
 {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable.\n\nApproval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable."},{"name":"approval:policy","text":"Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}]},"role":"user","id":"{{message:2}}"},"surfaceOp":"append"}
 {"type":"session/title","data":{"title":"Reply with a one-sentence description","messageSeqs":[7],"source":{"kind":"fallback"}}}
 {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
diff --git a/snapshots/web/message-actions/ui.expected.md b/snapshots/web/message-actions/ui.expected.md
index 3ca1911afc..58ae5e04f7 100644
--- a/snapshots/web/message-actions/ui.expected.md
+++ b/snapshots/web/message-actions/ui.expected.md
@@ -4,6 +4,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -62,7 +64,7 @@
   - img
   - text: Ran for {{duration}}
 - text: 7/25 {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -72,4 +74,9 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: 2 turns · 3 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 98% Input 7.8K tok · Output 103 tok
+- button "2 turns 3 steps · {{throughput}} tok/s":
+  - img
+  - text: 2 turns 3 steps{{throughput}} tok/s
+- button "7.9K tok · Cache hit 98%":
+  - img
+  - text: 7.9K tokCache hit 98%
diff --git a/snapshots/web/minimal-preset/ui.expected.md b/snapshots/web/minimal-preset/ui.expected.md
index 91a71e8e57..9ad6fdf256 100644
--- a/snapshots/web/minimal-preset/ui.expected.md
+++ b/snapshots/web/minimal-preset/ui.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -37,7 +39,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -48,4 +50,9 @@
   - img
 - button "0% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 0% Input 20 tok · Output 8 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "28 tok · Cache hit 0%":
+  - img
+  - text: 28 tokCache hit 0%
diff --git a/snapshots/web/permission-policy-context/session.v2.jsonl b/snapshots/web/permission-policy-context/session.v2.jsonl
index 122a45d0d0..94537cd60c 100644
--- a/snapshots/web/permission-policy-context/session.v2.jsonl
+++ b/snapshots/web/permission-policy-context/session.v2.jsonl
@@ -6,11 +6,11 @@
 {"type":"permission/preset","data":{"preset":"read-only"}}
 {"type":"sandbox/mode","data":{"mode":"read-only"}}
 {"type":"command/done","data":{"commandId":"{{command:1}}","kind":"success","text":"preset read-only"}}
-{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Can you create or edit a normal file right now under the current policy? Answer directly in one sentence. Do not call a tool just to discover the policy."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Can you create or edit a normal file right now under the current policy? Answer directly in one sentence. Do not call a tool just to discover the policy."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"}]}}
 {"type":"turn/start","data":{"turn":1}}
 {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","data":{"turn":1,"step":1}}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Can you create or edit a normal file right now under the current policy? Answer directly in one sentence. Do not call a tool just to discover the policy."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Can you create or edit a normal file right now under the current policy? Answer directly in one sentence. Do not call a tool just to discover the policy."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
 {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: read-only. Any available operation enforced by the DSH file sandbox cannot modify files in the standing mode. Do not refuse a required modification from this policy alone: try an available tool normally and follow any denial and escalation guidance it returns.\n\nApproval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: read-only. Any available operation enforced by the DSH file sandbox cannot modify files in the standing mode. Do not refuse a required modification from this policy alone: try an available tool normally and follow any denial and escalation guidance it returns."},{"name":"approval:policy","text":"Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}]},"role":"user","id":"{{message:2}}"},"surfaceOp":"append"}
 {"type":"session/title","data":{"title":"Can you create or edit","messageSeqs":[11],"source":{"kind":"fallback"}}}
 {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
@@ -24,13 +24,13 @@
 {"type":"approval/policy","data":{"policy":"never"}}
 {"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"inserted":[{"content":[{"type":"text","text":"The approval policy changed from \"ask\" to \"never\" (changed by the user)."}],"source":{"kind":"plugin","plugin":"user-approval"},"role":"user","id":"{{message:4}}"}]}}
 {"type":"command/done","data":{"commandId":"{{command:2}}","kind":"success","text":"preset danger-full-access"}}
-{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Does the DSH file sandbox currently restrict file operations? Answer directly in one sentence. Do not call tools."}],"source":{"kind":"user","rpcId":"{{rpc:2}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:5}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Does the DSH file sandbox currently restrict file operations? Answer directly in one sentence. Do not call tools."}],"source":{"kind":"user","rpcId":"{{rpc:2}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:5}}"}]}}
 {"type":"turn/start","data":{"turn":2}}
 {"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"removedCount":1,"inserted":[]}}
 {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","data":{"turn":2,"step":1}}
 {"type":"user/message","data":{"content":[{"type":"text","text":"The approval policy changed from \"ask\" to \"never\" (changed by the user)."}],"source":{"kind":"plugin","plugin":"user-approval"},"role":"user","id":"{{message:4}}"},"surfaceOp":"append"}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Does the DSH file sandbox currently restrict file operations? Answer directly in one sentence. Do not call tools."}],"source":{"kind":"user","rpcId":"{{rpc:2}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:5}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Does the DSH file sandbox currently restrict file operations? Answer directly in one sentence. Do not call tools."}],"source":{"kind":"user","rpcId":"{{rpc:2}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:5}}"},"surfaceOp":"append"}
 {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{message:6}}"},"surfaceOp":"append"}
 {"type":"assistant/message","data":{"turn":2,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user is asking about the current DSH file sandbox restrictions. According to the current runtime context snapshot, the file policy is \"danger-full-access\" which means no restrictions on file operations. Also, approval prompts are disabled, so I should not request sandbox escalation.\n\nLet me answer directly in one sentence without calling tools."},{"type":"text","text":"No, the DSH file sandbox currently grants full access — it does not restrict file operations."}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:7}}"},"usage":{"inputTokens":202,"outputTokens":87,"cacheReadTokens":14848,"reasoningTokens":66},"stream":[{"type":"chunk","time":1788240690252,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1788240690252,"index":0,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," user"," is"," asking"," about"," the"," current"," D","SH"," file"," sand","box"," restrictions","."," According"," to"," the"," current"," runtime"," context"," snapshot",","," the"," file"," policy"," is"," \"","danger","-full","-access","\""," which"," means"," no"," restrictions"," on"," file"," operations","."," Also",","," approval"," prompts"," are"," disabled",","," so"," I"," should"," not"," request"," sand","box"," escalation",".\n\n","Let"," me"," answer"," directly"," in"," one"," sentence"," without"," calling"," tools","."]},{"type":"chunk","time":1788240690252,"chunk":{"type":"block-start","index":1,"blockType":"text"}},{"type":"text-chunks","time0":1788240690252,"index":1,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["No",","," the"," D","SH"," file"," sand","box"," currently"," grants"," full"," access"," —"," it"," does"," not"," restrict"," file"," operations","."]},{"type":"chunk","time":1788240690253,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user is asking about the current DSH file sandbox restrictions. According to the current runtime context snapshot, the file policy is \"danger-full-access\" which means no restrictions on file operations. Also, approval prompts are disabled, so I should not request sandbox escalation.\n\nLet me answer directly in one sentence without calling tools."}}},{"type":"chunk","time":1788240690253,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"No, the DSH file sandbox currently grants full access — it does not restrict file operations."}}},{"type":"chunk","time":1788240690253,"chunk":{"type":"usage","usage":{"inputTokens":202,"outputTokens":87,"cacheReadTokens":14848,"reasoningTokens":66}}},{"type":"chunk","time":1788240690253,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
 {"type":"step/end","data":{"turn":2,"step":1}}
@@ -41,13 +41,13 @@
 {"type":"approval/policy","data":{"policy":"ask"}}
 {"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"inserted":[{"content":[{"type":"text","text":"The approval policy changed from \"never\" to \"ask\" (changed by the user)."}],"source":{"kind":"plugin","plugin":"user-approval"},"role":"user","id":"{{message:8}}"}]}}
 {"type":"command/done","data":{"commandId":"{{command:3}}","kind":"success","text":"preset workspace-write"}}
-{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Reply with exactly WORKSPACE_POLICY_SEEN. Do not call tools."}],"source":{"kind":"user","rpcId":"{{rpc:3}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:9}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Reply with exactly WORKSPACE_POLICY_SEEN. Do not call tools."}],"source":{"kind":"user","rpcId":"{{rpc:3}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:9}}"}]}}
 {"type":"turn/start","data":{"turn":3}}
 {"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"removedCount":1,"inserted":[]}}
 {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","data":{"turn":3,"step":1}}
 {"type":"user/message","data":{"content":[{"type":"text","text":"The approval policy changed from \"never\" to \"ask\" (changed by the user)."}],"source":{"kind":"plugin","plugin":"user-approval"},"role":"user","id":"{{message:8}}"},"surfaceOp":"append"}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Reply with exactly WORKSPACE_POLICY_SEEN. Do not call tools."}],"source":{"kind":"user","rpcId":"{{rpc:3}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:9}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Reply with exactly WORKSPACE_POLICY_SEEN. Do not call tools."}],"source":{"kind":"user","rpcId":"{{rpc:3}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:9}}"},"surfaceOp":"append"}
 {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable.\n\nApproval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable."},{"name":"approval:policy","text":"Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}]},"role":"user","id":"{{message:10}}"},"surfaceOp":"append"}
 {"type":"assistant/message","data":{"turn":3,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to reply with exactly \"WORKSPACE_POLICY_SEEN\"."},{"type":"text","text":"WORKSPACE_POLICY_SEEN"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:11}}"},"usage":{"inputTokens":245,"outputTokens":27,"cacheReadTokens":14976,"reasoningTokens":18},"stream":[{"type":"chunk","time":1788240690459,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1788240690459,"index":0,"dt":[0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," user"," wants"," me"," to"," reply"," with"," exactly"," \"","WORK","SP","ACE","_P","OL","ICY","_SE","EN","\"."]},{"type":"chunk","time":1788240690460,"chunk":{"type":"block-start","index":1,"blockType":"text"}},{"type":"text-chunks","time0":1788240690460,"index":1,"dt":[0,0,0,0,0,0,0],"texts":["WORK","SP","ACE","_P","OL","ICY","_SE","EN"]},{"type":"chunk","time":1788240690460,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to reply with exactly \"WORKSPACE_POLICY_SEEN\"."}}},{"type":"chunk","time":1788240690460,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"WORKSPACE_POLICY_SEEN"}}},{"type":"chunk","time":1788240690460,"chunk":{"type":"usage","usage":{"inputTokens":245,"outputTokens":27,"cacheReadTokens":14976,"reasoningTokens":18}}},{"type":"chunk","time":1788240690460,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
 {"type":"step/end","data":{"turn":3,"step":1}}
@@ -56,11 +56,11 @@
 {"type":"permission/preset","data":{"preset":"read-only"}}
 {"type":"sandbox/mode","data":{"mode":"read-only"}}
 {"type":"command/done","data":{"commandId":"{{command:4}}","kind":"success","text":"preset read-only"}}
-{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Create the relative path policy-neutral.txt in the current workspace containing exactly POLICY_NEUTRAL_OK, verify its contents, then report completion."}],"source":{"kind":"user","rpcId":"{{rpc:4}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:12}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Create the relative path policy-neutral.txt in the current workspace containing exactly POLICY_NEUTRAL_OK, verify its contents, then report completion."}],"source":{"kind":"user","rpcId":"{{rpc:4}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:12}}"}]}}
 {"type":"turn/start","data":{"turn":4}}
 {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","data":{"turn":4,"step":1}}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Create the relative path policy-neutral.txt in the current workspace containing exactly POLICY_NEUTRAL_OK, verify its contents, then report completion."}],"source":{"kind":"user","rpcId":"{{rpc:4}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:12}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Create the relative path policy-neutral.txt in the current workspace containing exactly POLICY_NEUTRAL_OK, verify its contents, then report completion."}],"source":{"kind":"user","rpcId":"{{rpc:4}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:12}}"},"surfaceOp":"append"}
 {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: read-only. Any available operation enforced by the DSH file sandbox cannot modify files in the standing mode. Do not refuse a required modification from this policy alone: try an available tool normally and follow any denial and escalation guidance it returns.\n\nApproval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: read-only. Any available operation enforced by the DSH file sandbox cannot modify files in the standing mode. Do not refuse a required modification from this policy alone: try an available tool normally and follow any denial and escalation guidance it returns."},{"name":"approval:policy","text":"Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}]},"role":"user","id":"{{message:13}}"},"surfaceOp":"append"}
 {"type":"assistant/message","data":{"turn":4,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The current policy is read-only, so write tools will be denied. I should attempt it normally and follow the denial/ escalation guidance. Let me try to write the file."},{"type":"tool-call","id":"call_00_1SovMaD1sZjZwhmQuUCb7415","name":"write","arguments":"{\"file_path\": \"policy-neutral.txt\", \"content\": \"POLICY_NEUTRAL_OK\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:14}}"},"usage":{"inputTokens":265,"outputTokens":103,"cacheReadTokens":15104,"reasoningTokens":35},"stream":[{"type":"chunk","time":1788240690726,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1788240690726,"index":0,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," current"," policy"," is"," read","-only",","," so"," write"," tools"," will"," be"," denied","."," I"," should"," attempt"," it"," normally"," and"," follow"," the"," denial","/"," escalation"," guidance","."," Let"," me"," try"," to"," write"," the"," file","."]},{"type":"chunk","time":1788240690726,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788240690726,"index":1,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"id":"call_00_1SovMaD1sZjZwhmQuUCb7415","name":"write","args":["","{","\"","file","_path","\"",": ","\"","policy","-neutral",".txt","\"",", ","\"","content","\"",": ","\"","POL","ICY","_","NE","UT","RAL","_OK","\"","}"]},{"type":"chunk","time":1788240690726,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The current policy is read-only, so write tools will be denied. I should attempt it normally and follow the denial/ escalation guidance. Let me try to write the file."}}},{"type":"chunk","time":1788240690726,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_1SovMaD1sZjZwhmQuUCb7415","name":"write","arguments":"{\"file_path\": \"policy-neutral.txt\", \"content\": \"POLICY_NEUTRAL_OK\"}"}}},{"type":"chunk","time":1788240690726,"chunk":{"type":"usage","usage":{"inputTokens":265,"outputTokens":103,"cacheReadTokens":15104,"reasoningTokens":35}}},{"type":"chunk","time":1788240690727,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
 {"type":"tool/call","data":{"turn":4,"step":1,"callId":"call_00_1SovMaD1sZjZwhmQuUCb7415","name":"write","arguments":"{\"file_path\": \"policy-neutral.txt\", \"content\": \"POLICY_NEUTRAL_OK\"}"}}
diff --git a/snapshots/web/plan-review/approved-expanded.expected.md b/snapshots/web/plan-review/approved-expanded.expected.md
index 58abbd47bd..43c4b97487 100644
--- a/snapshots/web/plan-review/approved-expanded.expected.md
+++ b/snapshots/web/plan-review/approved-expanded.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -58,7 +60,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -69,4 +71,9 @@
   - img
 - button "4% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 51% Input 10.2K tok · Output 346 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "10.6K tok · Cache hit 51%":
+  - img
+  - text: 10.6K tokCache hit 51%
diff --git a/snapshots/web/plan-review/approved.expected.md b/snapshots/web/plan-review/approved.expected.md
index cc7b07f86d..c04fb13bad 100644
--- a/snapshots/web/plan-review/approved.expected.md
+++ b/snapshots/web/plan-review/approved.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -38,7 +40,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -49,4 +51,9 @@
   - img
 - button "4% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 51% Input 10.2K tok · Output 346 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "10.6K tok · Cache hit 51%":
+  - img
+  - text: 10.6K tokCache hit 51%
diff --git a/snapshots/web/ptc-round/session.v2.jsonl b/snapshots/web/ptc-round/session.v2.jsonl
index 2b78e1c084..ed3568d1ed 100644
--- a/snapshots/web/ptc-round/session.v2.jsonl
+++ b/snapshots/web/ptc-round/session.v2.jsonl
@@ -2,11 +2,11 @@
 {"type":"permission/preset","data":{"preset":"workspace-write"}}
 {"type":"sandbox/mode","data":{"mode":"workspace-write"}}
 {"type":"approval/policy","data":{"policy":"ask"}}
-{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Using ONE run_code program: run bash `echo CODE_ROUND_OK`, then read the file missing.txt catching its error in the program. Return an object with both outcomes. Then reply DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Using ONE run_code program: run bash `echo CODE_ROUND_OK`, then read the file missing.txt catching its error in the program. Return an object with both outcomes. Then reply DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"}]}}
 {"type":"turn/start","data":{"turn":1}}
 {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","data":{"turn":1,"step":1}}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Using ONE run_code program: run bash `echo CODE_ROUND_OK`, then read the file missing.txt catching its error in the program. Return an object with both outcomes. Then reply DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Using ONE run_code program: run bash `echo CODE_ROUND_OK`, then read the file missing.txt catching its error in the program. Return an object with both outcomes. Then reply DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
 {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable.\n\nApproval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable."},{"name":"approval:policy","text":"Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}]},"role":"user","id":"{{message:2}}"},"surfaceOp":"append"}
 {"type":"session/title","data":{"title":"Using ONE run_code program: run","messageSeqs":[7],"source":{"kind":"fallback"}}}
 {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
diff --git a/snapshots/web/ptc-round/ui.expected.md b/snapshots/web/ptc-round/ui.expected.md
index 1d2c9b9abd..94727a92fe 100644
--- a/snapshots/web/ptc-round/ui.expected.md
+++ b/snapshots/web/ptc-round/ui.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -59,7 +61,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -70,4 +72,9 @@
   - img
 - button "7% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 52% Input 17.2K tok · Output 252 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "17.5K tok · Cache hit 52%":
+  - img
+  - text: 17.5K tokCache hit 52%
diff --git a/snapshots/web/question-composer/answered-expanded.expected.md b/snapshots/web/question-composer/answered-expanded.expected.md
index 34c5652e9a..a57598a5c3 100644
--- a/snapshots/web/question-composer/answered-expanded.expected.md
+++ b/snapshots/web/question-composer/answered-expanded.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -50,7 +52,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -61,4 +63,9 @@
   - img
 - button "3% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 95% Input 8.6K tok · Output 180 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "8.8K tok · Cache hit 95%":
+  - img
+  - text: 8.8K tokCache hit 95%
diff --git a/snapshots/web/question-composer/answered.expected.md b/snapshots/web/question-composer/answered.expected.md
index 1a879c04c5..7d7da25ef6 100644
--- a/snapshots/web/question-composer/answered.expected.md
+++ b/snapshots/web/question-composer/answered.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -32,7 +34,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -43,4 +45,9 @@
   - img
 - button "3% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 95% Input 8.6K tok · Output 180 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "8.8K tok · Cache hit 95%":
+  - img
+  - text: 8.8K tokCache hit 95%
diff --git a/snapshots/web/question-composer/cancelled.expected.md b/snapshots/web/question-composer/cancelled.expected.md
index d6f6be3bba..d23da91aed 100644
--- a/snapshots/web/question-composer/cancelled.expected.md
+++ b/snapshots/web/question-composer/cancelled.expected.md
@@ -4,6 +4,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -29,7 +31,7 @@
 - list:
   - listitem: Which color do you prefer?
 - button "Inspect"
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -40,4 +42,9 @@
   - img
 - button "3% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 97% Input 4.2K tok · Output 158 tok
+- button "1 turns 1 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 1 steps{{throughput}} tok/s
+- button "4.4K tok · Cache hit 97%":
+  - img
+  - text: 4.4K tokCache hit 97%
diff --git a/snapshots/web/question-composer/session.v2.jsonl b/snapshots/web/question-composer/session.v2.jsonl
index 543c7cd981..3c4b211db6 100644
--- a/snapshots/web/question-composer/session.v2.jsonl
+++ b/snapshots/web/question-composer/session.v2.jsonl
@@ -2,11 +2,11 @@
 {"type":"permission/preset","data":{"preset":"workspace-write"}}
 {"type":"sandbox/mode","data":{"mode":"workspace-write"}}
 {"type":"approval/policy","data":{"policy":"ask"}}
-{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use the ask_user_question tool to ask me exactly one multi-select question with id \"color\", question \"Which color do you prefer?\", header \"Pick one\", and two options: label \"Blue\" with description \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\", and label \"Green\" with description \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\" Set multi_select to true. After I answer, reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use the ask_user_question tool to ask me exactly one multi-select question with id \"color\", question \"Which color do you prefer?\", header \"Pick one\", and two options: label \"Blue\" with description \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\", and label \"Green\" with description \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\" Set multi_select to true. After I answer, reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"}]}}
 {"type":"turn/start","data":{"turn":1}}
 {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","data":{"turn":1,"step":1}}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Use the ask_user_question tool to ask me exactly one multi-select question with id \"color\", question \"Which color do you prefer?\", header \"Pick one\", and two options: label \"Blue\" with description \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\", and label \"Green\" with description \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\" Set multi_select to true. After I answer, reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Use the ask_user_question tool to ask me exactly one multi-select question with id \"color\", question \"Which color do you prefer?\", header \"Pick one\", and two options: label \"Blue\" with description \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\", and label \"Green\" with description \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\" Set multi_select to true. After I answer, reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
 {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable.\n\nApproval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable."},{"name":"approval:policy","text":"Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}]},"role":"user","id":"{{message:2}}"},"surfaceOp":"append"}
 {"type":"session/title","data":{"title":"Use the ask_user_question tool to","messageSeqs":[7],"source":{"kind":"fallback"}}}
 {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
diff --git a/snapshots/web/queue-actions/collapsed.expected.md b/snapshots/web/queue-actions/collapsed.expected.md
index 0b3e7b65b0..6645c331fd 100644
--- a/snapshots/web/queue-actions/collapsed.expected.md
+++ b/snapshots/web/queue-actions/collapsed.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
diff --git a/snapshots/web/queue-actions/editing.expected.md b/snapshots/web/queue-actions/editing.expected.md
index f32a37c548..d0586fb967 100644
--- a/snapshots/web/queue-actions/editing.expected.md
+++ b/snapshots/web/queue-actions/editing.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
diff --git a/snapshots/web/queue-actions/failed.expected.md b/snapshots/web/queue-actions/failed.expected.md
index d0f83b7fa3..02c1fa881b 100644
--- a/snapshots/web/queue-actions/failed.expected.md
+++ b/snapshots/web/queue-actions/failed.expected.md
@@ -1,5 +1,5 @@
 - alert: Queue submission failed (session/agent-busy)
-- textbox "Message or run a task... / commands, @ files or sessions":
+- textbox "Message or run a task, / commands, @ files or sessions":
   - paragraph: Queue submission to retry
 - button "Commands":
   - img
@@ -9,4 +9,4 @@
 - button "Select model, current DeepSeek-V4-Flash":
   - text: DeepSeek-V4-Flash
   - img
-- button "Send message"
+- button "Queue message"
diff --git a/snapshots/web/queue-actions/layout.expected.md b/snapshots/web/queue-actions/layout.expected.md
index 0e0835f2bb..79f239edd8 100644
--- a/snapshots/web/queue-actions/layout.expected.md
+++ b/snapshots/web/queue-actions/layout.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
diff --git a/snapshots/web/queue-actions/preserved-expanded.expected.md b/snapshots/web/queue-actions/preserved-expanded.expected.md
index 041650fb7b..6e9d8c1134 100644
--- a/snapshots/web/queue-actions/preserved-expanded.expected.md
+++ b/snapshots/web/queue-actions/preserved-expanded.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -56,7 +58,7 @@
       - img
     - button "Steer queued message" [disabled]:
       - img
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -66,4 +68,6 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}} TTFT avg {{duration}}
+- button "1 turns 1 steps":
+  - img
+  - text: 1 turns 1 steps
diff --git a/snapshots/web/queue-actions/preserved.expected.md b/snapshots/web/queue-actions/preserved.expected.md
index e9a74f7b05..a4547ed17d 100644
--- a/snapshots/web/queue-actions/preserved.expected.md
+++ b/snapshots/web/queue-actions/preserved.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -52,7 +54,7 @@
       - img
     - button "Steer queued message" [disabled]:
       - img
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -62,4 +64,6 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}} TTFT avg {{duration}}
+- button "1 turns 1 steps":
+  - img
+  - text: 1 turns 1 steps
diff --git a/snapshots/web/queue-actions/sending.expected.md b/snapshots/web/queue-actions/sending.expected.md
index 10115fe73b..d2b2a0d9de 100644
--- a/snapshots/web/queue-actions/sending.expected.md
+++ b/snapshots/web/queue-actions/sending.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -32,7 +34,7 @@
       - img
     - button "Steer queued message" [disabled]:
       - img
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
diff --git a/snapshots/web/queue-actions/ui.expected.md b/snapshots/web/queue-actions/ui.expected.md
index e314229b31..e7aa55934d 100644
--- a/snapshots/web/queue-actions/ui.expected.md
+++ b/snapshots/web/queue-actions/ui.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
diff --git a/snapshots/web/queued-image/delivered.expected.md b/snapshots/web/queued-image/delivered.expected.md
index 23fad54c88..7ea64dd0f6 100644
--- a/snapshots/web/queued-image/delivered.expected.md
+++ b/snapshots/web/queued-image/delivered.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -76,7 +78,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -87,4 +89,9 @@
   - img
 - button "6% of context used"
 - button "Send message" [disabled]
-- text: 3 turns · 3 steps LLM {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 99% Input 15.6K tok · Output 158 tok
+- button "3 turns 3 steps · {{throughput}} tok/s":
+  - img
+  - text: 3 turns 3 steps{{throughput}} tok/s
+- button "15.7K tok · Cache hit 99%":
+  - img
+  - text: 15.7K tokCache hit 99%
diff --git a/snapshots/web/queued-image/queued.expected.md b/snapshots/web/queued-image/queued.expected.md
index 457affb944..68d4ef90b7 100644
--- a/snapshots/web/queued-image/queued.expected.md
+++ b/snapshots/web/queued-image/queued.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
diff --git a/snapshots/web/seeded-history/command-row.expected.md b/snapshots/web/seeded-history/command-row.expected.md
index 3e9691ff71..527ad8658a 100644
--- a/snapshots/web/seeded-history/command-row.expected.md
+++ b/snapshots/web/seeded-history/command-row.expected.md
@@ -4,6 +4,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -58,7 +60,7 @@
   - text: Context injection AGENTS.md
 - img
 - text: permission preset read-only
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -68,4 +70,9 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 98% Input 15.8K tok · Output 135 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "16K tok · Cache hit 98%":
+  - img
+  - text: 16K tokCache hit 98%
diff --git a/snapshots/web/seeded-history/feedback-row.expected.md b/snapshots/web/seeded-history/feedback-row.expected.md
index 7ce1e515d4..ba2ac9fd6b 100644
--- a/snapshots/web/seeded-history/feedback-row.expected.md
+++ b/snapshots/web/seeded-history/feedback-row.expected.md
@@ -4,6 +4,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -62,7 +64,7 @@
   - img
   - text: "feedback Feedback recorded for session {{seededId}} Anonymous user: {{uuid}}."
 - text: "Feedback recorded for session {{seededId}} Anonymous user: {{uuid}}."
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -72,4 +74,9 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 98% Input 15.8K tok · Output 135 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "16K tok · Cache hit 98%":
+  - img
+  - text: 16K tokCache hit 98%
diff --git a/snapshots/web/seeded-history/file-open-failure.expected.md b/snapshots/web/seeded-history/file-open-failure.expected.md
deleted file mode 100644
index fece247a7a..0000000000
--- a/snapshots/web/seeded-history/file-open-failure.expected.md
+++ /dev/null
@@ -1,7 +0,0 @@
-- dialog "Couldn’t open file":
-  - heading "Couldn’t open file" [level=2]
-  - button "Close":
-    - img
-  - paragraph: "path open failed: xdg-open is not available"
-  - button "Cancel"
-  - button "Retry"
diff --git a/snapshots/web/seeded-history/file-preview.expected.md b/snapshots/web/seeded-history/file-preview.expected.md
new file mode 100644
index 0000000000..531cfe6e27
--- /dev/null
+++ b/snapshots/web/seeded-history/file-preview.expected.md
@@ -0,0 +1,6 @@
+- text: {{cwd}}/a.txt
+- button "Wrap lines" [pressed]:
+  - img
+- button "Read the file again":
+  - img
+- text: alpha
diff --git a/snapshots/web/seeded-history/ui-expanded.expected.md b/snapshots/web/seeded-history/ui-expanded.expected.md
index 70c6204338..b655c75182 100644
--- a/snapshots/web/seeded-history/ui-expanded.expected.md
+++ b/snapshots/web/seeded-history/ui-expanded.expected.md
@@ -4,6 +4,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -56,7 +58,7 @@
   - img
   - img
   - text: Context injection AGENTS.md
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -66,4 +68,9 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 98% Input 15.8K tok · Output 135 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "16K tok · Cache hit 98%":
+  - img
+  - text: 16K tokCache hit 98%
diff --git a/snapshots/web/seeded-history/ui.expected.md b/snapshots/web/seeded-history/ui.expected.md
index 7ea48e69f6..90642e4c58 100644
--- a/snapshots/web/seeded-history/ui.expected.md
+++ b/snapshots/web/seeded-history/ui.expected.md
@@ -4,6 +4,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -38,7 +40,7 @@
   - img
   - img
   - text: Context injection AGENTS.md
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -48,4 +50,9 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 98% Input 15.8K tok · Output 135 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "16K tok · Cache hit 98%":
+  - img
+  - text: 16K tokCache hit 98%
diff --git a/snapshots/web/skill-tool-row/ui.expected.md b/snapshots/web/skill-tool-row/ui.expected.md
index 74903e7e6e..737d74f2a6 100644
--- a/snapshots/web/skill-tool-row/ui.expected.md
+++ b/snapshots/web/skill-tool-row/ui.expected.md
@@ -4,6 +4,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -51,7 +53,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{date}} {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -61,4 +63,9 @@
   - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 0% Input 280 tok · Output 30 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "310 tok · Cache hit 0%":
+  - img
+  - text: 310 tokCache hit 0%
diff --git a/snapshots/web/steering/mid-steer.expected.md b/snapshots/web/steering/mid-steer.expected.md
index 557e5bc0ff..94b2356941 100644
--- a/snapshots/web/steering/mid-steer.expected.md
+++ b/snapshots/web/steering/mid-steer.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
diff --git a/snapshots/web/steering/session.v2.jsonl b/snapshots/web/steering/session.v2.jsonl
index 19d5bd5061..748f05dd05 100644
--- a/snapshots/web/steering/session.v2.jsonl
+++ b/snapshots/web/steering/session.v2.jsonl
@@ -2,25 +2,25 @@
 {"type":"permission/preset","data":{"preset":"workspace-write"}}
 {"type":"sandbox/mode","data":{"mode":"workspace-write"}}
 {"type":"approval/policy","data":{"policy":"ask"}}
-{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use the ask_user_question tool to ask me exactly one question with id \"checkpoint\", question \"Ready to continue?\", header \"Checkpoint\", and options labeled \"Yes\" and \"No\". After I answer, reply with one short sentence acknowledging my answer and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use the ask_user_question tool to ask me exactly one question with id \"checkpoint\", question \"Ready to continue?\", header \"Checkpoint\", and options labeled \"Yes\" and \"No\". After I answer, reply with one short sentence acknowledging my answer and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"}]}}
 {"type":"turn/start","data":{"turn":1}}
 {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","data":{"turn":1,"step":1}}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Use the ask_user_question tool to ask me exactly one question with id \"checkpoint\", question \"Ready to continue?\", header \"Checkpoint\", and options labeled \"Yes\" and \"No\". After I answer, reply with one short sentence acknowledging my answer and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Use the ask_user_question tool to ask me exactly one question with id \"checkpoint\", question \"Ready to continue?\", header \"Checkpoint\", and options labeled \"Yes\" and \"No\". After I answer, reply with one short sentence acknowledging my answer and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
 {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable.\n\nApproval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable."},{"name":"approval:policy","text":"Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}]},"role":"user","id":"{{message:2}}"},"surfaceOp":"append"}
 {"type":"session/title","data":{"title":"Use the ask_user_question tool to","messageSeqs":[7],"source":{"kind":"fallback"}}}
 {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
 {"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash","contextWindow":128000}}
-{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Interjection: include the word BANANA in your final reply."}],"source":{"kind":"user","rpcId":"{{rpc:2}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:3}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Interjection: include the word BANANA in your final reply."}],"source":{"kind":"user","rpcId":"{{rpc:2}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:3}}"}]}}
 {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[],"outcome":"canceled"}}
-{"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"inserted":[{"content":[{"type":"text","text":"Interjection: include the word BANANA in your final reply."}],"source":{"kind":"user","rpcId":"{{rpc:2}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:3}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"inserted":[{"content":[{"type":"text","text":"Interjection: include the word BANANA in your final reply."}],"source":{"kind":"user","rpcId":"{{rpc:2}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:3}}"}]}}
 {"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"steering-question","name":"ask_user_question","arguments":"{\"questions\":[{\"id\":\"checkpoint\",\"question\":\"Ready to continue?\",\"header\":\"Checkpoint\",\"options\":[{\"label\":\"Yes\"},{\"label\":\"No\"}]}]}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:4}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":1788240429254,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788240429756,"index":0,"dt":[],"id":"steering-question","name":"ask_user_question","args":["{\"questions\":[{\"id\":\"checkpoint\",\"question\":\"Ready to continue?\",\"header\":\"Checkpoint\",\"options\":[{\"label\":\"Yes\"},{\"label\":\"No\"}]}]}"]},{"type":"chunk","time":1788240430258,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"steering-question","name":"ask_user_question","arguments":"{\"questions\":[{\"id\":\"checkpoint\",\"question\":\"Ready to continue?\",\"header\":\"Checkpoint\",\"options\":[{\"label\":\"Yes\"},{\"label\":\"No\"}]}]}"}}},{"type":"chunk","time":1788240430759,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":1788240431261,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
 {"type":"tool/call","data":{"turn":1,"step":1,"callId":"steering-question","name":"ask_user_question","arguments":"{\"questions\":[{\"id\":\"checkpoint\",\"question\":\"Ready to continue?\",\"header\":\"Checkpoint\",\"options\":[{\"label\":\"Yes\"},{\"label\":\"No\"}]}]}"}}
 {"type":"tool/result","data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"steering-question"},"content":[{"type":"tool-result","toolCallId":"steering-question","content":[{"type":"text","text":"{\"answers\":[{\"id\":\"checkpoint\",\"selected\":[\"Yes\"]}]}"}],"isError":false}],"role":"user","id":"{{message:5}}"}},"sourceEventSeqs":[16],"surfaceOp":"append"}
 {"type":"step/end","data":{"turn":1,"step":1}}
 {"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","data":{"turn":1,"step":2}}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Interjection: include the word BANANA in your final reply."}],"source":{"kind":"user","rpcId":"{{rpc:2}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:3}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Interjection: include the word BANANA in your final reply."}],"source":{"kind":"user","rpcId":"{{rpc:2}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:3}}"},"surfaceOp":"append"}
 {"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"Great, let's move forward. BANANA!"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:6}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":1788240432201,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":1788240432703,"index":0,"dt":[],"texts":["Great, let's move forward. BANANA!"]},{"type":"chunk","time":1788240433206,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"Great, let's move forward. BANANA!"}}},{"type":"chunk","time":1788240433708,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":1788240434210,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
 {"type":"step/end","data":{"turn":1,"step":2}}
 {"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/snapshots/web/steering/settled-expanded.expected.md b/snapshots/web/steering/settled-expanded.expected.md
index 5c2738c768..fc4fa021e5 100644
--- a/snapshots/web/steering/settled-expanded.expected.md
+++ b/snapshots/web/steering/settled-expanded.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -43,7 +45,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -54,4 +56,9 @@
   - img
 - button "0% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 0% Input 20 tok · Output 10 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "30 tok · Cache hit 0%":
+  - img
+  - text: 30 tokCache hit 0%
diff --git a/snapshots/web/steering/settled.expected.md b/snapshots/web/steering/settled.expected.md
index 237bab0dfc..0ff456ca8a 100644
--- a/snapshots/web/steering/settled.expected.md
+++ b/snapshots/web/steering/settled.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -35,7 +37,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -46,4 +48,9 @@
   - img
 - button "0% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 0% Input 20 tok · Output 10 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "30 tok · Cache hit 0%":
+  - img
+  - text: 30 tokCache hit 0%
diff --git a/snapshots/web/subagent-conversation/nested.expected.md b/snapshots/web/subagent-conversation/nested.expected.md
index e5d8498557..1ed0fc0b02 100644
--- a/snapshots/web/subagent-conversation/nested.expected.md
+++ b/snapshots/web/subagent-conversation/nested.expected.md
@@ -8,6 +8,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
diff --git a/snapshots/web/subagent-conversation/ui-expanded.expected.md b/snapshots/web/subagent-conversation/ui-expanded.expected.md
index 37e05fa0d0..92e5e2c31a 100644
--- a/snapshots/web/subagent-conversation/ui-expanded.expected.md
+++ b/snapshots/web/subagent-conversation/ui-expanded.expected.md
@@ -11,6 +11,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -70,7 +72,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment" [disabled]:
@@ -78,4 +80,9 @@
 - 'button "Access mode, current: Custom"': Custom
 - button "6% of context used"
 - button "Send message" [disabled]
-- text: 2 turns · 2 steps LLM {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 99% Input 15.6K tok · Output 158 tok
+- button "2 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 2 turns 2 steps{{throughput}} tok/s
+- button "15.7K tok · Cache hit 99%":
+  - img
+  - text: 15.7K tokCache hit 99%
diff --git a/snapshots/web/subagent-conversation/ui.expected.md b/snapshots/web/subagent-conversation/ui.expected.md
index f4f25c4224..ec7b77fe58 100644
--- a/snapshots/web/subagent-conversation/ui.expected.md
+++ b/snapshots/web/subagent-conversation/ui.expected.md
@@ -11,6 +11,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -58,7 +60,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment" [disabled]:
@@ -66,4 +68,9 @@
 - 'button "Access mode, current: Custom"': Custom
 - button "6% of context used"
 - button "Send message" [disabled]
-- text: 2 turns · 2 steps LLM {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 99% Input 15.6K tok · Output 158 tok
+- button "2 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 2 turns 2 steps{{throughput}} tok/s
+- button "15.7K tok · Cache hit 99%":
+  - img
+  - text: 15.7K tokCache hit 99%
diff --git a/snapshots/web/subagent-interrupt/offline-composer.expected.md b/snapshots/web/subagent-interrupt/offline-composer.expected.md
index b34acde2d7..e7f7483bc3 100644
--- a/snapshots/web/subagent-interrupt/offline-composer.expected.md
+++ b/snapshots/web/subagent-interrupt/offline-composer.expected.md
@@ -8,6 +8,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
diff --git a/snapshots/web/turn-tail-actions/completed.expected.md b/snapshots/web/turn-tail-actions/completed.expected.md
index ed25b8d556..4f9b0b72f3 100644
--- a/snapshots/web/turn-tail-actions/completed.expected.md
+++ b/snapshots/web/turn-tail-actions/completed.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -35,7 +37,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -46,4 +48,9 @@
   - img
 - button "6% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 50% Input 15.7K tok · Output 112 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "15.8K tok · Cache hit 50%":
+  - img
+  - text: 15.8K tokCache hit 50%
diff --git a/snapshots/web/turn-tail-actions/focused.expected.md b/snapshots/web/turn-tail-actions/focused.expected.md
index 0c2c806aad..2108bafd30 100644
--- a/snapshots/web/turn-tail-actions/focused.expected.md
+++ b/snapshots/web/turn-tail-actions/focused.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -48,7 +50,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -59,4 +61,9 @@
   - img
 - button "6% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 50% Input 15.7K tok · Output 112 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "15.8K tok · Cache hit 50%":
+  - img
+  - text: 15.8K tokCache hit 50%
diff --git a/snapshots/web/turn-tail-actions/running.expected.md b/snapshots/web/turn-tail-actions/running.expected.md
index 502147691d..d4fced7fe3 100644
--- a/snapshots/web/turn-tail-actions/running.expected.md
+++ b/snapshots/web/turn-tail-actions/running.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -32,7 +34,7 @@
   - text: Bash Print alpha to stdout
 - paragraph: partial
 - status: Deep diving...
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -43,4 +45,9 @@
   - img
 - button "6% of context used"
 - button "Stop generating"
-- text: 1 turns · 1 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 0% Input 7.8K tok · Output 109 tok
+- button "1 turns 1 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 1 steps{{throughput}} tok/s
+- button "7.9K tok · Cache hit 0%":
+  - img
+  - text: 7.9K tokCache hit 0%
diff --git a/snapshots/web/turn-tail-actions/session.v2.jsonl b/snapshots/web/turn-tail-actions/session.v2.jsonl
index ff109593c5..e5715a20e8 100644
--- a/snapshots/web/turn-tail-actions/session.v2.jsonl
+++ b/snapshots/web/turn-tail-actions/session.v2.jsonl
@@ -2,11 +2,11 @@
 {"type":"permission/preset","data":{"preset":"workspace-write"}}
 {"type":"sandbox/mode","data":{"mode":"workspace-write"}}
 {"type":"approval/policy","data":{"policy":"ask"}}
-{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Begin your reply with the plain sentence \"Reading the workspace now.\" as text, and in that same message call the bash tool with the command \"echo alpha\". After the tool result, reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Begin your reply with the plain sentence \"Reading the workspace now.\" as text, and in that same message call the bash tool with the command \"echo alpha\". After the tool result, reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"}]}}
 {"type":"turn/start","data":{"turn":1}}
 {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","data":{"turn":1,"step":1}}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Begin your reply with the plain sentence \"Reading the workspace now.\" as text, and in that same message call the bash tool with the command \"echo alpha\". After the tool result, reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Begin your reply with the plain sentence \"Reading the workspace now.\" as text, and in that same message call the bash tool with the command \"echo alpha\". After the tool result, reply with the single word DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
 {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable.\n\nApproval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable."},{"name":"approval:policy","text":"Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}]},"role":"user","id":"{{message:2}}"},"surfaceOp":"append"}
 {"type":"session/title","data":{"title":"Begin your reply with the","messageSeqs":[7],"source":{"kind":"fallback"}}}
 {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
diff --git a/snapshots/web/turn-tail-actions/settled.expected.md b/snapshots/web/turn-tail-actions/settled.expected.md
index 5aff82d1a1..fd6de1de07 100644
--- a/snapshots/web/turn-tail-actions/settled.expected.md
+++ b/snapshots/web/turn-tail-actions/settled.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -34,7 +36,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -45,4 +47,9 @@
   - img
 - button "6% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 0% Input 7.8K tok · Output 109 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "7.9K tok · Cache hit 0%":
+  - img
+  - text: 7.9K tokCache hit 0%
diff --git a/snapshots/web/turn-tail-actions/usage-expanded.expected.md b/snapshots/web/turn-tail-actions/usage-expanded.expected.md
index a01ee4fd78..916569dc9c 100644
--- a/snapshots/web/turn-tail-actions/usage-expanded.expected.md
+++ b/snapshots/web/turn-tail-actions/usage-expanded.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -35,7 +37,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -46,4 +48,9 @@
   - img
 - button "6% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 50% Input 15.7K tok · Output 112 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "15.8K tok · Cache hit 50%":
+  - img
+  - text: 15.8K tokCache hit 50%
diff --git a/snapshots/web/web-search-round/session.v2.jsonl b/snapshots/web/web-search-round/session.v2.jsonl
index 25abee8559..d3067bbfc7 100644
--- a/snapshots/web/web-search-round/session.v2.jsonl
+++ b/snapshots/web/web-search-round/session.v2.jsonl
@@ -2,11 +2,11 @@
 {"type":"permission/preset","data":{"preset":"workspace-write"}}
 {"type":"sandbox/mode","data":{"mode":"workspace-write"}}
 {"type":"approval/policy","data":{"policy":"ask"}}
-{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use web_search once with queries [\"DeepSeek Harness snapshot search\",\"DeepSeek Harness multi-query search\"]. Then reply exactly SEARCH_DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use web_search once with queries [\"DeepSeek Harness snapshot search\",\"DeepSeek Harness multi-query search\"]. Then reply exactly SEARCH_DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"}]}}
 {"type":"turn/start","data":{"turn":1}}
 {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","data":{"turn":1,"step":1}}
-{"type":"user/message","data":{"content":[{"type":"text","text":"Use web_search once with queries [\"DeepSeek Harness snapshot search\",\"DeepSeek Harness multi-query search\"]. Then reply exactly SEARCH_DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"Asia/Shanghai"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Use web_search once with queries [\"DeepSeek Harness snapshot search\",\"DeepSeek Harness multi-query search\"]. Then reply exactly SEARCH_DONE and stop."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
 {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable.\n\nApproval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable."},{"name":"approval:policy","text":"Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}]},"role":"user","id":"{{message:2}}"},"surfaceOp":"append"}
 {"type":"session/title","data":{"title":"Use web_search once with queries","messageSeqs":[7],"source":{"kind":"fallback"}}}
 {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
diff --git a/snapshots/web/web-search-round/ui.expected.md b/snapshots/web/web-search-round/ui.expected.md
index 5ab42e660c..1aa9b33fc1 100644
--- a/snapshots/web/web-search-round/ui.expected.md
+++ b/snapshots/web/web-search-round/ui.expected.md
@@ -6,6 +6,8 @@
   - button "Session log":
     - text: Session log
     - img
+  - button "Open the sidebar":
+    - img
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
@@ -40,7 +42,7 @@
   - img
   - text: Ran for {{duration}}
 - text: {{clock}}
-- textbox "Message or run a task... / commands, @ files or sessions"
+- textbox "Message or run a task, / commands, @ files or sessions"
 - button "Commands":
   - img
 - button "Add attachment":
@@ -51,4 +53,9 @@
   - img
 - button "0% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 0% Input 22 tok · Output 7 tok
+- button "1 turns 2 steps · {{throughput}} tok/s":
+  - img
+  - text: 1 turns 2 steps{{throughput}} tok/s
+- button "29 tok · Cache hit 0%":
+  - img
+  - text: 29 tokCache hit 0%
diff --git a/tsconfig.base.json b/tsconfig.base.json
index d3900f6cba..04c09303a1 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -154,6 +154,18 @@
       "@deepseek-ai/dsh-client-ui-slots": ["./packages/client/ui-slots/src"],
       "@deepseek-ai/dsh-client-ui-attachment": ["./packages/client/ui-attachment/src"],
       "@deepseek-ai/dsh-client-ui-primitives": ["./packages/client/ui-primitives/src"],
+      "@deepseek-ai/dsh-client-ui-dockkit": ["./packages/client/ui-dockkit/src"],
+      "@deepseek-ai/dsh-client-ui-sidebar-right": ["./packages/client/ui-sidebar-right/src"],
+      "@deepseek-ai/dsh-client-ui-sidebar-right/client": ["./packages/client/ui-sidebar-right/src/client"],
+      "@deepseek-ai/dsh-client-ui-sidebar-textpreview": ["./packages/client/ui-sidebar-textpreview/src"],
+      "@deepseek-ai/dsh-client-ui-sidebar-textpreview/client": ["./packages/client/ui-sidebar-textpreview/src/client"],
+      "@deepseek-ai/dsh-api-workspace-files": ["./packages/api/workspace-files/src"],
+      "@deepseek-ai/dsh-api-workspace-files/types": ["./packages/api/workspace-files/src/types.ts"],
+      "@deepseek-ai/dsh-api-workspace-files/client": ["./packages/api/workspace-files/src/client/index.ts"],
+      "@deepseek-ai/dsh-client-resources": ["./packages/client/resources/src"],
+      "@deepseek-ai/dsh-client-resources/client": ["./packages/client/resources/src/client"],
+      "@deepseek-ai/dsh-client-ui-sidebar-files": ["./packages/client/ui-sidebar-files/src"],
+      "@deepseek-ai/dsh-client-ui-sidebar-files/client": ["./packages/client/ui-sidebar-files/src/client"],
       "@deepseek-ai/dsh-client-store": ["./packages/client/store/src/index.ts"],
       "@deepseek-ai/dsh-client-ui-renderer": ["./packages/client/ui-renderer/src"],
       "@deepseek-ai/dsh-client-ui-renderer/client": ["./packages/client/ui-renderer/src/client"],
diff --git a/tsconfig.client.json b/tsconfig.client.json
index b313547c81..b9a2a55382 100644
--- a/tsconfig.client.json
+++ b/tsconfig.client.json
@@ -84,6 +84,10 @@
     { "path": "./packages/client/ui-reference" },
     { "path": "./packages/client/ui-subagent" },
     { "path": "./packages/experimental/client-ui-agent-team" },
+    { "path": "./packages/client/ui-dockkit" },
+    { "path": "./packages/client/ui-sidebar-right" },
+    { "path": "./packages/client/ui-sidebar-textpreview" },
+    { "path": "./packages/client/ui-sidebar-files" },
     { "path": "./packages/client/ui-jobs" },
     { "path": "./packages/client/ui-schedule" },
     { "path": "./packages/client/ui-directory-picker-browse" },
@@ -107,6 +111,8 @@
     { "path": "./packages/client/locale" },
     { "path": "./packages/client/ui-renderer" },
     { "path": "./packages/client/ui-session" },
+    { "path": "./packages/client/resources" },
+    { "path": "./packages/api/workspace-files/tsconfig.client.json" },
     { "path": "./packages/client/web" },
     { "path": "./packages/context/file-reference" },
     { "path": "./apps/web" }
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 7fef53ebf8..1c68bd9d0b 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -89,6 +89,7 @@
     "apps/web/tests/turn-tail-actions.e2e.ts",
     "apps/web/tests/goal-multi-turn-actions.e2e.ts",
     "apps/web/tests/agent-team-panel.e2e.ts",
+    "apps/web/tests/sidebar-right.e2e.ts",
     "apps/web/tests/chat-scroll-fixture.ts",
     "apps/web/tests/chat-scroll-contract.e2e.ts",
     "apps/web/tests/chat-long-interactions.e2e.ts",
@@ -162,6 +163,7 @@
     { "path": "./packages/api/gateway/tsconfig.host.json" },
     { "path": "./packages/api/remotes/tsconfig.host.json" },
     { "path": "./packages/api/session-controller/tsconfig.host.json" },
+    { "path": "./packages/api/workspace-files/tsconfig.host.json" },
     { "path": "./packages/api/settings-controller" },
     { "path": "./packages/api/workspace-controller/tsconfig.host.json" },
     { "path": "./packages/typert/loader" },
diff --git a/website/docs.ts b/website/docs.ts
index 3a54d64cc3..c9823653d9 100644
--- a/website/docs.ts
+++ b/website/docs.ts
@@ -347,6 +347,8 @@ const subsystemGroups = [
     ['web-client.md', 'Web Client 架构', 'Web Client architecture'],
     ['client-modules.md', '客户端模块', 'Client modules'],
     ['slots.md', '客户端 Slots', 'Client slots'],
+    ['client-resources.md', '客户端资源', 'Client resources'],
+    ['sidebar-right.md', '右侧 Sidebar', 'Right Sidebar'],
     ['conversation.md', 'Conversation 组装', 'Conversation assembly'],
     ['typert.md', 'Typert', 'Typert'],
     ['storage.md', '存储', 'Storage'],