Merge remote-tracking branch 'origin/master' into feature/subagent-policy-inheritance

# Conflicts: # .agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml # examples/acp-agent/tests/acp.snapshot.ts
2026-07-26 16:12:38 +08:00
parent 6abb5eebc2 785efe03e3
commit be5f76b6c6
1297 changed files with 43626 additions and 9926 deletions
--- a/packages/README.i18n.yaml
+++ b/packages/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: d7427c3f9892f56185cc1175245f14a6ccea0d25
+README.zh.md: 6894aa7333f6ba4bc5723871fb77c18b5fb518a1
--- a/packages/README.md
+++ b/packages/README.md
@@ -1,5 +1,7 @@
 # Packages

+English | [中文](README.zh.md)
+
 Packages use the `@deepseek-ai/dsh-*` scope. Each is a Cordis `Service` subclass or function plugin; contributions use `ctx.effect()`, `ctx.on()`, or `ctx.waterfall()`. Authoring rules: [package](AGENTS.md) and [root](../AGENTS.md#conventions).

 ## Hierarchy
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -0,0 +1,56 @@
+# 包
+
+[English](README.md) | 中文
+
+所有包都使用 `@deepseek-ai/dsh-*` scope。每个包都是 Cordis `Service` 子类或函数插件；所有贡献通过 `ctx.effect()`、`ctx.on()` 或 `ctx.waterfall()` 注册。编写规则见[包](AGENTS.md)与[根规则](../AGENTS.md#conventions)。
+
+## 层级结构
+
+包位于 `packages/<group>/<pkg>/`；组是容器，包名仍为 `@deepseek-ai/dsh-<pkg>`。**每个组 README 是规范的包／ctx 键映射。**
+
+| 组 | 职责 | 发布预期 |
+|---|---|---|
+| [`core/`](core/README.md) | 产品 API 主干：会话、提示词、工具、agent（智能体）服务与具体循环 | 产品：稳定表面 |
+| [`goal/`](goal/README.md) | 持久化的同会话 goal 状态与生命周期 | 产品：稳定表面 |
+| [`llm/`](llm/README.md) | LLM（大语言模型）能力系列：抽象服务 + 提供方适配器 | 产品：稳定表面 |
+| [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定表面 |
+| [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定表面 |
+| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：面向模型所写程序的运行时 seam + worker 线程后端 | 产品：稳定表面 |
+| [`sandbox/`](sandbox/README.md) | 进程限制 seam；bwrap/Landlock/Seatbelt 后端 | 产品：稳定表面 |
+| [`fs/`](fs/README.md) | 文件系统能力系列：seam、本地实现、面向模型的文件工具、bash 后端发现工具 | 产品：稳定表面 |
+| [`lsp/`](lsp/README.md) | LSP 能力系列：seam、通用 stdio 提供方和 `lsp` 工具 | 产品：稳定表面 |
+| [`skill/`](skill/README.md) | Skill（技能）能力系列：提供方注册表、本地提供方和面向模型的目录／加载器 | 产品：稳定表面 |
+| [`compact/`](compact/README.md) | 压缩（compaction）能力系列：抽象 seam + 基础后端（工具延后） | 产品：稳定表面 |
+| [`context/`](context/README.md) | 模型可见请求上下文，包括 workspace 指令和时间上下文 | 产品：稳定表面 |
+| [`subagent/`](subagent/README.md) | Subagent 能力系列：提供方注册表 seam 和面向模型的委托工具 | 产品：稳定表面 |
+| [`tasks/`](tasks/README.md) | 通用后台任务运行时和面向模型的 `task_*` 控制工具 | 产品：稳定表面 |
+| [`workflow/`](workflow/README.md) | 工作流能力系列：脚本引擎 seam、worker 线程引擎、面向模型的 `workflow` 与新 agent `ralph` 工具 | 产品：稳定表面 |
+| [`web/`](web/README.md) | Web 能力系列：seam、搜索／获取提供方实现和面向模型的 Web 工具 | 产品：稳定表面 |
+| [`spill/`](spill/README.md) | 溢出能力系列：存储 seam、本地实现、工具结果溢出策略 | 产品：稳定表面 |
+| [`todo/`](todo/README.md) | Todo／规划系列：面向模型的 `todo_write` 工具 | 产品：稳定表面 |
+| [`plan/`](plan/README.md) | Plan 协作状态，提供直接进入命令与经评审的退出 | 产品：稳定表面 |
+| [`timeout/`](timeout/README.md) | 工具调用超时策略：`tools/execute` 截止时间强制执行器 | 产品：稳定表面 |
+| [`guard/`](guard/README.md) | 循环卫生守卫：建议性重复调用提醒 | 产品：稳定表面 |
+| [`cordis/`](cordis/README.md) | 自指运行时工具集：检查实时运行时的插件与服务，挂载／卸载模型所写插件（[设计](../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)） | 产品：稳定表面 |
+| [`hooks/`](hooks/README.md) | 钩子桥接 + 共享 Claude Code／Codex 协议格式库 | 产品：稳定表面 |
+| [`session-persistence/`](session-persistence/README.md) | 持久化能力系列：seam + JSONL/SQLite 后端 | 产品：稳定表面 |
+| [`session-query/`](session-query/README.md) | 会话检索系列：逻辑语料库、有界读取、血缘、事件关系、语义过滤和 SQLite 全文搜索 | 产品：稳定表面 |
+| [`session-title/`](session-title/README.md) | 日志支撑的会话标题：回退服务、共享 LLM 策略和选用提供方 | 产品：稳定表面 |
+| [`storage/`](storage/README.md) | 非会话存储中枢 + 后端 + 领域形式 | 产品：稳定表面 |
+| [`workspace/`](workspace/README.md) | Workspace 实体 | 产品：稳定表面 |
+| [`sdk/`](sdk/README.md) | 项目 SDK 工具 | 产品：稳定表面 |
+| [`acp/`](acp/README.md) | 仅面向自动化的 Agent Client Protocol 服务器 | 产品：稳定表面 |
+| [`ui/`](ui/README.md) | 人类／客户端集成：TUI 与 JSON-RPC、批准／交互 seam、用户问答工具 | 产品：稳定表面 |
+| [`examples/`](examples/README.md) | 演示组合包（agent-spine + TUI/CLI/ACP/JSON-RPC bin），由叶节点加载 | 支持：示例基础设施 |
+| [`support/`](support/README.md) | 支持基础设施（testkit、不变式、回放、Loader 冒烟测试） | 支持：兼容性预期较低 |
+| [`util/`](util/README.md) | 组间共享的低层零依赖工具（`Branded<B>`、Harness home／路径辅助函数、超时、保留策略） | 支持：小型、稳定、无 harness 依赖 |
+
+组用于区分产品 API 与支持基础设施。新包加入现有组；新组则更新其 README 和此表。
+
+## 依赖
+
+依赖图由工具生成：[docs/module-graph.md](../docs/module-graph.md)（`pnpm run gen-module-graph`，CI 中有新鲜度门禁）。
+
+**扩展插件依赖接口，绝不依赖具体循环。** `dsh-agent-loop` 可替换；UI、钩子和工具插件使用 `dsh-agent`。包括 `dsh-agent-spine-demo` 在内的组合包可以依赖主干插件。能力拆分为接口／实现／消费方包；详见[能力 seam](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)。
+
+包 README 覆盖用途、API、扩展点和[模型体验](../docs/cookbook/adding-a-package.md#4-write-the-package-readme)；列入模型无关[省略允许清单](../scripts/verify-package-readme-model-experience.ts)的包除外。它们还要包含 `## Known Limitations and Deferred Work`，或使用其[允许清单](../scripts/verify-package-readme-limitations.ts)。
--- a/packages/acp/README.i18n.yaml
+++ b/packages/acp/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: 326615210e5cfc39004fc5ab7462623089ac4126
+README.zh.md: 9999ecdd019501c3f501a6c69fab5e0ccfaf555c
--- a/packages/acp/README.md
+++ b/packages/acp/README.md
@@ -1,5 +1,7 @@
 # acp/ — Agent Client Protocol automation

+English | [中文](README.zh.md)
+
 The ACP group exposes harness agents to programmatic clients. It is an interoperability transport, not a presentation or human-interaction layer.

 | Package | Role |
--- a/packages/acp/README.zh.md
+++ b/packages/acp/README.zh.md
@@ -0,0 +1,11 @@
+# acp/：Agent Client Protocol 自动化
+
+[English](README.md) | 中文
+
+ACP（Agent Client Protocol）组将 harness 中的 agent（智能体）公开给程序化客户端。它是互操作传输层，而非展示层或人机交互层。
+
+| 包 | 职责 |
+|---|---|
+| [`acp/`](acp/README.md) | 仅面向自动化的 ACP 服务器：新文本会话、已提交的 assistant 输出、机器权限策略、取消和由连接拥有的清理。 |
+
+与之匹配的进程外 subagent 客户端仍位于 [`subagent/subagent-acp`](../subagent/subagent-acp/README.md)，因为它实现 subagent 提供方接口；任意 ACP 客户端都可以驱动同一服务器契约。
--- a/packages/acp/acp/README.i18n.yaml
+++ b/packages/acp/acp/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: 1b188b994d17ce56e8d5df019ddef755338fcc88
+README.zh.md: f8abe9e45a5efffa436513f7d4a931c69c624b84
--- a/packages/acp/acp/README.md
+++ b/packages/acp/acp/README.md
@@ -1,5 +1,7 @@
 # @deepseek-ai/dsh-acp

+English | [中文](README.zh.md)
+
 Automation-only [Agent Client Protocol](https://agentclientprotocol.com) server over JSON-RPC stdio. Programmatic clients create fresh harness agents, send text prompts, collect committed assistant text, resolve one-shot permission requests by policy, and cancel work. The primary in-repository client is [`dsh-subagent-acp`](../../subagent/subagent-acp/README.md).

 This package is a transport adapter, not a UI integration or a capability seam. It does not expose editor navigation, transcript replay, commands, modes, configuration pickers, elicitation, reasoning, plans, titles, or tool presentation. Interactive rendering and human questions belong to the web and TUI modules.
--- a/packages/acp/acp/README.zh.md
+++ b/packages/acp/acp/README.zh.md
@@ -0,0 +1,79 @@
+# @deepseek-ai/dsh-acp
+
+[English](README.md) | 中文
+
+通过 JSON-RPC stdio 提供的仅面向自动化的 [Agent Client Protocol](https://agentclientprotocol.com) 服务器。程序化客户端可以创建新 harness agent（智能体）、发送文本提示词、收集已提交的 assistant 文本、通过策略解决一次性权限请求并取消工作。仓库中的主要客户端是 [`dsh-subagent-acp`](../../subagent/subagent-acp/README.md)。
+
+此包（package）是传输适配器，而非 UI 集成或能力 seam。它不公开编辑器导航、transcript（文本记录）回放、命令、mode、配置选择器、信息征集、推理、计划、标题或工具展示。交互渲染与人类问题属于 Web 和 TUI 模块。
+
+## 插件
+
+`apply(ctx, config)` 在 stdin/stdout 上打开 `AgentSideConnection` 并驱动 `ctx.agents`。Stdout 专用于协议帧。
+
+| 配置 | 默认值 | 含义 |
+|---|---|---|
+| `provider` | 无 | 每个已创建 agent 的初始提供方路由。 |
+| `model` | 无 | 每个已创建 agent 的初始模型。 |
+
+两个字段都是可选的，以便由另一个 agent/request 监听器提供目标。可运行 ACP 组合同时要求两者。
+
+## 协议契约
+
+| 方法 | 行为 |
+|---|---|
+| `initialize` | 协商受支持的版本，并仅公布基线提示词（无图像、音频或嵌入上下文能力）。不公布会话、编辑器、终端、文件系统或 MCP 能力。 |
+| `authenticate` | 空操作，因为服务器不公布身份验证方法。 |
+| `session/new` | 使用绝对主 `cwd` 创建新 agent；接受空的 `additionalDirectories` 和 `mcpServers`，拒绝非空值。 |
+| `session/prompt` | 连接文本块，将基线资源链接渲染为带方括号的文本引用，拒绝空输入或超出基线的输入，每个会话只允许一个正在处理的请求，并从该请求拥有的持久 `turn/end` 结算。 |
+| `session/cancel` | 仅取消被定址的 agent，并将其待处理提示词结算为 `cancelled`；未知 id 为空操作。 |
+| `session/update` | 为每个非空文本块发出一个 `agent_message_chunk`；这些文本块来自已提交的 `assistant/message`。省略原始增量和非消息事件。 |
+| `session/request_permission` | 为携带工具调用 id 的桥接层所有批准请求提供一次性允许／拒绝选项。客户端可以自动回答。 |
+
+一个连接可以拥有多个会话。桥接层使用带品牌的 session id 为记录建键，并在路由事件或权限请求前检查精确的 agent 标识。每个会话都有独立的提示词槽位、workspace、取消路径和 disposer。
+
+已提交消息输出有意以逐 token 延迟换取干净的自动化结果。未提交的提供方分片和重试尝试无法泄漏部分文本；推理与工具活动仍保留在会话日志中，以便其他界面观测。
+
+## 生命周期
+
+客户端断开与 Cordis 释放共用同一个记忆化清理流程。桥接层先拒绝新会话和提示词，结算待处理提示词，然后并行释放所有已拥有的 agent handle，并等待它们的循环／会话清理完成。因此，仅 ACP 的插件重载不会遗留 agent。
+
+## 运行
+
+`pnpm --dir /path/to/deepseek-harness run demo:acp` 启动仓库的自动化服务器组合。父 harness 可以通过 [`@deepseek-ai/dsh-subagent-acp`](../../subagent/subagent-acp/README.md) spawn 它；其他 ACP 客户端只需上述核心方法。
+
+## 模型体验
+
+### 提示词文本
+
+#### 模型所见内容
+
+`session/prompt` 文本块会原样连接为一条用户消息；基线资源链接会在该消息中表示为带方括号的 `[resource_link name=… uri=…]` 引用，模型可以使用自身工具打开它。协议元数据、客户端能力、权限选择和 session id 绝不进入模型请求。
+
+#### Token 影响
+
+提示词 token 取决于数据，并保留在该会话的历史中直到压缩。并发 ACP 会话保留独立上下文。
+
+#### KV Cache 影响
+
+仅追加；新用户消息位于可复用请求前缀之后，不会使先前缓存条目失效。
+
+### 权限决策
+
+#### 模型所见内容
+
+没有直接内容。拥有该决策的工具通过常规工具结果路径记录允许、拒绝、取消或不可用结果。
+
+#### Token 影响
+
+只有拥有该决策的工具结果会贡献 token。
+
+#### KV Cache 影响
+
+通过所属工具结果仅追加。
+
+## 已知限制与延后工作
+
+- **仅新会话**：不支持加载、列出、恢复、删除和 fork。
+- **仅基线提示词和一个 workspace**：图像、音频、嵌入资源、非空附加目录和 MCP 服务器都会被拒绝；资源链接会被展平为文本引用，而不是已获取内容。
+- **仅已提交答案**：实时进度、推理、工具活动、计划、标题和用量不上线。
+- **连接拥有的生命期**：一个连接会释放其所有会话；尚未实现每会话关闭。
--- a/packages/bash/README.i18n.yaml
+++ b/packages/bash/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: 08b36270800cdd79c82d6781bbfb2e12e2dc2060
+README.zh.md: a98506a6cdf41e5b298b40e1b8e1faf0c4c917d2
--- a/packages/bash/README.md
+++ b/packages/bash/README.md
@@ -1,5 +1,7 @@
 # bash/ — bash capability family

+English | [中文](README.zh.md)
+
 The canonical three-package capability seam (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract executor interface, concrete implementations, and the model-facing tool that consumes it. All **product** packages.

 | Package | Role | ctx key |
--- a/packages/bash/README.zh.md
+++ b/packages/bash/README.zh.md
@@ -0,0 +1,14 @@
+# bash/：bash 能力家族
+
+[English](README.md) | 中文
+
+规范的三包能力 seam（见[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：抽象执行器接口、具体实现，以及消费该接口的面向模型工具。这些全是**产品** 包。
+
+| 包 | 职责 | ctx key |
+|---|---|---|
+| `bash/` | 抽象 bash 执行器 seam（接口 + 词汇；沙箱结果事实携带 [`sandbox/`](../sandbox/README.md) seam 的模式／强制执行词汇） | `ctx.bash` |
+| `bash-local/` | 本地子进程 `BashExecutor` 实现 | （注册 `ctx.bash`） |
+| `bash-sandbox/` | 消费沙箱的 `BashExecutor`（通过 `ctx.sandbox` 包装每个命令 argv，标记拒绝／强制执行事实；扩展 `bash-local` 的机制） | （注册 `ctx.bash`） |
+| `tool-bash/` | 面向模型的 `bash` schema；后台进程注册到通用 [`tasks/`](../tasks/README.md) 运行时 | （注册到 `ctx.tools`） |
+
+接口位于 `bash/bash/`。以 `bash-sandbox` 替换 `bash-local`，同时不改动接口或工具，正是这种拆分存在的意义：叶级 `cordis.yml` 选择一个执行器配置项；受限实现还需选择一个 `ctx.sandbox` 提供方配置项（见 [acp-agent 示例的默认组合](../../examples/acp-agent/)）。
--- a/packages/bash/bash-local/README.i18n.yaml
+++ b/packages/bash/bash-local/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: 1668f33e8acf6d749d4d3753478c12d48a19ac3c
+README.zh.md: 0e0a4ad41b532e39f6f2470aa981a08b6d6230c1
--- a/packages/bash/bash-local/README.md
+++ b/packages/bash/bash-local/README.md
@@ -1,5 +1,7 @@
 # @deepseek-ai/dsh-bash-local

+English | [中文](README.zh.md)
+
 Local-subprocess implementation of the `@deepseek-ai/dsh-bash` executor seam: `LocalBashExecutor` spawns `bash -c <command>` per call in its own process group, collects bounded output with size-limited full-stream spill files, and escalates kills SIGTERM→SIGKILL across the whole group.

 The package root exports the default and named `LocalBashExecutor` plugin plus its `Config`; subprocess plumbing stays internal to the implementation package.
--- a/packages/bash/bash-local/README.zh.md
+++ b/packages/bash/bash-local/README.zh.md
@@ -0,0 +1,49 @@
+# @deepseek-ai/dsh-bash-local
+
+[English](README.md) | 中文
+
+`@deepseek-ai/dsh-bash` 执行器 seam 的本地子进程实现：`LocalBashExecutor` 每次调用都会在独立进程组中 spawn `bash -c <command>`，收集有界输出，并用限制大小的完整流 spill 文件保留超量内容，随后针对整个进程组从 SIGTERM 逐步升级为 SIGKILL。
+
+包根目录导出默认与具名的 `LocalBashExecutor` 插件及其 `Config`；子进程管道细节保留在该实现包内部。
+
+## 配置
+
+```yaml
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+  config:
+    cwd: /path/to/workspace   # default: process.cwd()
+    timeoutMs: 120000          # default foreground timeout
+    maxTimeoutMs: 600000       # cap for per-call overrides
+    maxOutputBytes: 64000      # per-stream in-memory cap; overflow spills to disk
+    maxSpillBytes: 67108864    # per-stream full-output spill cap
+    graceMs: 3000              # kill escalation and post-exit pipe-drain grace
+```
+
+## 行为（以及设计来源）
+
+设计时调研了 Claude Code、OpenCode、Codex 和 pi 的 bash 工具，主要取舍如下：
+
+- **每次调用都 spawn，不保留 shell 状态**：每次调用都启动新的非登录 `bash -c`（行为确定，不读取 rc 文件）。调研的四种工具均会每次调用单独 spawn。`XXX(stateful-shell)` 位于 `src/run.ts`，记录了两种已验证的有状态设计（Claude Code 仅持久化 cwd；Codex 使用 PTY exec 会话），供真实工作流程需要时采用。
+- **使用逐步升级终止整个进程组**：子进程使用 `detached` spawn（拥有独立进程组）；终止时先向该组发送 SIGTERM，经过 `graceMs` 宽限期后再发送 SIGKILL（默认 3 秒，沿用 OpenCode 的升级策略；管道与子 shell 会随父进程一起结束）。主 shell 退出后，继承的 stdout/stderr 管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地阻止命令结束。系统会容忍 ESRCH；脱离该组重新挂载的 daemon 仍可能存活，这与调研工具的局限相同。
+- **保留尾部的截断 + 有界 spill 文件**：输出超过 `maxOutputBytes` 后，内存中保留尾部（错误／结果通常聚集在末尾，沿用 pi/OpenCode 的理由），同时将完整流追加到临时文件，并在可用时报告该路径。前台 `BashExecRequest.stdoutMaxBytes` 可为某个受信任调用方提高单次 stdout 捕获预算；stderr 和后台任务仍使用 `maxOutputBytes`。某个流大于 `maxSpillBytes` 时，会丢弃已不完整的 spill，仅返回带截断标记的尾部。如果最终关闭 spill 时报告延迟写回失败，执行器同样不会公布路径，以免声称存在不完整的文件。
+- **适合模型的环境变量 + 凭证清理**：以 `process.env` 为基础，移除形似凭证的变量（`*KEY*`／`*SECRET*`／`*TOKEN*`）和所有环境中的 `DSH_*` 名称，再设置 `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat`（Codex 硬编码的集合），防止分页器与 ANSI 颜色破坏结果。spec 的普通 `env` 在清理后合并，但会拒绝 `DSH_*`；受管 `dshEnv` 会拒绝普通名称并最后合并，防止遗留嵌套 harness 身份。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。详见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) 与 [受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
+- **后台进程**：`start()` 会立即返回实时 `BashProcess` 句柄，不应用超时（Claude Code 在转为后台时会解除超时）；句柄的 `readOutput()` 使用全流字节偏移量进行增量读取；dispose 会终止每个运行中的进程并等待其退出。所有具有任务形态的事项（id、所有权、轮询、通知）都属于通用 [`ctx.tasks` 运行时](../../tasks/tasks/README.md)，工具层会在其中注册该句柄；本执行器不会接触会话或注册表。
+
+## 模型体验
+
+通过 `dsh-tool-bash` 间接影响；该工具会渲染此执行器有界的 stdout/stderr 尾部、后台进程增量、spill 文件路径与基础设施失败。
+
+#### KV Cache 影响
+
+不会直接失效；请求前缀变更由具名消费方负责。
+
+## 已知限制与暂缓事项
+
+- **自身不受约束**：此执行器始终以 harness 进程的权限运行命令；需要限制的部署可以组合 [`dsh-bash-sandbox`](../bash-sandbox/README.md)，每次调用的 allow/deny/ask 策略则属于 `tools/pre-execute`。
+- **没有持久 shell 或 PTY**：每次调用都启动新的非登录 `bash -c`；仅持久化 cwd 与交互式终端会话均继续暂缓，直到真实工作流程需要它们。
+- **仅支持 POSIX**：`bash` 二进制、独立进程组、进程组终止以及 SIGTERM→SIGKILL 升级都已硬编码；不支持 Windows。
+- **凭证清理依赖名称启发式规则**：只匹配 `*KEY*`／`*SECRET*`／`*TOKEN*`；名称不同的 secret（例如 `*PASSWORD*`）会继续传递，对误删变量引入白名单属于已记录的后续工作。
+- **不会删除已完成的 spill 文件**：有界的完整输出恢复文件（以及每个进程的私有 spill 目录）会在 OS tmpdir 下累积，直到外部机制进行清理；超大的不完整 spill 会被丢弃并立即尝试删除，但清理失败可能留下一个有界文件。
+
+原始进程处理位于 `src/run.ts`；`src/index.ts` 负责服务接线。
--- a/packages/bash/bash-sandbox/README.i18n.yaml
+++ b/packages/bash/bash-sandbox/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: ca77a9c626784b29145712535d69de4afbd3a697
+README.zh.md: c1a65ead539ef3930d70d27f2b176a5346daded3
--- a/packages/bash/bash-sandbox/README.md
+++ b/packages/bash/bash-sandbox/README.md
@@ -1,5 +1,7 @@
 # @deepseek-ai/dsh-bash-sandbox

+English | [中文](README.zh.md)
+
 Sandbox-consuming implementation of the [`@deepseek-ai/dsh-bash`](../bash/) executor seam. Load it **instead of** `@deepseek-ai/dsh-bash-local`, together with a [`ctx.sandbox`](../../sandbox/sandbox/) provider (e.g. [`@deepseek-ai/dsh-sandbox-local`](../../sandbox/sandbox-local/)) and a [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/) (which owns the default mode + workspace root, shared with the sandboxed filesystem) — no alternate tool plugin is needed; `dsh-tool-bash` detects the executor's `sandboxMode` capability and adds the escalation fields.

 The package root exports the default and named `SandboxBashExecutor` plugin plus its `Config`; quoting and result-classification helpers stay internal.
--- a/packages/bash/bash-sandbox/README.zh.md
+++ b/packages/bash/bash-sandbox/README.zh.md
@@ -0,0 +1,90 @@
+# @deepseek-ai/dsh-bash-sandbox
+
+[English](README.md) | 中文
+
+消费 [`@deepseek-ai/dsh-bash`](../bash/) 执行器 seam 的沙箱实现。加载它时，应**用它替代** `@deepseek-ai/dsh-bash-local`，并同时加载 [`ctx.sandbox`](../../sandbox/sandbox/) 提供方（例如 [`@deepseek-ai/dsh-sandbox-local`](../../sandbox/sandbox-local/)）及 [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/)；后者拥有默认模式 + 工作区根目录，并与受沙箱约束的文件系统共享这些设置。无需使用替代工具插件；`dsh-tool-bash` 会检测执行器的 `sandboxMode` 能力并添加升权字段。
+
+包根目录导出默认与具名的 `SandboxBashExecutor` 插件及其 `Config`；引号处理与结果分类 helper 保留在内部。
+
+每条命令的限制方式都是：把本执行器即将 spawn 的精确 `['bash', '-c', command]` argv 交给提供方，再 spawn 其返回的（已包装）argv。由哪种平台 runner 执行限制，以及是否有 runner 可用（必须快速失败并返回结构化 `SANDBOX_UNAVAILABLE` 错误，绝不能静默无约束运行），属于提供方职责；本包只拥有 bash 侧。
+
+| 模式 | 文件影响 |
+|---|---|
+| `read-only`（默认） | 任何位置都不可写（在 `/dev` 中只有 `/dev/null` 节点可写，因此 `>/dev/null` 仍可正常工作） |
+| `workspace-write` | 只能写入 `workspaceRoot` + `/tmp`（在 bwrap 下为临时目录，在 Landlock 下为宿主 `/tmp`，在 Seatbelt 下为 `/private/tmp` 加每用户临时目录） |
+| `danger-full-access` | 不作限制；绝不咨询提供方。前台结果携带 `sandbox: { mode, denied: false }`；后台进程句柄不携带沙箱事实。 |
+
+语义：
+
+- **拒绝是结果事实。** 如果一次失败运行的 stderr 包含所选后端自身的拒绝方言，即提供方在每次包装时加上的特征（bwrap 下的 EROFS 文本、Landlock 下的 EACCES、Seatbelt 下的 EPERM），则结果报告 `BashRunResult.sandbox.denied: true`（从已收集的 stderr 尾部进行保守分类）。每次受限制运行还会携带执行时模式（`result.sandbox.mode`）与提供方强制执行完整性（`result.sandbox.enforcement`：`full`，或在较旧 Landlock ABI 上为 `partial`）。
+- **Runner 失败是沙箱失败，绝不是命令失败。** 前台执行会抛出 `SANDBOX_UNAVAILABLE`；已结算的后台进程会标记 `process.sandbox.runnerFailed`，bash 产生方通过通用 `task_output` 渲染它。spawn 失败也会经过结算，因此受限制的后台句柄会保留自身的模式／强制执行事实，并释放每进程计数。
+- **部署回退，每次调用策略。** [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/) 为每次工具调用解析完整的 `SandboxExecutionPolicy`：调用会话提供自身的模式覆盖与不可变 cwd 根目录，部署配置则为无 agent 调用提供回退。已批准的升权只更改该策略的模式，会话根目录仍然附着其上。`resolve()` 把策略带入 spec，因此来自不同项目的重叠命令会在各自的根目录与模式下运行、分类和报告。能力事实 `ctx.bash.sandboxMode` 报告已配置的默认值，因此工具层只在装载该执行器时才公布升权。模型只能通过结果事实了解沙箱：静态 bash 工具描述会解释拒绝标记，系统提示词中不会声明当前模式。
+- **只限制文件影响。** 设计上不限制网络与进程可见性：模式词汇不会声称覆盖后端未强制执行的范围。
+- 进程机制（spawn、进程组终止、输出收集／spill、后台句柄、凭证清理）继承自 [`dsh-bash-local`](../bash-local/)；runner 选择位于 [`dsh-sandbox-local`](../../sandbox/sandbox-local/)。
+
+seam 上仅拒绝：拒绝是一项已报告事实，本执行器绝不自行协商权限。批准问题位于工具层（`dsh-tool-bash`），由它驱动本包遵守的覆盖。
+
+```yaml
+- id: sandbox
+  name: '@deepseek-ai/dsh-sandbox-local'
+- id: sandbox-policy
+  name: '@deepseek-ai/dsh-sandbox-policy'
+  config:
+    mode: read-only
+    workspaceRoot: !!js process.cwd() # fallback for calls without a session cwd
+- id: bash
+  name: '@deepseek-ai/dsh-bash-sandbox'
+```
+
+无密钥消费方集成证明是 `tests/bwrap.e2e.ts`、`tests/landlock.e2e.ts` 和 `tests/seatbelt.e2e.ts`（通过 `ctx.bash` 驱动真实提供方 + 真实 runner，在真实世界验证，并在相应 runner 缺失时各自自行跳过）。agent-spine e2e 还会在一个 Cordis 上下文中驱动两个并发会话，并证明每个真实 bash 工具调用只能写入自身项目。可运行 demo 见 [acp-agent 示例的默认组合](../../../examples/acp-agent/)。
+
+## 模型体验
+
+### 间接的 Bash 工具 schema
+
+#### 模型看到的内容
+
+基线是生成的 [`dsh-tool-bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash)。通过公布一个执行限制的 `sandboxMode`，此后端会为 `bash` 增加 `sandbox_permissions`，其 enum 为 `workspace-write` | `danger-full-access`，并增加 `justification`。后端不添加提示词文本，会话的有效模式仍不会声明。
+
+#### Token 影响
+
+在 `bash` 可见的请求上增加少量固定 schema；模式切换不增加上下文 token。
+
+#### KV Cache 影响
+
+执行器持续公布相同沙箱能力时，前缀保持稳定。更改这些能力会改变 `bash` schema，可能使从该定义起的复用失效；每会话模式切换不会导致失效。
+
+### 间接的 Bash 工具结果
+
+#### 模型看到的内容
+
+在普通有界输出之后，被拒绝的调用会精确追加 `[sandbox: file access denied under <mode> mode]`。当升权可用时，接下来精确追加 `[sandbox: escalation available — retry this exact command once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]`。已结算的后台 runner 失败则追加 `[sandbox: the sandbox runner itself failed under <mode> mode — the command did not run; this is a sandbox problem, not a command failure]`。
+
+#### Token 影响
+
+除普通输出外，正常允许的运行不会增加 token。拒绝或失败会增加上述有条件标记，并保留到压缩。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 配置项失效。
+
+### 间接的 Bash 工具错误
+
+#### 模型看到的内容
+
+如果没有 runner 能强制执行受限模式，前台调用会传播 [`SANDBOX_UNAVAILABLE` 错误；它由 `dsh-sandbox` 持有](../../sandbox/sandbox/README.md#confinement-error-indirectly)。如果 runner 在执行时失败，此后端会提供第一行 stderr 作为详细信息。
+
+#### Token 影响
+
+该次调用可见的是有条件错误文本，并保留在历史记录中直到压缩。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 配置项失效。
+
+## 已知限制与暂缓事项
+
+- **限制只覆盖文件影响**：网络访问与进程可见性不变，因此这些模式不是通用安全沙箱。
+- **拒绝从失败命令的 stderr 推断**：后端特征使该推断可跨平台使用，但匹配的应用错误可能被分类为拒绝，也可能遗漏未出现在保留尾部中的拒绝。
+- **后台 runner 失败没有即时错误通道**：它记录在已结算进程上，并在调用方使用 `task_output` 读取通用任务时呈现。
+- **`danger-full-access` 有意绕过 `ctx.sandbox`**：它是显式无约束模式，不是更宽的沙箱 profile。
--- a/packages/bash/bash/README.i18n.yaml
+++ b/packages/bash/bash/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: b4ee66a1fa2696254a1f2f411b7db5d3190f8370
+README.zh.md: 151d4bd7ab257234584b9008c96e6356d7e39351
--- a/packages/bash/bash/README.md
+++ b/packages/bash/bash/README.md
@@ -1,5 +1,7 @@
 # @deepseek-ai/dsh-bash

+English | [中文](README.zh.md)
+
 The **bash executor seam**: an abstract `BashExecutor` service (`ctx.bash`) defining WHAT a bash backend does — run foreground commands and start background processes — without saying HOW. Task ids, ownership, collection, cancellation, and notices belong to the generic `ctx.tasks` runtime.

 This package is the interface quarter of the bash capability, split so each concern can evolve (and be swapped) independently:
--- a/packages/bash/bash/README.zh.md
+++ b/packages/bash/bash/README.zh.md
@@ -0,0 +1,49 @@
+# @deepseek-ai/dsh-bash
+
+[English](README.md) | 中文
+
+**bash 执行器 seam**：抽象 `BashExecutor` 服务（`ctx.bash`）定义 bash 后端做什么，即运行前台命令与启动后台进程，但不规定如何实现。task id、所有权、收集、取消与通知属于通用 `ctx.tasks` 运行时。
+
+本包是 bash 能力中负责接口的四分之一，各项职责因此可以独立演进（和替换）：
+
+| 包 | 职责 |
+|---|---|
+| `@deepseek-ai/dsh-bash`（本包） | 接口：抽象服务 + 词汇类型 |
+| `@deepseek-ai/dsh-bash-local` | 实现：本地子进程 |
+| `@deepseek-ai/dsh-bash-sandbox` | 实现：沿用 `dsh-bash-local` 的机制，但通过 [`ctx.sandbox`](../../sandbox/sandbox/) 限制每次 spawn，并将拒绝报告为结果事实 |
+| `@deepseek-ai/dsh-tool-bash` | 基于 `ctx.bash`、面向模型的工具 schema |
+
+该拆分与 LLM seam（`LlmService`／`LlmAdapter`）及 agent 工具调研结果一致：pi 将执行隐藏在 `BashOperations` 接口之后（本地 shell／SSH／VM 后端），Codex 则隐藏在 exec-server 协议之后。`dsh-bash-sandbox` 正是这种替换的实际应用：沙箱执行器位于同一接口之后；消费方检测其 `sandboxMode` 能力并添加升权字段，无需导入实现。容器化或远程执行器也可以同样接入。
+
+## 服务 API（`ctx.bash`）
+
+| 成员 | 语义 |
+|---|---|
+| `run(spec)` | 前台执行。命令完成时 resolve。**只会因基础设施失败而 reject**（工作目录不可用、shell 缺失、信号已在调用前中止）；非零退出、超时终止和中止终止都会 resolve 为描述性 `BashRunResult`。 |
+| `start(spec)` | 后台执行。立即返回不含任务语义的 `BashProcess` 句柄；**不应用超时**。调用方可以将其适配到 `ctx.tasks`。 |
+| `sandboxMode` | 工具层的能力事实：沙箱执行器用于限制执行的默认模式（基类中为 `undefined`，即「此执行器不使用沙箱」）。`dsh-tool-bash` 会在注册时读取它，仅当组合确实支持升权字段时才公布这些字段。 |
+| `BashProcess.readOutput()` | **增量** 读取输出：连续读取绝不会重复交付。因缓冲区边界丢失数据的读取会标记 `lossy`，并指向完整流 spill 文件。 |
+| `BashProcess.kill()` | 终止进程组。如果进程已结束，返回 `false`。 |
+
+实现会继承 `BashExecutor` 并实现抽象方法。dispose 必须终止每个运行中的进程并等待其退出，详见 HMR 安全测试。
+
+## 词汇
+
+`BashExecRequest`（command、workdir?、timeoutMs?、stdoutMaxBytes?、signal?、stdin?、env?、dshEnv?、sandboxPolicy?）在执行前解析为 `BashExecSpec`（command、workdir、timeoutMs、stdoutMaxBytes、signal?、stdin?、env?、dshEnv?、sandboxPolicy）。`stdoutMaxBytes` 是受信任前台运行的捕获预算，用于必须解析完整有界 stdout 的消费方；面向模型的 bash 工具不公开该字段。`sandboxPolicy` 在请求上可选，在已解析 spec 上必填但可为 null：它携带完整的每次调用模式与工作区根目录。沙箱工具路径通过 `ctx.sandboxPolicy` 从调用会话解析它；沙箱执行器的直接调用方回退到部署策略，非沙箱执行器则携带该字段但不作限制。
+
+每会话沙箱模式覆盖词汇（`'sandbox/mode'` 事件、`effectiveSandboxMode(events)` fold 以及 `setSandboxMode(session, mode)` 写入路径）不位于此处。它是所有强制执行家族共享的策略状态，属于 [`@deepseek-ai/dsh-sandbox-policy`](../../sandbox/sandbox-policy/)。`run()` 返回 `BashRunResult`；`start()` 返回 `BashProcess`，其增量读取与终止方法由 `dsh-tool-bash` 适配为通用任务注册。沙箱执行器会在前台结果与已结算进程句柄上标记 `BashSandboxInfo`。详见 `src/types.ts` 与 [core-data-structures/bash.md](../../../docs/core-data-structures/bash.md)。
+
+`stdin` 与普通 `env` 由同进程插件（hooks 桥接、原生插件）设置，用于向 hook 命令提供其 JSON payload 和 `CLAUDE_PROJECT_DIR`／`CLAUDE_PLUGIN_ROOT` 值。`dshEnv` 是受类型限制、仅允许受管 key 的独立受信任 overlay；导出的 `DSH_ENV_PREFIX` 是该 namespace、其 `DshEnvironmentKey` 模板类型、执行器清理、注册表验证、派生内置名称与模型指引的单一真源。模型 bash 使用 `ctx.bashEnv` 收集的当前快照。实现会移除继承的受管 key，拒绝普通 `env` 中的这些名称，再合并 `dshEnv`，因此省略的当前事实不会回退到陈旧环境状态。面向模型的工具不公开任何一个字段。这三者在已解析 spec 上仍然可选；缺失表示没有输入／overlay。详见 [bash-stdin-env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) 与 [会话环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
+
+## 模型体验
+
+通过 `dsh-tool-bash` 间接影响；该工具会将执行器输出与沙箱事实转为指引和保留的工具结果 token。
+
+#### KV Cache 影响
+
+不会直接失效；请求前缀变更由具名消费方负责。
+
+## 已知限制与暂缓事项
+
+- **没有交互式输入词汇**：`stdin` 只会在 spawn 时写入一次并关闭；seam 不提供向运行中任务继续输入的通道，也没有 PTY 会话概念。
+- **前台超时始终由执行器拥有**：seam 上的调用方拥有 deadline 模式已由 [工具调用超时策略 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md) 明确暂缓。
--- a/packages/bash/tool-bash/README.i18n.yaml
+++ b/packages/bash/tool-bash/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: 965ae25a5e29a4f767adfcb73e4a77f1060e4b46
+README.zh.md: 60be5c5ca5624719f5ca651a78b6ba56f3f3df06
--- a/packages/bash/tool-bash/README.md
+++ b/packages/bash/tool-bash/README.md
@@ -1,5 +1,7 @@
 # @deepseek-ai/dsh-tool-bash

+English | [中文](README.zh.md)
+
 The model-facing `bash` tool registered over the `ctx.bash` executor seam. Foreground execution stays behind that seam; a background process handle is registered with the generic `ctx.tasks` runtime and controlled through `task_output`, `task_list`, and `task_kill` from `@deepseek-ai/dsh-tool-tasks`.

 Requires a loaded executor implementation (e.g. `@deepseek-ai/dsh-bash-local`); the plugin stays pending until `ctx.bash` exists (`inject: ['tools', 'bash', 'systemPrompt']`).
--- a/packages/bash/tool-bash/README.zh.md
+++ b/packages/bash/tool-bash/README.zh.md
@@ -0,0 +1,158 @@
+# @deepseek-ai/dsh-tool-bash
+
+[English](README.md) | 中文
+
+模型侧 `bash` 工具，注册在 `ctx.bash` 执行器 seam 上。前台执行始终位于该 seam 之后；后台进程句柄会注册到通用 `ctx.tasks` 运行时，并通过 `task_output`、`task_list` 和 `task_kill` 控制；这些工具由 `@deepseek-ai/dsh-tool-tasks` 提供。
+
+需要加载执行器实现（例如 `@deepseek-ai/dsh-bash-local`）；在 `ctx.bash` 可用之前，插件会保持等待状态（`inject: ['tools', 'bash', 'systemPrompt']`）。
+
+包（package）根只公开 Cordis 插件契约（`name`、`inject`、`Config`、`apply`）；结果渲染和后台进程适配仍是实现细节，由同包测试覆盖。
+
+插件还会提供 `tool:bash` 提示词段落（顺序 105）：检查每个结果中的 `[exit code: N]` 标记，发现失败时先调查原因再继续。
+
+## 工具
+
+### `bash`
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `command` | string（必填） | 通过 `bash -c` 运行。调用之间不保留状态；请使用 `workdir`，不要使用 `cd`。 |
+| `description` | string（必填） | 用一行主动语态概述命令（5～10 个词），仅用于 UI／日志显示，不影响执行。 |
+| `timeoutMs` | number | 以毫秒为单位覆盖超时时间。执行器会应用其配置的默认值和上限。 |
+| `workdir` | string | 本次调用的工作目录。默认为调用方 agent（智能体）会话 cwd 的文件系统标识（`session.header.cwd`），使每个会话都在自己的工作区中运行；相对 `workdir` 也以同一标识为基准解析。 |
+| `run_in_background` | boolean | 立即返回 task id；不应用超时。 |
+| `sandbox_permissions` | string enum | 仅当已挂载的执行器启用沙箱时才会公开（`ctx.bash.sandboxMode` 报告一个具有限制作用的默认值）：被拒命令所需的更宽模式，取自封闭的目标词汇 `workspace-write`/`danger-full-access`（绝不能缩减为执行器默认值；有效模式按会话确定，执行时会基于它检查是否严格拓宽，未拓宽的请求直接失败，不会向任何人发起提示）。 |
+| `justification` | string | 必须与 `sandbox_permissions` 一同提供（缺少任一项都会产生验证错误）：用一句话向用户解释此命令为何需要这项更宽权限。 |
+
+执行前，`command`、`workdir` 和 `timeoutMs` 会通过 `ctx.bash.resolve()` 依据执行器配置默认值完成解析，因此执行器 seam（`BashExecSpec`）收到显式的 `workdir`/`timeoutMs` 值。工具层会根据调用方 agent 的 `session.header.cwd` 应用工作目录默认值，然后才调用 `resolve()`：由于 N 个会话共享一个执行器，逐会话 cwd 必须来自 `exec.agent`；只有无法取得会话 cwd 时，执行器才回退到自身配置／`process.cwd()`。存在沙箱策略时，工具会复用已经规范化的 `workspaceRoot` 作为工作目录基准，防止限制逻辑与进程启动过程对同一个会话路径拼写产生不同解析结果。
+
+### 托管 shell 环境
+
+每次模型发起的前台或后台 bash 调用都会收到新收集的一组可信 `DSH_*` 环境变量。`DSH_HOME` 是由 [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) 解析出的 Harness home 绝对路径（依次采用 `dshHome` 配置、环境中的 `$DSH_HOME`、`~/.dsh`），`DSH_SHELL=1` 则标识受托管的子进程。Agent 调用还会收到 `DSH_SESSION_ID=agent.session.header.id`；当活跃的持久化 seam 找到 JSONL 产物时，也会收到 `DSH_SESSION_JSONL=<absolute target path>`。JSONL 路径只是位置提示：首次 flush 前它可能尚不存在，也可能不包含当前缓冲的轮次，并且它不是授权凭据。
+
+`ctx.bashEnv` 持有收集过程。其他插件可以注册具有 effect 作用域的贡献方，提供稳定名称、已声明的键／说明以及 `resolve(execution: ToolExecution)`；重复持有或运行时返回未声明的键会快速失败，而 `list()` 无需执行提供方即可列举声明。Harness 内置项保留 `DSH_HOME`、`DSH_SHELL` 和 `DSH_SESSION_ID`；tool-bash 的持久化转换器持有 `DSH_SESSION_JSONL`，其值来自后端无关的 `sessionPersistence.locate()` seam。
+
+```ts
+import type { Context } from 'cordis'
+import type {} from '@deepseek-ai/dsh-tool-bash'
+
+export const inject = ['bashEnv']
+
+export function apply(ctx: Context): void {
+  ctx.bashEnv.register({
+    name: 'deployment-region',
+    variables: { DSH_DEPLOYMENT_REGION: { description: 'Current deployment region.' } },
+    resolve: execution => execution.agent === undefined ? {} : { DSH_DEPLOYMENT_REGION: 'cn-north' },
+  })
+}
+```
+
+overlay 根据当前 `ToolExecution` 计算，并通过专用的 `BashExecRequest.dshEnv` 通道传递。本地执行器会先删除继承的所有 `DSH_*`，再合并该快照，因此嵌套 harness 和并发的父／子 agent 不会泄漏陈旧身份。它绝不会修改 `process.env`。工具说明只教授通用 `$DSH_*` 约定，不会点名持久化专用变量，也不会添加永久的系统提示词段落。
+
+结果文本依次包含 stdout、可选的 `[stderr]` 段落和适用的沙箱拒绝、超时、信号、退出代码及截断标记。超时与最终退出状态分别报告；非零退出仍是由模型解释的结果，不会成为 `isError`。截断结果会链接安全的完整 spill 文件，或报告文件不可用。只有 spawn 错误和中止等基础设施故障才会产生 `isError`。
+
+已完成前台进程的规范成功值为 `{ kind: 'foreground', ...BashRunResult }`，已发布任务则为 `{ kind: 'background', taskId }`。Native renderer 保留上述文本，包括精确的 `started background task <id>`；程序化消费方使用带类型字段，无需解析这些字符串。执行器的流上限仍是 `BashRunResult` 的采集限制，并携带其 spill 路径。
+
+当 `run_in_background` 为 true 时，此插件会在 spawn 前预检 `ctx.tasks.start()`，把调用方 agent 注册为持有者，并将返回的 `BashProcess` 句柄适配为通用的取消／完成／增量输出钩子。任务运行时持有 id、跨会话隔离、完成通知、等待和 dispose（资源释放）清理；此插件只把 bash 退出／沙箱事实映射为任务输出和结果详情。`enableRunInBackground: false` 会移除该参数，并在执行时拒绝强制后台调用。
+
+## UI 展示
+
+工具持有自己的 `presentCall`/`presentResult` 渲染意图。前台调用是终端卡片，包含命令、说明、cwd、原始输出和解析后的退出状态。后台启动只返回 task id，因此使用通用执行卡片；通用 `task_*` 工具持有各自的卡片。这些 presenter 是纯函数，可安全回放。
+
+## 工具仅使用具名参数构建请求
+
+`BashExecRequest` seam 携带可选的 `stdoutMaxBytes`、`stdin`、普通 `env` 和托管 `dshEnv`，供可信进程内插件及此工具的环境注册表使用。模型侧工具不公开 `stdoutMaxBytes`、`stdin` 或 `env`：它使用具名的命令／工作目录／超时／信号／沙箱字段，加上从注册表收集的 `dshEnv` 来构建请求。额外模型键会被忽略，无法替换托管值。Shell 语法可以提供等价的命令级行为，而本地执行器会清除环境中的凭据和陈旧 `DSH_*` 值。参见 [stdin/env Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)。
+
+## 权限与升权
+
+除非启用沙箱的执行器（[`dsh-bash-sandbox`](../bash-sandbox/)）限制命令，否则命令以执行器的完整权限运行。仅拒绝型沙箱会把拒绝作为结果事实报告，并在此渲染为拒绝标记；逐调用的允许／拒绝／询问策略由 `tools/pre-execute` waterfall（瀑布式事件）负责（参见 docs/architecture.md）。
+
+需要升权的 bash 调用会在执行前解析 `ctx.approval`。`allowed-once` 只对该次调用应用请求模式；审批被拒、取消、不可用或缺少审批上下文时，命令完全不会执行，并返回不同的错误。发生真实拒绝后，模型可以在同一轮次中使用满足需要的最窄模式和理由重试同一命令一次；审批提示本身就是征求同意的步骤。升权绝不能预先推测，禁用或拒绝审批即为最终结果。其理由由 [沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) 持有。
+
+## 逐会话模式切换
+
+对于启用沙箱的执行器，每次调用依次按单次升权、会话覆盖、执行器默认值解析模式。未启用沙箱以及没有 agent 的调用不携带会话覆盖。提示词和切换通知均不公布当前常驻模式；拒绝结果会在边界相关时报告有效模式。参见 [`dsh-bash` 整合](../bash/README.md)和[沙箱切换契约](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)。
+
+## 模型体验
+
+### 系统提示词
+
+#### 模型看到的内容
+
+此插件注册作用域内的每个请求都包含下方 bash 指引。启用沙箱的执行器不会添加模式声明或切换通知。作用域工具限制可以隐藏 schema，但不会移除这个独立注册的段落。
+
+##### Bash 指引
+
+```markdown
+Check the [exit code: N] marker on every bash result; investigate failures before moving on.
+```
+
+#### Token 影响
+
+插件活跃期间，每个请求都会产生少量固定输入开销，不受沙箱模式或模式切换影响。
+
+#### KV Cache 影响
+
+只要注册作用域和提示词文本不变，前缀即可稳定复用。插件激活或 dispose 可能从此提示词段落开始使复用失效；沙箱模式切换不会。
+
+### 工具 schema
+
+#### 模型看到的内容
+
+模型会看到生成的 [`bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash)。仅当此生产方启用 `run_in_background` 时，该字段才会出现；仅当已挂载执行器声明支持沙箱时，`sandbox_permissions` 和 `justification` 才会出现。Agent 作用域的工具限制可以移除该 agent 的定义。
+
+#### Token 影响
+
+工具可见的每个请求都会产生固定 schema 开销；沙箱支持会增加升权字段及其条件说明段落。
+
+#### KV Cache 影响
+
+只要可见性、后台支持和执行器沙箱功能保持不变，前缀即可稳定复用。限制、配置或执行器发生变化时，可能从首个变化的工具定义开始使复用失效。
+
+### 前台结果
+
+#### 模型看到的内容
+
+renderer 先输出依数据而定的 stdout 尾部，再输出可选的 `[stderr]` 和 stderr 尾部。没有输出时，它会精确输出 `(no output)`。条件行精确为 `[output truncated; full output: <path-or-(unavailable)>]`、`[sandbox: file access denied under <mode> mode]`、`[timed out after <timeoutMs>ms]`、`[killed by signal: <signal>]` 和 `[exit code: <exitCode>]`；沙箱升权与 runner 故障行原文列于 [`dsh-bash-sandbox`](../bash-sandbox/README.md)。
+
+#### Token 影响
+
+调用前结果 token 为零。每条流的输出有界，每个已输出行则会保留在历史中，直至压缩（compaction）。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
+
+### 后台任务上下文与结果
+
+#### 模型看到的内容
+
+启动会精确返回 `started background task <taskId>`。此生产方会向通用任务运行时提供增量进程输出、可选的 `[some output was dropped from memory; full output: <paths-or-(unavailable)>]`、沙箱事实，以及 `exit code: <exitCode>` 或 `signal: <signal>` 等终止详情。[`dsh-tool-tasks`](../../tasks/tool-tasks/README.md) 持有模型可见的状态行、完成通知、列表和取消响应。
+
+#### Token 影响
+
+启动确认很短并会保留；收集到的输出依数据而定，并受执行器流缓冲区限制。消费式读取不会重复先前输出。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
+
+### 工具错误
+
+#### 模型看到的内容
+
+验证和策略失败统一为 `Error: <message>`。此包的稳定消息包括 `invalid command: expected a non-empty string`、`invalid description: expected a non-empty string`、`invalid timeoutMs: expected a positive number, got <value>`、`invalid escalation: sandbox_permissions requires a justification`、`invalid escalation: justification is only valid together with sandbox_permissions`、`invalid justification: expected a non-empty sentence`、`background execution is disabled for this bash tool`、`background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks`、`sandbox_permissions is not available in this composition (no sandboxing executor to escalate)`、`sandbox escalation to "<mode>" is not strictly wider than this call's current "<mode>" mode`、审批不可用／拒绝／取消变体，以及 `command aborted`。
+
+#### Token 影响
+
+只有失败调用会增加这些保留 token；升权被拒时命令不会运行，因此不会添加命令输出。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
+
+## 已知限制与延期工作
+
+- **回放退出状态 pill 从结果文本解析**：如果输出最后一行恰好精确为 `[exit code: N]` / `[killed by signal: …]`，会话回放将显示错误的 pill；这是仅影响展示的已知残留问题。
+- **`bash` 工具不采用 `timeout-policy` 预算**：根据[工具调用 timeout-policy Agent Note](../../../.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md)，它保留由执行器持有的 `BASH_TIMEOUT` 路径。
+- **后台进程没有执行器超时**：工作不再需要时，调用方必须使用 `task_kill`，或依赖持有者／服务的 dispose。
--- a/packages/client/AGENTS.md
+++ b/packages/client/AGENTS.md
@@ -10,8 +10,8 @@ The [slot system standard](../../.agents/notes/implemented/architecture/2026-07-

 1. **One API**: a plugin composes UI only through `ctx.slots.register({ name, children?, store?, inject? }, Component)`. There is no separate slot-definition call, no whitelist face object, no face-minting helper. The shell alone renders `'root'`.
 2. **children = declaration + authorization**: the slots your component renders are exactly the keys of your register call's `children` object (spec values: `kind`/`scope`). Rendering a slot you didn't declare, or declaring one someone else declared, fails at load — do not work around it; the conflict is the design speaking. Slot names mirror the composition path: `<domain>.<entry>.<hole>` (e.g. `'conversation.chat.toolview'`).
-3. **Component props are the four shares, all derived**: `PropsRuntime<K>` (SlotMap: owner params + `useSession`/`sessionId` on session scope + `useSessions`) & `PropsRenderSlots<S>` (children keys) & `PropsStore<H>` (store factory) & the inject face. Never hand-write a member a share already derives; never re-type a share locally.
-4. **Hooks are framework-made only**: `useSession`, `useSessions`, `useStore`, `renderSlot` are the four seats. Business code never creates a hook or selector as a prop value — pass plain data and callbacks. (Component-internal behavioral hooks that subscribe to nothing external are fine.)
+3. **Component props are the four shares, all derived**: `PropsRuntime<K>` (SlotMap: owner params + `useSession`/`sessionId` on session scope + global `useSessions`/`useWorkspaces`) & `PropsRenderSlots<S>` (children keys) & `PropsStore<H>` (store factory) & the inject face. Never hand-write a member a share already derives; never re-type a share locally.
+4. **Hooks are framework-made only**: `useSession`, `useSessions`, `useWorkspaces`, `useStore`, `renderSlot` are the five seats. Business code never creates a hook or selector as a prop value — pass plain data and callbacks. (Component-internal behavioral hooks that subscribe to nothing external are fine.)
 5. **Live data has exactly three channels**: parent knows it → owner props at the renderSlot site; only the component knows it → local state; shared across entries or survives remounts → a store declared at register. Derived data is a pure function over framework-hook data (`useMemo`), never its own subscription.
 6. **Stores: read `props.useStore`, write `props.actions.*`** — the declared actions are the complete mutation surface. Write the store as an exported `createXXXStore()` factory (module-level handles are forbidden — de-facto singletons); share by passing one handle to several registers inside `apply`. Production code never calls the factory or `.create()` outside `apply`; tests do (that is the sanctioned zero-machinery path).
 7. **inject returns plain data and callbacks** from the apply closure's own ctx — no hooks, no ReactNode producers, no whole-service objects. Its capability boundary is the plugin's declared `inject` topology; there is no wider ctx to reach for.
@@ -65,11 +65,21 @@ The GUI test structure (three tiers, lane map) is settled in the [GUI testing sy
 Run the narrowest rung that covers what you touched; escalate only when the change surface demands it.

 1. **Every GUI code change** — `pnpm run test:gui` (seconds; no browser, no server): the client suites plus the host-side GUI packages. This is the inner loop; run it as freely as a typecheck.
-2. **Changes to the build surface, boot wiring, or static serving** (`apps/web`, vite config, `dsh-host-webserver`) — additionally `pnpm run test:web`: rebuilds the frontend dist, then runs the browser smoke pair (the real-host case self-skips without `DEEPSEEK_API_KEY`).
+2. **Changes to the build surface, boot wiring, static serving, or the wire carriage** (`apps/web`, vite config, `dsh-host-webserver`, connection/handler/SSE) — additionally `pnpm run test:web`: rebuilds the frontend dist, then runs the browser smoke pair (the real-host case self-skips without `DEEPSEEK_API_KEY`) plus the keyless replayed e2e scenarios (`DSH_SNAPSHOT=refresh` rewrites their aria goldens after an intentional conversation-UI change; `DSH_SNAPSHOT=record` re-records fixtures with a key).
 3. **Before a PR** — `pnpm run check:pre-push` (the repo-wide gate ladder). Between PR windows this rung is not expected on every commit.

 If `test:gui` is red on code you did not touch, neither silently fix nor ignore it: note it in your handoff so it lands in the next PR window's sweep.

+## New plugin package checklist
+
+Bringing up a new `packages/client/<name>` plugin package (ui-workspace is the latest walked example; ui-sidebar/ui-question are good skeletons to copy):
+
+1. **Package skeleton**: `package.json` (`@deepseek-ai/dsh-client-<name>`, exports `.`/`./invariant`/`./client`/`./src/*`/`./package.json`, `dshClient` manifest, `files` list), `tsconfig.json` (extends `tsconfig.base.client.json`, one `references` entry per workspace dependency plus `support/invariants`), `tsdown.config.ts` (`clientBundle(id, ['lib/types/index.js', 'lib/types/invariant.js'])`), `src/index.ts` (empty node-half apply), `src/invariant.ts` (companion with a real reason), `src/css-modules.d.ts` when using CSS Modules, `README.md` with the Model Experience section.
+2. **Three registration surfaces, all required** (missing any one fails at a different, later point): the `tsconfig.client.json` aggregate `references` entry; the `CLIENT_PACKAGES` roster in `apps/cli/src/web.ts`; an `apps/cli/package.json` dependency (`mountWebPlugins` resolves roster packages against the composing app's URL — a roster row that is not a dependency of `apps/cli` fails to mount). `pnpm-workspace.yaml` already globs `packages/*/*`.
+3. **dshClient manifest semantics**: `platform: 'web'` always; `immediately: true` only for stage-one-prefetch infrastructure rows. `inject` lists package-name dependency edges — they are **informational only** (preflight display, HMR diffing); they do not sequence entry activation or apply order. Activation order is cordis fiber inject waiting on *services*, nothing else.
+4. **Registering into another package's slot**: if the declaring host provides no waitable service, your apply's order relative to the host's is unconstrained — a bare `slots.register` into its slot races boot (intermittent `slot "..." is not declared` page failures). Register with declaration-aware deferral: check `ctx.slots.spec(name)`, otherwise `ctx.slots.subscribe(name)` and register on the declaration event (SlotCore supports subscribing ahead of declaration); make the registration idempotent, and unsubscribe + dispose in the effect disposer. Only take a service edge in `inject` when the host actually provides one (ui-question → `'conversation'` is that case).
+5. Rebuild the bundle (`pnpm --filter <pkg> bundle`) before probing a live `dsh web` server — the registry serves `lib/client.js`, not sources.
+
 ## New component checklist

 1. Compose through register: merge the slot contract into `SlotMap`, declare the slot in its parent entry's `children`, register your component — see the [slot system standard](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md). No other composition route exists.
--- a/packages/client/connection/README.i18n.yaml
+++ b/packages/client/connection/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: 80228a180faba0c556ff720e999b29b5bb1635b6
+README.zh.md: f4b857886bfafa891ceb1bd6b79b27e1fb725819
--- a/packages/client/connection/README.md
+++ b/packages/client/connection/README.md
@@ -1,7 +1,13 @@
 # @deepseek-ai/dsh-client-connection

+English | [中文](README.zh.md)
+
 Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` seam, and the loop's sink/config types. The platform subclasses (WebApiClient/FixtureApiClient), the ConnectionController loop, and the fixture data source are package-internal — apply selects and drives them; tests reach them via src. Contract: api-contracts v3 §3.

+## Keyless fixture
+
+Any `fixture` query parameter selects the in-memory carrier. `fixture=empty` starts with no Workspace or Session; `fixturePrompt=reject` rejects prompts before acceptance; `fixtureAttach=fail` publishes a Session but rejects its Workspace attachment; `fixtureSessionCreate=drop-response` publishes and frames a Session before dropping the create response; and `fixtureFrames=workspace-first` reverses the default session-first create-frame order. Workspace creation by name/path and caller-preallocated SessionIds remain deterministic enough for assembled Web tests to reconcile list and frame arrival.
+
 ## Model Experience

 None, as the wire consumer layer moves already-composed messages between browser and host; nothing here reaches a model request.
--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -0,0 +1,22 @@
+# @deepseek-ai/dsh-client-connection
+
+[English](README.md) | 中文
+
+协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 单消费方流循环启动器）；导出表层携带协议契约类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。平台子类（WebApiClient/FixtureApiClient）、ConnectionController 循环和 fixture 数据源都属于包内部：apply 负责选择并驱动它们，测试则通过 src 访问。契约：api-contracts v3 §3。
+
+## 无密钥 fixture
+
+任何 `fixture` 查询参数都会选择内存载体。`fixture=empty` 启动时不含 Workspace 或 Session；`fixturePrompt=reject` 在接受前拒绝提示词；`fixtureAttach=fail` 发布 Session 但拒绝将其附加到 Workspace；`fixtureSessionCreate=drop-response` 在丢弃创建响应前发布 Session 并为其发出帧；`fixtureFrames=workspace-first` 则反转默认的 Session 优先创建帧顺序。按名称／路径创建 Workspace 以及由调用方预先分配 SessionId，均具有足够的确定性，组装后的 Web 测试可以据此协调列表与帧的到达。
+
+## 模型体验
+
+无。协议消费层只在浏览器与主机之间搬运已经组合好的消息；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **history 的隐式恢复存在争议**：在未附加的会话上打开 history，会在主机侧拉起 agent；纯持久化读取的替代方案记录在 rt-core 协调账本中，P-I 不作改变。该包的消费方会在首次打开时感受到这段延迟。
+- **计划移除 `ToolEventView`／`ToolCallView`／`ToolResultView` 的重新导出**：当 toolview 迁移删除主机 `viewFor` 行时，它们会一并移除（呈现属于客户端）；在此之前，fixture 保留一份局部 `viewFor` 镜像。
--- a/packages/client/connection/src/client/api.ts
+++ b/packages/client/connection/src/client/api.ts
@@ -8,6 +8,7 @@
 export type {
  ApiProxy, SessionsApi, SessionSummary, HostApi, EventsApi, MuxFrame, HostFrame,
  ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, ToolEventView,
+  WorkspaceApi, WorkspaceId, WorkspaceView,
 } from '@deepseek-ai/dsh-host-apiproxy/api'
 export type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools/presentation'
 export type {
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -10,7 +10,7 @@ import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
 import type {
  ApiProxy, ClientRequest, ClientResponse, HistoryEntry, HostFrame, MuxFrame, RpcReceipt,
  RpcRequest, RpcResponse, RpcResult, ServerRequest, ServerResponse, SessionSummary,
-  ToolCallView, ToolEventView, ToolResultView,
+  ToolCallView, ToolEventView, ToolResultView, WorkspaceId, WorkspaceView,
 } from './api.ts'
 import type { RequestPayload, ResponseValue, RpcMethodMap } from '@deepseek-ai/dsh-host-apiproxy/api'
 import { AbstractApiClient, RpcId } from './api.ts'
@@ -242,6 +242,20 @@ interface StreamConn<F> {
  push(envelope: RpcRequest<F>): void
 }

+/** Deterministic fixture branches used by keyless Web assembly tests. */
+export interface FixtureOptions {
+  /** Start with no real Workspace or Session. */
+  empty?: boolean
+  /** Reject every prompt before appending its user event. */
+  rejectPrompt?: boolean
+  /** Publish the Session but fail its Workspace account write. */
+  failWorkspaceAttach?: boolean
+  /** Publish and frame the Session, then throw instead of returning create. */
+  dropSessionCreateResponse?: boolean
+  /** Order of the two successful create frames. */
+  createFrameOrder?: 'session-first' | 'workspace-first'
+}
+
 /** Inbox pump shared by both stream generators (FrameQueue pattern: ONE abort listener hung
 *  outside the loop — a per-iteration {once:true} listener never fires for non-final rounds and
 *  piles up for the stream's lifetime, audit C5). breakNow force-ends the stream without the
@@ -286,10 +300,11 @@ class FxInbox<F> implements StreamConn<F> {

 /**
 * In-memory fake host: fx-alpha carries history and replay scripts; fx-beta is fx-alpha's child session (lineage indent material).
+ * @param options - fixture branches for empty state and failure timing.
 * @returns an ApiProxy backed entirely by in-memory state — no host process, no network.
 */
-export function createFixtureApi(): ApiProxy {
-  const sessions: SessionSummary[] = [
+export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
+  const sessions: SessionSummary[] = options.empty ? [] : [
    { sessionId: sid('fx-alpha'), updatedAt: Date.now(), running: true, cwd: '/tmp/fixture' },
    { sessionId: sid('fx-beta'), updatedAt: Date.now() - 60_000, running: false, parentSessionId: sid('fx-alpha'), cwd: '/tmp/fixture' },
    { sessionId: sid('fx-gamma'), updatedAt: Date.now() - 120_000, running: false, cwd: '/tmp/fixture' },
@@ -298,6 +313,20 @@ export function createFixtureApi(): ApiProxy {
  const nextTurn = new Map<SessionId, number>([[sid('fx-alpha'), 60]])
  let nextSession = 1
  let nextRpc = 1
+  let attachedSessions = options.empty ? 0 : 1
+  // Workspace entities mirroring the host registry: the fixture sessions all
+  // live under one workspace, whose account carries them in attach order.
+  const wid = (raw: string): WorkspaceId => raw as WorkspaceId
+  const fixtureEpoch = new Date(Date.now() - 300_000).toISOString()
+  const workspaces: WorkspaceView[] = options.empty ? [] : [{
+    workspaceId: wid('fx-ws-fixture'),
+    path: '/tmp/fixture',
+    title: 'fixture',
+    sessionIds: [sid('fx-alpha'), sid('fx-beta'), sid('fx-gamma')],
+    createdAt: fixtureEpoch,
+    updatedAt: fixtureEpoch,
+  }]
+  let nextWorkspace = 1
  const mint = (): ReturnType<typeof RpcId> => RpcId(`fx-rpc-${nextRpc++}`)
  /** Resident pending approval (stable rpcId: every mux open replays the same id, matching host replay semantics). */
  const pendingApprovalRpcId = mint()
@@ -464,12 +493,71 @@ export function createFixtureApi(): ApiProxy {
  return {
    sessions: {
      list: request => ok(request, { items: [...sessions].sort((a, b) => b.updatedAt - a.updatedAt) }),
-      create: (request) => {
+      create: async (request) => {
+        const workspace = request.payload.workspaceId === undefined
+          ? undefined
+          : workspaces.find(w => w.workspaceId === request.payload.workspaceId)
+        if (request.payload.workspaceId !== undefined && workspace === undefined) {
+          return err(request, {
+            code: 'workspace-not-found',
+            message: `no workspace ${request.payload.workspaceId}`,
+            details: { workspaceId: request.payload.workspaceId },
+          })
+        }
+        const cwd = workspace?.path ?? request.payload.cwd ?? '/tmp/fixture'
+        const requestedId = request.payload.sessionId
+        const attachWorkspace = (sessionId: SessionId): void => {
+          /* v8 ignore next -- callers enter only when a target Workspace exists. */
+          if (workspace === undefined || workspace.sessionIds.includes(sessionId)) return
+          workspace.sessionIds = [sessionId, ...workspace.sessionIds]
+          workspace.updatedAt = new Date().toISOString()
+          emitHost({ type: 'host/workspace-changed', workspace: { ...workspace } })
+        }
+        const attachFailure = (
+          sessionId: SessionId,
+          workspaceId: WorkspaceId,
+        ): Promise<RpcResponse<{ sessionId: SessionId }>> => err(request, {
+          code: 'workspace-attach-failed' as const,
+          message: `fixture rejected Workspace attachment for ${sessionId}`,
+          details: { sessionId, workspaceId },
+        })
+        if (requestedId !== undefined) {
+          const existing = summaryOf(requestedId)
+          if (existing !== undefined) {
+            if (existing.cwd !== cwd) {
+              return err(request, {
+                code: 'session-conflict',
+                message: `session ${requestedId} already uses ${existing.cwd ?? 'no cwd'}`,
+                details: { sessionId: requestedId, requestedCwd: cwd, ...existing.cwd === undefined ? {} : { existingCwd: existing.cwd } },
+              })
+            }
+            if (workspace !== undefined && !workspace.sessionIds.includes(requestedId)) {
+              if (options.failWorkspaceAttach) return attachFailure(requestedId, workspace.workspaceId)
+              attachWorkspace(requestedId)
+            }
+            return ok(request, { sessionId: requestedId })
+          }
+        }
        const created: SessionSummary = {
-          sessionId: sid(`fx-${nextSession++}`), updatedAt: Date.now(), running: false, cwd: '/tmp/fixture',
+          sessionId: requestedId ?? sid(`fx-${nextSession++}`), updatedAt: Date.now(), running: false, cwd,
        }
        sessions.push(created)
-        emitHost({ type: 'host/session-added', sessionId: created.sessionId })
+        attachedSessions += 1
+        const emitSession = (): void => {
+          emitHost({ type: 'host/session-added', sessionId: created.sessionId, cwd })
+        }
+        if (workspace !== undefined && options.failWorkspaceAttach) {
+          emitSession()
+          return attachFailure(created.sessionId, workspace.workspaceId)
+        }
+        if (workspace !== undefined && options.createFrameOrder === 'workspace-first') {
+          attachWorkspace(created.sessionId)
+          emitSession()
+        } else {
+          emitSession()
+          if (workspace !== undefined) attachWorkspace(created.sessionId)
+        }
+        if (options.dropSessionCreateResponse) throw new Error('fixture: dropped session.create response after publication')
        return ok(request, { sessionId: created.sessionId })
      },
      history: async (request) => {
@@ -489,6 +577,13 @@ export function createFixtureApi(): ApiProxy {
        if (summary === undefined) {
          return err(request, { code: 'session-not-found', message: `no session ${id}`, details: { sessionId: id } })
        }
+        if (options.rejectPrompt) {
+          return err(request, {
+            code: 'agent-busy',
+            message: 'fixture: prompt rejected before acceptance',
+            details: { reason: 'fixture-prompt-rejection' },
+          })
+        }
        summary.updatedAt = Date.now()
        const userText = content.map(b => (b.type === 'text' ? b.text : '')).join('')
        if (mode === 'steer' && replays.has(id)) {
@@ -524,7 +619,81 @@ export function createFixtureApi(): ApiProxy {
      },
    },
    host: {
-      describe: request => ok(request, { version: '0.0.0-fixture', cwd: '/tmp/fixture', attachedSessions: 1 }),
+      describe: request => ok(request, { version: '0.0.0-fixture', cwd: '/tmp/fixture', attachedSessions }),
+    },
+    workspace: {
+      list: request => ok(request, { items: workspaces.map(w => ({ ...w })) }),
+      create: (request) => {
+        const { path, name } = request.payload
+        const target = path ?? `/tmp/fixture-workspaces/${name ?? ''}`
+        const existing = workspaces.find(w => w.path === target)
+        if (existing !== undefined) return ok(request, { workspace: { ...existing }, created: false })
+        const now = new Date().toISOString()
+        const created: WorkspaceView = {
+          workspaceId: wid(`fx-ws-${nextWorkspace++}`),
+          path: target,
+          title: name ?? target.split('/').filter(Boolean).at(-1) ?? target,
+          sessionIds: [],
+          createdAt: now,
+          updatedAt: now,
+        }
+        workspaces.unshift(created)
+        emitHost({ type: 'host/workspace-changed', workspace: { ...created } })
+        return ok(request, { workspace: { ...created }, created: true })
+      },
+      rename: (request) => {
+        const { workspaceId, title } = request.payload
+        const workspace = workspaces.find(w => w.workspaceId === workspaceId)
+        if (workspace === undefined) {
+          return err(request, {
+            code: 'workspace-not-found',
+            message: `no workspace ${workspaceId}`,
+            details: { workspaceId },
+          })
+        }
+        const trimmed = title.trim()
+        if (trimmed !== workspace.title) {
+          if (workspaces.some(w => w.workspaceId !== workspaceId && w.title === trimmed)) {
+            return err(request, {
+              code: 'workspace-name-conflict',
+              message: `workspace name '${trimmed}' is already in use`,
+              details: { name: trimmed },
+            })
+          }
+          workspace.title = trimmed
+          workspace.updatedAt = new Date().toISOString()
+          emitHost({ type: 'host/workspace-changed', workspace: { ...workspace } })
+        }
+        return ok(request, { workspace: { ...workspace } })
+      },
+      insertSessionBefore: (request) => {
+        const { workspaceId, sessionId, beforeSessionId } = request.payload
+        const workspace = workspaces.find(w => w.workspaceId === workspaceId)
+        if (workspace === undefined) {
+          return err(request, {
+            code: 'workspace-not-found',
+            message: `no workspace ${workspaceId}`,
+            details: { workspaceId },
+          })
+        }
+        if (!workspace.sessionIds.includes(sessionId)
+          || (beforeSessionId !== undefined && !workspace.sessionIds.includes(beforeSessionId))) {
+          return err(request, {
+            code: 'workspace-move-invalid',
+            message: `session or anchor is not accounted by workspace ${workspaceId}`,
+            details: { workspaceId, sessionId, ...beforeSessionId === undefined ? {} : { beforeSessionId } },
+          })
+        }
+        const without = workspace.sessionIds.filter(id => id !== sessionId)
+        const at = beforeSessionId === undefined ? without.length : without.indexOf(beforeSessionId)
+        const sessionIds = [...without.slice(0, at), sessionId, ...without.slice(at)]
+        if (!sessionIds.every((id, index) => id === workspace.sessionIds[index])) {
+          workspace.sessionIds = sessionIds
+          workspace.updatedAt = new Date().toISOString()
+          emitHost({ type: 'host/workspace-changed', workspace: { ...workspace } })
+        }
+        return ok(request, { workspace: { ...workspace } })
+      },
    },
    events: {
      async *mux(_request, signal) {
@@ -606,7 +775,12 @@ export function createFixtureApi(): ApiProxy {
 * to the isomorphic pipeline (InProcessApiClient over toFetchHandler(fixtureImpl)).
 */
 export class FixtureApiClient extends AbstractApiClient {
-  private readonly api = createFixtureApi()
+  private readonly api: ApiProxy
+
+  constructor() {
+    super()
+    this.api = createFixtureApi(fixtureOptionsFromLocation())
+  }

  protected doFetch(): Promise<Response> {
    throw new Error('FixtureApiClient overrides all protocol paths; doFetch must be unreachable')
@@ -634,6 +808,10 @@ export class FixtureApiClient extends AbstractApiClient {
      case 'session.prompt': return this.api.sessions.prompt(request)
      case 'session.cancel': return this.api.sessions.cancel(request)
      case 'host.describe': return this.api.host.describe(request)
+      case 'workspace.list': return this.api.workspace.list(request)
+      case 'workspace.create': return this.api.workspace.create(request)
+      case 'workspace.rename': return this.api.workspace.rename(request)
+      case 'workspace.insertSessionBefore': return this.api.workspace.insertSessionBefore(request)
    }
  }

@@ -678,3 +856,16 @@ export class FixtureApiClient extends AbstractApiClient {
    return this.api.respond(message)
  }
 }
+
+/** Browser query mapping; direct unit callers pass FixtureOptions explicitly. */
+function fixtureOptionsFromLocation(): FixtureOptions {
+  if (typeof location === 'undefined') return {}
+  const query = new URLSearchParams(location.search)
+  return {
+    empty: query.get('fixture') === 'empty',
+    rejectPrompt: query.get('fixturePrompt') === 'reject',
+    failWorkspaceAttach: query.get('fixtureAttach') === 'fail',
+    dropSessionCreateResponse: query.get('fixtureSessionCreate') === 'drop-response',
+    createFrameOrder: query.get('fixtureFrames') === 'workspace-first' ? 'workspace-first' : 'session-first',
+  }
+}
--- a/packages/client/connection/src/client/index.ts
+++ b/packages/client/connection/src/client/index.ts
@@ -1,10 +1,7 @@
 /**
- * Browser half of the wire consumer layer (contract: api-contracts v3
- * section 3; export inventory = v3 §3.2). The wire is this package's client
- * half in its entirety — apply mounts ctx.connection: the shared api client
- * plus the connection controller handle. Mode selection (?fixture) happens
- * here so the rest of the client tree is mode-blind; the controller's sinks
- * are wired by the runtime plugin (object layer), which injects this service.
+ * Browser wire client. The plugin selects fixture or HTTP transport, provides
+ * the shared API client, and lets the runtime object layer start the stream
+ * controller with its sinks.
 */
 import type { Context } from 'cordis'
 import type { IApiClient } from './api.ts'
@@ -16,16 +13,15 @@ import { WebApiClient } from './web-api-client.ts'
 export type {
  ApiProxy, SessionsApi, SessionSummary, HostApi, EventsApi, MuxFrame, HostFrame,
  ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, ToolEventView,
-  ToolCallView, ToolResultView,
+  ToolCallView, ToolResultView, WorkspaceApi, WorkspaceId, WorkspaceView,
  RpcRequest, RpcResponse, RpcResult, RpcError, RpcErrorCode,
  ClientRequest, ServerResponse, ServerRequest, ClientResponse, RpcMessage, RpcReceipt,
  IApiClient, SessionId, SessionEvent, ContentBlock, StreamChunk,
 } from './api.ts'
 export { RpcId, AbstractApiClient, transportError } from './api.ts'

-// ---- Connection loop types (part of the ConnectionHandle.start contract;
-// the controller class itself stays package-internal — apply owns the loop,
-// tests reach it via src) ----
+// Connection loop types are public through ConnectionHandle.start; the
+// controller remains package-internal.
 export type { ConnectionConfig, ConnectionSinks, ConnectionState }


--- a/packages/client/connection/src/index.ts
+++ b/packages/client/connection/src/index.ts
@@ -1,12 +1,6 @@
-/**
- * Connection plugin, node half: the host end of the web transport. Registers
- * the /api prefix route on the web server and bridges node:http requests to
- * the transport-agnostic fetch-shaped api handler. The wire consumer layer
- * lives in the client half (src/client/ — contract: api-contracts v3
- * section 3); consumers import the /client subpath.
- */
+/** Host HTTP bridge for browser-client RPC. */
 import type { Context } from 'cordis'
-// Type-only route import; it also carries the httpServer Context merge.
+// Activates the httpServer Context merge used below.
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
 import { toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
 import { API_PATH } from './api-path.ts'
@@ -14,16 +8,15 @@ import { bridge } from './http-bridge.ts'

 export { API_PATH } from './api-path.ts'

-/** Cordis plugin name. */
+/** Stable Cordis plugin name. */
 export const name = 'client-connection'

-/** Required services: the route registry and the api gateway. */
+/** Services required before mounting the route. */
 export const inject = ['httpServer', 'apiProxy']

 /**
- * Mount the /api transport: wrap the api gateway into a fetch handler and
- * serve it under the /api prefix.
- * @param ctx - host plugin context carrying httpServer and apiProxy.
+ * Mounts the API gateway under the browser transport prefix.
+ * @param ctx - Host plugin context.
 */
 export function apply(ctx: Context): void {
  const apiHandler = toFetchHandler(ctx.apiProxy)
--- a/packages/client/connection/tests/fake-api.ts
+++ b/packages/client/connection/tests/fake-api.ts
@@ -71,6 +71,20 @@ export class FakeApiClient implements IApiClient {
    describe: payload => this.record('host.describe', payload, this.onDescribe(payload)),
  }

+  readonly workspace: IApiClient['workspace'] = {
+    list: (payload: unknown) => this.record('workspace.list', payload, Promise.resolve(ok({ items: [] }))),
+    create: (payload: unknown) => this.record('workspace.create', payload, Promise.resolve(ok({
+      workspace: { workspaceId: 'fk-ws' as never, path: '/f/ws', title: 'ws', sessionIds: [], createdAt: '0', updatedAt: '0' },
+      created: true,
+    }))),
+    rename: (payload: unknown) => this.record('workspace.rename', payload, Promise.resolve(ok({
+      workspace: { workspaceId: 'fk-ws' as never, path: '/f/ws', title: 'ws', sessionIds: [], createdAt: '0', updatedAt: '0' },
+    }))),
+    insertSessionBefore: (payload: unknown) => this.record('workspace.insertSessionBefore', payload, Promise.resolve(ok({
+      workspace: { workspaceId: 'fk-ws' as never, path: '/f/ws', title: 'ws', sessionIds: [], createdAt: '0', updatedAt: '0' },
+    }))),
+  }
+
  /** When true, streams never fire onOpen (misbehaving-carrier material for the handshake timeout guard). */
  suppressStreamOpen = false

--- a/packages/client/connection/tests/fixture.spec.ts
+++ b/packages/client/connection/tests/fixture.spec.ts
@@ -5,7 +5,7 @@
 * the hand-written fixture/host parallel implementations.
 */
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import type { SessionId } from '../src/client/api.ts'
+import type { SessionId, WorkspaceId } from '../src/client/api.ts'
 import { RpcId } from '../src/client/api.ts'
 import type { HostFrame, MuxFrame, RpcMessage, RpcRequest } from '../src/client/api.ts'
 import { FixtureApiClient, createFixtureApi } from '../src/client/fixture.ts'
@@ -87,7 +87,7 @@ describe('createFixtureApi', () => {
    await consuming
    if (!created.result.ok) throw new Error('create failed')
    const createdId = created.result.value.sessionId
-    expect(seen).toEqual([{ type: 'host/session-added', sessionId: createdId }])
+    expect(seen).toEqual([{ type: 'host/session-added', sessionId: createdId, cwd: '/tmp/fixture' }])
    const list = await api.sessions.list(req({}))
    if (!list.result.ok) throw new Error('list failed')
    expect(list.result.value.items.some(s => s.sessionId === createdId)).toBe(true)
@@ -259,6 +259,267 @@ describe('createFixtureApi', () => {
    const api = createFixtureApi()
    const response = await api.host.describe(req({}))
    expect(response.result).toMatchObject({ ok: true, value: { version: '0.0.0-fixture', attachedSessions: 1 } })
+    const empty = await createFixtureApi({ empty: true }).host.describe(req({}))
+    expect(empty.result).toMatchObject({ ok: true, value: { attachedSessions: 0 } })
+  })
+
+  it('workspace.list serves the resident account and create reuses on path collision', async () => {
+    const api = createFixtureApi()
+    const listed = await api.workspace.list(req({}))
+    if (!listed.result.ok) throw new Error('list failed')
+    expect(listed.result.value.items).toEqual([expect.objectContaining({
+      workspaceId: 'fx-ws-fixture', path: '/tmp/fixture', title: 'fixture',
+      sessionIds: ['fx-alpha', 'fx-beta', 'fx-gamma'],
+    })])
+    // path collision → the existing entity comes back, created:false, no frame.
+    const reused = await api.workspace.create(req({ path: '/tmp/fixture' }))
+    if (!reused.result.ok) throw new Error('reuse failed')
+    expect(reused.result.value).toMatchObject({ created: false, workspace: { workspaceId: 'fx-ws-fixture' } })
+  })
+
+  it('workspace.create by name mints a new entity and pushes host/workspace-changed', async () => {
+    const api = createFixtureApi()
+    const abort = new AbortController()
+    const seen: HostFrame[] = []
+    const consuming = (async () => {
+      for await (const envelope of api.events.host(req({}), abort.signal)) {
+        seen.push(envelope.payload)
+        abort.abort()
+      }
+    })()
+    await new Promise(resolve => setTimeout(resolve, 10))
+    const created = await api.workspace.create(req({ name: 'nova' }))
+    if (!created.result.ok) throw new Error('create failed')
+    expect(created.result.value.created).toBe(true)
+    expect(created.result.value.workspace).toMatchObject({
+      path: '/tmp/fixture-workspaces/nova', title: 'nova', sessionIds: [],
+    })
+    await consuming
+    expect(seen).toEqual([{ type: 'host/workspace-changed', workspace: created.result.value.workspace }])
+    // path spelling falls back to the basename when no title/name rides along.
+    const pathOnly = await api.workspace.create(req({ path: '/tmp/fixture-elsewhere/base' }))
+    if (!pathOnly.result.ok) throw new Error('pathOnly failed')
+    expect(pathOnly.result.value.workspace.title).toBe('base')
+    // Degenerate spellings reach the impl unfiltered (the fixture carrier has
+    // no schema gate): both-absent falls back to the bucket dir, and a
+    // basename-less path serves as its own title.
+    const bare = await api.workspace.create(req({}))
+    if (!bare.result.ok) throw new Error('bare failed')
+    expect(bare.result.value.workspace).toMatchObject({ path: '/tmp/fixture-workspaces/', title: 'fixture-workspaces' })
+    const rootPath = await api.workspace.create(req({ path: '/' }))
+    if (!rootPath.result.ok) throw new Error('rootPath failed')
+    expect(rootPath.result.value.workspace.title).toBe('/')
+  })
+
+  it('workspace.rename covers not-found, conflict, no-op, and the changed frame', async () => {
+    const api = createFixtureApi()
+    const abort = new AbortController()
+    const seen: HostFrame[] = []
+    const consuming = (async () => {
+      for await (const envelope of api.events.host(req({}), abort.signal)) {
+        seen.push(envelope.payload)
+        if (seen.length >= 2) abort.abort()
+      }
+    })()
+    await new Promise(resolve => setTimeout(resolve, 10))
+    const wsid = 'fx-ws-fixture' as WorkspaceId
+    const missing = await api.workspace.rename(req({ workspaceId: 'fx-ws-void' as WorkspaceId, title: 'x' }))
+    expect(missing.result).toMatchObject({ ok: false, error: { code: 'workspace-not-found', details: { workspaceId: 'fx-ws-void' } } })
+
+    await api.workspace.create(req({ name: 'occupied' }))
+    const conflict = await api.workspace.rename(req({ workspaceId: wsid, title: ' occupied ' }))
+    expect(conflict.result).toMatchObject({ ok: false, error: { code: 'workspace-name-conflict', details: { name: 'occupied' } } })
+
+    const noop = await api.workspace.rename(req({ workspaceId: wsid, title: ' fixture ' }))
+    if (!noop.result.ok) throw new Error('no-op rename failed')
+    expect(noop.result.value.workspace.title).toBe('fixture')
+
+    const renamed = await api.workspace.rename(req({ workspaceId: wsid, title: 'renamed' }))
+    if (!renamed.result.ok) throw new Error('rename failed')
+    expect(renamed.result.value.workspace.title).toBe('renamed')
+    await consuming
+    // Only the create and the effective rename emit frames; the no-op stays silent.
+    expect(seen.map(f => f.type)).toEqual(['host/workspace-changed', 'host/workspace-changed'])
+  })
+
+  it('workspace.insertSessionBefore moves, appends, no-ops, and rejects invalid ids', async () => {
+    const api = createFixtureApi()
+    const wsid = 'fx-ws-fixture' as WorkspaceId
+    const missing = await api.workspace.insertSessionBefore(req({ workspaceId: 'fx-ws-void' as WorkspaceId, sessionId: sid('fx-alpha') }))
+    expect(missing.result).toMatchObject({ ok: false, error: { code: 'workspace-not-found' } })
+    const ghost = await api.workspace.insertSessionBefore(req({ workspaceId: wsid, sessionId: sid('fx-ghost') }))
+    expect(ghost.result).toMatchObject({ ok: false, error: { code: 'workspace-move-invalid', details: { sessionId: 'fx-ghost' } } })
+    const badAnchor = await api.workspace.insertSessionBefore(req({ workspaceId: wsid, sessionId: sid('fx-alpha'), beforeSessionId: sid('fx-ghost') }))
+    expect(badAnchor.result).toMatchObject({ ok: false, error: { code: 'workspace-move-invalid', details: { beforeSessionId: 'fx-ghost' } } })
+
+    const moved = await api.workspace.insertSessionBefore(req({ workspaceId: wsid, sessionId: sid('fx-gamma'), beforeSessionId: sid('fx-beta') }))
+    if (!moved.result.ok) throw new Error('move failed')
+    expect(moved.result.value.workspace.sessionIds).toEqual(['fx-alpha', 'fx-gamma', 'fx-beta'])
+    const appended = await api.workspace.insertSessionBefore(req({ workspaceId: wsid, sessionId: sid('fx-alpha') }))
+    if (!appended.result.ok) throw new Error('append failed')
+    expect(appended.result.value.workspace.sessionIds).toEqual(['fx-gamma', 'fx-beta', 'fx-alpha'])
+    const before = appended.result.value.workspace.updatedAt
+    const noop = await api.workspace.insertSessionBefore(req({ workspaceId: wsid, sessionId: sid('fx-alpha') }))
+    if (!noop.result.ok) throw new Error('no-op move failed')
+    expect(noop.result.value.workspace.sessionIds).toEqual(['fx-gamma', 'fx-beta', 'fx-alpha'])
+    expect(noop.result.value.workspace.updatedAt).toBe(before)
+  })
+
+  it('session.create({workspaceId}) lands on the account and unknown ids error', async () => {
+    const api = createFixtureApi()
+    const abort = new AbortController()
+    const seen: HostFrame[] = []
+    const consuming = (async () => {
+      for await (const envelope of api.events.host(req({}), abort.signal)) {
+        seen.push(envelope.payload)
+        if (seen.length >= 2) abort.abort()
+      }
+    })()
+    await new Promise(resolve => setTimeout(resolve, 10))
+    const missing = await api.sessions.create(req({ workspaceId: 'fx-ws-void' as WorkspaceId }))
+    expect(missing.result).toMatchObject({ ok: false, error: { code: 'workspace-not-found', details: { workspaceId: 'fx-ws-void' } } })
+    const created = await api.sessions.create(req({ workspaceId: 'fx-ws-fixture' as WorkspaceId }))
+    if (!created.result.ok) throw new Error('create failed')
+    const id = created.result.value.sessionId
+    await consuming
+    // The session lands with the workspace's path as cwd, and the account
+    // write pushes the fresh workspace snapshot after session-added.
+    expect(seen[0]).toEqual({ type: 'host/session-added', sessionId: id, cwd: '/tmp/fixture' })
+    expect(seen[1]).toMatchObject({
+      type: 'host/workspace-changed',
+      workspace: { workspaceId: 'fx-ws-fixture', sessionIds: [id, 'fx-alpha', 'fx-beta', 'fx-gamma'] },
+    })
+  })
+
+  it('supports an empty baseline, preallocated ids, workspace-first frames, and idempotent retry', async () => {
+    const api = createFixtureApi({ empty: true, createFrameOrder: 'workspace-first' })
+    const initialSessions = await api.sessions.list(req({}))
+    const initialWorkspaces = await api.workspace.list(req({}))
+    expect(initialSessions.result).toMatchObject({ ok: true, value: { items: [] } })
+    expect(initialWorkspaces.result).toMatchObject({ ok: true, value: { items: [] } })
+
+    const made = await api.workspace.create(req({ name: 'nova' }))
+    if (!made.result.ok) throw new Error('workspace create failed')
+    const abort = new AbortController()
+    const framesPromise = collect(api.events.host(req({}), abort.signal), abort, frames => frames.length === 2)
+    await new Promise(resolve => setTimeout(resolve, 10))
+    const preallocated = sid('fx-preallocated')
+    const created = await api.sessions.create(req({
+      workspaceId: made.result.value.workspace.workspaceId,
+      sessionId: preallocated,
+    }))
+    expect(created.result).toEqual({ ok: true, value: { sessionId: preallocated } })
+    const frames = await framesPromise
+    expect(frames[0]).toMatchObject({
+      type: 'host/workspace-changed', workspace: { sessionIds: [preallocated] },
+    })
+    expect(frames[1]).toEqual({ type: 'host/session-added', sessionId: preallocated, cwd: made.result.value.workspace.path })
+
+    const retried = await api.sessions.create(req({
+      workspaceId: made.result.value.workspace.workspaceId,
+      sessionId: preallocated,
+    }))
+    expect(retried.result).toEqual({ ok: true, value: { sessionId: preallocated } })
+    const listed = await api.sessions.list(req({}))
+    if (!listed.result.ok) throw new Error('session list failed')
+    expect(listed.result.value.items.filter(item => item.sessionId === preallocated)).toHaveLength(1)
+
+    const conflict = await api.sessions.create(req({ sessionId: preallocated, cwd: '/elsewhere' }))
+    expect(conflict.result).toMatchObject({
+      ok: false,
+      error: { code: 'session-conflict', details: { sessionId: preallocated, requestedCwd: '/elsewhere' } },
+    })
+  })
+
+  it('attaches an existing ungrouped Session to a matching Workspace', async () => {
+    const api = createFixtureApi()
+    const sessionId = sid('fx-existing-ungrouped')
+    await expect(api.sessions.create(req({ sessionId, cwd: '/tmp/fixture' }))).resolves.toMatchObject({
+      result: { ok: true, value: { sessionId } },
+    })
+
+    await expect(api.sessions.create(req({
+      sessionId,
+      workspaceId: 'fx-ws-fixture' as WorkspaceId,
+    }))).resolves.toMatchObject({ result: { ok: true, value: { sessionId } } })
+
+    const workspaces = await api.workspace.list(req({}))
+    if (!workspaces.result.ok) throw new Error('workspace list failed')
+    expect(workspaces.result.value.items[0]?.sessionIds).toContain(sessionId)
+  })
+
+  it('reports a conflict without an existing cwd detail for an unrecorded cwd', async () => {
+    const api = createFixtureApi()
+    const listed = await api.sessions.list(req({}))
+    if (!listed.result.ok) throw new Error('session list failed')
+    const existing = listed.result.value.items.find(item => item.sessionId === sid('fx-alpha'))
+    if (existing === undefined) throw new Error('fixture Session missing')
+    delete existing.cwd
+
+    const conflict = await api.sessions.create(req({ sessionId: existing.sessionId }))
+    expect(conflict.result).toEqual({
+      ok: false,
+      error: {
+        code: 'session-conflict',
+        message: `session ${existing.sessionId} already uses no cwd`,
+        details: { sessionId: existing.sessionId, requestedCwd: '/tmp/fixture' },
+      },
+    })
+  })
+
+  it('publishes an ungrouped Session when Workspace attachment fails', async () => {
+    const api = createFixtureApi({ failWorkspaceAttach: true })
+    const sessionId = sid('fx-partial')
+    const created = await api.sessions.create(req({
+      workspaceId: 'fx-ws-fixture' as WorkspaceId,
+      sessionId,
+    }))
+    expect(created.result).toMatchObject({
+      ok: false,
+      error: { code: 'workspace-attach-failed', details: { sessionId, workspaceId: 'fx-ws-fixture' } },
+    })
+    const listed = await api.sessions.list(req({}))
+    const workspaces = await api.workspace.list(req({}))
+    if (!listed.result.ok || !workspaces.result.ok) throw new Error('list failed')
+    expect(listed.result.value.items.filter(item => item.sessionId === sessionId)).toHaveLength(1)
+    expect(workspaces.result.value.items[0]?.sessionIds).not.toContain(sessionId)
+
+    const retried = await api.sessions.create(req({
+      workspaceId: 'fx-ws-fixture' as WorkspaceId,
+      sessionId,
+    }))
+    expect(retried.result).toMatchObject({ ok: false, error: { code: 'workspace-attach-failed' } })
+    const afterRetry = await api.sessions.list(req({}))
+    if (!afterRetry.result.ok) throw new Error('list failed')
+    expect(afterRetry.result.value.items.filter(item => item.sessionId === sessionId)).toHaveLength(1)
+  })
+
+  it('reconciles a dropped create response and can reject a prompt before acceptance', async () => {
+    const sessionId = sid('fx-lost-response')
+    const dropped = createFixtureApi({ dropSessionCreateResponse: true })
+    await expect(Promise.resolve().then(() => dropped.sessions.create(req({
+      workspaceId: 'fx-ws-fixture' as WorkspaceId,
+      sessionId,
+    })))).rejects.toThrow(/dropped session\.create response/)
+    const listed = await dropped.sessions.list(req({}))
+    const workspaces = await dropped.workspace.list(req({}))
+    if (!listed.result.ok || !workspaces.result.ok) throw new Error('list failed')
+    expect(listed.result.value.items.some(item => item.sessionId === sessionId)).toBe(true)
+    expect(workspaces.result.value.items[0]?.sessionIds).toContain(sessionId)
+    await expect(dropped.sessions.create(req({
+      workspaceId: 'fx-ws-fixture' as WorkspaceId,
+      sessionId,
+    }))).resolves.toMatchObject({ result: { ok: true, value: { sessionId } } })
+
+    const rejecting = createFixtureApi({ empty: true, rejectPrompt: true })
+    const real = await rejecting.sessions.create(req({ sessionId: sid('fx-rejected') }))
+    if (!real.result.ok) throw new Error('session create failed')
+    const prompt = await rejecting.sessions.prompt(req({
+      sessionId: real.result.value.sessionId,
+      mode: 'queue' as const,
+      content: [{ type: 'text' as const, text: 'keep me' }],
+    }))
+    expect(prompt.result).toMatchObject({ ok: false, error: { code: 'agent-busy' } })
  })

  it('timing hooks: history delay + one-shot failure, silent append, and breakStreams end open generators', async () => {
@@ -311,6 +572,7 @@ describe('createFixtureApi', () => {
 describe('FixtureApiClient (protocol-level fake carrier)', () => {
  afterEach(() => {
    vi.restoreAllMocks()
+    vi.unstubAllGlobals()
  })

  it('doFetch is an unreachable tripwire (all protocol paths overridden)', () => {
@@ -346,6 +608,66 @@ describe('FixtureApiClient (protocol-level fake carrier)', () => {
    expect((await client.sessions.prompt({ sessionId: id, mode: 'queue', content: [{ type: 'text', text: '嗨' }] })).result.ok).toBe(true)
    expect((await client.sessions.cancel({ sessionId: id })).result.ok).toBe(true)
    expect((await client.host.describe({})).result.ok).toBe(true)
+    expect((await client.workspace.list({})).result.ok).toBe(true)
+    const workspace = await client.workspace.create({ name: 'via-client' })
+    if (!workspace.result.ok) throw new Error('workspace create failed')
+    expect(workspace.result.value.workspace.title).toBe('via-client')
+    const wsid = workspace.result.value.workspace.workspaceId
+    const renamed = await client.workspace.rename({ workspaceId: wsid, title: 'via-client-2' })
+    if (!renamed.result.ok) throw new Error('workspace rename failed')
+    expect(renamed.result.value.workspace.title).toBe('via-client-2')
+    const attached = await client.sessions.create({ workspaceId: wsid })
+    if (!attached.result.ok) throw new Error('attached create failed')
+    const moved = await client.workspace.insertSessionBefore({ workspaceId: wsid, sessionId: attached.result.value.sessionId })
+    if (!moved.result.ok) throw new Error('workspace move failed')
+    expect(moved.result.value.workspace.sessionIds).toEqual([attached.result.value.sessionId])
+  })
+
+  it('maps empty, prompt-reject, and workspace-first query scenarios', async () => {
+    vi.stubGlobal('location', {
+      search: '?fixture=empty&fixturePrompt=reject&fixtureFrames=workspace-first',
+    })
+    const client = new FixtureApiClient()
+    await expect(client.sessions.list({})).resolves.toMatchObject({ result: { ok: true, value: { items: [] } } })
+    const made = await client.workspace.create({ name: 'query-workspace' })
+    if (!made.result.ok) throw new Error('workspace create failed')
+    const abort = new AbortController()
+    const framesPromise = collect(client.events.host({}, abort.signal), abort, frames => frames.length === 2)
+    await new Promise(resolve => setTimeout(resolve, 10))
+    const sessionId = sid('fx-query-session')
+    const created = await client.sessions.create({
+      workspaceId: made.result.value.workspace.workspaceId,
+      sessionId,
+    })
+    expect(created.result).toMatchObject({ ok: true, value: { sessionId } })
+    const frames = await framesPromise
+    expect(frames.map(frame => frame.type)).toEqual(['host/workspace-changed', 'host/session-added'])
+    const rejected = await client.sessions.prompt({
+      sessionId,
+      mode: 'queue',
+      content: [{ type: 'text', text: 'retain' }],
+    })
+    expect(rejected.result).toMatchObject({ ok: false, error: { code: 'agent-busy' } })
+  })
+
+  it('maps attach-failure and dropped-response query scenarios', async () => {
+    vi.stubGlobal('location', { search: '?fixture&fixtureAttach=fail' })
+    const partial = new FixtureApiClient()
+    const partialResult = await partial.sessions.create({
+      workspaceId: 'fx-ws-fixture' as WorkspaceId,
+      sessionId: sid('fx-query-partial'),
+    })
+    expect(partialResult.result).toMatchObject({
+      ok: false,
+      error: { code: 'workspace-attach-failed', details: { sessionId: 'fx-query-partial' } },
+    })
+
+    vi.stubGlobal('location', { search: '?fixture&fixtureSessionCreate=drop-response' })
+    const dropped = new FixtureApiClient()
+    await expect(dropped.sessions.create({
+      workspaceId: 'fx-ws-fixture' as WorkspaceId,
+      sessionId: sid('fx-query-dropped'),
+    })).rejects.toThrow(/dropped session\.create response/)
  })

  it('fires onOpen at stream-iteration start and taps server-request full forms', async () => {
--- a/packages/client/hmr/README.i18n.yaml
+++ b/packages/client/hmr/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: 2b2f63c25cbf3a46babef78a4dfb52f859156887
+README.zh.md: 6d94ca4a5e91f390e58575aa4ddf64fc18a509de
--- a/packages/client/hmr/README.md
+++ b/packages/client/hmr/README.md
@@ -1,5 +1,7 @@
 # @deepseek-ai/dsh-client-hmr

+English | [中文](README.zh.md)
+
 Hot reload for fetch-arrival client plugins. A static-arrival entry composed only into `--dev` graphs (`dsh web --dev`); production graphs omit the row, so the shell-bundled code stays inert.

 The browser half subscribes to the system SSE channel (`GET /plugins/events`) and reloads one plugin per `rebuilt` frame, serialized through a queue (the bundle handoff slot is single). The sequence per frame — `prefetch` (fetch the new bundle before touching anything), `invalidate`, `registry.delete` (before the fiber: a bare fiber dispose trips the vendored Loader's self-dispose branch, which would mark the entry disabled), drain the old fiber, delete `entry.fiber`, remove owned `<style data-plugin>` tags, `entry.refresh()` re-imports and remounts, `fiber.await()` rethrows startup failures loud. Dependents reload through cordis itself: a fiber's activation epoch strings its service providers' uids, so replacing a provider's fiber cascades every dependent with zero client-side graph analysis. The node half detects rebuilds with one interval that stat-polls each graph bundle from a synchronous baseline, immediately re-hashes after adding a row, retains missing rows as dirty, and broadcasts only real rev changes; any tsdown watch process producing the bundle therefore triggers HMR with no builder→host channel.
--- a/packages/client/hmr/README.zh.md
+++ b/packages/client/hmr/README.zh.md
@@ -0,0 +1,21 @@
+# @deepseek-ai/dsh-client-hmr
+
+[English](README.md) | 中文
+
+为通过 fetch 到达的客户端插件提供热重载。该静态到达配置项只组合进 `--dev` 图（`dsh web --dev`）；生产图省略此行，因此外壳打包的代码保持不活动。
+
+浏览器侧订阅系统 SSE 通道（`GET /plugins/events`），每个 `rebuilt` 帧重载一个插件，并通过队列串行执行（组合包交接 slot 只能容纳一个）。每帧的顺序是：`prefetch`（在触碰任何内容前抓取新组合包）、`invalidate`、`registry.delete`（在 fiber 之前执行：只释放 fiber 会触发 vendored Loader 的 self-dispose 分支，把配置项标为禁用）、排空旧 fiber、删除 `entry.fiber`、移除自身拥有的 `<style data-plugin>` 标签、通过 `entry.refresh()` 重新导入并挂载、以 `fiber.await()` 将启动失败高声重新抛出。依赖方由 cordis 自身重载：fiber 的激活 epoch 会串联其服务提供方的 uid，因此替换提供方 fiber 会级联所有依赖方，无需客户端图分析。node 侧使用一个 interval 检测重建：从同步基线开始 stat-poll 每个图组合包；新增一行后立即重新计算 hash；缺失行保持 dirty；只广播真实 rev 变更。因此，任何生成组合包的 tsdown watch 进程都能触发 HMR，无需 builder→host 通道。
+
+## 模型体验
+
+无。重载驱动器属于浏览器侧机制；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **重载有意保持粗粒度**：会创建全新的 fiber 和组件；重载插件中的 React 状态会丢失，数据层（connection/runtime fiber、Session 对象）不受影响。react-refresh 级状态保留与「重新执行组合包会重新运行 factory」冲突，因此有意排除。
+- **失败时不回滚**：失败的重载会使配置项处于 FAILED 状态，并在 loader 状态投影中高声报告；自动恢复先前组合包会等到实际需要出现后再实现。
+- **重建帧不会刷新图 rev**：陈旧 rev 无害（组合包端点以 no-cache 提供内容）；rev 刷新会随重新连接握手机制落地。
--- a/packages/client/i18n/README.md
+++ b/packages/client/i18n/README.md
@@ -1,16 +0,0 @@
-# @deepseek-ai/dsh-client-i18n
-
-i18n plugin: I18nService (ns×locale dictionaries, bind(ns)→t with a stable function identity, locale store). Contract: api-contracts v3 §8.
-
-## Model Experience
-
-None, as the i18n registry serves browser UI copy; nothing here reaches a model request.
-
-#### KV Cache effect
-
-None; this package neither assembles nor sends a provider request.
-
-## Known Limitations and Deferred Work
-
- **zh/en ship as empty structures** — the existing UI copy is inline Chinese; extraction into dictionaries is deferred repo-wide work, so `bind(ns)` consumers today mostly receive key-echo fallbacks.
- **Locale switching re-renders the whole tree** — accepted as a low-frequency operation; no per-namespace subscription granularity.
--- a/packages/client/i18n/src/client/index.ts
+++ b/packages/client/i18n/src/client/index.ts
@@ -1,113 +0,0 @@
-/**
- * i18n plugin, browser half: namespace x locale dictionary registry with a
- * bound translate function whose reference is stable (safe for inject
- * surfaces). Mounts ctx.i18n and seeds the zh/en base dictionaries.
- * Contract: api-contracts v3 section 8.
- */
-import type { Context } from 'cordis'
-// The snapshot-store engine lives in runtime (store relocation): framework
-// data stores like this locale cell use it directly. The store carries no
-// hook — a React consumer binds a selector hook via web-react's
-// bindSnapshotSelector at its own seam (none exists today; the current
-// consumers are translate() reads and test-side subscribe/set).
-import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
-import { en } from '../locales/en.ts'
-import { zh } from '../locales/zh.ts'
-
-/** Translate a key with optional params. */
-export type Translate = (key: string, params?: Record<string, unknown>) => string
-
-/** Locale dictionary: flat key to template string ({name} placeholders). */
-export type LocaleDict = Record<string, string>
-
-declare module 'cordis' {
-  interface Context {
-    i18n: I18nService
-  }
-}
-
-/** Fallback locale consulted after the active locale misses. */
-export const FALLBACK_LOCALE = 'zh'
-
-/** Shared namespace for shell-level texts. */
-export const COMMON_NS = 'common'
-
-/**
- * Dictionary registry plus locale switch. Lookup chain per key: active locale
- * -> zh fallback -> the key itself (missing text stays visible, fail loud in
- * the UI rather than blank).
- */
-export class I18nService {
-  private dicts = new Map<string, Map<string, LocaleDict>>()
-  private bound = new Map<string, Translate>()
-  private localeStore = createSnapshotStore<string>(FALLBACK_LOCALE)
-
-  /**
-   * Register a dictionary for a namespace and locale. Duplicate (ns, locale)
-   * throws (single occupant; a namespace's texts have one owner).
-   * @param ns - namespace.
-   * @param locale - locale tag (zh/en to start).
-   * @param dict - dictionary.
-   * @returns disposer (idempotent).
-   */
-  register(ns: string, locale: string, dict: LocaleDict): () => void {
-    let locales = this.dicts.get(ns)
-    if (!locales) {
-      locales = new Map()
-      this.dicts.set(ns, locales)
-    }
-    if (locales.has(locale)) throw new Error(`i18n namespace "${ns}" already has locale "${locale}"`)
-    locales.set(locale, dict)
-    return () => {
-      const owner = this.dicts.get(ns)
-      if (owner?.get(locale) === dict) owner.delete(locale)
-    }
-  }
-
-  /**
-   * Bind a namespace to a translate function. The returned reference is
-   * stable per namespace (repeat binds return the same function), so it can
-   * ride inject surfaces without breaking memoization.
-   * @param ns - namespace.
-   * @returns the translate function (reads the locale store at call time).
-   */
-  bind(ns: string): Translate {
-    let t = this.bound.get(ns)
-    if (!t) {
-      t = (key, params) => this.translate(ns, key, params)
-      this.bound.set(ns, t)
-      return t
-    }
-    return t
-  }
-
-  /** Active locale store (switching re-renders the tree; low frequency). */
-  get locale(): SnapshotStore<string> {
-    return this.localeStore
-  }
-
-  private translate(ns: string, key: string, params?: Record<string, unknown>): string {
-    const locales = this.dicts.get(ns)
-    const template = locales?.get(this.localeStore.getSnapshot())?.[key]
-      ?? locales?.get(FALLBACK_LOCALE)?.[key]
-      ?? key
-    if (!params) return template
-    return template.replace(/\{(\w+)\}/g, (match, name: string) =>
-      name in params ? String(params[name]) : match)
-  }
-}
-
-/** Required services (none; the loader passes the export surface as an object plugin). */
-export const inject: string[] = []
-
-/**
- * Client plugin body: provide the i18n service with base dictionaries.
- * @param ctx - client cordis context.
- */
-export function apply(ctx: Context): void {
-  const i18n = new I18nService()
-  i18n.register(COMMON_NS, 'zh', zh)
-  i18n.register(COMMON_NS, 'en', en)
-  ctx.provide('i18n', i18n)
-}
--- a/packages/client/i18n/src/index.ts
+++ b/packages/client/i18n/src/index.ts
@@ -1,11 +0,0 @@
-/**
- * i18n plugin, node half. Pure UI plugin: the empty apply exists so the
- * plugin appears in the host cordis.yml / Loader (load and lifecycle follow
- * the host; the browser half ships via exports["./client"], discovered
- * through the package.json dshClient declaration). Everything else —
- * I18nService, Translate, LocaleDict — lives in the client half; consumers
- * import the /client subpath. Contract: api-contracts v3 section 8.
- */
-
-/** Host plugin body — no host-side behavior for the i18n plugin. */
-export function apply(): void {}
--- a/packages/client/i18n/tests/i18n.spec.ts
+++ b/packages/client/i18n/tests/i18n.spec.ts
@@ -1,53 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { I18nService } from '@deepseek-ai/dsh-client-i18n/client'
-
-describe('I18nService', () => {
-  it('translates from the active locale with zh fallback then key passthrough', () => {
-    const i18n = new I18nService()
-    i18n.register('ns', 'zh', { hello: '你好', onlyZh: '仅中文' })
-    i18n.register('ns', 'en', { hello: 'Hello' })
-    const t = i18n.bind('ns')
-    expect(i18n.locale.getSnapshot()).toBe('zh')
-    expect(t('hello')).toBe('你好')
-    i18n.locale.set('en')
-    expect(t('hello')).toBe('Hello')
-    expect(t('onlyZh')).toBe('仅中文')
-    expect(t('missing.key')).toBe('missing.key')
-  })
-
-  it('interpolates {name} params and leaves unknown placeholders intact', () => {
-    const i18n = new I18nService()
-    i18n.register('ns', 'zh', { greet: '你好，{name}！第 {n} 次', partial: '{known} 与 {unknown}' })
-    const t = i18n.bind('ns')
-    expect(t('greet', { name: '世界', n: 2 })).toBe('你好，世界！第 2 次')
-    expect(t('partial', { known: 'A' })).toBe('A 与 {unknown}')
-    expect(t('greet')).toBe('你好，{name}！第 {n} 次')
-  })
-
-  it('bind returns a stable reference per namespace', () => {
-    const i18n = new I18nService()
-    expect(i18n.bind('a')).toBe(i18n.bind('a'))
-    expect(i18n.bind('a')).not.toBe(i18n.bind('b'))
-  })
-
-  it('duplicate (ns, locale) throws; disposer unregisters and is idempotent', () => {
-    const i18n = new I18nService()
-    const dispose = i18n.register('ns', 'zh', { k: 'v1' })
-    expect(() => i18n.register('ns', 'zh', { k: 'v2' })).toThrow('already has locale')
-    dispose()
-    dispose()
-    const t = i18n.bind('ns')
-    expect(t('k')).toBe('k')
-    i18n.register('ns', 'zh', { k: 'v2' })
-    expect(t('k')).toBe('v2')
-  })
-
-  it('locale store is subscribable (snapshot store contract)', () => {
-    const i18n = new I18nService()
-    let notified = 0
-    i18n.locale.subscribe(() => { notified += 1 })
-    i18n.locale.set('en')
-    expect(i18n.locale.getSnapshot()).toBe('en')
-    expect(notified).toBe(1)
-  })
-})
--- a/packages/client/i18n/tests/invariant.spec.ts
+++ b/packages/client/i18n/tests/invariant.spec.ts
@@ -1,30 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { Context } from 'cordis'
-import { apply as nodeApply } from '@deepseek-ai/dsh-client-i18n'
-import { apply as clientApply, COMMON_NS, I18nService, inject } from '@deepseek-ai/dsh-client-i18n/client'
-import * as I18nInvariant from '@deepseek-ai/dsh-client-i18n/invariant'
-import InvariantService from '@deepseek-ai/dsh-invariants'
-
-describe('invariant companion', () => {
-  it('registers under the package name with an empty installer', async () => {
-    const ctx = new Context()
-    await ctx.plugin(InvariantService, { enabled: true })
-    await expect(ctx.plugin(I18nInvariant).await()).resolves.toBeDefined()
-  })
-
-  it('node-half apply is a no-op host placeholder', () => {
-    nodeApply()
-    expect(true).toBe(true) // reaching here without throw is the contract
-  })
-
-  it('client apply provides ctx.i18n seeded with the zh/en common namespace', async () => {
-    expect(inject).toEqual([])
-    const ctx = new Context()
-    await ctx.plugin({ inject, apply: clientApply }).await()
-    const i18n = ctx.get('i18n')
-    expect(i18n).toBeInstanceOf(I18nService)
-    // Seeded dictionaries occupy the (ns, locale) seats even while empty.
-    expect(() => (i18n as I18nService).register(COMMON_NS, 'zh', {})).toThrow('already has locale')
-    expect(() => (i18n as I18nService).register(COMMON_NS, 'en', {})).toThrow('already has locale')
-  })
-})
--- a/packages/client/i18n/tsdown.config.ts
+++ b/packages/client/i18n/tsdown.config.ts
@@ -1,3 +0,0 @@
-import { clientBundle } from '../tsdown.client.ts'
-
-export default clientBundle('@deepseek-ai/dsh-client-i18n', ['lib/types/index.js', 'lib/types/invariant.js'])
--- a/packages/client/locale/README.i18n.yaml
+++ b/packages/client/locale/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: 9015af2b44a33771b06863ace139fe97695df616
+README.zh.md: 6b129bcabbef5b5a00c5073ebc9142a0e406ddba
--- a/packages/client/locale/README.md
+++ b/packages/client/locale/README.md
@@ -0,0 +1,18 @@
+# @deepseek-ai/dsh-client-locale
+
+English | [中文](README.zh.md)
+
+Locale plugin: LocaleService — the browser locale preference (`zh`/`en`, persisted under `dsh.locale`, getter/setter with `locale/change` snapshots) plus the ns×locale dictionary registry (`bind(ns)`→t with a stable function identity; lookup chain active → zh → key).
+
+## Model Experience
+
+None, as the locale registry serves browser UI copy; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Only the Settings surface is translated** — other pages keep inline copy; repo-wide extraction into dictionaries is deferred.
+- **Locale switching re-renders subscribed consumers only** — sections not wired to `locale/change` keep their rendered text until remount.
--- a/packages/client/locale/README.zh.md
+++ b/packages/client/locale/README.zh.md
@@ -0,0 +1,18 @@
+# @deepseek-ai/dsh-client-locale
+
+[English](README.md) | 中文
+
+locale 插件：LocaleService 包含浏览器 locale 偏好（`zh`／`en`，以 `dsh.locale` 为键持久化；提供 getter／setter，并生成 `locale/change` 快照），以及 ns×locale 字典注册表（`bind(ns)`→t 的函数标识稳定；查找链为 active → zh → key）。
+
+## 模型体验
+
+无。locale 注册表为浏览器 UI 文案提供服务；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **只有设置界面完成翻译**：其他页面仍保留内联文案；将全仓文案提取到字典的工作暂缓。
+- **切换 locale 只重新渲染已订阅的消费方**：未接入 `locale/change` 的分区会保留已渲染文本，直到重新挂载。
--- a/packages/client/locale/package.json
+++ b/packages/client/locale/package.json
@@ -0,0 +1,62 @@
+{
+  "name": "@deepseek-ai/dsh-client-locale",
+  "description": "Locale plugin: LocaleService (zh/en preference with getter/setter/change event + persistence; ns x locale dictionaries, bind(ns) -> t); registers the Language settings row",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-client-runtime"
+    ],
+    "platform": "web",
+    "immediately": true
+  },
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}
--- a/packages/client/locale/src/client/LanguageRow.module.css
+++ b/packages/client/locale/src/client/LanguageRow.module.css
@@ -0,0 +1,47 @@
+/* Language row (figma 'Setting-Cell': gap 8, pad 16/0, hairline separator;
+ * the section column removes the separator on its last child). */
+
+.row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 16px 0;
+  border-bottom: 1px solid var(--dsw-alias-border-l2);
+}
+
+.rowText {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding-right: 48px;
+}
+
+.title {
+  font-size: 14px;
+  font-weight: 400;
+  line-height: 22px;
+  color: var(--dsw-alias-label-primary);
+}
+
+/* Selector pill (figma 'Selector': h36 r18, fill #F5F6F7, pad 0/14, gap 12). */
+.selector {
+  display: inline-flex;
+  align-items: center;
+  gap: 12px;
+  height: 36px;
+  padding: 0 14px;
+  border: none;
+  border-radius: 18px;
+  background: var(--dsw-alias-bg-module-platform);
+  font: inherit;
+  font-size: 14px;
+  line-height: 22px;
+  color: var(--dsw-alias-label-primary);
+  cursor: pointer;
+}
+
+.chevron {
+  flex: none;
+}
--- a/packages/client/locale/src/client/LanguageRow.tsx
+++ b/packages/client/locale/src/client/LanguageRow.tsx
@@ -0,0 +1,68 @@
+/**
+ * Language preference row registered into the General section item slot
+ * (figma 501:30011 'Setting-Cell'): title + selector pill opening the locale
+ * menu. Registered by this package — the locale feature owns its own
+ * settings surface.
+ */
+import { useState } from 'react'
+import type { PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots'
+import { IconChevronDownOutline14, Menu } from '@deepseek-ai/dsh-client-ui-primitives'
+import type {} from './settings-contract.ts'
+import type { createLanguageRowStore } from './settings-store.ts'
+import css from './LanguageRow.module.css'
+
+/** Injected business face: namespace-bound translate + the preference write. */
+export interface LanguageRowInjected {
+  /** Translate a `settings.locale` dictionary key to the active-locale text. */
+  t: (key: string) => string
+  /** Switch the active locale (a registered locale id). */
+  setLocale: (id: string) => void
+}
+
+/** Full component props: runtime share + store share + injected face. */
+export type LanguageRowComponentProps =
+  PropsRuntime<'settings.general.item'> & PropsStore<ReturnType<typeof createLanguageRowStore>> & LanguageRowInjected
+
+/**
+ * Render the Language row.
+ * @param props - composed slot props.
+ * @returns the row element tree.
+ */
+export function LanguageRow({ t, setLocale, useStore }: LanguageRowComponentProps) {
+  const active = useStore(s => s.active)
+  const options = useStore(s => s.options)
+  const [open, setOpen] = useState(false)
+  const activeLabel = options.find(o => o.id === active)?.label ?? active
+
+  return (
+    <div className={css.row}>
+      <div className={css.rowText}>
+        <div className={css.title}>{t('language.title')}</div>
+      </div>
+      <Menu
+        open={open}
+        onClose={() => { setOpen(false) }}
+        items={options.map(o => ({ id: o.id, label: o.label }))}
+        selectedId={active}
+        onSelect={(id) => {
+          setLocale(id)
+          setOpen(false)
+        }}
+        align="end"
+        portal
+        anchor={(
+          <button
+            type="button"
+            className={css.selector}
+            aria-haspopup="menu"
+            aria-expanded={open}
+            onClick={() => { setOpen(v => !v) }}
+          >
+            {activeLabel}
+            <IconChevronDownOutline14 className={css.chevron} />
+          </button>
+        )}
+      />
+    </div>
+  )
+}
--- a/packages/client/locale/src/client/index.ts
+++ b/packages/client/locale/src/client/index.ts
@@ -0,0 +1,248 @@
+/**
+ * Browser-side locale registry. Bound translation functions retain stable
+ * identity for injected consumers. The plugin also registers the Language
+ * preference row into the settings General section — the locale feature owns
+ * its own settings surface.
+ */
+import type { Context } from 'cordis'
+import { deferRegistration, type BoundActions } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import { en } from '../locales/en.ts'
+import { zh } from '../locales/zh.ts'
+import type { LanguageRowInjected } from './LanguageRow.tsx'
+import { LanguageRow } from './LanguageRow.tsx'
+import { createLanguageRowStore } from './settings-store.ts'
+
+export type { LanguageRowComponentProps, LanguageRowInjected } from './LanguageRow.tsx'
+export type { LanguageOptionRow, LanguageRowState } from './settings-store.ts'
+export type { SettingsGeneralItemOwnerProps } from './settings-contract.ts'
+
+/** Translate a key with optional params. */
+export type Translate = (key: string, params?: Record<string, unknown>) => string
+
+/** Locale dictionary: flat key to template string ({name} placeholders). */
+export type LocaleDict = Record<string, string>
+
+/** Locale identifier: the two shipped locales. */
+export type LocaleId = 'zh' | 'en'
+
+/** One selectable locale: id plus its self-described display name. */
+export interface LocaleDefinition {
+  /** Locale id (persisted; the setLocale argument). */
+  id: LocaleId
+  /** Display name in its own language (中文 / English). */
+  label: string
+}
+
+/** Immutable locale state published on every change. */
+export interface LocaleSnapshot {
+  /** Active locale id. */
+  active: LocaleId
+  /** Selectable locales in display order. */
+  locales: readonly LocaleDefinition[]
+  /** Monotonic change counter (registry or active changes). */
+  revision: number
+}
+
+declare module 'cordis' {
+  interface Context {
+    locale: LocaleService
+  }
+  interface Events {
+    /**
+     * Locale state changed (active locale switched or registry updated).
+     * @param snapshot - Current immutable locale snapshot.
+     * @mode emit
+     */
+    'locale/change'(snapshot: LocaleSnapshot): void
+  }
+}
+
+/** Fallback locale consulted after the active locale misses (also the default). */
+export const FALLBACK_LOCALE: LocaleId = 'zh'
+
+/** Shared namespace for shell-level texts. */
+export const COMMON_NS = 'common'
+
+/** Namespace owning this feature's settings-row copy. */
+export const SETTINGS_NS = 'settings.locale'
+
+/** localStorage key holding the persisted locale id. */
+export const STORAGE_KEY = 'dsh.locale'
+
+/** The two shipped locales. */
+const LOCALES: readonly LocaleDefinition[] = Object.freeze([
+  { id: 'zh', label: '中文' },
+  { id: 'en', label: 'English' },
+])
+
+/**
+ * Dictionary registry plus locale preference. Lookup chain per key: active
+ * locale -> zh fallback -> the key itself (missing text stays visible, fail
+ * loud in the UI rather than blank). Reads go through {@link getLocale};
+ * writes only through {@link setLocale}; continuous sync only through the
+ * `locale/change` event.
+ */
+export class LocaleService {
+  private dicts = new Map<string, Map<string, LocaleDict>>()
+  private bound = new Map<string, Translate>()
+  private snapshot: LocaleSnapshot
+  private readonly ctx: Context
+
+  /**
+   * @param ctx - owning context (change events are emitted on it).
+   */
+  constructor(ctx: Context) {
+    this.ctx = ctx
+    this.snapshot = Object.freeze({ active: restorePreference(), locales: LOCALES, revision: 0 })
+  }
+
+  /**
+   * Read the current immutable locale snapshot.
+   * @returns the current snapshot (stable reference until the next change).
+   */
+  getLocale(): LocaleSnapshot {
+    return this.snapshot
+  }
+
+  /**
+   * Switch the active locale — the only preference write entry. Persists the
+   * id and emits `locale/change`.
+   * @param id - a registered locale id; unknown ids throw.
+   */
+  setLocale(id: string): void {
+    const match = this.snapshot.locales.find(l => l.id === id)
+    if (match === undefined) throw new Error(`locale "${id}" is not registered`)
+    if (this.snapshot.active === match.id) return
+    this.snapshot = Object.freeze({
+      active: match.id,
+      locales: this.snapshot.locales,
+      revision: this.snapshot.revision + 1,
+    })
+    persistPreference(match.id)
+    this.ctx.emit('locale/change', this.snapshot)
+  }
+
+  /**
+   * Register a dictionary for a namespace and locale. Duplicate (ns, locale)
+   * throws (single occupant; a namespace's texts have one owner).
+   * @param ns - namespace.
+   * @param locale - locale tag (zh/en to start).
+   * @param dict - dictionary.
+   * @returns disposer (idempotent).
+   */
+  register(ns: string, locale: string, dict: LocaleDict): () => void {
+    let locales = this.dicts.get(ns)
+    if (!locales) {
+      locales = new Map()
+      this.dicts.set(ns, locales)
+    }
+    if (locales.has(locale)) throw new Error(`locale namespace "${ns}" already has locale "${locale}"`)
+    locales.set(locale, dict)
+    return () => {
+      const owner = this.dicts.get(ns)
+      if (owner?.get(locale) === dict) owner.delete(locale)
+    }
+  }
+
+  /**
+   * Bind a namespace to a translate function. The returned reference is
+   * stable per namespace (repeat binds return the same function), so it can
+   * ride inject surfaces without breaking memoization.
+   * @param ns - namespace.
+   * @returns the translate function (reads the active locale at call time).
+   */
+  bind(ns: string): Translate {
+    let t = this.bound.get(ns)
+    if (!t) {
+      t = (key, params) => this.translate(ns, key, params)
+      this.bound.set(ns, t)
+      return t
+    }
+    return t
+  }
+
+  private translate(ns: string, key: string, params?: Record<string, unknown>): string {
+    const locales = this.dicts.get(ns)
+    const template = locales?.get(this.snapshot.active)?.[key]
+      ?? locales?.get(FALLBACK_LOCALE)?.[key]
+      ?? key
+    if (!params) return template
+    return template.replace(/\{(\w+)\}/g, (match, name: string) =>
+      name in params ? String(params[name]) : match)
+  }
+}
+
+/** Read the persisted locale id; unknown or unreadable values fall back to zh. */
+function restorePreference(): LocaleId {
+  // Non-browser runs (node e2e booting the client tree) have no localStorage.
+  if (typeof localStorage === 'undefined') return FALLBACK_LOCALE
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY)
+    if (stored === 'zh' || stored === 'en') return stored
+  } catch {
+    // Storage access can throw (privacy mode); the default below covers it.
+  }
+  return FALLBACK_LOCALE
+}
+
+/** Persist the locale id; storage failures are non-fatal (preference resets next boot). */
+function persistPreference(id: LocaleId): void {
+  if (typeof localStorage === 'undefined') return
+  try {
+    localStorage.setItem(STORAGE_KEY, id)
+  } catch {
+    // Storage access can throw (privacy mode / quota); the preference simply
+    // does not survive the session.
+  }
+}
+
+/** Required services: the slot registry (the feature registers its own settings row). */
+export const inject = ['slots']
+
+/**
+ * Client plugin body: provide the locale service with base dictionaries and
+ * register the feature-owned Language preference row into the General
+ * section's item slot (a feature owns its settings surface).
+ * @param ctx - client cordis context.
+ */
+export function apply(ctx: ClientContext): void {
+  const locale = new LocaleService(ctx)
+  locale.register(COMMON_NS, 'zh', zh)
+  locale.register(COMMON_NS, 'en', en)
+  locale.register(SETTINGS_NS, 'zh', { 'language.title': '语言' })
+  locale.register(SETTINGS_NS, 'en', { 'language.title': 'Language' })
+  ctx.provide('locale', locale)
+
+  const store = createLanguageRowStore()
+  let bound: BoundActions<typeof store> | undefined
+  const sync = (snapshot: LocaleSnapshot): void => {
+    bound?.sync(
+      snapshot.active,
+      snapshot.locales.map(l => ({ id: l.id, label: l.label })),
+      snapshot.revision,
+    )
+  }
+  ctx.on('locale/change', sync)
+  const injected = (actions: BoundActions<typeof store>): LanguageRowInjected => {
+    bound = actions
+    // Re-sync from the getter so no event is lost between registration and
+    // first render (the store's revision guard drops stale duplicates).
+    sync(locale.getLocale())
+    return {
+      t: locale.bind(SETTINGS_NS),
+      setLocale: (id) => { locale.setLocale(id) },
+    }
+  }
+  ctx.effect(() => {
+    const deferred = deferRegistration(ctx.slots, 'settings.general.item', LanguageRow, () =>
+      ctx.slots.register({
+        name: 'settings.general.item',
+        id: 'language',
+        order: 0,
+        store,
+        inject: injected,
+      }, LanguageRow))
+    return () => { deferred.dispose() }
+  }, 'locale: language settings row registration')
+}
--- a/packages/client/locale/src/client/settings-contract.ts
+++ b/packages/client/locale/src/client/settings-contract.ts
@@ -0,0 +1,26 @@
+/**
+ * The `settings.general.item` slot type — one preference row inside the
+ * settings General section, contributed by the feature plugin that owns the
+ * preference (locale → Language, ui-theme → Appearance). Options: `id` (row
+ * key), `order` (row position). Rows draw their own internals (row layout,
+ * separators via CSS); the section column only stacks them.
+ *
+ * TYPE HOME RATIONALE: the slot is declared at runtime by
+ * ui-settings-general's General entry, but its type lives here — this
+ * package is the common dependency of every item registrant (any settings
+ * row carries copy, so every registrant already depends on locale), whereas
+ * the declarer's own contract is unreachable for locale/ui-theme without a
+ * reference cycle.
+ */
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    /** One preference row inside the settings General section (see module JSDoc). */
+    'settings.general.item': { kind: 'list'; scope: 'root'; owner: SettingsGeneralItemOwnerProps }
+  }
+}
+
+/** Owner share of a General preference row (the section supplies nothing). */
+export interface SettingsGeneralItemOwnerProps {
+  /** Marker field: item owner props are intentionally empty. */
+  children?: never
+}
--- a/packages/client/locale/src/client/settings-store.ts
+++ b/packages/client/locale/src/client/settings-store.ts
@@ -0,0 +1,47 @@
+/**
+ * Language row slot store: a mirror of the locale service snapshot. The
+ * plugin's apply-world change listener is the only writer; the row component
+ * reads via props.useStore.
+ */
+import { defineStore, type EngineStoreHandle } from '@deepseek-ai/dsh-client-runtime/client'
+
+/** One selectable locale row (id + self-described label). */
+export interface LanguageOptionRow {
+  /** Locale id (the setLocale argument). */
+  id: string
+  /** Display name in its own language (中文 / English). */
+  label: string
+}
+
+/** Store state mirrored from the locale snapshot. */
+export interface LanguageRowState {
+  /** Active locale id. */
+  active: string
+  /** Selectable locales in display order. */
+  options: LanguageOptionRow[]
+  /** Service revision; -1 until first sync so revision 0 lands as a change. */
+  revision: number
+}
+
+/** Declared action shape giving the exported factory a stable return type. */
+type LanguageRowActions = {
+  sync: (draft: LanguageRowState, active: string, options: LanguageOptionRow[], revision: number) => void
+}
+
+/**
+ * Declares the Language row state and write surface.
+ * @returns the store handle.
+ */
+export function createLanguageRowStore(): EngineStoreHandle<LanguageRowState, LanguageRowActions> {
+  return defineStore({
+    init: (): LanguageRowState => ({ active: '', options: [], revision: -1 }),
+    actions: {
+      sync: (d, active: string, options: LanguageOptionRow[], revision: number) => {
+        if (revision <= d.revision) return
+        d.active = active
+        d.options = options
+        d.revision = revision
+      },
+    },
+  })
+}
--- a/packages/client/locale/src/css-modules.d.ts
+++ b/packages/client/locale/src/css-modules.d.ts
@@ -0,0 +1,6 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css'
--- a/packages/client/locale/src/index.ts
+++ b/packages/client/locale/src/index.ts
@@ -0,0 +1,4 @@
+/** Host loader entry for the browser implementation exported from `./client`. */
+
+/** Host plugin body — no host-side behavior for the locale plugin. */
+export function apply(): void {}
--- a/packages/client/locale/src/invariant.ts
+++ b/packages/client/locale/src/invariant.ts
@@ -1,16 +1,16 @@
 /**
- * Package-owned invariant companion for `@deepseek-ai/dsh-client-i18n`.
- * @module @deepseek-ai/dsh-client-i18n/invariant
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-locale`.
+ * @module @deepseek-ai/dsh-client-locale/invariant
 */

 /* jscpd:ignore-start */
 import type { Context } from 'cordis'
 import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'

-const PACKAGE_NAME = '@deepseek-ai/dsh-client-i18n'
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-locale'

 /** Cordis companion plugin name. */
-export const name = 'client-i18n-invariant'
+export const name = 'client-locale-invariant'
 /** Service required before the companion can reserve package ownership. */
 export const inject = ['invariants']

--- a/packages/client/locale/src/locales/en.ts
+++ b/packages/client/locale/src/locales/en.ts
--- a/packages/client/locale/src/locales/zh.ts
+++ b/packages/client/locale/src/locales/zh.ts
--- a/packages/client/locale/tests/apply.spec.ts
+++ b/packages/client/locale/tests/apply.spec.ts
@@ -0,0 +1,116 @@
+/** locale apply wiring: service + dictionaries provision, declaration-aware
+ * Language row registration, snapshot projection into the row store, and
+ * recovery after an HMR collapse of the declaring entry. */
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { apply, inject, SETTINGS_NS } from '@deepseek-ai/dsh-client-locale/client'
+import type { LanguageRowInjected, LocaleService } from '@deepseek-ai/dsh-client-locale/client'
+import { LanguageRow } from '../src/client/LanguageRow.tsx'
+import type { createLanguageRowStore } from '../src/client/settings-store.ts'
+
+const SLOT = 'settings.general.item'
+
+async function bench() {
+  const ctx = new Context()
+  await ctx.plugin(SlotsService).await()
+  return { ctx, slots: ctx.get('slots') as SlotsService }
+}
+
+/** Stand in for the settings shell: declare the General item slot from root. */
+function declareItems(slots: SlotsService): () => void {
+  return slots.register(
+    { name: 'root', children: { [SLOT]: { kind: 'list', scope: 'root' } } } as never,
+    () => null,
+  )
+}
+
+/** Mirror the framework's inject choreography: bake a real instance from the
+ * declared handle and hand its actions to the entry's inject factory. */
+function faceOf(slots: SlotsService) {
+  const entry = slots.entries(SLOT).find(e => e.component === LanguageRow)!
+  const handle = entry.store as ReturnType<typeof createLanguageRowStore>
+  const instance = handle.create()
+  const face = (entry.inject as unknown as (a: typeof instance.actions) => LanguageRowInjected)(instance.actions)
+  return { entry, instance, face }
+}
+
+describe('locale apply', () => {
+  it('declares the slot service', () => {
+    expect(inject).toEqual(['slots'])
+  })
+
+  it('provides the service with base + settings dictionaries and registers the row (declaration before or after apply)', async () => {
+    const before = await bench()
+    declareItems(before.slots)
+    await before.ctx.plugin({ inject: [...inject], apply }).await()
+    const locale = before.ctx.get('locale') as LocaleService
+    // Base dictionaries are registered: the (ns, locale) seats are occupied.
+    expect(() => locale.register('common', 'zh', {})).toThrow('already has locale')
+    expect(() => locale.register('common', 'en', {})).toThrow('already has locale')
+    expect(locale.bind(SETTINGS_NS)('language.title')).toBe('语言')
+    const entry = before.slots.entries(SLOT).find(e => e.component === LanguageRow)!
+    expect(entry.options).toMatchObject({ id: 'language', order: 0 })
+
+    const after = await bench()
+    const fiber = after.ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    expect(after.slots.entries(SLOT)).toHaveLength(0)
+    declareItems(after.slots)
+    await Promise.resolve()
+    expect(after.slots.entries(SLOT).some(e => e.component === LanguageRow)).toBe(true)
+  })
+
+  it('projects service snapshots into the row store and routes face writes back', async () => {
+    const b = await bench()
+    declareItems(b.slots)
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    const locale = b.ctx.get('locale') as LocaleService
+    // An event ahead of any inject hits the unbound-actions arm.
+    locale.setLocale('en')
+
+    const { instance, face } = faceOf(b.slots)
+    // The inject-time re-sync sealed the init window: the mirror is current.
+    expect(instance.getSnapshot().active).toBe('en')
+    expect(instance.getSnapshot().options.map(o => o.id)).toEqual(['zh', 'en'])
+    expect(face.t('language.title')).toBe('Language')
+
+    face.setLocale('zh')
+    expect(locale.getLocale().active).toBe('zh')
+    expect(instance.getSnapshot().active).toBe('zh')
+    expect(face.t('language.title')).toBe('语言')
+  })
+
+  it('recovers after an HMR collapse of the declaring entry (stale disposer must not block)', async () => {
+    const b = await bench()
+    const host = declareItems(b.slots)
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    expect(b.slots.entries(SLOT)).toHaveLength(1)
+
+    // Collapse: the declarer dies, the cascade removes our entry while the
+    // apply closure still holds its (now stale) disposer.
+    host()
+    expect(b.slots.entries(SLOT)).toHaveLength(0)
+
+    declareItems(b.slots)
+    await Promise.resolve()
+    expect(b.slots.entries(SLOT).some(e => e.component === LanguageRow)).toBe(true)
+  })
+
+  it('teardown removes the row; teardown without a declaration is quiet', async () => {
+    const b = await bench()
+    declareItems(b.slots)
+    const fiber = b.ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    expect(b.slots.entries(SLOT)).toHaveLength(1)
+    await fiber.dispose()
+    expect(b.slots.entries(SLOT)).toHaveLength(0)
+
+    // Never-declared bench: the effect disposer's dispose arm stays undefined.
+    const quiet = await bench()
+    const f2 = quiet.ctx.plugin({ inject: [...inject], apply })
+    await f2.await()
+    await f2.dispose()
+    expect(quiet.slots.entries(SLOT)).toHaveLength(0)
+  })
+})
--- a/packages/client/locale/tests/invariant.spec.ts
+++ b/packages/client/locale/tests/invariant.spec.ts
@@ -0,0 +1,34 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { apply as nodeApply } from '@deepseek-ai/dsh-client-locale'
+import { apply as clientApply, COMMON_NS, LocaleService, inject } from '@deepseek-ai/dsh-client-locale/client'
+import * as LocaleInvariant from '@deepseek-ai/dsh-client-locale/invariant'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+describe('invariant companion', () => {
+  it('registers under the package name with an empty installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    await expect(ctx.plugin(LocaleInvariant).await()).resolves.toBeDefined()
+  })
+
+  it('node-half apply is a no-op host placeholder', () => {
+    nodeApply()
+    expect(true).toBe(true) // reaching here without throw is the contract
+  })
+
+  it('client apply provides ctx.locale seeded with the zh/en common namespace', async () => {
+    // The feature registers its own Language settings row, hence the slots edge.
+    expect(inject).toEqual(['slots'])
+    const ctx = new Context()
+    new SlotsService(ctx)
+    await ctx.plugin({ inject, apply: clientApply }).await()
+    const locale = ctx.get('locale')
+    expect(locale).toBeInstanceOf(LocaleService)
+    // Seeded dictionaries occupy the (ns, locale) seats even while empty.
+    expect(() => (locale as LocaleService).register(COMMON_NS, 'zh', {})).toThrow('already has locale')
+    expect(() => (locale as LocaleService).register(COMMON_NS, 'en', {})).toThrow('already has locale')
+  })
+})
--- a/packages/client/locale/tests/language-row.spec.tsx
+++ b/packages/client/locale/tests/language-row.spec.tsx
@@ -0,0 +1,82 @@
+// @vitest-environment jsdom
+/** LanguageRow behavior: selector pill shows the active locale, the menu
+ * opens/closes, and selection drives setLocale. */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { createSnapshotStore, type SessionListState, type WorkspaceListState } from '@deepseek-ai/dsh-client-runtime/client'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
+import { LanguageRow } from '../src/client/LanguageRow.tsx'
+import type { LanguageRowComponentProps } from '../src/client/LanguageRow.tsx'
+import { createLanguageRowStore } from '../src/client/settings-store.ts'
+
+afterEach(cleanup)
+
+const OPTIONS = [{ id: 'zh', label: '中文' }, { id: 'en', label: 'English' }]
+
+/** Empty global standard-kit hooks (the row reads neither). */
+function emptySessions() {
+  const store = createSnapshotStore<SessionListState>(
+    { ids: [], byId: {}, current: undefined, intent: undefined, phase: 'ready' })
+  return bindSnapshotSelector(store)
+}
+function emptyWorkspaces() {
+  const store = createSnapshotStore<WorkspaceListState>({
+    items: [], intent: undefined, state: 'idle', phase: 'ready', error: null,
+    baselinesReady: true, recentWorkspaceId: undefined,
+  })
+  return bindSnapshotSelector(store)
+}
+
+function mount(active = 'en') {
+  // Real store instance — the sanctioned zero-machinery path for tests.
+  const store = createLanguageRowStore().create()
+  store.actions.sync(active, OPTIONS, 0)
+  const setLocale = vi.fn()
+  const props: LanguageRowComponentProps = {
+    useSessions: emptySessions(),
+    useWorkspaces: emptyWorkspaces(),
+    useStore: bindSnapshotSelector(store),
+    actions: store.actions,
+    t: (key: string) => key === 'language.title' ? 'Language' : key,
+    setLocale,
+  }
+  render(<LanguageRow {...props} />)
+  return { store, setLocale }
+}
+
+describe('LanguageRow', () => {
+  it('shows the title and the active locale label on the selector pill', () => {
+    mount('en')
+    expect(screen.getByText('Language')).toBeDefined()
+    const trigger = screen.getByRole('button', { name: /English/ })
+    expect(trigger.getAttribute('aria-expanded')).toBe('false')
+  })
+
+  it('opens the menu, selects a locale, and closes', () => {
+    const b = mount('en')
+    const trigger = screen.getByRole('button', { name: /English/ })
+    fireEvent.click(trigger)
+    expect(trigger.getAttribute('aria-expanded')).toBe('true')
+    fireEvent.click(screen.getByRole('menuitem', { name: '中文' }))
+    expect(b.setLocale).toHaveBeenCalledWith('zh')
+    expect(trigger.getAttribute('aria-expanded')).toBe('false')
+    expect(screen.queryByRole('menuitem', { name: '中文' })).toBeNull()
+  })
+
+  it('closes on outside pointerdown without selecting', () => {
+    const b = mount('en')
+    fireEvent.click(screen.getByRole('button', { name: /English/ }))
+    expect(screen.getByRole('menuitem', { name: '中文' })).toBeDefined()
+    fireEvent.pointerDown(document.body)
+    expect(screen.queryByRole('menuitem', { name: '中文' })).toBeNull()
+    expect(b.setLocale).not.toHaveBeenCalled()
+  })
+
+  it('follows store changes; an unknown active id falls back to the id itself', () => {
+    const b = mount('en')
+    act(() => { b.store.actions.sync('zh', OPTIONS, 1) })
+    expect(screen.getByRole('button', { name: /中文/ })).toBeDefined()
+    act(() => { b.store.actions.sync('fr', OPTIONS, 2) })
+    expect(screen.getByRole('button', { name: /fr/ })).toBeDefined()
+  })
+})
--- a/packages/client/locale/tests/locale.spec.ts
+++ b/packages/client/locale/tests/locale.spec.ts
@@ -0,0 +1,102 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import type { LocaleSnapshot } from '@deepseek-ai/dsh-client-locale/client'
+import { LocaleService, STORAGE_KEY } from '@deepseek-ai/dsh-client-locale/client'
+
+const make = (): { ctx: Context; svc: LocaleService; events: LocaleSnapshot[] } => {
+  const ctx = new Context()
+  const events: LocaleSnapshot[] = []
+  ctx.on('locale/change', (snapshot) => { events.push(snapshot) })
+  return { ctx, svc: new LocaleService(ctx), events }
+}
+
+describe('LocaleService', () => {
+  beforeEach(() => {
+    localStorage.clear()
+  })
+
+  it('translates through the active-locale -> zh -> key chain', () => {
+    const { svc } = make()
+    svc.register('ns', 'zh', { hello: '你好', onlyZh: '仅中文' })
+    svc.register('ns', 'en', { hello: 'Hello' })
+    const t = svc.bind('ns')
+    expect(svc.getLocale().active).toBe('zh')
+    expect(t('hello')).toBe('你好')
+    svc.setLocale('en')
+    expect(t('hello')).toBe('Hello')
+    expect(t('onlyZh')).toBe('仅中文')
+    expect(t('missing.key')).toBe('missing.key')
+  })
+
+  it('interpolates {name} params and leaves unknown placeholders intact', () => {
+    const { svc } = make()
+    svc.register('ns', 'zh', { greet: '你好，{name}！第 {n} 次', partial: '{known} 与 {unknown}' })
+    const t = svc.bind('ns')
+    expect(t('greet', { name: '世界', n: 2 })).toBe('你好，世界！第 2 次')
+    expect(t('partial', { known: 'A' })).toBe('A 与 {unknown}')
+  })
+
+  it('bind returns a stable per-namespace function identity', () => {
+    const { svc } = make()
+    expect(svc.bind('a')).toBe(svc.bind('a'))
+    expect(svc.bind('a')).not.toBe(svc.bind('b'))
+  })
+
+  it('rejects duplicate (ns, locale) and disposer only removes its own dict', () => {
+    const { svc } = make()
+    const dispose = svc.register('ns', 'zh', { k: 'v1' })
+    expect(() => svc.register('ns', 'zh', { k: 'v2' })).toThrow('already has locale')
+    dispose()
+    const t = svc.bind('ns')
+    expect(t('k')).toBe('k')
+    svc.register('ns', 'zh', { k: 'v2' })
+    expect(t('k')).toBe('v2')
+    dispose()
+    expect(t('k')).toBe('v2')
+  })
+
+  it('setLocale persists, republishes an immutable snapshot, and no-ops on same value', () => {
+    const { svc, events } = make()
+    svc.setLocale('en')
+    expect(svc.getLocale().active).toBe('en')
+    expect(localStorage.getItem(STORAGE_KEY)).toBe('en')
+    expect(events).toHaveLength(1)
+    expect(events[0]).toBe(svc.getLocale())
+    expect(events[0]!.revision).toBe(1)
+    svc.setLocale('en')
+    expect(events).toHaveLength(1)
+  })
+
+  it('throws on unknown locale ids', () => {
+    const { svc } = make()
+    expect(() => { svc.setLocale('fr') }).toThrow('not registered')
+  })
+
+  it('restores a persisted locale and falls back to zh on garbage', () => {
+    localStorage.setItem(STORAGE_KEY, 'en')
+    expect(make().svc.getLocale().active).toBe('en')
+    localStorage.setItem(STORAGE_KEY, 'fr')
+    expect(make().svc.getLocale().active).toBe('zh')
+  })
+
+  it('runs without localStorage (node boots): defaults on read, no-op on write', () => {
+    vi.stubGlobal('localStorage', undefined)
+    try {
+      const { svc } = make()
+      expect(svc.getLocale().active).toBe('zh')
+      svc.setLocale('en')
+      expect(svc.getLocale().active).toBe('en')
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+
+  it('exposes the two shipped locales with self-described labels', () => {
+    const { svc } = make()
+    expect(svc.getLocale().locales).toEqual([
+      { id: 'zh', label: '中文' },
+      { id: 'en', label: 'English' },
+    ])
+  })
+})
--- a/packages/client/locale/tests/settings-store.spec.ts
+++ b/packages/client/locale/tests/settings-store.spec.ts
@@ -0,0 +1,30 @@
+/** Language row store: snapshot-mirror action and the revision guard. */
+import { describe, expect, it } from 'vitest'
+import { createLanguageRowStore } from '../src/client/settings-store.ts'
+
+const OPTIONS = [{ id: 'zh', label: '中文' }, { id: 'en', label: 'English' }]
+
+describe('createLanguageRowStore', () => {
+  it('init shape: empty mirror with revision at -1', () => {
+    const store = createLanguageRowStore().create()
+    expect(store.getSnapshot()).toEqual({ active: '', options: [], revision: -1 })
+  })
+
+  it('sync mirrors the snapshot and advances the revision', () => {
+    const store = createLanguageRowStore().create()
+    store.actions.sync('zh', OPTIONS, 0)
+    expect(store.getSnapshot()).toEqual({ active: 'zh', options: OPTIONS, revision: 0 })
+    store.actions.sync('en', OPTIONS, 1)
+    expect(store.getSnapshot().active).toBe('en')
+    expect(store.getSnapshot().revision).toBe(1)
+  })
+
+  it('revision guard drops stale and duplicate writes', () => {
+    const store = createLanguageRowStore().create()
+    store.actions.sync('en', OPTIONS, 5)
+    store.actions.sync('zh', OPTIONS, 4)
+    store.actions.sync('zh', OPTIONS, 5)
+    expect(store.getSnapshot().active).toBe('en')
+    expect(store.getSnapshot().revision).toBe(5)
+  })
+})
--- a/packages/client/locale/tsconfig.json
+++ b/packages/client/locale/tsconfig.json
@@ -9,10 +9,16 @@
  ],
  "references": [
    {
-      "path": "../../../vendor/cordis"
+      "path": "../runtime"
    },
    {
-      "path": "../runtime"
+      "path": "../ui-primitives"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../../../vendor/cordis"
    },
    {
      "path": "../../support/invariants"
--- a/packages/client/locale/tsdown.config.ts
+++ b/packages/client/locale/tsdown.config.ts
@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-locale', ['lib/types/index.js', 'lib/types/invariant.js'])
--- a/packages/client/modules/README.i18n.yaml
+++ b/packages/client/modules/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: efba9e2eb0b148677fc7ac18bfad6333fb6f80da
+README.zh.md: 7d1aa8af08256c47c1ae65343e46c30e910128d0
--- a/packages/client/modules/README.md
+++ b/packages/client/modules/README.md
@@ -1,5 +1,7 @@
 # @deepseek-ai/dsh-client-modules

+English | [中文](README.zh.md)
+
 Client module system: the browser peer of Node's internal ESM loader, built as a lazy CJS table. The web shell mounts the vendored cordis Loader for entry governance (fiber lifecycle, inject waiting, update/refresh) and injects this package's `ClientModuleLoader` as its `internal` seam — the vendored side's only consumption point is `EntryTree.import`, so replacing `internal` replaces exactly "how plugin code arrives" and nothing else.

 Lazy CJS model (web2): executing a plugin bundle only REGISTERS its factory (`window.__ModuleLoader__.load({id, factory})`); every module body side effect — CSS injection included — lives in the factory closure and runs at materialization (`factory(require)` → export surface, memoized in `loadCache`), not at script execution. A factory that requires another registered-but-unmaterialized module materializes it recursively, so load order needs no external sequencing; require cycles throw (factory-form CJS cannot deliver partial exports). `<id>/client` and the bare id name the same surface (a plugin bundle IS its package's client half).
--- a/packages/client/modules/README.zh.md
+++ b/packages/client/modules/README.zh.md
@@ -0,0 +1,22 @@
+# @deepseek-ai/dsh-client-modules
+
+[English](README.md) | 中文
+
+客户端模块系统：Node 内部 ESM loader 的浏览器端对等实现，以惰性 CJS 表构建。web 外壳挂载 vendored cordis Loader 来治理配置项（fiber 生命周期、inject 等待、update/refresh），并把该包的 `ClientModuleLoader` 作为其 `internal` seam 注入；vendored 一侧唯一的消费点是 `EntryTree.import`，因此替换 `internal` 恰好只会替换「插件代码如何到达」，不会改变其他内容。
+
+惰性 CJS 模型（web2）：执行插件组合包只会注册其 factory（`window.__ModuleLoader__.load({id, factory})`）；每个模块主体的副作用（包括 CSS 注入）都位于 factory 闭包中，在物化时运行（`factory(require)` → 导出表层，并在 `loadCache` 中记忆化），不会在脚本执行时运行。如果 factory 请求另一个已注册但尚未物化的模块，系统会递归物化它，因此加载顺序无需外部编排；require 循环会抛出异常（factory 形式的 CJS 无法交付部分导出）。`<id>/client` 与裸 id 指向同一表层（一个插件组合包就是其包的客户端侧）。
+
+解析分支顺序（`import(specifier)`）：平台种子词 → 外壳实例；记忆化记录 → 表层；外壳自身的静态注册表（`registerStatic`，app-shell）→ 模块；已注册 factory → 物化；图行（`window.__DSH_BOOT__`）→ 抓取 + 执行 + 物化；其他情况一律抛出异常。这是构建时组合包纯度门禁的运行时镜像。交给 factory 的同步 `require` 采用相同顺序，但不含抓取分支，并把观察到的边记录到模块记录中。`prefetch` 是第一阶段到达 hook（抓取 + 执行，只注册；并发调用共享一个进行中的 task）；`invalidate` 会丢弃 factory 与物化记录，使下一次 prefetch/import 重新抓取（HMR hook）。
+
+## 模型体验
+
+无。模块 loader 属于浏览器侧内核机制；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **有意采用扁平模块图**：每个组合包是一个模块节点，其边只指向表叶；接口（loadCache/edges/invalidate）按通用模块图塑形，因此可以改变 externalization 粒度而不更改接口。
+- **自身不记录卸载账目**：样式移除与 fiber 拆卸顺序属于 HMR 驱动器（`@deepseek-ai/dsh-client-hmr`）；loader 只逐记录清点自身拥有的样式标签 id。
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: 5d44f666a12e747eb79535c48d87fcaff381d770
+README.zh.md: 16577c356ba79066c7c56ae07a266f4ec85fa2e9
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -1,6 +1,18 @@
 # @deepseek-ai/dsh-client-runtime

-Client cordis boot + core services: SlotsService (Service wrapper over SlotCore + 'slots/changed' bridge), SessionsService (list store projection, scope tree, bindings, ancestry), the Session object layer (exported as a type; instances are owned and handed out by SessionsService — the manager/paging internals stay package-internal, tests reach them via src), ClientLoader (`./loader` subpath, statically held by the shell). Contract: api-contracts v3 §4.
+English | [中文](README.zh.md)
+
+Client cordis boot and React-free object services: SlotsService wraps SlotCore and supplies renderer data sources; SessionsService owns Session objects, list/scope/history state, and page-local Session Intent state; WorkspacesService depends on SessionsService and owns Workspace objects, list/actions, page-local Workspace Intent state, default-target derivation, and the cross-object New Session flow. The runtime fans the shared Host stream into both managers. Contract: api-contracts v3 §4.
+
+## Workspace and Session lists
+
+Workspace and Session lists have independent monotone `pending` → `ready` baseline phases and separate refresh activity/error state. Incremental frames arriving during a list request replay over its response. The first successful baseline establishes Host order; later refreshes update rows and membership without changing the relative order of identities already shown. Workspace recency is derived only after both baselines are ready and never changes Workspace list order.
+
+SlotsService gives the renderer separate bare observables for `useSessions` and `useWorkspaces`; web-react creates the hooks. Workspace business state does not enter `SessionListState` or an entry store.
+
+## Session creation failures
+
+`SessionsService.create` accepts an optional caller-preallocated SessionId. It throws `SessionCreateError` on failure: `requestedSessionId` remains available after transport uncertainty, while `publishedSessionId` is set when `workspace-attach-failed` proves the Host published a real Session before attachment failed. For the New Session flow, the frontend Session object owns its retained prompt and advances it through attachment and send; a partially published Session keeps the same object and prompt while it appears as Ungrouped.

 ## Session title projection

--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -0,0 +1,33 @@
+# @deepseek-ai/dsh-client-runtime
+
+[English](README.md) | 中文
+
+客户端 cordis 启动与不依赖 React 的对象服务：SlotsService 包装 SlotCore 并提供 renderer 数据源；SessionsService 拥有 Session 对象、列表／scope／history 状态和页面局部 Session Intent 状态；WorkspacesService 依赖 SessionsService，拥有 Workspace 对象、列表／操作、页面局部 Workspace Intent 状态、默认目标派生，以及跨对象 New Session 流程。运行时把共享 Host 流分发给两个 manager。契约：api-contracts v3 §4。
+
+## Workspace 与 Session 列表
+
+Workspace 和 Session 列表各自具有单调的 `pending` → `ready` 基线阶段，也有各自的刷新活动／错误状态。列表请求期间到达的增量帧会在其响应之上回放。第一次成功的基线建立 Host 顺序；后续刷新更新行和成员关系，但不改变已经显示的标识之间的相对顺序。Workspace 新近程度只在两条基线都 ready 后派生，且绝不改变 Workspace 列表顺序。
+
+SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸 observable；web-react 创建 hook。Workspace 业务状态不会进入 `SessionListState` 或配置项 store。
+
+## Session 创建失败
+
+`SessionsService.create` 接受可选的、由调用方预先分配的 SessionId。失败时抛出 `SessionCreateError`：传输状态不确定后仍可取得 `requestedSessionId`；如果 Host 在附加失败前已经发布真实 Session，则会设置 `publishedSessionId`，此时 `workspace-attach-failed` 提供了证明。在 New Session 流程中，前端 Session 对象拥有其保留的提示词，并推动提示词完成附加与发送；部分发布的 Session 会保留同一对象和提示词，同时显示为 Ungrouped。
+
+## Session 标题投影
+
+`SessionManager` 独立于列表和 Session 实例到达情况，保留最近一次通过验证的 `session/title` 控制快照。seq 更新的事件会替换旧快照，标题时间戳计入列表新近程度；订阅基线会先丢弃 seq 超过其 `lastSeq` 的任何已保留标题，再接收可选的折叠标题。显式移除 Session 也会清除已保留标题。因此，面向客户端的 `SessionSummary.title` 只包含真实的持久标题；`displayTitle` 始终存在，并依次回退到 cwd basename 和 Session id。冷启动的持久会话会保持该回退值，直到打开或恢复会话，促使主机折叠并投影日志支持的标题。
+
+## 模型体验
+
+无。客户端运行时承载浏览器侧服务与 Session 对象层；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **`loader.unload` 是 stub（抛出 not-implemented）**：完整链路（fiber 释放 → 注册级联 → 样式移除）随 HMR 项目落地。
+- **scope 拆卸由阶段驱动，目前只能有一个占用者**：已 staged 的 Session 精确跟随 `list.current`（staging 就是打开信号：事件窗口打开 ⟺ Session 位于 stage）；在 staged 状态下被移除的 Session，其 scope 会冻结保留，直到 stage 转向其他 Session，而非直到真实观察者数量降为零。解析（`cell()`／`binding()`／`scope()`）只是纯寻址，可安全用于渲染。并发 pane 落地时，staged 状态可以扩展为多 pane 列表。
+- **插件组合包从该包执行值导入时必须使用 `/client` 子路径**：裸包名不在 loader external 表中，会内联第二个模块实例；其私有 scope-tag Symbol 永远无法匹配（空状态 P0 事故复盘）。
--- a/packages/client/runtime/src/client/contract/store.ts
+++ b/packages/client/runtime/src/client/contract/store.ts
@@ -161,11 +161,7 @@ function deepFreeze(value: unknown): void {
  }
 }

-// ---- defineStore shell (slot terminal design §4) ----
-// The type authority is ui-slots' store family (create(scopeKey?) and
-// clearPersisted() included); this module houses only the engine-backed
-// implementation. The one engine-side widening left: instances expose the
-// raw engine store for framework/test surfaces.
+// ui-slots owns the contract; this module supplies the engine implementation.

 /** A live engine instance: the contract instance plus the raw engine store. */
 export interface EngineStoreInstance<T, A extends ActionsDecl<T>> extends StoreInstance<T, A> {
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -1,55 +1,38 @@
-/**
- * Browser half: the whole runtime contract surface (api-contracts v3 §4) —
- * SlotsService (declaration ledger + renderer seam + store axis, built-in
- * 'root'), SessionsService (list store + current selection + scope tree +
- * object layer), and the cordis Context/Events merges. apply mounts
- * ctx.slots + ctx.sessions and wires the connection stream loop into the
- * object layer. A static-arrival entry: the web shell bundles this module
- * and mounts it through the host graph (module loading lives in
- * @deepseek-ai/dsh-client-modules, entry governance in the vendored Loader).
- */
+/** Browser runtime services for slots, sessions, workspaces, and connection-stream delivery. */
 import type { Context } from 'cordis'
 import type { ConnectionHandle, SessionId } from '@deepseek-ai/dsh-client-connection/client'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotsService } from './slots.ts'
 import { SessionsService } from './sessions/service.ts'
 import type { SessionListState } from './sessions/service.ts'
+import { WorkspacesService } from './workspaces/service.ts'
 import type { ConversationSnapshot, RunningToolCall, ToolResultNode } from './sessions/conversation.ts'

 export { SlotsService } from './slots.ts'
-// RootOwnerProps rides the 'root' SlotMap row (both migrated here from
-// ui-layout: the framework slot is declared by the framework package).
 export type { RootOwnerProps } from './slots.ts'
-export { SessionsService, scopeOf } from './sessions/service.ts'
+export { SessionCreateError, SessionsService, scopeOf, workspaceTitleOf } from './sessions/service.ts'
+export { WorkspacesService } from './workspaces/service.ts'
 export type { Session } from './sessions/session.ts'
 export type { SessionBinding, SessionListState, SessionSummary } from './sessions/service.ts'
-// The snapshot-store engine lives here since the store migration (the data
-// layer owns its substrate; web-react is React glue only). The './client'
-// main export is the single serving door — no store subpath.
+export type { SessionIntentListSnapshot, SessionListPhase } from './sessions/manager.ts'
+export type { WorkspaceListPhase } from './workspaces/manager.ts'
+export type { WorkspaceListState } from './workspaces/service.ts'
+export type { WorkspaceId, WorkspaceView } from '@deepseek-ai/dsh-client-connection/client'
+// Runtime owns the snapshot store; web-react only binds it to React.
 export { createSnapshotStore, defineStore, shallowEqual } from './contract/store.ts'
 export type {
  EngineStoreHandle, EngineStoreInstance, ObservableSnapshot, SnapshotStore,
 } from './contract/store.ts'
 export type {
-  AssistantBlock, AssistantMessageNode, ContextMessageNode, ConversationNode, ConversationSnapshot,
-  RunningToolCall, SteeringMessageNode,
-  ToolResultNode, UnknownSurfaceNode, UserMessageNode,
+  AssistantBlock, AssistantMessageNode, ComposerPhase, ContextMessageNode, ConversationNode,
+  ConversationSnapshot, PendingPrompt, RunningToolCall, SessionIntentSnapshot, SessionIntentTarget,
+  SteeringMessageNode, ToolResultNode, UnknownSurfaceNode, UserMessageNode,
 } from './sessions/conversation.ts'
-// PendingWait is a value export: tests construct fixture waits directly.
 export { PendingWait } from './sessions/pending.ts'
 export type { PendingInteraction, PendingKind, PendingPayloads } from './sessions/pending.ts'
 export type { SessionId } from '@deepseek-ai/dsh-client-connection/client'

-// ---- Narrowed aliases (the single narrowing point of the slot type chain:
-// ui-slots/web-react stay generic and dependency-inverted; the client-tree
-// concrete types live here, where their subjects live) ----
-
-/**
- * The client cordis context face: the base Context plus the service keys
- * this package's declaration merge contributes (slots/sessions/loader) and
- * every later plugin's merge. A plain alias — the merges land on Context
- * itself inside the client program; the name marks intent at consumer seams.
- */
+/** Client-side Cordis context after declaration merging. */
 export type ClientContext = Context

 /** The conversation-snapshot selector hook (ConvViewProps/ToolRowProps take this). */
@@ -69,15 +52,15 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
   * every session-scope slot component receives these from the framework.
   */
  interface SessionStandardProps {
-    /** Selector hook over this session's conversation snapshot. */
    useSession: SnapshotSelectorHook<ConversationSnapshot>
    /** The framework-resolved session id (owners never pass it). */
    sessionId: SessionId
  }
-  /** Global standard kit, real members: the session-list hook every slot component receives. */
+  /** Props injected into every global slot component. */
  interface GlobalStandardProps {
-    /** Selector hook over the session list snapshot (`current` included — the arbitrated selection seat). */
    useSessions: SnapshotSelectorHook<SessionListState>
+    /** Selector hook over real Workspaces and their independent baseline lifecycle. */
+    useWorkspaces: SnapshotSelectorHook<import('./workspaces/service.ts').WorkspaceListState>
  }
 }

@@ -93,24 +76,31 @@ declare module 'cordis' {
  interface Context {
    slots: import('./slots.ts').SlotsService
    sessions: import('./sessions/service.ts').SessionsService
+    workspaces: import('./workspaces/service.ts').WorkspacesService
  }
 }

 /** Required services: the wire handle mounted by the connection plugin. */
 export const inject = ['connection']

-/**
- * Client plugin body: mount slots + sessions, start the stream loop.
- * @param ctx - client cordis context.
+/** Mounts the browser runtime services and connection stream.
+ * @param ctx - Client Cordis context.
 */
 export function apply(ctx: Context): void {
  ctx.plugin(SlotsService)
  const connection = ctx.get('connection') as ConnectionHandle
  const sessions = new SessionsService(ctx, connection.api)
+  const workspaces = new WorkspacesService(ctx, connection.api, sessions)
  const loop = connection.start({
-    onMuxEnvelope: (envelope) => { sessions.manager.handleMuxEnvelope(envelope) },
-    onHostEnvelope: (envelope) => { sessions.manager.handleHostEnvelope(envelope) },
-    onConnected: () => { sessions.manager.handleConnected() },
+    onMuxEnvelope: (envelope) => { sessions.handleMuxEnvelope(envelope) },
+    onHostEnvelope: (envelope) => {
+      sessions.handleHostEnvelope(envelope)
+      workspaces.handleHostEnvelope(envelope)
+    },
+    onConnected: () => {
+      sessions.handleConnected()
+      workspaces.handleConnected()
+    },
  })
  ctx.effect(() => () => { loop.stop() }, 'runtime: connection stream loop')
 }
--- a/packages/client/runtime/src/client/ordered-baseline.ts
+++ b/packages/client/runtime/src/client/ordered-baseline.ts
@@ -0,0 +1,43 @@
+/**
+ * Merge an authoritative baseline without moving identities already visible to
+ * the client. Baseline-only identities are inserted relative to the nearest
+ * following known identity; identities absent from the baseline are removed.
+ *
+ * @param current - the established client order.
+ * @param baseline - the latest authoritative rows.
+ * @param keyOf - stable identity selector.
+ * @returns baseline-valued rows with the established relative order retained.
+ */
+export function mergeOrderedBaseline<T>(
+  current: readonly T[],
+  baseline: readonly T[],
+  keyOf: (value: T) => unknown,
+): T[] {
+  const baselineByKey = new Map<unknown, T>()
+  for (const value of baseline) baselineByKey.set(keyOf(value), value)
+
+  const merged = current
+    .map(value => baselineByKey.get(keyOf(value)))
+    .filter((value): value is T => value !== undefined)
+  const mergedKeys = new Set(merged.map(keyOf))
+
+  for (let index = 0; index < baseline.length; index++) {
+    const value = baseline[index]
+    /* v8 ignore next -- dense-array guard: index is bounded by baseline.length. */
+    if (value === undefined || mergedKeys.has(keyOf(value))) continue
+    let insertion = merged.length
+    for (let following = index + 1; following < baseline.length; following++) {
+      const candidate = baseline[following]
+      /* v8 ignore next -- dense-array guard: following is bounded by baseline.length. */
+      if (candidate === undefined) continue
+      const known = merged.findIndex(item => keyOf(item) === keyOf(candidate))
+      if (known !== -1) {
+        insertion = known
+        break
+      }
+    }
+    merged.splice(insertion, 0, value)
+    mergedKeys.add(keyOf(value))
+  }
+  return merged
+}
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -4,7 +4,9 @@
 // string here (narrow to real brands when convenient).

 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
-import type { RpcError, SessionId, ToolCallView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
+import type {
+  RpcError, SessionId, ToolCallView, ToolResultView, WorkspaceId,
+} from '@deepseek-ai/dsh-client-connection/client'
 import type { PendingInteraction } from './pending.ts'

 /** Assistant content blocks sorted by what the UI cares about
@@ -149,12 +151,58 @@ export interface PartialAssistant {
 /** History-open lifecycle of a Session window. */
 export type OpenState = 'cold' | 'loading' | 'open' | 'error'

+/**
+ * Input-area shape of an OPEN session, derived at snapshot assembly (the one
+ * place that knows the predicate — consumers switch, never re-derive):
+ *
+ * - `blank`: no activity ever (no nodes, no partial, not running, no pending
+ *   waits, no prompt attempt) — the UI renders the blank-session guidance
+ *   hero.
+ * - `engaging`: the first prompt was initiated but no content landed yet —
+ *   the UI holds the composer through the accept → running → first-event
+ *   frames. Entered synchronously before prompt()'s first await.
+ * - `active`: content exists (nodes, partial, running turn, or pending
+ *   waits) — the ordinary conversation view.
+ *
+ * Monotone within a session object: blank → engaging → active, no returns.
+ * A failed first prompt stays `engaging` (composer + error strip — retry
+ * semantics; bouncing back to the hero would discard the error context).
+ * Sessions whose window is not open (`loading`/`error`) are outside phase
+ * jurisdiction: consumers branch on {@link ConversationSnapshot.openState}
+ * first (phase still reports `active`-ish facts but must not be rendered).
+ */
+export type ComposerPhase = 'blank' | 'engaging' | 'active'
+
 /** Send/stop failure surfaced in the input error strip; op picks the user-facing copy (发送失败 vs 停止失败). */
 export interface PromptError {
  op: 'send' | 'stop'
  error: RpcError
 }

+/** Workspace target of a frontend-only Session. */
+export type SessionIntentTarget =
+  | { kind: 'workspace'; workspaceId: WorkspaceId }
+  | { kind: 'workspace-intent' }
+
+/** Publication state owned by a frontend Session before it joins the Host. */
+export interface SessionIntentSnapshot {
+  target: SessionIntentTarget
+  phase: 'ready' | 'connecting'
+  error?: { step: 'session'; message: string }
+}
+
+/** One editable prompt retained by its Session until the Host accepts it. */
+export interface PendingPrompt {
+  text: string
+  phase: 'editing' | 'sending' | 'failed'
+  /** Failed prerequisite retried before sending, or the send itself. */
+  retry: 'connect' | 'send'
+  /** Workspace needed when retrying Session attachment. */
+  workspaceId?: WorkspaceId
+  /** Last failure diagnostic, absent while editing or sending. */
+  error?: string
+}
+
 /** The immutable snapshot contract Session hands to uSES (see the web client architecture RFC). */
 export interface ConversationSnapshot {
  sessionId: SessionId
@@ -166,6 +214,8 @@ export interface ConversationSnapshot {
  runningCalls: readonly RunningToolCall[]
  pending: readonly PendingInteraction[]
  running: boolean
+  /** Input-area shape (see {@link ComposerPhase}); derived here, switched on by consumers. */
+  composerPhase: ComposerPhase
  /** Set after host/session-removed; the UI grays out and disables input. */
  removed: boolean
  openState: OpenState
@@ -173,5 +223,9 @@ export interface ConversationSnapshot {
  hasMore: boolean
  loadingOlder: boolean
  promptError: PromptError | null
+  /** Frontend-only publication state; null for a Host-connected Session. */
+  intent: SessionIntentSnapshot | null
+  /** Session-owned editable prompt waiting for connection, attachment, or send. */
+  pendingPrompt: PendingPrompt | null
  lastAgentError: string | null
 }
--- a/packages/client/runtime/src/client/sessions/fold-adapter.ts
+++ b/packages/client/runtime/src/client/sessions/fold-adapter.ts
@@ -24,10 +24,10 @@ export interface CallIndexEntry {
  callView: ToolCallView | null
 }

-/** Non-surface-eligible sentinel event (safely skipped by surfaceOpOf's undefined branch).
- *  'noop/padding' is not a real event type on purpose: a genuine type with fake data would
- *  surface as garbage the day anyone adds handling for it (design §D.1; the cast is the one
- *  place a synthetic event enters the window). */
+/** Non-surface sentinel used to preserve paged-window sequence offsets.
+ * `noop/padding` is deliberately not a real event type, so it cannot acquire
+ * surface behavior; this cast is the only synthetic event entry point.
+ */
 function paddingEvent(seq: number): SessionEvent {
  return { type: 'noop/padding', seq, time: 0, data: {} } as unknown as SessionEvent
 }
--- a/packages/client/runtime/src/client/sessions/lineage.ts
+++ b/packages/client/runtime/src/client/sessions/lineage.ts
@@ -1,6 +1,6 @@
 // flattenLineage: summaries -> flat list with lineage indentation (pure function).
-// Roots sort by updatedAt desc, DFS expansion with children in the same order; orphaned lineage
-// degrades to root level; cycles fail soft and emit as roots.
+// The input order is authoritative; lineage only makes each child adjacent to its parent.
+// Orphaned lineage degrades to root level; cycles fail soft and emit as roots.

 import type { SessionId, SessionSummary } from '@deepseek-ai/dsh-client-connection/client'

@@ -22,8 +22,9 @@ export interface SessionListEntry {
 }

 /**
- * summaries -> flat list with lineage indentation (pure; roots by updatedAt
- * desc, DFS children in the same order, orphans degrade to roots).
+ * Summaries -> flat list with lineage indentation. Root and sibling order
+ * follows the established input order; this projection never re-sorts a
+ * hydrated list from mutable timestamps.
 * @param summaries - the host's session.list items.
 * @returns display rows in render order.
 */
@@ -43,9 +44,6 @@ export function flattenLineage(summaries: readonly TitledSessionSummary[]): Sess
    }
  }

-  const byUpdatedDesc = (a: TitledSessionSummary, b: TitledSessionSummary): number => b.updatedAt - a.updatedAt
-  roots.sort(byUpdatedDesc)
-
  const out: SessionListEntry[] = []
  const visited = new Set<SessionId>()
  const walk = (s: TitledSessionSummary, depth: number): void => {
@@ -57,7 +55,6 @@ export function flattenLineage(summaries: readonly TitledSessionSummary[]): Sess
    out.push({ ...s, depth })
    const kids = children.get(s.sessionId)
    if (kids === undefined) return
-    kids.sort(byUpdatedDesc)
    for (const kid of kids) walk(kid, depth + 1)
  }
  for (const root of roots) walk(root, 0)
--- a/packages/client/runtime/src/client/sessions/manager.ts
+++ b/packages/client/runtime/src/client/sessions/manager.ts
@@ -2,22 +2,51 @@
 // dispatch entry + list state, constructed and held by SessionsService (one per client runtime).
 // List data never enters zustand; React connects via subscribe/getListSnapshot.

-import type { IApiClient, HostFrame, MuxFrame, RpcError, RpcRequest, RpcResult, SessionId, SessionSummary } from '@deepseek-ai/dsh-client-connection/client'
+import type { IApiClient, HostFrame, MuxFrame, RpcError, RpcRequest, RpcResult, SessionId, SessionSummary, WorkspaceId } from '@deepseek-ai/dsh-client-connection/client'
 // Value import from the inline-safe wire layer (not the connection plugin):
 // plugin-to-plugin value imports are a bundle purity error.
 import { transportError } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { mergeOrderedBaseline } from '../ordered-baseline.ts'
 import type { SessionListEntry, TitledSessionSummary } from './lineage.ts'
 import { flattenLineage } from './lineage.ts'
 import { Notifier } from './notifier.ts'
 import { Session } from './session.ts'
+import type { SessionIntentSnapshot, SessionIntentTarget } from './conversation.ts'
+
+/**
+ * List arrival lifecycle, orthogonal to the pull-activity `state` axis:
+ * `pending` (no successful pull yet — an empty items array means "nothing
+ * arrived", not "nothing exists") → `ready` (at least one pull landed).
+ * Monotone: `ready` never steps back — later pull failures and reconnect
+ * re-pulls ride the `state`/`error` axis, which is where failure is modeled
+ * (no `error` phase here; that would duplicate `state`).
+ */
+export type SessionListPhase = 'pending' | 'ready'
+
+/** Session-owned frontend Intent projected into the global list snapshot. */
+export interface SessionIntentListSnapshot extends SessionIntentSnapshot {
+  sessionId: SessionId
+  prompt: string
+}

 /** Immutable session-list snapshot for useSessionList. */
 export interface SessionListSnapshot {
  items: readonly SessionListEntry[]
+  /** Selected real or frontend-only Session id. */
+  current: SessionId | undefined
+  /** Sole page-local frontend Session projection; its state remains owned by Session. */
+  intent: SessionIntentListSnapshot | undefined
  state: 'idle' | 'loading' | 'error'
+  /** Arrival lifecycle (see {@link SessionListPhase}); `state` stays the pull-activity axis. */
+  phase: SessionListPhase
  error: RpcError | null
 }

+type SessionListMutation =
+  | { kind: 'upsert'; summary: SessionSummary }
+  | { kind: 'remove'; sessionId: SessionId }
+  | { kind: 'status'; sessionId: SessionId; running: boolean }
+
 /** Per-session cap for pre-instantiation approval/question buffering (low-frequency frames; a few dozen covers any real backlog). */
 const PENDING_BUFFER_CAP = 32

@@ -39,8 +68,16 @@ export class SessionManager {
  private readonly titleSnapshots = new Map<SessionId, SessionTitleSnapshot>()
  private summaries: SessionSummary[] = []
  private listState: 'idle' | 'loading' | 'error' = 'idle'
+  /** Arrival phase; the pending → ready edge fires on the first successful pull (see SessionListPhase). */
+  private listPhase: SessionListPhase = 'pending'
  private listError: RpcError | null = null
  private listInflight: Promise<void> | null = null
+  /** Mutations arriving after a list request starts are replayed over its response. */
+  private listMutations: SessionListMutation[] | null = null
+
+  private selected: SessionId | undefined
+  private intentSessionId: SessionId | undefined
+  private stopIntentWatch: (() => void) | undefined

  private listSnapshotCache: SessionListSnapshot
  /** Entry-identity cache (§C.2 reference stability): list rebuilds reuse the previous entry
@@ -52,10 +89,90 @@ export class SessionManager {
    this.listSnapshotCache = this.buildListSnapshot()
  })

-  constructor(private readonly api: IApiClient) {
+  /**
+   * @param api - shared wire client.
+   * @param restoredSelection - persisted real-Session selection candidate.
+   */
+  constructor(
+    private readonly api: IApiClient,
+    restoredSelection?: SessionId,
+  ) {
+    this.selected = restoredSelection
    this.listSnapshotCache = this.buildListSnapshot()
  }

+  // ---- Selection and client-local intents ----
+
+  /**
+   * Select a real Session and discard the unmaterialized intent.
+   * @param sessionId - listed real Session id.
+   */
+  select(sessionId: SessionId): void {
+    if (!this.summaries.some(summary => summary.sessionId === sessionId)) {
+      throw new Error(`sessions.select: unknown session ${sessionId}`)
+    }
+    this.discardIntent()
+    this.selected = sessionId
+    this.notifier.notifyNow()
+  }
+
+  /** Clear selection and abandon any frontend-only Session. */
+  clearSelection(): void {
+    this.discardIntent()
+    this.selected = undefined
+    this.notifier.notifyNow()
+  }
+
+  /**
+   * Start a frontend Session against a real or still-local Workspace target.
+   * @param target - real Workspace or the WorkspacesService-owned local target.
+   * @param prompt - optional prompt retained when retargeting from a picker.
+   * @returns the frontend Session object that owns the Intent.
+   */
+  startIntent(target: SessionIntentTarget, prompt = ''): Session {
+    this.discardIntent()
+    const sessionId = `client-session-${crypto.randomUUID()}` as SessionId
+    const session = this.createSession(sessionId, { target, prompt })
+    this.sessions.set(sessionId, session)
+    this.intentSessionId = sessionId
+    this.selected = sessionId
+    this.stopIntentWatch = session.subscribe(() => {
+      if (this.intentSessionId !== sessionId) return
+      if (session.getSnapshot().intent === null) {
+        this.intentSessionId = undefined
+        this.stopIntentWatch?.()
+        this.stopIntentWatch = undefined
+      }
+      this.notifier.markDirty()
+    })
+    this.notifier.notifyNow()
+    return session
+  }
+
+  /**
+   * Resolve the active frontend Session Intent.
+   * @returns the active frontend Session, if one remains selected.
+   */
+  getIntent(): Session | undefined {
+    return this.intentSessionId === undefined ? undefined : this.sessions.get(this.intentSessionId)
+  }
+
+  /**
+   * Update the retained prompt of the active frontend Session.
+   * @param text - exact controlled-input value for the active frontend Session.
+   */
+  updateIntent(text: string): void {
+    this.getIntent()?.updatePendingPrompt(text)
+  }
+
+  private discardIntent(): void {
+    const session = this.getIntent()
+    this.intentSessionId = undefined
+    this.stopIntentWatch?.()
+    this.stopIntentWatch = undefined
+    session?.abandonIntent()
+  }
+
  // ---- Instance management ----

  /**
@@ -67,7 +184,7 @@ export class SessionManager {
  get(sessionId: SessionId): Session {
    let session = this.sessions.get(sessionId)
    if (session === undefined) {
-      session = new Session(sessionId, this.api)
+      session = this.createSession(sessionId)
      this.sessions.set(sessionId, session)
      // Sync the running bit from the list snapshot into the new instance (consistency when the list precedes open).
      const summary = this.summaries.find(s => s.sessionId === sessionId)
@@ -82,6 +199,22 @@ export class SessionManager {
    return session
  }

+  private createSession(
+    sessionId: SessionId,
+    intent?: { target: SessionIntentTarget; prompt: string },
+  ): Session {
+    return new Session(sessionId, this.api, {
+      ...(intent === undefined ? {} : { intent }),
+      onPublished: (published) => {
+        this.sessions.set(published.sessionId, published)
+        this.recordMutation({
+          kind: 'upsert',
+          summary: { sessionId: published.sessionId, updatedAt: Date.now(), running: false },
+        })
+      },
+    })
+  }
+
  // ---- List surface ----

  /** Full refresh via session.list (single-flight: an in-flight call is reused). */
@@ -89,13 +222,21 @@ export class SessionManager {
    if (this.listInflight !== null) return this.listInflight
    this.listState = 'loading'
    this.listError = null
+    const established = this.summaries
+    const mutations: SessionListMutation[] = []
+    this.listMutations = mutations
    this.notifier.markDirty()
    this.listInflight = (async () => {
      try {
        const { result } = await this.api.sessions.list({})
        if (result.ok) {
-          this.summaries = result.value.items
+          let summaries = this.listPhase === 'pending'
+            ? result.value.items
+            : mergeOrderedBaseline(established, result.value.items, summary => summary.sessionId)
+          for (const mutation of mutations) summaries = applyMutation(summaries, mutation)
+          this.summaries = summaries
          this.listState = 'idle'
+          this.listPhase = 'ready'
          // Push running bits down to instantiated Sessions (the list is the authoritative summary source).
          for (const s of this.summaries) this.sessions.get(s.sessionId)?.handleRunning(s.running)
        } else {
@@ -108,6 +249,7 @@ export class SessionManager {
        /* v8 ignore next -- the `? null` arm is unreachable: transportError always returns ok:false. */
        this.listError = folded.ok ? null : folded.error
      } finally {
+        this.listMutations = null
        this.listInflight = null
        this.notifier.markDirty()
      }
@@ -118,18 +260,37 @@ export class SessionManager {
  /**
   * Contract session.create; on success merge into summaries immediately (no
   * wait for the next refresh).
-   * @param cwd - optional working directory for the new session.
+   * @param opts - target workspace or working directory, plus an optional caller-owned id.
   * @returns the create result.
   */
-  async create(cwd?: string): Promise<RpcResult<{ sessionId: SessionId }>> {
+  async create(
+    opts: { workspaceId?: WorkspaceId; cwd?: string; sessionId?: SessionId } = {},
+  ): Promise<RpcResult<{ sessionId: SessionId }>> {
    try {
-      const { result } = await this.api.sessions.create(cwd === undefined ? {} : { cwd })
-      if (result.ok && !this.summaries.some(s => s.sessionId === result.value.sessionId)) {
-        this.summaries = [
-          { sessionId: result.value.sessionId, updatedAt: Date.now(), running: false, ...(cwd !== undefined ? { cwd } : {}) },
-          ...this.summaries,
-        ]
-        this.notifier.markDirty()
+      const payload = opts.workspaceId !== undefined
+        ? { workspaceId: opts.workspaceId, ...(opts.sessionId === undefined ? {} : { sessionId: opts.sessionId }) }
+        : {
+          ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+          ...(opts.sessionId === undefined ? {} : { sessionId: opts.sessionId }),
+        }
+      const { result } = await this.api.sessions.create(payload)
+      if (result.ok) {
+        this.recordMutation({ kind: 'upsert', summary: {
+          sessionId: result.value.sessionId, updatedAt: Date.now(), running: false,
+          ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+        } })
+      } else {
+        const publishedSessionId = workspaceAttachSessionId(result.error)
+        // Publication precedes attachment. The error's id is a real Session,
+        // so expose it immediately as Ungrouped while the caller keeps the
+        // prompt buffer and decides whether to retry attachment.
+        if (publishedSessionId !== undefined) {
+          this.recordMutation({ kind: 'upsert', summary: {
+            sessionId: publishedSessionId,
+            updatedAt: Date.now(),
+            running: false,
+          } })
+        }
      }
      return result
    } catch (error) {
@@ -137,6 +298,23 @@ export class SessionManager {
    }
  }

+  /**
+   * Insert-or-enrich a locally synthesized summary: a new id prepends; an
+   * existing entry only gains fields it lacks (the session-added frame and the
+   * create() echo race — whichever lands second must fill the placeholder's
+   * missing cwd/parentSessionId, never overwrite list-refresh data).
+   */
+  private mergeSummary(summary: SessionSummary): void {
+    this.recordMutation({ kind: 'upsert', summary })
+  }
+
+  /** Apply immediately and retain for replay when a list response is in flight. */
+  private recordMutation(mutation: SessionListMutation): void {
+    this.listMutations?.push(mutation)
+    this.summaries = applyMutation(this.summaries, mutation)
+    this.notifier.markDirty()
+  }
+
  // ---- Subscription surface (for useSessionList) ----

  /**
@@ -216,31 +394,24 @@ export class SessionManager {
    const frame = envelope.payload
    switch (frame.type) {
      case 'host/session-added': {
-        if (!this.summaries.some(s => s.sessionId === frame.sessionId)) {
-          this.summaries = [
-            {
-              sessionId: frame.sessionId, updatedAt: Date.now(), running: false,
-              ...(frame.parentSessionId !== undefined ? { parentSessionId: frame.parentSessionId } : {}),
-            },
-            ...this.summaries,
-          ]
-          this.notifier.markDirty()
-        }
+        this.mergeSummary({
+          sessionId: frame.sessionId, updatedAt: Date.now(), running: false,
+          ...(frame.parentSessionId !== undefined ? { parentSessionId: frame.parentSessionId } : {}),
+          ...(frame.cwd !== undefined ? { cwd: frame.cwd } : {}),
+        })
+        this.sessions.get(frame.sessionId)?.handlePublished()
        return
      }
      case 'host/session-removed': {
-        this.summaries = this.summaries.filter(s => s.sessionId !== frame.sessionId)
+        this.recordMutation({ kind: 'remove', sessionId: frame.sessionId })
        this.sessions.get(frame.sessionId)?.handleRemoved() // instance survives (resident-instance rule), only flagged in the snapshot
        this.pendingBuffers.delete(frame.sessionId) // a removed session's buffered frames must not replay on a future instantiation
        this.titleSnapshots.delete(frame.sessionId)
-        this.notifier.markDirty()
        return
      }
      case 'host/session-status': {
-        this.summaries = this.summaries.map(s =>
-          s.sessionId === frame.sessionId && s.running !== frame.running ? { ...s, running: frame.running } : s)
+        this.recordMutation({ kind: 'status', sessionId: frame.sessionId, running: frame.running })
        this.sessions.get(frame.sessionId)?.handleRunning(frame.running)
-        this.notifier.markDirty()
        return
      }
      case 'host/agent-error': {
@@ -252,7 +423,7 @@ export class SessionManager {
    }
  }

-  /** After each connection generation (first connect included): refresh the list + resync opened instances (reconnect = rebuild). */
+  /** After each connection generation: refresh the session baseline and rebuild opened windows. */
  handleConnected(): void {
    void this.refreshList()
    for (const session of this.sessions.values()) void session.resync()
@@ -281,6 +452,57 @@ export class SessionManager {
    }
    const sameOrder = items.length === this.itemsCache.length && items.every((e, i) => e === this.itemsCache[i])
    if (!sameOrder) this.itemsCache = items
-    return { items: this.itemsCache, state: this.listState, error: this.listError }
+    const intentSession = this.getIntent()
+    const intentState = intentSession?.getSnapshot()
+    const intent = intentSession !== undefined
+      && intentState !== undefined && intentState.intent !== null && intentState.pendingPrompt !== null
+      ? {
+        sessionId: intentSession.sessionId,
+        ...intentState.intent,
+        prompt: intentState.pendingPrompt.text,
+      }
+      : undefined
+    const selected = this.selected
+    const current = selected !== undefined && (
+      intent?.sessionId === selected || items.some(item => item.sessionId === selected)
+    ) ? selected : undefined
+    return {
+      items: this.itemsCache,
+      current,
+      intent,
+      state: this.listState,
+      phase: this.listPhase,
+      error: this.listError,
+    }
  }
 }
+
+/** Apply one list mutation without deriving display order. */
+function applyMutation(summaries: readonly SessionSummary[], mutation: SessionListMutation): SessionSummary[] {
+  switch (mutation.kind) {
+    case 'upsert': {
+      const existing = summaries.find(summary => summary.sessionId === mutation.summary.sessionId)
+      if (existing === undefined) return [mutation.summary, ...summaries]
+      const filled: SessionSummary = {
+        ...existing,
+        ...(existing.cwd === undefined && mutation.summary.cwd !== undefined ? { cwd: mutation.summary.cwd } : {}),
+        ...(existing.parentSessionId === undefined && mutation.summary.parentSessionId !== undefined
+          ? { parentSessionId: mutation.summary.parentSessionId } : {}),
+      }
+      if (filled.cwd === existing.cwd && filled.parentSessionId === existing.parentSessionId) return [...summaries]
+      return summaries.map(summary => summary.sessionId === mutation.summary.sessionId ? filled : summary)
+    }
+    case 'remove':
+      return summaries.filter(summary => summary.sessionId !== mutation.sessionId)
+    case 'status':
+      return summaries.map(summary => summary.sessionId === mutation.sessionId && summary.running !== mutation.running
+        ? { ...summary, running: mutation.running }
+        : summary)
+  }
+}
+
+/** Temporary source-plane bridge while the Host contract and client project build independently. */
+function workspaceAttachSessionId(error: RpcError): SessionId | undefined {
+  const candidate = error as unknown as { code: string; details: { sessionId?: SessionId } }
+  return candidate.code === 'workspace-attach-failed' ? candidate.details.sessionId : undefined
+}
--- a/packages/client/runtime/src/client/sessions/service.ts
+++ b/packages/client/runtime/src/client/sessions/service.ts
@@ -15,12 +15,16 @@
 * survives frozen (read-only view) until the stage moves on.
 */
 import type { Context, Fiber } from 'cordis'
-import type { IApiClient, SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import type { IApiClient, RpcError, SessionId, WorkspaceId } from '@deepseek-ai/dsh-client-connection/client'
 import type { SessionCell } from '@deepseek-ai/dsh-client-ui-slots'
 import type { SnapshotStore } from '../contract/store.ts'
 import { createSnapshotStore } from '../contract/store.ts'
 import { SessionManager } from './manager.ts'
+import type {
+  SessionIntentListSnapshot, SessionListPhase,
+} from './manager.ts'
 import type { Session } from './session.ts'
+import type { SessionIntentTarget } from './conversation.ts'

 /** Session list row projected from the host list RPC plus live stream increments. */
 export interface SessionSummary {
@@ -40,7 +44,36 @@ export interface SessionSummary {
 * the single useSessions standard hook reads list and selection together —
 * sidebar highlighting and SessionProvider share one fact source).
 */
-export interface SessionListState { ids: SessionId[]; byId: Record<SessionId, SessionSummary>; current: SessionId | undefined }
+export interface SessionListState {
+  ids: SessionId[]
+  byId: Record<SessionId, SessionSummary>
+  current: SessionId | undefined
+  /** Frontend Session Intent projected from its owning Session object. */
+  intent: SessionIntentListSnapshot | undefined
+  /** Arrival lifecycle projected 1:1 from the manager snapshot (see SessionListPhase): empty-with-ready means "truly no sessions". */
+  phase: SessionListPhase
+}
+
+/** Structured session-create failure preserving partial publication identity. */
+export class SessionCreateError extends Error {
+  override readonly name = 'SessionCreateError'
+  /** Definitely published by Host before Workspace attachment failed. */
+  readonly publishedSessionId: SessionId | undefined
+
+  /**
+   * @param rpcError - Host business or folded transport error.
+   * @param requestedSessionId - caller-preallocated id used for later stream/list reconciliation.
+   */
+  constructor(
+    readonly rpcError: RpcError,
+    readonly requestedSessionId: SessionId | undefined,
+  ) {
+    super(`session create failed: ${rpcError.code}: ${rpcError.message}`)
+    this.publishedSessionId = rpcError.code === 'workspace-attach-failed'
+      ? rpcError.details.sessionId
+      : undefined
+  }
+}

 /** Session assembly handle for SessionProvider/inject factories (identity-stable per session). */
 export interface SessionBinding {
@@ -64,6 +97,20 @@ export function scopeOf(ctx: Context): SessionId | undefined {
 /** Shared no-op plugin backing each session scope fiber. */
 function sessionScope(): void {}

+/**
+ * Workspace display title of a session cwd: the path's last non-empty
+ * segment (both separators accepted; trailing separators ignored), or ''
+ * for separator-only paths — callers own their fallback (session id, raw
+ * cwd, default-directory copy). The repo-wide single basename derivation —
+ * every surface naming a workspace (picker rows, toggle labels, list titles)
+ * calls this instead of re-splitting paths.
+ * @param cwd - workspace directory path.
+ * @returns basename title, or '' when no non-empty segment exists.
+ */
+export function workspaceTitleOf(cwd: string): string {
+  return cwd.replace(/[/\\]+$/, '').split(/[/\\]/).pop() ?? ''
+}
+
 /**
 * Display title projection: durable title, project directory basename, then
 * the raw id.
@@ -71,8 +118,8 @@ function sessionScope(): void {}
 function displayTitleOf(title: string | undefined, cwd: string | undefined, id: SessionId): string {
  if (title !== undefined) return title
  if (cwd !== undefined && cwd !== '') {
-    const base = cwd.replace(/[/\\]+$/, '').split(/[/\\]/).pop()
-    if (base !== undefined && base !== '') return base
+    const base = workspaceTitleOf(cwd)
+    if (base !== '') return base
  }
  return id
 }
@@ -89,8 +136,8 @@ interface ScopeRecord {
 export class SessionsService {
  /** List snapshot store (list RPC + host stream increments; re-pulled on reconnect) — the useSessions standard feed, current included. */
  readonly list: SnapshotStore<SessionListState>
-  /** The object-layer instance cluster and frame dispatch entry (wired to the connection by the runtime apply). */
-  readonly manager: SessionManager
+  /** The object-layer instance cluster and frame dispatch entry. */
+  private readonly manager: SessionManager

  /**
   * Persisted selection cell (the durable half of `list.current`). Private on
@@ -117,12 +164,14 @@ export class SessionsService {
   * @param ctx - client root context (scope fibers mount under it).
   * @param api - wire client shared with every Session.
   */
-  constructor(private readonly rootCtx: Context, private readonly api: IApiClient) {
-    this.manager = new SessionManager(api)
+  constructor(private readonly rootCtx: Context, api: IApiClient) {
    this.selection = createSnapshotStore<{ sessionId?: SessionId }>(
      {},
      { persist: { name: 'dsh.sessions.current' } })
-    this.list = createSnapshotStore<SessionListState>({ ids: [], byId: {}, current: undefined })
+    this.manager = new SessionManager(api, this.selection.getSnapshot().sessionId)
+    this.list = createSnapshotStore<SessionListState>({
+      ids: [], byId: {}, current: undefined, intent: undefined, phase: 'pending',
+    })
    // The manager owns wire truth; the store is its projection. Manager
    // notifications are already microtask-batched.
    this.manager.subscribe(() => { this.projectList() })
@@ -142,56 +191,88 @@ export class SessionsService {
   * @param id - session id (must exist in the list store).
   */
  open(id: SessionId): void {
-    if (this.list.getSnapshot().byId[id] === undefined) {
-      throw new Error(`sessions.open: unknown session ${id}`)
-    }
-    this.selection.update((draft) => { draft.sessionId = id })
-    this.list.update((draft) => { draft.current = id })
+    this.manager.select(id)
  }

  /**
   * Clear the current selection so the layout shows the no-session empty
-   * state. Wipes the persisted selection too — a reload stays on empty until
-   * the user opens or starts a session. Staging holds the previous occupant
-   * across the blank (same masked-gap rule as a transient list miss).
+   * state (new-session affordance and the workspace preselection flow).
+   * Wipes the persisted selection too — a reload stays on empty until the
+   * user opens or starts a session. The staged scope keeps its frozen view
+   * per the masked-gap contract until the next open() moves the stage.
   */
  clear(): void {
-    this.selection.set({})
-    this.list.update((draft) => { draft.current = undefined })
+    this.manager.clearSelection()
+  }
+
+  /**
+   * Start or retarget the sole client-local Session intent.
+   * @param target - resolved real or frontend-only Workspace target.
+   * @param prompt - optional prompt retained across retargeting.
+   * @returns the frontend Session object that owns the Intent.
+   */
+  startIntent(target: SessionIntentTarget, prompt = ''): Session {
+    return this.manager.startIntent(target, prompt)
+  }
+
+  /**
+   * Resolve the active frontend Session Intent.
+   * @returns the active frontend Session object, if one exists.
+   */
+  intent(): Session | undefined {
+    return this.manager.getIntent()
+  }
+
+  /**
+   * Update the retained prompt of the active frontend Session.
+   * @param text - exact controlled-input value for the current Session Intent.
+   */
+  updateIntent(text: string): void {
+    this.manager.updateIntent(text)
+  }
+
+  /**
+   * Refresh the real Session baseline, reusing an in-flight pull.
+   * @returns completion of the current or newly started baseline pull.
+   */
+  refresh(): Promise<void> {
+    return this.manager.refreshList()
+  }
+
+  /**
+   * Route a mux stream envelope into the Session object layer.
+   * @param envelope - validated mux stream envelope.
+   */
+  handleMuxEnvelope(envelope: Parameters<SessionManager['handleMuxEnvelope']>[0]): void {
+    this.manager.handleMuxEnvelope(envelope)
+  }
+
+  /**
+   * Route a Host stream envelope into the Session object layer.
+   * @param envelope - validated Host stream envelope.
+   */
+  handleHostEnvelope(envelope: Parameters<SessionManager['handleHostEnvelope']>[0]): void {
+    this.manager.handleHostEnvelope(envelope)
+  }
+
+  /** Rebuild the Session baseline and every opened window after connection. */
+  handleConnected(): void {
+    this.manager.handleConnected()
  }

  /**
   * Create a session on the host.
-   * @param opts - creation options (project directory).
+   * @param opts - target workspace or directory and an optional preallocated id.
   * @returns the new session id.
+   * @throws {SessionCreateError} with the requested id and, after an attach
+   * failure, the definitely published id.
   */
-  async create(opts: { cwd?: string } = {}): Promise<SessionId> {
-    const result = await this.manager.create(opts.cwd)
-    if (!result.ok) throw new Error(`session create failed: ${result.error.code}: ${result.error.message}`)
+  async create(opts: { workspaceId?: WorkspaceId; cwd?: string; sessionId?: SessionId } = {}): Promise<SessionId> {
+    const result = await this.manager.create(opts)
+    if (!result.ok) throw new SessionCreateError(result.error, opts.sessionId)
    return result.value.sessionId
  }

-  /**
-   * Create a workspace folder under the host process cwd and a session in it.
-   * Name is a single path segment (no separators); the host mkdir runs inside
-   * session.create. Caller opens the returned id when it wants the session staged.
-   * @param name - workspace folder basename.
-   * @returns the new session id.
-   */
-  async createWorkspace(name: string): Promise<SessionId> {
-    const trimmed = name.trim()
-    if (trimmed === '') throw new Error('sessions.createWorkspace: name is required')
-    if (/[/\\]/.test(trimmed)) {
-      throw new Error('sessions.createWorkspace: name must not contain path separators')
-    }
-    const { result } = await this.api.host.describe({})
-    if (!result.ok) {
-      throw new Error(`host.describe failed: ${result.error.code}: ${result.error.message}`)
-    }
-    const hostCwd = result.value.cwd.replace(/[/\\]+$/, '')
-    return this.create({ cwd: `${hostCwd}/${trimmed}` })
-  }
-
  /**
   * Resolve a session-scoped context view (use-and-discard).
   * @param id - session id.
@@ -244,11 +325,12 @@ export class SessionsService {
   * failed one retries the next time current is touched).
   */
  private followCurrent(): void {
-    const current = this.list.getSnapshot().current
+    const snapshot = this.list.getSnapshot()
+    const current = snapshot.current
    // A masked gap (current blanked while the selection's session is
    // transiently absent) holds the stage: tearing down on the gap would
    // destroy exactly the frozen scope the mask exists to preserve.
-    if (current === undefined || current === this.watched) return
+    if (current === undefined || snapshot.byId[current] === undefined || current === this.watched) return
    this.watched = current
    this.sweepDeferred()
    const record = this.resolve(current)
@@ -291,8 +373,7 @@ export class SessionsService {
      fiber,
      ctx,
      binding: { sessionId: id, session, ctx },
-      // Bare source form (store migration): the Session object IS the
-      // observable; the React side binds the useSession hook per cell.
+      // Session is the observable; React binds a selector hook at its own seam.
      cell: { sessionId: id, session },
    }
    this.scopes.set(id, record)
@@ -301,7 +382,7 @@ export class SessionsService {

  /** Project the manager's list snapshot into the store (title derivation is display-only). */
  private projectList(): void {
-    const items = this.manager.getListSnapshot().items
+    const { items, current, intent, phase } = this.manager.getListSnapshot()
    const ids: SessionId[] = []
    const byId: Record<SessionId, SessionSummary> = {}
    for (const entry of items) {
@@ -316,11 +397,13 @@ export class SessionsService {
        ...(entry.parentSessionId !== undefined ? { parentId: entry.parentSessionId } : {}),
      }
    }
-    // current = the persisted selection, masked while its session is absent
-    // (falls to the empty state; resurfaces if the session returns).
-    const selected = this.selection.getSnapshot().sessionId
-    const current = selected !== undefined && byId[selected] !== undefined ? selected : undefined
-    this.list.set({ ids, byId, current })
+    const persisted = this.selection.getSnapshot().sessionId
+    if (intent?.sessionId === current) {
+      if (persisted !== undefined) this.selection.set({})
+    } else if (current !== undefined && byId[current] !== undefined && persisted !== current) {
+      this.selection.set({ sessionId: current })
+    }
+    this.list.set({ ids, byId, current, intent, phase })
    this.pruneScopes(byId)
  }

--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -1,20 +1,18 @@
-// Session: wraps every contract call that needs a sessionId + all conversation state for this
-// session (design §A.2/§A.9/§D.2/§D.3). Instances are resident (ruling 2): never destroyed once
-// created, they keep consuming mux frames in the background; React connects directly via
-// subscribe/getSnapshot.
+// Sessions remain resident after creation so they continue consuming mux frames off-screen.

 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import type {
  HistoryEntry, IApiClient, MuxFrame, RpcError, RpcId, RpcResult,
-  SessionId, ToolEventView,
+  SessionId, ToolEventView, WorkspaceId,
 } from '@deepseek-ai/dsh-client-connection/client'
 // Value import from the inline-safe wire layer (not the connection plugin):
 // plugin-to-plugin value imports are a bundle purity error.
 import { transportError } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { ObservableSnapshot } from '../contract/store.ts'
 import type {
-  ConversationNode, ConversationSnapshot, OpenState, PromptError, RunningToolCall,
+  ComposerPhase, ConversationNode, ConversationSnapshot, OpenState, PendingPrompt,
+  PromptError, RunningToolCall, SessionIntentSnapshot, SessionIntentTarget,
 } from './conversation.ts'
 import type { PendingInteraction } from './pending.ts'
 import { PendingWait } from './pending.ts'
@@ -22,14 +20,18 @@ import { FoldAdapter } from './fold-adapter.ts'
 import { Notifier } from './notifier.ts'
 import { PartialAccumulator } from './partial.ts'

-/** Messages per page (F.4 ledger: promote to Config at graduation; every call site references this constant). */
+/** Messages requested per history page. */
 export const PAGE_MESSAGES = 50

+/** Optional frontend Intent and publication observer for a Session object. */
+export interface SessionOptions {
+  intent?: { target: SessionIntentTarget; prompt: string }
+  onPublished?(session: Session): void
+}
+
 /**
- * Per-session state owner: event window + fold + partial, snapshot out via
- * subscribe/getSnapshot (see the web client architecture RFC). Bare source
- * only (store migration): the React machinery binds the per-cell useSession
- * hook at its own seam — no selector hook member lives on the data layer.
+ * Owns a session's event window, derived conversation state, and observable
+ * snapshot. React bindings remain outside this data layer.
 */
 export class Session implements ObservableSnapshot<ConversationSnapshot> {
  // ---- Window and derived state (all private; the snapshot is the only read surface) ----
@@ -54,8 +56,7 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
   *  Derived from window events (turn/end sweep) — rebuilt by rebuildDerivedFromWindow like partial/openCalls. */
  private frozenNodes: ConversationNode[] = []
  private pending = new Map<string, PendingInteraction>()
-  // Revision counters + caches backing the snapshot's reference-stability contract (§A.9.4/§C.2,
-  // audit S5): buildSnapshot reuses the previous array when the revision is unchanged, so
+  // Revision counters preserve array identity when derived content is unchanged, so
  // React.memo children survive unrelated snapshot swaps (chunk storms must not re-render every
  // tool card and pending card). Mutation sites bump the matching revision. partial needs no
  // counter — PartialAccumulator.toPartial already returns a cached reference when unchanged.
@@ -66,12 +67,22 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
  private frozenRev = 0
  private nodesCache: { folded: readonly ConversationNode[]; frozenRev: number; value: readonly ConversationNode[] } | null = null
  private running = false
+  /**
+   * Sticky send marker, private input of the composerPhase derivation: set
+   * synchronously before prompt()'s first await, never reset — the blank →
+   * engaging edge of the phase machine (see ComposerPhase).
+   */
+  private promptAttempted = false
  private removed = false
  private promptError: PromptError | null = null
+  private intent: SessionIntentSnapshot | null
+  private pendingPrompt: PendingPrompt | null
+  private intentGeneration = 0
+  private published: boolean
  private lastAgentError: string | null = null
-  /** Buffer for live events arriving while open/resync is in flight (stitched by seq once history lands, §D.3). */
+  /** Live events buffered during open/resync and stitched by sequence once history lands. */
  private liveBuffer: { event: SessionEvent; view: ToolEventView | undefined }[] = []
-  /** Gap-repair (resync-lite) in flight: acceptLiveEvent detours to liveBuffer until the tail page lands (audit S3). */
+  /** Gap repair in flight; live events detour to the buffer until the tail page lands. */
  private stitching = false
  /** subscribed.lastSeq baseline (gap detection; null when no subscribed frame arrived — degrade to the liveBuffer dedup path). */
  private subscribedLastSeq: number | null = null
@@ -81,7 +92,23 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
    this.snapshotCache = this.buildSnapshot()
  })

-  constructor(readonly sessionId: SessionId, private readonly api: IApiClient) {
+  /**
+   * @param sessionId - stable identity shared by the frontend Intent and Host entity.
+   * @param api - shared wire client.
+   * @param options - optional frontend-only initial state and publication observer.
+   */
+  constructor(
+    readonly sessionId: SessionId,
+    private readonly api: IApiClient,
+    private readonly options: SessionOptions = {},
+  ) {
+    this.intent = options.intent === undefined
+      ? null
+      : { target: options.intent.target, phase: 'ready' }
+    this.pendingPrompt = options.intent === undefined
+      ? null
+      : { text: options.intent.prompt, phase: 'editing', retry: 'send' }
+    this.published = options.intent === undefined
    this.snapshotCache = this.buildSnapshot()
  }

@@ -96,6 +123,10 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
  async prompt(content: ContentBlock[], mode: 'queue' | 'steer'): Promise<RpcResult<{ accepted: true }>> {
    this.promptError = null
    this.lastAgentError = null
+    // Synchronous, before the first await: the blank → engaging edge must be
+    // visible on the session area's very first frame when a caller sends
+    // ahead of navigation (first-send flow).
+    this.promptAttempted = true
    this.notifier.markDirty()
    let result: RpcResult<{ accepted: true }>
    try {
@@ -110,6 +141,60 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
    return result
  }

+  /**
+   * Update this Session's retained prompt while it remains editable.
+   * @param text - exact controlled value of this Session's retained prompt.
+   */
+  updatePendingPrompt(text: string): void {
+    const pending = this.pendingPrompt
+    if (pending === null || pending.phase === 'sending') return
+    this.pendingPrompt = { ...pending, text }
+    this.notifier.notifyNow()
+  }
+
+  /**
+   * Connect this frontend Session to a real Workspace and flush its retained prompt.
+   * @param workspaceId - real Workspace target.
+   */
+  connect(workspaceId: WorkspaceId): void {
+    const intent = this.intent
+    const pending = this.pendingPrompt
+    if (intent === null || intent.phase === 'connecting' || pending === null || pending.text.trim() === '') return
+    const connecting: SessionIntentSnapshot = {
+      target: { kind: 'workspace', workspaceId },
+      phase: 'connecting',
+    }
+    const queued: PendingPrompt = {
+      ...pending,
+      phase: 'sending',
+      retry: 'connect',
+      workspaceId,
+    }
+    delete queued.error
+    this.intent = connecting
+    this.pendingPrompt = queued
+    this.notifier.notifyNow()
+    void this.flushPendingPrompt()
+  }
+
+  /** Stop a superseded frontend Intent from automatically sending after publication. */
+  abandonIntent(): void {
+    if (this.intent === null) return
+    this.intentGeneration += 1
+  }
+
+  /** Retry this Session's retained prompt from its failed prerequisite. */
+  retryPendingPrompt(): void {
+    const pending = this.pendingPrompt
+    if (pending === null || pending.phase === 'sending' || pending.text.trim() === '') return
+    const sending: PendingPrompt = { ...pending, phase: 'sending' }
+    delete sending.error
+    this.pendingPrompt = sending
+    this.promptError = null
+    this.notifier.markDirty()
+    void this.flushPendingPrompt()
+  }
+
  /**
   * Stop: contract session.cancel 1:1; failures land in promptError (same error-strip display slot).
   * @returns the cancel result.
@@ -277,6 +362,11 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
    this.notifier.markDirty()
  }

+  /** Mark that Host publication is known without resolving an uncertain local create response. */
+  handlePublished(): void {
+    this.markPublished()
+  }
+
  /** host/session-removed relay: flag the snapshot (instance survives — resident-instance rule). */
  handleRemoved(): void {
    this.removed = true
@@ -292,8 +382,7 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
    this.notifier.markDirty()
  }

-  /** Instance-eviction hook, reserved no-op (design §F.6): resident instances are never destroyed
-   *  in v1; an eviction policy lands here (unsubscribe, drop buffers) without touching call sites. */
+  /** No-op because session instances remain resident. */
  dispose(): void {}

  // ---- 私有 ----
@@ -311,6 +400,112 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
    this.pendingRev++
  }

+  /** Advance the retained prompt through Session attachment and submission. */
+  private async flushPendingPrompt(): Promise<void> {
+    const pending = this.pendingPrompt
+    if (pending?.phase === 'sending') {
+      const ready = pending.retry === 'connect'
+        ? await this.attachPendingPrompt(pending)
+        : pending
+      if (ready !== null) await this.sendPendingPrompt(ready)
+    }
+  }
+
+  /** Complete the Host Session prerequisite and return the prompt's send step. */
+  private async attachPendingPrompt(pending: PendingPrompt): Promise<PendingPrompt | null> {
+    const workspaceId = pending.workspaceId
+    if (workspaceId === undefined) throw new Error('a Session attachment requires a Workspace id')
+    const originIntent = this.intent
+    const originGeneration = this.intentGeneration
+    let result: RpcResult<{ sessionId: SessionId }>
+    try {
+      result = (await this.api.sessions.create({ sessionId: this.sessionId, workspaceId })).result
+    } catch (error) {
+      result = transportError(error)
+    }
+    let ready: PendingPrompt | null = null
+    if (result.ok) {
+      ready = this.completePendingAttachment(pending, originIntent, originGeneration)
+    } else {
+      this.failPendingAttachment(pending, originIntent, originGeneration, result.error)
+    }
+    this.notifier.markDirty()
+    return ready
+  }
+
+  /** Move a published Session to the send step unless its page intent was superseded. */
+  private completePendingAttachment(
+    pending: PendingPrompt,
+    originIntent: SessionIntentSnapshot | null,
+    originGeneration: number,
+  ): PendingPrompt | null {
+    this.markPublished()
+    this.intent = null
+    this.promptAttempted = true
+    const superseded = originIntent !== null && originGeneration !== this.intentGeneration
+    const next: PendingPrompt = {
+      ...pending,
+      phase: superseded ? 'failed' : 'sending',
+      retry: 'send',
+      ...(superseded ? { error: 'Message was not sent because you navigated away.' } : {}),
+    }
+    if (!superseded) delete next.error
+    this.pendingPrompt = next
+    return superseded ? null : next
+  }
+
+  /** Retain the prompt at the failed attachment step that owns the retry. */
+  private failPendingAttachment(
+    pending: PendingPrompt,
+    originIntent: SessionIntentSnapshot | null,
+    originGeneration: number,
+    error: RpcError,
+  ): void {
+    const partiallyPublished = error.code === 'workspace-attach-failed'
+    if (partiallyPublished) {
+      this.markPublished()
+      this.intent = null
+      this.promptAttempted = true
+    }
+    const activeIntent = !partiallyPublished
+      && originIntent !== null
+      && originGeneration === this.intentGeneration
+      && this.intent === originIntent
+    if (activeIntent) {
+      this.intent = {
+        target: originIntent.target,
+        phase: 'ready',
+        error: { step: 'session', message: rpcErrorMessage(error) },
+      }
+      this.pendingPrompt = { ...pending, phase: 'editing' }
+    }
+    if (!activeIntent && (partiallyPublished || originIntent === null) && this.pendingPrompt === pending) {
+      this.pendingPrompt = { ...pending, phase: 'failed', error: rpcErrorMessage(error) }
+    }
+  }
+
+  /** Submit the retained prompt and keep it only when Host rejects the send. */
+  private async sendPendingPrompt(pending: PendingPrompt): Promise<void> {
+    const result = await this.prompt([{ type: 'text', text: pending.text.trim() }], 'queue')
+    if (this.pendingPrompt === pending) {
+      this.pendingPrompt = result.ok
+        ? null
+        : {
+          ...pending,
+          retry: 'send',
+          phase: 'failed',
+          error: rpcErrorMessage(result.error),
+        }
+      this.notifier.markDirty()
+    }
+  }
+
+  private markPublished(): void {
+    if (this.published) return
+    this.published = true
+    this.options.onPublished?.(this)
+  }
+
  /** @param generation - openGeneration at launch; every await re-checks it and a stale pass
   *  drops all writes (resync superseded this open — its outcome belongs to a dead connection). */
  private async doOpen(generation: number): Promise<void> {
@@ -527,21 +722,47 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
    if (this.pendingCache === null || this.pendingCache.rev !== this.pendingRev) {
      this.pendingCache = { rev: this.pendingRev, value: [...this.pending.values()] }
    }
+    const partial = this.partial?.toPartial() ?? null
    return {
      sessionId: this.sessionId,
      nodes,
      foldDegraded: degraded,
-      partial: this.partial?.toPartial() ?? null,
+      partial,
      runningCalls: this.callsCache.value,
      pending: this.pendingCache.value,
      running: this.running,
+      composerPhase: derivePhase(
+        nodes.length > 0 || partial !== null || this.running || this.pendingCache.value.length > 0,
+        this.promptAttempted,
+      ),
      removed: this.removed,
      openState: this.openState,
      openError: this.openError,
      hasMore: this.hasMore,
      loadingOlder: this.loadingOlder,
      promptError: this.promptError,
+      intent: this.intent,
+      pendingPrompt: this.pendingPrompt,
      lastAgentError: this.lastAgentError,
    }
  }
 }
+
+function rpcErrorMessage(error: RpcError): string {
+  return `${error.code}: ${error.message}`
+}
+
+/**
+ * The composerPhase judgment — the single site that knows the predicate
+ * (consumers switch on the result, never re-derive). Monotone per session
+ * object: `hasContent` only grows within a window and `promptAttempted` is
+ * sticky, so blank → engaging → active never steps back; a failed first
+ * prompt stays engaging (retry semantics — see ComposerPhase).
+ * @param hasContent - any conversation material exists (nodes, partial, running turn, pending waits).
+ * @param promptAttempted - a prompt was initiated on this session object.
+ * @returns the derived phase.
+ */
+function derivePhase(hasContent: boolean, promptAttempted: boolean): ComposerPhase {
+  if (hasContent) return 'active'
+  return promptAttempted ? 'engaging' : 'blank'
+}
--- a/packages/client/runtime/src/client/slots.ts
+++ b/packages/client/runtime/src/client/slots.ts
@@ -235,13 +235,17 @@ export class SlotsService extends Service {
    }
  }

-  /** Build (once) the host face the installed renderer reads; sessions resolve lazily at first render. */
+  /** Build once after both object-layer services mount; session cells still resolve lazily. */
  private hostFace(): SlotRendererHost {
    if (this._host !== undefined) return this._host
    const sessions = this.ctx.get('sessions')
    if (sessions === undefined) {
      throw new Error("renderSlot('root') before the sessions service mounted — boot order puts runtime apply first")
    }
+    const workspaces = this.ctx.get('workspaces')
+    if (workspaces === undefined) {
+      throw new Error("renderSlot('root') before the workspaces service mounted — boot order puts runtime apply first")
+    }
    // Identity-stable view: current rides the list snapshot (arbitrated), but
    // the provider consumes it as its own observable; one cached object keeps
    // the renderer's per-source hook cache stable.
@@ -262,6 +266,7 @@ export class SlotsService extends Service {
        current,
        cell: id => sessions.cell(id),
      },
+      workspaces: { list: workspaces.list },
    }
    return this._host
  }
--- a/packages/client/runtime/src/client/workspaces/manager.ts
+++ b/packages/client/runtime/src/client/workspaces/manager.ts
@@ -0,0 +1,282 @@
+/** Workspace baseline, incremental-frame, and unary-action owner. */
+
+import type {
+  HostFrame, IApiClient, RpcError, RpcRequest, RpcResult, SessionId, WorkspaceId, WorkspaceView,
+} from '@deepseek-ai/dsh-client-connection/client'
+import { transportError } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { mergeOrderedBaseline } from '../ordered-baseline.ts'
+import { Notifier } from '../sessions/notifier.ts'
+import {
+  Workspace, type WorkspaceCreateInput, type WorkspaceIntentSnapshot,
+} from './workspace.ts'
+
+export type { WorkspaceIntentSnapshot } from './workspace.ts'
+
+/** Monotone workspace-list arrival lifecycle. */
+export type WorkspaceListPhase = 'pending' | 'ready'
+
+/** Immutable workspace-list snapshot. */
+export interface WorkspaceListSnapshot {
+  items: readonly WorkspaceView[]
+  /** The sole page-local Workspace intent; never persisted or sent over the Host stream. */
+  intent: WorkspaceIntentSnapshot | undefined
+  state: 'idle' | 'loading' | 'error'
+  phase: WorkspaceListPhase
+  error: RpcError | null
+}
+
+/** Workspace object cluster driven by one list baseline and changed-frame upserts. */
+export class WorkspaceManager {
+  private items: Workspace[] = []
+  private intent: Workspace | undefined
+  private itemViewsSource: readonly Workspace[] | null = null
+  private itemViewsCache: readonly WorkspaceView[] = []
+  private state: WorkspaceListSnapshot['state'] = 'idle'
+  private phase: WorkspaceListPhase = 'pending'
+  private error: RpcError | null = null
+  private inflight: Promise<void> | null = null
+  private refreshFrames: WorkspaceView[] | null = null
+  private snapshotCache: WorkspaceListSnapshot
+  private readonly notifier = new Notifier(() => {
+    this.snapshotCache = this.buildSnapshot()
+  })
+
+  /** @param api - shared wire client. */
+  constructor(private readonly api: IApiClient) {
+    this.snapshotCache = this.buildSnapshot()
+  }
+
+  /**
+   * Replace the current client-local Workspace intent object.
+   * @param name - directory/display name used if the intent is materialized.
+   * @returns the new intent snapshot.
+   */
+  startIntent(name = 'workspace'): WorkspaceIntentSnapshot {
+    this.intent = new Workspace(this.api, { name })
+    this.notifier.notifyNow()
+    return this.intent.getSnapshot().intent as WorkspaceIntentSnapshot
+  }
+
+  /** Discard the current client-local Workspace intent. */
+  discardIntent(): void {
+    if (this.intent === undefined) return
+    this.intent = undefined
+    this.notifier.notifyNow()
+  }
+
+  /**
+   * Materialize the current Workspace intent through the ordinary Host create seam.
+   * A superseded intent is never cleared by an older completion.
+   * @returns the Host create result, or undefined when no intent exists.
+   */
+  async materializeIntent(): Promise<RpcResult<{ workspace: WorkspaceView; created: boolean }> | undefined> {
+    const intent = this.intent
+    if (intent?.getSnapshot().intent?.phase !== 'ready') return undefined
+    const completion = intent.materialize()
+    if (completion === undefined) return undefined
+    this.notifier.notifyNow()
+    const result = await completion
+    if (result.ok) {
+      this.upsert(result.value.workspace, intent)
+      if (this.intent === intent) this.intent = undefined
+    }
+    this.notifier.markDirty()
+    return result
+  }
+
+  /**
+   * Refresh from workspace.list. The first successful response establishes
+   * Host order; later responses update membership and values without moving
+   * identities already visible to the client. Frames arriving during the RPC
+   * are replayed over its response.
+   * @returns the shared in-flight refresh.
+   */
+  refresh(): Promise<void> {
+    if (this.inflight !== null) return this.inflight
+    this.state = 'loading'
+    this.error = null
+    const established = this.itemViews()
+    const frames: WorkspaceView[] = []
+    this.refreshFrames = frames
+    this.notifier.markDirty()
+    this.inflight = (async () => {
+      try {
+        const { result } = await this.api.workspace.list({})
+        if (result.ok) {
+          let items = this.phase === 'pending'
+            ? result.value.items
+            : mergeOrderedBaseline(established, result.value.items, workspace => workspace.workspaceId)
+          for (const workspace of frames) items = upsertWorkspace(items, workspace)
+          this.installViews(items)
+          this.state = 'idle'
+          this.phase = 'ready'
+        } else {
+          this.state = 'error'
+          this.error = result.error
+        }
+      } catch (error) {
+        this.state = 'error'
+        const folded = transportError<never>(error)
+        /* v8 ignore next -- transportError always returns the failure branch. */
+        this.error = folded.ok ? null : folded.error
+      } finally {
+        this.refreshFrames = null
+        this.inflight = null
+        this.notifier.markDirty()
+      }
+    })()
+    return this.inflight
+  }
+
+  /**
+   * Create or resolve a real Workspace, then publish its returned snapshot
+   * without waiting for the changed frame.
+   * @param input - name under workspaceRoot or an existing absolute path.
+   * @returns the wire result.
+   */
+  async create(input: WorkspaceCreateInput): Promise<RpcResult<{ workspace: WorkspaceView; created: boolean }>> {
+    const workspace = new Workspace(this.api, input)
+    const completion = workspace.materialize()
+    if (completion === undefined) throw new Error('a local Workspace must be materializable')
+    const result = await completion
+    if (result.ok) this.upsert(result.value.workspace, workspace)
+    return result
+  }
+
+  /**
+   * Rename a Workspace, then publish its returned snapshot without waiting
+   * for the changed frame.
+   * @param workspaceId - target workspace.
+   * @param title - new display title.
+   * @returns the wire result.
+   */
+  async rename(workspaceId: WorkspaceId, title: string): Promise<RpcResult<{ workspace: WorkspaceView }>> {
+    const { result } = await this.api.workspace.rename({ workspaceId, title })
+    if (result.ok) this.upsert(result.value.workspace)
+    return result
+  }
+
+  /**
+   * Move a session within its Workspace's manual order, then publish the
+   * returned snapshot without waiting for the changed frame.
+   * @param workspaceId - owning workspace.
+   * @param sessionId - accounted session to move.
+   * @param beforeSessionId - accounted anchor to insert before; omitted appends.
+   * @returns the wire result.
+   */
+  async insertSessionBefore(
+    workspaceId: WorkspaceId,
+    sessionId: SessionId,
+    beforeSessionId?: SessionId,
+  ): Promise<RpcResult<{ workspace: WorkspaceView }>> {
+    const { result } = await this.api.workspace.insertSessionBefore({
+      workspaceId, sessionId,
+      ...beforeSessionId === undefined ? {} : { beforeSessionId },
+    })
+    if (result.ok) this.upsert(result.value.workspace)
+    return result
+  }
+
+  /**
+   * Host-frame entry. Non-workspace frames are ignored so the runtime can
+   * fan one host stream out to both object managers.
+   * @param envelope - host stream envelope.
+   */
+  handleHostEnvelope(envelope: RpcRequest<HostFrame>): void {
+    if (envelope.payload.type === 'host/workspace-changed') this.upsert(envelope.payload.workspace)
+  }
+
+  /** Re-pull the baseline after each connection generation. */
+  handleConnected(): void {
+    void this.refresh()
+  }
+
+  /**
+   * Subscribe to workspace snapshot invalidation.
+   * @param listener - snapshot invalidation callback.
+   * @returns unsubscribe function.
+   */
+  subscribe(listener: () => void): () => void {
+    return this.notifier.subscribe(listener)
+  }
+
+  /**
+   * Read the cached workspace snapshot after flushing pending notifications.
+   * @returns the cached workspace snapshot.
+   */
+  getSnapshot(): WorkspaceListSnapshot {
+    this.notifier.ensureFresh()
+    return this.snapshotCache
+  }
+
+  private buildSnapshot(): WorkspaceListSnapshot {
+    return {
+      items: this.itemViews(),
+      intent: this.intent?.getSnapshot().intent,
+      state: this.state,
+      phase: this.phase,
+      error: this.error,
+    }
+  }
+
+  /** Upsert one Host view, optionally retaining the local object that materialized it. */
+  private upsert(view: WorkspaceView, identity?: Workspace): void {
+    this.refreshFrames?.push(view)
+    const index = this.items.findIndex(item => item.getSnapshot().view?.workspaceId === view.workspaceId)
+    // Mutation responses and changed frames race (two carriers, no ordering):
+    // reject a snapshot strictly older than the installed projection so a
+    // late unary response cannot roll back a newer frame.
+    const installed = index === -1 ? undefined : this.items[index]?.getSnapshot().view
+    if (installed !== undefined && Date.parse(view.updatedAt) < Date.parse(installed.updatedAt)) return
+    if (identity !== undefined) {
+      this.items = index === -1
+        ? [identity, ...this.items]
+        : this.items.map((item, position) => position === index ? identity : item)
+    } else if (index === -1) {
+      this.items = [new Workspace(this.api, view), ...this.items]
+    } else {
+      this.items[index]?.adopt(view)
+      this.items = [...this.items]
+    }
+    this.notifier.markDirty()
+  }
+
+  private installViews(views: readonly WorkspaceView[]): void {
+    const existing = new Map(
+      this.items.flatMap((workspace) => {
+        const view = workspace.getSnapshot().view
+        return view === undefined ? [] : [[view.workspaceId, workspace] as const]
+      }),
+    )
+    const installed = new Map<WorkspaceView['workspaceId'], Workspace>()
+    for (const view of views) {
+      const duplicate = installed.get(view.workspaceId)
+      if (duplicate !== undefined) {
+        duplicate.adopt(view)
+        continue
+      }
+      const workspace = existing.get(view.workspaceId) ?? new Workspace(this.api, view)
+      workspace.adopt(view)
+      installed.set(view.workspaceId, workspace)
+    }
+    this.items = [...installed.values()]
+  }
+
+  private itemViews(): readonly WorkspaceView[] {
+    if (this.itemViewsSource === this.items) return this.itemViewsCache
+    this.itemViewsSource = this.items
+    this.itemViewsCache = this.items.flatMap((workspace) => {
+      const view = workspace.getSnapshot().view
+      return view === undefined ? [] : [view]
+    })
+    return this.itemViewsCache
+  }
+}
+
+/** Known ids retain their position; a newly created Workspace enters first. */
+function upsertWorkspace(items: readonly WorkspaceView[], workspace: WorkspaceView): WorkspaceView[] {
+  const index = items.findIndex(item => item.workspaceId === workspace.workspaceId)
+  return index === -1
+    ? [workspace, ...items]
+    : items.map((item, position) => position === index ? workspace : item)
+}
--- a/packages/client/runtime/src/client/workspaces/service.ts
+++ b/packages/client/runtime/src/client/workspaces/service.ts
@@ -0,0 +1,193 @@
+/** WorkspacesService projects the Workspace object manager for UI consumers. */
+
+import type { Context } from 'cordis'
+import type {
+  IApiClient, RpcError, SessionId, WorkspaceId, WorkspaceView,
+} from '@deepseek-ai/dsh-client-connection/client'
+import type { SnapshotStore } from '../contract/store.ts'
+import { createSnapshotStore } from '../contract/store.ts'
+import type { SessionsService } from '../sessions/service.ts'
+import { WorkspaceManager, type WorkspaceIntentSnapshot, type WorkspaceListPhase } from './manager.ts'
+
+/** Workspace list plus the two-baseline readiness and default-target projection. */
+export interface WorkspaceListState {
+  items: readonly WorkspaceView[]
+  /** Sole client-local Workspace projection; its state remains owned by Workspace. */
+  intent: WorkspaceIntentSnapshot | undefined
+  state: 'idle' | 'loading' | 'error'
+  phase: WorkspaceListPhase
+  error: RpcError | null
+  /** True only after both workspace.list and session.list have succeeded. */
+  baselinesReady: boolean
+  /** Most recently active Workspace, derived without changing `items` order. */
+  recentWorkspaceId: WorkspaceId | undefined
+}
+
+/** Real Workspace object layer and Host actions. */
+export class WorkspacesService {
+  /** UI-facing immutable projection; the manager remains wire truth. */
+  readonly list: SnapshotStore<WorkspaceListState>
+  /** Workspace baseline and frame owner. */
+  private readonly manager: WorkspaceManager
+  private initialSessionResolved = false
+  private composingIntent = false
+
+  /**
+   * @param ctx - client root context.
+   * @param api - shared wire client.
+   * @param sessions - lower-level Session service used for recency and cross-domain intent orchestration.
+   */
+  constructor(ctx: Context, api: IApiClient, private readonly sessions: SessionsService) {
+    this.manager = new WorkspaceManager(api)
+    this.list = createSnapshotStore<WorkspaceListState>({
+      items: [], intent: undefined, state: 'idle', phase: 'pending', error: null,
+      baselinesReady: false, recentWorkspaceId: undefined,
+    })
+    this.manager.subscribe(() => { if (!this.composingIntent) this.project() })
+    this.sessions.list.subscribe(() => { if (!this.composingIntent) this.project() })
+    ctx.reflect.provide('workspaces', this, undefined)
+  }
+
+  /**
+   * Start the sole Session intent, resolving the default Workspace here.
+   * @param workspaceId - optional explicit real Workspace target.
+   * @param prompt - optional prompt retained while retargeting.
+   */
+  startSession(workspaceId?: WorkspaceId, prompt = ''): void {
+    const snapshot = this.list.getSnapshot()
+    const resolved = workspaceId ?? snapshot.recentWorkspaceId ?? snapshot.items[0]?.workspaceId
+    this.composingIntent = true
+    try {
+      if (resolved === undefined) {
+        this.manager.startIntent()
+        this.sessions.startIntent({ kind: 'workspace-intent' }, prompt)
+      } else {
+        this.manager.discardIntent()
+        this.sessions.startIntent({ kind: 'workspace', workspaceId: resolved }, prompt)
+      }
+    } finally {
+      this.composingIntent = false
+      this.project()
+    }
+  }
+
+  /** Connect the current frontend Workspace and Session, then flush the Session-owned prompt. */
+  sendSession(): void {
+    const session = this.sessions.intent()
+    const target = session?.getSnapshot().intent?.target
+    if (session === undefined || target === undefined) return
+    if (target.kind === 'workspace') {
+      session.connect(target.workspaceId)
+      return
+    }
+    if (session.getSnapshot().pendingPrompt?.text.trim() === '') return
+    void this.manager.materializeIntent().then((result) => {
+      if (this.sessions.intent() !== session) return
+      if (result?.ok) {
+        session.connect(result.value.workspace.workspaceId)
+      }
+    })
+  }
+
+  /**
+   * Create a Workspace by name or register an existing path.
+   * @param input - exactly one Host create spelling.
+   * @returns the created or idempotently resolved Workspace.
+   */
+  async create(input: { name: string } | { path: string }): Promise<WorkspaceView> {
+    const result = await this.manager.create(input)
+    if (!result.ok) throw new Error(`workspace create failed: ${result.error.code}: ${result.error.message}`)
+    return result.value.workspace
+  }
+
+  /**
+   * Rename a Workspace.
+   * @param workspaceId - target workspace.
+   * @param title - new display title (trimmed non-empty by the Host).
+   * @returns the renamed Workspace view.
+   */
+  async rename(workspaceId: WorkspaceId, title: string): Promise<WorkspaceView> {
+    const result = await this.manager.rename(workspaceId, title)
+    if (!result.ok) throw new Error(`workspace rename failed: ${result.error.code}: ${result.error.message}`)
+    return result.value.workspace
+  }
+
+  /**
+   * Move a session within its Workspace's manual order (DOM-insertBefore-like).
+   * @param workspaceId - owning workspace.
+   * @param sessionId - accounted session to move.
+   * @param beforeSessionId - accounted anchor to insert before; omitted appends.
+   * @returns the updated Workspace view.
+   */
+  async insertSessionBefore(
+    workspaceId: WorkspaceId,
+    sessionId: SessionId,
+    beforeSessionId?: SessionId,
+  ): Promise<WorkspaceView> {
+    const result = await this.manager.insertSessionBefore(workspaceId, sessionId, beforeSessionId)
+    if (!result.ok) throw new Error(`workspace move failed: ${result.error.code}: ${result.error.message}`)
+    return result.value.workspace
+  }
+
+  /**
+   * Refresh the workspace baseline, reusing an in-flight pull.
+   * @returns completion of the current or newly started workspace baseline pull.
+   */
+  refresh(): Promise<void> {
+    return this.manager.refresh()
+  }
+
+  /**
+   * Route a Host stream envelope into the Workspace object layer.
+   * @param envelope - validated Host stream envelope.
+   */
+  handleHostEnvelope(envelope: Parameters<WorkspaceManager['handleHostEnvelope']>[0]): void {
+    this.manager.handleHostEnvelope(envelope)
+  }
+
+  /** Rebuild the Workspace baseline after connection. */
+  handleConnected(): void {
+    this.manager.handleConnected()
+  }
+
+  private project(): void {
+    const workspace = this.manager.getSnapshot()
+    const sessions = this.sessions.list.getSnapshot()
+    if (workspace.intent !== undefined && sessions.intent?.target.kind !== 'workspace-intent') {
+      this.manager.discardIntent()
+      return
+    }
+    const baselinesReady = workspace.phase === 'ready' && sessions.phase === 'ready'
+    this.list.set({
+      ...workspace,
+      baselinesReady,
+      recentWorkspaceId: baselinesReady ? recentWorkspace(workspace.items, sessions.byId) : undefined,
+    })
+    if (!this.initialSessionResolved && baselinesReady) {
+      this.initialSessionResolved = true
+      if (sessions.current === undefined && sessions.intent === undefined) this.startSession()
+    }
+  }
+}
+
+/** Stable tie-breaking follows Host Workspace order. */
+function recentWorkspace(
+  workspaces: readonly WorkspaceView[],
+  sessions: ReturnType<SessionsService['list']['getSnapshot']>['byId'],
+): WorkspaceId | undefined {
+  let selected: WorkspaceId | undefined
+  let selectedTime = Number.NEGATIVE_INFINITY
+  for (const workspace of workspaces) {
+    let latest = Number.NEGATIVE_INFINITY
+    for (const sessionId of workspace.sessionIds) {
+      const session = sessions[sessionId]
+      if (session !== undefined) latest = Math.max(latest, session.updatedAt)
+    }
+    if (latest === Number.NEGATIVE_INFINITY) latest = Date.parse(workspace.createdAt)
+    if (selected === undefined || latest > selectedTime) {
+      selected = workspace.workspaceId
+      selectedTime = latest
+    }
+  }
+  return selected
+}
--- a/packages/client/runtime/src/client/workspaces/workspace.ts
+++ b/packages/client/runtime/src/client/workspaces/workspace.ts
@@ -0,0 +1,143 @@
+/** React-free Workspace entity with a client-local materialization lifecycle. */
+
+import type {
+  IApiClient, RpcResult, WorkspaceView,
+} from '@deepseek-ai/dsh-client-connection/client'
+import { transportError } from '@deepseek-ai/dsh-host-apiproxy/api'
+import type { ObservableSnapshot } from '../contract/store.ts'
+import { Notifier } from '../sessions/notifier.ts'
+
+/** Host input retained by a local Workspace until materialization succeeds. */
+export type WorkspaceCreateInput = { name: string } | { path: string }
+
+/** Observable state of a client-local Workspace intent. */
+export interface WorkspaceIntentSnapshot {
+  name: string
+  phase: 'ready' | 'creating'
+  error?: string
+}
+
+/** A Workspace is either a local intent or a materialized Host view. */
+export interface WorkspaceSnapshot {
+  view: WorkspaceView | undefined
+  intent: WorkspaceIntentSnapshot | undefined
+}
+
+interface WorkspaceIntent {
+  input: WorkspaceCreateInput
+  snapshot: WorkspaceIntentSnapshot
+}
+
+/**
+ * Observable Workspace object whose identity survives Host materialization.
+ * Local instances retain their create input and failure state; materialized
+ * instances expose the latest Host view.
+ */
+export class Workspace implements ObservableSnapshot<WorkspaceSnapshot> {
+  private view: WorkspaceView | undefined
+  private intent: WorkspaceIntent | undefined
+  private materialization: Promise<RpcResult<{ workspace: WorkspaceView; created: boolean }>> | null = null
+  private snapshotCache: WorkspaceSnapshot
+  private readonly notifier = new Notifier(() => {
+    this.snapshotCache = this.buildSnapshot()
+  })
+
+  /**
+   * @param api - shared wire client.
+   * @param source - local create input or an existing Host Workspace view.
+   */
+  constructor(private readonly api: IApiClient, source: WorkspaceCreateInput | WorkspaceView) {
+    if ('workspaceId' in source) {
+      this.view = source
+    } else {
+      this.intent = {
+        input: source,
+        snapshot: { name: intentName(source), phase: 'ready' },
+      }
+    }
+    this.snapshotCache = this.buildSnapshot()
+  }
+
+  /**
+   * Materialize this local Workspace through the Host create seam.
+   * Re-entry shares the in-flight completion; a materialized instance returns undefined.
+   * @returns the Host result, or undefined when this Workspace is already materialized.
+   */
+  materialize(): Promise<RpcResult<{ workspace: WorkspaceView; created: boolean }>> | undefined {
+    if (this.materialization !== null) return this.materialization
+    const intent = this.intent
+    if (intent === undefined) return undefined
+    intent.snapshot = { name: intent.snapshot.name, phase: 'creating' }
+    this.notifier.notifyNow()
+    const completion = this.completeMaterialization(intent).finally(() => {
+      if (this.materialization === completion) this.materialization = null
+    })
+    this.materialization = completion
+    return completion
+  }
+
+  /**
+   * Adopt a Host view without replacing this Workspace object.
+   * An existing materialized identity accepts updates only for the same Workspace id.
+   * @param view - latest Host projection.
+   */
+  adopt(view: WorkspaceView): void {
+    if (this.view !== undefined && this.view.workspaceId !== view.workspaceId) {
+      throw new Error('cannot adopt a different Workspace id')
+    }
+    this.view = view
+    this.intent = undefined
+    this.notifier.markDirty()
+  }
+
+  /**
+   * Subscribe to Workspace snapshot invalidation.
+   * @param listener - snapshot invalidation callback.
+   * @returns unsubscribe function.
+   */
+  subscribe(listener: () => void): () => void {
+    return this.notifier.subscribe(listener)
+  }
+
+  /**
+   * Read the cached Workspace snapshot after flushing pending notifications.
+   * @returns the cached Workspace snapshot.
+   */
+  getSnapshot(): WorkspaceSnapshot {
+    this.notifier.ensureFresh()
+    return this.snapshotCache
+  }
+
+  private async completeMaterialization(
+    intent: WorkspaceIntent,
+  ): Promise<RpcResult<{ workspace: WorkspaceView; created: boolean }>> {
+    let result: RpcResult<{ workspace: WorkspaceView; created: boolean }>
+    try {
+      result = (await this.api.workspace.create(intent.input)).result
+    } catch (error) {
+      result = transportError(error)
+    }
+    if (this.intent !== intent) return result
+    if (result.ok) {
+      this.adopt(result.value.workspace)
+    } else {
+      intent.snapshot = {
+        name: intent.snapshot.name,
+        phase: 'ready',
+        error: `${result.error.code}: ${result.error.message}`,
+      }
+      this.notifier.markDirty()
+    }
+    return result
+  }
+
+  private buildSnapshot(): WorkspaceSnapshot {
+    return { view: this.view, intent: this.intent?.snapshot }
+  }
+}
+
+function intentName(input: WorkspaceCreateInput): string {
+  if ('name' in input) return input.name
+  const trimmed = input.path.replace(/[\\/]+$/, '')
+  return trimmed.split(/[\\/]/).pop() ?? input.path
+}
--- a/packages/client/runtime/src/index.ts
+++ b/packages/client/runtime/src/index.ts
@@ -1,11 +1,4 @@
-/**
- * Runtime plugin, node half. The implementation lives entirely in the client
- * half (src/client/ — SlotsService, SessionsService + object layer, and the
- * shell-held ClientLoader under ./loader); consumers import the /client or
- * /loader subpaths. The empty apply exists so the plugin appears in the host
- * Loader (lifecycle governance + dshClient discovery). Contract:
- * api-contracts v3 section 4.
- */
+/** Host loader entry for the browser runtime exported from `./client` and `./loader`. */

 /** Host plugin body — no host-side behavior for the runtime plugin. */
 export function apply(_ctx: unknown): void {}
--- a/packages/client/runtime/tests/client-apply.spec.ts
+++ b/packages/client/runtime/tests/client-apply.spec.ts
@@ -1,5 +1,5 @@
 /**
- * Runtime plugin browser-half apply: slots + sessions mounting over the
+ * Runtime plugin browser-half apply: slots + object services mounting over the
 * connection handle, stream-loop sink wiring into the object layer, and the
 * fiber-scoped loop teardown.
 */
@@ -34,14 +34,17 @@ async function mount(): Promise<Bench> {
 }

 describe('runtime client apply', () => {
-  it('mounts ctx.slots + ctx.sessions and wires the stream sinks into the manager', async () => {
+  it('mounts slots, Sessions, and Workspaces and fans host frames into both managers', async () => {
    const bench = await mount()
    expect(bench.ctx.get('slots') !== undefined).toBe(true)
    // The built-in 'root' declaration ships with this package's SlotsService
    // (the SlotMap 'root' merge lives here since the slot-parity rework).
    expect(bench.ctx.slots.spec('root')).toEqual({ kind: 'single', scope: 'root' })
    const sessions = bench.ctx.get('sessions')
+    const workspaces = bench.ctx.get('workspaces')
    expect(sessions !== undefined).toBe(true)
+    expect(workspaces !== undefined).toBe(true)
+    if (workspaces === undefined) throw new Error('WorkspacesService missing after runtime apply')
    expect(bench.sinks).toBeDefined()

    // Frame sinks reach the object layer: a host session-added lands in the list store.
@@ -51,6 +54,18 @@ describe('runtime client apply', () => {
    })
    await Promise.resolve()
    expect((sessions as { list: { getSnapshot(): { ids: string[] } } }).list.getSnapshot().ids).toContain('s-new')
+    bench.sinks?.onHostEnvelope?.({
+      rpcId: 'r-workspace' as never,
+      payload: {
+        type: 'host/workspace-changed',
+        workspace: {
+          workspaceId: 'w-new', path: '/w/new', title: 'new', sessionIds: [],
+          createdAt: '2026-01-01T00:00:00.000Z', updatedAt: '2026-01-01T00:00:00.000Z',
+        },
+      } as never,
+    })
+    await Promise.resolve()
+    expect(workspaces.list.getSnapshot().items[0]?.workspaceId).toBe('w-new')
    // Mux sink and onConnected route without throwing (manager semantics own the behavior).
    bench.sinks?.onMuxEnvelope?.({ rpcId: 'r2' as never, payload: { type: 'stream/error', message: 'x' } as never })
    bench.sinks?.onConnected?.()
--- a/packages/client/runtime/tests/fake-api.ts
+++ b/packages/client/runtime/tests/fake-api.ts
@@ -3,9 +3,23 @@
 // deferred-controlled timing). Streams are hand pumps: pushMux/pushHost.
 import type {
  ClientResponse, HostFrame, IApiClient, MuxFrame, RpcError, RpcReceipt, RpcRequest, RpcResponse, SessionId,
+  WorkspaceId, WorkspaceView,
 } from '@deepseek-ai/dsh-client-connection/client'
 import { RpcId } from '@deepseek-ai/dsh-client-connection/client'

+/** Programmable-default workspace row (branded id, ISO-ish times). */
+function fakeWorkspace(id: string, over: Partial<WorkspaceView> = {}): WorkspaceView {
+  return {
+    workspaceId: id as WorkspaceId,
+    path: '/f/ws',
+    title: 'ws',
+    sessionIds: [],
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+    ...over,
+  }
+}
+
 export interface Deferred<T> {
  promise: Promise<T>
  resolve(value: T): void
@@ -74,6 +88,24 @@ export class FakeApiClient implements IApiClient {
    describe: (payload: unknown) => this.record('host.describe', payload, this.onDescribe(payload)),
  }

+  onWorkspaceList: (payload: unknown) => Promise<RpcResponse<{ items: never[] }>> = () => Promise.resolve(ok({ items: [] }))
+  onWorkspaceCreate: (payload: unknown) => Promise<RpcResponse<{ workspace: WorkspaceView; created: boolean }>> =
+    () => Promise.resolve(ok({ workspace: fakeWorkspace('fk-ws'), created: true }))
+
+  onWorkspaceRename: (payload: unknown) => Promise<RpcResponse<{ workspace: WorkspaceView }>> =
+    () => Promise.resolve(ok({ workspace: fakeWorkspace('fk-ws') }))
+
+  onWorkspaceInsertSessionBefore: (payload: unknown) => Promise<RpcResponse<{ workspace: WorkspaceView }>> =
+    () => Promise.resolve(ok({ workspace: fakeWorkspace('fk-ws') }))
+
+  readonly workspace: IApiClient['workspace'] = {
+    list: (payload: unknown) => this.record('workspace.list', payload, this.onWorkspaceList(payload)),
+    create: (payload: unknown) => this.record('workspace.create', payload, this.onWorkspaceCreate(payload)),
+    rename: (payload: unknown) => this.record('workspace.rename', payload, this.onWorkspaceRename(payload)),
+    insertSessionBefore: (payload: unknown) =>
+      this.record('workspace.insertSessionBefore', payload, this.onWorkspaceInsertSessionBefore(payload)),
+  }
+
  /** When true, streams never fire onOpen (misbehaving-carrier material for the handshake timeout guard). */
  suppressStreamOpen = false

--- a/packages/client/runtime/tests/lineage.spec.ts
+++ b/packages/client/runtime/tests/lineage.spec.ts
@@ -13,7 +13,7 @@ const s = (id: string, updatedAt: number, parent?: string): SessionSummary => ({
 })

 describe('flattenLineage', () => {
-  it('sorts roots by updatedAt desc and expands children DFS with depth, children sorted too', () => {
+  it('keeps established root and sibling order while expanding children DFS with depth', () => {
    const out = flattenLineage([
      s('old-root', 10),
      s('new-root', 30),
@@ -22,7 +22,7 @@ describe('flattenLineage', () => {
      s('grandkid', 5, 'kid-new'),
    ])
    expect(out.map(e => [e.sessionId, e.depth])).toEqual([
-      ['new-root', 0], ['kid-new', 1], ['grandkid', 2], ['kid-old', 1], ['old-root', 0],
+      ['old-root', 0], ['new-root', 0], ['kid-old', 1], ['kid-new', 1], ['grandkid', 2],
    ])
  })

--- a/packages/client/runtime/tests/manager.spec.ts
+++ b/packages/client/runtime/tests/manager.spec.ts
@@ -57,7 +57,7 @@ describe('instances', () => {
 })

 describe('list lifecycle', () => {
-  it('single-flights refreshList and lands items sorted through lineage flattening', async () => {
+  it('single-flights refreshList and preserves the Host baseline order', async () => {
    const api = new FakeApiClient()
    const gate = deferred<Awaited<ReturnType<FakeApiClient['onList']>>>()
    api.onList = () => gate.promise
@@ -65,12 +65,33 @@ describe('list lifecycle', () => {
    const first = manager.refreshList()
    const second = manager.refreshList()
    expect(manager.getListSnapshot().state).toBe('loading')
-    gate.resolve(ok({ items: [summary(S1), summary(S2, { updatedAt: 200 })] as never[] }))
+    gate.resolve(ok({ items: [summary(S2, { updatedAt: 200 }), summary(S1)] as never[] }))
    await Promise.all([first, second])
    expect(api.callsOf('session.list')).toHaveLength(1)
    const snapshot = manager.getListSnapshot()
    expect(snapshot.state).toBe('idle')
-    expect(snapshot.items.map(i => i.sessionId)).toEqual([S2, S1]) // updatedAt desc
+    expect(snapshot.items.map(i => i.sessionId)).toEqual([S2, S1])
+  })
+
+  it('replays incremental frames over hydration and never batch-reorders established ids', async () => {
+    const api = new FakeApiClient()
+    const first = deferred<Awaited<ReturnType<FakeApiClient['onList']>>>()
+    api.onList = () => first.promise
+    const manager = new SessionManager(api)
+    const hydration = manager.refreshList()
+    manager.handleHostEnvelope({
+      rpcId: 'during-first' as never,
+      payload: { type: 'host/session-added', sessionId: S2 },
+    })
+    first.resolve(ok({ items: [summary(S1)] as never[] }))
+    await hydration
+    expect(manager.getListSnapshot().items.map(item => item.sessionId)).toEqual([S2, S1])
+
+    api.onList = () => Promise.resolve(ok({
+      items: [summary(S1, { updatedAt: 900 }), summary(S2, { updatedAt: 800 })] as never[],
+    }))
+    await manager.refreshList()
+    expect(manager.getListSnapshot().items.map(item => item.sessionId)).toEqual([S2, S1])
  })

  it('keeps the error in the list snapshot on failure', async () => {
@@ -79,6 +100,26 @@ describe('list lifecycle', () => {
    const manager = new SessionManager(api)
    await manager.refreshList()
    expect(manager.getListSnapshot()).toMatchObject({ state: 'error', error: { code: 'internal' } })
+    // A failed pull does not step the arrival phase: still pending.
+    expect(manager.getListSnapshot().phase).toBe('pending')
+  })
+
+  it('phase steps pending → ready on the first successful pull and never returns', async () => {
+    const api = new FakeApiClient()
+    const manager = new SessionManager(api)
+    expect(manager.getListSnapshot().phase).toBe('pending')
+    await manager.refreshList()
+    expect(manager.getListSnapshot().phase).toBe('ready')
+    // Sticky across later failures: the pull-activity axis reports the error,
+    // the arrival phase holds.
+    api.onList = () => Promise.resolve(err({ code: 'internal', message: 'down', details: {} }))
+    await manager.refreshList()
+    expect(manager.getListSnapshot()).toMatchObject({ state: 'error', phase: 'ready' })
+    // And across an empty re-pull (empty-with-ready = truly no sessions).
+    api.onList = () => Promise.resolve(ok({ items: [] as never[] }))
+    await manager.refreshList()
+    expect(manager.getListSnapshot()).toMatchObject({ state: 'idle', phase: 'ready' })
+    expect(manager.getListSnapshot().items).toEqual([])
  })

  it('merges create into the list immediately without waiting for a refresh', async () => {
@@ -192,14 +233,14 @@ describe('remaining branches', () => {
    expect(session.getSnapshot().running).toBe(true)
  })

-  it('create passes cwd through, folds transport throws, and skips the merge when already listed', async () => {
+  it('create passes cwd and a preallocated id, folds transport throws, and deduplicates the echo', async () => {
    const api = new FakeApiClient()
    api.onCreate = () => Promise.resolve(ok({ sessionId: S1 }))
    const manager = new SessionManager(api)
-    await manager.create('/tmp/w')
-    expect(api.callsOf('session.create')).toEqual([{ cwd: '/tmp/w' }])
+    await manager.create({ cwd: '/tmp/w', sessionId: S1 })
+    expect(api.callsOf('session.create')).toEqual([{ cwd: '/tmp/w', sessionId: S1 }])
    expect(manager.getListSnapshot().items[0]).toMatchObject({ sessionId: S1, cwd: '/tmp/w' })
-    await manager.create('/tmp/w') // same id returned: no duplicate row
+    await manager.create({ cwd: '/tmp/w' }) // same id returned: no duplicate row
    expect(manager.getListSnapshot().items).toHaveLength(1)
    api.onCreate = () => Promise.reject(new Error('create wire down'))
    expect(await manager.create()).toMatchObject({ ok: false, error: { code: 'internal' } })
@@ -208,6 +249,42 @@ describe('remaining branches', () => {
    expect(await manager.create()).toMatchObject({ ok: false })
  })

+  it('publishes a real Ungrouped summary from workspace-attach-failed', async () => {
+    const api = new FakeApiClient()
+    api.onCreate = () => Promise.resolve(err({
+      code: 'workspace-attach-failed',
+      message: 'published but unattached',
+      details: { sessionId: S1, workspaceId: 'w1' },
+    } as never))
+    const manager = new SessionManager(api)
+    const result = await manager.create({ workspaceId: 'w1' as never, sessionId: S1 })
+    expect(result).toMatchObject({ ok: false, error: { code: 'workspace-attach-failed' } })
+    expect(manager.getListSnapshot().items).toEqual([expect.objectContaining({ sessionId: S1 })])
+    expect(manager.getListSnapshot().items[0]).not.toHaveProperty('cwd')
+  })
+
+  it('reconciles a preallocated id after an ordinary transport failure', async () => {
+    const api = new FakeApiClient()
+    api.onCreate = () => Promise.reject(new Error('response lost'))
+    const manager = new SessionManager(api)
+    const failed = await manager.create({ workspaceId: 'w1' as never, sessionId: S1 })
+    expect(failed).toMatchObject({ ok: false, error: { message: 'response lost' } })
+    expect(manager.getListSnapshot().items).toEqual([])
+
+    manager.handleHostEnvelope({
+      rpcId: 'published-later' as never,
+      payload: { type: 'host/session-added', sessionId: S1, cwd: '/w/one' },
+    })
+    expect(manager.getListSnapshot().items).toEqual([
+      expect.objectContaining({ sessionId: S1, cwd: '/w/one' }),
+    ])
+    manager.handleHostEnvelope({
+      rpcId: 'duplicate-frame' as never,
+      payload: { type: 'host/session-added', sessionId: S1, cwd: '/w/one' },
+    })
+    expect(manager.getListSnapshot().items).toHaveLength(1)
+  })
+
  it('subscribe notifies on list changes and stops after unsubscribe', async () => {
    const api = new FakeApiClient()
    const manager = new SessionManager(api)
--- a/packages/client/runtime/tests/session-intents.spec.ts
+++ b/packages/client/runtime/tests/session-intents.spec.ts
@@ -0,0 +1,191 @@
+import { Context } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionId, WorkspaceId, WorkspaceView } from '@deepseek-ai/dsh-client-connection/client'
+import { SessionsService } from '../src/client/sessions/service.ts'
+import { WorkspacesService } from '../src/client/workspaces/service.ts'
+import { FakeApiClient, deferred, err, ok } from './fake-api.ts'
+
+const sid = (id: string): SessionId => id as SessionId
+const wid = (id: string): WorkspaceId => id as WorkspaceId
+
+function workspace(id: string, sessionIds: SessionId[] = []): WorkspaceView {
+  return {
+    workspaceId: wid(id),
+    path: `/w/${id}`,
+    title: id,
+    sessionIds,
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+  }
+}
+
+async function ready(
+  api: FakeApiClient,
+  workspaces: WorkspacesService,
+  sessions: SessionsService,
+  workspaceRows: WorkspaceView[],
+  sessionRows: { sessionId: SessionId; updatedAt: number; running: boolean }[] = [],
+): Promise<void> {
+  api.onWorkspaceList = () => Promise.resolve(ok({ items: workspaceRows as never[] }))
+  api.onList = () => Promise.resolve(ok({ items: sessionRows as never[] }))
+  await Promise.all([workspaces.refresh(), sessions.refresh()])
+  await Promise.resolve()
+}
+
+function services(api: FakeApiClient): { sessions: SessionsService; workspaces: WorkspacesService } {
+  const ctx = new Context()
+  const sessions = new SessionsService(ctx, api)
+  const workspaces = new WorkspacesService(ctx, api, sessions)
+  return { sessions, workspaces }
+}
+
+function pendingPrompt(sessions: SessionsService, sessionId: SessionId) {
+  return sessions.binding(sessionId)?.session.getSnapshot().pendingPrompt
+}
+
+describe('frontend Session and Workspace intents', () => {
+  it('resolves the initial intent into the most recently active Workspace', async () => {
+    const api = new FakeApiClient()
+    const { sessions, workspaces } = services(api)
+    const old = workspace('old', [sid('s-old')])
+    const recent = workspace('recent', [sid('s-recent')])
+    await ready(api, workspaces, sessions, [old, recent], [
+      { sessionId: sid('s-old'), updatedAt: 1, running: false },
+      { sessionId: sid('s-recent'), updatedAt: 2, running: false },
+    ])
+    expect(sessions.list.getSnapshot().intent).toMatchObject({
+      target: { kind: 'workspace', workspaceId: 'recent' },
+      phase: 'ready',
+    })
+    expect(workspaces.list.getSnapshot().intent).toBeUndefined()
+  })
+
+  it('materializes zero-state Workspace and Session intents and retains a rejected first prompt', async () => {
+    const api = new FakeApiClient()
+    const { sessions, workspaces } = services(api)
+    await ready(api, workspaces, sessions, [])
+    expect(workspaces.list.getSnapshot().intent).toMatchObject({ name: 'workspace', phase: 'ready' })
+    sessions.updateIntent('first prompt')
+    api.onWorkspaceCreate = () => Promise.resolve(ok({ workspace: workspace('created'), created: true }))
+    api.onCreate = payload => Promise.resolve(ok({
+      sessionId: (payload as { sessionId: SessionId }).sessionId,
+    }))
+    api.onPrompt = () => Promise.resolve(err({ code: 'internal', message: 'prompt offline', details: {} }))
+    workspaces.sendSession()
+    await vi.waitFor(() => {
+      const sessionId = sessions.list.getSnapshot().current as SessionId
+      expect(pendingPrompt(sessions, sessionId)).toMatchObject({
+        text: 'first prompt', phase: 'failed', retry: 'send',
+      })
+    })
+    expect(api.callsOf('workspace.create')).toEqual([{ name: 'workspace' }])
+    const create = api.callsOf('session.create')[0] as { workspaceId: WorkspaceId; sessionId: SessionId }
+    expect(create.workspaceId).toBe('created')
+    expect(api.callsOf('session.prompt')).toEqual([{
+      sessionId: create.sessionId,
+      mode: 'queue',
+      content: [{ type: 'text', text: 'first prompt' }],
+    }])
+    expect(workspaces.list.getSnapshot().intent).toBeUndefined()
+  })
+
+  it('turns Workspace attachment failure into a focused real Session and retries its prompt', async () => {
+    const api = new FakeApiClient()
+    const { sessions, workspaces } = services(api)
+    const target = workspace('target')
+    await ready(api, workspaces, sessions, [target])
+    sessions.updateIntent('keep this')
+    api.onCreate = (payload) => {
+      const sessionId = (payload as { sessionId: SessionId }).sessionId
+      return Promise.resolve(err({
+        code: 'workspace-attach-failed',
+        message: 'attach rejected',
+        details: { sessionId, workspaceId: target.workspaceId },
+      }))
+    }
+    workspaces.sendSession()
+    await vi.waitFor(() => {
+      const snapshot = sessions.list.getSnapshot()
+      expect(snapshot.intent).toBeUndefined()
+      expect(pendingPrompt(sessions, snapshot.current as SessionId)).toMatchObject({
+        text: 'keep this', phase: 'failed', retry: 'connect',
+      })
+    })
+    const published = sessions.list.getSnapshot().current as SessionId
+    const session = sessions.binding(published)!.session
+    session.updatePendingPrompt('retry this')
+    api.onCreate = () => Promise.resolve(ok({ sessionId: published }))
+    session.retryPendingPrompt()
+    await vi.waitFor(() => {
+      expect(pendingPrompt(sessions, published)).toBeNull()
+    })
+    expect(api.callsOf('session.prompt').at(-1)).toMatchObject({
+      sessionId: published,
+      content: [{ type: 'text', text: 'retry this' }],
+    })
+  })
+
+  it('does not send after navigation while Session creation is in flight', async () => {
+    const api = new FakeApiClient()
+    const { sessions, workspaces } = services(api)
+    const target = workspace('target')
+    await ready(api, workspaces, sessions, [target])
+    const gate = deferred<Awaited<ReturnType<FakeApiClient['onCreate']>>>()
+    api.onCreate = () => gate.promise
+    sessions.updateIntent('do not send yet')
+    workspaces.sendSession()
+    await vi.waitFor(() => { expect(api.callsOf('session.create')).toHaveLength(1) })
+    const requested = (api.callsOf('session.create')[0] as { sessionId: SessionId }).sessionId
+    workspaces.startSession(target.workspaceId)
+    const replacement = sessions.list.getSnapshot().intent!
+    gate.resolve(ok({ sessionId: requested }))
+    await vi.waitFor(() => {
+      expect(pendingPrompt(sessions, requested)).toMatchObject({
+        text: 'do not send yet', phase: 'failed', retry: 'send',
+      })
+    })
+    expect(api.callsOf('session.prompt')).toEqual([])
+    expect(sessions.list.getSnapshot()).toMatchObject({
+      current: replacement.sessionId,
+      intent: { sessionId: replacement.sessionId },
+    })
+  })
+
+  it('keeps a lost-response Intent and retries creation with its preallocated id', async () => {
+    const api = new FakeApiClient()
+    const { sessions, workspaces } = services(api)
+    const target = workspace('target')
+    await ready(api, workspaces, sessions, [target])
+    sessions.updateIntent('preserve me')
+    api.onCreate = () => Promise.reject(new Error('response lost'))
+    workspaces.sendSession()
+    await vi.waitFor(() => {
+      expect(sessions.list.getSnapshot().intent?.error).toMatchObject({ step: 'session' })
+    })
+    const requested = sessions.list.getSnapshot().intent?.sessionId as SessionId
+    sessions.handleHostEnvelope({
+      rpcId: 'published-later' as never,
+      payload: { type: 'host/session-added', sessionId: requested, cwd: target.path },
+    })
+    expect(sessions.list.getSnapshot()).toMatchObject({
+      current: requested,
+      intent: { sessionId: requested, error: { step: 'session' } },
+    })
+    expect(sessions.intent()?.getSnapshot().pendingPrompt).toMatchObject({
+      text: 'preserve me', phase: 'editing',
+    })
+
+    api.onCreate = payload => Promise.resolve(ok({
+      sessionId: (payload as { sessionId: SessionId }).sessionId,
+    }))
+    workspaces.sendSession()
+    await vi.waitFor(() => {
+      expect(api.callsOf('session.create')).toHaveLength(2)
+      expect(api.callsOf('session.prompt')).toHaveLength(1)
+      expect(sessions.list.getSnapshot()).toMatchObject({ current: requested, intent: undefined })
+      expect(pendingPrompt(sessions, requested)).toBeNull()
+    })
+    expect(api.callsOf('session.create').map(call => (call as { sessionId: SessionId }).sessionId))
+      .toEqual([requested, requested])
+  })
+})
--- a/packages/client/runtime/tests/session.spec.ts
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -217,19 +217,33 @@ describe('paging', () => {
 })

 describe('prompt and cancel errors', () => {
-  it('sends content through session.prompt with the mode passed through', async () => {
+  it('sends content through session.prompt; composerPhase steps blank → engaging synchronously at send entry', async () => {
    const { api, session } = makeSession()
-    const result = await session.prompt([{ type: 'text', text: '要发的' }], 'queue')
+    // The blank → engaging edge fires before the RPC settles: the first-send
+    // flow reads the phase on the session area's first frame to keep the
+    // guidance hero from flashing back in.
+    expect(session.getSnapshot().composerPhase).toBe('blank')
+    const inFlight = session.prompt([{ type: 'text', text: '要发的' }], 'queue')
+    expect(session.getSnapshot().composerPhase).toBe('engaging')
+    const result = await inFlight
    expect(result.ok).toBe(true)
+    // Monotone: settlement alone does not step the phase anywhere.
+    expect(session.getSnapshot().composerPhase).toBe('engaging')
    expect(api.callsOf('session.prompt')).toMatchObject([{ sessionId: SID, mode: 'queue', content: [{ type: 'text', text: '要发的' }] }])
+    // First content lands (running turn): engaging → active.
+    session.handleRunning(true)
+    expect(session.getSnapshot().composerPhase).toBe('active')
  })

-  it('business failure lands in promptError with op=send', async () => {
+  it('business failure lands in promptError with op=send; the phase stays engaging (retry, no hero bounce)', async () => {
    const { api, session } = makeSession()
    api.onPrompt = () => Promise.resolve(err({ code: 'agent-busy', message: 'busy', details: { reason: 'x' } }))
    const result = await session.prompt([{ type: 'text', text: '失败的' }], 'queue')
    expect(result.ok).toBe(false)
    expect(session.getSnapshot().promptError).toMatchObject({ op: 'send', error: { code: 'agent-busy' } })
+    // Failed first prompt: composer + error strip is the retry surface —
+    // blank is unreachable once a send was initiated.
+    expect(session.getSnapshot().composerPhase).toBe('engaging')
  })

  it('lands cancel failures in promptError with op=stop', async () => {
--- a/packages/client/runtime/tests/sessions-service.spec.ts
+++ b/packages/client/runtime/tests/sessions-service.spec.ts
@@ -9,7 +9,7 @@
 import { Context } from 'cordis'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
-import { SessionsService, scopeOf } from '../src/client/sessions/service.ts'
+import { SessionCreateError, SessionsService, scopeOf } from '../src/client/sessions/service.ts'
 import { FakeApiClient, ok } from './fake-api.ts'

 const sid = (s: string): SessionId => s as SessionId
@@ -36,14 +36,14 @@ async function feedList(b: Bench, rows: { id: string; cwd?: string; parentId?: s
      ...(r.parentId !== undefined ? { parentSessionId: sid(r.parentId) } : {}),
    })),
  }) as never)
-  await b.svc.manager.refreshList()
+  await b.svc.refresh()
  await Promise.resolve() // manager notifier flush
 }

 describe('list store projection', () => {
  it('projects durable titles separately from cwd/id display fallbacks and parent links', async () => {
    const b = bench()
-    b.svc.manager.handleMuxEnvelope({
+    b.svc.handleMuxEnvelope({
      rpcId: 'title' as never,
      payload: { type: 'session/title', sessionId: sid('s1'), title: 'Durable title', eventSeq: 2, updatedAt: 3 },
    })
@@ -61,7 +61,7 @@ describe('list store projection', () => {
  it('reflects live increments (host stream via manager) into the store', async () => {
    const b = bench()
    await feedList(b, [{ id: 's1' }])
-    b.svc.manager.handleHostEnvelope({ rpcId: 'r1' as never, payload: { type: 'host/session-added', sessionId: sid('s2') } as never })
+    b.svc.handleHostEnvelope({ rpcId: 'r1' as never, payload: { type: 'host/session-added', sessionId: sid('s2') } as never })
    await Promise.resolve()
    expect(b.svc.list.getSnapshot().ids).toContain('s2')
  })
@@ -77,7 +77,7 @@ describe('scope tree', () => {
    expect(scopeOf(scoped as Context)).toBe('s1')
    expect(scopeOf(b.ctx)).toBeUndefined()
    const binding = b.svc.binding(sid('s1'))
-    expect(binding?.session).toBe(b.svc.manager.get(sid('s1')))
+    expect(binding?.session).toBe(b.svc.cell('s1')?.session)
    expect(b.svc.binding(sid('s1'))).toBe(binding)
    expect(binding?.ctx).toBe(scoped)
  })
@@ -187,9 +187,8 @@ describe('cell (render-layer session kit)', () => {
    const cell = b.svc.cell('s1')
    expect(cell).toBeDefined()
    expect(cell?.sessionId).toBe('s1')
-    // Bare-source form (store migration): the cell carries the Session
-    // observable itself; hook binding happens in the React machinery.
-    expect(cell?.session).toBe(b.svc.manager.get(sid('s1')))
+    // The cell carries the observable; hook binding happens in React.
+    expect(cell?.session).toBe(b.svc.binding(sid('s1'))?.session)
    expect(b.svc.cell('s1')).toBe(cell)
    expect(b.svc.cell('ghost')).toBeUndefined()
  })
@@ -285,36 +284,45 @@ describe('ancestry', () => {
 })

 describe('create', () => {
-  it('returns the new id on ok and throws a coded error on failure', async () => {
+  it('passes a preallocated id and preserves it on ordinary failure', async () => {
    const b = bench()
    b.api.onCreate = () => Promise.resolve(ok({ sessionId: sid('fresh') }))
-    await expect(b.svc.create({ cwd: '/w' })).resolves.toBe('fresh')
+    await expect(b.svc.create({ cwd: '/w', sessionId: sid('fresh') })).resolves.toBe('fresh')
+    expect(b.api.callsOf('session.create')).toEqual([{ cwd: '/w', sessionId: 'fresh' }])
    b.api.onCreate = () => Promise.resolve({
      rpcId: 'e' as never,
      result: { ok: false as const, error: { code: 'internal' as const, message: '爆了', details: {} } },
    } as never)
-    await expect(b.svc.create()).rejects.toThrow(/internal: 爆了/)
-  })
-})
-
-describe('createWorkspace', () => {
-  it('joins host.describe cwd with the name and creates there', async () => {
-    const b = bench()
-    b.api.onDescribe = () => Promise.resolve(ok({ version: '0', cwd: '/host/root', attachedSessions: 0 }))
-    b.api.onCreate = () => Promise.resolve(ok({ sessionId: sid('ws') }))
-    await expect(b.svc.createWorkspace('My Proj')).resolves.toBe('ws')
-    expect(b.api.callsOf('session.create')).toEqual([{ cwd: '/host/root/My Proj' }])
+    const failure = await b.svc.create({ sessionId: sid('candidate') }).catch((error: unknown) => error)
+    expect(failure).toBeInstanceOf(SessionCreateError)
+    expect(failure).toMatchObject({
+      requestedSessionId: 'candidate', publishedSessionId: undefined,
+      rpcError: { code: 'internal', message: '爆了' },
+    })
  })

-  it('rejects empty names and path separators; surfaces describe failures', async () => {
+  it('surfaces the definitely published id after Workspace attachment fails', async () => {
    const b = bench()
-    await expect(b.svc.createWorkspace('  ')).rejects.toThrow(/name is required/)
-    await expect(b.svc.createWorkspace('a/b')).rejects.toThrow(/path separators/)
-    b.api.onDescribe = () => Promise.resolve({
-      rpcId: 'e' as never,
-      result: { ok: false as const, error: { code: 'internal' as const, message: 'down', details: {} } },
+    b.api.onCreate = () => Promise.resolve({
+      rpcId: 'attach' as never,
+      result: {
+        ok: false,
+        error: {
+          code: 'workspace-attach-failed', message: 'ledger unavailable',
+          details: { sessionId: sid('published'), workspaceId: 'ws' },
+        },
+      },
    } as never)
-    await expect(b.svc.createWorkspace('ok')).rejects.toThrow(/host.describe failed/)
+    const failure = await b.svc.create({
+      workspaceId: 'ws' as never,
+      sessionId: sid('published'),
+    }).catch((error: unknown) => error)
+    await Promise.resolve()
+    expect(failure).toMatchObject({
+      publishedSessionId: 'published', requestedSessionId: 'published',
+      rpcError: { code: 'workspace-attach-failed' },
+    })
+    expect(b.svc.list.getSnapshot().byId[sid('published')]).toMatchObject({ id: 'published' })
  })
 })

--- a/packages/client/runtime/tests/slots-service.spec.ts
+++ b/packages/client/runtime/tests/slots-service.spec.ts
@@ -85,11 +85,18 @@ function captureHost(bench: Bench, children?: object): SlotRendererHost {
  })
  bench.erased.register({ name: 'root', ...(children !== undefined ? { children } : {}) }, C)
  bench.ctx.reflect.provide('sessions', fakeSessions())
+  bench.ctx.reflect.provide('workspaces', fakeWorkspaces())
  bench.erased.renderSlot('root', {})
  if (host === undefined) throw new Error('renderer never received the host')
  return host
 }

+/** Minimal independent Workspace list source for the renderer host seam. */
+function fakeWorkspaces() {
+  const state = { items: [], phase: 'ready' as const }
+  return { list: { getSnapshot: () => state, subscribe: () => () => undefined } }
+}
+
 /** Minimal sessions face for the host seam (list observable + cell). */
 function fakeSessions() {
  const state = { ids: [], byId: {}, current: undefined as string | undefined }
@@ -190,9 +197,18 @@ describe('renderer install seam', () => {
    bench.erased.install({ renderRoot })
    bench.erased.register({ name: 'root' }, C)
    bench.ctx.reflect.provide('sessions', fakeSessions())
+    bench.ctx.reflect.provide('workspaces', fakeWorkspaces())
    expect(bench.erased.renderSlot('root', {})).toBe('tree')
    expect(renderRoot).toHaveBeenCalledTimes(1)
  })
+
+  it('fails before rendering when the Workspace object layer is absent', async () => {
+    const bench = await boot()
+    bench.erased.install({ renderRoot: () => null })
+    bench.erased.register({ name: 'root' }, C)
+    bench.ctx.reflect.provide('sessions', fakeSessions())
+    expect(() => bench.erased.renderSlot('root', {})).toThrow(/workspaces service mounted/)
+  })
 })

 describe('host face', () => {
@@ -220,6 +236,12 @@ describe('host face', () => {
    expect(host.sessions.cell('known')).toMatchObject({ sessionId: 'known' })
    expect(host.sessions.cell('ghost')).toBeUndefined()
  })
+
+  it('exposes the independent Workspace list source', async () => {
+    const bench = await boot()
+    const host = captureHost(bench)
+    expect(host.workspaces.list.getSnapshot()).toEqual({ items: [], phase: 'ready' })
+  })
 })

 describe('store instance axis', () => {
@@ -315,6 +337,7 @@ describe('entry-unload cascade', () => {
      renderRoot: (h: SlotRendererHost) => { host = h; return 'rendered' },
    })
    bench.ctx.reflect.provide('sessions', fakeSessions())
+    bench.ctx.reflect.provide('workspaces', fakeWorkspaces())
    // The declarer here is NOT the root occupant: root stays occupied by a
    // separate entry so disposing the declarer only kills its children.
    const disposeRoot = bench.erased.register({ name: 'root' }, C)
--- a/packages/client/runtime/tests/workspaces-service.spec.ts
+++ b/packages/client/runtime/tests/workspaces-service.spec.ts
@@ -0,0 +1,157 @@
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import type { SessionId, WorkspaceId, WorkspaceView } from '@deepseek-ai/dsh-client-connection/client'
+import { SessionsService } from '../src/client/sessions/service.ts'
+import { WorkspaceManager } from '../src/client/workspaces/manager.ts'
+import { WorkspacesService } from '../src/client/workspaces/service.ts'
+import { FakeApiClient, deferred, err, ok } from './fake-api.ts'
+
+const sid = (id: string): SessionId => id as SessionId
+const wid = (id: string): WorkspaceId => id as WorkspaceId
+
+function workspace(id: string, sessionIds: SessionId[] = [], createdAt = '2026-01-01T00:00:00.000Z'): WorkspaceView {
+  return {
+    workspaceId: wid(id), path: `/w/${id}`, title: id, sessionIds,
+    createdAt, updatedAt: createdAt,
+  }
+}
+
+describe('WorkspaceManager', () => {
+  it('owns, materializes, retries, supersedes, and discards Workspace objects with local intents', async () => {
+    const api = new FakeApiClient()
+    const manager = new WorkspaceManager(api)
+    manager.startIntent('first')
+    expect(manager.getSnapshot().intent).toEqual({ name: 'first', phase: 'ready' })
+
+    api.onWorkspaceCreate = () => Promise.resolve(err({
+      code: 'workspace-name-conflict', message: 'taken', details: { name: 'first' },
+    } as never))
+    await expect(manager.materializeIntent()).resolves.toMatchObject({ ok: false })
+    expect(manager.getSnapshot().intent).toMatchObject({ name: 'first', phase: 'ready' })
+    expect(typeof manager.getSnapshot().intent?.error).toBe('string')
+
+    const gate = deferred<Awaited<ReturnType<FakeApiClient['onWorkspaceCreate']>>>()
+    api.onWorkspaceCreate = () => gate.promise
+    const stale = manager.materializeIntent()
+    expect(manager.getSnapshot().intent?.phase).toBe('creating')
+    manager.startIntent('replacement')
+    gate.resolve(ok({ workspace: workspace('first'), created: true }))
+    await stale
+    expect(manager.getSnapshot().intent).toEqual({ name: 'replacement', phase: 'ready' })
+
+    api.onWorkspaceCreate = () => Promise.resolve(ok({ workspace: workspace('replacement'), created: true }))
+    await expect(manager.materializeIntent()).resolves.toMatchObject({ ok: true })
+    expect(manager.getSnapshot().intent).toBeUndefined()
+    await expect(manager.materializeIntent()).resolves.toBeUndefined()
+    manager.discardIntent()
+    manager.startIntent('discarded')
+    manager.discardIntent()
+    expect(manager.getSnapshot().intent).toBeUndefined()
+  })
+
+  it('replays changed frames over hydration and keeps established order on refresh', async () => {
+    const api = new FakeApiClient()
+    const gate = deferred<Awaited<ReturnType<FakeApiClient['onWorkspaceList']>>>()
+    api.onWorkspaceList = () => gate.promise
+    const manager = new WorkspaceManager(api)
+    const hydration = manager.refresh()
+    manager.handleHostEnvelope({
+      rpcId: 'changed' as never,
+      payload: { type: 'host/workspace-changed', workspace: workspace('new') },
+    })
+    gate.resolve(ok({ items: [workspace('old')] as never[] }))
+    await hydration
+    expect(manager.getSnapshot()).toMatchObject({ phase: 'ready', state: 'idle' })
+    expect(manager.getSnapshot().items.map(item => item.workspaceId)).toEqual(['new', 'old'])
+
+    api.onWorkspaceList = () => Promise.resolve(ok({
+      items: [workspace('old'), workspace('new')] as never[],
+    }))
+    await manager.refresh()
+    expect(manager.getSnapshot().items.map(item => item.workspaceId)).toEqual(['new', 'old'])
+  })
+
+  it('single-flights refreshes and exposes result and transport failures independently of readiness', async () => {
+    const api = new FakeApiClient()
+    const gate = deferred<Awaited<ReturnType<FakeApiClient['onWorkspaceList']>>>()
+    api.onWorkspaceList = () => gate.promise
+    const manager = new WorkspaceManager(api)
+    const first = manager.refresh()
+    const second = manager.refresh()
+    expect(manager.getSnapshot().state).toBe('loading')
+    gate.resolve(ok({ items: [] }))
+    await Promise.all([first, second])
+    expect(api.callsOf('workspace.list')).toHaveLength(1)
+
+    api.onWorkspaceList = () => Promise.resolve(err({ code: 'internal', message: 'down', details: {} }))
+    await manager.refresh()
+    expect(manager.getSnapshot()).toMatchObject({ phase: 'ready', state: 'error', error: { message: 'down' } })
+    api.onWorkspaceList = () => Promise.reject(new Error('wire down'))
+    await manager.refresh()
+    expect(manager.getSnapshot()).toMatchObject({ phase: 'ready', state: 'error', error: { message: 'wire down' } })
+  })
+
+  it('creates by name/path, prepends a new row, and folds failures', async () => {
+    const api = new FakeApiClient()
+    const manager = new WorkspaceManager(api)
+    api.onWorkspaceCreate = payload => Promise.resolve(ok({
+      workspace: workspace('created', [], '2026-02-01T00:00:00.000Z'),
+      created: true,
+      payload,
+    } as never))
+    await expect(manager.create({ name: 'created' })).resolves.toMatchObject({ ok: true })
+    expect(api.callsOf('workspace.create')).toEqual([{ name: 'created' }])
+    expect(manager.getSnapshot().items[0]?.workspaceId).toBe('created')
+
+    api.onWorkspaceCreate = () => Promise.reject(new Error('create transport'))
+    await expect(manager.create({ path: '/w/existing' })).resolves.toMatchObject({
+      ok: false, error: { code: 'internal', message: 'create transport' },
+    })
+  })
+})
+
+describe('WorkspacesService', () => {
+  it('feeds SessionManager readiness and recent-Workspace targeting without changing Host order', async () => {
+    const ctx = new Context()
+    const api = new FakeApiClient()
+    const sessions = new SessionsService(ctx, api)
+    const workspaces = new WorkspacesService(ctx, api, sessions)
+    api.onWorkspaceList = () => Promise.resolve(ok({
+      items: [
+        workspace('stable-first', [], '2026-01-03T00:00:00.000Z'),
+        workspace('active', [sid('s-active')], '2026-01-01T00:00:00.000Z'),
+      ] as never[],
+    }))
+    await workspaces.refresh()
+    await Promise.resolve()
+    expect(workspaces.list.getSnapshot()).toMatchObject({ baselinesReady: false, recentWorkspaceId: undefined })
+
+    api.onList = () => Promise.resolve(ok({
+      items: [{ sessionId: sid('s-active'), updatedAt: Date.parse('2026-02-01'), running: false }] as never[],
+    }))
+    await sessions.refresh()
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(workspaces.list.getSnapshot()).toMatchObject({
+      baselinesReady: true,
+      recentWorkspaceId: 'active',
+    })
+    expect(sessions.list.getSnapshot().intent).toMatchObject({
+      target: { kind: 'workspace', workspaceId: 'active' },
+    })
+    expect(workspaces.list.getSnapshot().items.map(item => item.workspaceId)).toEqual(['stable-first', 'active'])
+  })
+
+  it('returns created Workspaces and preserves Host business errors', async () => {
+    const ctx = new Context()
+    const api = new FakeApiClient()
+    const sessions = new SessionsService(ctx, api)
+    const workspaces = new WorkspacesService(ctx, api, sessions)
+    await expect(workspaces.create({ path: '/w/existing' })).resolves.toMatchObject({ workspaceId: 'fk-ws' })
+    expect(api.callsOf('workspace.create')).toEqual([{ path: '/w/existing' }])
+    api.onWorkspaceCreate = () => Promise.resolve(err({
+      code: 'workspace-invalid-path', message: 'missing', details: { path: '/missing' },
+    }))
+    await expect(workspaces.create({ path: '/missing' })).rejects.toThrow(/workspace-invalid-path: missing/)
+  })
+})
--- a/packages/client/tsdown.client.ts
+++ b/packages/client/tsdown.client.ts
@@ -33,7 +33,7 @@ export const INLINE_SAFE = /^@deepseek-ai\/dsh-(host-apiproxy|session|llm|tools|
 * Documented TEMPORARY exemption, not a platform module (hence not in
 * platform.ts): the snapshot-store engine (createSnapshotStore/defineStore/
 * shallowEqual) lives in runtime pending its promotion-time rehoming, and
- * five importers (i18n, ui-layout, ui-conversation ×3) ride this single
+ * five importers (locale, ui-layout, ui-conversation ×3) ride this single
 * exemption. At runtime the lazy CJS table answers the require natively:
 * runtime is an immediately-tier row, its factory is registered before any
 * dependent bundle materializes. TODO(webload/store-rehome): remove with the
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: f5e2603e8ad588740bea3be4f1a195d658721f0c
+README.zh.md: 900d3d1608da3c86078dc56ec819b1f851e63de7
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -1,14 +1,18 @@
 # @deepseek-ai/dsh-client-ui-conversation

+English | [中文](README.zh.md)
+
 Conversation domain: skeleton (header/tabs/composer/empty state), chat view (grouped step-summary flow, streaming tail isolation, stats line, per-tool row slot with a bash sample registrant), minimal details panel, scope-addressed ConversationService. Contract: api-contracts v3 §7 plus the slot terminal design (store seat / props shares).

+The no-session hero renders the frontend Session Intent from the Session list projection, including its frontend Workspace Intent when no real Workspace exists. It declares `conversation.empty.workspace`, where ui-workspace registers the same picker used by the sidebar. WorkspacesService starts the cross-object flow; each Workspace or Session object owns its own materialization. The Session keeps its identity across publication and retains any prompt that still needs connection or delivery; ConversationRoot reads that `pendingPrompt` from `useSession` and edits or retries it through the scoped ConversationService.
+
 The view ring IS a slot: the conversation registration declares the `'conversation.view'` list slot (session scope) in its `children` table, ConversationRoot renders the active entry through its renderSlot share (`only: <active id>`), and view tabs project from the ring ledger's registration options (`id`/`order`/`label`). The chat view is this package's own ring entry; other plugins (ui-trajectory) contribute tabs through plain `ctx.slots.register` — the former package-local view registry (`registerView`/`ViewEntry`/`ConversationViewMap` and the chrome attachment table) is retired, with per-view chrome dissolved into the view components themselves.

 Generic tool rows classify the built-in bash, read, search, write, and edit names into dedicated visual variants. The filesystem variants render the edit icon and `Write · <path>` or `Edit · <path>` summary while retaining the shared row-to-details interaction.

 Tool rows are slots too — the standalone tool ring (`ToolViewRegistry`/`ctx.toolviews`/outlet) is retired. The chat entry declares the keyed `'conversation.chat.toolview'` hole (session scope; the key space is runtime-open); its render site dispatches per row via `entryKey: toolName` with `GenericToolCard` as the call-site `fallback`. The owner payload is the uniform `ToolRowOwnerProps` (`callId`/`toolName`/`block`/`openDetails`) and `ToolRowProps` pre-composes it with the session standard kit. A registrant is a plain plugin: `ctx.slots.register({ name: 'conversation.chat.toolview', key: '<tool>', inject? }, Row)` with `inject: ['slots', 'conversation']` as the load-order seam (apply mounts ConversationService after the chat registration, so the service being present guarantees the slot is declared); session differentiation happens inside the component (`useSessions` reading `parentId` — the bash sample is the third-party-posture exemplar). Trajectory/waterfall toolview slots share this shape and land with their own render sites (RendersCheck rejects a declaration nobody renders).

-Per-session UI state (selection, composer draft, active view) lives in the declared chat store (`stores.ts` `createChatStore`): apply constructs one handle and passes it to the conversation, chat-view, and details registrations, so the session slots share one instance per session (selection written by the chat view, read by details) and the framework owns instance lifecycle and draft persistence. Components are pure — the framework standard kit (`useSession`/`sessionId`/`useSessions`) and the store faces (`useStore`/`actions`) arrive automatically from the registration declaration; the inject factories contribute plain data and callbacks only (send/stop choreography, tab read face, details/paging callbacks, startSession chain).
+Per-session UI state (selection, ordinary composer draft, active view) lives in the declared chat store (`stores.ts` `createChatStore`): apply constructs one handle and passes it to the conversation, chat-view, and details registrations, so the session slots share one instance per session (selection written by the chat view, read by details) and the framework owns instance lifecycle and draft persistence. The frontend Session Intent comes from the Session list projection; after publication, any retained prompt comes from that Session's conversation snapshot. Components are pure — the framework standard kit (`useSession`/`sessionId` when session-scoped, plus global `useSessions`/`useWorkspaces`) and the store faces (`useStore`/`actions`) arrive automatically from the registration declaration; inject factories contribute plain data and callbacks for runtime Session actions, send/stop, tabs, details, and paging.

 `src/client/` is organized for the future package split: `contract/` is the sole inter-domain shared face (`slots.ts` slot declarations + composed slot props including the tool-row contract, `views.ts` shared primitives, `tool-call-model.ts`); the `skeleton/`, `chat/`, and `toolviews/` (sample registrants) domain directories import contract files and never each other; `apply.ts` is the only assembly point allowed to import all three domains. The `/client` export surface is the contract only — `apply`/`inject`, the two service classes, and the `contract/` type families; implementation components (skeleton, chat rows) and the store factory stay internal and reach the page exclusively through apply's slot registrations (tests take them via the `./src/*` subpath).

--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -0,0 +1,33 @@
+# @deepseek-ai/dsh-client-ui-conversation
+
+[English](README.md) | 中文
+
+会话领域：骨架（标题栏／标签页／编辑器／空状态）、聊天视图（分组步骤摘要流、流式尾部隔离、统计行、逐工具行 slot 及一个 bash 示例注册方）、最小详情面板、按 scope 寻址的 ConversationService。契约：api-contracts v3 §7 加 slot 终端设计（store seat／props share）。
+
+无会话主视觉区会渲染来自 Session 列表投影的前端 Session Intent；没有真实 Workspace 时，还会包含其前端 Workspace Intent。它声明 `conversation.empty.workspace`，ui-workspace 会在此注册侧边栏所用的同一选择器。WorkspacesService 启动跨对象流程；每个 Workspace 或 Session 对象拥有自身的物化。Session 在发布期间保持身份，并保留任何仍需连接或交付的提示词；ConversationRoot 读取该 `pendingPrompt`，其来源是 `useSession`，再通过 scope 内的 ConversationService 编辑或重试。
+
+视图环本身就是 slot：会话注册声明 `'conversation.view'` 列表 slot（Session scope），并将其列在 `children` 表中；ConversationRoot 通过 renderSlot share 渲染活跃配置项（`only: <active id>`）；视图标签页从环账本的注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包自身的环配置项；其他插件（ui-trajectory）通过普通的 `ctx.slots.register` 贡献标签页。先前包内的视图注册表（`registerView`／`ViewEntry`／`ConversationViewMap` 及 chrome 附加表）已退役，逐视图 chrome 则被拆入视图组件自身。
+
+通用工具行把内置的 bash、read、search、write 和 edit 名称归入专用视觉变体。文件系统变体会渲染 edit 图标和 `Write · <path>` 或 `Edit · <path>` 摘要，同时保留共享的行到详情交互。
+
+工具行同样是 slot：独立工具环（`ToolViewRegistry`／`ctx.toolviews`／outlet）已经退役。聊天配置项声明键控的 `'conversation.chat.toolview'` 空位（Session scope；key 空间在运行时开放）；其渲染点逐行通过 `entryKey: toolName` 分发，并以 `GenericToolCard` 作为调用点 `fallback`。owner 载荷是统一的 `ToolRowOwnerProps`（`callId`／`toolName`／`block`／`openDetails`），`ToolRowProps` 则预先将其与 Session 标准工具包组合。注册方只是普通插件：`ctx.slots.register({ name: 'conversation.chat.toolview', key: '<tool>', inject? }, Row)`，以 `inject: ['slots', 'conversation']` 作为加载顺序 seam（apply 在聊天注册后挂载 ConversationService，因此服务存在即可保证 slot 已声明）；Session 区分在组件内部完成（`useSessions` 读取 `parentId`，bash 示例是第三方姿态的范例）。Trajectory/waterfall 工具视图 slot 共享此形状，并随各自的渲染点落地（RendersCheck 会拒绝没有任何渲染方的声明）。
+
+逐 Session UI 状态（选择、普通编辑器草稿、活跃视图）位于已声明的聊天 store（`stores.ts` `createChatStore`）中：apply 构造一个 handle，并将其传给会话、聊天视图和详情注册，因此 Session slot 每个 Session 共享一个实例（选择由聊天视图写入、详情读取），框架拥有实例生命周期与草稿持久化。前端 Session Intent 来自 Session 列表投影；发布后，任何保留的提示词都来自该 Session 的会话快照。组件保持纯粹：框架标准工具包（Session scope 下的 `useSession`／`sessionId`，以及全局 `useSessions`／`useWorkspaces`）和 store 表层（`useStore`／`actions`）会从注册声明自动到达；inject factory 为运行时 Session 操作、发送／停止、标签页、详情和分页贡献普通数据与回调。
+
+`src/client/` 按未来的包拆分组织：`contract/` 是唯一的跨领域共享表层（`slots.ts` slot 声明 + 组合后的 slot props，包括工具行契约、`views.ts` 共享原语、`tool-call-model.ts`）；`skeleton/`、`chat/` 和 `toolviews/`（示例注册方）领域目录只导入 contract 文件，彼此绝不导入；`apply.ts` 是唯一允许导入全部三个领域的组装点。`/client` 导出表层只包含契约：`apply`／`inject`、两个服务类和 `contract/` 类型家族；实现组件（骨架、聊天行）与 store factory 保持内部状态，只能通过 apply 的 slot 注册到达页面（测试通过 `./src/*` 子路径获取它们）。
+
+## 模型体验
+
+无。会话 UI 在浏览器中渲染会话历史与流；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **统计行没有耗时区段**：assistant `usage` 只携带 token 计数；耗时需要主机数据源。
+- **详情面板是最小形态**：以原始形式显示已选择调用的参数／结果；Input/Output/Metadata 切换、Prev/Next 步进与 See-in-trajectory 深链接暂缓实现。
+- **assistant footer 扩展（IconActions 行、逐消息分页）是预留 slot**：设计中已有图稿，尚未实现。
+- **others 工具行的闪光图标是手绘近似版本**：无法在本地导出设计字形的矢量几何；等到存在精确导出后再将其提升到 ui-primitives。
+- **审批卡片只是只读占位符**：问题请求通过编辑器链回答（ui-question），Web 侧审批回答属于 P-II 审批项目。
--- a/packages/client/ui-conversation/package.json
+++ b/packages/client/ui-conversation/package.json
@@ -24,7 +24,7 @@
  },
  "dshClient": {
    "inject": [
-      "@deepseek-ai/dsh-client-i18n",
+      "@deepseek-ai/dsh-client-locale",
      "@deepseek-ai/dsh-client-runtime",
      "@deepseek-ai/dsh-client-ui-layout"
    ],
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -1,14 +1,4 @@
-/**
- * Client plugin body: register the conversation/details slot occupants and
- * the no-session empty state, contribute the chat entry into the
- * 'conversation.view' ring that the conversation registration declares, then
- * mount the conversation service (class plugin) and the bash toolview sample.
- * Assembly only — components receive everything through props: the framework
- * standard kit and store faces arrive automatically from the declarations
- * below; the inject factories contribute the plain-data-and-callbacks
- * business face (design §5). Tool rows are ordinary keyed-slot registrations
- * into 'conversation.chat.toolview' — no dedicated registry exists.
- */
+/** Registers the conversation components, shared store, and service callbacks. */
 import type { Context } from 'cordis'
 import type { BoundActions } from '@deepseek-ai/dsh-client-ui-slots'
 import type { SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
@@ -25,8 +15,8 @@ import { ConversationRoot } from './skeleton/ConversationRoot.tsx'
 import { DetailsPanel } from './skeleton/DetailsPanel.tsx'
 import { EmptyState } from './skeleton/EmptyState.tsx'

-/** Required services (cordis fiber inject — the loader passes the whole export surface as an object plugin). */
-export const inject = ['slots', 'layout', 'sessions']
+/** Services required by the conversation plugin. */
+export const inject = ['slots', 'layout', 'sessions', 'workspaces']

 /** Resolve the session-scoped conversation service (scope-addressed send/cancel), failing loud. */
 function scopedConversation(sessions: SessionsService, id: SessionId): ConversationService {
@@ -37,24 +27,18 @@ function scopedConversation(sessions: SessionsService, id: SessionId): Conversat
  return conversation
 }

-/**
- * Client plugin body.
- * @param ctx - client root context.
+/** Mounts the conversation plugin.
+ * @param ctx - Client root context.
 */
 export function apply(ctx: Context): void {
  const sessions = ctx.sessions
+  const workspaces = ctx.workspaces
  const layout = ctx.layout
  const slots = ctx.slots

-  // Shared store handle, constructed here so its identity lives and dies with
-  // this fiber (a module-level handle would be a de-facto singleton). The
-  // conversation, chat-view, and details registrations all declare it; same
-  // scope key = same instance, so chat-view selection writes and details
-  // reads meet in one store.
+  // Apply-time construction keeps store identity bound to this fiber.
  const chatStore = createChatStore()

-  // Tab projection over the view ring's ledger (list entries carry id/order/
-  // label as registration options; the ledger keeps them order-sorted).
  const viewTabs = (): ViewTab[] => {
    const tabs: ViewTab[] = []
    for (const entry of slots.entries('conversation.view')) {
@@ -103,7 +87,9 @@ export function apply(ctx: Context): void {
            // Stop failure surfaces via snapshot.promptError; nothing to restore.
          })
        },
-        open: (target: SessionId) => { sessions.open(target) },
+        open: (sessionId) => { sessions.open(sessionId) },
+        updateSessionPrompt: (text) => { scoped.updatePendingPrompt(text) },
+        retrySessionPrompt: () => { scoped.retryPendingPrompt() },
      }
    },
  }, ConversationRoot)
@@ -120,13 +106,16 @@ export function apply(ctx: Context): void {
    label: 'Chat',
    children: { 'conversation.chat.toolview': { kind: 'keyed', scope: 'session' } },
    store: chatStore,
-    inject: (sessionId: SessionId, actions: BoundActions<typeof chatStore>): ChatViewInjected => ({
-      openDetails: (target) => {
-        actions.select(target)
-        layout.openDetails()
-      },
-      loadOlder: () => { void sessions.manager.get(sessionId).loadOlder() },
-    }),
+    inject: (sessionId: SessionId, actions: BoundActions<typeof chatStore>): ChatViewInjected => {
+      const scoped = scopedConversation(sessions, sessionId)
+      return {
+        openDetails: (target) => {
+          actions.select(target)
+          layout.openDetails()
+        },
+        loadOlder: () => { void scoped.loadOlder() },
+      }
+    },
  }, ChatView)

  // Class-plugin mount (packages/AGENTS.md service form): the service
@@ -150,20 +139,11 @@ export function apply(ctx: Context): void {

  slots.register({
    name: 'conversation.empty',
+    children: { 'conversation.empty.workspace': { kind: 'single', scope: 'root' } },
    inject: (): EmptyStateInjected => ({
-      // ctx.get, not ctx.conversation: the service mounts on this plugin's
-      // own child fiber, so it is not in the inject topology the property
-      // proxy enforces; get reads the global store and stays loud on a torn
-      // boot through the optional-chain throw below.
-      startSession: (opts) => {
-        const conversation = ctx.get('conversation')
-        if (conversation === undefined) throw new Error('ui-conversation: conversation service unavailable')
-        return conversation.startSession(opts)
-      },
-      createWorkspaceSession: async (name) => {
-        const id = await sessions.createWorkspace(name)
-        sessions.open(id)
-      },
+      startSession: (workspaceId, prompt) => { workspaces.startSession(workspaceId, prompt) },
+      updateSessionPrompt: (text) => { sessions.updateIntent(text) },
+      sendSession: () => { workspaces.sendSession() },
    }),
  }, EmptyState)
 }
--- a/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
+++ b/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
@@ -1,9 +1,4 @@
-// StatsLine: the session stats row (figma 122:11212 "cache hit 92% · 1,284
-// tokens · 45.2s · 5 turns · 32 steps"), rendered by ChatView under the flow
-// (part of the chat view body — the chrome attachment mechanism retired with
-// the view ring). Duration has no data source in P-I (ledger). Subscribes to
-// `nodes` only: chunk batches never swap that reference, so the row renders
-// zero times during streaming (the RFC performance model's acceptance row).
+// Settled-node identity prevents stream-delta updates from rerendering this row.

 import { memo, useMemo } from 'react'
 import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
--- a/Show More
+++ b/Show More