Merge remote-tracking branch 'origin/master' into feat/telemetry-otel-plugin

Resolutions: regenerate the conflicted generated docs (cordis services
catalog, event-producer-consumer, module-graph); take master's
packages/README pair and re-insert the telemetry row on both sides;
re-record the README and session-doc translation pairs.

packages/AGENTS.md

@@ -7,7 +7,7 @@ These package-specific rules supplement the repo-wide [conventions](../AGENTS.md
 - **Product-visible plugins require a non-unit REAL-composition test.** Hand-built `ctx.plugin(...)` suites are insufficient. Boot test-only `cordis.yml` through the Loader and app/process; mock only external/nondeterministic boundaries and assert model-visible, durable, or user-visible output. Keep opt-ins out of shipped defaults. [Policy](../docs/testing.md).
 - **Initiator-owned private chains derive, then capture.** Under `ctx.agents.withInitiator()`, recover the Agent at each orchestration entry, derive `agent.session`, and let operation-local helpers close over it. Keep `Agent` and `Session` explicit at lifecycle, session-log, service, authority, worker/process, persistence, and wire interfaces; do not widen a leaf helper from `Session` to `Context` merely to hide a parameter ([rationale](../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)).
 - **Represent one asynchronous operation with one lifecycle controller or transaction.** Separate readiness, cancellation, disposal, reservation, or sentinel state requires an independent owner or settlement boundary; otherwise fold it while preserving rollback, callback containment, and quiescence.
-- **Shape capability interfaces around all current consumers.** Keep tool-schema, Loader, UI, transport, and backend-specific behavior in the consumer or adapter; do not let one consumer dictate the interface ([capability-seam rationale](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)).
+- **Shape capability interfaces around all current consumers.** Keep tool-schema, Loader, UI, transport, and backend-specific behavior in the consumer or adapter; do not let one consumer dictate the interface ([capability-seam rationale](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)). Inverse smell: a public service method with one internal caller — pass a private capability closure instead (`RunCodeBridgeOptions`).
 - **Require a current owner and need.** Tie each abstraction, state machine, option, defensive copy, and compatibility path to a current contract or production consumer, and keep behavior in its owning plugin or service.
 - **Require evidence for public choices.** Configurability does not justify an unsupported default, public operation set, format, or imported external concept. Use current-consumer evidence or relevant prior art; otherwise require an explicit value or defer the choice.
 - **Write model-facing contracts from the model's perspective.** Prompts, tool schemas, results, and diagnostics contain only task-relevant concepts, not UI, transport, or implementation vocabulary. Pin stable model-visible text verbatim and dynamic behavior through snapshots or end-to-end coverage.

packages/README.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write
-README.md: 7343d559149645e2d76bc93f864a9665155e4b26
-README.zh.md: a3fd5c6d9e2e41fda104db97cdf2a281acdaaf72
+#   pnpm run verify-translation-pairing --write packages/README.md
+README.md: d16e395a42e491461c0862227205931894c27e39
+README.zh.md: 3fb4181ce7ae7b0d79a13ca4358b9df39d83ef1f

packages/README.md

@@ -13,14 +13,15 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`core/`](core/README.md) | Product API spine: sessions, prompts, tools, agent services, and the concrete loop | Product — stable surface |
 | [`goal/`](goal/README.md) | Persisted same-session goal state and lifecycle | Product — stable surface |
 | [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable surface |
+| [`subprocess/`](subprocess/README.md) | Subprocess capability family: spawn seam + local process-tree implementation | Product — stable surface |
 | [`bash/`](bash/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable surface |
-| [`pty/`](pty/README.md) | Persistent PTY capability family: owner-scoped sessions, local impl, model-facing tools | Product — stable surface |
-| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: runtime seam for model-written programs + worker-thread backend | Product — stable surface |
+| [`pty/`](pty/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable surface |
+| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: the runtime seam for model-written programs + a worker-thread backend | Product — stable surface |
 | [`sandbox/`](sandbox/README.md) | Process-confinement seam; bwrap/Landlock/Seatbelt backends | Product — stable surface |
 | [`fs/`](fs/README.md) | Filesystem capability family: seam, local impl, model-facing file tools, bash-backed discovery tools | Product — stable surface |
 | [`lsp/`](lsp/README.md) | LSP capability family: seam, generic stdio provider, and the `lsp` tool | Product — stable surface |
 | [`skill/`](skill/README.md) | Skill capability family: the provider registry, local provider, and model-facing catalog/loader | Product — stable surface |
-| [`compact/`](compact/README.md) | Compaction capability family: abstract seam + basic backend (tool deferred) | Product — stable surface |
+| [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface |
 | [`context/`](context/README.md) | Model-visible request context, including workspace instructions and time context | Product — stable surface |
 | [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface |
 | [`tasks/`](tasks/README.md) | Generic background-task runtime and model-facing `task_*` control tools | Product — stable surface |
@@ -34,7 +35,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`cordis/`](cordis/README.md) | Self-referential runtime toolset: inspect the live runtime's plugins and services, mount/unmount model-written plugins ([design](../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)) | Product — stable surface |
 | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface |
 | [`session-persistence/`](session-persistence/README.md) | Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface |
-| [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, bounded reads, lineage, relationships, semantic filtering, SQLite full-text search | Product — stable surface |
+| [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, bounded reads, lineage, event relationships, semantic filtering, and SQLite full-text search | Product — stable surface |
 | [`session-title/`](session-title/README.md) | Log-backed session titles: fallback service, shared LLM policy, and opt-in providers | Product — stable surface |
 | [`telemetry/`](telemetry/README.md) | Session reporting: capture/redact seam, OTel backend | Product — stable surface |
 | [`storage/`](storage/README.md) | Non-session storage hub + backends + domain form | Product — stable surface |
@@ -44,7 +45,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`ui/`](ui/README.md) | Human/client integrations: TUI and JSON-RPC, approval/interaction seams, ask-user tool | Product — stable surface |
 | [`examples/`](examples/README.md) | Demo bundles (agent-spine + TUI/CLI/ACP/JSON-RPC bins) leaves load | Support — example infra |
 | [`support/`](support/README.md) | Support infrastructure (testkits, invariants, replay, Loader smokes) | Support — lower compatibility expectations |
-| [`util/`](util/README.md) | Zero-dependency utilities shared across groups (`Branded<B>`, home/path helpers, timeout, retention) | Support — small, stable, harness-dep-free |
+| [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (`Branded<B>`, Harness home/path helpers, timeout, retention) | Support — small, stable, harness-dep-free |
 
 Groups distinguish product API from support infrastructure. New packages join an existing group; a new group updates its README and this table.
 
@@ -52,6 +53,6 @@ Groups distinguish product API from support infrastructure. New packages join an
 
 The dependency graph is generated: [docs/module-graph.md](../docs/module-graph.md) (`pnpm run gen-module-graph`, freshness-gated in CI).
 
-**Extension plugins depend on interfaces, never the concrete loop.** `dsh-agent-loop` is swappable; UI, hook, and tool plugins use `dsh-agent`. Composition bundles, including `dsh-agent-spine-demo`, may depend on spine plugins. Capabilities split into interface/implementation/consumer packages; see [capability seams](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md).
+**Extension plugins depend on interfaces, never the concrete loop.** `dsh-agent-loop` is swappable; UI, hook, and tool plugins use `dsh-agent`. Composition bundles, including `dsh-agent-spine-demo`, may depend on spine plugins. Capabilities split into interface / implementation / consumer packages; see [capability seams](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md).
 
 Package READMEs cover purpose, APIs, extension points, and [Model Experience](../docs/cookbook/adding-a-package.md#4-write-the-package-readme) unless on the model-agnostic [omission allowlist](../scripts/verify-package-readme-model-experience.ts). They also carry `## Known Limitations and Deferred Work` or use its [allowlist](../scripts/verify-package-readme-limitations.ts).

packages/README.zh.md

@@ -13,8 +13,9 @@
 | [`core/`](core/README.md) | 产品 API 主干：会话、提示词、工具、agent（智能体）服务与具体循环 | 产品：稳定表面 |
 | [`goal/`](goal/README.md) | 持久化的同会话 goal 状态与生命周期 | 产品：稳定表面 |
 | [`llm/`](llm/README.md) | LLM（大语言模型）能力系列：抽象服务 + 提供方适配器 | 产品：稳定表面 |
+| [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定表面 |
 | [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定表面 |
-| [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现、面向模型的工具 | 产品：稳定表面 |
+| [`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 后端发现工具 | 产品：稳定表面 |
@@ -34,7 +35,7 @@
 | [`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-query/`](session-query/README.md) | 会话检索系列：逻辑语料库、有界读取、血缘、事件关系、语义过滤和 SQLite 全文搜索 | 产品：稳定表面 |
 | [`session-title/`](session-title/README.md) | 日志支撑的会话标题：回退服务、共享 LLM 策略和选用提供方 | 产品：稳定表面 |
 | [`telemetry/`](telemetry/README.md) | 会话上报：捕获／脱敏 seam、OTel 后端 | 产品：稳定表面 |
 | [`storage/`](storage/README.md) | 非会话存储中枢 + 后端 + 领域形式 | 产品：稳定表面 |
@@ -44,7 +45,7 @@
 | [`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>`、home／路径辅助函数、超时、保留策略） | 支持：小型、稳定、无 harness 依赖 |
+| [`util/`](util/README.md) | 组间共享的低层零依赖工具（`Branded<B>`、Harness home／路径辅助函数、超时、保留策略） | 支持：小型、稳定、无 harness 依赖 |
 
 组用于区分产品 API 与支持基础设施。新包加入现有组；新组则更新其 README 和此表。
 

packages/bash/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-README.md: 08b36270800cdd79c82d6781bbfb2e12e2dc2060
-README.zh.md: a98506a6cdf41e5b298b40e1b8e1faf0c4c917d2
+README.md: e60ad9b0e4c48cf35a2601e7dec4d2d50807707b
+README.zh.md: 57c28b45cf713aeaac725edb70d1fc24912c35db

packages/bash/README.md

@@ -6,8 +6,8 @@ The canonical three-package capability seam (see [capability seams](../../.agent
 
 | Package | Role | ctx key |
 |---|---|---|
-| `bash/` | Abstract bash executor seam (interface + vocabulary; sandbox result facts carry the [`sandbox/`](../sandbox/README.md) seam's mode/enforcement vocabulary) | `ctx.bash` |
-| `bash-local/` | Local-subprocess `BashExecutor` implementation | (registers `ctx.bash`) |
+| `bash/` | Abstract bash executor seam (interface + vocabulary; sandbox result facts carry the [`sandbox/`](../sandbox/README.md) seam's mode/enforcement vocabulary, and the managed-env/output vocabulary is re-exported from the [`subprocess/`](../subprocess/README.md) seam) | `ctx.bash` |
+| `bash-local/` | Local `BashExecutor` implementation over the [`subprocess/`](../subprocess/README.md) service (command defaulting, deadlines, terminal env, background-read merge) | (registers `ctx.bash`) |
 | `bash-sandbox/` | Sandbox-consuming `BashExecutor` (wraps every command argv via `ctx.sandbox`, stamps denial/enforcement facts; extends `bash-local`'s mechanics) | (registers `ctx.bash`) |
 | `tool-bash/` | Model-facing `bash` schema; background processes register with the generic [`tasks/`](../tasks/README.md) runtime | (registers on `ctx.tools`) |
 

packages/bash/README.zh.md

@@ -6,8 +6,8 @@
 
 | 包 | 职责 | ctx key |
 |---|---|---|
-| `bash/` | 抽象 bash 执行器 seam（接口 + 词汇；沙箱结果事实携带 [`sandbox/`](../sandbox/README.md) seam 的模式／强制执行词汇） | `ctx.bash` |
-| `bash-local/` | 本地子进程 `BashExecutor` 实现 | （注册 `ctx.bash`） |
+| `bash/` | 抽象 bash 执行器 seam（接口 + 词汇；沙箱结果事实携带 [`sandbox/`](../sandbox/README.md) seam 的模式／强制执行词汇，受管环境／输出词汇则从 [`subprocess/`](../subprocess/README.md) seam 重导出） | `ctx.bash` |
+| `bash-local/` | 构建在 [`subprocess/`](../subprocess/README.md) 服务之上的本地 `BashExecutor` 实现（命令默认值补全、deadline、终端环境、后台读取合并） | （注册 `ctx.bash`） |
 | `bash-sandbox/` | 消费沙箱的 `BashExecutor`（通过 `ctx.sandbox` 包装每个命令 argv，标记拒绝／强制执行事实；扩展 `bash-local` 的机制） | （注册 `ctx.bash`） |
 | `tool-bash/` | 面向模型的 `bash` schema；后台进程注册到通用 [`tasks/`](../tasks/README.md) 运行时 | （注册到 `ctx.tools`） |
 

packages/bash/bash-local/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-README.md: 1668f33e8acf6d749d4d3753478c12d48a19ac3c
-README.zh.md: 0e0a4ad41b532e39f6f2470aa981a08b6d6230c1
+README.md: 694b7a7686ea6c38da5a354ff6b6e6d2c4520706
+README.zh.md: aa6de87df48ee943ccdd2c6227ad977f596b5516

packages/bash/bash-local/README.md

@@ -2,9 +2,9 @@
 
 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.
+Local implementation of the `@deepseek-ai/dsh-bash` executor seam over the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) service: `LocalBashExecutor` spawns `bash -c <command>` per call as a managed process group through `ctx.subprocess`, and owns everything bash-shaped — command defaulting and caps, timeout/cancel classification, the model-friendly terminal environment, and the model-facing stdout/stderr merge for background reads. Group mechanics (bounded spill-backed output, credential scrub, kill escalation, disposal) are the subprocess service's.
 
-The package root exports the default and named `LocalBashExecutor` plugin plus its `Config`; subprocess plumbing stays internal to the implementation package.
+The package root exports the default and named `LocalBashExecutor` plugin plus its `Config`.
 
 ## Config
 
@@ -24,11 +24,11 @@ The package root exports the default and named `LocalBashExecutor` plugin plus i
 
 Design surveyed against the bash tools of Claude Code, OpenCode, Codex, and pi; the notable choices:
 
-- **Spawn per call, no shell state** — every call is a fresh non-login `bash -c` (deterministic; no rc files). All four surveyed tools spawn per call. `XXX(stateful-shell)` in `src/run.ts` records the two proven stateful designs (Claude Code's cwd-only persistence; Codex's PTY exec sessions) for when real workflows demand them.
-- **Process-group kills with escalation** — children are spawned `detached` (own process group); kills send SIGTERM to the group, then SIGKILL after the `graceMs` grace (default 3s — OpenCode's escalation; pipelines and subshells die with the parent). After the main shell exits, inherited stdout/stderr pipes receive the same bounded drain grace so a surviving descendant cannot hold the command open indefinitely. ESRCH is tolerated; daemons that re-parent away from the group can still survive — same caveat as the surveyed tools.
-- **Tail-keep truncation + bounded spill files** — output beyond `maxOutputBytes` keeps the in-memory TAIL (errors/results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a temp file whose path is reported when available. A foreground `BashExecRequest.stdoutMaxBytes` can raise stdout's capture budget for one trusted caller; stderr and background tasks still use `maxOutputBytes`. A stream larger than `maxSpillBytes` discards its now-incomplete spill and returns only the marked truncated tail. If the final spill close reports a delayed writeback failure, the executor likewise withholds the path rather than advertising an incomplete file.
-- **Model-friendly env + credential scrub** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names, then `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` (Codex's hardcoded set) so pagers and ANSI color don't garble results. A spec's ordinary `env` is merged after the scrub but rejects `DSH_*`; managed `dshEnv` rejects ordinary names and merges last, preventing stale nested-harness identity. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
-- **Background processes** — `start()` returns a live `BashProcess` handle immediately, no timeout applies (Claude Code detaches timeouts when backgrounding), the handle's `readOutput()` is incremental with whole-stream byte offsets, and disposal kills every running process and awaits its exit. Everything task-shaped (ids, ownership, polling, notices) lives in the generic [`ctx.tasks` runtime](../../tasks/tasks/README.md), which the tool layer registers the handle with — this executor never sees a session or a registry.
+- **Spawn per call, no shell state** — every call is a fresh non-login `bash -c` (deterministic; no rc files). All four surveyed tools spawn per call. `XXX(stateful-shell)` in `src/index.ts` records the two proven stateful designs (Claude Code's cwd-only persistence; Codex's PTY exec sessions) for when real workflows demand them.
+- **Configured budgets over managed groups** — `resolve()` fills `workdir`/`timeoutMs`/`stdoutMaxBytes` from config, and every spawn hands the service explicit byte caps, spill cap, and `graceMs` (default 3s — OpenCode's escalation). Process-group kills, the post-exit pipe-drain grace, tail-keep truncation, and bounded spill files are [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) mechanics. A foreground `BashExecRequest.stdoutMaxBytes` can raise stdout's capture budget for one trusted caller; stderr and background runs still use `maxOutputBytes`.
+- **Timeout and cancel classification** — `run()` fuses its config-clamped timeout with the caller's signal through one deadline; only the executor's own timeout reports `timedOut`, an upstream cancel reports `aborted`, and a self-signaled command reports neither ([timeout-library Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)).
+- **Model-friendly terminal env** — `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` (Codex's hardcoded set) so pagers and ANSI color don't garble results, merged as ordinary env under the service's credential scrub and `DSH_*` channel rules; an explicit caller entry still wins. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
+- **Background processes** — `start()` returns a live `BashProcess` handle immediately, no timeout applies (Claude Code detaches timeouts when backgrounding), and the handle's `readOutput()` merges the service's offset-based stdout/stderr reads into one marked-section delta with a consuming cursor. A still-running process belongs to the subprocess service, so it survives executor reloads and dies (killed and joined) with the service's disposal. Everything task-shaped (ids, ownership, polling, notices) lives in the generic [`ctx.tasks` runtime](../../tasks/tasks/README.md), which the tool layer registers the handle with — this executor never sees a session or a registry.
 
 ## Model Experience
 
@@ -42,8 +42,7 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 - **Unconfined by itself** — this executor always runs commands with the harness process's authority; deployments needing confinement compose [`dsh-bash-sandbox`](../bash-sandbox/README.md), while per-call allow/deny/ask policy belongs on `tools/pre-execute`.
 - **No persistent shell or PTY** — every call starts a fresh non-login `bash -c`; cwd-only persistence and interactive terminal sessions remain deferred until a real workflow requires them.
-- **POSIX-only** — the `bash` binary, detached process groups, group kills, and SIGTERM→SIGKILL escalation are hardcoded; Windows is unsupported.
-- **The credential scrub is a name heuristic** — `*KEY*`/`*SECRET*`/`*TOKEN*` only; differently-named secrets (e.g. `*PASSWORD*`) pass through, and a whitelist for over-scrubbed vars is noted future work.
-- **Completed spill files are not deleted** — bounded full-output recovery files (and the private per-process spill dir) accumulate under the OS tmpdir until something external cleans them; oversize incomplete spills are discarded and deletion is attempted immediately, but a cleanup failure can leave a bounded file behind.
+- **POSIX-only** — the `bash` binary is hardcoded, and the underlying service's group semantics are POSIX; Windows is unsupported.
+- **A background spawn-failure note is single-delivery** — the subprocess service buffers no output for a process that never ran, so the executor injects `spawn failed: …` into exactly one `readOutput()` delta; a reader that discards that delta cannot recover it.
 
-The raw process handling lives in `src/run.ts`; `src/index.ts` is the service wiring.
+Scrub-heuristic and spill-retention caveats live with [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md), which owns those mechanics.

packages/bash/bash-local/README.zh.md

@@ -2,9 +2,9 @@
 
 [English](README.md) | 中文
 
-`@deepseek-ai/dsh-bash` 执行器 seam 的本地子进程实现：`LocalBashExecutor` 每次调用都会在独立进程组中 spawn `bash -c <command>`，收集有界输出，并用限制大小的完整流 spill 文件保留超量内容，随后针对整个进程组从 SIGTERM 逐步升级为 SIGKILL。
+`@deepseek-ai/dsh-bash` 执行器 seam 的本地实现，构建在 [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) 服务之上：`LocalBashExecutor` 每次调用都通过 `ctx.subprocess` 把 `bash -c <command>` 作为受管进程组 spawn，并拥有所有 bash 形态的职责（命令默认值补全与上限、超时与取消分类、适合模型的终端环境，以及后台读取时面向模型的 stdout/stderr 合并）。进程组机制（以 spill 文件兜底的有界输出、凭据清除、kill 升级、dispose（资源释放））归进程管理器服务所有。
 
-包根目录导出默认与具名的 `LocalBashExecutor` 插件及其 `Config`；子进程管道细节保留在该实现包内部。
+包根目录导出默认与具名的 `LocalBashExecutor` 插件及其 `Config`。
 
 ## 配置
 
@@ -24,11 +24,11 @@
 
 设计时调研了 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)，工具层会在其中注册该句柄；本执行器不会接触会话或注册表。
+- **每次调用都 spawn，不保留 shell 状态**：每次调用都启动新的非登录 `bash -c`（行为确定，不读取 rc 文件）。调研的四种工具均会每次调用单独 spawn。`XXX(stateful-shell)` 位于 `src/index.ts`，记录了两种已验证的有状态设计（Claude Code 仅持久化 cwd；Codex 使用 PTY exec 会话），供真实工作流程需要时采用。
+- **在受管进程组之上应用配置预算**：`resolve()` 从配置补全 `workdir`／`timeoutMs`／`stdoutMaxBytes`，每次 spawn 都向服务传入显式的字节上限、spill 上限与 `graceMs`（默认 3 秒，沿用 OpenCode 的升级策略）。进程组终止、退出后的管道排空宽限期、尾部保留截断与有界 spill 文件是 [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) 的机制。前台 `BashExecRequest.stdoutMaxBytes` 可为某个受信任调用方提高单次 stdout 捕获预算；stderr 和后台运行仍使用 `maxOutputBytes`。
+- **超时与取消分类**：`run()` 通过同一个 deadline 把经配置钳位的超时与调用方的信号融合；只有执行器自身的超时报告 `timedOut`，上游取消报告 `aborted`，自行发出信号终止的命令两者皆不报告（见[超时库 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)）。
+- **适合模型的终端环境**：设置 `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat`（Codex 硬编码的集合），防止分页器与 ANSI 颜色破坏结果；这些条目作为普通 env 合并，遵循服务的凭据清除与 `DSH_*` 通道规则；调用方的显式条目依旧优先。详见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) 与 [受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
+- **后台进程**：`start()` 会立即返回实时 `BashProcess` 句柄，不应用超时（Claude Code 在转为后台时会解除超时）；句柄的 `readOutput()` 把服务基于偏移量的 stdout/stderr 读取合并为一条带标记分节的增量，由一个消费游标驱动。仍在运行的进程归进程管理器服务所有，因此它能在执行器重载后存活，并随服务的 dispose 被终止且等待退出。所有具有任务形态的事项（id、所有权、轮询、通知）都属于通用 [`ctx.tasks` 运行时](../../tasks/tasks/README.md)，工具层会在其中注册该句柄；本执行器不会接触会话或注册表。
 
 ## 模型体验
 
@@ -42,8 +42,7 @@
 
 - **自身不受约束**：此执行器始终以 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 会被丢弃并立即尝试删除，但清理失败可能留下一个有界文件。
+- **仅支持 POSIX**：`bash` 二进制已硬编码，底层服务的进程组语义也是 POSIX 的；不支持 Windows。
+- **后台 spawn 失败提示只交付一次**：进程管理器不会为从未真正运行的进程缓冲任何输出，因此执行器把 `spawn failed: …` 注入恰好一个 `readOutput()` 增量；丢弃了该增量的读取方无法再恢复它。
 
-原始进程处理位于 `src/run.ts`；`src/index.ts` 负责服务接线。
+凭据清除启发式规则与 spill 保留的注意事项随 [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) 记录；这些机制归它所有。

packages/bash/bash-local/package.json

@@ -29,6 +29,7 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-bash": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1",
     "@deepseek-ai/dsh-timeout": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
@@ -38,6 +39,8 @@
   "devDependencies": {
     "@deepseek-ai/dsh-bash": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-subprocess": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
     "@deepseek-ai/dsh-timeout": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }

packages/bash/bash-local/src/index.ts

@@ -1,17 +1,39 @@
 /**
- * Local-subprocess implementation of the bash executor seam. Each command runs
- * as `bash -c` in its own process group; disposal kills and joins live groups.
- * Execution policy belongs in `tools/pre-execute` or a sandboxing executor.
+ * Local implementation of the bash executor seam over the subprocess
+ * seam. Each command runs as `bash -c` in a managed process group spawned
+ * through `ctx.subprocess`; this executor owns command defaulting, deadlines
+ * and cause classification, the model-friendly terminal environment, and the
+ * model-facing stdout/stderr merge for background reads. Execution policy
+ * belongs in `tools/pre-execute` or a sandboxing executor.
  * @module @deepseek-ai/dsh-bash-local
  */
 
 import { Context } from 'cordis'
 import z from 'schemastery'
 import { BashExecutor } from '@deepseek-ai/dsh-bash'
-import type { BashExecRequest, BashExecSpec, BashProcess, BashProcessRead, BashRunResult } from '@deepseek-ai/dsh-bash'
+import type { BashExecRequest, BashExecSpec, BashProcess, BashProcessRead, BashRunResult, CollectedOutput } from '@deepseek-ai/dsh-bash'
+import type { SubprocessCollect, SubprocessHandle, SubprocessOutputReader, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
 import { clampTimeout, deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
-import { DEFAULT_GRACE_MS, DEFAULT_MAX_SPILL_BYTES, runBash } from './run.ts'
-import type { RunInternals, RunningBash } from './run.ts'
+
+/**
+ * Model-friendly environment overrides: disable colors, pagers, and
+ * interactive terminal features that would garble tool output (the same set
+ * Codex hardcodes; Claude Code achieves it via TERM=dumb). Bash-tool policy —
+ * merged first into the spawn's explicit env, so a trusted caller's own entry
+ * still wins; the subprocess service applies its credential scrub independently.
+ */
+export const ENV_OVERRIDES = {
+  NO_COLOR: '1',
+  TERM: 'dumb',
+  PAGER: 'cat',
+  GIT_PAGER: 'cat',
+} as const
+
+/** Default SIGTERM→SIGKILL grace period (the `graceMs` config; matches OpenCode's 3s). */
+const DEFAULT_GRACE_MS = 3_000
+
+/** Default per-stream spill cap (the `maxSpillBytes` config). */
+const DEFAULT_MAX_SPILL_BYTES = 64 * 1024 * 1024
 
 /** Plugin config (all optional — `static Config` supplies the defaults). */
 export interface Config {
@@ -32,6 +54,16 @@ export interface Config {
 /** The shape after schemastery applied the defaults (cwd has none). */
 type ResolvedConfig = Required<Omit<Config, 'cwd'>> & Pick<Config, 'cwd'>
 
+/** Project a settled collect-mode reader into the final CollectedOutput shape. */
+function finalOutput(reader: SubprocessOutputReader): CollectedOutput {
+  const read = reader.readFrom(0)
+  return {
+    text: read.text,
+    truncated: read.lossy,
+    ...read.spillPath !== undefined ? { spillPath: read.spillPath } : {},
+  }
+}
+
 function assertPositiveFinite(name: string, value: number): void {
   if (!Number.isFinite(value) || value <= 0) {
     throw new Error(`bash-local: ${name} must be a positive finite number`)
@@ -39,10 +71,15 @@ function assertPositiveFinite(name: string, value: number): void {
 }
 
 /**
- * Local bash executor with bounded output, spill files, and process-group
- * `SIGTERM` to `SIGKILL` escalation.
+ * Local bash executor over `ctx.subprocess`. Bounded output, spill files, and
+ * process-group SIGTERM→SIGKILL escalation are the subprocess service's
+ * mechanics; this executor supplies their configured budgets per spawn, so a
+ * still-running background process stays managed (killed and joined at
+ * composition teardown) even across an executor reload.
  */
 export class LocalBashExecutor extends BashExecutor {
+  static inject = ['subprocess']
+
   static Config: z<Config> = z.object({
     cwd: z.string(),
     timeoutMs: z.number().default(120_000),
@@ -52,11 +89,6 @@ export class LocalBashExecutor extends BashExecutor {
     graceMs: z.number().default(DEFAULT_GRACE_MS),
   })
 
-  /** Live processes retained only so disposal can kill and join them. */
-  private live = new Map<BashProcess, RunningBash>()
-  /** Test seam: spill knobs forwarded to runBash. */
-  internals: RunInternals = {}
-
   /** Validated config (schemastery applied the defaults before construction). */
   readonly config: ResolvedConfig
 
@@ -69,17 +101,6 @@ export class LocalBashExecutor extends BashExecutor {
     assertPositiveFinite('maxOutputBytes', this.config.maxOutputBytes)
     assertPositiveFinite('maxSpillBytes', this.config.maxSpillBytes)
     assertPositiveFinite('graceMs', this.config.graceMs)
-    ctx.effect(() => async () => {
-      // Await closure so even a TERM-trapping child cannot outlive the fiber.
-      const pending: Promise<void>[] = []
-      for (const [proc, running] of this.live) {
-        proc.status = 'killed'
-        running.kill()
-        pending.push(proc.done)
-      }
-      this.live.clear()
-      await Promise.all(pending)
-    }, 'local bash teardown')
   }
 
   /**
@@ -105,7 +126,7 @@ export class LocalBashExecutor extends BashExecutor {
       stdoutMaxBytes,
       ...request.signal ? { signal: request.signal } : {},
       // Carry stdin/ordinary env/trusted dshEnv through verbatim — optional,
-      // no config default. run.ts owns the scrub and merge order.
+      // no config default. The subprocess service owns the scrub and merge order.
       ...request.stdin !== undefined ? { stdin: request.stdin } : {},
       ...request.env !== undefined ? { env: request.env } : {},
       ...request.dshEnv !== undefined ? { dshEnv: request.dshEnv } : {},
@@ -116,41 +137,71 @@ export class LocalBashExecutor extends BashExecutor {
     }
   }
 
+  /** Map one resolved bash spec onto a fully-specified subprocess spawn. */
+  // XXX(stateful-shell): evaluate persistent cwd or PTY sessions when workflows require shell state.
+  private spawnSpec(spec: BashExecSpec, stdoutMaxBytes: number, signal: AbortSignal | undefined): SubprocessSpawnSpec {
+    const collect = (maxBytes: number): SubprocessCollect =>
+      ({ maxBytes, spill: { maxBytes: this.config.maxSpillBytes } })
+    return {
+      argv: ['bash', '-c', spec.command],
+      cwd: spec.workdir,
+      stdio: {
+        stdin: spec.stdin !== undefined ? { data: spec.stdin } : 'ignore',
+        stdout: collect(stdoutMaxBytes),
+        stderr: collect(this.config.maxOutputBytes),
+      },
+      graceMs: this.config.graceMs,
+      signal,
+      // One explicit env map for the seam, layered so the trusted dshEnv
+      // snapshot beats both the caller's env and the terminal overrides; the
+      // subprocess service merges the whole map after its ambient scrub.
+      env: { ...ENV_OVERRIDES, ...spec.env, ...spec.dshEnv },
+    }
+  }
+
+  /** The collect-mode readers the executor itself requested (present by construction). */
+  private static collected(handle: SubprocessHandle): { stdout: SubprocessOutputReader; stderr: SubprocessOutputReader } {
+    const { stdout, stderr } = handle.collected
+    /* v8 ignore start -- collect dispositions expose both readers by the seam contract; defensive. */
+    if (stdout === undefined || stderr === undefined) {
+      throw new Error('bash-local: subprocess implementation dropped a requested collect stream')
+    }
+    /* v8 ignore stop */
+    return { stdout, stderr }
+  }
+
   async run(spec: BashExecSpec): Promise<BashRunResult> {
     // One deadline combines timeout and upstream cancellation; disposal clears its timer.
     using d = deadline(spec.signal, spec.timeoutMs, 'BASH_TIMEOUT')
-    const outcome = await runBash({
-      command: spec.command,
-      cwd: spec.workdir,
-      stdoutMaxBytes: spec.stdoutMaxBytes,
-      stderrMaxBytes: this.config.maxOutputBytes,
-      maxSpillBytes: this.config.maxSpillBytes,
-      graceMs: this.config.graceMs,
-      signal: d.signal,
-      stdin: spec.stdin,
-      env: spec.env,
-      dshEnv: spec.dshEnv,
-    }, this.internals).done
+    const handle = this.ctx.subprocess.spawn(this.spawnSpec(spec, spec.stdoutMaxBytes, d.signal))
+    const outcome = await handle.done
+    const collected = LocalBashExecutor.collected(handle)
     // Only this executor's timeout reason counts as timedOut; outer deadlines count as aborts.
     const timedOut = timeoutOf(d.signal, 'BASH_TIMEOUT') !== undefined
     const aborted = d.signal.aborted && !timedOut
-    return { ...outcome, timedOut, aborted, timeoutMs: spec.timeoutMs }
+    return {
+      ...outcome,
+      timedOut,
+      aborted,
+      timeoutMs: spec.timeoutMs,
+      stdout: finalOutput(collected.stdout),
+      stderr: finalOutput(collected.stderr),
+    }
   }
 
   start(spec: BashExecSpec): BashProcess {
     // Background runs ignore timeoutMs; callers stop them through kill() or spec.signal.
-    const running = runBash({
-      command: spec.command,
-      cwd: spec.workdir,
-      stdoutMaxBytes: this.config.maxOutputBytes,
-      stderrMaxBytes: this.config.maxOutputBytes,
-      maxSpillBytes: this.config.maxSpillBytes,
-      graceMs: this.config.graceMs,
-      signal: spec.signal,
-      stdin: spec.stdin,
-      env: spec.env,
-      dshEnv: spec.dshEnv,
-    }, this.internals)
+    const running = this.ctx.subprocess.spawn(this.spawnSpec(spec, this.config.maxOutputBytes, spec.signal))
+    const collected = LocalBashExecutor.collected(running)
+
+    // A spawn failure produces no process output, so the subprocess service has nothing
+    // to buffer; the note is delivered exactly once through the read path.
+    let spawnFailureNote: string | undefined
+    const consumeSpawnFailure = (): string => {
+      const note = spawnFailureNote ?? ''
+      spawnFailureNote = undefined
+      return note
+    }
 
     let stdoutOffset = 0
     let stderrOffset = 0
@@ -165,26 +216,27 @@ export class LocalBashExecutor extends BashExecutor {
         }
         proc.exitCode = outcome.exitCode
         proc.signal = outcome.signal
-        this.onProcessDone(proc, running.stderr.readFrom(0).text)
-        this.live.delete(proc)
+        this.onProcessDone(proc, collected.stderr.readFrom(0).text)
       }, (error: unknown) => {
         // Background spawn failures settle as killed and surface through the read path.
         proc.status = 'killed'
-        running.stderr.push(Buffer.from(`spawn failed: ${String(error)}`))
-        this.onProcessDone(proc, running.stderr.readFrom(0).text)
-        this.live.delete(proc)
+        spawnFailureNote = `spawn failed: ${String(error)}`
+        this.onProcessDone(proc, spawnFailureNote)
       }),
       readOutput: (): BashProcessRead => {
-        const out = running.stdout.readFrom(stdoutOffset)
-        const err = running.stderr.readFrom(stderrOffset)
+        const out = collected.stdout.readFrom(stdoutOffset)
+        const err = collected.stderr.readFrom(stderrOffset)
         stdoutOffset = out.nextOffset
         stderrOffset = err.nextOffset
 
+        // A failed spawn never produced process output, so the note and real
+        // stderr text are mutually exclusive.
+        const errText = err.text.length > 0 ? err.text : consumeSpawnFailure()
         // Single newline between sections: stdout chunks usually end with one
         // already; add it only when missing.
         const separator = out.text.length > 0 && !out.text.endsWith('\n') ? '\n' : ''
         const delta = out.text
-          + (err.text.length > 0 ? `${separator}[stderr]\n${err.text}` : '')
+          + (errText.length > 0 ? `${separator}[stderr]\n${errText}` : '')
         return {
           delta,
           lossy: out.lossy || err.lossy,
@@ -195,11 +247,10 @@ export class LocalBashExecutor extends BashExecutor {
       kill: (): boolean => {
         if (proc.status !== 'running') return false
         proc.status = 'killed'
-        running.kill()
+        running.terminate()
         return true
       },
     }
-    this.live.set(proc, running)
     return proc
   }
 

packages/bash/bash-local/src/run.ts

@@ -1,399 +0,0 @@
-/**
- * Process plumbing for the local bash executor: detached process-group spawn,
- * tail-keep output with spill files, and SIGTERM→SIGKILL escalation. This layer
- * reacts to an abort signal; the executor owns deadlines and classifies causes.
- * @module dsh-bash-local/run
- */
-
-import { type ChildProcessByStdio, spawn } from 'node:child_process'
-import type { Readable, Writable } from 'node:stream'
-import { randomBytes } from 'node:crypto'
-import { closeSync, mkdtempSync, openSync, unlinkSync, writeSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { DSH_ENV_PREFIX } from '@deepseek-ai/dsh-bash'
-import type { CollectedOutput, DshEnvironment } from '@deepseek-ai/dsh-bash'
-
-/**
- * Model-friendly environment overrides: disable colors, pagers, and
- * interactive terminal features that would garble tool output (the same set
- * Codex hardcodes; Claude Code achieves it via TERM=dumb).
- */
-export const ENV_OVERRIDES = {
-  NO_COLOR: '1',
-  TERM: 'dumb',
-  PAGER: 'cat',
-  GIT_PAGER: 'cat',
-} as const
-
-/**
- * Credential-shaped env vars are NOT forwarded to commands (the harness's
- * own DEEPSEEK_API_KEY must not leak into `env` output, tool results, or
- * spill files). Same default pattern as Codex's env policy; a future config
- * can whitelist specific vars when a workflow genuinely needs one.
- */
-export const SENSITIVE_ENV_PATTERN = /KEY|SECRET|TOKEN/i
-
-/**
- * Build a child environment from scrubbed ambient values, terminal overrides,
- * ordinary caller entries, and a managed `DSH_*` snapshot. Ambient managed
- * names are removed; ordinary and managed entries reject the other channel's
- * namespace before `dshEnv` merges last.
- * @param extra - caller entries; `DSH_*` names are rejected.
- * @param dshEnv - managed entries; non-`DSH_*` names are rejected.
- * @returns the environment to hand to `spawn` for the child process.
- */
-export function childEnv(
-  extra?: Readonly<Record<string, string>>,
-  dshEnv?: DshEnvironment,
-): NodeJS.ProcessEnv {
-  const env: NodeJS.ProcessEnv = {}
-  for (const [key, value] of Object.entries(process.env)) {
-    if (!SENSITIVE_ENV_PATTERN.test(key) && !key.startsWith(DSH_ENV_PREFIX)) env[key] = value
-  }
-  for (const key of Object.keys(extra ?? {})) {
-    if (key.startsWith(DSH_ENV_PREFIX)) {
-      throw new Error(`ordinary bash env cannot set reserved variable "${key}"; use dshEnv`)
-    }
-  }
-  for (const key of Object.keys(dshEnv ?? {})) {
-    if (!key.startsWith(DSH_ENV_PREFIX)) {
-      throw new Error(`managed bash env cannot set ordinary variable "${key}"; use env`)
-    }
-  }
-  return { ...env, ...ENV_OVERRIDES, ...extra, ...dshEnv }
-}
-
-/** What to run and under which limits (resolved — no defaults in here). */
-export interface SpawnSpec {
-  command: string
-  cwd: string
-  /** Stdout in-memory cap; overflow spills to disk (tail kept in memory). */
-  stdoutMaxBytes: number
-  /** Stderr in-memory cap; overflow spills to disk (tail kept in memory). */
-  stderrMaxBytes: number
-  /** Per-stream spill-file cap; larger streams retain only their in-memory tail. */
-  maxSpillBytes: number
-  /** Grace period for kill escalation and for inherited pipes after shell exit. */
-  graceMs: number
-  /**
-   * Abort signal — kills the process group when it fires. The executor owns
-   * timing: `run()` passes a fused timeout/cancel deadline signal (see
-   * `@deepseek-ai/dsh-timeout`), `start()` passes the bare upstream signal.
-   * runBash only listens and kills; it does NOT classify why (the executor
-   * reads the signal's reason afterward).
-   */
-  signal?: AbortSignal | undefined
-  /**
-   * Bytes to write to the child's stdin, then close it. Absent (or empty)
-   * leaves stdin closed/empty. Set by in-process plugins (the hooks bridges);
-   * the model-facing `dsh-tool-bash` tool does not thread model input here.
-   */
-  stdin?: string | undefined
-  /**
-   * Ordinary environment entries merged after the credential scrub and
-   * terminal overrides. `DSH_*` names are rejected and belong in `dshEnv`.
-   */
-  env?: Record<string, string> | undefined
-  /** Harness-owned entries; non-`DSH_*` names are rejected before spawn. */
-  dshEnv?: DshEnvironment | undefined
-}
-
-/**
- * Raw outcome of one closed process (before result shaping). Deliberately
- * carries NO timeout/cancel classification: runBash kills on abort but does not
- * decide why — the executor's `run()`/`start()` reads the deadline signal it
- * owns to classify `timedOut`/`aborted` (see the package README).
- */
-export interface SpawnOutcome {
-  exitCode: number | null
-  signal: NodeJS.Signals | null
-  stdout: CollectedOutput
-  stderr: CollectedOutput
-}
-
-/** Injectable knobs so tests can exercise spill behavior without the OS tmpdir. */
-export interface RunInternals {
-  /** Directory for spill files (defaults to the OS temp dir). */
-  spillDir?: string
-}
-
-/** Default SIGTERM→SIGKILL grace period (the `graceMs` config; matches OpenCode's 3s). */
-export const DEFAULT_GRACE_MS = 3_000
-
-/** Default per-stream spill cap (the `maxSpillBytes` config). */
-export const DEFAULT_MAX_SPILL_BYTES = 64 * 1024 * 1024
-
-let spillCounter = 0
-let defaultSpillDir: string | undefined
-
-/**
- * The default spill location: a private (0700) per-process directory under
- * the OS tmpdir, created lazily. Predictable world-readable paths would let
- * other local users read command output or pre-create symlinks.
- */
-function privateSpillDir(): string {
-  defaultSpillDir ??= mkdtempSync(join(tmpdir(), 'dsh-bash-'))
-  return defaultSpillDir
-}
-
-/**
- * Collects one stream with a bounded in-memory tail. On first overflow a
- * spill file is created and every chunk (including those already collected)
- * is appended there while the full stream remains within `maxSpillBytes`.
- *
- * Tail-keep rationale (pi/OpenCode): errors and final results cluster at the
- * end of command output; the spill file covers the head.
- */
-export class OutputCollector {
-  private chunks: Buffer[] = []
-  private bytes = 0
-  private dropped = false
-  private spillFd: number | undefined
-  private spillFile: string | undefined
-  private spillDisabled = false
-  /** Total bytes ever pushed (not just retained). */
-  private total = 0
-
-  constructor(
-    private readonly maxBytes: number,
-    private readonly maxSpillBytes: number,
-    private readonly label: string,
-    private readonly spillDir: string,
-  ) {}
-
-  /**
-   * Ingest one stream chunk, counting it toward the whole-stream total. On
-   * first overflow of the in-memory cap a spill file is opened and every chunk
-   * (already-collected ones included) is appended there from then on; the
-   * in-memory tail then drops whole chunks from its head (or the head of a
-   * single over-cap chunk) until it fits the cap again.
-   * @param chunk - the raw bytes from one stream 'data' event.
-   */
-  push(chunk: Buffer): void {
-    this.total += chunk.length
-    const overflows = this.bytes + chunk.length > this.maxBytes
-    if (!this.spillDisabled && (overflows || this.spillFd !== undefined)) this.spillAll(chunk)
-    this.chunks.push(chunk)
-    this.bytes += chunk.length
-    while (this.bytes > this.maxBytes && this.chunks.length > 1) {
-      // Drop whole chunks from the head; pipe chunks are small (≤64KiB), so
-      // the retained tail tracks the cap closely enough for a model-facing
-      // truncation boundary. (length > 1 was just checked — shift() returns.)
-      const head = this.chunks.shift() as Buffer
-      this.bytes -= head.length
-      this.dropped = true
-    }
-    if (this.bytes > this.maxBytes && this.chunks.length === 1) {
-      // A single chunk larger than the cap: keep its tail.
-      const only = this.chunks[0] as Buffer
-      this.chunks[0] = only.subarray(only.length - this.maxBytes)
-      this.bytes = this.maxBytes
-      this.dropped = true
-    }
-  }
-
-  /** Open the spill file lazily and append `chunk` (and any prior chunks once). */
-  private spillAll(chunk: Buffer): void {
-    if (this.total > this.maxSpillBytes) {
-      this.discardSpill()
-      return
-    }
-    if (this.spillFd === undefined) {
-      // Random suffix + O_EXCL + no-follow-equivalent ('wx' fails on any
-      // existing path, symlink or not) + owner-only mode: defeats spill-path
-      // prediction and symlink planting in shared tmp dirs.
-      this.spillFile = join(
-        this.spillDir,
-        `dsh-bash-${process.pid}-${++spillCounter}-${randomBytes(6).toString('hex')}-${this.label}.log`,
-      )
-      this.spillFd = openSync(this.spillFile, 'wx', 0o600)
-      for (const prior of this.chunks) writeSync(this.spillFd, prior)
-    }
-    writeSync(this.spillFd, chunk)
-  }
-
-  /** Stop spilling and remove the file once it can no longer hold the complete stream. */
-  private discardSpill(): void {
-    const fd = this.spillFd
-    const file = this.spillFile
-    this.spillFd = undefined
-    this.spillFile = undefined
-    this.spillDisabled = true
-    if (fd !== undefined) {
-      try {
-        closeSync(fd)
-      } catch {
-        // Retain the descriptor so finalize can retry the failed close.
-        this.spillFd = fd
-      }
-    }
-    if (file !== undefined) {
-      try {
-        unlinkSync(file)
-      } catch {
-        // A failed unlink leaves at most maxSpillBytes behind, never an unbounded file.
-      }
-    }
-  }
-
-  /**
-   * Incremental read in whole-stream byte coordinates: returns everything
-   * pushed since `fromByte`. When `fromByte` has already slid out of the
-   * in-memory tail window, the read is `lossy` — it returns the whole
-   * retained tail and the gap is only recoverable from the spill file.
-   * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 for the first read).
-   * @returns the delta text, the offset for the next read, the `lossy` flag, and the spill path when one was created.
-   */
-  readFrom(fromByte: number): { text: string; nextOffset: number; lossy: boolean; spillPath?: string } {
-    const windowStart = this.total - this.bytes
-    const buffer = Buffer.concat(this.chunks)
-    const lossy = fromByte < windowStart
-    const slice = lossy ? buffer : buffer.subarray(fromByte - windowStart)
-    return {
-      text: slice.toString('utf8'),
-      nextOffset: this.total,
-      lossy,
-      ...this.spillFile !== undefined ? { spillPath: this.spillFile } : {},
-    }
-  }
-
-  /**
-   * Close the spill file (if any) and return the final output. A failed close
-   * (delayed writeback fault) stops advertising the spill path — the file may
-   * be missing its tail — but still returns the in-memory result.
-   * @returns the final collected output: tail text, truncation flag, and the spill path when intact.
-   */
-  finalize(): CollectedOutput {
-    if (this.spillFd !== undefined) {
-      try {
-        closeSync(this.spillFd)
-      } catch {
-        // A delayed writeback failure makes the spill unreliable; keep finalize
-        // total but stop advertising that file.
-        this.spillFile = undefined
-      }
-      this.spillFd = undefined
-    }
-    return {
-      text: Buffer.concat(this.chunks).toString('utf8'),
-      truncated: this.dropped,
-      ...this.spillFile !== undefined ? { spillPath: this.spillFile } : {},
-    }
-  }
-}
-
-/**
- * Send `sig` to a detached process group. Never throws: delivery races process
- * exit and may run in a timer callback, so failures are contained and a
- * non-positive pid is a no-op.
- * @param pid - the group leader's pid; non-positive means the spawn failed and the call is a no-op.
- * @param sig - the signal to deliver to the whole group.
- */
-export function killGroup(pid: number, sig: NodeJS.Signals): void {
-  if (pid <= 0) return
-  try {
-    process.kill(-pid, sig)
-  } catch {
-    // Swallow: see contract above.
-  }
-}
-
-/**
- * A live bash child process: the promise resolves when the process closes;
- * `kill()` starts the SIGTERM→grace→SIGKILL escalation on its group.
- */
-export interface RunningBash {
-  /** Process id (group leader); -1 when the spawn itself failed. */
-  readonly pid: number
-  /** stdout/stderr collectors (live — background polling reads incrementally). */
-  readonly stdout: OutputCollector
-  readonly stderr: OutputCollector
-  /** Resolves when the process closes; rejects only for spawn-level failures. */
-  readonly done: Promise<SpawnOutcome>
-  /** Begin SIGTERM→grace→SIGKILL on the process group. Idempotent. */
-  kill(): void
-}
-
-/**
- * Spawn one isolated `bash -c` process group and collect its output.
- * Runtime exits resolve as {@link SpawnOutcome}; only spawn failures reject.
- * @param spec - fully resolved command, cwd, limits, and cancellation.
- * @param internals - test-only process and spill-directory overrides.
- * @returns live process handle and outcome promise.
- */
-// XXX(stateful-shell): evaluate persistent cwd or PTY sessions when workflows require shell state.
-export function runBash(spec: SpawnSpec, internals: RunInternals = {}): RunningBash {
-  const spillDir = internals.spillDir ?? privateSpillDir()
-
-  if (spec.signal?.aborted) {
-    throw new Error(`aborted before spawn: ${String(spec.signal.reason ?? 'aborted')}`)
-  }
-
-  // Keep absent stdin as /dev/null; literal tuples preserve non-null output types.
-  const env = childEnv(spec.env, spec.dshEnv)
-  const child: ChildProcessByStdio<Writable | null, Readable, Readable> = spec.stdin !== undefined
-    ? spawn('bash', ['-c', spec.command], { cwd: spec.cwd, env, stdio: ['pipe', 'pipe', 'pipe'], detached: true })
-    : spawn('bash', ['-c', spec.command], { cwd: spec.cwd, env, stdio: ['ignore', 'pipe', 'pipe'], detached: true })
-
-  const stdout = new OutputCollector(spec.stdoutMaxBytes, spec.maxSpillBytes, 'stdout', spillDir)
-  const stderr = new OutputCollector(spec.stderrMaxBytes, spec.maxSpillBytes, 'stderr', spillDir)
-  child.stdout.on('data', (chunk: Buffer) => { stdout.push(chunk) })
-  child.stderr.on('data', (chunk: Buffer) => { stderr.push(chunk) })
-
-  let graceTimer: NodeJS.Timeout | undefined
-
-  // Failed spawns use pid -1 so kill remains a no-op.
-  const pid = child.pid ?? -1
-
-  const kill = (): void => {
-    if (graceTimer !== undefined) return // escalation already in flight
-    killGroup(pid, 'SIGTERM')
-    graceTimer = setTimeout(() => { killGroup(pid, 'SIGKILL') }, spec.graceMs)
-  }
-
-  // The executor owns timeout classification; this layer only reacts to abort.
-  const onAbort = (): void => { kill() }
-  spec.signal?.addEventListener('abort', onAbort, { once: true })
-
-  // Stdin writes are best-effort; process exit and captured output remain authoritative.
-  if (child.stdin !== null) {
-    child.stdin.on('error', () => { /* stdin write is best-effort; outcome rides on exit/output. */ })
-    child.stdin.end(spec.stdin)
-  }
-
-  const done = new Promise<SpawnOutcome>((resolve, reject) => {
-    let settled = false
-    let pipeDrainTimer: NodeJS.Timeout | undefined
-    const settle = (exitCode: number | null, signal: NodeJS.Signals | null): void => {
-      if (settled) return
-      settled = true
-      child.stdout.destroy()
-      child.stderr.destroy()
-      cleanup()
-      resolve({
-        exitCode,
-        signal,
-        stdout: stdout.finalize(),
-        stderr: stderr.finalize(),
-      })
-    }
-    child.on('error', (error) => {
-      // No meaningful close outcome follows a spawn failure.
-      settled = true
-      cleanup()
-      reject(error)
-    })
-    child.on('exit', (exitCode, signal) => {
-      pipeDrainTimer = setTimeout(() => { settle(exitCode, signal) }, spec.graceMs)
-    })
-    child.on('close', settle)
-    function cleanup(): void {
-      if (graceTimer !== undefined) clearTimeout(graceTimer)
-      if (pipeDrainTimer !== undefined) clearTimeout(pipeDrainTimer)
-      spec.signal?.removeEventListener('abort', onAbort)
-    }
-  })
-
-  return { pid, stdout, stderr, done, kill }
-}

packages/bash/bash-local/tests/executor.spec.ts

@@ -4,16 +4,18 @@ import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import type { BashProcess } from '@deepseek-ai/dsh-bash'
 
 const spillDir = mkdtempSync(join(tmpdir(), 'dsh-bash-exec-spec-'))
 
 async function setup(config: ConstructorParameters<typeof LocalBashExecutor>[1] = {}) {
   const ctx = new Context()
+  await ctx.plugin(LocalSubprocessService)
+  ;(ctx.subprocess as LocalSubprocessService).internals = { spillDir }
   // A short kill grace via the REAL config path, so escalation tests stay fast.
   await ctx.plugin(LocalBashExecutor, { graceMs: 200, ...config })
   const bash = ctx.bash as LocalBashExecutor
-  bash.internals = { spillDir }
   return { ctx, bash }
 }
 
@@ -293,44 +295,52 @@ describe('LocalBashExecutor.start (background process handles)', () => {
   })
 })
 
-describe('LocalBashExecutor disposal', () => {
-  it('disposing the fiber kills running processes and AWAITS their exit (no orphans, SIGKILL escalation included)', async () => {
+describe('process lifecycle ownership (the subprocess service, not the executor)', () => {
+  it('a background process survives executor-fiber disposal and dies with the subprocess service', async () => {
     const ctx = new Context()
-    const fiber = await ctx.plugin(LocalBashExecutor, { graceMs: 200 })
+    const managerFiber = await ctx.plugin(LocalSubprocessService)
+    ;(ctx.subprocess as LocalSubprocessService).internals = { spillDir }
+    const executorFiber = await ctx.plugin(LocalBashExecutor, { graceMs: 200 })
     const bash = ctx.bash as LocalBashExecutor
-    bash.internals = { spillDir }
 
     // The child prints its own pid ($$ = the detached bash group leader) so
     // the test can probe liveness through the public read surface alone.
-    const proc = bash.start(bash.resolve({ command: 'trap \'\' TERM; echo $$; sleep 60' }))
+    const proc = bash.start(bash.resolve({ command: 'echo $$; sleep 60' }))
     const pid = Number((await readUntil(proc, '\n')).trim())
     expect(Number.isInteger(pid) && pid > 0).toBe(true)
 
-    await fiber.dispose()
-    // Disposal itself waited: the pid must already be gone, no grace left —
-    // even for a TERM-trapping child held until the SIGKILL escalation landed.
+    // Executor reload/disposal leaves background work running — the
+    // handle stays live and readable, mirroring the task runtime's
+    // registrations-outlive-producer-fibers contract.
+    await executorFiber.dispose()
+    expect(proc.status).toBe('running')
+    expect(() => process.kill(pid, 0)).not.toThrow()
+
+    // Service disposal kills the group and AWAITS its exit (no orphans).
+    await managerFiber.dispose()
     expect(() => process.kill(pid, 0)).toThrow()
-    expect(proc.status).toBe('killed')
     await proc.done
+    expect(proc.status).toBe('killed')
   })
 
-  it('settled processes already left the live map: dispose does not touch them', async () => {
+  it('service disposal escalates to SIGKILL for TERM-trapping children and settles handles', async () => {
     const ctx = new Context()
-    const fiber = await ctx.plugin(LocalBashExecutor, { graceMs: 200 })
+    const managerFiber = await ctx.plugin(LocalSubprocessService)
+    ;(ctx.subprocess as LocalSubprocessService).internals = { spillDir }
+    await ctx.plugin(LocalBashExecutor, { graceMs: 200 })
     const bash = ctx.bash as LocalBashExecutor
-    bash.internals = { spillDir }
 
     const finished = bash.start(bash.resolve({ command: 'echo done' }))
     await finished.done
     expect(finished.status).toBe('completed')
-    const running = bash.start(bash.resolve({ command: 'sleep 60' }))
+    const trapping = bash.start(bash.resolve({ command: 'trap \'\' TERM; echo armed; sleep 60' }))
+    await readUntil(trapping, 'armed')
 
-    await fiber.dispose()
-    // The teardown marks every LIVE entry killed; a settled process had
-    // already left the map, so its status stays completed.
+    await managerFiber.dispose()
+    // A settled process was untouched; the live one died by escalation.
     expect(finished.status).toBe('completed')
-    expect(running.status).toBe('killed')
-    await running.done
-    expect(running.signal).toBe('SIGTERM')
+    await trapping.done
+    expect(trapping.status).toBe('killed')
+    expect(trapping.signal).toBe('SIGKILL')
   })
 })

packages/bash/bash-local/tests/run.spec.ts

@@ -1,510 +0,0 @@
-import { mkdtempSync, readFileSync, statSync, unlinkSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { dirname, join } from 'node:path'
-import { describe, expect, it, vi } from 'vitest'
-import type { DshEnvironment } from '@deepseek-ai/dsh-bash'
-import { killGroup, OutputCollector, runBash } from '../src/run.ts'
-import type { RunningBash } from '../src/run.ts'
-
-const { failNextClose, failNextUnlink } = vi.hoisted(() => ({
-  failNextClose: { value: false },
-  failNextUnlink: { value: false },
-}))
-vi.mock('node:fs', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('node:fs')>()
-  return {
-    ...actual,
-    closeSync(fd: number): void {
-      if (failNextClose.value) {
-        failNextClose.value = false
-        throw Object.assign(new Error('simulated EIO on close'), { code: 'EIO' })
-      }
-      actual.closeSync(fd)
-    },
-    unlinkSync(path: Parameters<typeof actual.unlinkSync>[0]): void {
-      if (failNextUnlink.value) {
-        failNextUnlink.value = false
-        throw Object.assign(new Error('simulated EIO on unlink'), { code: 'EIO' })
-      }
-      actual.unlinkSync(path)
-    },
-  }
-})
-
-const spillDir = mkdtempSync(join(tmpdir(), 'dsh-bash-spec-'))
-
-function spec(command: string, overrides: Partial<Parameters<typeof runBash>[0]> = {}) {
-  return {
-    command,
-    cwd: process.cwd(),
-    stdoutMaxBytes: 64_000,
-    stderrMaxBytes: 64_000,
-    maxSpillBytes: 64 * 1024 * 1024,
-    graceMs: 3_000,
-    ...overrides,
-  }
-}
-
-/** Poll until a pid no longer exists (kill(pid, 0) throws ESRCH). */
-async function waitGone(pid: number, timeoutMs = 5_000): Promise<void> {
-  const deadline = Date.now() + timeoutMs
-  while (Date.now() < deadline) {
-    try {
-      process.kill(pid, 0)
-    } catch {
-      return
-    }
-    await new Promise(resolve => setTimeout(resolve, 20))
-  }
-  throw new Error(`pid ${pid} still alive after ${timeoutMs}ms`)
-}
-
-async function waitForStdout(running: RunningBash, expected: string, timeoutMs = 5_000): Promise<void> {
-  const deadline = Date.now() + timeoutMs
-  while (Date.now() < deadline) {
-    if (running.stdout.readFrom(0).text.includes(expected)) return
-    await new Promise(resolve => setTimeout(resolve, 20))
-  }
-  throw new Error(`stdout did not include ${JSON.stringify(expected)} after ${timeoutMs}ms`)
-}
-
-async function waitForPidFile(path: string, timeoutMs = 5_000): Promise<number> {
-  const deadline = Date.now() + timeoutMs
-  while (Date.now() < deadline) {
-    try {
-      const pid = Number(readFileSync(path, 'utf8').trim())
-      if (Number.isSafeInteger(pid) && pid > 0) return pid
-    } catch {
-      // The child shell has not written the pid file yet.
-    }
-    await new Promise(resolve => setTimeout(resolve, 20))
-  }
-  throw new Error(`pid file ${path} was not written after ${timeoutMs}ms`)
-}
-
-describe('runBash', () => {
-  it('captures stdout on success', async () => {
-    const result = await runBash(spec('echo hello')).done
-    expect(result.exitCode).toBe(0)
-    expect(result.signal).toBeNull()
-    expect(result.stdout.text).toBe('hello\n')
-    expect(result.stdout.truncated).toBe(false)
-    expect(result.stderr.text).toBe('')
-  })
-
-  it('captures stderr separately', async () => {
-    const result = await runBash(spec('echo oops >&2')).done
-    expect(result.exitCode).toBe(0)
-    expect(result.stdout.text).toBe('')
-    expect(result.stderr.text).toBe('oops\n')
-  })
-
-  it('captures both streams', async () => {
-    const result = await runBash(spec('echo out; echo err >&2')).done
-    expect(result.stdout.text).toBe('out\n')
-    expect(result.stderr.text).toBe('err\n')
-  })
-
-  it('reports non-zero exit codes', async () => {
-    const result = await runBash(spec('exit 42')).done
-    expect(result.exitCode).toBe(42)
-    expect(result.signal).toBeNull()
-  })
-
-  it('applies model-friendly env overrides', async () => {
-    const result = await runBash(spec('echo "$NO_COLOR/$TERM/$PAGER"')).done
-    expect(result.stdout.text).toBe('1/dumb/cat\n')
-  })
-
-  it('runs in the requested cwd', async () => {
-    const result = await runBash(spec('pwd', { cwd: '/tmp' })).done
-    expect(result.stdout.text.trim()).toMatch(/\/tmp$/)
-  })
-
-  it('kills the process group with SIGTERM when the signal fires', async () => {
-    // runBash owns no timer: it kills on abort. The executor drives the timeout
-    // by firing this signal via a deadline (see executor.spec.ts); here we
-    // assert the kill itself lands as SIGTERM.
-    const controller = new AbortController()
-    const start = Date.now()
-    const running = runBash(spec('sleep 60', { signal: controller.signal }))
-    setTimeout(() => { controller.abort('deadline') }, 100)
-    const result = await running.done
-    expect(Date.now() - start).toBeLessThan(5_000)
-    expect(result.signal).toBe('SIGTERM')
-    expect(result.exitCode).toBeNull()
-  })
-
-  it('escalates to SIGKILL when SIGTERM is trapped', async () => {
-    const running = runBash(spec('trap \'\' TERM; echo ready; while :; do sleep 60 & wait $!; done', { graceMs: 200 }))
-    await waitForStdout(running, 'ready\n')
-    running.kill()
-    const result = await running.done
-    expect(result.signal).toBe('SIGKILL')
-  })
-
-  it('kills the whole process group (grandchildren die too)', async () => {
-    // The subshell writes the sleep's pid then waits on it; killing the
-    // group must take the sleep down with bash.
-    const pidFile = join(spillDir, `grandchild-${Date.now()}.pid`)
-    const running = runBash(spec(`sleep 60 & echo $! > ${pidFile}; wait`))
-    const grandchild = await waitForPidFile(pidFile)
-    expect(grandchild).toBeGreaterThan(0)
-
-    running.kill()
-    const result = await running.done
-    expect(result.signal).toBe('SIGTERM')
-    await waitGone(grandchild)
-  })
-
-  it('aborts via AbortSignal mid-run', async () => {
-    const controller = new AbortController()
-    const running = runBash(spec('sleep 60', { signal: controller.signal }))
-    setTimeout(() => { controller.abort('user cancelled') }, 50)
-    const result = await running.done
-    expect(result.signal).toBe('SIGTERM')
-  })
-
-  it('throws when the signal is already aborted before spawn', () => {
-    const controller = new AbortController()
-    controller.abort('too late')
-    expect(() => runBash(spec('echo hi', { signal: controller.signal })))
-      .toThrow(/aborted before spawn: too late/)
-  })
-
-  it('rejects with a spawn error for a nonexistent cwd', async () => {
-    await expect(runBash(spec('echo hi', { cwd: '/nonexistent-dir-dsh-test' })).done)
-      .rejects.toThrow(/ENOENT/)
-  })
-
-  it('kill() is idempotent (second call does not restart escalation)', async () => {
-    const running = runBash(spec('sleep 60'))
-    running.kill()
-    running.kill()
-    const result = await running.done
-    expect(result.signal).toBe('SIGTERM')
-  })
-
-  it('bounds inherited-pipe draining after the shell exits', async () => {
-    const pidFile = join(spillDir, `pipe-holder-${Date.now()}.pid`)
-    const started = Date.now()
-    const running = runBash(spec(`sleep 60 & echo $! > ${pidFile}; echo shell-done`, { graceMs: 100 }))
-    const descendant = await waitForPidFile(pidFile)
-    try {
-      const result = await running.done
-      expect(Date.now() - started).toBeLessThan(1_000)
-      expect(result.exitCode).toBe(0)
-      expect(result.stdout.text).toBe('shell-done\n')
-    } finally {
-      process.kill(descendant, 'SIGKILL')
-      await waitGone(descendant)
-    }
-  })
-})
-
-describe('stdin and extra env (set by in-process plugins)', () => {
-  it('writes stdin to the command and closes it', async () => {
-    const result = await runBash(spec('cat', { stdin: 'hello from stdin\n' })).done
-    expect(result.exitCode).toBe(0)
-    expect(result.stdout.text).toBe('hello from stdin\n')
-  })
-
-  it('a command that reads stdin sees EOF when none is supplied', async () => {
-    // No stdin → fd 0 is /dev/null, so `cat` reads EOF and exits 0 with no
-    // output (it does NOT block).
-    const result = await runBash(spec('cat')).done
-    expect(result.exitCode).toBe(0)
-    expect(result.stdout.text).toBe('')
-  })
-
-  it('gives fd 0 the exact pre-seam type: /dev/null when no stdin, a pipe when supplied', async () => {
-    // With no bytes, fd 0 remains the pre-seam `ignore` default (/dev/null, a character device).
-    // Supplied bytes use Node's spawn pipe, which is an AF_UNIX socket rather than a FIFO.
-    const none = await runBash(spec('test -c /dev/stdin && echo char || echo other')).done
-    expect(none.stdout.text).toBe('char\n')
-    const piped = await runBash(spec('test -S /dev/stdin && echo socket || echo other', { stdin: 'x' })).done
-    expect(piped.stdout.text).toBe('socket\n')
-  })
-
-  it('merges ordinary extra env entries onto the scrubbed environment', async () => {
-    const result = await runBash(spec('echo "$EXTRA_ONE/$EXTRA_TWO"', {
-      env: { EXTRA_ONE: 'alpha', EXTRA_TWO: 'beta' },
-    })).done
-    expect(result.stdout.text).toBe('alpha/beta\n')
-  })
-
-  it('an explicit extra env entry overrides the model-friendly override and the scrub', async () => {
-    // TERM is a model-friendly OVERRIDE (dumb); an explicit extra entry wins.
-    // EXPLICIT_OVERRIDE_KEY matches the credential scrub pattern, yet an explicit
-    // entry is still honored — the scrub only drops AMBIENT process.env creds.
-    const result = await runBash(spec('echo "$TERM/$EXPLICIT_OVERRIDE_KEY"', {
-      env: { TERM: 'xterm-256color', EXPLICIT_OVERRIDE_KEY: 'explicit-wins' },
-    })).done
-    expect(result.stdout.text).toBe('xterm-256color/explicit-wins\n')
-  })
-
-  it('does not crash or reject when the child ignores a large stdin (EPIPE)', async () => {
-    // The child exits without reading, so closing a stdin pipe holding ~1 MiB triggers EPIPE.
-    // The handler swallows that write error and `done` reports the child's real exit.
-    const big = 'x'.repeat(1024 * 1024)
-    const result = await runBash(spec('exit 7', { stdin: big })).done
-    expect(result.exitCode).toBe(7)
-  })
-})
-
-describe('output truncation and spill', () => {
-  it('applies stdout and stderr caps independently', async () => {
-    const result = await runBash(
-      spec('printf "%.0sx" $(seq 1 500); printf "%.0se" $(seq 1 500) >&2', {
-        stdoutMaxBytes: 500,
-        stderrMaxBytes: 100,
-      }),
-      { spillDir },
-    ).done
-    expect(result.stdout.truncated).toBe(false)
-    expect(result.stdout.text).toBe('x'.repeat(500))
-    expect(result.stderr.truncated).toBe(true)
-    expect(result.stderr.text.length).toBeLessThanOrEqual(100)
-  })
-
-  it('keeps the tail and spills the full stream to disk', async () => {
-    // 200 numbered lines of ~10 bytes; cap at 500 bytes keeps a late tail.
-    const result = await runBash(
-      spec('for i in $(seq 1 200); do printf "line-%04d\\n" $i; done', { stdoutMaxBytes: 500, stderrMaxBytes: 500 }),
-      { spillDir },
-    ).done
-    expect(result.stdout.truncated).toBe(true)
-    expect(result.stdout.text.length).toBeLessThanOrEqual(500)
-    expect(result.stdout.text).toContain('line-0200')
-    expect(result.stdout.text).not.toContain('line-0001')
-    expect(result.stdout.spillPath).toBeDefined()
-    const full = readFileSync(result.stdout.spillPath!, 'utf8')
-    expect(full).toContain('line-0001')
-    expect(full).toContain('line-0200')
-  })
-
-  it('does not truncate output exactly at the cap', async () => {
-    const result = await runBash(
-      spec('printf "%.0sx" $(seq 1 500)', { stdoutMaxBytes: 500, stderrMaxBytes: 500 }),
-      { spillDir },
-    ).done
-    expect(result.stdout.truncated).toBe(false)
-    expect(result.stdout.text.length).toBe(500)
-    expect(result.stdout.spillPath).toBeUndefined()
-  })
-
-  it('settles with the tail and no spill path when final spill close fails', async () => {
-    failNextClose.value = true
-    const result = await runBash(
-      spec('for i in $(seq 1 200); do printf "line-%04d\\n" $i; done', { stdoutMaxBytes: 500, stderrMaxBytes: 500 }),
-      { spillDir },
-    ).done
-    expect(failNextClose.value).toBe(false)
-    expect(result.exitCode).toBe(0)
-    expect(result.stdout.truncated).toBe(true)
-    expect(result.stdout.text).toContain('line-0200')
-    expect(result.stdout.spillPath).toBeUndefined()
-  })
-})
-
-describe('OutputCollector', () => {
-  it('keeps the tail of a single oversized chunk', () => {
-    const collector = new OutputCollector(10, 100, 'test', spillDir)
-    collector.push(Buffer.from('0123456789abcdef'))
-    const out = collector.finalize()
-    expect(out.text).toBe('6789abcdef')
-    expect(out.truncated).toBe(true)
-    expect(readFileSync(out.spillPath!, 'utf8')).toBe('0123456789abcdef')
-  })
-
-  it('readFrom returns increments and flags lossy reads', () => {
-    const collector = new OutputCollector(10, 100, 'test', spillDir)
-    collector.push(Buffer.from('aaaaa'))
-    const first = collector.readFrom(0)
-    expect(first.text).toBe('aaaaa')
-    expect(first.lossy).toBe(false)
-    expect(first.nextOffset).toBe(5)
-
-    collector.push(Buffer.from('bbbbb'))
-    const second = collector.readFrom(first.nextOffset)
-    expect(second.text).toBe('bbbbb')
-    expect(second.lossy).toBe(false)
-
-    // Push enough to slide the window past the last offset.
-    collector.push(Buffer.from('c'.repeat(20)))
-    const third = collector.readFrom(second.nextOffset)
-    expect(third.lossy).toBe(true)
-    expect(third.text).toBe('c'.repeat(10))
-    expect(third.spillPath).toBeDefined()
-  })
-
-  it('contains close failures and drops the spill path', () => {
-    const collector = new OutputCollector(4, 100, 'closefail', spillDir)
-    collector.push(Buffer.from('aaaa'))
-    collector.push(Buffer.from('bbbb'))
-    expect(collector.readFrom(0).spillPath).toBeDefined()
-
-    failNextClose.value = true
-    let out: ReturnType<typeof collector.finalize>
-    expect(() => { out = collector.finalize() }).not.toThrow()
-
-    expect(failNextClose.value).toBe(false)
-    expect(out!.text).toBe('bbbb')
-    expect(out!.truncated).toBe(true)
-    expect(out!.spillPath).toBeUndefined()
-  })
-
-  it('discards a spill that exceeds its configured cap', () => {
-    const collector = new OutputCollector(4, 8, 'bounded', spillDir)
-    collector.push(Buffer.from('aaaa'))
-    collector.push(Buffer.from('bbbb'))
-    const spillPath = collector.readFrom(0).spillPath!
-    expect(readFileSync(spillPath, 'utf8')).toBe('aaaabbbb')
-
-    collector.push(Buffer.from('c'))
-    collector.push(Buffer.from('dddd'))
-    const out = collector.finalize()
-    expect(out.text).toBe('dddd')
-    expect(out.truncated).toBe(true)
-    expect(out.spillPath).toBeUndefined()
-    expect(() => readFileSync(spillPath)).toThrow()
-  })
-
-  it('does not create a spill when the first overflowing chunk exceeds the cap', () => {
-    const collector = new OutputCollector(4, 4, 'no-spill', spillDir)
-    collector.push(Buffer.from('abcdefgh'))
-    const out = collector.finalize()
-    expect(out.text).toBe('efgh')
-    expect(out.truncated).toBe(true)
-    expect(out.spillPath).toBeUndefined()
-  })
-
-  it('contains cleanup failures while disabling an oversize spill', () => {
-    const collector = new OutputCollector(4, 8, 'cleanup-fail', spillDir)
-    collector.push(Buffer.from('aaaa'))
-    collector.push(Buffer.from('bbbb'))
-    const spillPath = collector.readFrom(0).spillPath!
-
-    failNextClose.value = true
-    failNextUnlink.value = true
-    expect(() => { collector.push(Buffer.from('c')) }).not.toThrow()
-    expect(failNextClose.value).toBe(false)
-    expect(failNextUnlink.value).toBe(false)
-    expect(collector.finalize().spillPath).toBeUndefined()
-    unlinkSync(spillPath)
-  })
-})
-
-describe('killGroup', () => {
-  it('ignores non-positive pids', () => {
-    expect(() => { killGroup(-1, 'SIGTERM') }).not.toThrow()
-    expect(() => { killGroup(0, 'SIGTERM') }).not.toThrow()
-  })
-
-  it('swallows ESRCH for vanished groups', async () => {
-    const running = runBash(spec('true'))
-    await running.done
-    expect(() => { killGroup(running.pid, 'SIGTERM') }).not.toThrow()
-  })
-})
-
-describe('abort edge cases', () => {
-  it('reports a fallback reason for reason-less pre-aborted signals', () => {
-    // Real AbortControllers always set a DOMException reason; signal-like
-    // objects from other libraries may not — the fallback covers them.
-    const bare = {
-      aborted: true,
-      reason: undefined,
-      addEventListener() {},
-      removeEventListener() {},
-    } as unknown as AbortSignal
-    expect(() => runBash(spec('echo hi', { signal: bare })))
-      .toThrow(/aborted before spawn: aborted/)
-  })
-
-  it('reports the terminating signal of an externally self-killed command', async () => {
-    // runBash reports the raw signal; whether it counts as timeout/cancel is the
-    // executor's classification (a self-kill is neither) — see executor.spec.ts.
-    const result = await runBash(spec('kill -TERM $$')).done
-    expect(result.signal).toBe('SIGTERM')
-  })
-})
-
-describe('environment and spill-file hardening', () => {
-  it('scrubs credential-shaped and ambient DSH env vars from child processes', async () => {
-    process.env.DSH_TEST_API_KEY = 'super-secret'
-    process.env.DSH_TEST_TOKEN = 'also-secret'
-    process.env.DSH_TEST_PLAIN = 'visible'
-    try {
-      const result = await runBash(spec('echo "[${DSH_TEST_API_KEY:-absent}|${DSH_TEST_TOKEN:-absent}|${DSH_TEST_PLAIN:-absent}]"')).done
-      expect(result.stdout.text.trim()).toBe('[absent|absent|absent]')
-    } finally {
-      delete process.env.DSH_TEST_API_KEY
-      delete process.env.DSH_TEST_TOKEN
-      delete process.env.DSH_TEST_PLAIN
-    }
-  })
-
-  it('injects only the current trusted DSH environment after scrubbing ambient values', async () => {
-    process.env.DSH_STALE = 'old-value'
-    try {
-      const result = await runBash(spec('echo "[${DSH_STALE:-absent}|$DSH_SHELL|$DSH_SESSION_ID]"', {
-        dshEnv: { DSH_SHELL: '1', DSH_SESSION_ID: 'current-session' },
-      })).done
-      expect(result.stdout.text.trim()).toBe('[absent|1|current-session]')
-    } finally {
-      delete process.env.DSH_STALE
-    }
-  })
-
-  it('rejects DSH variables on the ordinary env channel', () => {
-    expect(() => runBash(spec('true', { env: { DSH_WRONG_CHANNEL: 'bad' } })))
-      .toThrow(/DSH_WRONG_CHANNEL.*dshEnv/)
-  })
-
-  it('rejects ordinary variables on the managed env channel', () => {
-    const invalid = { PATH: '/wrong-channel' } as unknown as DshEnvironment
-    expect(() => runBash(spec('true', { dshEnv: invalid })))
-      .toThrow(/managed bash env.*PATH.*use env/)
-  })
-
-  it('creates spill files with owner-only permissions and random names', async () => {
-    const result = await runBash(
-      spec('for i in $(seq 1 200); do printf "line-%04d\\n" $i; done', { stdoutMaxBytes: 500, stderrMaxBytes: 500 }),
-      { spillDir },
-    ).done
-    const path = result.stdout.spillPath!
-    expect(path).toMatch(/dsh-bash-\d+-\d+-[0-9a-f]{12}-stdout\.log$/)
-    const mode = statSync(path).mode & 0o777
-    expect(mode).toBe(0o600)
-  })
-
-  it('defaults spills into a private per-process directory', async () => {
-    const result = await runBash(
-      spec('for i in $(seq 1 200); do printf "line-%04d\\n" $i; done', { stdoutMaxBytes: 500, stderrMaxBytes: 500 }),
-    ).done
-    const dir = dirname(result.stdout.spillPath!)
-    expect(dir).toMatch(/dsh-bash-/)
-    const mode = statSync(dir).mode & 0o777
-    expect(mode).toBe(0o700)
-  })
-
-  it('killGroup never throws, even for EPERM-style failures', () => {
-    const spy = vi.spyOn(process, 'kill').mockImplementation(() => {
-      throw Object.assign(new Error('EPERM'), { code: 'EPERM' })
-    })
-    try {
-      expect(() => { killGroup(12345, 'SIGTERM') }).not.toThrow()
-    } finally {
-      spy.mockRestore()
-    }
-  })
-
-  it('honors AbortSignal on background-style runs (no timeout)', async () => {
-    const controller = new AbortController()
-    const running = runBash(spec('sleep 60', { signal: controller.signal }))
-    setTimeout(() => { controller.abort() }, 50)
-    const result = await running.done
-    expect(result.signal).toBe('SIGTERM')
-  })
-})

packages/bash/bash-local/tsconfig.json

@@ -26,6 +26,9 @@
     {
       "path": "../../bash/bash"
     },
+    {
+      "path": "../../subprocess/subprocess"
+    },
     {
       "path": "../../support/invariants"
     }

packages/bash/bash-sandbox/package.json

@@ -38,6 +38,7 @@
     "@deepseek-ai/dsh-bash": "workspace:^",
     "@deepseek-ai/dsh-bash-local": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
     "@deepseek-ai/dsh-sandbox": "workspace:^",
     "@deepseek-ai/dsh-sandbox-local": "workspace:^",
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",

packages/bash/bash-sandbox/src/index.ts

@@ -34,7 +34,7 @@ export type Config = LocalConfig
  * mode; `result.sandbox` reports the mode and enforcement actually used.
  */
 export class SandboxBashExecutor extends LocalBashExecutor {
-  static inject = ['sandbox', 'sandboxPolicy']
+  static override inject = ['subprocess', 'sandbox', 'sandboxPolicy']
 
   // No own Config: the sandbox default (mode + workspaceRoot) moved to
   // ctx.sandboxPolicy, so this executor inherits LocalBashExecutor's Config
@@ -128,7 +128,7 @@ export class SandboxBashExecutor extends LocalBashExecutor {
    * Wrap one shell command via the `ctx.sandbox` provider: hand over the
    * exact `['bash', '-c', command]` argv this executor would spawn, get back
    * the confined argv, and re-assemble it into the `exec …` command string
-   * the inherited spawn path runs (the outer `bash -c` that `runBash` spawns
+   * the inherited spawn path runs (the outer `bash -c` the subprocess service spawns
    * `exec`s into the runner, so no extra shell lingers). Provider errors
    * (fail-closed `SANDBOX_UNAVAILABLE`) propagate to the caller unchanged.
    */

packages/bash/bash-sandbox/tests/bwrap.e2e.ts

@@ -9,6 +9,7 @@ import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
 import { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
 import { bwrapProfileArgs } from '@deepseek-ai/dsh-sandbox-local/src/profiles.ts'
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 
 /**
  * Keyless integration of the real provider and executor through public run/start paths. With
@@ -42,6 +43,7 @@ async function sandboxedBash(workspace: string, mode: 'read-only' | 'workspace-w
   ctx = new Context()
   await ctx.plugin(LocalSandboxProvider, {})
   await ctx.plugin(SandboxPolicyService, { mode, workspaceRoot: workspace })
+  await ctx.plugin(LocalSubprocessService)
   await ctx.plugin(SandboxBashExecutor, { cwd: workspace, timeoutMs: 30_000 })
   return ctx.bash as SandboxBashExecutor
 }

packages/bash/bash-sandbox/tests/landlock.e2e.ts

@@ -9,6 +9,7 @@ import { launcherPath } from 'node-addon-landlock-run'
 import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
 import { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 
 /**
  * KEYLESS consumer-integration proof: the REAL `LocalSandboxProvider` (bwrap
@@ -47,6 +48,7 @@ async function sandboxedBash(workspace: string, mode: 'read-only' | 'workspace-w
   await ctx.plugin(LocalSandboxProvider, {})
   ;(ctx.sandbox as LocalSandboxProvider).internals = { probeBwrap: () => false }
   await ctx.plugin(SandboxPolicyService, { mode, workspaceRoot: workspace })
+  await ctx.plugin(LocalSubprocessService)
   await ctx.plugin(SandboxBashExecutor, { cwd: workspace, timeoutMs: 30_000 })
   return ctx.bash as SandboxBashExecutor
 }

packages/bash/bash-sandbox/tests/sandbox.spec.ts

@@ -15,6 +15,7 @@ import { SANDBOX_UNAVAILABLE, SandboxProvider, SandboxUnavailableError } from '@
 import type { ConfinedArgv, SandboxExecutionPolicy, SandboxMode, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 import { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import { classifyDenial, classifyRunnerFailure, shellQuote } from '../src/helpers.ts'
 import type { Config } from '@deepseek-ai/dsh-bash-sandbox'
 
@@ -58,9 +59,10 @@ async function setup(
     ...mode !== undefined ? { mode } : {},
     ...workspaceRoot !== undefined ? { workspaceRoot } : {},
   })
+  await ctx.plugin(LocalSubprocessService)
+  ;(ctx.subprocess as LocalSubprocessService).internals = { spillDir }
   await ctx.plugin(SandboxBashExecutor, { graceMs: 200, ...execConfig })
   const bash = ctx.bash as SandboxBashExecutor
-  bash.internals = { spillDir }
   return { ctx, bash, calls }
 }
 

packages/bash/bash-sandbox/tests/seatbelt.e2e.ts

@@ -9,6 +9,7 @@ import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
 import { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
 import { seatbeltProfileArgs } from '@deepseek-ai/dsh-sandbox-local/src/profiles.ts'
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 
 /**
  * Keyless macOS integration of the real provider and executor through public run/start paths.
@@ -41,6 +42,7 @@ async function sandboxedBash(workspace: string, mode: 'read-only' | 'workspace-w
   await ctx.plugin(LocalSandboxProvider, {})
   ;(ctx.sandbox as LocalSandboxProvider).internals = { probeBwrap: () => false, probeLandlock: () => 'unusable' }
   await ctx.plugin(SandboxPolicyService, { mode, workspaceRoot: workspace })
+  await ctx.plugin(LocalSubprocessService)
   await ctx.plugin(SandboxBashExecutor, { cwd: workspace, timeoutMs: 30_000 })
   return ctx.bash as SandboxBashExecutor
 }

packages/bash/bash/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-README.md: b4ee66a1fa2696254a1f2f411b7db5d3190f8370
-README.zh.md: 151d4bd7ab257234584b9008c96e6356d7e39351
+README.md: d7bf746969f52000fe298b65b995b7c631d8001c
+README.zh.md: 14476b770397e4ef850c7c867e3058e25085c339

packages/bash/bash/README.md

@@ -33,7 +33,7 @@ Implementations subclass `BashExecutor` and implement the abstract methods. Disp
 
 The per-session sandbox-mode override vocabulary (the `'sandbox/mode'` event, the `effectiveSandboxMode(events)` fold, and the `setSandboxMode(session, mode)` write path) is NOT here — it is policy state shared by every enforcing family, owned by [`@deepseek-ai/dsh-sandbox-policy`](../../sandbox/sandbox-policy/). `run()` returns `BashRunResult`; `start()` returns `BashProcess`, whose incremental read and kill methods are adapted by `dsh-tool-bash` into a generic task registration. A sandboxing executor stamps `BashSandboxInfo` on foreground results and settled process handles. See `src/types.ts` and [core-data-structures/bash.md](../../../docs/core-data-structures/bash.md).
 
-`stdin` and ordinary `env` are set by in-process plugins (the hooks bridges, native plugins) to feed a hook command its JSON payload and `CLAUDE_PROJECT_DIR`/`CLAUDE_PLUGIN_ROOT` values. `dshEnv` is a separate trusted overlay restricted by type to managed keys; the exported `DSH_ENV_PREFIX` is the single source for that namespace, its `DshEnvironmentKey` template type, executor scrubbing, registry validation, derived built-in names, and model guidance. Model bash uses the current snapshot collected by `ctx.bashEnv`. Implementations remove inherited managed keys, reject those names in ordinary `env`, then merge `dshEnv`, so an omitted current fact cannot fall back to stale ambient state. The model-facing tool exposes none of these as parameters. All three remain optional on the resolved spec; absent means no input/overlay. See [the bash-stdin-env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [the session environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
+`stdin` and ordinary `env` are set by in-process plugins (the hooks bridges, native plugins) to feed a hook command its JSON payload and `CLAUDE_PROJECT_DIR`/`CLAUDE_PLUGIN_ROOT` values. `dshEnv` is a separate trusted overlay restricted by type to managed keys; the exported `DSH_ENV_PREFIX` is the single source for that namespace, its `DshEnvironmentKey` template type, executor scrubbing, registry validation, derived built-in names, and model guidance. Model bash uses the current snapshot collected by `ctx.bashEnv`. Implementations remove inherited managed keys, then merge `dshEnv` after ordinary `env`, so an omitted current fact cannot fall back to stale ambient state and an `env` entry cannot displace a managed value. The model-facing tool exposes none of these as parameters. All three remain optional on the resolved spec; absent means no input/overlay. See [the bash-stdin-env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [the session environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
 
 ## Model Experience
 

packages/bash/bash/README.zh.md

@@ -33,7 +33,7 @@
 
 每会话沙箱模式覆盖词汇（`'sandbox/mode'` 事件、`effectiveSandboxMode(events)` fold 以及 `setSandboxMode(session, mode)` 写入路径）不位于此处。它是所有强制执行家族共享的策略状态，属于 [`@deepseek-ai/dsh-sandbox-policy`](../../sandbox/sandbox-policy/)。`run()` 返回 `BashRunResult`；`start()` 返回 `BashProcess`，其增量读取与终止方法由 `dsh-tool-bash` 适配为通用任务注册。沙箱执行器会在前台结果与已结算进程句柄上标记 `BashSandboxInfo`。详见 `src/types.ts` 与 [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)。
+`stdin` 与普通 `env` 由同进程插件（hooks 桥接、原生插件）设置，用于向 hook 命令提供其 JSON payload 和 `CLAUDE_PROJECT_DIR`／`CLAUDE_PLUGIN_ROOT` 值。`dshEnv` 是受类型限制、仅允许受管 key 的独立受信任 overlay；导出的 `DSH_ENV_PREFIX` 是该 namespace、其 `DshEnvironmentKey` 模板类型、执行器清理、注册表验证、派生内置名称与模型指引的单一真源。模型 bash 使用 `ctx.bashEnv` 收集的当前快照。实现会移除继承的受管 key，再在普通 `env` 之后合并 `dshEnv`，因此省略的当前事实不会回退到陈旧环境状态，`env` 条目也无法顶掉受管值。面向模型的工具不公开任何一个字段。这三者在已解析 spec 上仍然可选；缺失表示没有输入／overlay。详见 [bash-stdin-env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) 与 [会话环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
 
 ## 模型体验
 

packages/bash/bash/package.json

@@ -28,11 +28,13 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1",
     "@deepseek-ai/dsh-sandbox": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-subprocess": "workspace:^",
     "@deepseek-ai/dsh-sandbox": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }

packages/bash/bash/src/index.ts

@@ -43,7 +43,10 @@ declare module 'cordis' {
  *   failures settle as `killed` with the error on stderr.
  * - {@link BashProcess.readOutput} is incremental: consecutive reads never
  *   repeat output. Lossy reads report truncation and available spill files.
- * - Disposal kills all running background processes and awaits their exit.
+ * - A still-running background process is stopped and awaited when its
+ *   owning composition tears down. With the subprocess seam that
+ *   boundary is `ctx.subprocess` disposal, so a background process survives
+ *   an executor-only reload.
  */
 export abstract class BashExecutor extends Service {
   constructor(ctx: Context) {

packages/bash/bash/src/types.ts

@@ -1,19 +1,17 @@
 /**
  * Execution types for the bash executor seam. Background task semantics belong
- * to `@deepseek-ai/dsh-tasks`; this seam exposes only process handles.
+ * to `@deepseek-ai/dsh-tasks`; this seam exposes only process handles. The
+ * managed-environment and captured-output vocabulary is owned by the
+ * subprocess seam and re-exported here so bash consumers keep one import
+ * root.
  * @module dsh-bash/types
  */
 
 import type { SandboxEnforcement, SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import type { CollectedOutput, DshEnvironment } from '@deepseek-ai/dsh-subprocess'
 
-/** Namespace prefix reserved for DeepSeek Harness-managed child environment facts. */
-export const DSH_ENV_PREFIX = 'DSH_' as const
-
-/** One environment key inside the managed {@link DSH_ENV_PREFIX} namespace. */
-export type DshEnvironmentKey = `${typeof DSH_ENV_PREFIX}${string}`
-
-/** Trusted DeepSeek Harness variables for one bash execution. */
-export type DshEnvironment = Readonly<Record<DshEnvironmentKey, string>>
+export { DSH_ENV_PREFIX } from '@deepseek-ai/dsh-subprocess'
+export type { CollectedOutput, DshEnvironment, DshEnvironmentKey } from '@deepseek-ai/dsh-subprocess'
 
 /**
  * Sandbox facts for one run, present iff a sandboxing executor handled it.
@@ -62,17 +60,18 @@ export interface BashExecRequest {
   stdin?: string | undefined
   /**
    * Ordinary environment entries for the command, merged after the credential
-   * scrub. `DSH_*` is reserved for {@link dshEnv} and implementations reject it
-   * here. Set by in-process plugins (the hooks bridges set
-   * `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, …); the model-facing bash tool
-   * does not expose it as a parameter.
+   * scrub. Managed facts belong in {@link dshEnv}, which merges after this
+   * map, so an entry here can never displace one. Set by in-process plugins
+   * (the hooks bridges set `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, …); the
+   * model-facing bash tool does not expose it as a parameter.
    */
   env?: Record<string, string> | undefined
   /**
-   * Harness-owned `DSH_*` variables for this execution. Executors discard
-   * ambient `DSH_*` entries before merging this snapshot, so an unavailable
-   * current fact cannot inherit a stale value from the harness process, and
-   * reject non-`DSH_*` names supplied through this managed channel.
+   * Harness-owned `DSH_*` variables for this execution (typed to managed
+   * keys). Executors discard ambient `DSH_*` entries before merging this
+   * snapshot last, so an unavailable current fact cannot inherit a stale
+   * value from the harness process and a caller {@link env} entry cannot
+   * displace a managed one.
    */
   dshEnv?: DshEnvironment | undefined
   /** Fully resolved per-call sandbox policy; sandboxing executors default it. */
@@ -99,27 +98,17 @@ export interface BashExecSpec {
   stdin?: string | undefined
   /**
    * Ordinary environment entries carried through from
-   * {@link BashExecRequest.env}. `DSH_*` remains reserved for {@link dshEnv}.
+   * {@link BashExecRequest.env}; {@link dshEnv} still merges after them.
    * OPTIONAL on the spec for the same reason as `stdin`: absent means no
    * ordinary extra environment.
    */
   env?: Record<string, string> | undefined
-  /** Managed `DSH_*` snapshot; implementations reject ordinary names. */
+  /** Managed `DSH_*` snapshot (typed to managed keys); merges after {@link env}. */
   dshEnv?: DshEnvironment | undefined
   /** Resolved sandbox policy; ignored by executors that do not confine. */
   sandboxPolicy: SandboxExecutionPolicy | undefined
 }
 
-/** One captured stream: the (possibly truncated) text plus recovery info. */
-export interface CollectedOutput {
-  /** Collected text — the TAIL of the stream when truncated. */
-  text: string
-  /** True when bytes were dropped from `text`. */
-  truncated: boolean
-  /** Path to a file holding the COMPLETE stream, when truncated and available. */
-  spillPath?: string
-}
-
 /** The outcome of one completed (or killed) foreground run. */
 export interface BashRunResult {
   /** Exit code; null when the process died from a signal. */
@@ -165,8 +154,9 @@ export interface BashProcessRead {
 
 /**
  * A background process handle returned by {@link BashExecutor.start}. It is the
- * only access path; buffered output remains readable after exit. Executor
- * disposal kills running processes and awaits {@link done}.
+ * only access path; buffered output remains readable after exit. Composition
+ * teardown (the subprocess service's disposal) kills running processes and
+ * awaits {@link done}; an executor-only reload leaves them running.
  */
 export interface BashProcess {
   /** Process lifecycle state (settled exactly once). */

packages/bash/bash/tsconfig.json

@@ -14,6 +14,9 @@
     {
       "path": "../../../vendor/cordis"
     },
+    {
+      "path": "../../subprocess/subprocess"
+    },
     {
       "path": "../../sandbox/sandbox"
     },

packages/bash/tool-bash/package.json

@@ -52,6 +52,7 @@
     "@deepseek-ai/dsh-bash-local": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
     "@deepseek-ai/dsh-paths": "workspace:^",
     "@deepseek-ai/dsh-sandbox": "workspace:^",
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
@@ -60,6 +61,7 @@
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-tasks": "workspace:^",
+    "@deepseek-ai/dsh-tasks-local": "workspace:^",
     "@deepseek-ai/dsh-tool-tasks": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/dsh-user-approval": "workspace:^",

packages/bash/tool-bash/src/index.ts

@@ -535,7 +535,7 @@ export function apply(ctx: Context, config: Config = {}): void {
         if (tasks === undefined) {
           throw new Error('background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks')
         }
-        // The caller owns cancellation until TaskService commits detached ownership.
+        // The caller owns cancellation until ctx.tasks commits detached ownership.
         if (exec.signal.aborted) {
           const error = new HarnessError('tool call aborted', TOOL_ABORTED)
           error.name = 'AbortError'

packages/bash/tool-bash/tests/integration.spec.ts

@@ -8,9 +8,10 @@ import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
-import TaskService from '@deepseek-ai/dsh-tasks'
+import LocalTaskService from '@deepseek-ai/dsh-tasks-local'
 import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
 import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
 
@@ -27,8 +28,9 @@ async function harness(adapter: MockAdapter, sessionRoot?: string, dshHome?: str
     await ctx.plugin(SessionPersistenceJsonl, { root: sessionRoot, compression: 'none' })
   }
   await ctx.plugin(AgentLoop, { agents: [] })
-  await ctx.plugin(TaskService)
+  await ctx.plugin(LocalTaskService)
   await ctx.plugin(ToolTasks)
+  await ctx.plugin(LocalSubprocessService)
   await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000 })
   await ctx.plugin(ToolBash, dshHome === undefined ? {} : { dshHome })
   ctx.llm.registerAdapter(['mock'], adapter)
@@ -169,7 +171,7 @@ describe('bash tool through the agent loop', () => {
   })
 
   it('background: start ack → completion notice as user/message → task_output collects it', async () => {
-    // The task id is deterministic (a fresh TaskService counts per kind from 1),
+    // The task id is deterministic (a fresh LocalTaskService counts per kind from 1),
     // so the script can name `bash-1` without threading a generated id.
     const adapter = new MockAdapter([
       toolCallResponse('call-1', 'bash', { command: 'echo bg-ok', description: 'test command', run_in_background: true }),

packages/bash/tool-bash/tests/tools.spec.ts

@@ -12,11 +12,12 @@ import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
-import TaskService from '@deepseek-ai/dsh-tasks'
+import LocalTaskService from '@deepseek-ai/dsh-tasks-local'
 import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
 import ApprovalService from '@deepseek-ai/dsh-user-approval'
 import type { ApprovalOutcome } from '@deepseek-ai/dsh-user-approval'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
 import { processOutcome } from '../src/background.ts'
@@ -32,8 +33,9 @@ async function setup() {
   await ctx.plugin(SystemPrompt)
   await ctx.plugin(ToolRegistry)
   await ctx.plugin(AgentRegistry)
+  await ctx.plugin(LocalSubprocessService)
+  ;(ctx.subprocess as LocalSubprocessService).internals = { spillDir }
   await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, graceMs: 200 })
-  ;(ctx.bash as LocalBashExecutor).internals = { spillDir }
   await ctx.plugin(ToolBash)
   return ctx
 }
@@ -44,10 +46,11 @@ async function setupWithTasks() {
   await ctx.plugin(SystemPrompt)
   await ctx.plugin(ToolRegistry)
   await ctx.plugin(AgentRegistry)
-  await ctx.plugin(TaskService)
+  await ctx.plugin(LocalTaskService)
   await ctx.plugin(ToolTasks)
+  await ctx.plugin(LocalSubprocessService)
+  ;(ctx.subprocess as LocalSubprocessService).internals = { spillDir }
   await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, graceMs: 200 })
-  ;(ctx.bash as LocalBashExecutor).internals = { spillDir }
   await ctx.plugin(ToolBash)
   return ctx
 }
@@ -180,7 +183,7 @@ async function setupSandboxed(withApproval = false) {
   await ctx.plugin(SystemPrompt)
   await ctx.plugin(ToolRegistry)
   await ctx.plugin(AgentRegistry)
-  await ctx.plugin(TaskService)
+  await ctx.plugin(LocalTaskService)
   await ctx.plugin(ToolTasks)
   await ctx.plugin(SandboxPolicyService, {})
   await ctx.plugin(RecordingSandboxExecutor)
@@ -275,8 +278,9 @@ describe('bash tool', () => {
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
+    await ctx.plugin(LocalSubprocessService)
+    ;(ctx.subprocess as LocalSubprocessService).internals = { spillDir }
     await ctx.plugin(LocalBashExecutor, { maxOutputBytes: 100, graceMs: 200 })
-    ;(ctx.bash as LocalBashExecutor).internals = { spillDir }
     await ctx.plugin(ToolBash)
     const result = await call(ctx, 'bash', { command: 'for i in $(seq 1 100); do printf "line-%04d\\n" $i; done', description: 'test command' })
     expect(text(result)).toContain('[output truncated; full output: ')
@@ -383,6 +387,7 @@ describe('bash tool', () => {
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
+    await ctx.plugin(LocalSubprocessService)
     await ctx.plugin(LocalBashExecutor, {})
     const fiber = await ctx.plugin(ToolBash)
     expect(ctx.tools.schemas()).toHaveLength(1)
@@ -400,6 +405,7 @@ describe('bash tool', () => {
     // inject: ['tools', 'bash'] keeps the plugin pending until bash exists.
     await ctx.plugin(ToolBash)
     expect(ctx.tools.schemas()).toHaveLength(0)
+    await ctx.plugin(LocalSubprocessService)
     await ctx.plugin(LocalBashExecutor, {})
     await new Promise(resolve => setTimeout(resolve, 0))
     expect(ctx.tools.schemas()).toHaveLength(1)
@@ -411,6 +417,7 @@ describe('bash tool', () => {
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
+    await ctx.plugin(LocalSubprocessService)
     await ctx.plugin(LocalBashExecutor, {})
     ToolBash.apply(ctx, {})
     const schema = ctx.tools.schemas()[0]!
@@ -472,7 +479,7 @@ describe('background execution through the task runtime', () => {
   })
 
   it('fails loud when the task runtime is not loaded', async () => {
-    const ctx = await setup() // no TaskService / ToolTasks
+    const ctx = await setup() // no LocalTaskService / ToolTasks
     const result = await call(ctx, 'bash', { command: 'sleep 60', description: 'test command', run_in_background: true })
     expect(result.isError).toBe(true)
     expect(text(result)).toContain('background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks')
@@ -483,7 +490,7 @@ describe('background execution through the task runtime', () => {
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(AgentRegistry)
-    await ctx.plugin(TaskService)
+    await ctx.plugin(LocalTaskService)
     await ctx.plugin(ToolTasks)
     await ctx.plugin(CountingStartExecutor)
     await ctx.plugin(ToolBash)
@@ -511,7 +518,7 @@ describe('background execution through the task runtime', () => {
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(AgentRegistry)
-    await ctx.plugin(TaskService)
+    await ctx.plugin(LocalTaskService)
     await ctx.plugin(CountingStartExecutor)
     await ctx.plugin(ToolBash)
 
@@ -526,6 +533,7 @@ describe('background execution through the task runtime', () => {
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
+    await ctx.plugin(LocalSubprocessService)
     await ctx.plugin(LocalBashExecutor, {})
     await ctx.plugin(ToolBash, { enableRunInBackground: false })
 
@@ -1073,7 +1081,7 @@ describe('the model-facing bash tool builds its request from named args only (no
       await ctx.plugin(SessionStore)
       await ctx.plugin(SessionPersistenceJsonl, { root: join(spillDir, 'jsonl') })
     }
-    await ctx.plugin(TaskService)
+    await ctx.plugin(LocalTaskService)
     await ctx.plugin(ToolTasks)
     await ctx.plugin(RecordingBashExecutor)
     await ctx.plugin(ToolBash, { dshHome: recordingDshHome })

packages/client/connection/src/client/api.ts

@@ -9,6 +9,7 @@ export type {
   ApiProxy, SessionsApi, SessionSummary, HostApi, EventsApi, MuxFrame, HostFrame,
   ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, ToolEventView,
   WorkspaceApi, WorkspaceId, WorkspaceView,
+  CommandsApi, CommandDescriptor, CommandExecuteResult, SkillsApi, SkillEntry,
 } from '@deepseek-ai/dsh-host-apiproxy/api'
 export type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools/presentation'
 export type {

packages/client/connection/src/client/fixture.ts

@@ -6,7 +6,7 @@
 // approval/question requests exercise replay and composer takeover with stable rpcIds.
 
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
-import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
+import type { SessionEvent, SessionId, TodoItem } from '@deepseek-ai/dsh-session/types'
 import type {
   ApiProxy, ClientRequest, ClientResponse, HistoryEntry, HostFrame, MuxFrame, RpcReceipt,
   RpcRequest, RpcResponse, RpcResult, ServerRequest, ServerResponse, SessionSummary,
@@ -124,6 +124,65 @@ function buildAlphaLog(): SessionEvent[] {
   toolTurn(61, 'fx-write', '{"path":"notes/demo.txt","content":"hello fixture\\n"}', 'wrote notes/demo.txt')
   toolTurn(62, 'edit', '{"file_path":"notes/demo.txt","old_string":"hello","new_string":"hello fixture"}', '已编辑')
   toolTurn(63, 'write', '{"file_path":"notes/new-demo.txt","content":"hello fixture\\n"}', '已写入')
+  // Turn 64: one run_code turn with three logged sub-dispatches — the Code
+  // Mode acceptance surface (parent code row + nested native-identical rows,
+  // including an isError sub-call and a bash sub-call that must hit the same
+  // keyed registration a top-level bash row uses).
+  {
+    const turn = 64
+    const callId = `fx-call-${turn}`
+    const program = 'const listing = await tools.bash({ command: "ls notes", description: "List notes" })\n'
+      + 'const demo = await tools.read({ path: "notes/demo.txt" })\n'
+      + 'await tools.read({ path: "notes/missing.txt" }).catch(() => "tolerated")\n'
+      + 'return { listing, demo }'
+    const args = JSON.stringify({ code: program, description: 'Read the notes files and summarize' })
+    push({ type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } })
+    push({ type: 'user/message', surfaceOp: 'append', data: { content: text(`问题 ${turn}：run_code 样本。`), source: { kind: 'user' } } })
+    push({ type: 'step/start', data: { turn, step: 0 } })
+    push({
+      type: 'assistant/message', surfaceOp: 'append',
+      data: { turn, step: 0, content: [{ type: 'tool-call', id: callId, name: 'run_code', arguments: args } as ContentBlock], provenance: { provider: 'fixture', model: 'fx-1' } },
+    })
+    push({ type: 'tool/call', data: { turn, step: 0, callId, name: 'run_code', arguments: args } })
+    const dispatchPair = (n: number, name: string, dispatchArgs: Record<string, unknown>, resultText: string, isError = false): void => {
+      push({
+        type: 'tool/code-dispatch-start',
+        data: { parentCallId: callId, subCallId: `${callId}:code:${n}`, name, arguments: dispatchArgs },
+      })
+      push({
+        type: 'tool/code-dispatch',
+        data: {
+          parentCallId: callId, subCallId: `${callId}:code:${n}`, name,
+          arguments: dispatchArgs, isError, content: [{ type: 'text', text: resultText }],
+        },
+      })
+    }
+    dispatchPair(1, 'bash', { command: 'ls notes', description: 'List notes' }, 'demo.txt\nnew-demo.txt')
+    dispatchPair(2, 'read', { path: 'notes/demo.txt' }, 'hello fixture\n')
+    dispatchPair(3, 'read', { path: 'notes/missing.txt' }, 'Error: ENOENT: notes/missing.txt not found', true)
+    push({
+      type: 'tool/result', surfaceOp: 'append',
+      data: { turn, step: 0, callId, content: text('{"listing":"demo.txt\\nnew-demo.txt","demo":"hello fixture\\n"}'), isError: false },
+    })
+    push({ type: 'step/end', data: { turn, step: 0 } })
+    push({ type: 'turn/end', data: { turn, reason: { kind: 'completed' } } })
+  }
+  // Turn 65: todo_write sample — the TodoRow toolview in the flow plus the
+  // todo/write snapshot event feeding the TodoPanel plan strip.
+  const fixtureTodos = [
+    { content: '梳理需求', status: 'completed' },
+    { content: '实现 fixture 样本', status: 'in_progress' },
+    { content: '浏览器验收', status: 'pending' },
+  ]
+  const todoArgs = JSON.stringify({ todos: fixtureTodos })
+  toolTurn(65, 'todo_write', todoArgs, 'Updated todo list: 1 pending, 1 in progress, 1 completed.')
+  // The real tool appends the snapshot mid-execution — between tool/call and
+  // tool/result — so the fixture reproduces that exact ordering (the last
+  // toolTurn events run ... tool/call, tool/result, step/end, turn/end).
+  const callIndex = events.length - 4
+  const callTime = events[callIndex]?.time as number
+  events.splice(callIndex + 1, 0, { type: 'todo/write', time: callTime + 400, data: { todos: fixtureTodos } })
+  events.forEach((e, i) => { e.seq = i })
   return events as unknown as SessionEvent[]
 }
 
@@ -238,6 +297,15 @@ function pageOf(
   return { events, hasMore: start > 0 }
 }
 
+/** Current todo projection over the full log (host parallel: latest todo/write, last write wins). */
+function backscanTodos(log: readonly SessionEvent[]): TodoItem[] | undefined {
+  for (let i = log.length - 1; i >= 0; i--) {
+    const event = log[i]
+    if (event !== undefined && event.type === 'todo/write') return event.data.todos
+  }
+  return undefined
+}
+
 interface StreamConn<F> {
   push(envelope: RpcRequest<F>): void
 }
@@ -304,10 +372,11 @@ class FxInbox<F> implements StreamConn<F> {
  * @returns an ApiProxy backed entirely by in-memory state — no host process, no network.
  */
 export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
+  // The resident fixture sessions all carry history, so none of them is blank.
   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' },
+    { sessionId: sid('fx-alpha'), updatedAt: Date.now(), running: true, blank: false, cwd: '/tmp/fixture' },
+    { sessionId: sid('fx-beta'), updatedAt: Date.now() - 60_000, running: false, blank: false, parentSessionId: sid('fx-alpha'), cwd: '/tmp/fixture' },
+    { sessionId: sid('fx-gamma'), updatedAt: Date.now() - 120_000, running: false, blank: false, cwd: '/tmp/fixture' },
   ]
   const logs = new Map<SessionId, SessionEvent[]>([[sid('fx-alpha'), buildAlphaLog()]])
   const nextTurn = new Map<SessionId, number>([[sid('fx-alpha'), 60]])
@@ -384,6 +453,16 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
   }
 
   const summaryOf = (id: SessionId): SessionSummary | undefined => sessions.find(s => s.sessionId === id)
+  /** Shared session guard for sessionId-addressed catalog routes: the error
+   *  response when the session is unknown, undefined when it exists. */
+  const requireSession = (request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<never>> | undefined => {
+    if (summaryOf(request.payload.sessionId) !== undefined) return undefined
+    return err<{ sessionId: SessionId }, never>(request, {
+      code: 'session-not-found',
+      message: `no session ${request.payload.sessionId}`,
+      details: { sessionId: request.payload.sessionId },
+    })
+  }
   const setRunning = (id: SessionId, running: boolean): void => {
     const summary = summaryOf(id)
     if (summary === undefined || summary.running === running) return
@@ -539,12 +618,13 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
           }
         }
         const created: SessionSummary = {
-          sessionId: requestedId ?? sid(`fx-${nextSession++}`), updatedAt: Date.now(), running: false, cwd,
+          sessionId: requestedId ?? sid(`fx-${nextSession++}`), updatedAt: Date.now(), running: false, blank: true, cwd,
         }
         sessions.push(created)
         attachedSessions += 1
         const emitSession = (): void => {
-          emitHost({ type: 'host/session-added', sessionId: created.sessionId, cwd })
+          // Mirrors the host: the frame fires at creation, so blank is constantly true.
+          emitHost({ type: 'host/session-added', sessionId: created.sessionId, blank: true, cwd })
         }
         if (workspace !== undefined && options.failWorkspaceAttach) {
           emitSession()
@@ -564,12 +644,14 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
         const log = logs.get(request.payload.sessionId) ?? []
         // Snapshot at request time, deliver after the transit delay (mirrors a real host under latency).
         const page = pageOf(log, request.payload.beforeSeq, request.payload.maxMessages ?? 50)
+        // Tail page carries the session-level todo projection (host parallel: full-log backscan).
+        const todos = request.payload.beforeSeq === undefined ? backscanTodos(log) : undefined
         const doomed = failNextHistory
         failNextHistory = false
         const delay = historyDelayMs
         if (delay > 0) await new Promise(resolve => setTimeout(resolve, delay))
         if (doomed) throw new Error('fixture: simulated history transport failure')
-        return ok(request, page)
+        return ok(request, { ...page, ...todos === undefined ? {} : { todos } })
       },
       prompt: (request) => {
         const { sessionId: id, mode, content } = request.payload
@@ -585,6 +667,8 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
           })
         }
         summary.updatedAt = Date.now()
+        // First accepted prompt appends events: the summary stops being blank.
+        summary.blank = false
         const userText = content.map(b => (b.type === 'text' ? b.text : '')).join('')
         if (mode === 'steer' && replays.has(id)) {
           // Steering: insert a steering message into the current turn; the replay continues.
@@ -666,6 +750,20 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
         }
         return ok(request, { workspace: { ...workspace } })
       },
+      delete: (request) => {
+        const { workspaceId } = request.payload
+        const index = workspaces.findIndex(workspace => workspace.workspaceId === workspaceId)
+        if (index === -1) {
+          return err(request, {
+            code: 'workspace-not-found',
+            message: `no workspace ${workspaceId}`,
+            details: { workspaceId },
+          })
+        }
+        workspaces.splice(index, 1)
+        emitHost({ type: 'host/workspace-removed', workspaceId })
+        return ok(request, { deleted: true as const })
+      },
       insertSessionBefore: (request) => {
         const { workspaceId, sessionId, beforeSessionId } = request.payload
         const workspace = workspaces.find(w => w.workspaceId === workspaceId)
@@ -695,6 +793,52 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
         return ok(request, { workspace: { ...workspace } })
       },
     },
+    commands: {
+      // The catalog mirrors one session's effective view (every fixture
+      // session has an agent, like the real host).
+      list: (request) => {
+        const missing = requireSession(request)
+        if (missing !== undefined) return missing
+        return ok(request, {
+          commands: [
+            { name: 'compact', description: 'fixture：压缩当前会话上下文' },
+            { name: 'echo', description: 'fixture：回显参数', input: { hint: 'text to echo' } },
+            { name: 'goal-fixture', description: 'fixture：目标样本命令', input: { hint: '<objective>' } },
+          ],
+        })
+      },
+      execute: (request) => {
+        const missing = requireSession(request)
+        if (missing !== undefined) return missing
+        const line = request.payload.line.trim()
+        const match = /^\/(\S+)(?:\s+(.*))?$/.exec(line)
+        const name = match?.[1]
+        if (name === 'compact' || name === 'echo') {
+          return ok(request, {
+            matched: true as const,
+            result: { kind: 'success' as const, text: name === 'echo' ? (match?.[2] ?? '') : 'fixture：已压缩（假动作）' },
+          })
+        }
+        if (name === 'goal-fixture') {
+          return ok(request, {
+            matched: true as const,
+            result: { kind: 'success' as const, text: `fixture：goal 已设置（${request.payload.sessionId}）` },
+          })
+        }
+        return ok(request, { matched: false as const })
+      },
+    },
+    skills: {
+      list: (request) => {
+        const missing = requireSession(request)
+        if (missing !== undefined) return missing
+        return ok(request, {
+          skills: [
+            { name: 'fixture-demo', description: 'fixture 技能样本', whenToUse: '仅供 UI 目录渲染验收' },
+          ],
+        })
+      },
+    },
     events: {
       async *mux(_request, signal) {
         const conn = new FxInbox<MuxFrame>()
@@ -811,7 +955,12 @@ export class FixtureApiClient extends AbstractApiClient {
       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.delete': return this.api.workspace.delete(request)
       case 'workspace.insertSessionBefore': return this.api.workspace.insertSessionBefore(request)
+      case 'command.list': return this.api.commands.list(request)
+      // The in-memory execute never blocks, so a never-aborting signal is faithful here.
+      case 'command.execute': return this.api.commands.execute(request, new AbortController().signal)
+      case 'skill.list': return this.api.skills.list(request)
     }
   }
 

packages/client/connection/src/client/index.ts

@@ -14,6 +14,7 @@ export type {
   ApiProxy, SessionsApi, SessionSummary, HostApi, EventsApi, MuxFrame, HostFrame,
   ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, ToolEventView,
   ToolCallView, ToolResultView, WorkspaceApi, WorkspaceId, WorkspaceView,
+  CommandsApi, CommandDescriptor, CommandExecuteResult, SkillsApi, SkillEntry,
   RpcRequest, RpcResponse, RpcResult, RpcError, RpcErrorCode,
   ClientRequest, ServerResponse, ServerRequest, ClientResponse, RpcMessage, RpcReceipt,
   IApiClient, SessionId, SessionEvent, ContentBlock, StreamChunk,

packages/client/connection/tests/fake-api.ts

@@ -2,7 +2,8 @@
 // data source on a real clock; behavior tests need per-case responses and
 // deferred-controlled timing). Streams are hand pumps: pushMux/pushHost.
 import type {
-  HostFrame, IApiClient, MuxFrame, RpcRequest, RpcResponse, SessionId,
+  CommandDescriptor, CommandExecuteResult, HostFrame, IApiClient, MuxFrame,
+  RpcRequest, RpcResponse, SessionId, SkillEntry,
 } from '../src/client/api.ts'
 import { RpcId } from '../src/client/api.ts'
 
@@ -80,11 +81,30 @@ export class FakeApiClient implements IApiClient {
     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' },
     }))),
+    delete: (payload: unknown) => this.record('workspace.delete', payload, Promise.resolve(ok({ deleted: true as const }))),
     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' },
     }))),
   }
 
+  // Payloads stay `unknown` (lint-lane note above); response rows are the real
+  // wire shapes so cases can program catalogs and skill lists without casts.
+  onCommandList: (payload: unknown) => Promise<RpcResponse<{ commands: CommandDescriptor[] }>>
+    = () => Promise.resolve(ok({ commands: [] }))
+  onCommandExecute: (payload: unknown) => Promise<RpcResponse<{ matched: boolean; result?: CommandExecuteResult }>>
+    = () => Promise.resolve(ok({ matched: false }))
+  onSkillList: (payload: unknown) => Promise<RpcResponse<{ skills: SkillEntry[] }>>
+    = () => Promise.resolve(ok({ skills: [] }))
+
+  readonly commands: IApiClient['commands'] = {
+    list: (payload: unknown) => this.record('command.list', payload, this.onCommandList(payload)),
+    execute: (payload: unknown) => this.record('command.execute', payload, this.onCommandExecute(payload)),
+  }
+
+  readonly skills: IApiClient['skills'] = {
+    list: (payload: unknown) => this.record('skill.list', payload, this.onSkillList(payload)),
+  }
+
   /** When true, streams never fire onOpen (misbehaving-carrier material for the handshake timeout guard). */
   suppressStreamOpen = false
 

packages/client/connection/tests/fixture-commands.spec.ts

@@ -0,0 +1,92 @@
+/**
+ * Fixture commands/skills domains: contract-shape conformance for the two
+ * domains added to ApiProxy — rpcId echo, session-addressed catalogs, execute
+ * parse/dispatch, skill.list session resolution, and the FixtureApiClient
+ * dispatch rows.
+ */
+import { describe, expect, it } from 'vitest'
+import type { SessionId } from '../src/client/api.ts'
+import { RpcId } from '../src/client/api.ts'
+import type { RpcRequest } from '../src/client/api.ts'
+import { FixtureApiClient, createFixtureApi } from '../src/client/fixture.ts'
+
+const sid = (id: string): SessionId => id as SessionId
+let reqCount = 0
+const req = <P>(payload: P): RpcRequest<P> => ({ rpcId: RpcId(`t-${reqCount++}`), payload })
+const signal = new AbortController().signal
+
+describe('createFixtureApi commands/skills', () => {
+  it('serves the addressed session catalog with rpcId echo', async () => {
+    const api = createFixtureApi()
+    const request = req({ sessionId: sid('fx-alpha') })
+    const response = await api.commands.list(request)
+    expect(response.rpcId).toBe(request.rpcId)
+    if (!response.result.ok) throw new Error('list failed')
+    const commands = response.result.value.commands
+    expect(commands.map(c => c.name)).toEqual(['compact', 'echo', 'goal-fixture'])
+    // input hint rides only the commands declaring it.
+    const echo = commands.find(c => c.name === 'echo')
+    expect(echo?.input?.hint).toBeTruthy()
+    expect(commands.find(c => c.name === 'compact')?.input).toBeUndefined()
+  })
+
+  it('rejects a catalog request for an unknown session', async () => {
+    const api = createFixtureApi()
+    const response = await api.commands.list(req({ sessionId: sid('fx-nope') }))
+    expect(response.result).toMatchObject({ ok: false, error: { code: 'session-not-found' } })
+  })
+
+  it('executes a known command line and reports matched with a result', async () => {
+    const api = createFixtureApi()
+    const response = await api.commands.execute(req({ sessionId: sid('fx-alpha'), line: '/echo hello world' }), signal)
+    if (!response.result.ok) throw new Error('execute failed')
+    expect(response.result.value.matched).toBe(true)
+    expect(response.result.value.result).toEqual({ kind: 'success', text: 'hello world' })
+  })
+
+  it('addresses execute to the session (result text carries the id)', async () => {
+    const api = createFixtureApi()
+    const hit = await api.commands.execute(req({ sessionId: sid('fx-alpha'), line: '/goal-fixture ship' }), signal)
+    if (!hit.result.ok) throw new Error('execute failed')
+    expect(hit.result.value.matched).toBe(true)
+    expect(hit.result.value.result?.text).toContain('fx-alpha')
+
+    const missing = await api.commands.execute(req({ sessionId: sid('fx-nope'), line: '/goal-fixture ship' }), signal)
+    expect(missing.result).toMatchObject({ ok: false, error: { code: 'session-not-found' } })
+  })
+
+  it('falls to matched:false on unknown names and non-command lines', async () => {
+    const api = createFixtureApi()
+    for (const line of ['/nope', 'plain text', '/']) {
+      const response = await api.commands.execute(req({ sessionId: sid('fx-alpha'), line }), signal)
+      if (!response.result.ok) throw new Error('execute failed')
+      expect(response.result.value.matched).toBe(false)
+      expect(response.result.value.result).toBeUndefined()
+    }
+  })
+
+  it('serves the skill catalog for the addressed session and rejects unknown sessions', async () => {
+    const api = createFixtureApi()
+    const response = await api.skills.list(req({ sessionId: sid('fx-alpha') }))
+    if (!response.result.ok) throw new Error('skill list failed')
+    expect(response.result.value.skills[0]?.name).toBe('fixture-demo')
+
+    const missingSession = await api.skills.list(req({ sessionId: sid('fx-nope') }))
+    expect(missingSession.result).toMatchObject({ ok: false, error: { code: 'session-not-found' } })
+  })
+})
+
+describe('FixtureApiClient command/skill dispatch', () => {
+  it('routes the three method keys through the in-memory dispatch table', async () => {
+    const client = new FixtureApiClient()
+    const list = await client.commands.list({ sessionId: sid('fx-alpha') })
+    if (!list.result.ok) throw new Error('command.list failed')
+    expect(list.result.value.commands.length).toBeGreaterThan(0)
+    const executed = await client.commands.execute({ sessionId: sid('fx-alpha'), line: '/compact' })
+    if (!executed.result.ok) throw new Error('command.execute failed')
+    expect(executed.result.value.matched).toBe(true)
+    const skills = await client.skills.list({ sessionId: sid('fx-alpha') })
+    if (!skills.result.ok) throw new Error('skill.list failed')
+    expect(skills.result.value.skills.length).toBeGreaterThan(0)
+  })
+})

packages/client/connection/tests/fixture.spec.ts

@@ -71,6 +71,21 @@ describe('createFixtureApi', () => {
     expect(empty.result.value).toEqual({ events: [], hasMore: false })
   })
 
+  it('emits the todo/write snapshot at the real tool boundary: between tool/call and tool/result, timestamps monotonic', async () => {
+    const api = createFixtureApi()
+    const tail = await api.sessions.history(req({ sessionId: sid('fx-alpha'), maxMessages: 10 }))
+    if (!tail.result.ok) throw new Error('history failed')
+    const events = tail.result.value.events.map(e => e.event)
+    const todoAt = events.findIndex(e => e.type === 'todo/write')
+    expect(todoAt).toBeGreaterThan(0)
+    // Production ordering (the tool appends mid-execution): call → snapshot → result.
+    expect(events[todoAt - 1]?.type).toBe('tool/call')
+    expect(events[todoAt + 1]?.type).toBe('tool/result')
+    const times = events.slice(todoAt - 1, todoAt + 2).map(e => e.time)
+    expect(times[0]).toBeLessThanOrEqual(times[1] ?? 0)
+    expect(times[1]).toBeLessThanOrEqual(times[2] ?? 0)
+  })
+
   it('create adds a session and pushes host/session-added to open host streams', async () => {
     const api = createFixtureApi()
     const abort = new AbortController()
@@ -87,7 +102,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, cwd: '/tmp/fixture' }])
+    expect(seen).toEqual([{ type: 'host/session-added', sessionId: createdId, blank: true, 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)
@@ -365,6 +380,31 @@ describe('createFixtureApi', () => {
     expect(noop.result.value.workspace.updatedAt).toBe(before)
   })
 
+  it('workspace.delete removes only the Workspace row and emits the removal 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)
+        abort.abort()
+      }
+    })()
+    await new Promise(resolve => setTimeout(resolve, 10))
+    const missing = await api.workspace.delete(req({ workspaceId: 'fx-ws-void' as WorkspaceId }))
+    expect(missing.result).toMatchObject({ ok: false, error: { code: 'workspace-not-found' } })
+    const deleted = await api.workspace.delete(req({ workspaceId: 'fx-ws-fixture' as WorkspaceId }))
+    expect(deleted.result).toEqual({ ok: true, value: { deleted: true } })
+    await consuming
+    expect(seen).toEqual([{ type: 'host/workspace-removed', workspaceId: 'fx-ws-fixture' }])
+    const list = await api.workspace.list(req({}))
+    if (!list.result.ok) throw new Error('workspace list failed')
+    expect(list.result.value.items.some(workspace => workspace.workspaceId === 'fx-ws-fixture')).toBe(false)
+    const sessions = await api.sessions.list(req({}))
+    if (!sessions.result.ok) throw new Error('session list failed')
+    expect(sessions.result.value.items.map(session => session.sessionId)).toContain('fx-alpha')
+  })
+
   it('session.create({workspaceId}) lands on the account and unknown ids error', async () => {
     const api = createFixtureApi()
     const abort = new AbortController()
@@ -384,7 +424,7 @@ describe('createFixtureApi', () => {
     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[0]).toEqual({ type: 'host/session-added', sessionId: id, blank: true, cwd: '/tmp/fixture' })
     expect(seen[1]).toMatchObject({
       type: 'host/workspace-changed',
       workspace: { workspaceId: 'fx-ws-fixture', sessionIds: [id, 'fx-alpha', 'fx-beta', 'fx-gamma'] },
@@ -413,7 +453,7 @@ describe('createFixtureApi', () => {
     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 })
+    expect(frames[1]).toEqual({ type: 'host/session-added', sessionId: preallocated, blank: true, cwd: made.result.value.workspace.path })
 
     const retried = await api.sessions.create(req({
       workspaceId: made.result.value.workspace.workspaceId,

packages/client/locale/tests/language-row.spec.tsx

@@ -16,12 +16,12 @@ 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' })
+    { ids: [], byId: {}, current: undefined, phase: 'ready' })
   return bindSnapshotSelector(store)
 }
 function emptyWorkspaces() {
   const store = createSnapshotStore<WorkspaceListState>({
-    items: [], intent: undefined, state: 'idle', phase: 'ready', error: null,
+    items: [], state: 'idle', phase: 'ready', error: null,
     baselinesReady: true, recentWorkspaceId: undefined,
   })
   return bindSnapshotSelector(store)

packages/client/runtime/README.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write
-README.md: 5d44f666a12e747eb79535c48d87fcaff381d770
-README.zh.md: 16577c356ba79066c7c56ae07a266f4ec85fa2e9
+#   pnpm run verify-translation-pairing --write packages/client/runtime/README.md
+README.md: a434b2d5719de2f30a883ee6e0d26264b3c62f4e
+README.zh.md: a79fa99578e6bce4f0ff8e7c1f7538df8a436778

packages/client/runtime/README.md

@@ -2,17 +2,23 @@
 
 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.
+Client cordis boot and React-free object services: SlotsService wraps SlotCore and supplies renderer data sources; SessionsService owns Session objects, list/scope/history state; WorkspacesService depends on SessionsService and owns Workspace objects, list/actions, default-target derivation, and the New Session blank-reuse entry (`connectWorkspace`). The runtime fans the shared Host stream into both managers. Client sessions are always Host-born (Session+Agent+cwd in one `session.create`); the client holds no pre-entity session state — a session's Agent scope (the client mirror of host dsh-scope, keyed by the shared agent/session id) is born when its row enters the list mirror and dies with the prune. Contract: api-contracts v3 §4. `ConversationSnapshot` carries `todos` — the session's current todo projection: taken from the tail history page's full-log value (host-computed, independent of the page window), preserved across an older-page prepend, and overwritten by each live `todo/write` (last write wins). A tail response that omits the field means the log holds no `todo/write`, so the list resets to empty — a plan the log never kept (a write lost to a host crash) disappears on the next open or resync.
 
 ## 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.
+Workspace and Session lists have independent monotone `pending` → `ready` baseline phases and separate refresh activity/error state. Incremental upsert/removal frames and unary mutation echoes 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. Removed Workspace ids retain process-local tombstones so late changed frames cannot resurrect them; reconnect still takes `workspace.list` as the baseline. Workspace recency is derived only after both baselines are ready and never changes Workspace list order.
+
+`WorkspacesService.delete(workspaceId)` removes the registration from the client projection after the successful unary response; the matching `host/workspace-removed` frame is idempotent and synchronizes other tabs. Session state and the current Session selection are independent, so accounted Sessions immediately project under Ungrouped after their Workspace disappears.
 
 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
+## New Session and the blank mirror
 
-`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.
+`WorkspacesService.connectWorkspace(workspaceId)` resolves the session a New Session flow lands in: it reuses the workspace's existing blank session from the list mirror (`blank && cwd == workspace.path`) or calls `session.create({workspaceId})`, returning the session id for the caller to open. `SessionSummary.blank` mirrors the host's derived empty-log bit and only ever lowers on the client: seeded by `session.list` / the `host/session-added` frame, flipped false by the first ACCEPTED local `prompt()` (on the RPC success response — acceptance proves the user message is in the host log; a rejected first prompt keeps the session blank and reusable) and by any `running: true` status frame, re-aligned by every list re-pull. List surfaces hide blank rows; the store carries every row. `SessionsService.create` accepts an optional caller-preallocated SessionId and throws `SessionCreateError` (carrying `requestedSessionId`) on failure.
+
+## Code Mode sub-dispatch index
+
+`ConversationSnapshot.codeDispatches` groups a `run_code` call's sub-dispatches under their parent callId, in start order, using the native call-block shapes: a `tool/code-dispatch-start` event lands the `RunningToolCall` form (rows derive the running ring from the shape) and its `tool/code-dispatch` settlement replaces it in place with the `ToolResultNode` form, `callTime` carrying the paired start's time. A settle whose start fell outside the replay window appends directly with `callTime: null` (duration unknown — never a fabricated zero). Live mux frames and history replay build the identical index; sub-calls never join the surface `nodes` flow; per-parent array and map references are memo-stable across unrelated snapshot swaps.
 
 ## Session title projection
 
@@ -29,5 +35,5 @@ None; this package neither assembles nor sends a provider request.
 ## Known Limitations and Deferred Work
 
 - **`loader.unload` is a stub (throws not-implemented)** — the full chain (fiber dispose → registration cascade → style removal) lands with the HMR project.
-- **Scope teardown is stage-driven, single-occupant today** — the staged session follows `list.current` exactly (staging is the open signal: the event window opens ⟺ the session is on stage); a removed-while-staged session's scope survives frozen until the stage moves on, not until true observer count reaches zero. Resolution (`cell()`/`binding()`/`scope()`) is pure addressing, render-safe. The staged state can widen to a multi-pane list when concurrent panes land.
+- **Scope teardown is stage-driven, single-occupant today** — the staged session follows `list.current` exactly (staging is the open signal: the event window opens ⟺ the session is on stage); a removed-while-staged session's scope survives frozen until the stage moves on, not until true observer count reaches zero. Resolution (`provideInfo()`/`binding()`/`scope()`) is pure addressing, render-safe. The staged state can widen to a multi-pane list when concurrent panes land.
 - **Value imports of this package from plugin bundles must use the `/client` subpath** — the bare package name is not in the loader externals table and inlines a second module instance, whose private scope-tag Symbol never matches (the empty-state P0 postmortem).

packages/client/runtime/README.zh.md

@@ -2,17 +2,23 @@
 
 [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。
+客户端 cordis 启动与不依赖 React 的对象服务：SlotsService 包装 SlotCore 并提供 renderer 数据源；SessionsService 拥有 Session 对象、列表／scope／history 状态；WorkspacesService 依赖 SessionsService，拥有 Workspace 对象、列表／操作、默认目标派生，以及 New Session 空会话复用入口（`connectWorkspace`）。运行时把共享 Host 流分发给两个 manager。客户端 Session 一律由 Host 出生（一次 `session.create` 同瞬产出 Session+Agent+cwd）；客户端不持有任何实体化之前的会话状态——Agent scope（host dsh-scope 的客户端镜像，以 agent/session 共用 id 为键）在会话行进入列表镜像时出生，随 prune 死亡。契约：api-contracts v3 §4。`ConversationSnapshot` 携带 `todos`——会话当前的 todo 投影：取自尾页 history 携带的全量 log 值（host 计算，独立于分页窗口），跨往前翻页保留，并被每次实时 `todo/write` 覆盖（后写胜出）。尾页响应省略该字段即表示 log 中没有任何 `todo/write`，因此列表复位为空——log 从未留下的计划（写入因 host 崩溃丢失）会在下一次打开或 resync 时消失。
 
 ## Workspace 与 Session 列表
 
-Workspace 和 Session 列表各自具有单调的 `pending` → `ready` 基线阶段，也有各自的刷新活动／错误状态。列表请求期间到达的增量帧会在其响应之上回放。第一次成功的基线建立 Host 顺序；后续刷新更新行和成员关系，但不改变已经显示的标识之间的相对顺序。Workspace 新近程度只在两条基线都 ready 后派生，且绝不改变 Workspace 列表顺序。
+Workspace 和 Session 列表各自具有单调的 `pending` → `ready` 基线阶段，也有各自的刷新活动／错误状态。列表请求期间到达的增量更新／移除帧与一元变更回显会在其响应之上回放。第一次成功的基线建立 Host 顺序；后续刷新更新行和成员关系，但不改变已经显示的标识之间的相对顺序。已移除的 Workspace id 会保留进程本地删除标记，避免延迟到达的 changed 帧将其复活；重连仍以 `workspace.list` 作为基线。Workspace 新近程度只在两条基线都 ready 后派生，且绝不改变 Workspace 列表顺序。
+
+`WorkspacesService.delete(workspaceId)` 在一元响应成功后从客户端投影中移除注册记录；对应的 `host/workspace-removed` 帧具有幂等性，并负责同步其他标签页。Session 状态与当前 Session selection 相互独立，因此 Workspace 消失后，其已记账的 Session 会立即投影到 Ungrouped 下。
 
 SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸 observable；web-react 创建 hook。Workspace 业务状态不会进入 `SessionListState` 或配置项 store。
 
-## Session 创建失败
+## New Session 与 blank 镜像
 
-`SessionsService.create` 接受可选的、由调用方预先分配的 SessionId。失败时抛出 `SessionCreateError`：传输状态不确定后仍可取得 `requestedSessionId`；如果 Host 在附加失败前已经发布真实 Session，则会设置 `publishedSessionId`，此时 `workspace-attach-failed` 提供了证明。在 New Session 流程中，前端 Session 对象拥有其保留的提示词，并推动提示词完成附加与发送；部分发布的 Session 会保留同一对象和提示词，同时显示为 Ungrouped。
+`WorkspacesService.connectWorkspace(workspaceId)` 解析 New Session 流程最终落入的会话：先在列表镜像中复用该 workspace 的既有空会话（`blank && cwd == workspace.path`），未命中则调用 `session.create({workspaceId})`，返回会话 id 由调用方 open。`SessionSummary.blank` 镜像主机派生的空日志位，在客户端只降不升：由 `session.list`／`host/session-added` 帧播种，本地首次**受理成功**的 `prompt()`（RPC 成功响应时——受理即证明用户消息已入主机日志；首讯被拒则会话保持 blank、保持可复用）与任何 `running: true` 状态帧翻为 false，每次列表重拉重新对齐。列表表面隐藏 blank 行；store 保留全部行。`SessionsService.create` 接受可选的、由调用方预先分配的 SessionId，失败时抛出 `SessionCreateError`（携带 `requestedSessionId`）。
+
+## Code Mode 子调用索引
+
+`ConversationSnapshot.codeDispatches` 按父调用的 callId 和启动顺序，用原生调用块形状组织一个 `run_code` 调用的子调用：`tool/code-dispatch-start` 事件落成 `RunningToolCall` 形状（行组件从该形状推导运行中的转圈状态），其 `tool/code-dispatch` 完结事件原位替换为 `ToolResultNode` 形状，`callTime` 携带成对 start 事件的时间。start 落在回放窗口之外的完结事件则直接追加，`callTime: null`（耗时未知——绝不伪造零耗时）。live mux 帧与历史回放构建相同的索引；子调用永不进入 surface `nodes` 流；无关快照交换不会改变每个父调用对应的数组引用和映射引用，两者均保持 memo 稳定。
 
 ## Session 标题投影
 
@@ -29,5 +35,5 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 ## 已知限制与暂缓事项
 
 - **`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 列表。
+- **scope 拆卸由阶段驱动，目前只能有一个占用者**：已 staged 的 Session 精确跟随 `list.current`（staging 就是打开信号：事件窗口打开 ⟺ Session 位于 stage）；在 staged 状态下被移除的 Session，其 scope 会冻结保留，直到 stage 转向其他 Session，而非直到真实观察者数量降为零。解析（`provideInfo()`／`binding()`／`scope()`）只是纯寻址，可安全用于渲染。并发 pane 落地时，staged 状态可以扩展为多 pane 列表。
 - **插件组合包从该包执行值导入时必须使用 `/client` 子路径**：裸包名不在 loader external 表中，会内联第二个模块实例；其私有 scope-tag Symbol 永远无法匹配（空状态 P0 事故复盘）。

packages/client/runtime/src/client/agents/scope.ts

@@ -0,0 +1,70 @@
+/**
+ * Client Agent-scope primitive: mint a Cordis context tagged with the owning
+ * Agent's identity. The mechanism mirrors the host `dsh-scope` architecture
+ * (no-op plugin fiber + context tag + `Context.filter` routing predicate);
+ * the shape deliberately diverges: the filter lives on the actx itself
+ * instead of a separate carrier object, so scoped dispatch is plain cordis —
+ * `actx.bail(actx, event, payload)` / `actx.emit(actx, ...)` — with no
+ * wrapper. The host needs a detached carrier because its dispatch subject is
+ * the business Agent object; client scope events carry only ids, so the
+ * actx is the natural subject. The second divergence stands: the scope key
+ * is the branded `SessionId` (value compared), not an object identity — the
+ * agent and its session share one id (1:1, same axis; no separate AgentId
+ * brand), and a client scope's identity IS that wire id. Third divergence,
+ * deliberate: the client scopes the Agent IDENTITY, not a live Agent object
+ * — a cold session's host Agent is already disposed while its client actx
+ * stays alive for history viewing.
+ */
+import { Context as CordisContext } from 'cordis'
+import type { Context, Fiber } from 'cordis'
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+
+/** Context tag written by {@link createScope}. */
+const kScope = Symbol('dsh.client.scope')
+
+/** A minted Agent scope and its disposal boundary. */
+export interface AgentScopeHandle {
+  /**
+   * Tagged context: scope-owned registrations and scoped dispatch both go
+   * through it (passing it as the dispatch subject routes to this agent's
+   * tagged listeners plus every untagged one).
+   */
+  ctx: Context
+  /** Backing fiber (dispose tears down every scope-owned registration). */
+  fiber: Fiber
+}
+
+/** Shared no-op plugin backing each Agent scope fiber. */
+function agentScope(): void {}
+
+/**
+ * Mint an Agent scope under `ctx`: a no-op plugin fiber whose context
+ * carries the agent tag and the dispatch filter — untagged listeners are
+ * admitted globally, tagged listeners only for a matching agent.
+ * Registrations through the returned ctx dispose with the fiber.
+ * @param ctx - client root context the scope fiber mounts under.
+ * @param key - owning agent identity (the routing tag; agent id === session id).
+ * @returns the tagged context and its backing fiber.
+ */
+export function createScope(ctx: Context, key: SessionId): AgentScopeHandle {
+  const fiber = ctx.plugin(agentScope)
+  return {
+    fiber,
+    ctx: fiber.ctx.extend({
+      [kScope]: key,
+      [CordisContext.filter](listenerCtx: Context): boolean {
+        const tag = scopeOf(listenerCtx)
+        return tag === undefined || tag === key
+      },
+    }),
+  }
+}
+
+/**
+ * Read the nearest agent tag inherited by a context.
+ * @param ctx - any client context.
+ * @returns its agent identity (the session id), or undefined for root contexts.
+ */
+export function scopeOf(ctx: Context): SessionId | undefined {
+  return (ctx as Context & { [kScope]?: SessionId })[kScope]
+}

packages/client/runtime/src/client/index.ts

@@ -1,7 +1,7 @@
 /** 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 type { MaybeSnapshotSelectorHook, 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'
@@ -11,10 +11,14 @@ import type { ConversationSnapshot, RunningToolCall, ToolResultNode } from './se
 export { SlotsService } from './slots.ts'
 export type { RootOwnerProps } from './slots.ts'
 export { SessionCreateError, SessionsService, scopeOf, workspaceTitleOf } from './sessions/service.ts'
+export { createScope } from './agents/scope.ts'
+export type { AgentScopeHandle } from './agents/scope.ts'
 export { WorkspacesService } from './workspaces/service.ts'
 export type { Session } from './sessions/session.ts'
-export type { SessionBinding, SessionListState, SessionSummary } from './sessions/service.ts'
-export type { SessionIntentListSnapshot, SessionListPhase } from './sessions/manager.ts'
+export type {
+  SessionBinding, SessionListState, SessionProvideContribution, SessionProvideDescriptor, SessionSummary,
+} from './sessions/service.ts'
+export type { 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'
@@ -24,9 +28,9 @@ export type {
   EngineStoreHandle, EngineStoreInstance, ObservableSnapshot, SnapshotStore,
 } from './contract/store.ts'
 export type {
-  AssistantBlock, AssistantMessageNode, ComposerPhase, ContextMessageNode, ConversationNode,
-  ConversationSnapshot, PendingPrompt, RunningToolCall, SessionIntentSnapshot, SessionIntentTarget,
-  SteeringMessageNode, ToolResultNode, UnknownSurfaceNode, UserMessageNode,
+  AssistantBlock, AssistantMessageNode, CodeSubCall, ComposerPhase, ContextMessageNode, ConversationNode,
+  ConversationSnapshot, QueuedMessage, RunningToolCall,
+  SteeringMessageNode, TodoItem, ToolResultNode, UnknownSurfaceNode, UserMessageNode,
 } from './sessions/conversation.ts'
 export { PendingWait } from './sessions/pending.ts'
 export type { PendingInteraction, PendingKind, PendingPayloads } from './sessions/pending.ts'
@@ -56,6 +60,12 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
     /** The framework-resolved session id (owners never pass it). */
     sessionId: SessionId
   }
+  /** Standard kit for slots that remain mounted while current session changes. */
+  interface SessionMaybeStandardProps {
+    useSession: MaybeSnapshotSelectorHook<ConversationSnapshot>
+    /** Current session id; absent in the no-session state. */
+    sessionId: SessionId | undefined
+  }
   /** Props injected into every global slot component. */
   interface GlobalStandardProps {
     useSessions: SnapshotSelectorHook<SessionListState>
@@ -72,6 +82,20 @@ declare module 'cordis' {
      * @param key - the mutated SlotMap key.
      */
     'slots/changed'(key: string): void
+    /**
+     * The host command registry changed (host/commands-changed passthrough).
+     * Pure invalidation signal: subscribers refetch `command.list` in the
+     * background rather than diffing.
+     * @mode emit
+     */
+    'commands/changed'(): void
+    /**
+     * A connection generation was (re-)established. Wire-derived caches must
+     * treat their state as stale and repull (commands directory; the queue
+     * mirrors reset themselves through the session resync path).
+     * @mode emit
+     */
+    'connection/reset'(): void
   }
   interface Context {
     slots: import('./slots.ts').SlotsService
@@ -91,15 +115,23 @@ export function apply(ctx: Context): void {
   const connection = ctx.get('connection') as ConnectionHandle
   const sessions = new SessionsService(ctx, connection.api)
   const workspaces = new WorkspacesService(ctx, connection.api, sessions)
+  ctx.effect(
+    () => workspaces.startInitialSelection(),
+    'runtime: initial Workspace selection',
+  )
   const loop = connection.start({
     onMuxEnvelope: (envelope) => { sessions.handleMuxEnvelope(envelope) },
     onHostEnvelope: (envelope) => {
       sessions.handleHostEnvelope(envelope)
       workspaces.handleHostEnvelope(envelope)
+      // Typed-event bridge: the session layer ignores registry frames (no
+      // session routing); consumers (command directory caches) subscribe on ctx.
+      if (envelope.payload.type === 'host/commands-changed') ctx.emit('commands/changed')
     },
     onConnected: () => {
       sessions.handleConnected()
       workspaces.handleConnected()
+      ctx.emit('connection/reset')
     },
   })
   ctx.effect(() => () => { loop.stop() }, 'runtime: connection stream loop')

packages/client/runtime/src/client/sessions/conversation.ts

@@ -4,11 +4,14 @@
 // string here (narrow to real brands when convenient).
 
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { TodoItem } from '@deepseek-ai/dsh-session/types'
 import type {
-  RpcError, SessionId, ToolCallView, ToolResultView, WorkspaceId,
+  RpcError, SessionId, ToolCallView, ToolResultView,
 } from '@deepseek-ai/dsh-client-connection/client'
 import type { PendingInteraction } from './pending.ts'
 
+export type { TodoItem }
+
 /** Assistant content blocks sorted by what the UI cares about
  *  (text body / collapsible reasoning / tool-call card head / other fallback). */
 export type AssistantBlock =
@@ -127,6 +130,21 @@ export type ConversationNode =
   | ToolResultNode
   | UnknownSurfaceNode
 
+/**
+ * One `run_code` sub-dispatch materialized in the native call-block shapes so
+ * every consumer (tool rows, details panel) renders it through the exact
+ * components that render a native call: a started-but-unsettled sub-call is a
+ * {@link RunningToolCall} (rows derive the running state from the shape,
+ * exactly as for native calls) and its `tool/code-dispatch` settlement
+ * replaces it in place with the {@link ToolResultNode} form. Never part of
+ * the surface `nodes` flow — sub-calls live under their parent via
+ * {@link ConversationSnapshot.codeDispatches}. `callId` is the deterministic
+ * sub-call id (`<parent>:code:<n>`); the call side carries the sub-tool name
+ * and its JSON-stringified logged arguments; `content`/`isError` are the
+ * settled sub-call's complete logged outcome.
+ */
+export type CodeSubCall = RunningToolCall | ToolResultNode
+
 /** In-flight tool card material: tool/call seen, tool/result not yet. */
 export interface RunningToolCall {
   callId: string
@@ -141,6 +159,12 @@ export interface RunningToolCall {
 }
 
 
+/** One queued-message row mirrored from `session/queued` frames (key: the enqueueing prompt's rpcId when wire-sourced). */
+export interface QueuedMessage {
+  readonly key: string
+  readonly preview: string
+}
+
 /** In-progress assistant output (chunk accumulator product). */
 export interface PartialAssistant {
   turn: number
@@ -179,30 +203,6 @@ export interface PromptError {
   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
@@ -212,7 +212,16 @@ export interface ConversationSnapshot {
   foldDegraded: boolean
   partial: PartialAssistant | null
   runningCalls: readonly RunningToolCall[]
+  /**
+   * `run_code` sub-dispatches grouped under their parent callId, in dispatch
+   * order. Populated from in-window `tool/code-dispatch` events (live and
+   * replay identically); the per-parent array reference is stable across
+   * unrelated snapshot swaps (memo premise, same regime as `nodes`).
+   */
+  codeDispatches: ReadonlyMap<string, readonly CodeSubCall[]>
   pending: readonly PendingInteraction[]
+  /** Read-only inbox mirror (session/queued frames + mux-open baseline; cleared by the leave-running flip). */
+  queue: readonly QueuedMessage[]
   running: boolean
   /** Input-area shape (see {@link ComposerPhase}); derived here, switched on by consumers. */
   composerPhase: ComposerPhase
@@ -223,9 +232,19 @@ 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
+  /**
+   * Whether this session still has an empty log (no user message yet).
+   * Mirrors the host summary's derived blank bit: seeded from `session.list`
+   * / the `host/session-added` frame, flipped false by the first ACCEPTED
+   * prompt locally (on the RPC success response — acceptance proves the
+   * user message is in the host log; a rejected first prompt keeps the
+   * session blank and reusable) and by any `running: true` status remotely,
+   * and re-aligned by every list re-pull (the summary stays authoritative).
+   * Blank sessions are hidden from session lists and reused by New Session.
+   */
+  blank: boolean
   lastAgentError: string | null
+  /** Current whole-list `todo/write` projection — the tail page's full-log value, then each live
+   *  write (last write wins); empty = the log holds no plan. */
+  todos: readonly TodoItem[]
 }

packages/client/runtime/src/client/sessions/lineage.ts

@@ -15,6 +15,8 @@ export interface SessionListEntry {
   title?: string
   updatedAt: number
   running: boolean
+  /** Empty-log bit mirrored from the summary; lists hide blank sessions (filtering stays with the consumer). */
+  blank: boolean
   parentSessionId?: SessionId
   cwd?: string
   /** Lineage indent depth: root = 0; the UI just multiplies by the indent width. */

packages/client/runtime/src/client/sessions/manager.ts

@@ -11,7 +11,6 @@ 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:
@@ -23,19 +22,11 @@ import type { SessionIntentSnapshot, SessionIntentTarget } from './conversation.
  */
 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. */
+  /** Selected Session id (validated against items; masked to undefined while its session is off the list). */
   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
@@ -46,6 +37,8 @@ type SessionListMutation =
   | { kind: 'upsert'; summary: SessionSummary }
   | { kind: 'remove'; sessionId: SessionId }
   | { kind: 'status'; sessionId: SessionId; running: boolean }
+  /** Local first-send flip: the sender clears blank without waiting for a host frame. */
+  | { kind: 'engaged'; sessionId: SessionId }
 
 /** Per-session cap for pre-instantiation approval/question buffering (low-frequency frames; a few dozen covers any real backlog). */
 const PENDING_BUFFER_CAP = 32
@@ -76,8 +69,6 @@ export class SessionManager {
   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
@@ -101,87 +92,38 @@ export class SessionManager {
     this.listSnapshotCache = this.buildListSnapshot()
   }
 
-  // ---- Selection and client-local intents ----
+  // ---- Selection ----
 
   /**
-   * Select a real Session and discard the unmaterialized intent.
-   * @param sessionId - listed real Session id.
+   * Select a listed Session.
+   * @param sessionId - listed 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. */
+  /** Clear the selection (the layout falls to the no-session view state). */
   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 {
-    const session = this.getIntent()
-    if (session === undefined) return
-    session.updatePendingPrompt(text)
-    // The intent watch defers via markDirty, but the hero composer reads this
-    // prompt from the LIST snapshot as a controlled value: it must flush in
-    // the same tick as onChange (see Notifier.notifyNow) or React rolls the
-    // textarea back and IME composition breaks.
-    this.notifier.notifyNow()
-  }
-
-  private discardIntent(): void {
-    const session = this.getIntent()
-    this.intentSessionId = undefined
-    this.stopIntentWatch?.()
-    this.stopIntentWatch = undefined
-    session?.abandonIntent()
-  }
-
   // ---- Instance management ----
 
+  /**
+   * Drop a session instance (scope-prune companion, decision 12: instance
+   * and scope share one lifecycle). The host session log is the durable
+   * truth — a later get() lazily rebuilds and open() backfills history.
+   * @param sessionId - the session to drop.
+   */
+  drop(sessionId: SessionId): void {
+    this.sessions.delete(sessionId)
+  }
+
   /**
    * Lazy build: return the existing instance or construct one (no auto-open —
    * open is triggered by the container's select callback).
@@ -193,31 +135,33 @@ export class SessionManager {
     if (session === undefined) {
       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)
-      if (summary !== undefined) session.handleRunning(summary.running)
-      // Replay approval/question frames buffered before instantiation (rpcId verbatim, same semantics as the subscribed baseline replay).
+      // Replay approval/question/queued frames buffered before instantiation (rpcId
+      // verbatim, same semantics as the subscribed baseline replay). Replay happens
+      // BEFORE the running-bit sync: a not-running summary must sweep replayed queue
+      // rows the same way a live status flip would (their retirement events dropped
+      // while the session was uninstantiated).
       const buffered = this.pendingBuffers.get(sessionId)
       if (buffered !== undefined) {
         this.pendingBuffers.delete(sessionId)
         for (const envelope of buffered) session.handleMuxEnvelope(envelope.rpcId, envelope.payload)
       }
+      // Sync the running and blank bits from the list snapshot into the new
+      // instance (consistency when the list precedes open).
+      const summary = this.summaries.find(s => s.sessionId === sessionId)
+      if (summary !== undefined) {
+        session.handleBlank(summary.blank)
+        session.handleRunning(summary.running)
+      }
     }
     return session
   }
 
-  private createSession(
-    sessionId: SessionId,
-    intent?: { target: SessionIntentTarget; prompt: string },
-  ): Session {
+  private createSession(sessionId: SessionId): 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 },
-        })
+      // The sender's local first-send flip mirrors into the list row so the
+      // session surfaces (lists filter on blank) before any host frame lands.
+      onEngaged: (engaged) => {
+        this.recordMutation({ kind: 'engaged', sessionId: engaged.sessionId })
       },
     })
   }
@@ -244,8 +188,13 @@ export class SessionManager {
           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)
+          // Push running/blank bits down to instantiated Sessions (the list is the authoritative summary source).
+          for (const s of this.summaries) {
+            const session = this.sessions.get(s.sessionId)
+            if (session === undefined) continue
+            session.handleBlank(s.blank)
+            session.handleRunning(s.running)
+          }
         } else {
           this.listState = 'error'
           this.listError = result.error
@@ -266,7 +215,8 @@ export class SessionManager {
 
   /**
    * Contract session.create; on success merge into summaries immediately (no
-   * wait for the next refresh).
+   * wait for the next refresh). A created session is blank by definition
+   * (entity birth precedes the first message).
    * @param opts - target workspace or working directory, plus an optional caller-owned id.
    * @returns the create result.
    */
@@ -274,16 +224,14 @@ export class SessionManager {
     opts: { workspaceId?: WorkspaceId; cwd?: string; sessionId?: SessionId } = {},
   ): Promise<RpcResult<{ sessionId: SessionId }>> {
     try {
+      const shared = opts.sessionId === undefined ? {} : { sessionId: opts.sessionId }
       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 }),
-        }
+        ? { workspaceId: opts.workspaceId, ...shared }
+        : { ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }), ...shared }
       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,
+          sessionId: result.value.sessionId, updatedAt: Date.now(), running: false, blank: true,
           ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
         } })
       } else {
@@ -296,6 +244,7 @@ export class SessionManager {
             sessionId: publishedSessionId,
             updatedAt: Date.now(),
             running: false,
+            blank: true,
           } })
         }
       }
@@ -370,16 +319,31 @@ export class SessionManager {
         this.titleSnapshots.delete(frame.sessionId)
         this.notifier.markDirty()
       }
+      // New mux-generation baseline: buffered session/queued frames belong to
+      // the previous generation and the host is about to resend the live
+      // snapshot — drop them, or every reconnect appends a duplicate batch
+      // (and enough reconnects push real approval/question frames past the
+      // cap). Same re-baseline signal Session uses for its own mirror.
+      const buffered = this.pendingBuffers.get(frame.sessionId)
+      if (buffered !== undefined) {
+        const kept = buffered.filter(item => item.payload.type !== 'session/queued')
+        if (kept.length !== buffered.length) {
+          if (kept.length === 0) this.pendingBuffers.delete(frame.sessionId)
+          else this.pendingBuffers.set(frame.sessionId, kept)
+        }
+      }
     }
     const session = this.sessions.get(frame.sessionId)
     if (session === undefined) {
-      // Approval/question frames never hit history: buffer for replay on instantiation;
-      // everything else drops (not instantiated — history fully backfills on open).
+      // Approval/question/queued frames never hit history: buffer for replay on
+      // instantiation; everything else drops (not instantiated — history fully
+      // backfills on open).
       switch (frame.type) {
         case 'approval/requested':
         case 'approval/resolved':
         case 'question/requested':
-        case 'question/resolved': {
+        case 'question/resolved':
+        case 'session/queued': {
           const buffer = this.pendingBuffers.get(frame.sessionId) ?? []
           buffer.push(envelope)
           if (buffer.length > PENDING_BUFFER_CAP) buffer.splice(0, buffer.length - PENDING_BUFFER_CAP)
@@ -402,11 +366,11 @@ export class SessionManager {
     switch (frame.type) {
       case 'host/session-added': {
         this.mergeSummary({
-          sessionId: frame.sessionId, updatedAt: Date.now(), running: false,
+          sessionId: frame.sessionId, updatedAt: Date.now(), running: false, blank: frame.blank,
           ...(frame.parentSessionId !== undefined ? { parentSessionId: frame.parentSessionId } : {}),
           ...(frame.cwd !== undefined ? { cwd: frame.cwd } : {}),
         })
-        this.sessions.get(frame.sessionId)?.handlePublished()
+        this.sessions.get(frame.sessionId)?.handleBlank(frame.blank)
         return
       }
       case 'host/session-removed': {
@@ -448,6 +412,7 @@ export class SessionManager {
       const prev = this.entryCache.get(entry.sessionId)
       if (
         prev !== undefined && prev.updatedAt === entry.updatedAt && prev.running === entry.running
+        && prev.blank === entry.blank
         && prev.parentSessionId === entry.parentSessionId && prev.cwd === entry.cwd
         && prev.title === entry.title && prev.depth === entry.depth
       ) return prev
@@ -459,24 +424,13 @@ export class SessionManager {
     }
     const sameOrder = items.length === this.itemsCache.length && items.every((e, i) => e === this.itemsCache[i])
     if (!sameOrder) this.itemsCache = items
-    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
+    const current = selected !== undefined && items.some(item => item.sessionId === selected)
+      ? selected
+      : undefined
     return {
       items: this.itemsCache,
       current,
-      intent,
       state: this.listState,
       phase: this.listPhase,
       error: this.listError,
@@ -492,18 +446,29 @@ function applyMutation(summaries: readonly SessionSummary[], mutation: SessionLi
       if (existing === undefined) return [mutation.summary, ...summaries]
       const filled: SessionSummary = {
         ...existing,
+        // Blank only lowers: a stale true (session-added racing the local
+        // first send) never re-hides an already-surfaced session.
+        blank: existing.blank && mutation.summary.blank,
         ...(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]
+      if (filled.cwd === existing.cwd && filled.parentSessionId === existing.parentSessionId
+        && filled.blank === existing.blank) 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 }
+      // running:true doubles as the cross-端 blank flip (a blank session
+      // never runs, so the first running frame proves a message landed).
+      return summaries.map(summary => summary.sessionId === mutation.sessionId
+        && (summary.running !== mutation.running || (mutation.running && summary.blank))
+        ? { ...summary, running: mutation.running, blank: summary.blank && !mutation.running }
+        : summary)
+    case 'engaged':
+      return summaries.map(summary => summary.sessionId === mutation.sessionId && summary.blank
+        ? { ...summary, blank: false }
         : summary)
   }
 }

packages/client/runtime/src/client/sessions/notifier.ts

@@ -3,11 +3,17 @@
 // the flush rebuilds the snapshot cache BEFORE notifying (useSyncExternalStore requires a stable
 // getSnapshot reference). With no listeners the rebuild is skipped and only the dirty bit is set
 // (keeps frame storms cheap); the next getSnapshot rebuilds lazily.
+//
+// Freshness and notification are SEPARATE bits: a pull (ensureFresh) between
+// markDirty and the scheduled flush rebuilds the snapshot but must not
+// swallow the notification — push subscribers (object-layer watchers) would
+// otherwise starve whenever any reader pulls first.
 
 /** Subscription + microtask-batched notification primitive (shared by Session and SessionManager). */
 export class Notifier {
   private listeners = new Set<() => void>()
   private dirty = false
+  private notifyPending = false
   private scheduled = false
 
   /** @param rebuild - snapshot rebuild function injected by the owner (writes the owner's snapshotCache). */
@@ -28,14 +34,18 @@ export class Notifier {
   /** State-change entry: mark dirty and schedule the batched flush. */
   markDirty(): void {
     this.dirty = true
+    this.notifyPending = true
     if (this.scheduled) return
     this.scheduled = true
     queueMicrotask(() => {
       this.scheduled = false
-      if (!this.dirty) return
-      if (this.listeners.size === 0) return // lazy: no subscribers, keep dirty for the next getSnapshot
-      this.dirty = false
-      this.rebuild()
+      if (!this.notifyPending) return
+      if (this.listeners.size === 0) return // lazy: no subscribers; dirty (if still set) rebuilds on next getSnapshot
+      this.notifyPending = false
+      if (this.dirty) {
+        this.dirty = false
+        this.rebuild()
+      }
       for (const listener of this.listeners) listener()
     })
   }
@@ -46,13 +56,18 @@ export class Notifier {
    */
   notifyNow(): void {
     this.dirty = true
+    this.notifyPending = true
     if (this.listeners.size === 0) return // lazy: same as markDirty, next getSnapshot rebuilds
+    this.notifyPending = false
     this.dirty = false
     this.rebuild()
     for (const listener of this.listeners) listener()
   }
 
-  /** Pre-getSnapshot check: rebuild synchronously when dirty (read path before first subscribe / while unobserved). */
+  /**
+   * Pre-getSnapshot check: rebuild synchronously when dirty (read path
+   * before first subscribe / while unobserved). Notification stays pending.
+   */
   ensureFresh(): void {
     if (!this.dirty) return
     this.dirty = false

packages/client/runtime/src/client/sessions/service.ts

@@ -2,8 +2,9 @@
  * SessionsService: root sessions service — list snapshot store (manager
  * projection; carries `current`, the persisted selection every
  * session-scoped surface keys off — migrated here from ui-layout per the
- * slot-parity design), session scope tree (mintScope pattern: no-op plugin
- * Fiber + ctx.extend scope tag), stable SessionBinding cache, ancestry walk.
+ * slot-parity design), Agent scope tree (mintScope pattern: no-op plugin
+ * Fiber + ctx.extend scope tag; one scope per session, agent id === session
+ * id), stable SessionBinding cache, ancestry walk.
  *
  * Scope lifecycle is stage-driven: a scope is minted lazily on first
  * resolution (pure — resolution has no side effects and is render-safe);
@@ -16,15 +17,15 @@
  */
 import type { Context, Fiber } from 'cordis'
 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 {
+  HostObservable, SessionMaybeProvideInfo, SessionProvideInfo,
+} from '@deepseek-ai/dsh-client-ui-slots'
 import type { SnapshotStore } from '../contract/store.ts'
 import { createSnapshotStore } from '../contract/store.ts'
+import { createScope, scopeOf as scopeTagOf } from '../agents/scope.ts'
 import { SessionManager } from './manager.ts'
-import type {
-  SessionIntentListSnapshot, SessionListPhase,
-} from './manager.ts'
+import type { 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 {
@@ -36,6 +37,13 @@ export interface SessionSummary {
   cwd?: string
   parentId?: SessionId
   running: boolean
+  /**
+   * Empty-log bit (host summary derivation mirror). New Session reuses a blank
+   * one targeting the same workspace. Filtering stays with the consumer: the
+   * store carries every row, while the Workspace browser shows only the
+   * selected blank entry.
+   */
+  blank: boolean
   updatedAt: number
 }
 
@@ -48,17 +56,13 @@ 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. */
+/** Structured session-create failure. */
 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.
@@ -69,9 +73,6 @@ export class SessionCreateError extends Error {
     readonly requestedSessionId: SessionId | undefined,
   ) {
     super(`session create failed: ${rpcError.code}: ${rpcError.message}`)
-    this.publishedSessionId = rpcError.code === 'workspace-attach-failed'
-      ? rpcError.details.sessionId
-      : undefined
   }
 }
 
@@ -82,20 +83,10 @@ export interface SessionBinding {
   readonly ctx: Context
 }
 
-/** Scope tag key (client counterpart of the host dsh-scope pattern). */
-const kScope = Symbol('dsh.client.scope')
-
-/**
- * Read the session scope tag off a context.
- * @param ctx - any client context.
- * @returns the session id, or undefined on root contexts.
- */
-export function scopeOf(ctx: Context): SessionId | undefined {
-  return (ctx as Context & { [kScope]?: SessionId })[kScope]
-}
-
-/** Shared no-op plugin backing each session scope fiber. */
-function sessionScope(): void {}
+// Scope primitives live in ../agents/scope.ts (the client mirror of host
+// dsh-scope, keyed by Agent identity); re-exported here so existing
+// consumers keep their import site.
+export { scopeOf } from '../agents/scope.ts'
 
 /**
  * Workspace display title of a session cwd: the path's last non-empty
@@ -128,8 +119,30 @@ interface ScopeRecord {
   fiber: Fiber
   ctx: Context
   binding: SessionBinding
-  /** Render-layer standard kit (identity-stable per scope; the renderer's per-cell caches key off it). */
-  cell: SessionCell
+  /** Render-layer standard-props bundle (identity-stable per scope; the renderer's per-info caches key off it). */
+  provideInfo: SessionProvideInfo
+}
+
+/** One plugin's per-session standard-props contribution (see {@link SessionsService.provide}). */
+export interface SessionProvideContribution {
+  /** Bare observable sources, keyed by hook base name ('input' → useInput). */
+  hooks?: Record<string, HostObservable<unknown>>
+  /** Stable plain members (action callbacks etc.), spread into standard props verbatim. */
+  props?: Record<string, unknown>
+}
+
+/**
+ * Static declaration plus per-session resolver for one standard-kit
+ * contribution. The declared names let the renderer construct the same hook
+ * and prop surface while no session is current.
+ */
+export interface SessionProvideDescriptor {
+  /** Hook base names (`input` becomes `useInput`). */
+  hooks?: readonly string[]
+  /** Plain standard-prop names. */
+  props?: readonly string[]
+  /** Resolve every declared member for one definite session. */
+  resolve(binding: SessionBinding): SessionProvideContribution
 }
 
 /** Root sessions service: list store, current selection, object-layer manager, scope tree, bindings, ancestry. */
@@ -150,6 +163,10 @@ export class SessionsService {
   private readonly selection: SnapshotStore<{ sessionId?: SessionId }>
 
   private readonly scopes = new Map<SessionId, ScopeRecord>()
+  /** Registered per-session standard-props providers, in registration order. */
+  private readonly providers: SessionProvideDescriptor[] = []
+  /** Static no-session projection, rebuilt only when the provider roster changes. */
+  private maybeInfo: SessionMaybeProvideInfo
   /**
    * The staged session id — follows `list.current` exactly, holding its last
    * defined value across masked gaps (a transiently absent selection blanks
@@ -170,7 +187,7 @@ export class SessionsService {
       { persist: { name: 'dsh.sessions.current' } })
     this.manager = new SessionManager(api, this.selection.getSnapshot().sessionId)
     this.list = createSnapshotStore<SessionListState>({
-      ids: [], byId: {}, current: undefined, intent: undefined, phase: 'pending',
+      ids: [], byId: {}, current: undefined, phase: 'pending',
     })
     // The manager owns wire truth; the store is its projection. Manager
     // notifications are already microtask-batched.
@@ -182,9 +199,97 @@ export class SessionsService {
     // the follower writes no list state — session.open()'s synchronous prefix
     // touches only session-side state and its own microtask-batched notifier.
     this.list.subscribe(() => { this.followCurrent() })
+    // The runtime's own contribution comes first: useSession rides the same
+    // provide channel every plugin uses (no renderer special case).
+    this.providers.push({
+      hooks: ['session'],
+      resolve: binding => ({ hooks: { session: binding.session } }),
+    })
+    this.maybeInfo = this.materializeMaybeProvideInfo()
     rootCtx.reflect.provide('sessions', this, undefined)
   }
 
+  /**
+   * Register a per-session standard-props provider: every session-scope slot
+   * component receives the contributed members as standard props (`hooks`
+   * sources become `use<Name>` selector hooks on the render side; `props`
+   * spread verbatim). Contributions materialize lazily with the session's
+   * scope record and die with it. Registration order is resolution order;
+   * duplicate member names fail loud at materialization.
+   * @param descriptor - static member roster plus per-session resolver.
+   * @returns disposer removing the provider (already-materialized bundles keep their members until their scope drops).
+   */
+  provide(descriptor: SessionProvideDescriptor): () => void {
+    this.providers.push(descriptor)
+    // Scopes may already exist (boot order: the list lands and resolves
+    // scopes before later plugins register) — their bundles must include
+    // every provider by first render, so re-materialize on roster change.
+    this.rematerializeProvideBundles()
+    return () => {
+      const at = this.providers.indexOf(descriptor)
+      if (at >= 0) this.providers.splice(at, 1)
+      this.rematerializeProvideBundles()
+    }
+  }
+
+  /** Rebuild every live scope's standard-props bundle after a provider roster change. */
+  private rematerializeProvideBundles(): void {
+    this.maybeInfo = this.materializeMaybeProvideInfo()
+    for (const record of this.scopes.values()) {
+      record.provideInfo = this.materializeProvideInfo(record.binding)
+    }
+  }
+
+  /** Build the static no-session kit and reject duplicate declared names. */
+  private materializeMaybeProvideInfo(): SessionMaybeProvideInfo {
+    const hooks: Record<string, undefined> = {}
+    const props: Record<string, undefined> = {}
+    for (const descriptor of this.providers) {
+      for (const name of descriptor.hooks ?? []) {
+        if (Object.hasOwn(hooks, name)) throw new Error(`sessions.provide: duplicate hook "${name}"`)
+        hooks[name] = undefined
+      }
+      for (const name of descriptor.props ?? []) {
+        if (Object.hasOwn(props, name)) throw new Error(`sessions.provide: duplicate prop "${name}"`)
+        props[name] = undefined
+      }
+    }
+    return { sessionId: undefined, hooks, props }
+  }
+
+  /** Materialize the standard-props bundle for one session (fails loud on duplicate member names). */
+  private materializeProvideInfo(binding: SessionBinding): SessionProvideInfo {
+    const hooks: Record<string, HostObservable<unknown>> = {}
+    const props: Record<string, unknown> = {}
+    for (const descriptor of this.providers) {
+      const contribution = descriptor.resolve(binding)
+      const contributedHooks = contribution.hooks ?? {}
+      const contributedProps = contribution.props ?? {}
+      for (const name of Object.keys(contributedHooks)) {
+        if (!(descriptor.hooks ?? []).includes(name)) {
+          throw new Error(`sessions.provide: undeclared hook "${name}"`)
+        }
+      }
+      for (const name of Object.keys(contributedProps)) {
+        if (!(descriptor.props ?? []).includes(name)) {
+          throw new Error(`sessions.provide: undeclared prop "${name}"`)
+        }
+      }
+      for (const name of descriptor.hooks ?? []) {
+        const source = contributedHooks[name]
+        if (source === undefined) throw new Error(`sessions.provide: missing hook "${name}"`)
+        if (Object.hasOwn(hooks, name)) throw new Error(`sessions.provide: duplicate hook "${name}"`)
+        hooks[name] = source
+      }
+      for (const name of descriptor.props ?? []) {
+        if (!Object.hasOwn(contributedProps, name)) throw new Error(`sessions.provide: missing prop "${name}"`)
+        if (Object.hasOwn(props, name)) throw new Error(`sessions.provide: duplicate prop "${name}"`)
+        props[name] = contributedProps[name]
+      }
+    }
+    return { sessionId: binding.sessionId, hooks, props }
+  }
+
   /**
    * Select a session as current. Unknown ids fail loud instead of navigating
    * nowhere.
@@ -205,32 +310,6 @@ export class SessionsService {
     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.
@@ -261,21 +340,26 @@ export class SessionsService {
   }
 
   /**
-   * Create a session on the host.
+   * Create a session on the host. Resolution guarantee: by the time the
+   * promise resolves, the created session is in the list store and
+   * {@link SessionsService.binding} resolves it — callers (New Session
+   * draft hand-off) may address the scope synchronously, without waiting a
+   * notifier flush. The synchronous projection below makes this structural
+   * rather than an accident of microtask ordering.
    * @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.
+   * @throws {SessionCreateError} with the requested id.
    */
   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)
+    this.projectList()
     return result.value.sessionId
   }
 
   /**
-   * Resolve a session-scoped context view (use-and-discard).
-   * @param id - session id.
+   * Resolve an Agent-scoped context view (use-and-discard).
+   * @param id - session id (the agent identity — 1:1 same axis).
    * @returns scoped ctx, or undefined for a session neither listed nor already scoped.
    */
   scope(id: SessionId): Context | undefined {
@@ -283,7 +367,7 @@ export class SessionsService {
   }
 
   /**
-   * Read the session scope tag off a context. Service-method seam: fetch
+   * Read the Agent scope tag off a context. Service-method seam: fetch
    * bundles must reach scope resolution through ctx.sessions — a cross-bundle
    * value import of the standalone helper would inline a second module
    * instance whose private tag Symbol never matches.
@@ -291,7 +375,22 @@ export class SessionsService {
    * @returns the session id, or undefined on root contexts.
    */
   scopeOf(ctx: Context): SessionId | undefined {
-    return scopeOf(ctx)
+    return scopeTagOf(ctx)
+  }
+
+  /**
+   * Resolve the business Session behind an Agent-scoped context — the one
+   * hop every scoped consumer (event listeners, per-session controllers)
+   * takes from ctx-space into object-space (the client mirror of host
+   * `agent.session`). Same service-method seam as
+   * {@link SessionsService.scopeOf}.
+   * @param ctx - an Agent-scoped context.
+   * @returns the Session, or undefined when the ctx is untagged or its scope was pruned.
+   */
+  sessionOf(ctx: Context): Session | undefined {
+    const id = scopeTagOf(ctx)
+    if (id === undefined) return undefined
+    return this.scopes.get(id)?.binding.session
   }
 
   /**
@@ -305,16 +404,26 @@ export class SessionsService {
   }
 
   /**
-   * Resolve the render-layer session cell (SessionProvider's feed through
-   * the renderer host; ctx never enters the render layer). Pure resolution —
-   * render-safe: SessionProvider calls this during render, so no staging, no
-   * window side effects (StrictMode double-invokes and concurrent discarded
-   * passes must stay free).
+   * Resolve the render-layer standard-props bundle (SessionProvider's feed
+   * through the renderer host; ctx never enters the render layer). Pure
+   * resolution — render-safe: SessionProvider calls this during render, so no
+   * staging, no window side effects (StrictMode double-invokes and concurrent
+   * discarded passes must stay free).
    * @param id - session id.
-   * @returns cell, or undefined for a session neither listed nor already scoped.
+   * @returns the provide info, or undefined for a session neither listed nor already scoped.
    */
-  cell(id: string): SessionCell | undefined {
-    return this.resolve(id as SessionId)?.cell
+  provideInfo(id: string): SessionProvideInfo | undefined {
+    return this.resolve(id as SessionId)?.provideInfo
+  }
+
+  /**
+   * Resolve the current-session-optional standard kit. Unknown or absent ids
+   * return the static no-session projection rather than removing hook props.
+   * @param id - current session id, when selected.
+   * @returns a definite or no-session provide bundle.
+   */
+  maybeProvideInfo(id: string | undefined): SessionMaybeProvideInfo {
+    return (id === undefined ? undefined : this.provideInfo(id)) ?? this.maybeInfo
   }
 
   /**
@@ -360,29 +469,42 @@ export class SessionsService {
     return chain
   }
 
-  /** Lazily mint the scope + binding for a listed (or already-scoped) session. */
+  /**
+   * Lazily mint the scope + binding for an eligible session. Eligibility and
+   * prune share one predicate (decision 12): listed on the host — a scope is
+   * born when its session enters the client's view (list mirror row from the
+   * baseline pull, a create() echo, or the session-added frame) and dies with
+   * the prune when the row leaves.
+   */
   private resolve(id: SessionId): ScopeRecord | undefined {
     const existing = this.scopes.get(id)
     if (existing !== undefined) return existing
-    // Frozen scopes outlive the list; new scopes are only minted for listed sessions.
-    if (this.list.getSnapshot().byId[id] === undefined) return undefined
-    const fiber = this.rootCtx.plugin(sessionScope)
-    const ctx = fiber.ctx.extend({ [kScope]: id })
+    if (!this.eligible(id)) return undefined
+    const { fiber, ctx } = createScope(this.rootCtx, id)
     const session = this.manager.get(id)
+    // The Session owns its scoped dispatch point (host Agent.loopCtx mirror);
+    // mint and bind are one step so a live scope record implies a bound actx.
+    session.bindScope(ctx)
+    const binding: SessionBinding = { sessionId: id, session, ctx }
     const record: ScopeRecord = {
       fiber,
       ctx,
-      binding: { sessionId: id, session, ctx },
-      // Session is the observable; React binds a selector hook at its own seam.
-      cell: { sessionId: id, session },
+      binding,
+      // Sources are bare observables; React binds selector hooks at its own seam.
+      provideInfo: this.materializeProvideInfo(binding),
     }
     this.scopes.set(id, record)
     return record
   }
 
+  /** The one aliveness predicate shared by scope mint and prune: host-listed. */
+  private eligible(id: SessionId): boolean {
+    return this.list.getSnapshot().byId[id] !== undefined
+  }
+
   /** Project the manager's list snapshot into the store (title derivation is display-only). */
   private projectList(): void {
-    const { items, current, intent, phase } = this.manager.getListSnapshot()
+    const { items, current, phase } = this.manager.getListSnapshot()
     const ids: SessionId[] = []
     const byId: Record<SessionId, SessionSummary> = {}
     for (const entry of items) {
@@ -391,6 +513,7 @@ export class SessionsService {
         id: entry.sessionId,
         displayTitle: displayTitleOf(entry.title, entry.cwd, entry.sessionId),
         running: entry.running,
+        blank: entry.blank,
         updatedAt: entry.updatedAt,
         ...(entry.title !== undefined ? { title: entry.title } : {}),
         ...(entry.cwd !== undefined ? { cwd: entry.cwd } : {}),
@@ -398,19 +521,22 @@ export class SessionsService {
       }
     }
     const persisted = this.selection.getSnapshot().sessionId
-    if (intent?.sessionId === current) {
+    // No current (cleared, or masked gap) wipes the persisted cell — a reload
+    // stays on empty; the in-memory selection still resurfaces a masked id.
+    if (current === undefined) {
       if (persisted !== undefined) this.selection.set({})
-    } else if (current !== undefined && byId[current] !== undefined && persisted !== current) {
+    } else if (byId[current] !== undefined && persisted !== current) {
       this.selection.set({ sessionId: current })
     }
-    this.list.set({ ids, byId, current, intent, phase })
+    this.list.set({ ids, byId, current, phase })
     this.pruneScopes(byId)
   }
 
-  /** Tear down scopes for removed sessions off stage; the staged one defers until the stage moves. */
+  /** Tear down scope + instance for no-longer-eligible sessions off stage; the staged one defers until the stage moves. */
   private pruneScopes(byId: Record<SessionId, SessionSummary>): void {
+    void byId
     for (const [id, record] of this.scopes) {
-      if (byId[id] !== undefined) continue
+      if (this.eligible(id)) continue
       if (id === this.watched) {
         this.deferredRemovals.add(id)
         continue
@@ -421,12 +547,22 @@ export class SessionsService {
     }
   }
 
-  /** Dispose a scope fiber and its session-keyed slot-store instances together (single lifecycle axis). */
+  /**
+   * One teardown for the whole per-session axis (decision 12): the scope
+   * fiber (cascading every actx-registered effect: input shell, slash
+   * controller, popup, plugin stores, listeners), the session-keyed slot
+   * stores, and the Session instance itself — the host session log is the
+   * durable truth, a reopen lazily rebuilds and backfills via open().
+   */
   private dropScope(id: SessionId, record: ScopeRecord): void {
     void record.fiber.dispose()
+    // Release the Session's dispatch point with the scope it belongs to (a
+    // surviving instance — the live Intent — rebinds when resolve re-mints).
+    record.binding.session.unbindScope()
     // Optional lookup: slots and sessions are sibling services with no
     // declared dependency; a slots-less boot (object-layer tests) skips.
     this.rootCtx.get('slots')?.pruneStoreScope(id)
+    this.manager.drop(id)
   }
 
   /** Run deferred teardowns whose session is no longer staged (called when the stage moves). */
@@ -436,8 +572,8 @@ export class SessionsService {
        * stage move sweeps first, so the set cannot contain the id the stage just
        * moved to; kept as a guard against future extra sweep call sites. */
       if (id === this.watched) continue
-      // Still absent from the list? (A re-added id cancels the deferred teardown.)
-      if (this.list.getSnapshot().byId[id] !== undefined) {
+      // Eligible again? (A re-added id cancels the deferred teardown.)
+      if (this.eligible(id)) {
         this.deferredRemovals.delete(id)
         continue
       }

packages/client/runtime/src/client/sessions/session.ts

@@ -1,18 +1,19 @@
 // Sessions remain resident after creation so they continue consuming mux frames off-screen.
 
+import type { Context } from 'cordis'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
-import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type { SessionEvent, TodoItem } from '@deepseek-ai/dsh-session/types'
 import type {
   HistoryEntry, IApiClient, MuxFrame, RpcError, RpcId, RpcResult,
-  SessionId, ToolEventView, WorkspaceId,
+  SessionId, ToolEventView,
 } 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 {
-  ComposerPhase, ConversationNode, ConversationSnapshot, OpenState, PendingPrompt,
-  PromptError, RunningToolCall, SessionIntentSnapshot, SessionIntentTarget,
+  CodeSubCall, ComposerPhase, ConversationNode, ConversationSnapshot, OpenState,
+  PromptError, QueuedMessage, RunningToolCall,
 } from './conversation.ts'
 import type { PendingInteraction } from './pending.ts'
 import { PendingWait } from './pending.ts'
@@ -23,10 +24,37 @@ import { PartialAccumulator } from './partial.ts'
 /** Messages requested per history page. */
 export const PAGE_MESSAGES = 50
 
-/** Optional frontend Intent and publication observer for a Session object. */
+/** Manager-owned observers of a Session object's local state edges. */
 export interface SessionOptions {
-  intent?: { target: SessionIntentTarget; prompt: string }
-  onPublished?(session: Session): void
+  /**
+   * First ACCEPTED prompt on a blank session (fires at most once, on the
+   * prompt RPC's success response): the manager mirrors the blank→false flip
+   * into its list row so the session surfaces without waiting for a host
+   * frame. Acceptance is the flip point because it proves the user message
+   * is in the host log; a rejected first prompt keeps the session blank
+   * (hidden, still reusable by connectWorkspace).
+   */
+  onEngaged?(session: Session): void
+}
+
+/** Queue-row preview cap: the dock renders one line, the full content never leaves the host mirror. */
+const QUEUE_PREVIEW_CHARS = 200
+
+/** Internal inbox-mirror entry: the snapshot row plus the retirement-matching fields the frames carry. */
+interface QueuedEntry {
+  row: QueuedMessage
+  steering: boolean
+  /** JSON-serialized MessageSource (steering retirement matches by source, the host-mirror precedent). */
+  sourceJson: string
+}
+
+/** Single-line queue-row preview: text blocks flattened, non-text as tags, capped by code point. */
+function queuePreviewOf(content: readonly ContentBlock[]): string {
+  const flat = content
+    .map(block => (block.type === 'text' ? block.text : `[${block.type}]`))
+    .join(' ').replace(/\s+/g, ' ').trim()
+  const chars = Array.from(flat)
+  return chars.length > QUEUE_PREVIEW_CHARS ? `${chars.slice(0, QUEUE_PREVIEW_CHARS).join('')}…` : flat
 }
 
 /**
@@ -64,8 +92,21 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
   private callsCache: { rev: number; value: RunningToolCall[] } | null = null
   private pendingRev = 0
   private pendingCache: { rev: number; value: PendingInteraction[] } | null = null
+  /** Inbox mirror (session/queued frames + mux-open baseline). Queue frames never hit history,
+   *  so this is stream-only state: reconnect clears it and the fresh baseline re-populates. */
+  private queued: QueuedEntry[] = []
+  private queueRev = 0
+  private queueCache: { rev: number; value: QueuedMessage[] } | null = null
   private frozenRev = 0
   private nodesCache: { folded: readonly ConversationNode[]; frozenRev: number; value: readonly ConversationNode[] } | null = null
+  /** Current whole-list todo/write projection: each tail history response replaces it (an omitted
+   *  field is the authoritative empty list) and every live write overwrites it. */
+  private todos: readonly TodoItem[] = []
+  /** `run_code` sub-dispatches by parent callId (window-derived, like openCalls). Appends
+   *  copy-on-write the per-parent array so published snapshot references never mutate. */
+  private codeDispatches = new Map<string, readonly CodeSubCall[]>()
+  private dispatchesRev = 0
+  private dispatchesCache: { rev: number; value: ReadonlyMap<string, readonly CodeSubCall[]> } | null = null
   private running = false
   /**
    * Sticky send marker, private input of the composerPhase derivation: set
@@ -73,12 +114,10 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
    * engaging edge of the phase machine (see ComposerPhase).
    */
   private promptAttempted = false
+  /** Empty-log mirror (see ConversationSnapshot.blank); monotone false once flipped. */
+  private blankBit = 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
   /** Live events buffered during open/resync and stitched by sequence once history lands. */
   private liveBuffer: { event: SessionEvent; view: ToolEventView | undefined }[] = []
@@ -91,27 +130,46 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
   private readonly notifier = new Notifier(() => {
     this.snapshotCache = this.buildSnapshot()
   })
+  /**
+   * Agent-scoped cordis context, bound once by SessionsService when it
+   * mints the scope (the client mirror of the host Agent's loopCtx). The
+   * Session dispatches its own scoped events through it; undefined means
+   * unbound (bare object-layer construction) or already pruned — both skip
+   * dispatch-dependent behavior rather than fail.
+   */
+  private actx: Context | undefined
 
   /**
-   * @param sessionId - stable identity shared by the frontend Intent and Host entity.
+   * @param sessionId - Host session identity (client sessions are always Host-born).
    * @param api - shared wire client.
-   * @param options - optional frontend-only initial state and publication observer.
+   * @param options - optional manager-owned state observers.
    */
   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()
   }
 
+  /**
+   * Bind the Agent-scoped context minted by SessionsService (single write;
+   * a second bind is a wiring error and throws). Direction stays one-way at
+   * the seam: consumers still reach the Session via `sessions.sessionOf`,
+   * while the Session holds its own dispatch point (host Agent.loopCtx
+   * mirror).
+   * @param actx - the agent's scoped context.
+   */
+  bindScope(actx: Context): void {
+    if (this.actx !== undefined) throw new Error(`session ${this.sessionId} already has a bound scope`)
+    this.actx = actx
+  }
+
+  /** Release the bound scope at prune time (a later rebind accompanies a freshly minted scope). */
+  unbindScope(): void {
+    this.actx = undefined
+  }
+
   // ---- Operations ----
 
   /**
@@ -137,64 +195,22 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
     if (!result.ok) {
       this.promptError = { op: 'send', error: result.error }
       this.notifier.markDirty()
+      return result
+    }
+    // Blank flips on ACCEPTANCE, not attempt: an accepted prompt has logged
+    // its user/message on the host (events.length > 0 is fact, not
+    // optimism), while a rejected first prompt must keep the session blank
+    // — the client-side blank mirror only ever lowers, so flipping early on
+    // a failure would surface the session forever and strip its
+    // connectWorkspace reuse eligibility against the host's authority.
+    if (this.blankBit) {
+      this.blankBit = false
+      this.options.onEngaged?.(this)
+      this.notifier.markDirty()
     }
     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.
@@ -267,6 +283,11 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
    *  in-flight open first — its history request rode the dead connection and must not settle
    *  the fresh generation into 'error' (audit S4). */
   async resync(): Promise<void> {
+    // The queue mirror is NOT cleared here: onConnected (which drives resync)
+    // races the mux frames — the fresh generation's baseline may have landed
+    // already, and the host never resends it. The mirror re-baselines on the
+    // session/subscribed frame instead (same stream as the queue snapshot
+    // that follows it, so ordering is guaranteed).
     if (this.openState === 'cold') return // never opened: no window to rebuild (doOpen flips to 'loading' synchronously, so cold implies no in-flight open)
     this.openGeneration++
     this.openPromise = null
@@ -315,12 +336,35 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
   handleMuxEnvelope(rpcId: RpcId, frame: MuxFrame): void {
     switch (frame.type) {
       case 'session/event': {
+        this.retireQueued(frame.event)
         this.acceptLiveEvent(frame.event, frame.view)
         return
       }
+      case 'session/queued': {
+        // Row key: the enqueueing prompt's rpcId when it rode this wire (the
+        // provisional-echo reconciliation key); otherwise the frame envelope id.
+        const key = 'rpcId' in frame.source ? String(frame.source.rpcId) : `f:${rpcId}`
+        this.queued.push({
+          row: { key, preview: queuePreviewOf(frame.content) },
+          steering: frame.steering,
+          sourceJson: JSON.stringify(frame.source),
+        })
+        this.queueRev++
+        this.notifier.markDirty()
+        return
+      }
       case 'session/subscribed': {
         this.subscribedLastSeq = frame.lastSeq
-        return // pure baseline bookkeeping, no visible change
+        // New mux-generation baseline: the host pushes this session's queue
+        // snapshot AFTER the subscribed frame on the same stream, so the
+        // stale mirror clears here — race-free against onConnected/resync
+        // timing (clearing there could wipe a baseline that already landed).
+        if (this.queued.length > 0) {
+          this.queued = []
+          this.queueRev++
+          this.notifier.markDirty()
+        }
+        return
       }
       case 'approval/requested': {
         const { type: _type, sessionId: _sid, ...payload } = frame
@@ -357,14 +401,38 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
    * @param running - the new running state.
    */
   handleRunning(running: boolean): void {
+    // Leave-running sweep (host queuedMirror precedent): discard paths (cancel,
+    // terminal steering drop) have no per-entry frame, so ANY not-running signal
+    // with a nonempty mirror clears it — checked before the equality return so a
+    // stale replay on an already-idle session still sweeps.
+    if (!running && this.queued.length > 0) {
+      this.queued = []
+      this.queueRev++
+      this.notifier.markDirty()
+    }
+    // Turn-start conversion: a blank session never runs, so the first
+    // running:true proves another端's first message landed (设计稿 2.2).
+    if (running && this.blankBit) {
+      this.blankBit = false
+      this.notifier.markDirty()
+    }
     if (this.running === running) return
     this.running = running
     this.notifier.markDirty()
   }
 
-  /** Mark that Host publication is known without resolving an uncertain local create response. */
-  handlePublished(): void {
-    this.markPublished()
+  /**
+   * Blank-bit relay from the authoritative summary source (list baseline and
+   * the session-added frame). Monotone: once any signal (local first send,
+   * running flip, an earlier summary) cleared it, a stale true never
+   * re-blanks.
+   * @param blank - the summary's derived empty-log bit.
+   */
+  handleBlank(blank: boolean): void {
+    if (blank === this.blankBit) return
+    if (blank && (this.promptAttempted || this.running)) return
+    this.blankBit = blank
+    this.notifier.markDirty()
   }
 
   /** host/session-removed relay: flag the snapshot (instance survives — resident-instance rule). */
@@ -400,112 +468,6 @@ 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> {
@@ -520,13 +482,13 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
         this.openError = result.error
         return
       }
-      this.installWindow(result.value.events, result.value.hasMore)
+      this.installWindow(result.value.events, result.value.hasMore, result.value.todos)
       // Gap detection (§D.3-4): baseline past the window tail and liveBuffer did not cover it -> pull the tail page once more.
       const tailSeq = this.windowTailSeq()
       if (this.subscribedLastSeq !== null && tailSeq !== null && this.subscribedLastSeq > tailSeq) {
         result = (await this.api.sessions.history({ sessionId: this.sessionId, maxMessages: PAGE_MESSAGES })).result
         if (generation !== this.openGeneration) return
-        if (result.ok) this.installWindow(result.value.events, result.value.hasMore)
+        if (result.ok) this.installWindow(result.value.events, result.value.hasMore, result.value.todos)
       }
       this.openState = 'open'
     } catch (error) {
@@ -544,11 +506,19 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
    *  Stitching MUST NOT route through acceptLiveEvent: openState is still 'loading' here
    *  (doOpen flips it after install), so recursing would push every buffered event straight
    *  back into liveBuffer where nothing ever drains it — a silent drop loop (audit S1). */
-  private installWindow(entries: HistoryEntry[], hasMore: boolean): void {
+  private installWindow(entries: HistoryEntry[], hasMore: boolean, todos: readonly TodoItem[] | undefined): void {
     this.events = entries.map(e => e.event)
     this.views = entries.map(e => e.view)
     this.baseSeq = this.events[0]?.seq ?? 0
     this.hasMore = hasMore
+    // Session-level projection from the tail page (full-log latest todo/write,
+    // independent of the window); an in-window write below re-derives the same
+    // value, and later live events keep overwriting it. Every caller here is a
+    // tail request (no beforeSeq), which the host answers with the projection
+    // or omits it only when the full log holds no todo/write — so an absent
+    // field is the authoritative empty list, not a missing carrier. Assigning
+    // it clears a plan the log never kept (a write lost to a host crash).
+    this.todos = todos ?? []
     this.foldAdapter.reset(this.events, this.baseSeq, this.views)
     this.rebuildDerivedFromWindow()
     const buffered = this.liveBuffer
@@ -599,7 +569,7 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
       const { result } = await this.api.sessions.history({ sessionId: this.sessionId, maxMessages: PAGE_MESSAGES })
       // Failure or superseded by a full resync: drop — the resync path rebuilds and clears the buffer itself.
       if (result.ok && generation === this.openGeneration && this.openState === 'open') {
-        this.installWindow(result.value.events, result.value.hasMore)
+        this.installWindow(result.value.events, result.value.hasMore, result.value.todos)
       }
     } catch (error) {
       console.error('[web-runtime] gap repair failed:', error)
@@ -608,9 +578,89 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
     }
   }
 
+  /** Consumption-event retirement, mirroring the host queuedMirror rules: a message-triggered
+   *  turn/start claims the oldest non-steering entry; a steering/message drains the oldest
+   *  steering entry with the same source (loop-authored steering matches nothing and drops none). */
+  private retireQueued(event: SessionEvent): void {
+    if (this.queued.length === 0) return
+    let index = -1
+    if (event.type === 'turn/start') {
+      if (event.data.trigger.kind !== 'message') return
+      index = this.queued.findIndex(entry => !entry.steering)
+    } else if (event.type === 'steering/message') {
+      const source = JSON.stringify(event.data.source)
+      index = this.queued.findIndex(entry => entry.steering && entry.sourceJson === source)
+    } else {
+      return
+    }
+    if (index < 0) return
+    this.queued.splice(index, 1)
+    this.queueRev++
+    this.notifier.markDirty()
+  }
+
   /** Per-event side effects (right column of the §A.9 dispatch table):
    *  chunk accumulation / partial clear on finalize / openCalls add-remove. */
   private applyEventSideEffects(event: SessionEvent, view?: ToolEventView): void {
+    // The `tool/code-dispatch-start`/`tool/code-dispatch` pair is declared by
+    // the host-side dsh-tools plugin whose types cannot enter the client
+    // program (its host Context merges collide with the client's), so this
+    // wire consumer narrows them structurally — the same posture as every
+    // other cross-wire event payload.
+    if ((event.type as string) === 'tool/code-dispatch-start') {
+      // A started sub-dispatch enters the index as a RunningToolCall — the
+      // exact shape a native in-flight call renders from — under its parent
+      // run_code callId; it never joins the surface flow.
+      const data = event.data as unknown as {
+        parentCallId: string
+        subCallId: string
+        name: string
+        arguments: unknown
+      }
+      const running: CodeSubCall = {
+        callId: data.subCallId, name: data.name,
+        argsRaw: JSON.stringify(data.arguments),
+        turn: 0, step: 0, time: event.time, callView: null,
+      }
+      const siblings = this.codeDispatches.get(data.parentCallId) ?? []
+      this.codeDispatches.set(data.parentCallId, [...siblings, running])
+      this.dispatchesRev++
+      return
+    }
+    if ((event.type as string) === 'tool/code-dispatch') {
+      // Settlement replaces the running entry in place (same array position,
+      // so parallel sub-calls keep their start order) with the
+      // ToolResultNode form; a settle with no observed start (history window
+      // cut mid-pair, or a pre-start-event log) appends directly.
+      const data = event.data as unknown as {
+        parentCallId: string
+        subCallId: string
+        name: string
+        arguments: unknown
+        isError: boolean
+        content: ContentBlock[]
+      }
+      const siblings = this.codeDispatches.get(data.parentCallId) ?? []
+      const at = siblings.findIndex(sub => sub.callId === data.subCallId)
+      const started = at === -1 ? undefined : siblings[at]
+      const settled: CodeSubCall = {
+        kind: 'tool-result', seq: event.seq, time: event.time,
+        callId: data.subCallId,
+        call: { name: data.name, argsRaw: JSON.stringify(data.arguments) },
+        // Duration source: the paired start's time when observed; null =
+        // unknown (settle-only window), matching the native tool-result
+        // contract so views never present a fabricated zero duration.
+        callTime: started === undefined ? null : started.time,
+        content: data.content, isError: data.isError,
+        callView: null, resultView: null,
+      }
+      this.codeDispatches.set(
+        data.parentCallId,
+        at === -1 ? [...siblings, settled] : siblings.map((sub, index) => (index === at ? settled : sub)),
+      )
+      this.dispatchesRev++
+      return
+    }
     switch (event.type) {
       case 'assistant/chunk': {
         const { turn, step, chunk } = event.data
@@ -639,6 +689,10 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
         if (this.openCalls.delete(String(event.data.callId))) this.callsRev++
         return
       }
+      case 'todo/write': {
+        this.todos = event.data.todos
+        return
+      }
       case 'turn/end': {
         // Aborted turns never finalize. The accumulated partial is VALUE, not residue: freeze it
         // into an interrupted terminal node (pulse stops, text survives) instead of deleting it.
@@ -683,13 +737,18 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
 
   /** Re-derive state (partial/openCalls/frozenNodes) from raw window events after a rebuild — keeps
    *  paging/stitching consistent, and makes the live freeze and the history replay converge on the
-   *  same interrupted nodes (chunks are logged, so the replayed sweep re-freezes identical text). */
+   *  same interrupted nodes (chunks are logged, so the replayed sweep re-freezes identical text).
+   *  todos is deliberately NOT reset: it is session-level (seeded by the tail page's full-log
+   *  projection, not derivable from an arbitrary window). The window always extends to the log
+   *  tail, so an in-window todo/write can only overwrite it with the same latest value. */
   private rebuildDerivedFromWindow(): void {
     this.partial = null
     this.openCalls.clear()
     this.callsRev++
     this.frozenNodes = []
     this.frozenRev++
+    this.codeDispatches = new Map()
+    this.dispatchesRev++
     for (let i = 0; i < this.events.length; i++) {
       const event = this.events[i]
       /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */
@@ -722,6 +781,12 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
     if (this.pendingCache === null || this.pendingCache.rev !== this.pendingRev) {
       this.pendingCache = { rev: this.pendingRev, value: [...this.pending.values()] }
     }
+    if (this.dispatchesCache === null || this.dispatchesCache.rev !== this.dispatchesRev) {
+      this.dispatchesCache = { rev: this.dispatchesRev, value: new Map(this.codeDispatches) }
+    }
+    if (this.queueCache === null || this.queueCache.rev !== this.queueRev) {
+      this.queueCache = { rev: this.queueRev, value: this.queued.map(entry => entry.row) }
+    }
     const partial = this.partial?.toPartial() ?? null
     return {
       sessionId: this.sessionId,
@@ -730,6 +795,8 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
       partial,
       runningCalls: this.callsCache.value,
       pending: this.pendingCache.value,
+      codeDispatches: this.dispatchesCache.value,
+      queue: this.queueCache.value,
       running: this.running,
       composerPhase: derivePhase(
         nodes.length > 0 || partial !== null || this.running || this.pendingCache.value.length > 0,
@@ -741,17 +808,13 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
       hasMore: this.hasMore,
       loadingOlder: this.loadingOlder,
       promptError: this.promptError,
-      intent: this.intent,
-      pendingPrompt: this.pendingPrompt,
+      blank: this.blankBit,
       lastAgentError: this.lastAgentError,
+      todos: this.todos,
     }
   }
 }
 
-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

packages/client/runtime/src/client/slots.ts

@@ -235,7 +235,7 @@ export class SlotsService extends Service {
     }
   }
 
-  /** Build once after both object-layer services mount; session cells still resolve lazily. */
+  /** Build once after both object-layer services mount; per-session provide bundles still resolve lazily. */
   private hostFace(): SlotRendererHost {
     if (this._host !== undefined) return this._host
     const sessions = this.ctx.get('sessions')
@@ -264,7 +264,8 @@ export class SlotsService extends Service {
       sessions: {
         list: sessions.list,
         current,
-        cell: id => sessions.cell(id),
+        provideInfo: id => sessions.provideInfo(id),
+        maybeProvideInfo: id => sessions.maybeProvideInfo(id),
       },
       workspaces: { list: workspaces.list },
     }
@@ -275,13 +276,13 @@ export class SlotsService extends Service {
   private resolveStore(handle: EngineStoreHandle, sessionId: string | undefined): StoreInstanceLike {
     const record = this._stores.get(handle)
     if (record === undefined) throw new Error('store handle is not registered (entry unloaded, or the handle never went through register)')
-    const key = record.scope === 'session' ? sessionId : ROOT_INSTANCE_KEY
-    if (key === undefined) throw new Error('session-scoped store resolution requires a session id')
+    const key = record.scope === 'root' ? ROOT_INSTANCE_KEY : sessionId
+    if (key === undefined) throw new Error(`${record.scope} store resolution requires a session id`)
     let instance = record.instances.get(key)
     if (instance === undefined) {
       // Session instances get the scope key (the engine suffixes the persist
       // key per session); root instances stay keyless.
-      instance = record.scope === 'session' ? handle.create(key) : handle.create()
+      instance = record.scope === 'root' ? handle.create() : handle.create(key)
       record.instances.set(key, instance)
     }
     return instance

packages/client/runtime/src/client/workspaces/manager.ts

@@ -6,11 +6,7 @@ import type {
 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'
+import { Workspace, type WorkspaceCreateInput } from './workspace.ts'
 
 /** Monotone workspace-list arrival lifecycle. */
 export type WorkspaceListPhase = 'pending' | 'ready'
@@ -18,24 +14,34 @@ 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
 }
 
+type WorkspaceDelta =
+  | { type: 'upsert'; workspace: WorkspaceView }
+  | { type: 'remove'; workspaceId: WorkspaceId }
+
 /** 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 refreshFrames: WorkspaceDelta[] | null = null
+  /**
+   * Ids this process has seen removed, kept for the connection's lifetime so
+   * a late changed frame or a stale baseline row cannot resurrect a deleted
+   * row. Correctness rests on Host ids never being reused (the registry mints
+   * a fresh `randomUUID` per record, including when the same directory is
+   * registered again) — a path-derived id scheme would turn these entries
+   * into permanent blindfolds and must clear them instead.
+   */
+  private readonly removedIds = new Set<WorkspaceId>()
   private snapshotCache: WorkspaceListSnapshot
   private readonly notifier = new Notifier(() => {
     this.snapshotCache = this.buildSnapshot()
@@ -46,44 +52,6 @@ export class WorkspaceManager {
     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
@@ -96,7 +64,7 @@ export class WorkspaceManager {
     this.state = 'loading'
     this.error = null
     const established = this.itemViews()
-    const frames: WorkspaceView[] = []
+    const frames: WorkspaceDelta[] = []
     this.refreshFrames = frames
     this.notifier.markDirty()
     this.inflight = (async () => {
@@ -106,7 +74,8 @@ export class WorkspaceManager {
           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)
+          items = items.filter(workspace => !this.removedIds.has(workspace.workspaceId))
+          for (const delta of frames) items = applyWorkspaceDelta(items, delta)
           this.installViews(items)
           this.state = 'idle'
           this.phase = 'ready'
@@ -156,6 +125,18 @@ export class WorkspaceManager {
     return result
   }
 
+  /**
+   * Delete a Workspace registration and remove its local projection from the
+   * unary response without waiting for the Host frame.
+   * @param workspaceId - target workspace.
+   * @returns the wire result.
+   */
+  async delete(workspaceId: WorkspaceId): Promise<RpcResult<{ deleted: true }>> {
+    const { result } = await this.api.workspace.delete({ workspaceId })
+    if (result.ok) this.remove(workspaceId, true)
+    return result
+  }
+
   /**
    * Move a session within its Workspace's manual order, then publish the
    * returned snapshot without waiting for the changed frame.
@@ -184,6 +165,7 @@ export class WorkspaceManager {
    */
   handleHostEnvelope(envelope: RpcRequest<HostFrame>): void {
     if (envelope.payload.type === 'host/workspace-changed') this.upsert(envelope.payload.workspace)
+    else if (envelope.payload.type === 'host/workspace-removed') this.remove(envelope.payload.workspaceId)
   }
 
   /** Re-pull the baseline after each connection generation. */
@@ -212,7 +194,6 @@ export class WorkspaceManager {
   private buildSnapshot(): WorkspaceListSnapshot {
     return {
       items: this.itemViews(),
-      intent: this.intent?.getSnapshot().intent,
       state: this.state,
       phase: this.phase,
       error: this.error,
@@ -221,7 +202,8 @@ export class WorkspaceManager {
 
   /** Upsert one Host view, optionally retaining the local object that materialized it. */
   private upsert(view: WorkspaceView, identity?: Workspace): void {
-    this.refreshFrames?.push(view)
+    if (this.removedIds.has(view.workspaceId)) return
+    this.refreshFrames?.push({ type: 'upsert', workspace: 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
@@ -241,6 +223,24 @@ export class WorkspaceManager {
     this.notifier.markDirty()
   }
 
+  /** Remove one id idempotently and retain a tombstone against late echoes. */
+  private remove(workspaceId: WorkspaceId, direct = false): void {
+    this.refreshFrames?.push({ type: 'remove', workspaceId })
+    this.removedIds.add(workspaceId)
+    const items = this.items.filter(item =>
+      item.getSnapshot().view?.workspaceId !== workspaceId)
+    if (items.length === this.items.length) {
+      // The Host frame may have removed the row first but left its batched
+      // notification pending. A successful unary echo still flushes that
+      // committed state before the user action resolves.
+      if (direct) this.notifier.notifyNow()
+      return
+    }
+    this.items = items
+    if (direct) this.notifier.notifyNow()
+    else this.notifier.markDirty()
+  }
+
   private installViews(views: readonly WorkspaceView[]): void {
     const existing = new Map(
       this.items.flatMap((workspace) => {
@@ -280,3 +280,10 @@ function upsertWorkspace(items: readonly WorkspaceView[], workspace: WorkspaceVi
     ? [workspace, ...items]
     : items.map((item, position) => position === index ? workspace : item)
 }
+
+/** Replay one ordered delta over a baseline: upsert in place, or drop the removed id. */
+function applyWorkspaceDelta(items: readonly WorkspaceView[], delta: WorkspaceDelta): WorkspaceView[] {
+  return delta.type === 'upsert'
+    ? upsertWorkspace(items, delta.workspace)
+    : items.filter(workspace => workspace.workspaceId !== delta.workspaceId)
+}

packages/client/runtime/src/client/workspaces/service.ts

@@ -7,13 +7,11 @@ import type {
 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'
+import { WorkspaceManager, 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
@@ -29,64 +27,128 @@ export class WorkspacesService {
   readonly list: SnapshotStore<WorkspaceListState>
   /** Workspace baseline and frame owner. */
   private readonly manager: WorkspaceManager
-  private initialSessionResolved = false
-  private composingIntent = false
+  /** In-flight blank-session creates keyed by workspace (connectWorkspace coalescing). */
+  private readonly connecting = new Map<WorkspaceId, Promise<SessionId>>()
+  /** Guards the runtime-owned one-shot initial-selection subscription. */
+  private initialSelectionStarted = 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.
+   * @param sessions - lower-level Session service used for recency and blank-session reuse.
    */
   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,
+      items: [], 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() })
+    this.manager.subscribe(() => { this.project() })
+    this.sessions.list.subscribe(() => { 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.
+   * Resolve the session a New Session flow lands in once this Workspace is
+   * chosen: reuse the workspace's existing blank session when one is in the
+   * list mirror, else create a fresh one on the host (`session.create` births
+   * the full Session+Agent — the client holds no intermediate state). The
+   * caller owns navigation: take the returned id to `sessions.open`.
+   * Resolution guarantee (both arms): the returned id is already in the list
+   * store and `sessions.binding(id)` resolves synchronously — draft hand-off
+   * may write the new scope's machine before opening.
+   * @param workspaceId - chosen Workspace (must be in the workspace list).
+   * @returns the reused or newly created session id.
    */
-  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)
+  async connectWorkspace(workspaceId: WorkspaceId): Promise<SessionId> {
+    const workspace = this.list.getSnapshot().items.find(item => item.workspaceId === workspaceId)
+    if (workspace === undefined) throw new Error(`workspaces.connectWorkspace: unknown workspace ${workspaceId}`)
+    // Coalesce concurrent connects: a create's summary lands without cwd
+    // until the host frame arrives, so a second call inside that window
+    // would miss the reuse scan and mint another hidden blank session.
+    const inflight = this.connecting.get(workspaceId)
+    if (inflight !== undefined) return inflight
+    // Reuse: blank && same canonical cwd (workspace.path is the host realpath
+    // canon; summary cwd is the session header passthrough of the same canon).
+    const sessions = this.sessions.list.getSnapshot()
+    for (const id of sessions.ids) {
+      const summary = sessions.byId[id]
+      if (summary !== undefined && summary.blank && summary.cwd === workspace.path) return summary.id
+    }
+    const attempt = this.sessions.create({ workspaceId })
+      .finally(() => { this.connecting.delete(workspaceId) })
+    this.connecting.set(workspaceId, attempt)
+    return attempt
+  }
+
+  /**
+   * Follow the first complete Workspace/Session baseline and select a default
+   * session exactly once. A restored current session wins; otherwise the most
+   * recent Workspace is connected (reusing or creating its blank session).
+   * Later explicit clears stay cleared instead of retriggering this startup
+   * policy. A failed connect may retry on the next baseline projection.
+   * @returns disposer for the baseline subscription; late work cannot navigate after disposal.
+   */
+  startInitialSelection(): () => void {
+    if (this.initialSelectionStarted) {
+      throw new Error('workspaces.startInitialSelection: already started')
+    }
+    this.initialSelectionStarted = true
+    let state: 'waiting' | 'connecting' | 'done' = 'waiting'
+    let disposed = false
+    const reconcile = (): void => {
+      if (disposed || state !== 'waiting') return
+      const workspace = this.list.getSnapshot()
+      if (!workspace.baselinesReady) return
+      const current = this.sessions.list.getSnapshot().current
+      const target = workspace.recentWorkspaceId
+      if (current !== undefined || target === undefined) {
+        state = 'done'
+        return
       }
-    } finally {
-      this.composingIntent = false
-      this.project()
+      state = 'connecting'
+      void this.connectWorkspace(target).then(
+        (sessionId) => {
+          if (disposed) return
+          if (this.sessions.list.getSnapshot().current === undefined) {
+            this.sessions.open(sessionId)
+          }
+          state = 'done'
+        },
+        (reason: unknown) => {
+          if (disposed) return
+          state = 'waiting'
+          console.warn('initial workspace selection failed:', reason)
+        },
+      )
+    }
+    const unsubscribe = this.list.subscribe(reconcile)
+    reconcile()
+    return () => {
+      disposed = true
+      unsubscribe()
     }
   }
 
-  /** 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)
+  /**
+   * The shared New Session action behind the shell entry points (sidebar
+   * button, workspace browser): resolve the target Workspace — explicit wins,
+   * else the recent-Workspace projection — connect its blank session and
+   * navigate there; with no Workspace at all, clear the selection into the
+   * New Session view state. Connect failures are non-fatal (console
+   * diagnostics; the current view stays usable).
+   * @param workspaceId - explicit target Workspace for scoped actions.
+   */
+  startSession(workspaceId?: WorkspaceId): void {
+    const target = workspaceId ?? this.list.getSnapshot().recentWorkspaceId
+    if (target === undefined) {
+      this.sessions.clear()
       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)
-      }
-    })
+    void this.connectWorkspace(target).then(
+      (sessionId) => { this.sessions.open(sessionId) },
+      (reason: unknown) => { console.warn('new session failed:', reason) },
+    )
   }
 
   /**
@@ -112,6 +174,16 @@ export class WorkspacesService {
     return result.value.workspace
   }
 
+  /**
+   * Delete one Workspace registration. Sessions, session logs, and the
+   * directory remain Host-owned outside this operation.
+   * @param workspaceId - target workspace.
+   */
+  async delete(workspaceId: WorkspaceId): Promise<void> {
+    const result = await this.manager.delete(workspaceId)
+    if (!result.ok) throw new Error(`workspace delete failed: ${result.error.code}: ${result.error.message}`)
+  }
+
   /**
    * Move a session within its Workspace's manual order (DOM-insertBefore-like).
    * @param workspaceId - owning workspace.
@@ -153,20 +225,15 @@ export class WorkspacesService {
   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,
+      items: workspace.items,
+      state: workspace.state,
+      phase: workspace.phase,
+      error: workspace.error,
       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()
-    }
   }
 }
 

packages/client/runtime/tests/client-apply.spec.ts

@@ -8,7 +8,9 @@ import { describe, expect, it } from 'vitest'
 import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
 import type { ConnectionSinks } from '@deepseek-ai/dsh-client-connection/client'
 import * as RuntimeClient from '../src/client/index.ts'
-import { FakeApiClient } from './fake-api.ts'
+import type { SessionsService } from '../src/client/sessions/service.ts'
+import type { WorkspacesService } from '../src/client/workspaces/service.ts'
+import { FakeApiClient, ok } from './fake-api.ts'
 
 interface Bench {
   ctx: Context
@@ -33,6 +35,10 @@ async function mount(): Promise<Bench> {
   return bench
 }
 
+async function flushMicrotasks(): Promise<void> {
+  for (let i = 0; i < 12; i++) await Promise.resolve()
+}
+
 describe('runtime client apply', () => {
   it('mounts slots, Sessions, and Workspaces and fans host frames into both managers', async () => {
     const bench = await mount()
@@ -50,7 +56,7 @@ describe('runtime client apply', () => {
     // Frame sinks reach the object layer: a host session-added lands in the list store.
     bench.sinks?.onHostEnvelope?.({
       rpcId: 'r1' as never,
-      payload: { type: 'host/session-added', sessionId: 's-new' } as never,
+      payload: { type: 'host/session-added', blank: true, sessionId: 's-new' } as never,
     })
     await Promise.resolve()
     expect((sessions as { list: { getSnapshot(): { ids: string[] } } }).list.getSnapshot().ids).toContain('s-new')
@@ -71,6 +77,31 @@ describe('runtime client apply', () => {
     bench.sinks?.onConnected?.()
   })
 
+  it('selects the recent Workspace once when the first baselines have no current session', async () => {
+    const bench = await mount()
+    bench.api.onWorkspaceList = () => Promise.resolve(ok({
+      items: [{
+        workspaceId: 'w-recent', path: '/w/recent', title: 'recent', sessionIds: [],
+        createdAt: '2026-01-01T00:00:00.000Z', updatedAt: '2026-01-01T00:00:00.000Z',
+      }] as never[],
+    }))
+    bench.api.onList = () => Promise.resolve(ok({ items: [] }))
+
+    bench.sinks?.onConnected?.()
+    await flushMicrotasks()
+
+    const sessions = bench.ctx.get('sessions') as SessionsService
+    const workspaces = bench.ctx.get('workspaces') as WorkspacesService
+    expect(bench.api.callsOf('session.create')).toEqual([{ workspaceId: 'w-recent' }])
+    expect(sessions.list.getSnapshot().current).toBe('fk-new')
+
+    sessions.clear()
+    await workspaces.refresh()
+    await flushMicrotasks()
+    expect(sessions.list.getSnapshot().current).toBeUndefined()
+    expect(bench.api.callsOf('session.create')).toHaveLength(1)
+  })
+
   it('stops the stream loop when the plugin fiber unloads', async () => {
     const bench = await mount()
     const fiber = [...bench.ctx.registry.values()].find(f => f.name?.includes('client'))

packages/client/runtime/tests/event-script.ts

@@ -26,10 +26,22 @@ export const ev = {
     at(seq, { type: 'tool/call', data: { turn, step, callId, name, arguments: args } }),
   toolResult: (seq: number, turn: number, callId: string, body: string, step = 0): SessionEvent =>
     at(seq, { type: 'tool/result', surfaceOp: 'append', data: { turn, step, callId, content: text(body), isError: false } }),
+  codeDispatchStart: (seq: number, parentCallId: string, n: number, name: string, args: unknown): SessionEvent =>
+    at(seq, {
+      type: 'tool/code-dispatch-start',
+      data: { parentCallId, subCallId: `${parentCallId}:code:${n}`, name, arguments: args },
+    }),
+  codeDispatch: (seq: number, parentCallId: string, n: number, name: string, args: unknown, body: string, isError = false): SessionEvent =>
+    at(seq, {
+      type: 'tool/code-dispatch',
+      data: { parentCallId, subCallId: `${parentCallId}:code:${n}`, name, arguments: args, isError, content: text(body) },
+    }),
   stepEnd: (seq: number, turn: number, step = 0): SessionEvent =>
     at(seq, { type: 'step/end', data: { turn, step } }),
   turnEnd: (seq: number, turn: number, reason: 'completed' | 'cancelled' = 'completed'): SessionEvent =>
     at(seq, { type: 'turn/end', data: { turn, reason: { kind: reason } } }),
+  todoWrite: (seq: number, todos: { content: string; status: 'pending' | 'in_progress' | 'completed' }[]): SessionEvent =>
+    at(seq, { type: 'todo/write', data: { todos } }),
 }
 
 /** One complete plain turn (turn/start → user → step → assistant → turn/end), 6 events from startSeq. */

packages/client/runtime/tests/fake-api.ts

@@ -2,7 +2,8 @@
 // data source on a real clock; behavior tests need per-case responses and
 // deferred-controlled timing). Streams are hand pumps: pushMux/pushHost.
 import type {
-  ClientResponse, HostFrame, IApiClient, MuxFrame, RpcError, RpcReceipt, RpcRequest, RpcResponse, SessionId,
+  ClientResponse, CommandDescriptor, CommandExecuteResult, HostFrame, IApiClient, MuxFrame,
+  RpcError, RpcReceipt, RpcRequest, RpcResponse, SessionId, SkillEntry,
   WorkspaceId, WorkspaceView,
 } from '@deepseek-ai/dsh-client-connection/client'
 import { RpcId } from '@deepseek-ai/dsh-client-connection/client'
@@ -61,7 +62,7 @@ export class FakeApiClient implements IApiClient {
   onList: (payload: unknown) => Promise<RpcResponse<{ items: never[] }>> = () => Promise.resolve(ok({ items: [] }))
   onCreate: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-new' as SessionId }))
   onHistory: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number })
-  => Promise<RpcResponse<{ events: never[]; hasMore: boolean }>> =
+  => Promise<RpcResponse<{ events: never[]; hasMore: boolean; todos?: { content: string; status: 'pending' | 'in_progress' | 'completed' }[] }>> =
     () => Promise.resolve(ok({ events: [], hasMore: false }))
 
   onPrompt: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
@@ -95,6 +96,9 @@ export class FakeApiClient implements IApiClient {
   onWorkspaceRename: (payload: unknown) => Promise<RpcResponse<{ workspace: WorkspaceView }>> =
     () => Promise.resolve(ok({ workspace: fakeWorkspace('fk-ws') }))
 
+  onWorkspaceDelete: (payload: unknown) => Promise<RpcResponse<{ deleted: true }>> =
+    () => Promise.resolve(ok({ deleted: true }))
+
   onWorkspaceInsertSessionBefore: (payload: unknown) => Promise<RpcResponse<{ workspace: WorkspaceView }>> =
     () => Promise.resolve(ok({ workspace: fakeWorkspace('fk-ws') }))
 
@@ -102,10 +106,30 @@ export class FakeApiClient implements IApiClient {
     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)),
+    delete: (payload: unknown) => this.record('workspace.delete', payload, this.onWorkspaceDelete(payload)),
     insertSessionBefore: (payload: unknown) =>
       this.record('workspace.insertSessionBefore', payload, this.onWorkspaceInsertSessionBefore(payload)),
   }
 
+  // Payloads stay `unknown` (lint-lane note above); response rows are the real
+  // wire shapes so cases can program requires-bearing catalogs and dual-address
+  // skill lists without casts.
+  onCommandList: (payload: unknown) => Promise<RpcResponse<{ commands: CommandDescriptor[] }>>
+    = () => Promise.resolve(ok({ commands: [] }))
+  onCommandExecute: (payload: unknown) => Promise<RpcResponse<{ matched: boolean; result?: CommandExecuteResult }>>
+    = () => Promise.resolve(ok({ matched: false }))
+  onSkillList: (payload: unknown) => Promise<RpcResponse<{ skills: SkillEntry[] }>>
+    = () => Promise.resolve(ok({ skills: [] }))
+
+  readonly commands: IApiClient['commands'] = {
+    list: (payload: unknown) => this.record('command.list', payload, this.onCommandList(payload)),
+    execute: (payload: unknown) => this.record('command.execute', payload, this.onCommandExecute(payload)),
+  }
+
+  readonly skills: IApiClient['skills'] = {
+    list: (payload: unknown) => this.record('skill.list', payload, this.onSkillList(payload)),
+  }
+
   /** When true, streams never fire onOpen (misbehaving-carrier material for the handshake timeout guard). */
   suppressStreamOpen = false
 

packages/client/runtime/tests/lineage.spec.ts

@@ -8,7 +8,7 @@ import type { SessionId, SessionSummary } from '@deepseek-ai/dsh-client-connecti
 import { flattenLineage } from '../src/client/sessions/lineage.ts'
 
 const s = (id: string, updatedAt: number, parent?: string): SessionSummary => ({
-  sessionId: id as SessionId, updatedAt, running: false,
+  sessionId: id as SessionId, updatedAt, running: false, blank: false,
   ...(parent !== undefined ? { parentSessionId: parent as SessionId } : {}),
 })
 

packages/client/runtime/tests/manager.spec.ts

@@ -12,8 +12,10 @@ import { entries, plainTurn } from './event-script.ts'
 const S1 = 'fk-m1' as SessionId
 const S2 = 'fk-m2' as SessionId
 
-function summary(sessionId: SessionId, over: Partial<{ updatedAt: number; running: boolean; parentSessionId: SessionId }> = {}) {
-  return { sessionId, updatedAt: 100, running: false, ...over }
+type SummaryOver = Partial<{ updatedAt: number; running: boolean; blank: boolean; parentSessionId: SessionId }>
+
+function summary(sessionId: SessionId, over: SummaryOver = {}) {
+  return { sessionId, updatedAt: 100, running: false, blank: false, ...over }
 }
 
 describe('instances', () => {
@@ -81,7 +83,7 @@ describe('list lifecycle', () => {
     const hydration = manager.refreshList()
     manager.handleHostEnvelope({
       rpcId: 'during-first' as never,
-      payload: { type: 'host/session-added', sessionId: S2 },
+      payload: { type: 'host/session-added', blank: true, sessionId: S2 },
     })
     first.resolve(ok({ items: [summary(S1)] as never[] }))
     await hydration
@@ -157,7 +159,7 @@ describe('list lifecycle', () => {
     expect(titled.items[1]?.title).toBeUndefined()
 
     manager.handleHostEnvelope({ rpcId: 'removed' as never, payload: { type: 'host/session-removed', sessionId: S1 } })
-    manager.handleHostEnvelope({ rpcId: 'readded' as never, payload: { type: 'host/session-added', sessionId: S1 } })
+    manager.handleHostEnvelope({ rpcId: 'readded' as never, payload: { type: 'host/session-added', blank: true, sessionId: S1 } })
     expect(manager.getListSnapshot().items.find(item => item.sessionId === S1)?.title).toBeUndefined()
   })
 
@@ -196,8 +198,8 @@ describe('host frame routing', () => {
   it('adds/removes/flips sessions from host frames and keeps removed instances resident', async () => {
     const api = new FakeApiClient()
     const manager = new SessionManager(api)
-    manager.handleHostEnvelope({ rpcId: 'h1' as never, payload: { type: 'host/session-added', sessionId: S1 } })
-    manager.handleHostEnvelope({ rpcId: 'h2' as never, payload: { type: 'host/session-added', sessionId: S1 } }) // dup: ignored
+    manager.handleHostEnvelope({ rpcId: 'h1' as never, payload: { type: 'host/session-added', blank: true, sessionId: S1 } })
+    manager.handleHostEnvelope({ rpcId: 'h2' as never, payload: { type: 'host/session-added', blank: true, sessionId: S1 } }) // dup: ignored
     expect(manager.getListSnapshot().items).toHaveLength(1)
 
     const session = manager.get(S1)
@@ -273,14 +275,14 @@ describe('remaining branches', () => {
 
     manager.handleHostEnvelope({
       rpcId: 'published-later' as never,
-      payload: { type: 'host/session-added', sessionId: S1, cwd: '/w/one' },
+      payload: { type: 'host/session-added', blank: true, 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' },
+      payload: { type: 'host/session-added', blank: true, sessionId: S1, cwd: '/w/one' },
     })
     expect(manager.getListSnapshot().items).toHaveLength(1)
   })
@@ -295,7 +297,7 @@ describe('remaining branches', () => {
     expect(notified).toBeGreaterThan(0)
     const seen = notified
     unsubscribe()
-    manager.handleHostEnvelope({ rpcId: 'h' as never, payload: { type: 'host/session-added', sessionId: S1 } })
+    manager.handleHostEnvelope({ rpcId: 'h' as never, payload: { type: 'host/session-added', blank: true, sessionId: S1 } })
     await new Promise(resolve => setTimeout(resolve, 0))
     expect(notified).toBe(seen)
   })
@@ -334,8 +336,8 @@ describe('remaining branches', () => {
   it('carries parentSessionId from host/session-added into the lineage row', () => {
     const api = new FakeApiClient()
     const manager = new SessionManager(api)
-    manager.handleHostEnvelope({ rpcId: 'h1' as never, payload: { type: 'host/session-added', sessionId: S1 } })
-    manager.handleHostEnvelope({ rpcId: 'h2' as never, payload: { type: 'host/session-added', sessionId: S2, parentSessionId: S1 } })
+    manager.handleHostEnvelope({ rpcId: 'h1' as never, payload: { type: 'host/session-added', blank: true, sessionId: S1 } })
+    manager.handleHostEnvelope({ rpcId: 'h2' as never, payload: { type: 'host/session-added', blank: true, sessionId: S2, parentSessionId: S1 } })
     const items = manager.getListSnapshot().items
     expect(items.find(e => e.sessionId === S2)).toMatchObject({ parentSessionId: S1, depth: 1 })
   })

packages/client/runtime/tests/queue-store.spec.ts

@@ -0,0 +1,193 @@
+/**
+ * Queue mirror semantics (web input-triggers queue cut 1): session/queued
+ * intake, host-rule retirement (message turn/start claims oldest non-steering;
+ * steering/message drains by source), leave-running sweep, reconnect reset,
+ * pre-instantiation buffering, and snapshot reference stability.
+ */
+import { describe, expect, it } from 'vitest'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { MuxFrame, RpcId, SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import { Session } from '../src/client/sessions/session.ts'
+import { SessionManager } from '../src/client/sessions/manager.ts'
+import { FakeApiClient } from './fake-api.ts'
+import { ev } from './event-script.ts'
+
+const SID = 'fk-q1' as SessionId
+const text = (t: string): ContentBlock[] => [{ type: 'text', text: t }]
+const rid = (id: string): RpcId => id as RpcId
+
+/** session/queued frame with the wire-sourced rpcId key (the host prompt path). */
+function queuedFrame(body: string, rpcId: string, steering = false): MuxFrame {
+  return {
+    type: 'session/queued', sessionId: SID, content: text(body),
+    source: { kind: 'user', rpcId: rid(rpcId) } as never, steering,
+  }
+}
+
+function makeSession(): Session {
+  return new Session(SID, new FakeApiClient())
+}
+
+describe('queue intake', () => {
+  it('lands a queued frame as a row keyed by the source rpcId with a flat preview', () => {
+    const session = makeSession()
+    session.handleMuxEnvelope(rid('env-1'), queuedFrame('第一条  排队\n消息', 'p-1'))
+    const queue = session.getSnapshot().queue
+    expect(queue).toEqual([{ key: 'p-1', preview: '第一条 排队 消息' }])
+  })
+
+  it('falls back to the envelope rpcId when the source carries none, and tags non-text blocks', () => {
+    const session = makeSession()
+    session.handleMuxEnvelope(rid('env-2'), {
+      type: 'session/queued', sessionId: SID,
+      content: [{ type: 'text', text: 'hi' }, { type: 'image', data: 'x' } as never],
+      source: { kind: 'plugin', plugin: 'loop' }, steering: false,
+    })
+    expect(session.getSnapshot().queue).toEqual([{ key: 'f:env-2', preview: 'hi [image]' }])
+  })
+
+  it('caps the preview at 200 code points with an ellipsis', () => {
+    const session = makeSession()
+    session.handleMuxEnvelope(rid('env-3'), queuedFrame('长'.repeat(201), 'p-cap'))
+    const preview = session.getSnapshot().queue[0]?.preview ?? ''
+    expect(Array.from(preview)).toHaveLength(201) // 200 + …
+    expect(preview.endsWith('…')).toBe(true)
+  })
+
+  it('keeps the queue array reference stable across unrelated snapshot swaps', () => {
+    const session = makeSession()
+    session.handleMuxEnvelope(rid('env-4'), queuedFrame('稳定', 'p-s'))
+    const before = session.getSnapshot().queue
+    session.handleAgentError('unrelated') // dirties the snapshot without touching the queue
+    expect(session.getSnapshot().queue).toBe(before)
+  })
+})
+
+describe('queue retirement (host queuedMirror rules)', () => {
+  it('a message-triggered turn/start claims the oldest non-steering row', () => {
+    const session = makeSession()
+    session.handleMuxEnvelope(rid('e1'), queuedFrame('先', 'p-1'))
+    session.handleMuxEnvelope(rid('e2'), queuedFrame('后', 'p-2'))
+    session.handleMuxEnvelope(rid('e3'), { type: 'session/event', sessionId: SID, event: ev.turnStart(0, 0) })
+    expect(session.getSnapshot().queue.map(r => r.key)).toEqual(['p-2'])
+  })
+
+  it('an injection-triggered turn/start claims nothing', () => {
+    const session = makeSession()
+    session.handleMuxEnvelope(rid('e1'), queuedFrame('留', 'p-1'))
+    const injection = {
+      ...ev.turnStart(0, 0),
+      data: { turn: 0, trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'x' } } },
+    } as never
+    session.handleMuxEnvelope(rid('e2'), { type: 'session/event', sessionId: SID, event: injection })
+    expect(session.getSnapshot().queue).toHaveLength(1)
+  })
+
+  it('steering/message drains the source-matched steering row only', () => {
+    const session = makeSession()
+    session.handleMuxEnvelope(rid('e1'), queuedFrame('普通', 'p-1'))
+    session.handleMuxEnvelope(rid('e2'), queuedFrame('插话', 'p-2', true))
+    // Loop-authored steering (different source) must not consume the user entry.
+    const foreignSteering = {
+      seq: 0, time: 1,
+      type: 'steering/message', surfaceOp: 'append',
+      data: { turn: 0, content: text('loop'), source: { kind: 'plugin', plugin: 'loop' } },
+    } as never
+    session.handleMuxEnvelope(rid('e3'), { type: 'session/event', sessionId: SID, event: foreignSteering })
+    expect(session.getSnapshot().queue).toHaveLength(2)
+    const matchedSteering = {
+      seq: 1, time: 2,
+      type: 'steering/message', surfaceOp: 'append',
+      data: { turn: 0, content: text('插话'), source: { kind: 'user', rpcId: rid('p-2') } },
+    } as never
+    session.handleMuxEnvelope(rid('e4'), { type: 'session/event', sessionId: SID, event: matchedSteering })
+    expect(session.getSnapshot().queue.map(r => r.key)).toEqual(['p-1'])
+  })
+
+  it('a leave-running flip sweeps the whole mirror (cancel/terminal-drop cover)', () => {
+    const session = makeSession()
+    session.handleRunning(true)
+    session.handleMuxEnvelope(rid('e1'), queuedFrame('一', 'p-1'))
+    session.handleMuxEnvelope(rid('e2'), queuedFrame('二', 'p-2', true))
+    session.handleRunning(false)
+    expect(session.getSnapshot().queue).toEqual([])
+  })
+
+  it('a stale not-running relay on an idle session still sweeps replayed rows', () => {
+    const session = makeSession()
+    session.handleMuxEnvelope(rid('e1'), queuedFrame('孤儿', 'p-1'))
+    session.handleRunning(false) // running already false: equality path must not skip the sweep
+    expect(session.getSnapshot().queue).toEqual([])
+  })
+})
+
+describe('queue reconnect semantics', () => {
+  it('session/subscribed re-baselines the mirror: stale rows drop, the following snapshot lands fresh', () => {
+    const session = makeSession()
+    session.handleMuxEnvelope(rid('e1'), queuedFrame('旧连接', 'p-old'))
+    // New mux generation: subscribed arrives first on the same stream...
+    session.handleMuxEnvelope(rid('e2'), { type: 'session/subscribed', sessionId: SID, lastSeq: 10 })
+    expect(session.getSnapshot().queue).toEqual([])
+    // ...then the queue snapshot replays the live inbox.
+    session.handleMuxEnvelope(rid('e3'), queuedFrame('新基线', 'p-new'))
+    expect(session.getSnapshot().queue.map(r => r.key)).toEqual(['p-new'])
+  })
+
+  it('resync must NOT clear the mirror (regression: onConnected races the mux baseline)', async () => {
+    const session = makeSession()
+    // Reconnect ordering that broke: mux opened first and already delivered
+    // the fresh generation's baseline; host stream (and with it onConnected →
+    // resync) lands after. The host never resends — clearing here left the
+    // dock empty until the next enqueue.
+    session.handleMuxEnvelope(rid('e1'), { type: 'session/subscribed', sessionId: SID, lastSeq: 5 })
+    session.handleMuxEnvelope(rid('e2'), queuedFrame('新基线', 'p-fresh'))
+    await session.resync()
+    expect(session.getSnapshot().queue.map(r => r.key)).toEqual(['p-fresh'])
+  })
+})
+
+describe('manager buffering of queued frames', () => {
+  it('buffers session/queued for uninstantiated sessions and replays before the running sync', () => {
+    const api = new FakeApiClient()
+    const manager = new SessionManager(api)
+    manager.handleMuxEnvelope({ rpcId: rid('b1'), payload: queuedFrame('预热', 'p-b1') })
+    // Instantiation replays the buffer; no summary exists, so no running sweep runs.
+    const session = manager.get(SID)
+    expect(session.getSnapshot().queue.map(r => r.key)).toEqual(['p-b1'])
+    // The buffer is consumed: a second get must not double-replay.
+    expect(manager.get(SID).getSnapshot().queue).toHaveLength(1)
+  })
+
+  it('a not-running list summary sweeps replayed rows at instantiation', async () => {
+    const api = new FakeApiClient()
+    api.onList = () => Promise.resolve(ok([{ sessionId: SID, updatedAt: 1, running: false }]))
+    const manager = new SessionManager(api)
+    await manager.refreshList()
+    manager.handleMuxEnvelope({ rpcId: rid('b2'), payload: queuedFrame('该扫掉', 'p-b2') })
+    expect(manager.get(SID).getSnapshot().queue).toEqual([])
+  })
+
+  it('subscribed re-baselines the uninstantiated buffer: stale queued frames drop, non-queue frames survive (regression: reconnect duplication)', () => {
+    const api = new FakeApiClient()
+    const manager = new SessionManager(api)
+    // Generation 1 baseline lands while the session is uninstantiated, along
+    // with a pending approval (never re-derivable from history).
+    manager.handleMuxEnvelope({ rpcId: rid('g1a'), payload: queuedFrame('第一代', 'p-g1') })
+    manager.handleMuxEnvelope({
+      rpcId: rid('g1b'),
+      payload: { type: 'approval/requested', sessionId: SID, approvalId: 'ap-1' as never, toolName: 'bash' },
+    })
+    // Reconnect: generation 2 replays subscribed + the SAME live queue entry.
+    manager.handleMuxEnvelope({ rpcId: rid('g2a'), payload: { type: 'session/subscribed', sessionId: SID, lastSeq: 3 } })
+    manager.handleMuxEnvelope({ rpcId: rid('g2b'), payload: queuedFrame('第一代', 'p-g1') })
+    const snapshot = manager.get(SID).getSnapshot()
+    // One queue row (no duplicate batch); the approval survived the re-baseline.
+    expect(snapshot.queue.map(r => r.key)).toEqual(['p-g1'])
+    expect(snapshot.pending.map(p => p.kind)).toEqual(['approval'])
+  })
+})
+
+/** ok wrapper with a typed items payload (the shared helper pins value to never[]). */
+function ok(items: { sessionId: SessionId; updatedAt: number; running: boolean }[]) {
+  return { rpcId: rid(`ok-${items.length}`), result: { ok: true as const, value: { items: items as never[] } } }
+}

packages/client/runtime/tests/scope.spec.ts

@@ -0,0 +1,84 @@
+/**
+ * Agent-scope primitive spec: the actx minted by createScope carries the
+ * tag and the dispatch filter itself, so plain cordis dispatch with the actx
+ * as subject routes by agent — same-agent tagged listeners receive,
+ * foreign-agent ones are filtered out, untagged listeners hear everything,
+ * and a subject-less root dispatch stays unfiltered. Scope-owned listeners
+ * dispose with the fiber.
+ */
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import { createScope, scopeOf } from '../src/client/agents/scope.ts'
+
+const sid = (k: string): SessionId => k as SessionId
+
+declare module 'cordis' {
+  interface Events {
+    /**
+     * Test-only routed probe event.
+     * @param payload - marker payload.
+     * @mode bail
+     */
+    'test/scope-probe'(payload: { from: string }): true | undefined
+  }
+}
+
+function bench() {
+  const root = new Context()
+  const a = createScope(root, sid('a'))
+  const b = createScope(root, sid('b'))
+  const seen: string[] = []
+  const listen = (label: string, ctx: Context, answer?: true) => {
+    ctx.on('test/scope-probe', (payload) => {
+      seen.push(`${label}:${payload.from}`)
+      return answer
+    })
+  }
+  return { root, a, b, seen, listen }
+}
+
+describe('createScope', () => {
+  it('tags the ctx (scopeOf) and leaves the root untagged', () => {
+    const { root, a } = bench()
+    expect(scopeOf(a.ctx)).toBe(sid('a'))
+    expect(scopeOf(root)).toBeUndefined()
+  })
+
+  it('scoped dispatch reaches same-session and untagged listeners, never a foreign session', () => {
+    const { root, a, b, seen, listen } = bench()
+    listen('a', a.ctx)
+    listen('b', b.ctx)
+    listen('root', root)
+    a.ctx.bail(a.ctx, 'test/scope-probe', { from: 'a' })
+    expect(seen).toEqual(['a:a', 'root:a'])
+    seen.length = 0
+    b.ctx.emit(b.ctx, 'test/scope-probe', { from: 'b' })
+    expect(seen).toEqual(['b:b', 'root:b'])
+  })
+
+  it('bail answers the first same-scope listener and skips filtered foreign ones', () => {
+    const { a, b, listen } = bench()
+    listen('b', b.ctx, true) // registered first, but foreign → filtered out
+    expect(a.ctx.bail(a.ctx, 'test/scope-probe', { from: 'a' })).toBeUndefined()
+    listen('a', a.ctx, true)
+    expect(a.ctx.bail(a.ctx, 'test/scope-probe', { from: 'a' })).toBe(true)
+  })
+
+  it('a subject-less root dispatch is unfiltered (every listener hears it)', () => {
+    const { root, a, b, seen, listen } = bench()
+    listen('a', a.ctx)
+    listen('b', b.ctx)
+    listen('root', root)
+    root.emit('test/scope-probe', { from: 'root' })
+    expect(seen).toEqual(['a:root', 'b:root', 'root:root'])
+  })
+
+  it('fiber disposal removes scope-owned listeners', async () => {
+    const { a, seen, listen } = bench()
+    listen('a', a.ctx)
+    await a.fiber.dispose()
+    a.ctx.emit(a.ctx, 'test/scope-probe', { from: 'late' })
+    expect(seen).toEqual([])
+  })
+})

packages/client/runtime/tests/session-intents.spec.ts

@@ -1,219 +0,0 @@
-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('echoes updateIntent into the list snapshot in the same tick (controlled-input contract)', async () => {
-    const api = new FakeApiClient()
-    const { sessions, workspaces } = services(api)
-    await ready(api, workspaces, sessions, [workspace('target')])
-    let notified = 0
-    sessions.list.subscribe(() => { notified += 1 })
-    // IME composition drives change events that a controlled textarea must see
-    // reflected before the handler returns; a microtask-deferred echo makes
-    // React roll the DOM back and the composition commits partial keystrokes.
-    sessions.updateIntent('你')
-    expect(sessions.list.getSnapshot().intent?.prompt).toBe('你')
-    expect(notified).toBeGreaterThan(0)
-  })
-
-  it('ignores updateIntent with no active Intent', async () => {
-    const api = new FakeApiClient()
-    const { sessions, workspaces } = services(api)
-    await ready(api, workspaces, sessions, [workspace('only', [sid('s-real')])], [
-      { sessionId: sid('s-real'), updatedAt: 1, running: false },
-    ])
-    sessions.open(sid('s-real'))
-    expect(sessions.list.getSnapshot().intent).toBeUndefined()
-    let notified = 0
-    sessions.list.subscribe(() => { notified += 1 })
-    sessions.updateIntent('dropped')
-    expect(notified).toBe(0)
-  })
-
-  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])
-  })
-})

packages/client/runtime/tests/session.spec.ts

@@ -22,9 +22,9 @@ function makeSession(api = new FakeApiClient()): { api: FakeApiClient; session:
   return { api, session: new Session(SID, api) }
 }
 
-function histResponse(events: SessionEvent[], hasMore = false) {
+function histResponse(events: SessionEvent[], hasMore = false, todos?: { content: string; status: 'pending' | 'in_progress' | 'completed' }[]) {
   // history now returns HistoryEntry[] ({event, view?}); these tests are view-less.
-  return Promise.resolve(ok({ events: entries(events) as never[], hasMore }))
+  return Promise.resolve(ok({ events: entries(events) as never[], hasMore, ...todos === undefined ? {} : { todos } }))
 }
 
 describe('open', () => {
@@ -153,6 +153,42 @@ describe('live event path', () => {
     })
   })
 
+  it('folds todo/write into snapshot.todos last-write-wins, live and on window replay', async () => {
+    const listA = [{ content: '搭骨架', status: 'completed' as const }, { content: '写组件', status: 'in_progress' as const }]
+    const listB = [{ content: '搭骨架', status: 'completed' as const }, { content: '写组件', status: 'completed' as const }]
+    const { session } = await opened()
+    expect(session.getSnapshot().todos).toEqual([])
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.todoWrite(6, listA))
+    expect(session.getSnapshot().todos).toEqual(listA)
+    feed(ev.todoWrite(7, listB))
+    expect(session.getSnapshot().todos).toEqual(listB)
+    // Window replay converges on the same last snapshot (history contains both writes).
+    const replayed = makeSession()
+    replayed.api.onHistory = () => histResponse([...plainTurn(0, 0, 'a', 'b'), ev.todoWrite(6, listA), ev.todoWrite(7, listB)])
+    await replayed.session.open()
+    expect(replayed.session.getSnapshot().todos).toEqual(listB)
+  })
+
+  it('seeds todos from the tail page projection when the last write precedes the window', async () => {
+    const list = [{ content: '窗口外的计划', status: 'in_progress' as const }]
+    // Cold open: the page window carries NO todo/write; the projection rides the response.
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(100, 9, '问', '答'), true, list)
+    await session.open()
+    expect(session.getSnapshot().todos).toEqual(list)
+    // Paging an older window in must not clear the session-level projection.
+    api.onHistory = () => histResponse(plainTurn(94, 8, '旧问', '旧答'), false)
+    await session.loadOlder()
+    expect(session.getSnapshot().todos).toEqual(list)
+    // A later live write still overrides the seeded projection.
+    session.handleMuxEnvelope('r' as never, {
+      type: 'session/event', sessionId: SID,
+      event: ev.todoWrite(106, [{ content: '新计划', status: 'pending' as const }]),
+    })
+    expect(session.getSnapshot().todos).toEqual([{ content: '新计划', status: 'pending' }])
+  })
+
   it('repairs a seq gap by repulling the tail page instead of appending a hole', async () => {
     const { api, session } = await opened(plainTurn(0, 0, 'a', 'b')) // tail seq = 5
     const repaired = [...plainTurn(0, 0, 'a', 'b'), ...plainTurn(6, 1, 'c', 'd')]
@@ -166,6 +202,37 @@ describe('live event path', () => {
     const seqs = session.getSnapshot().nodes.map(n => n.seq)
     expect(seqs).toEqual([1, 3, 7, 9]) // both turns' user/assistant, no hole, no duplicate 9
   })
+
+  it('gap repair adopts the repull response projection (a missed todo/write outside the new tail page)', async () => {
+    const { api, session } = await opened(plainTurn(0, 0, 'a', 'b')) // tail seq = 5
+    expect(session.getSnapshot().todos).toEqual([])
+    // The missed range contained a todo/write that the repulled page no longer
+    // covers; the response's session-level projection is the only carrier.
+    const current = [{ content: '断线期间写的', status: 'in_progress' as const }]
+    api.onHistory = () => histResponse([...plainTurn(0, 0, 'a', 'b'), ...plainTurn(8, 1, 'c', 'd')], false, current)
+    session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.assistant(11, 1, 'd') })
+    await vi.waitFor(() => {
+      expect(api.callsOf('session.history').length).toBe(2)
+    })
+    await Promise.resolve()
+    expect(session.getSnapshot().todos).toEqual(current)
+  })
+
+  it('clears the plan when a tail response omits the projection (a write the log never kept)', async () => {
+    // Live write lands, then the host crashes before persisting it: the
+    // authoritative log holds no todo/write, so the resync tail response
+    // carries no projection — an omitted field on a tail request is the empty
+    // list, not a missing carrier, and the rolled-back plan must disappear.
+    const { api, session } = await opened(plainTurn(0, 0, 'a', 'b'))
+    session.handleMuxEnvelope('r' as never, {
+      type: 'session/event', sessionId: SID,
+      event: ev.todoWrite(6, [{ content: '丢失的计划', status: 'in_progress' as const }]),
+    })
+    expect(session.getSnapshot().todos).toEqual([{ content: '丢失的计划', status: 'in_progress' }])
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    await session.resync()
+    expect(session.getSnapshot().todos).toEqual([])
+  })
 })
 
 describe('paging', () => {
@@ -644,6 +711,95 @@ describe('resync', () => {
   })
 })
 
+describe('run_code sub-dispatch indexing', () => {
+  it('a start event lands as a running-shaped sub-call and its settle replaces it in place', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, '问', '答'))
+    await session.open()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"1","description":"d"}'))
+    feed(ev.codeDispatchStart(8, 'p1', 1, 'bash', { command: 'sleep' }))
+    feed(ev.codeDispatchStart(9, 'p1', 2, 'read', { path: 'a.txt' }))
+    const live = session.getSnapshot().codeDispatches.get('p1')
+    expect(live).toHaveLength(2)
+    // Running shape (no 'kind'): the exact RunningToolCall form native rows use.
+    expect(live?.[0]).toMatchObject({ callId: 'p1:code:1', name: 'bash', argsRaw: '{"command":"sleep"}' })
+    expect(live?.[0] !== undefined && 'kind' in live[0]).toBe(false)
+    // Settle out of order (parallel run): #2 first — replaces in place, keeping start order.
+    feed(ev.codeDispatch(10, 'p1', 2, 'read', { path: 'a.txt' }, 'alpha'))
+    const mixed = session.getSnapshot().codeDispatches.get('p1')
+    expect(mixed?.map(sub => 'kind' in sub)).toEqual([false, true])
+    expect(mixed?.[1]).toMatchObject({ callId: 'p1:code:2', content: [{ type: 'text', text: 'alpha' }] })
+    // The settle carries the paired start's time as callTime (duration source).
+    feed(ev.codeDispatch(11, 'p1', 1, 'bash', { command: 'sleep' }, 'done'))
+    const settled = session.getSnapshot().codeDispatches.get('p1')
+    expect(settled?.map(sub => 'kind' in sub)).toEqual([true, true])
+    expect(settled?.[0]).toMatchObject({ callId: 'p1:code:1', callTime: 1_700_000_000_008 })
+  })
+
+  it('indexes live tool/code-dispatch events under their parent as native-shaped result nodes', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, '问', '答'))
+    await session.open()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"return 1","description":"跑一个程序"}'))
+    feed(ev.codeDispatch(8, 'p1', 1, 'bash', { command: 'ls', description: '列目录' }, 'demo.txt'))
+    feed(ev.codeDispatch(9, 'p1', 2, 'read', { path: 'a.txt' }, 'Error: ENOENT', true))
+    const subs = session.getSnapshot().codeDispatches.get('p1')
+    expect(subs).toHaveLength(2)
+    expect(subs?.[0]).toMatchObject({
+      kind: 'tool-result', callId: 'p1:code:1',
+      call: { name: 'bash', argsRaw: '{"command":"ls","description":"列目录"}' },
+      // The settle event carries no start time: callTime stays null (never a
+      // fabricated zero-duration).
+      callTime: null,
+      isError: false, content: [{ type: 'text', text: 'demo.txt' }],
+    })
+    expect(subs?.[1]).toMatchObject({ callId: 'p1:code:2', isError: true })
+    // No paired start in the window: duration is UNKNOWN (null), never a
+    // fabricated zero-duration span.
+    expect(subs?.[0]).toMatchObject({ callTime: null })
+    // Sub-dispatches never join the surface flow.
+    expect(session.getSnapshot().nodes.some(n => n.kind === 'tool-result' && n.callId.includes(':code:'))).toBe(false)
+  })
+
+  it('rebuilds the same index from a history window (replay parity)', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse([
+      ...plainTurn(0, 0, '问', '答'),
+      ev.turnStart(6, 1),
+      ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"return 1","description":"跑一个程序"}'),
+      ev.codeDispatch(8, 'p1', 1, 'bash', { command: 'ls' }, 'demo.txt'),
+      ev.toolResult(9, 1, 'p1', '{"done":true}'),
+      ev.turnEnd(10, 1),
+    ])
+    await session.open()
+    const subs = session.getSnapshot().codeDispatches.get('p1')
+    expect(subs).toHaveLength(1)
+    expect(subs?.[0]).toMatchObject({ callId: 'p1:code:1', call: { name: 'bash' } })
+  })
+
+  it('keeps the dispatch map reference across unrelated changes and swaps it on a new dispatch', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, '稳', '定'))
+    await session.open()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"1","description":"d"}'))
+    feed(ev.codeDispatch(8, 'p1', 1, 'bash', { command: 'ls' }, 'x'))
+    const before = session.getSnapshot()
+    feed(ev.chunkStart(9, 1))
+    feed(ev.chunkText(10, 1, '流式'))
+    const after = session.getSnapshot()
+    expect(after.codeDispatches).toBe(before.codeDispatches)
+    feed(ev.codeDispatch(11, 'p1', 2, 'read', { path: 'a' }, 'y'))
+    expect(session.getSnapshot().codeDispatches).not.toBe(after.codeDispatches)
+    expect(session.getSnapshot().codeDispatches.get('p1')).toHaveLength(2)
+  })
+})
+
 describe('reference stability (the memo contract)', () => {
   it('keeps unchanged node references across an append and swaps the snapshot object', async () => {
     const { api, session } = makeSession()

packages/client/runtime/tests/sessions-service.spec.ts

@@ -10,7 +10,7 @@ import { Context } from 'cordis'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
 import { SessionCreateError, SessionsService, scopeOf } from '../src/client/sessions/service.ts'
-import { FakeApiClient, ok } from './fake-api.ts'
+import { FakeApiClient, deferred, ok } from './fake-api.ts'
 
 const sid = (s: string): SessionId => s as SessionId
 
@@ -28,10 +28,12 @@ function bench(): Bench {
 }
 
 /** Refresh the manager list from programmable rows and flush the microtask batch. */
-async function feedList(b: Bench, rows: { id: string; cwd?: string; parentId?: string; running?: boolean }[]): Promise<void> {
+type FeedRow = { id: string; cwd?: string; parentId?: string; running?: boolean; blank?: boolean }
+
+async function feedList(b: Bench, rows: FeedRow[]): Promise<void> {
   b.api.onList = () => Promise.resolve(ok({
     items: rows.map(r => ({
-      sessionId: sid(r.id), updatedAt: 1, running: r.running ?? false,
+      sessionId: sid(r.id), updatedAt: 1, running: r.running ?? false, blank: r.blank ?? false,
       ...(r.cwd !== undefined ? { cwd: r.cwd } : {}),
       ...(r.parentId !== undefined ? { parentSessionId: sid(r.parentId) } : {}),
     })),
@@ -61,7 +63,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.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', blank: true, sessionId: sid('s2') } as never })
     await Promise.resolve()
     expect(b.svc.list.getSnapshot().ids).toContain('s2')
   })
@@ -77,7 +79,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.cell('s1')?.session)
+    expect(binding?.session).toBe(b.svc.provideInfo('s1')?.hooks['session'])
     expect(b.svc.binding(sid('s1'))).toBe(binding)
     expect(binding?.ctx).toBe(scoped)
   })
@@ -184,20 +186,20 @@ describe('cell (render-layer session kit)', () => {
   it('resolves an identity-stable {sessionId, session} cell; unknown ids yield undefined', async () => {
     const b = bench()
     await feedList(b, [{ id: 's1' }])
-    const cell = b.svc.cell('s1')
-    expect(cell).toBeDefined()
-    expect(cell?.sessionId).toBe('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()
+    const info = b.svc.provideInfo('s1')
+    expect(info).toBeDefined()
+    expect(info?.sessionId).toBe('s1')
+    // The bundle carries bare observables; hook binding happens in React.
+    expect(info?.hooks['session']).toBe(b.svc.binding(sid('s1'))?.session)
+    expect(b.svc.provideInfo('s1')).toBe(info)
+    expect(b.svc.provideInfo('ghost')).toBeUndefined()
   })
 
-  it('cell()/binding() are pure resolution: no staging, no deferred sweep', async () => {
+  it('provideInfo()/binding() are pure resolution: no staging, no deferred sweep', async () => {
     const b = bench()
     await feedList(b, [{ id: 's1' }, { id: 's2' }])
     b.svc.open(sid('s1')) // staged
-    b.svc.cell('s2') // resolution only — must NOT move the stage
+    b.svc.provideInfo('s2') // resolution only — must NOT move the stage
     b.svc.binding(sid('s2'))
     await feedList(b, [{ id: 's2' }]) // s1 removed: still staged → deferred, scope survives
     expect(b.svc.scope(sid('s1'))).toBeDefined()
@@ -209,7 +211,7 @@ describe('cell (render-layer session kit)', () => {
     const historyCalls = () => b.api.calls.filter(c => c.method === 'session.history')
     // Resolution is addressing, not staging: no window pull.
     b.svc.scope(sid('s1'))
-    b.svc.cell('s1')
+    b.svc.provideInfo('s1')
     b.svc.binding(sid('s1'))
     expect(historyCalls()).toHaveLength(0)
     b.svc.open(sid('s1'))
@@ -296,12 +298,24 @@ describe('create', () => {
     const failure = await b.svc.create({ sessionId: sid('candidate') }).catch((error: unknown) => error)
     expect(failure).toBeInstanceOf(SessionCreateError)
     expect(failure).toMatchObject({
-      requestedSessionId: 'candidate', publishedSessionId: undefined,
+      requestedSessionId: 'candidate',
       rpcError: { code: 'internal', message: '爆了' },
     })
   })
 
-  it('surfaces the definitely published id after Workspace attachment fails', async () => {
+  it('resolves with the session already listed and binding-resolvable (no flush wait)', async () => {
+    const b = bench()
+    b.api.onCreate = () => Promise.resolve(ok({ sessionId: sid('born') }))
+    const born = await b.svc.create({ workspaceId: 'ws' as never })
+    // Synchronously after resolution — the draft hand-off contract: the
+    // create echo IS the entity entering the client's view (blank row +
+    // resolvable scope/binding), no notifier flush in between.
+    expect(b.svc.list.getSnapshot().byId[born]).toMatchObject({ id: 'born', blank: true })
+    expect(b.svc.binding(born)).toBeDefined()
+    expect(b.svc.scope(born)).toBeDefined()
+  })
+
+  it('lists the published id after Workspace attachment fails (publication precedes attachment)', async () => {
     const b = bench()
     b.api.onCreate = () => Promise.resolve({
       rpcId: 'attach' as never,
@@ -318,11 +332,111 @@ describe('create', () => {
       sessionId: sid('published'),
     }).catch((error: unknown) => error)
     await Promise.resolve()
+    expect(failure).toBeInstanceOf(SessionCreateError)
     expect(failure).toMatchObject({
-      publishedSessionId: 'published', requestedSessionId: 'published',
+      requestedSessionId: 'published',
       rpcError: { code: 'workspace-attach-failed' },
     })
-    expect(b.svc.list.getSnapshot().byId[sid('published')]).toMatchObject({ id: 'published' })
+    expect(b.svc.list.getSnapshot().byId[sid('published')]).toMatchObject({ id: 'published', blank: true })
+  })
+})
+
+describe('scope lifecycle rides the list mirror (entity parity: no client-side pre-birth)', () => {
+  it('a session-added frame births the row (blank) and makes the scope resolvable; removal prunes it', async () => {
+    const b = bench()
+    await feedList(b, [])
+    expect(b.svc.scope(sid('s-new'))).toBeUndefined() // not in view: no scope, no exceptions
+    b.svc.handleHostEnvelope({
+      rpcId: 'add' as never,
+      payload: { type: 'host/session-added', sessionId: sid('s-new'), blank: true, cwd: '/w/a' } as never,
+    })
+    await Promise.resolve()
+    const scoped = b.svc.scope(sid('s-new'))
+    expect(scoped).toBeDefined()
+    expect(scopeOf(scoped as Context)).toBe('s-new')
+    b.svc.handleHostEnvelope({
+      rpcId: 'rm' as never,
+      payload: { type: 'host/session-removed', sessionId: sid('s-new') },
+    })
+    await Promise.resolve()
+    expect(b.svc.scope(sid('s-new'))).toBeUndefined()
+  })
+})
+
+describe('blank mirror', () => {
+  it('flips blank=false from the running:true status frame (cross-client conversion)', async () => {
+    const b = bench()
+    await feedList(b, [{ id: 's1', blank: true }])
+    expect(b.svc.list.getSnapshot().byId[sid('s1')]).toMatchObject({ blank: true })
+    b.svc.handleHostEnvelope({
+      rpcId: 'st' as never,
+      payload: { type: 'host/session-status', sessionId: sid('s1'), running: true },
+    })
+    await Promise.resolve()
+    expect(b.svc.list.getSnapshot().byId[sid('s1')]).toMatchObject({ blank: false, running: true })
+    // The instantiated Session mirrors the same flip.
+    expect(b.svc.binding(sid('s1'))?.session.getSnapshot().blank).toBe(false)
+  })
+
+  it('flips blank=false on prompt ACCEPTANCE, not on the attempt', async () => {
+    const b = bench()
+    await feedList(b, [{ id: 's1', blank: true, cwd: '/w/a' }])
+    const session = b.svc.binding(sid('s1'))!.session
+    expect(session.getSnapshot().blank).toBe(true)
+    const gate = deferred<Awaited<ReturnType<FakeApiClient['onPrompt']>>>()
+    b.api.onPrompt = () => gate.promise
+    const send = session.prompt([{ type: 'text', text: 'hi' }], 'queue')
+    // In flight: still blank (the flip point is the success response, which
+    // proves the user message reached the host log).
+    expect(session.getSnapshot().blank).toBe(true)
+    gate.resolve(ok({ accepted: true as const }))
+    await send
+    expect(session.getSnapshot().blank).toBe(false)
+    await Promise.resolve()
+    expect(b.svc.list.getSnapshot().byId[sid('s1')]).toMatchObject({ blank: false })
+  })
+
+  it('keeps a rejected first prompt blank: hidden and still reusable', async () => {
+    const b = bench()
+    await feedList(b, [{ id: 's1', blank: true, cwd: '/w/a' }])
+    const session = b.svc.binding(sid('s1'))!.session
+    b.api.onPrompt = () => Promise.resolve({
+      rpcId: 'busy' as never,
+      result: { ok: false as const, error: { code: 'internal' as const, message: 'agent busy', details: {} } },
+    } as never)
+    const result = await session.prompt([{ type: 'text', text: 'hi' }], 'queue')
+    expect(result.ok).toBe(false)
+    // No flip on failure: local stays aligned with the host authority
+    // (events.length still 0), so the session stays hidden and reusable.
+    expect(session.getSnapshot().blank).toBe(true)
+    await Promise.resolve()
+    expect(b.svc.list.getSnapshot().byId[sid('s1')]).toMatchObject({ blank: true })
+  })
+
+  it('takes session-added blank=true as the hidden birth and list blank as reconnect authority', async () => {
+    const b = bench()
+    await feedList(b, [])
+    b.svc.handleHostEnvelope({
+      rpcId: 'add' as never,
+      payload: { type: 'host/session-added', sessionId: sid('s-new'), blank: true, cwd: '/w/a' } as never,
+    })
+    await Promise.resolve()
+    expect(b.svc.list.getSnapshot().byId[sid('s-new')]).toMatchObject({ blank: true })
+    // Reconnect re-pull: the summary's blank=false wins (authoritative alignment).
+    await feedList(b, [{ id: 's-new', blank: false, cwd: '/w/a' }])
+    expect(b.svc.list.getSnapshot().byId[sid('s-new')]).toMatchObject({ blank: false })
+  })
+
+  it('never re-blanks: a stale blank=true summary cannot hide an engaged session', async () => {
+    const b = bench()
+    await feedList(b, [{ id: 's1', blank: true }])
+    const session = b.svc.binding(sid('s1'))!.session
+    await session.prompt([{ type: 'text', text: 'hi' }], 'queue')
+    await Promise.resolve()
+    expect(b.svc.list.getSnapshot().byId[sid('s1')]).toMatchObject({ blank: false })
+    // The next list pull still claims blank (host hasn't logged the message yet).
+    await feedList(b, [{ id: 's1', blank: true }])
+    expect(b.svc.binding(sid('s1'))?.session.getSnapshot().blank).toBe(false)
   })
 })
 

packages/client/runtime/tests/slots-service.spec.ts

@@ -97,13 +97,17 @@ function fakeWorkspaces() {
   return { list: { getSnapshot: () => state, subscribe: () => () => undefined } }
 }
 
-/** Minimal sessions face for the host seam (list observable + cell). */
+/** Minimal sessions face for the host seam (list observable + provide bundle). */
 function fakeSessions() {
   const state = { ids: [], byId: {}, current: undefined as string | undefined }
   return {
     list: { getSnapshot: () => state, subscribe: () => () => undefined },
-    cell: (id: string) => (id === 'known'
-      ? { sessionId: id, session: { getSnapshot: () => undefined, subscribe: () => () => undefined } }
+    provideInfo: (id: string) => (id === 'known'
+      ? {
+        sessionId: id,
+        hooks: { session: { getSnapshot: () => undefined, subscribe: () => () => undefined } },
+        props: {},
+      }
       : undefined),
   }
 }
@@ -228,13 +232,13 @@ describe('host face', () => {
     expect(host.entriesOf('t.host')).toHaveLength(0)
   })
 
-  it('exposes sessions list/current/cell (current riding the list snapshot)', async () => {
+  it('exposes sessions list/current/provideInfo (current riding the list snapshot)', async () => {
     const bench = await boot()
     const host = captureHost(bench)
     expect(host.sessions.list.getSnapshot()).toMatchObject({ ids: [] })
     expect(host.sessions.current.getSnapshot()).toBeUndefined()
-    expect(host.sessions.cell('known')).toMatchObject({ sessionId: 'known' })
-    expect(host.sessions.cell('ghost')).toBeUndefined()
+    expect(host.sessions.provideInfo('known')).toMatchObject({ sessionId: 'known' })
+    expect(host.sessions.provideInfo('ghost')).toBeUndefined()
   })
 
   it('exposes the independent Workspace list source', async () => {

packages/client/runtime/tests/wire-events.spec.ts

@@ -0,0 +1,55 @@
+/**
+ * Wire-to-typed-event bridge (web input-triggers cut 1): host/commands-changed
+ * → ctx 'commands/changed'; each established connection generation →
+ * ctx 'connection/reset' (the forced cache-invalidation broadcast).
+ */
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import type { ConnectionHandle, ConnectionSinks } from '@deepseek-ai/dsh-client-connection/client'
+import * as RuntimeClient from '../src/client/index.ts'
+import { FakeApiClient } from './fake-api.ts'
+
+interface Bench {
+  ctx: Context
+  sinks: ConnectionSinks | undefined
+}
+
+async function mount(): Promise<Bench> {
+  const ctx = new Context()
+  const api = new FakeApiClient()
+  const bench: Bench = { ctx, sinks: undefined }
+  const handle: ConnectionHandle = {
+    api,
+    start: (sinks) => {
+      bench.sinks = sinks
+      return { stop: () => {} }
+    },
+  }
+  ctx.reflect.provide('connection', handle)
+  await ctx.plugin(RuntimeClient).await()
+  return bench
+}
+
+describe('wire event bridge', () => {
+  it('broadcasts commands/changed on a host/commands-changed frame, not on other host frames', async () => {
+    const bench = await mount()
+    let changed = 0
+    bench.ctx.on('commands/changed', () => { changed++ })
+    bench.sinks?.onHostEnvelope?.({ rpcId: 'r1' as never, payload: { type: 'host/commands-changed' } })
+    expect(changed).toBe(1)
+    bench.sinks?.onHostEnvelope?.({
+      rpcId: 'r2' as never,
+      payload: { type: 'host/session-status', sessionId: 's1' as never, running: true },
+    })
+    expect(changed).toBe(1)
+  })
+
+  it('broadcasts connection/reset on every established generation (reconnect invalidation)', async () => {
+    const bench = await mount()
+    let resets = 0
+    bench.ctx.on('connection/reset', () => { resets++ })
+    bench.sinks?.onConnected?.()
+    bench.sinks?.onConnected?.() // second generation after a reconnect
+    expect(resets).toBe(2)
+  })
+})

packages/client/runtime/tests/workspaces-service.spec.ts

@@ -17,38 +17,6 @@ function workspace(id: string, sessionIds: SessionId[] = [], createdAt = '2026-0
 }
 
 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']>>>()
@@ -108,10 +76,52 @@ describe('WorkspaceManager', () => {
       ok: false, error: { code: 'internal', message: 'create transport' },
     })
   })
+
+  it('replays removal over an in-flight baseline and ignores duplicate or late updates', 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: 'removed' as never,
+      payload: { type: 'host/workspace-removed', workspaceId: wid('gone') },
+    })
+    gate.resolve(ok({ items: [workspace('gone'), workspace('kept')] as never[] }))
+    await hydration
+    expect(manager.getSnapshot().items.map(item => item.workspaceId)).toEqual(['kept'])
+
+    manager.handleHostEnvelope({
+      rpcId: 'late-change' as never,
+      payload: { type: 'host/workspace-changed', workspace: workspace('gone') },
+    })
+    manager.handleHostEnvelope({
+      rpcId: 'duplicate-remove' as never,
+      payload: { type: 'host/workspace-removed', workspaceId: wid('gone') },
+    })
+    expect(manager.getSnapshot().items.map(item => item.workspaceId)).toEqual(['kept'])
+  })
+
+  it('removes from the unary delete echo while a refresh is in flight', async () => {
+    const api = new FakeApiClient()
+    api.onWorkspaceList = () => Promise.resolve(ok({ items: [workspace('gone')] as never[] }))
+    const manager = new WorkspaceManager(api)
+    await manager.refresh()
+    const gate = deferred<Awaited<ReturnType<FakeApiClient['onWorkspaceList']>>>()
+    api.onWorkspaceList = () => gate.promise
+    const refresh = manager.refresh()
+
+    await expect(manager.delete(wid('gone'))).resolves.toMatchObject({ ok: true })
+    expect(api.callsOf('workspace.delete')).toEqual([{ workspaceId: 'gone' }])
+    expect(manager.getSnapshot().items).toEqual([])
+    gate.resolve(ok({ items: [workspace('gone')] as never[] }))
+    await refresh
+    expect(manager.getSnapshot().items).toEqual([])
+  })
 })
 
 describe('WorkspacesService', () => {
-  it('feeds SessionManager readiness and recent-Workspace targeting without changing Host order', async () => {
+  it('feeds readiness and recent-Workspace targeting without changing Host order', async () => {
     const ctx = new Context()
     const api = new FakeApiClient()
     const sessions = new SessionsService(ctx, api)
@@ -127,7 +137,7 @@ describe('WorkspacesService', () => {
     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[],
+      items: [{ sessionId: sid('s-active'), updatedAt: Date.parse('2026-02-01'), running: false, blank: false }] as never[],
     }))
     await sessions.refresh()
     await Promise.resolve()
@@ -136,12 +146,65 @@ describe('WorkspacesService', () => {
       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('connectWorkspace reuses the workspace-matched blank session and creates otherwise', 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('alpha'), workspace('beta')] as never[],
+    }))
+    api.onList = () => Promise.resolve(ok({
+      items: [
+        // Blank session already parked in alpha (cwd == workspace path canon).
+        { sessionId: sid('s-blank'), updatedAt: 2, running: false, blank: true, cwd: '/w/alpha' },
+        // Non-blank sibling in beta must never be reused.
+        { sessionId: sid('s-active'), updatedAt: 3, running: false, blank: false, cwd: '/w/beta' },
+      ] as never[],
+    }))
+    await Promise.all([workspaces.refresh(), sessions.refresh()])
+    await Promise.resolve()
+
+    // Hit: same workspace → the parked blank session comes back, no create RPC.
+    await expect(workspaces.connectWorkspace(wid('alpha'))).resolves.toBe('s-blank')
+    expect(api.callsOf('session.create')).toEqual([])
+    // Resolution guarantee: the id is binding-resolvable synchronously.
+    expect(sessions.binding(sid('s-blank'))).toBeDefined()
+
+    // Miss: beta has only a non-blank session → host create with workspaceId.
+    api.onCreate = () => Promise.resolve(ok({ sessionId: sid('s-fresh') }))
+    await expect(workspaces.connectWorkspace(wid('beta'))).resolves.toBe('s-fresh')
+    expect(api.callsOf('session.create')).toEqual([{ workspaceId: 'beta' }])
+    // Same guarantee on the create arm (draft hand-off writes the machine pre-open).
+    expect(sessions.binding(sid('s-fresh'))).toBeDefined()
+
+    // Unknown workspace fails loud instead of silently creating in nowhere.
+    await expect(workspaces.connectWorkspace(wid('ghost'))).rejects.toThrow(/unknown workspace ghost/)
+  })
+
+  it('a rejected first prompt keeps the blank session eligible for connectWorkspace reuse', 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('alpha')] as never[] }))
+    api.onList = () => Promise.resolve(ok({
+      items: [{ sessionId: sid('s-blank'), updatedAt: 2, running: false, blank: true, cwd: '/w/alpha' }] as never[],
+    }))
+    await Promise.all([workspaces.refresh(), sessions.refresh()])
+    await Promise.resolve()
+    const session = sessions.binding(sid('s-blank'))!.session
+    api.onPrompt = () => Promise.resolve(err({ code: 'internal', message: 'agent busy', details: {} }) as never)
+    await session.prompt([{ type: 'text', text: 'hi' }], 'queue')
+    await Promise.resolve()
+    // Failure leaves blank intact, so the same session is still the reuse hit.
+    await expect(workspaces.connectWorkspace(wid('alpha'))).resolves.toBe('s-blank')
+    expect(api.callsOf('session.create')).toEqual([])
+  })
+
   it('returns created Workspaces and preserves Host business errors', async () => {
     const ctx = new Context()
     const api = new FakeApiClient()
@@ -154,4 +217,20 @@ describe('WorkspacesService', () => {
     }))
     await expect(workspaces.create({ path: '/missing' })).rejects.toThrow(/workspace-invalid-path: missing/)
   })
+
+  it('deletes a Workspace or preserves it when the Host rejects deletion', 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('alpha')] as never[] }))
+    await workspaces.refresh()
+    await expect(workspaces.delete(wid('alpha'))).resolves.toBeUndefined()
+    expect(workspaces.list.getSnapshot().items).toEqual([])
+
+    api.onWorkspaceDelete = () => Promise.resolve(err({
+      code: 'workspace-not-found', message: 'gone', details: { workspaceId: 'ghost' },
+    }))
+    await expect(workspaces.delete(wid('ghost'))).rejects.toThrow(/workspace-not-found: gone/)
+  })
 })

packages/client/ui-command/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-README.md: 6ae1778af1ca38a6c49c7f462e536a9c16c7e6bb
-README.zh.md: 01847710df7c12ace7f87e45abc8e83958469740
+README.md: 17bc4edd7d002d6bba4470c9418a9179b2cb131b
+README.zh.md: 1291556409b993aa893e102386f75c45bb195adf

packages/client/ui-command/README.md

@@ -0,0 +1,26 @@
+# @deepseek-ai/dsh-client-ui-command
+
+English | [中文](README.zh.md)
+
+Client command surface (`ctx.command`): the session-keyed command-directory cache, the `/` command source with matchSpace/matchEnter adjudication hooks, three-kind dispatch (execute / popupSelect / leadingInput), and the popupSelect registration face for business packages. Contract: the [web command surfaces Agent Note](../../../.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md).
+
+`src/client/contract.ts` is the frozen business face: `CommandServiceContract.register(name, spec)` is everything a business package consumes; `CommandUiSpec{options, onSelect}` keeps popup data self-served — the shell component is this package's and business never sees it. Command kinds derive per dispatch, never per registration: a host descriptor with `input` is leadingInput, a registered `CommandUiSpec` is popupSelect, everything else is execute.
+
+`CommandDirectory` (`src/client/directory.ts`) is the one wire-derived cache, keyed by session: every session is agent-backed, so `command.list({sessionId})` is the only address shape and the source's scope-birth `warm` hook prewarms the session's entry. Entries are soft-invalidated by the `commands/changed` typed event (old snapshot serves while the repull flies), hard-invalidated by `connection/reset`, epoch-guarded so a superseded pull can never overwrite a newer one. `matchSpace` answers synchronously from this cache only; `matchEnter` strong-waits it on the SubmitAttempt signal and rejects on warmup failure — a `/` line is never silently downgraded to a plain prompt.
+
+`PopupSelectController` (`src/client/popup.ts`) is the headless shell state: `PopupSelectView` self-registers into `conversation.input.overlay` (the SlotMap key is ui-conversation's; this package pulls the declaration in with a type-only import — no runtime edge). The shell is a transient layer holding focus while open; token-segment consumption after onSelect runs both branches through `consumeTokenSegment` (menu-path span CAS, enter-path bare-token equality) against the draft face the wiring layer binds via `bindDraft`.
+
+The `/client` export surface is the plugin body (`apply`/`inject`), `CommandService`, the directory and popup classes with their state types, and the frozen contract types; the shell component itself is internal to the overlay registration.
+
+## Model Experience
+
+Indirectly, through the host `command.execute` RPC this package's dispatch and `claim.submit` paths trigger: a matched command's handler mutates host domain state that other packages project into the next request (the `/plan` handler flips plan mode, whose owning package injects its `plan:policy` system-prompt section), while the command line itself, the detached result, and every menu/notice rendering stay client-side and never enter the session log.
+
+#### KV Cache effect
+
+None directly; this package neither assembles nor sends a provider request. Command handlers it triggers may change what the owning host packages contribute to the next request's system prompt (a section appearing or disappearing replaces earlier request tokens and invalidates the provider prefix from that point), but that effect is owned and documented by each command's host package.
+
+## Known Limitations and Deferred Work
+
+- **The popupSelect shell has no shipped business consumer** — model selection (host `selectModel`) is the design's reference case and lands with its own feature work; until then the shell is exercised by package tests only.
+- **Detached-result notices fall back to the console off-session** — the fire-and-forget paths route results to the triggering session's composer via `SessionInput.notify`; after session teardown the console line is the only remaining surface.

packages/client/ui-command/README.zh.md

@@ -0,0 +1,26 @@
+# @deepseek-ai/dsh-client-ui-command
+
+[English](README.md) | 中文
+
+客户端命令业务面（`ctx.command`）：以会话为 key 的命令目录缓存、带 matchSpace／matchEnter 裁决钩子的 `/` 命令 source、三型派发（execute／popupSelect／leadingInput），以及面向业务包的 popupSelect 注册面。契约：[Web 命令业务面 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md)。
+
+`src/client/contract.ts` 是冻结的业务表层：`CommandServiceContract.register(name, spec)` 是业务包消费的全部内容；`CommandUiSpec{options, onSelect}` 让 popup 数据自给自足——壳组件归本包所有，业务永远见不到它。命令三型按每次派发派生，绝不在注册时定型：带 `input` 的 host descriptor 是 leadingInput，注册了 `CommandUiSpec` 的是 popupSelect，其余全部是 execute。
+
+`CommandDirectory`（`src/client/directory.ts`）是唯一的 wire 派生缓存，以会话为 key：每个会话恒为 agent-backed，因此 `command.list({sessionId})` 是唯一的寻址形状，source 的 scope 出生 `warm` 钩子会预热该会话的缓存项。缓存项由 `commands/changed` 类型化事件软失效（重拉在途期间旧快照继续服务），由 `connection/reset` 硬失效，并以 epoch 把关，被取代的旧拉取永远无法覆盖更新的结果。`matchSpace` 只凭该缓存同步应答；`matchEnter` 在 SubmitAttempt 信号上强等缓存，预热失败即拒绝——`/` 开头的一行绝不会被静默降级为普通提示词。
+
+`PopupSelectController`（`src/client/popup.ts`）是无头的壳状态：`PopupSelectView` 自行注册进 `conversation.input.overlay`（SlotMap key 归 ui-conversation 所有；本包只以 type-only 导入引入该声明——没有运行时依赖边）。壳是打开期间持有焦点的瞬态层；onSelect 之后的 token 片段消费在两条分支上都经 `consumeTokenSegment` 执行（菜单路径做 span CAS，回车路径做裸 token 相等比较），作用于接线层经 `bindDraft` 绑定的草稿表层。
+
+`/client` 导出表层是插件主体（`apply`／`inject`）、`CommandService`、目录类和 popup 类及其状态类型，以及冻结的契约类型；壳组件本身是 overlay 注册的内部实现。
+
+## 模型体验
+
+间接影响，途径是本包的派发与 `claim.submit` 路径触发的 host `command.execute` RPC：匹配命中的命令，其 handler 会修改 host 领域状态，其他包再把该状态投影进下一个请求（`/plan` 的 handler 翻转 plan 模式，其归属包注入 `plan:policy` 系统提示词 section），而命令行本身、detached result 与所有菜单／notice 渲染都留在客户端，永不进入会话日志。
+
+#### KV Cache 影响
+
+无直接影响；该包既不组装也不发送提供方请求。它触发的命令 handler 可能改变归属 host 包对下一个请求系统提示词的贡献（某个 section 的出现或消失会替换较早的请求 token，并使提供方前缀从该点起失效），但这一影响由各命令的 host 包拥有并记录。
+
+## 已知限制与暂缓事项
+
+- **popupSelect 壳还没有已上架的业务消费者**：模型选择（host `selectModel`）是设计的参照用例，将随其自身的功能工作落地；在此之前，壳只由包测试演练。
+- **脱离会话后，detached result 的 notice 回退到 console**：fire-and-forget 路径经 `SessionInput.notify` 把结果送到触发会话的编辑器；会话拆除后，console 输出行是仅剩的呈现面。

packages/client/ui-command/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-command",
+  "description": "Client command surface: global directory cache, '/' source, three command UI kinds, popupSelect registry",
+  "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",
+      "@deepseek-ai/dsh-client-ui-slash",
+      "@deepseek-ai/dsh-client-ui-conversation"
+    ],
+    "platform": "web"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "clsx": "^2.0.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-connection": "^0.0.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-slash": "^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-connection": "workspace:^",
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slash": "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"
+  ]
+}

packages/client/ui-command/src/client/PopupSelectView.module.css

@@ -0,0 +1,98 @@
+/* Official popupSelect shell card: menu-surface tokens (same family as
+ * ui-primitives Menu.module.css — figma MenuDropdown r12 / hairline /
+ * shadow-lv3), anchored by the conversation.input.overlay slot. */
+
+.card {
+  /* The overlay anchor is a zero-height strip on the composer card's top
+     edge; entries float themselves above it (same rule as MenuView). */
+  position: absolute;
+  bottom: calc(100% + 4px);
+  left: 0;
+  z-index: 100;
+  padding: 4px;
+  display: flex;
+  flex-direction: column;
+  min-width: 220px;
+  max-height: 320px;
+  overflow-y: auto;
+  border: 1px solid var(--dsw-alias-border-inverted);
+  border-radius: 12px;
+  background: var(--dsw-specific-menu);
+  box-shadow: var(--dsw-shadow-lv3);
+  outline: none;
+}
+
+.row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 8px;
+  border-radius: 8px;
+  cursor: pointer;
+  font-size: 13px;
+  color: var(--dsw-alias-text-primary);
+}
+
+.rowActive {
+  background: var(--dsw-alias-fill-hover);
+}
+
+.label {
+  flex: 1;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.detail {
+  font-size: 12px;
+  color: var(--dsw-alias-text-tertiary);
+  white-space: nowrap;
+}
+
+.check {
+  display: inline-flex;
+  color: var(--dsw-alias-text-secondary);
+}
+
+.status {
+  padding: 8px;
+  font-size: 12px;
+  color: var(--dsw-alias-text-tertiary);
+}
+
+.search {
+  margin: 2px 2px 4px;
+  padding: 6px 8px;
+  border: 1px solid var(--dsw-alias-border-inverted);
+  border-radius: 8px;
+  background: transparent;
+  font-size: 13px;
+  color: var(--dsw-alias-text-primary);
+  outline: none;
+}
+
+.error {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 8px;
+  font-size: 12px;
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.errorText {
+  flex: 1;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.retry {
+  padding: 2px 8px;
+  border: 1px solid var(--dsw-alias-border-inverted);
+  border-radius: 6px;
+  background: transparent;
+  font-size: 12px;
+  color: var(--dsw-alias-text-primary);
+  cursor: pointer;
+}

packages/client/ui-command/src/client/PopupSelectView.tsx

@@ -0,0 +1,133 @@
+/**
+ * Official popupSelect shell: renders one session's PopupSelectController
+ * store into the conversation.input.overlay anchor. Unlike the slash menu
+ * (combobox — textarea keeps focus), this shell HOLDS focus while open: the
+ * inner search input takes focus, plain typing filters the loaded options
+ * locally, Enter/↑↓ drive the filtered highlight, Escape dismisses back to
+ * the composer, and ←→ keep the search input's native caret. Any pointer
+ * interaction outside the box dismisses (the click's own target takes
+ * focus). Closed state renders null; the overlay slot stays mounted.
+ */
+import { useEffect, useRef } from 'react'
+import { useSyncExternalStore } from 'react'
+import clsx from 'clsx'
+import { IconCheckOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
+import { filterOptions } from './popup.ts'
+import type { PopupSelectController } from './popup.ts'
+import css from './PopupSelectView.module.css'
+
+/** Injected business face of the popupSelect overlay entry. */
+export interface PopupSelectInjected {
+  /** The session's shell controller (state store + verbs; the view never touches the open-context type). */
+  popup: PopupSelectController
+}
+
+/**
+ * Render the popupSelect shell overlay entry.
+ * @param props - injected face: the session's shell controller.
+ * @returns the select card while open; null while closed.
+ */
+export function PopupSelectView({ popup }: PopupSelectInjected) {
+  const state = useSyncExternalStore(
+    fn => popup.state.subscribe(fn),
+    () => popup.state.getSnapshot(),
+  )
+  const cardRef = useRef<HTMLDivElement>(null)
+  const searchRef = useRef<HTMLInputElement>(null)
+
+  // Focus ownership: the search input grabs on open (the design's
+  // transient-layer rule), and ANY outside pointer interaction dismisses —
+  // capture phase so a click landing anywhere else (textarea included)
+  // closes the shell before its own handlers run; that click's target then
+  // takes focus naturally, so no focusComposer here.
+  useEffect(() => {
+    if (!state.open) return
+    searchRef.current?.focus()
+    const onPointerDown = (ev: PointerEvent): void => {
+      if (cardRef.current !== null && ev.target instanceof Node && cardRef.current.contains(ev.target)) return
+      popup.dismiss()
+    }
+    document.addEventListener('pointerdown', onPointerDown, true)
+    return () => { document.removeEventListener('pointerdown', onPointerDown, true) }
+  }, [state.open, popup])
+
+  if (!state.open) return null
+
+  const rows = filterOptions(state.options, state.search)
+
+  const onKeyDown = (ev: React.KeyboardEvent<HTMLDivElement>): void => {
+    // ArrowLeft/ArrowRight fall through on purpose: the search input keeps
+    // its native caret movement.
+    switch (ev.key) {
+      case 'ArrowDown':
+        ev.preventDefault()
+        popup.move(1)
+        return
+      case 'ArrowUp':
+        ev.preventDefault()
+        popup.move(-1)
+        return
+      case 'Enter':
+        ev.preventDefault()
+        void popup.select(state.active)
+        return
+      case 'Escape':
+        ev.preventDefault()
+        popup.dismiss({ focusComposer: true })
+        return
+      default:
+    }
+  }
+
+  return (
+    <div
+      ref={cardRef}
+      className={css.card}
+      aria-label={`/${String(state.command)} options`}
+      onKeyDown={onKeyDown}
+    >
+      <input
+        ref={searchRef}
+        className={css.search}
+        type="text"
+        placeholder="Search…"
+        aria-label="Filter options"
+        value={state.search}
+        readOnly={state.submitting}
+        onChange={(ev) => { popup.setSearch(ev.currentTarget.value) }}
+      />
+      {state.error !== null && (
+        <div className={css.error} role="alert">
+          <span className={css.errorText}>{state.error}</span>
+          {state.status === 'failed' && (
+            <button type="button" className={css.retry} onClick={() => { popup.retry() }}>Retry</button>
+          )}
+        </div>
+      )}
+      {state.status === 'pending' && <div className={css.status}>Loading options…</div>}
+      {state.submitting && <div className={css.status}>Applying…</div>}
+      {state.status === 'ready' && rows.length === 0 && <div className={css.status}>No options</div>}
+      {state.status === 'ready' && (
+        <div role="listbox" aria-label={`/${String(state.command)} matches`}>
+          {rows.map((option, index) => (
+            <div
+              key={option.id}
+              role="option"
+              aria-selected={index === state.active}
+              className={clsx(css.row, index === state.active && css.rowActive)}
+              // mousedown would race the document capture listener; the shell
+              // owns focus anyway, so a plain click (inside the card → no
+              // dismiss) works.
+              onClick={() => { void popup.select(index) }}
+              onMouseEnter={() => { popup.highlight(index) }}
+            >
+              <span className={css.label}>{option.label}</span>
+              {option.detail !== undefined && <span className={css.detail}>{option.detail}</span>}
+              {option.active === true && <span className={css.check}><IconCheckOutline16 /></span>}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}

packages/client/ui-command/src/client/contract.ts

@@ -0,0 +1,55 @@
+/**
+ * Frozen contract of the client command surface. Types only. The
+ * CommandService (`ctx.command`) implements this face; business packages
+ * consume `register` alone.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ClientSessionContext } from '@deepseek-ai/dsh-client-ui-slash/client'
+
+/** One option row of a popupSelect shell. */
+export interface SelectOption {
+  readonly id: string
+  readonly label: string
+  readonly detail?: string
+  readonly active?: boolean
+}
+
+/**
+ * Business registration for the popupSelect command kind. Data is
+ * self-served: options/onSelect use the business package's own protocol.
+ * The shell component is owned by ui-command; business never sees it. Both
+ * callbacks receive the ClientSessionContext captured at popup open.
+ */
+export type CommandUiSpec = {
+  readonly kind: 'popupSelect'
+  options(session: ClientSessionContext, signal: AbortSignal): Promise<readonly SelectOption[]>
+  onSelect(option: SelectOption, session: ClientSessionContext): void | Promise<void>
+}
+
+/**
+ * One client-owned command contribution: a slash-menu entry whose behavior
+ * lives entirely on the client (no host descriptor). Merged with the host
+ * catalog by name — a collision with a host command fails loud at candidate
+ * synthesis, never shadows.
+ */
+export interface CommandContribution {
+  /** Command name without the leading slash (unique across contributions). */
+  readonly name: string
+  /** Menu row description. */
+  readonly description: string
+  /** Capability filter, called with a fresh projection per candidate pass. */
+  available(session: ClientSessionContext): boolean
+  /** The command's UI behavior (this phase: popupSelect only). */
+  readonly ui: CommandUiSpec
+}
+
+/** The `ctx.command` service face visible to business packages. */
+export interface CommandServiceContract {
+  /**
+   * Register one client command contribution; effect disposer. Duplicate
+   * names throw at registration.
+   */
+  register(contribution: CommandContribution): () => void
+  /** Resolve the per-session popup controller for one session scope (wiring/overlay layer). */
+  popupFor(actx: ClientContext): unknown
+}

packages/client/ui-command/src/client/directory.ts

@@ -0,0 +1,175 @@
+/**
+ * Command-directory cache keyed by session: one entry per served catalog —
+ * every session is agent-backed, so `command.list({sessionId})` is the only
+ * address shape. Each entry keeps the single-flight / soft-hard invalidation
+ * / epoch-guard behavior of the original global cache; the session-key axis
+ * is the only extra dimension.
+ */
+import type { IApiClient, SessionId } from '@deepseek-ai/dsh-client-connection/client'
+
+/** command.list success value, derived so the wire type authority stays in apiproxy. */
+type ListValue = Extract<Awaited<ReturnType<IApiClient['commands']['list']>>['result'], { ok: true }>['value']
+
+/** One host command descriptor as served to the client. */
+export type CommandDescriptor = ListValue['commands'][number]
+
+/**
+ * cold = never pulled; pending = pull in flight with nothing servable;
+ * ready = snapshot serving (a soft-invalidate repull keeps this status);
+ * failed = last winning pull rejected, snapshot dropped.
+ */
+export type DirectoryStatus = 'cold' | 'pending' | 'ready' | 'failed'
+
+/** Injected pull (the service binds command.list off the root connection). */
+export type FetchCommands = (sessionId: SessionId) => Promise<readonly CommandDescriptor[]>
+
+/** One session key's cache cell. */
+class Entry {
+  state: DirectoryStatus = 'cold'
+  commands: readonly CommandDescriptor[] = []
+  /** Bumped at each pull start; only the latest pull may publish its outcome. */
+  epoch = 0
+  lastError: unknown
+  waiters: Array<() => void> = []
+}
+
+/** The session-keyed directory cache. Plain class — the owning service wires events and RPC. */
+export class CommandDirectory {
+  private readonly entries = new Map<SessionId, Entry>()
+
+  constructor(private readonly fetchCommands: FetchCommands) {}
+
+  /**
+   * Current cache status for one session.
+   * @param sessionId - session key.
+   * @returns the entry status (cold when never touched).
+   */
+  status(sessionId: SessionId): DirectoryStatus {
+    return this.entries.get(sessionId)?.state ?? 'cold'
+  }
+
+  /**
+   * Synchronous exact-name lookup over one session's hot snapshot.
+   * @param sessionId - session key.
+   * @param name - command name without the leading slash.
+   * @returns the descriptor, or undefined when absent or the entry is not ready.
+   */
+  resolve(sessionId: SessionId, name: string): CommandDescriptor | undefined {
+    const entry = this.entries.get(sessionId)
+    if (entry === undefined || entry.state !== 'ready') return undefined
+    return entry.commands.find(c => c.name === name)
+  }
+
+  /** Soft invalidation (commands-changed): background repull on every touched key; ready snapshots keep serving. */
+  invalidateAll(): void {
+    for (const key of this.entries.keys()) void this.refresh(key)
+  }
+
+  /**
+   * Hard reset on reconnect: every entry drops its snapshot (the agent world
+   * may have changed shape across the generation) and prewarms.
+   */
+  resetConnected(): void {
+    for (const [key, entry] of this.entries) {
+      entry.state = 'cold'
+      entry.commands = []
+      void this.refresh(key)
+    }
+  }
+
+  /**
+   * Fire-and-forget prewarm of one session (the command source's scope-birth
+   * warm hook lands here).
+   * @param sessionId - session key.
+   */
+  warm(sessionId: SessionId): void {
+    const entry = this.entry(sessionId)
+    if (entry.state === 'cold' || entry.state === 'failed') void this.refresh(sessionId)
+  }
+
+  /**
+   * Start one pull for one session. Publishes ready/failed only while it is
+   * still the key's latest pull (epoch guard); a ready snapshot is not
+   * demoted while the pull flies.
+   * @param sessionId - session key.
+   * @returns settled when this pull's outcome is published or discarded.
+   */
+  async refresh(sessionId: SessionId): Promise<void> {
+    const entry = this.entry(sessionId)
+    const epoch = ++entry.epoch
+    if (entry.state !== 'ready') entry.state = 'pending'
+    try {
+      const commands = await this.fetchCommands(sessionId)
+      if (epoch !== entry.epoch) return
+      entry.commands = commands
+      entry.state = 'ready'
+      entry.lastError = undefined
+    } catch (error) {
+      if (epoch !== entry.epoch) return
+      entry.commands = []
+      entry.state = 'failed'
+      entry.lastError = error
+    } finally {
+      if (epoch === entry.epoch) notifyWaiters(entry)
+    }
+  }
+
+  /**
+   * Strong-wait until one session's catalog is servable (the enter-
+   * adjudication "directory must be reached" rule): ready returns at once;
+   * cold/failed launch a fresh pull; pending joins the flying one. Rejects
+   * when the awaited pull fails or the signal aborts.
+   * @param sessionId - session key.
+   * @param signal - attempt-scoped abort (the SubmitAttempt signal).
+   * @returns the hot command snapshot.
+   */
+  async ensureReady(sessionId: SessionId, signal: AbortSignal): Promise<readonly CommandDescriptor[]> {
+    const entry = this.entry(sessionId)
+    while (true) {
+      if (entry.state === 'ready') return entry.commands
+      if (entry.state !== 'pending') void this.refresh(sessionId)
+      await settled(entry, signal)
+      if (entry.state === 'failed') {
+        throw new Error(`command directory warmup failed: ${entry.lastError instanceof Error ? entry.lastError.message : String(entry.lastError)}`)
+      }
+      // Still pending (the awaited pull was superseded) → wait for the winner.
+    }
+  }
+
+  private entry(sessionId: SessionId): Entry {
+    let entry = this.entries.get(sessionId)
+    if (entry === undefined) {
+      entry = new Entry()
+      this.entries.set(sessionId, entry)
+    }
+    return entry
+  }
+}
+
+/** One settlement tick for one entry: resolves at the next winning publish, rejects on abort. */
+function settled(entry: Entry, signal: AbortSignal): Promise<void> {
+  if (signal.aborted) return Promise.reject(abortReason(signal))
+  return new Promise((resolve, reject) => {
+    const waiter = (): void => {
+      signal.removeEventListener('abort', onAbort)
+      resolve()
+    }
+    const onAbort = (): void => {
+      entry.waiters = entry.waiters.filter(w => w !== waiter)
+      reject(abortReason(signal))
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+    entry.waiters.push(waiter)
+  })
+}
+
+function notifyWaiters(entry: Entry): void {
+  const woken = entry.waiters
+  entry.waiters = []
+  for (const wake of woken) wake()
+}
+
+/** Normalize an abort into an Error rejection. */
+function abortReason(signal: AbortSignal): Error {
+  return signal.reason instanceof Error ? signal.reason : new Error('command directory wait aborted')
+}

packages/client/ui-command/src/client/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Command UI plugin, browser half: CommandService (`ctx.command`) owning the
+ * capability-keyed directory cache, the '/' command source, the client
+ * contribution registry, and the per-session popupSelect controllers; the
+ * popupSelect shell self-registers into conversation.input.overlay with
+ * per-session resolution.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+// Type-only: pulls the 'conversation.input.overlay' SlotMap declaration (the
+// key's owner) into this program so the overlay registration below typechecks
+// against the real declaration — no runtime edge to ui-conversation.
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { CommandService } from './service.ts'
+import type { PopupSelectInjected } from './PopupSelectView.tsx'
+import { PopupSelectView } from './PopupSelectView.tsx'
+
+export { CommandService } from './service.ts'
+export { CommandDirectory } from './directory.ts'
+export type { CommandDescriptor, DirectoryStatus } from './directory.ts'
+export { filterOptions, PopupSelectController } from './popup.ts'
+export type { PopupSelectDeps, PopupSpec, PopupState, TokenSegment } from './popup.ts'
+export type { PopupSelectInjected } from './PopupSelectView.tsx'
+export type {
+  CommandContribution, CommandServiceContract, CommandUiSpec, SelectOption,
+} from './contract.ts'
+
+declare module 'cordis' {
+  interface Context {
+    command: CommandService
+  }
+}
+
+/** Required services: the '/' source registry plus the scope + wire faces the service reads. */
+export const inject = ['slash', 'sessions', 'connection']
+
+/**
+ * Client plugin body: mount the service, then register the popupSelect shell
+ * into the input overlay once its declarer is up.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  ctx.plugin(CommandService)
+  // Conditional mount, same seam as ui-slash's MenuView registration:
+  // 'conversation.input.overlay' is declared by the conversation composer
+  // entry, and the conversation service's presence is the registration-safe
+  // signal that the declaration is on the ledger.
+  ctx.inject(['slots', 'conversation', 'command', 'sessions'], (scope: ClientContext) => {
+    const command = scope.command
+    const sessions = scope.sessions
+    scope.effect(() => scope.slots.register({
+      name: 'conversation.input.overlay',
+      id: 'command-popup',
+      order: 1,
+      inject: (sessionId): PopupSelectInjected => {
+        const actx = sessions.scope(sessionId)
+        if (actx === undefined) throw new Error(`ui-command: session "${String(sessionId)}" resolved no scope`)
+        return { popup: command.popupFor(actx) }
+      },
+    }, PopupSelectView), 'ui-command: popupSelect overlay registration')
+  })
+}

packages/client/ui-command/src/client/popup.ts

@@ -0,0 +1,251 @@
+/**
+ * Headless popupSelect shell state (design §10): one controller per client
+ * session, owned by CommandService's per-session map and torn down by the
+ * session scope disposer. The shell is a transient layer (never in the input
+ * state machine): it loads options once, filters them locally against the
+ * shell's own search text, and settles a selection through the context
+ * captured at open time. Draft consumption and composer focus are injected
+ * callbacks — the session wiring dispatches the consume-token event (the
+ * Input side owns the span/bare-token CAS guard) and focuses the composer;
+ * the controller never touches the input machine.
+ */
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type { TokenSpan } from '@deepseek-ai/dsh-client-ui-slash/client'
+import type { SelectOption } from './contract.ts'
+
+/**
+ * The command token segment snapshotted at shell-open time, replayed to the
+ * injected {@link PopupSelectDeps.consume} callback after a successful
+ * selection. The Input side guards it: a menu-path span consumes iff draftRev
+ * is unchanged, an enter-path line iff the trimmed draft still equals the
+ * bare token.
+ */
+export type TokenSegment =
+  | { readonly via: 'menu'; readonly span: TokenSpan }
+  | { readonly via: 'enter'; readonly token: string }
+
+/**
+ * Structural business spec the shell settles against — the popupSelect half
+ * of CommandUiSpec, generic in the context value the opener captures (the
+ * session wiring passes its session projection; the controller only carries
+ * it from open() to the callbacks).
+ */
+export interface PopupSpec<TCtx> {
+  /** Load the option rows once per open (retry after failure reuses the same signal). */
+  options(context: TCtx, signal: AbortSignal): Promise<readonly SelectOption[]>
+  /** Settle the picked option against the open-time context. */
+  onSelect(option: SelectOption, context: TCtx): void | Promise<void>
+}
+
+/** Injected session-wiring callbacks of one controller (tests pass fakes). */
+export interface PopupSelectDeps {
+  /**
+   * Consume the open-time token segment after a successful onSelect (the
+   * wiring dispatches the consume-token event to the opening session).
+   * @param segment - the open-time token segment snapshot.
+   * @returns whether the token was consumed; false (CAS miss) is benign and
+   * never retried.
+   */
+  consume(segment: TokenSegment): boolean
+  /** Return focus to the session composer (successful settle and Escape close paths). */
+  focusComposer(): void
+}
+
+/** Popup shell state (the shell component renders from here; closed = render null). */
+export interface PopupState {
+  readonly open: boolean
+  /** Command name the shell is open for (null while closed). */
+  readonly command: string | null
+  /** Options-load lifecycle; 'failed' keeps the shell open for retry(). */
+  readonly status: 'pending' | 'ready' | 'failed'
+  /** Options as loaded — never re-fetched per keystroke; views render {@link filterOptions} over them. */
+  readonly options: readonly SelectOption[]
+  /** Local filter text over the loaded options. */
+  readonly search: string
+  /** Highlight index into the filtered row list (0 when empty/pending). */
+  readonly active: number
+  /** A select() settlement is in flight: further select/search/highlight no-op until it settles. */
+  readonly submitting: boolean
+  /** Surfaced settlement failure (options load or onSelect); null when none. */
+  readonly error: string | null
+}
+
+const CLOSED: PopupState = {
+  open: false, command: null, status: 'pending', options: [], search: '', active: 0, submitting: false, error: null,
+}
+
+/**
+ * Filter option rows against the shell's local search text (case-insensitive
+ * substring over label and detail; blank search keeps every row).
+ * @param options - the loaded rows.
+ * @param search - the shell's search text.
+ * @returns the rows the shell shows and highlights over.
+ */
+export function filterOptions(options: readonly SelectOption[], search: string): readonly SelectOption[] {
+  const query = search.trim().toLowerCase()
+  if (query === '') return options
+  return options.filter(o => o.label.toLowerCase().includes(query) || (o.detail?.toLowerCase().includes(query) ?? false))
+}
+
+/** One open shell's bindings (spec + open-time context + segment snapshot + options-fetch abort). */
+interface OpenBinding<TCtx> {
+  readonly command: string
+  readonly spec: PopupSpec<TCtx>
+  readonly context: TCtx
+  readonly segment: TokenSegment
+  readonly abort: AbortController
+}
+
+/** The shell's error-strip line for a settlement failure. */
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * Headless controller of one session's popupSelect shell. Late settlements
+ * lose their write rights through binding identity: dismiss/dispose/reopen
+ * swap the binding, so a settling options fetch or onSelect that no longer
+ * matches writes nothing and consumes nothing.
+ */
+export class PopupSelectController<TCtx = unknown> {
+  /** Shell state store (the overlay component subscribes here). */
+  readonly state: SnapshotStore<PopupState> = createSnapshotStore<PopupState>(CLOSED)
+  private binding: OpenBinding<TCtx> | null = null
+
+  /**
+   * @param deps - session-wiring callbacks (token consumption + composer focus).
+   */
+  constructor(private readonly deps: PopupSelectDeps) {}
+
+  /**
+   * Open the shell for one command: publish pending state and fetch options
+   * once through the business spec. A reopen supersedes the previous shell
+   * (its options fetch is aborted, its late settlements are dropped).
+   * @param command - command name the shell serves.
+   * @param spec - the registered popupSelect spec.
+   * @param context - open-time context snapshot, handed verbatim to options/onSelect.
+   * @param segment - open-time token segment snapshot for post-select consumption.
+   */
+  open(command: string, spec: PopupSpec<TCtx>, context: TCtx, segment: TokenSegment): void {
+    this.binding?.abort.abort()
+    const binding: OpenBinding<TCtx> = { command, spec, context, segment, abort: new AbortController() }
+    this.binding = binding
+    this.state.set({ ...CLOSED, open: true, command })
+    this.load(binding)
+  }
+
+  /** Run the one options fetch of a binding; settlement rights die with the binding. */
+  private load(binding: OpenBinding<TCtx>): void {
+    binding.spec.options(binding.context, binding.abort.signal).then(
+      (options) => {
+        if (this.binding !== binding) return
+        this.state.set({ ...this.state.getSnapshot(), status: 'ready', options, active: 0, error: null })
+      },
+      (error: unknown) => {
+        if (this.binding !== binding) return
+        console.error(`[ui-command] popupSelect options failed for /${binding.command}:`, error)
+        this.state.set({ ...this.state.getSnapshot(), status: 'failed', options: [], active: 0, error: errorText(error) })
+      },
+    )
+  }
+
+  /** Re-run a failed options fetch (search survives; no-op unless status is 'failed'). */
+  retry(): void {
+    const binding = this.binding
+    const s = this.state.getSnapshot()
+    if (binding === null || !s.open || s.status !== 'failed') return
+    this.state.set({ ...s, status: 'pending', error: null })
+    this.load(binding)
+  }
+
+  /**
+   * Replace the local search text (pure local filter — the provider is never
+   * re-queried) and rebase the highlight onto the new filtered list.
+   * @param search - the shell search input's text.
+   */
+  setSearch(search: string): void {
+    const s = this.state.getSnapshot()
+    if (!s.open || s.submitting || search === s.search) return
+    this.state.set({ ...s, search, active: 0 })
+  }
+
+  /**
+   * Move the highlight across the filtered rows (wraps around; no-op unless
+   * options are ready and no selection is in flight).
+   * @param dir - +1 down, -1 up.
+   */
+  move(dir: 1 | -1): void {
+    const s = this.state.getSnapshot()
+    if (!s.open || s.status !== 'ready' || s.submitting) return
+    const rows = filterOptions(s.options, s.search)
+    if (rows.length === 0) return
+    const active = (s.active + dir + rows.length) % rows.length
+    this.state.set({ ...s, active })
+  }
+
+  /**
+   * Set the highlight directly (pointer hover; no-op unless ready, idle, and
+   * in filtered range).
+   * @param index - filtered-row index.
+   */
+  highlight(index: number): void {
+    const s = this.state.getSnapshot()
+    if (!s.open || s.status !== 'ready' || s.submitting) return
+    if (index < 0 || index >= filterOptions(s.options, s.search).length || index === s.active) return
+    this.state.set({ ...s, active: index })
+  }
+
+  /**
+   * Select one filtered row: single-flight — the first call enters
+   * `submitting` and later calls no-op until it settles. Success consumes the
+   * open-time token segment (a false CAS answer is benign), closes, and
+   * returns focus to the composer. Failure keeps the shell open with search,
+   * highlight, and token intact, surfaces the error, and re-arms select as
+   * the retry.
+   * @param index - filtered-row index (callers pass the highlight or the clicked row).
+   * @returns settled when the attempt has closed the shell or surfaced its failure.
+   */
+  async select(index: number): Promise<void> {
+    const binding = this.binding
+    const s = this.state.getSnapshot()
+    if (binding === null || !s.open || s.status !== 'ready' || s.submitting) return
+    const option = filterOptions(s.options, s.search)[index]
+    if (option === undefined) return
+    this.state.set({ ...s, submitting: true, error: null })
+    try {
+      await binding.spec.onSelect(option, binding.context)
+    } catch (error) {
+      console.error(`[ui-command] popupSelect onSelect failed for /${binding.command}:`, error)
+      if (this.binding !== binding) return // dismissed/reopened/disposed while onSelect flew
+      this.state.set({ ...this.state.getSnapshot(), submitting: false, error: errorText(error) })
+      return
+    }
+    if (this.binding !== binding) return // late success: no state write, no consumption
+    this.deps.consume(binding.segment)
+    this.binding = null
+    this.state.set(CLOSED)
+    this.deps.focusComposer()
+  }
+
+  /**
+   * Close the shell; aborts a flying options fetch and revokes settlement
+   * rights. An outside pointer interaction dismisses plainly (the click's own
+   * target takes focus); Escape passes focusComposer to return focus explicitly.
+   * @param opts - focusComposer: also restore composer focus (Escape path).
+   */
+  dismiss(opts?: { readonly focusComposer?: boolean }): void {
+    if (this.binding === null) return
+    this.binding.abort.abort()
+    this.binding = null
+    this.state.set(CLOSED)
+    if (opts?.focusComposer === true) this.deps.focusComposer()
+  }
+
+  /** Scope-teardown disposer: abort in-flight work and clear state (no focus side effect). */
+  dispose(): void {
+    this.binding?.abort.abort()
+    this.binding = null
+    this.state.set(CLOSED)
+  }
+}

packages/client/ui-command/src/client/service.ts

@@ -0,0 +1,292 @@
+/**
+ * CommandService (`ctx.command`): the '/' command source over the
+ * session-keyed directory, the client-contribution registry, and the
+ * per-session popupSelect controllers. Candidate synthesis merges the host
+ * catalog with contributions by availability, then query/position filtering;
+ * a host/contribution name collision fails loud. Every execute addresses the
+ * session's agent by sessionId — sessions are always agent-backed.
+ */
+import { Service } from 'cordis'
+import type { Context } from 'cordis'
+import type { ConnectionHandle, SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import type { ClientContext, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  CandidateRequest, ClientSessionContext, CommandClaim, PickOutcome, SlashCandidate, SlashPick,
+  SlashServiceContract, SubmitOutcome,
+} from '@deepseek-ai/dsh-client-ui-slash/client'
+import type { CommandContribution, CommandServiceContract } from './contract.ts'
+import type { CommandDescriptor } from './directory.ts'
+import { CommandDirectory } from './directory.ts'
+import { PopupSelectController } from './popup.ts'
+import type { TokenSegment } from './popup.ts'
+
+/** Live mutable state in one holder (service methods run behind the caller-ctx tracker). */
+interface LiveState {
+  readonly contributions: Map<string, CommandContribution>
+  readonly popups: Map<SessionId, PopupSelectController<ClientSessionContext>>
+}
+
+/** Command surface: session-keyed directory + '/' source + contribution registry + per-session popups. */
+export class CommandService extends Service implements CommandServiceContract {
+  static inject = ['slash', 'sessions', 'connection']
+
+  private readonly directory: CommandDirectory
+  private readonly live: LiveState = { contributions: new Map(), popups: new Map() }
+
+  /**
+   * @param ctx - owning root context (plugin fiber; the service registers
+   * itself as `command` and follows that fiber's lifetime).
+   */
+  constructor(ctx: Context) {
+    super(ctx, 'command')
+    const connection = ctx.get('connection') as ConnectionHandle | undefined
+    if (connection === undefined) throw new Error('ui-command: connection service unavailable')
+    this.directory = new CommandDirectory(async (sessionId) => {
+      const { result } = await connection.api.commands.list({ sessionId })
+      if (!result.ok) throw new Error(`command.list failed: ${result.error.code}: ${result.error.message}`)
+      return result.value.commands
+    })
+    const slash = ctx.get('slash') as SlashServiceContract | undefined
+    if (slash === undefined) throw new Error('ui-command: slash service unavailable')
+    ctx.effect(() => slash.registerSource({
+      trigger: '/',
+      name: 'command',
+      candidates: (session, req) => this.candidates(session, req),
+      onPick: pick => this.dispatch(pick),
+      matchSpace: (session, token) => this.matchSpace(session, token),
+      matchEnter: (session, line, signal) => this.matchEnter(session, line, signal),
+      warm: (session) => { this.directory.warm(session.sessionId) },
+    }), 'command: slash source')
+    ctx.on('commands/changed', () => { this.directory.invalidateAll() })
+    ctx.on('connection/reset', () => { this.directory.resetConnected() })
+  }
+
+  /**
+   * Register one client command contribution; effect disposer (rides the
+   * caller's fiber). Duplicate names throw.
+   * @param contribution - the contribution (descriptor + availability + popup spec).
+   * @returns the disposer removing the registration.
+   */
+  register(contribution: CommandContribution): () => void {
+    const dispose = this.ctx.effect(() => {
+      const { contributions } = this.live
+      if (contributions.has(contribution.name)) {
+        throw new Error(`ui-command: duplicate contribution for /${contribution.name}`)
+      }
+      contributions.set(contribution.name, contribution)
+      return () => { contributions.delete(contribution.name) }
+    }, 'command.register()')
+    return () => { void dispose() }
+  }
+
+  /**
+   * Resolve the per-session popup controller (lazy; dies with the session
+   * scope). The controller's consume callback dispatches the scoped
+   * consume-token event back to this session; focusComposer reaches the
+   * composer through the overlay slot currency.
+   * @param actx - session-scope ctx.
+   * @returns the resident controller.
+   */
+  popupFor(actx: ClientContext): PopupSelectController<ClientSessionContext> {
+    const sessions = this.sessions()
+    const id = sessions.scopeOf(actx)
+    if (id === undefined) throw new Error('command.popupFor requires a session scope')
+    const { popups } = this.live
+    const existing = popups.get(id)
+    if (existing !== undefined) return existing
+    const controller = new PopupSelectController<ClientSessionContext>({
+      consume: segment => actx.bail(actx, 'slash/input-consume-token', {
+        guard: segment.via === 'menu'
+          ? { kind: 'span', span: segment.span }
+          : { kind: 'bare-token', token: segment.token },
+      }) === true,
+      focusComposer: () => { this.focusHooks.get(id)?.() },
+    })
+    popups.set(id, controller)
+    actx.effect(() => () => {
+      controller.dispose()
+      popups.delete(id)
+      this.focusHooks.delete(id)
+    }, 'command: session popup')
+    return controller
+  }
+
+  /** Composer focus hooks by session (the overlay wiring binds the textarea focus here). */
+  private readonly focusHooks = new Map<SessionId, () => void>()
+
+  /**
+   * Bind one session's composer-focus hook (overlay slot wiring; unbind on unmount).
+   * @param id - session id.
+   * @param focus - textarea focus callback.
+   * @returns the unbind disposer.
+   */
+  bindComposerFocus(id: SessionId, focus: () => void): () => void {
+    this.focusHooks.set(id, focus)
+    return () => {
+      if (this.focusHooks.get(id) === focus) this.focusHooks.delete(id)
+    }
+  }
+
+  /** Menu candidates: host catalog + contribution availability, then query/position filtering. */
+  private async candidates(session: ClientSessionContext, req: CandidateRequest): Promise<readonly SlashCandidate[]> {
+    const list = await this.directory.ensureReady(session.sessionId, req.signal)
+    const rows: SlashCandidate[] = []
+    const seen = new Set<string>()
+    for (const c of list) {
+      seen.add(c.name)
+      rows.push({ name: c.name, description: c.description, ...(c.input !== undefined ? { hint: c.input.hint } : {}) })
+    }
+    for (const contribution of this.live.contributions.values()) {
+      if (!contribution.available(session)) continue
+      if (seen.has(contribution.name)) {
+        throw new Error(`ui-command: contribution /${contribution.name} collides with a host command`)
+      }
+      rows.push({ name: contribution.name, description: contribution.description })
+    }
+    return rows
+      .filter(c => c.name.startsWith(req.query))
+      .filter(c => req.position === 'leading' || c.hint === undefined)
+  }
+
+  /** Decision table, menu column: contribution → popup; host input → claim; host bare → detached execute. */
+  private dispatch(pick: SlashPick): PickOutcome {
+    const name = pick.candidate.name
+    const contribution = this.live.contributions.get(name)
+    if (contribution !== undefined && contribution.available(pick.session)) {
+      this.openPopup(contribution, pick.session, { via: 'menu', span: pick.span })
+      return 'handled'
+    }
+    const desc = this.directory.resolve(pick.session.sessionId, name)
+    if (desc === undefined) return undefined // snapshot swapped between menu and pick → miss
+    if (desc.input !== undefined) return { claim: this.leadingClaim(desc, pick.session) }
+    // Menu-pick execute consumes the trigger span before the detached run
+    // (scoped event; the input owns the CAS guard).
+    this.consumeVia(pick.session.sessionId, { via: 'menu', span: pick.span })
+    this.runDetached(desc, pick.session, `/${name}`)
+    return 'handled'
+  }
+
+  /** Decision table, space column: hot-key sync check; only host leadingInput claims. */
+  private matchSpace(session: ClientSessionContext, token: string): PickOutcome {
+    if (!token.startsWith('/')) return undefined
+    const name = token.slice(1)
+    if (this.live.contributions.has(name)) return undefined // popup kinds never claim on space
+    const desc = this.directory.resolve(session.sessionId, name)
+    if (desc === undefined || desc.input === undefined) return undefined
+    return { claim: this.leadingClaim(desc, session) }
+  }
+
+  /**
+   * Decision table, enter column. Strong-waits the session's catalog (a
+   * warmup failure rejects — never a silent downgrade). Contributions and
+   * bare host commands act on the bare token only; leadingInput claims
+   * args-tolerant.
+   */
+  private async matchEnter(session: ClientSessionContext, line: string, signal: AbortSignal): Promise<PickOutcome> {
+    const trimmed = line.trim()
+    if (!trimmed.startsWith('/')) return undefined
+    const ws = trimmed.search(/\s/)
+    const token = ws === -1 ? trimmed : trimmed.slice(0, ws)
+    const bare = ws === -1
+    const name = token.slice(1)
+    if (name === '') return undefined
+    const contribution = this.live.contributions.get(name)
+    if (contribution !== undefined && contribution.available(session)) {
+      if (!bare) return undefined
+      this.openPopup(contribution, session, { via: 'enter', token })
+      return 'handled'
+    }
+    await this.directory.ensureReady(session.sessionId, signal)
+    const desc = this.directory.resolve(session.sessionId, name)
+    if (desc === undefined) return undefined
+    if (desc.input !== undefined) return { claim: this.leadingClaim(desc, session) }
+    if (!bare) return undefined
+    this.consumeVia(session.sessionId, { via: 'enter', token })
+    this.runDetached(desc, session, trimmed)
+    return 'handled'
+  }
+
+  /** Open the session's popup for one contribution (menu pick / bare enter). */
+  private openPopup(
+    contribution: CommandContribution,
+    session: ClientSessionContext,
+    segment: TokenSegment,
+  ): void {
+    const actx = this.scopeFor(session.sessionId)
+    if (actx === undefined) return
+    this.popupFor(actx).open(contribution.name, contribution.ui, session, segment)
+  }
+
+  /** Build the leadingInput claim: token `/name ` + the command.execute submit transaction. */
+  private leadingClaim(desc: CommandDescriptor, session: ClientSessionContext): CommandClaim {
+    const token = `/${desc.name} `
+    return {
+      token,
+      ...(desc.input !== undefined ? { hint: desc.input.hint } : {}),
+      submit: (args, _actx) => this.execute(session, token + args),
+    }
+  }
+
+  /** The command.execute transaction, addressed to the session's agent. */
+  private async execute(
+    session: ClientSessionContext,
+    line: string,
+  ): Promise<SubmitOutcome> {
+    const connection = this.ctx.get('connection') as ConnectionHandle
+    const { result } = await connection.api.commands.execute({ sessionId: session.sessionId, line })
+    if (!result.ok) throw new Error(`command.execute failed: ${result.error.code}: ${result.error.message}`)
+    if (!result.value.matched) return { kind: 'error', text: `unknown or malformed command: ${line}` }
+    const detached = result.value.result
+    return detached === undefined
+      ? { kind: 'success' }
+      : { kind: detached.kind, ...(detached.text !== undefined ? { text: detached.text } : {}) }
+  }
+
+  /**
+   * Fire-and-forget execute for the internal ('handled') paths. The detached
+   * result surfaces as a notice routed to the triggering session's composer,
+   * so a late result lands on its own session after a switch.
+   */
+  private runDetached(desc: CommandDescriptor, session: ClientSessionContext, line: string): void {
+    void this.execute(session, line).then(
+      (outcome) => {
+        if (outcome.kind === 'error') this.noticeFor(session.sessionId, desc.name, 'error', outcome.text ?? `/${desc.name} failed`)
+        else if (outcome.text !== undefined) this.noticeFor(session.sessionId, desc.name, 'info', outcome.text)
+      },
+      (error: unknown) => {
+        this.noticeFor(session.sessionId, desc.name, 'error', error instanceof Error ? error.message : String(error))
+      },
+    )
+  }
+
+  /** Dispatch a consume-token event to one session (menu-pick / bare-enter execute paths). */
+  private consumeVia(id: SessionId, segment: TokenSegment): void {
+    const actx = this.scopeFor(id)
+    if (actx === undefined) return
+    actx.bail(actx, 'slash/input-consume-token', {
+      guard: segment.via === 'menu'
+        ? { kind: 'span', span: segment.span }
+        : { kind: 'bare-token', token: segment.token },
+    })
+  }
+
+  /** Route a detached result to the session's composer notice channel (scope gone = attempt died with it). */
+  private noticeFor(id: SessionId, _name: string, level: 'info' | 'error', text: string): void {
+    const actx = this.scopeFor(id)
+    if (actx === undefined) return
+    const conversation = actx.get('conversation')
+    if (conversation === undefined) return
+    conversation.input.for(actx).notify(level, text)
+  }
+
+  /** id → actx interchange (registered exchange point: this service coordinates for projection-only sources). */
+  private scopeFor(id: SessionId): ClientContext | undefined {
+    return this.sessions().scope(id)
+  }
+
+  private sessions(): SessionsService {
+    const sessions = this.ctx.get('sessions')
+    if (sessions === undefined) throw new Error('ui-command: sessions service unavailable')
+    return sessions
+  }
+}

packages/client/ui-command/src/css-modules.d.ts

@@ -0,0 +1,6 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css'

packages/client/ui-command/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Command UI plugin, node half. Pure UI plugin: the empty apply exists so
+ * the plugin appears in the host cordis.yml / Loader; the browser half ships
+ * via exports["./client"], discovered through the package.json dshClient
+ * declaration. The host command registry itself mounts separately
+ * (bootHost + CommandService).
+ */
+
+/** Host plugin body — no host-side behavior for the command UI plugin. */
+export function apply(): void {}

packages/client/ui-command/src/invariant.ts

@@ -0,0 +1,31 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-command`.
+ * @module @deepseek-ai/dsh-client-ui-command/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-command'
+
+/** Cordis companion plugin name. */
+export const name = 'client-ui-command-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: a browser-side source over the wire command
+ * directory — it emits no cordis events and owns no cross-plugin mutable
+ * state; dispatch and cache behavior are asserted by this package's specs.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/client/ui-command/tests/browser-plugin.spec.ts

@@ -0,0 +1,83 @@
+/**
+ * ui-command browser half on a real cordis Context with fake slash/slots
+ * faces and real session scopes: the plugin body mounts CommandService as
+ * `command`, the popupSelect shell registers into conversation.input.overlay
+ * once the conversation seam is up with a per-session inject (sessionId →
+ * scope → popupFor; unknown id fails loud), both fold up on fiber disposal
+ * (HMR safety), and the service satisfies the frozen CommandServiceContract.
+ */
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import { createScope, scopeOf } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SlashSource } from '@deepseek-ai/dsh-client-ui-slash/client'
+import type { CommandServiceContract } from '../src/client/contract.ts'
+import type { PopupSelectInjected } from '../src/client/PopupSelectView.tsx'
+import { apply, CommandService, inject } from '../src/client/index.ts'
+
+const sid = (k: string): SessionId => k as SessionId
+
+async function bench() {
+  const ctx = new Context()
+  const sources = new Map<string, SlashSource>()
+  const overlays = new Map<string, { inject: unknown }>()
+  ctx.provide('slash', {
+    registerSource(src: SlashSource) {
+      sources.set(`${src.trigger} ${src.name}`, src)
+      return () => { sources.delete(`${src.trigger} ${src.name}`) }
+    },
+  })
+  const scopes = new Map<SessionId, Context>()
+  ctx.provide('sessions', {
+    scope: (id: SessionId) => scopes.get(id),
+    scopeOf: (c: Context) => scopeOf(c),
+  })
+  ctx.provide('connection', { api: { commands: { list: () => Promise.resolve({ result: { ok: true, value: { commands: [] } } }) } } })
+  ctx.provide('slots', {
+    register(options: { name: string; id?: string; inject?: unknown }) {
+      const key = `${options.name}#${options.id ?? ''}`
+      overlays.set(key, { inject: options.inject })
+      return () => { overlays.delete(key) }
+    },
+  })
+  ctx.provide('conversation', {})
+  const fiber = ctx.plugin({ inject: [...inject], apply })
+  await fiber.await()
+  const mint = (key: string) => {
+    const handle = createScope(ctx, sid(key))
+    scopes.set(sid(key), handle.ctx)
+    return handle
+  }
+  return { ctx, fiber, sources, overlays, mint }
+}
+
+describe('apply', () => {
+  it('declares the services it binds', () => {
+    expect(inject).toEqual(['slash', 'sessions', 'connection'])
+  })
+
+  it('mounts ctx.command, registers the source and the overlay entry, and folds up on disposal', async () => {
+    const { ctx, fiber, sources, overlays } = await bench()
+    const command = ctx.get('command')
+    expect(command).toBeInstanceOf(CommandService)
+    // Frozen-contract conformance (compile-time check rides the assignment).
+    const contract: CommandServiceContract = command as CommandService
+    expect(typeof contract.register).toBe('function')
+    expect(typeof contract.popupFor).toBe('function')
+    expect([...sources.keys()]).toEqual(['/ command'])
+    expect([...overlays.keys()]).toEqual(['conversation.input.overlay#command-popup'])
+    await fiber.dispose()
+    expect(sources.size).toBe(0)
+    expect(overlays.size).toBe(0)
+  })
+
+  it('the overlay inject resolves the per-session popup controller by sessionId and fails loud on an unknown id', async () => {
+    const { ctx, overlays, mint } = await bench()
+    const command = ctx.get('command') as CommandService
+    const scope = mint('s1')
+    const entry = overlays.get('conversation.input.overlay#command-popup')!
+    const injectEntry = entry.inject as (sessionId: SessionId) => PopupSelectInjected
+    expect(injectEntry(sid('s1')).popup).toBe(command.popupFor(scope.ctx))
+    expect(() => injectEntry(sid('ghost'))).toThrow(/resolved no scope/)
+  })
+})

packages/client/ui-command/tests/directory.spec.ts

@@ -0,0 +1,293 @@
+/**
+ * CommandDirectory unit tests over the session-key axis: per-key status
+ * transitions and epoch guard, key isolation across sessions, soft
+ * invalidation (invalidateAll), the reconnect hard reset (resetConnected:
+ * every entry drops its snapshot and prewarms), the warm hook's cold/failed
+ * gate, and the per-key ensureReady strong-wait policy.
+ */
+import { describe, expect, it } from 'vitest'
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import type { CommandDescriptor } from '../src/client/directory.ts'
+import { CommandDirectory } from '../src/client/directory.ts'
+
+const sid = (k: string): SessionId => k as SessionId
+const S1 = sid('s1')
+const S2 = sid('s2')
+
+function deferred<T>() {
+  let resolve!: (value: T) => void
+  let reject!: (reason?: unknown) => void
+  const promise = new Promise<T>((res, rej) => { resolve = res; reject = rej })
+  return { promise, resolve, reject }
+}
+
+const CMDS: CommandDescriptor[] = [
+  { name: 'plan', description: 'plan mode' },
+  { name: 'goal', description: 'set goal', input: { hint: 'goal text' } },
+]
+
+const S2_CMDS: CommandDescriptor[] = [
+  ...CMDS,
+  { name: 'attach', description: 'attach a file', input: { hint: 'path' } },
+]
+
+/** Directory over per-key pull queues: each fetch appends a hand-settled deferred. */
+function bench() {
+  const pulls = new Map<SessionId, Array<ReturnType<typeof deferred<readonly CommandDescriptor[]>>>>()
+  const calls: SessionId[] = []
+  const dir = new CommandDirectory((key) => {
+    calls.push(key)
+    const d = deferred<readonly CommandDescriptor[]>()
+    const queue = pulls.get(key) ?? []
+    queue.push(d)
+    pulls.set(key, queue)
+    return d.promise
+  })
+  const pull = (key: SessionId, i: number) => {
+    const d = pulls.get(key)?.[i]
+    if (d === undefined) throw new Error(`no pull #${i} for ${key}`)
+    return d
+  }
+  return { dir, pull, calls, countOf: (key: SessionId) => pulls.get(key)?.length ?? 0 }
+}
+
+describe('status and resolve (per key)', () => {
+  it('starts cold and resolves nothing', () => {
+    const { dir } = bench()
+    expect(dir.status(S1)).toBe('cold')
+    expect(dir.resolve(S1, 'plan')).toBeUndefined()
+  })
+
+  it('serves exact-name lookups once ready, undefined for unknown names', async () => {
+    const { dir, pull } = bench()
+    const refreshed = dir.refresh(S1)
+    expect(dir.status(S1)).toBe('pending')
+    pull(S1, 0).resolve(CMDS)
+    await refreshed
+    expect(dir.status(S1)).toBe('ready')
+    expect(dir.resolve(S1, 'goal')).toEqual(CMDS[1])
+    expect(dir.resolve(S1, 'nope')).toBeUndefined()
+  })
+
+  it('drops the snapshot and records failure on a failed pull', async () => {
+    const { dir, pull } = bench()
+    const refreshed = dir.refresh(S1)
+    pull(S1, 0).reject(new Error('boom'))
+    await refreshed
+    expect(dir.status(S1)).toBe('failed')
+    expect(dir.resolve(S1, 'plan')).toBeUndefined()
+  })
+
+  it('keys are isolated: one session catalog landing leaves another cold', async () => {
+    const { dir, pull } = bench()
+    const refreshed = dir.refresh(S1)
+    pull(S1, 0).resolve(CMDS)
+    await refreshed
+    expect(dir.status(S2)).toBe('cold')
+    expect(dir.resolve(S2, 'plan')).toBeUndefined()
+
+    const other = dir.refresh(S2)
+    pull(S2, 0).resolve(S2_CMDS)
+    await other
+    expect(dir.resolve(S2, 'attach')).toBeDefined()
+    expect(dir.resolve(S1, 'attach')).toBeUndefined()
+  })
+})
+
+describe('epoch guard (per key)', () => {
+  it('a superseded pull cannot overwrite the newer one (old resolves after new)', async () => {
+    const { dir, pull } = bench()
+    const first = dir.refresh(S1)
+    const second = dir.refresh(S1)
+    pull(S1, 1).resolve(CMDS)
+    await second
+    expect(dir.resolve(S1, 'plan')).toBeDefined()
+    pull(S1, 0).resolve([{ name: 'stale', description: 'old world' }])
+    await first
+    expect(dir.resolve(S1, 'stale')).toBeUndefined()
+    expect(dir.resolve(S1, 'plan')).toBeDefined()
+  })
+
+  it('a superseded failure cannot demote the newer success', async () => {
+    const { dir, pull } = bench()
+    const first = dir.refresh(S1)
+    const second = dir.refresh(S1)
+    pull(S1, 1).resolve(CMDS)
+    await second
+    pull(S1, 0).reject(new Error('late failure'))
+    await first
+    expect(dir.status(S1)).toBe('ready')
+    expect(dir.resolve(S1, 'plan')).toBeDefined()
+  })
+
+  it('epochs are per key: one session supersede leaves another session epoch alone', async () => {
+    const { dir, pull } = bench()
+    const one = dir.refresh(S1)
+    void dir.refresh(S2)
+    void dir.refresh(S2) // supersedes the s2 pull only
+    pull(S1, 0).resolve(CMDS)
+    await one
+    expect(dir.status(S1)).toBe('ready')
+  })
+})
+
+describe('invalidateAll (commands-changed soft)', () => {
+  it('repulls every touched key in the background while ready snapshots keep serving', async () => {
+    const { dir, pull, countOf } = bench()
+    const a = dir.refresh(S1)
+    const b = dir.refresh(S2)
+    pull(S1, 0).resolve(CMDS)
+    pull(S2, 0).resolve(S2_CMDS)
+    await Promise.all([a, b])
+
+    dir.invalidateAll()
+    expect(countOf(S1)).toBe(2)
+    expect(countOf(S2)).toBe(2)
+    expect(dir.status(S1)).toBe('ready')
+    expect(dir.resolve(S2, 'attach')).toBeDefined()
+
+    pull(S1, 1).resolve([{ name: 'fresh', description: 'new world' }])
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(dir.resolve(S1, 'fresh')).toBeDefined()
+    expect(dir.resolve(S1, 'plan')).toBeUndefined()
+  })
+
+  it('an untouched directory invalidates to nothing (no keys, no pulls)', () => {
+    const { dir, calls } = bench()
+    dir.invalidateAll()
+    expect(calls).toEqual([])
+  })
+})
+
+describe('resetConnected (reconnect hard)', () => {
+  it('every entry drops its snapshot immediately and prewarms', async () => {
+    const { dir, pull, countOf } = bench()
+    const a = dir.refresh(S1)
+    const b = dir.refresh(S2)
+    pull(S1, 0).resolve(CMDS)
+    pull(S2, 0).resolve(S2_CMDS)
+    await Promise.all([a, b])
+
+    dir.resetConnected()
+    // Hard: the agent world may have changed shape across the generation.
+    expect(dir.status(S1)).toBe('pending')
+    expect(dir.resolve(S1, 'plan')).toBeUndefined()
+    expect(dir.status(S2)).toBe('pending')
+    expect(dir.resolve(S2, 'attach')).toBeUndefined()
+    expect(countOf(S1)).toBe(2)
+    expect(countOf(S2)).toBe(2)
+
+    pull(S1, 1).resolve(CMDS)
+    pull(S2, 1).resolve(S2_CMDS)
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(dir.status(S1)).toBe('ready')
+    expect(dir.resolve(S2, 'attach')).toBeDefined()
+  })
+})
+
+describe('warm', () => {
+  it('launches a pull from cold, again after failure, and never over pending/ready', async () => {
+    const { dir, pull, countOf } = bench()
+    dir.warm(S1)
+    expect(countOf(S1)).toBe(1)
+    dir.warm(S1) // pending → no second pull
+    expect(countOf(S1)).toBe(1)
+
+    pull(S1, 0).reject(new Error('boom'))
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(dir.status(S1)).toBe('failed')
+    dir.warm(S1) // failed → retry
+    expect(countOf(S1)).toBe(2)
+
+    pull(S1, 1).resolve(CMDS)
+    await Promise.resolve()
+    await Promise.resolve()
+    dir.warm(S1) // ready → no-op
+    expect(countOf(S1)).toBe(2)
+  })
+
+  it('warms keys independently', () => {
+    const { dir, countOf } = bench()
+    dir.warm(S2)
+    expect(countOf(S2)).toBe(1)
+    expect(countOf(S1)).toBe(0)
+  })
+})
+
+describe('ensureReady (per key)', () => {
+  const signal = () => new AbortController().signal
+
+  it('returns the hot snapshot at once when ready', async () => {
+    const { dir, pull, countOf } = bench()
+    const warm = dir.refresh(S1)
+    pull(S1, 0).resolve(CMDS)
+    await warm
+    await expect(dir.ensureReady(S1, signal())).resolves.toEqual(CMDS)
+    expect(countOf(S1)).toBe(1)
+  })
+
+  it('launches a pull from cold and resolves on arrival, without touching other keys', async () => {
+    const { dir, pull, countOf } = bench()
+    const wait = dir.ensureReady(S2, signal())
+    expect(dir.status(S2)).toBe('pending')
+    pull(S2, 0).resolve(S2_CMDS)
+    await expect(wait).resolves.toEqual(S2_CMDS)
+    expect(countOf(S1)).toBe(0)
+  })
+
+  it('joins a flying pull instead of starting a second one', async () => {
+    const { dir, pull, countOf } = bench()
+    void dir.refresh(S1)
+    const wait = dir.ensureReady(S1, signal())
+    expect(countOf(S1)).toBe(1)
+    pull(S1, 0).resolve(CMDS)
+    await expect(wait).resolves.toEqual(CMDS)
+  })
+
+  it('rejects when the awaited pull fails (no silent downgrade)', async () => {
+    const { dir, pull } = bench()
+    const wait = dir.ensureReady(S1, signal())
+    pull(S1, 0).reject(new Error('warmup boom'))
+    await expect(wait).rejects.toThrow('command directory warmup failed: warmup boom')
+  })
+
+  it('retries from failed state with a fresh pull', async () => {
+    const { dir, pull } = bench()
+    const first = dir.ensureReady(S1, signal())
+    pull(S1, 0).reject(new Error('boom'))
+    await expect(first).rejects.toThrow()
+    const second = dir.ensureReady(S1, signal())
+    pull(S1, 1).resolve(CMDS)
+    await expect(second).resolves.toEqual(CMDS)
+  })
+
+  it('rejects on abort while waiting', async () => {
+    const { dir } = bench()
+    const ac = new AbortController()
+    const wait = dir.ensureReady(S1, ac.signal)
+    ac.abort(new Error('attempt superseded'))
+    await expect(wait).rejects.toThrow('attempt superseded')
+  })
+
+  it('rejects immediately on an already-aborted signal', async () => {
+    const { dir, pull } = bench()
+    const warm = dir.refresh(S1)
+    pull(S1, 0).reject(new Error('irrelevant'))
+    await warm
+    const ac = new AbortController()
+    ac.abort() // bare abort: the DOMException reason is itself an Error and travels as-is
+    await expect(dir.ensureReady(S1, ac.signal)).rejects.toThrow(/aborted/)
+  })
+
+  it('keeps waiting across a superseded pull and settles on the winner', async () => {
+    const { dir, pull } = bench()
+    const wait = dir.ensureReady(S1, signal())
+    void dir.refresh(S1) // supersedes pull #0 with pull #1
+    pull(S1, 0).resolve([{ name: 'stale', description: 'loser' }])
+    pull(S1, 1).resolve(CMDS)
+    await expect(wait).resolves.toEqual(CMDS)
+  })
+})

packages/client/ui-command/tests/popup-view.spec.tsx

@@ -0,0 +1,174 @@
+// @vitest-environment jsdom
+/**
+ * PopupSelectView interaction spec (design §10.2): the search input takes
+ * focus on open and plain typing filters locally, ↑↓ move the filtered
+ * highlight while ←→ stay native to the input, Enter selects single-flight,
+ * Escape dismisses back through focusComposer, outside pointerdown dismisses
+ * plainly, and the submitting/failed states render pending text and a
+ * working retry button.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import type { SelectOption } from '../src/client/contract.ts'
+import type { PopupSpec, TokenSegment } from '../src/client/popup.ts'
+import { PopupSelectController } from '../src/client/popup.ts'
+import { PopupSelectView } from '../src/client/PopupSelectView.tsx'
+
+afterEach(cleanup)
+
+const OPTIONS: SelectOption[] = [
+  { id: 'dark', label: 'Dark' },
+  { id: 'light', label: 'Light', active: true },
+  { id: 'sepia', label: 'Sepia', detail: 'warm' },
+]
+
+const SEGMENT: TokenSegment = { via: 'enter', token: '/theme' }
+
+function spec(overrides: Partial<PopupSpec<string>> = {}): PopupSpec<string> {
+  return {
+    options: () => Promise.resolve(OPTIONS),
+    onSelect: () => undefined,
+    ...overrides,
+  }
+}
+
+async function mountOpen(overrides: Partial<PopupSpec<string>> = {}, consumeResult = true) {
+  const consume = vi.fn((_segment: TokenSegment) => consumeResult)
+  const focusComposer = vi.fn()
+  const popup = new PopupSelectController<string>({ consume, focusComposer })
+  const view = render(<PopupSelectView popup={popup} />)
+  await act(async () => {
+    popup.open('theme', spec(overrides), 'ctx-A', SEGMENT)
+    await Promise.resolve()
+  })
+  return { popup, view, consume, focusComposer, search: screen.getByRole('textbox', { name: 'Filter options' }) }
+}
+
+function rowLabels(): string[] {
+  return screen.getAllByRole('option').map(o => o.querySelector('span')!.textContent!)
+}
+
+describe('PopupSelectView', () => {
+  it('renders null while closed, opens with focus in the search input', async () => {
+    const popup = new PopupSelectController<string>({ consume: () => true, focusComposer: () => {} })
+    const view = render(<PopupSelectView popup={popup} />)
+    expect(view.container.childElementCount).toBe(0)
+    await act(async () => {
+      popup.open('theme', spec(), 'ctx-A', SEGMENT)
+      await Promise.resolve()
+    })
+    const search = screen.getByRole('textbox', { name: 'Filter options' })
+    expect(document.activeElement).toBe(search)
+    expect(rowLabels()).toEqual(['Dark', 'Light', 'Sepia'])
+  })
+
+  it('typing filters rows locally and rebases the highlight', async () => {
+    const options = vi.fn(() => Promise.resolve(OPTIONS))
+    const { search } = await mountOpen({ options })
+    act(() => { fireEvent.change(search, { target: { value: 'li' } }) })
+    expect(rowLabels()).toEqual(['Light'])
+    expect(screen.getByRole('option').getAttribute('aria-selected')).toBe('true')
+    expect(options).toHaveBeenCalledTimes(1)
+    act(() => { fireEvent.change(search, { target: { value: 'zzz' } }) })
+    expect(screen.queryByRole('option')).toBeNull()
+    expect(screen.queryByText('No options')).not.toBeNull()
+  })
+
+  it('ArrowUp/Down move the filtered highlight; ArrowLeft/Right are left to the native caret', async () => {
+    const { search } = await mountOpen()
+    act(() => { fireEvent.keyDown(search, { key: 'ArrowDown' }) })
+    let options = screen.getAllByRole('option')
+    expect(options[1]!.getAttribute('aria-selected')).toBe('true')
+    act(() => { fireEvent.keyDown(search, { key: 'ArrowUp' }) })
+    options = screen.getAllByRole('option')
+    expect(options[0]!.getAttribute('aria-selected')).toBe('true')
+    // fireEvent returns false when preventDefault was called: arrow left/right must NOT be intercepted.
+    expect(fireEvent.keyDown(search, { key: 'ArrowLeft' })).toBe(true)
+    expect(fireEvent.keyDown(search, { key: 'ArrowRight' })).toBe(true)
+  })
+
+  it('Enter selects the highlighted row: onSelect, consume, close, focusComposer', async () => {
+    const seen: Array<{ option: SelectOption; context: string }> = []
+    const { view, search, consume, focusComposer } = await mountOpen({
+      onSelect: (option, context) => { seen.push({ option, context }) },
+    })
+    act(() => { fireEvent.keyDown(search, { key: 'ArrowDown' }) })
+    await act(async () => { fireEvent.keyDown(search, { key: 'Enter' }) })
+    expect(seen).toEqual([{ option: OPTIONS[1], context: 'ctx-A' }])
+    expect(consume).toHaveBeenCalledExactlyOnceWith(SEGMENT)
+    expect(focusComposer).toHaveBeenCalledTimes(1)
+    expect(view.container.childElementCount).toBe(0)
+  })
+
+  it('click selects a row; mouseenter moves the highlight', async () => {
+    const seen: SelectOption[] = []
+    const { view } = await mountOpen({ onSelect: (option) => { seen.push(option) } })
+    const options = screen.getAllByRole('option')
+    act(() => { fireEvent.mouseEnter(options[2]!) })
+    expect(screen.getAllByRole('option')[2]!.getAttribute('aria-selected')).toBe('true')
+    await act(async () => { fireEvent.click(options[2]!) })
+    expect(seen).toEqual([OPTIONS[2]])
+    expect(view.container.childElementCount).toBe(0)
+  })
+
+  it('submitting shows pending, locks the search input, and further Enter/click no-op', async () => {
+    let release!: () => void
+    const onSelect = vi.fn(() => new Promise<void>((resolve) => { release = resolve }))
+    const { search, consume } = await mountOpen({ onSelect })
+    await act(async () => { fireEvent.keyDown(search, { key: 'Enter' }) })
+    expect(screen.queryByText('Applying…')).not.toBeNull()
+    expect((search as HTMLInputElement).readOnly).toBe(true)
+    await act(async () => {
+      fireEvent.keyDown(search, { key: 'Enter' })
+      fireEvent.click(screen.getAllByRole('option')[1]!)
+    })
+    expect(onSelect).toHaveBeenCalledTimes(1)
+    await act(async () => {
+      release()
+      await Promise.resolve()
+    })
+    expect(consume).toHaveBeenCalledTimes(1)
+  })
+
+  it('a failed options load shows the error with a Retry button that reloads', async () => {
+    let attempts = 0
+    await mountOpen({
+      options: () => {
+        attempts += 1
+        return attempts === 1 ? Promise.reject(new Error('directory down')) : Promise.resolve(OPTIONS)
+      },
+    })
+    expect(screen.getByRole('alert').textContent).toContain('directory down')
+    await act(async () => {
+      fireEvent.click(screen.getByRole('button', { name: 'Retry' }))
+      await Promise.resolve()
+    })
+    expect(attempts).toBe(2)
+    expect(rowLabels()).toEqual(['Dark', 'Light', 'Sepia'])
+  })
+
+  it('an onSelect failure keeps the shell open with the error strip and no retry button (re-select is the retry)', async () => {
+    const { search, consume } = await mountOpen({ onSelect: () => Promise.reject(new Error('host rejected')) })
+    await act(async () => { fireEvent.keyDown(search, { key: 'Enter' }) })
+    expect(screen.getByRole('alert').textContent).toContain('host rejected')
+    expect(screen.queryByRole('button', { name: 'Retry' })).toBeNull()
+    expect(consume).not.toHaveBeenCalled()
+    expect(screen.getAllByRole('option').length).toBe(3)
+  })
+
+  it('Escape dismisses and restores composer focus', async () => {
+    const { view, search, focusComposer } = await mountOpen()
+    act(() => { fireEvent.keyDown(search, { key: 'Escape' }) })
+    expect(view.container.childElementCount).toBe(0)
+    expect(focusComposer).toHaveBeenCalledTimes(1)
+  })
+
+  it('an outside pointerdown dismisses without focusComposer; an inside one does not dismiss', async () => {
+    const { view, focusComposer } = await mountOpen()
+    act(() => { fireEvent.pointerDown(screen.getAllByRole('option')[0]!) })
+    expect(view.container.childElementCount).not.toBe(0)
+    act(() => { fireEvent.pointerDown(document.body) })
+    expect(view.container.childElementCount).toBe(0)
+    expect(focusComposer).not.toHaveBeenCalled()
+  })
+})

packages/client/ui-command/tests/popup.spec.ts

@@ -0,0 +1,356 @@
+/**
+ * PopupSelectController behavior (design §10.2/§10.3): one options load per
+ * open with local search filtering, filtered highlight movement,
+ * single-flight select with open-time context, consume-on-success (CAS miss
+ * benign), failure-keeps-open retry semantics for both options and onSelect,
+ * and binding-identity revocation of late settlements after
+ * dismiss/reopen/dispose.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import type { SelectOption } from '../src/client/contract.ts'
+import type { PopupSpec, TokenSegment } from '../src/client/popup.ts'
+import { filterOptions, PopupSelectController } from '../src/client/popup.ts'
+
+interface Ctx { readonly session: string }
+const CTX_A: Ctx = { session: 'A' }
+
+const OPTIONS: SelectOption[] = [
+  { id: 'dark', label: 'Dark' },
+  { id: 'light', label: 'Light', active: true },
+  { id: 'sepia', label: 'Sepia', detail: 'warm' },
+]
+
+const SEGMENT: TokenSegment = { via: 'enter', token: '/theme' }
+
+function spec(overrides: Partial<PopupSpec<Ctx>> = {}): PopupSpec<Ctx> {
+  return {
+    options: () => Promise.resolve(OPTIONS),
+    onSelect: () => undefined,
+    ...overrides,
+  }
+}
+
+/** Fake session wiring: records consume/focus calls; consume answer is settable per test. */
+function makeDeps(consumeResult = true) {
+  const consume = vi.fn((_segment: TokenSegment) => consumeResult)
+  const focusComposer = vi.fn()
+  return { consume, focusComposer }
+}
+
+async function readyPopup(overrides: Partial<PopupSpec<Ctx>> = {}, deps = makeDeps()) {
+  const popup = new PopupSelectController<Ctx>(deps)
+  popup.open('theme', spec(overrides), CTX_A, SEGMENT)
+  await Promise.resolve()
+  return { popup, deps }
+}
+
+describe('filterOptions', () => {
+  it('matches case-insensitively over label and detail; blank keeps all', () => {
+    expect(filterOptions(OPTIONS, '')).toBe(OPTIONS)
+    expect(filterOptions(OPTIONS, '  ')).toBe(OPTIONS)
+    expect(filterOptions(OPTIONS, 'DARK')).toEqual([OPTIONS[0]])
+    expect(filterOptions(OPTIONS, 'warm')).toEqual([OPTIONS[2]])
+    expect(filterOptions(OPTIONS, 'nope')).toEqual([])
+  })
+})
+
+describe('open and options load', () => {
+  it('publishes pending immediately, ready when options land', async () => {
+    const popup = new PopupSelectController<Ctx>(makeDeps())
+    let release!: (options: readonly SelectOption[]) => void
+    popup.open('theme', spec({ options: () => new Promise((resolve) => { release = resolve }) }), CTX_A, SEGMENT)
+    expect(popup.state.getSnapshot()).toMatchObject({ open: true, command: 'theme', status: 'pending', search: '', submitting: false, error: null })
+    release(OPTIONS)
+    await Promise.resolve()
+    expect(popup.state.getSnapshot()).toMatchObject({ status: 'ready', options: OPTIONS, active: 0 })
+  })
+
+  it('loads options exactly once: search filters locally without re-querying the provider', async () => {
+    const options = vi.fn(() => Promise.resolve(OPTIONS))
+    const { popup } = await readyPopup({ options })
+    popup.setSearch('li')
+    popup.setSearch('light')
+    const s = popup.state.getSnapshot()
+    expect(options).toHaveBeenCalledTimes(1)
+    expect(s.options).toEqual(OPTIONS) // original array retained; filtering is view-side
+    expect(s.search).toBe('light')
+    expect(filterOptions(s.options, s.search)).toEqual([OPTIONS[1]])
+  })
+
+  it('a reopen aborts the old load and drops its late arrival', async () => {
+    const popup = new PopupSelectController<Ctx>(makeDeps())
+    let firstSignal!: AbortSignal
+    let releaseFirst!: (options: readonly SelectOption[]) => void
+    popup.open('alpha', spec({
+      options: (_ctx, signal) => {
+        firstSignal = signal
+        return new Promise((resolve) => { releaseFirst = resolve })
+      },
+    }), CTX_A, SEGMENT)
+    popup.open('beta', spec(), CTX_A, SEGMENT)
+    expect(firstSignal.aborted).toBe(true)
+    releaseFirst([{ id: 'stale', label: 'stale' }])
+    await Promise.resolve()
+    const s = popup.state.getSnapshot()
+    expect(s.command).toBe('beta')
+    expect(s.options).toEqual(OPTIONS)
+  })
+
+  it('dispose aborts the flying load, clears state, and drops the late arrival', async () => {
+    const popup = new PopupSelectController<Ctx>(makeDeps())
+    let signal!: AbortSignal
+    let release!: (options: readonly SelectOption[]) => void
+    popup.open('theme', spec({
+      options: (_ctx, s) => {
+        signal = s
+        return new Promise((resolve) => { release = resolve })
+      },
+    }), CTX_A, SEGMENT)
+    popup.dispose()
+    expect(signal.aborted).toBe(true)
+    expect(popup.state.getSnapshot().open).toBe(false)
+    release(OPTIONS)
+    await Promise.resolve()
+    expect(popup.state.getSnapshot().open).toBe(false)
+  })
+
+  it('an options failure keeps the shell open with search retained, surfaces the error, and retry reloads', async () => {
+    let attempts = 0
+    const { popup } = await readyPopup({
+      options: () => {
+        attempts += 1
+        return attempts === 1 ? Promise.reject(new Error('directory down')) : Promise.resolve(OPTIONS)
+      },
+    })
+    await Promise.resolve()
+    popup.setSearch('da')
+    // The failure landed before setSearch (readyPopup awaited); search must survive it and retry.
+    expect(popup.state.getSnapshot()).toMatchObject({ open: true, status: 'failed', error: 'directory down', search: 'da' })
+    popup.retry()
+    expect(popup.state.getSnapshot()).toMatchObject({ status: 'pending', error: null })
+    await Promise.resolve()
+    expect(popup.state.getSnapshot()).toMatchObject({ status: 'ready', options: OPTIONS, search: 'da' })
+    expect(attempts).toBe(2)
+  })
+
+  it('retry is a no-op unless the options load failed', async () => {
+    const { popup } = await readyPopup()
+    popup.retry()
+    expect(popup.state.getSnapshot().status).toBe('ready')
+    const closed = new PopupSelectController<Ctx>(makeDeps())
+    closed.retry()
+    expect(closed.state.getSnapshot().open).toBe(false)
+  })
+})
+
+describe('search / move / highlight over the filtered list', () => {
+  it('setSearch rebases the highlight to 0 and ignores closed shells and identical text', async () => {
+    const { popup } = await readyPopup()
+    popup.move(1)
+    expect(popup.state.getSnapshot().active).toBe(1)
+    popup.setSearch('s')
+    expect(popup.state.getSnapshot()).toMatchObject({ search: 's', active: 0 })
+    const before = popup.state.getSnapshot()
+    popup.setSearch('s')
+    expect(popup.state.getSnapshot()).toBe(before)
+    const closed = new PopupSelectController<Ctx>(makeDeps())
+    closed.setSearch('x')
+    expect(closed.state.getSnapshot().search).toBe('')
+  })
+
+  it('move wraps across the FILTERED rows', async () => {
+    const { popup } = await readyPopup()
+    popup.setSearch('a') // Dark, Sepia (detail 'warm' also matches 'a'? label match: Dark, Sepia)
+    const rows = filterOptions(popup.state.getSnapshot().options, 'a')
+    expect(rows.length).toBe(2)
+    popup.move(1)
+    expect(popup.state.getSnapshot().active).toBe(1)
+    popup.move(1)
+    expect(popup.state.getSnapshot().active).toBe(0)
+    popup.move(-1)
+    expect(popup.state.getSnapshot().active).toBe(1)
+  })
+
+  it('move is a no-op while pending, closed, or when the filter matches nothing', async () => {
+    const pending = new PopupSelectController<Ctx>(makeDeps())
+    pending.open('theme', spec({ options: () => new Promise(() => {}) }), CTX_A, SEGMENT)
+    pending.move(1)
+    expect(pending.state.getSnapshot().active).toBe(0)
+    const closed = new PopupSelectController<Ctx>(makeDeps())
+    closed.move(1)
+    expect(closed.state.getSnapshot().active).toBe(0)
+    const { popup } = await readyPopup()
+    popup.setSearch('nope')
+    popup.move(1)
+    expect(popup.state.getSnapshot().active).toBe(0)
+  })
+
+  it('highlight sets the active filtered row and ignores out-of-range or same-index calls', async () => {
+    const { popup } = await readyPopup()
+    popup.highlight(1)
+    expect(popup.state.getSnapshot().active).toBe(1)
+    popup.highlight(99)
+    popup.highlight(-1)
+    popup.highlight(1)
+    expect(popup.state.getSnapshot().active).toBe(1)
+    popup.setSearch('dark') // one filtered row → index 1 now out of range
+    popup.highlight(1)
+    expect(popup.state.getSnapshot().active).toBe(0)
+  })
+})
+
+describe('select', () => {
+  it('runs onSelect with the filtered option and the open-time context, consumes, closes, refocuses', async () => {
+    const seen: Array<{ option: SelectOption; context: Ctx }> = []
+    const deps = makeDeps()
+    const { popup } = await readyPopup({
+      onSelect: (option, context) => { seen.push({ option, context }) },
+    }, deps)
+    popup.setSearch('light')
+    await popup.select(0)
+    expect(seen).toEqual([{ option: OPTIONS[1], context: CTX_A }])
+    expect(deps.consume).toHaveBeenCalledExactlyOnceWith(SEGMENT)
+    expect(deps.focusComposer).toHaveBeenCalledTimes(1)
+    expect(popup.state.getSnapshot().open).toBe(false)
+  })
+
+  it('is single-flight: the first call enters submitting, later Enter/click calls no-op', async () => {
+    let release!: () => void
+    const onSelect = vi.fn(() => new Promise<void>((resolve) => { release = resolve }))
+    const deps = makeDeps()
+    const { popup } = await readyPopup({ onSelect }, deps)
+    const first = popup.select(0)
+    expect(popup.state.getSnapshot().submitting).toBe(true)
+    await popup.select(0)
+    await popup.select(1)
+    popup.setSearch('x') // locked while submitting
+    popup.move(1)
+    popup.highlight(1)
+    expect(popup.state.getSnapshot()).toMatchObject({ search: '', active: 0 })
+    release()
+    await first
+    expect(onSelect).toHaveBeenCalledTimes(1)
+    expect(deps.consume).toHaveBeenCalledTimes(1)
+    expect(popup.state.getSnapshot().open).toBe(false)
+  })
+
+  it('a consume CAS miss is benign: no retry, still closes and refocuses', async () => {
+    const deps = makeDeps(false)
+    const { popup } = await readyPopup({}, deps)
+    await popup.select(0)
+    expect(deps.consume).toHaveBeenCalledTimes(1)
+    expect(deps.focusComposer).toHaveBeenCalledTimes(1)
+    expect(popup.state.getSnapshot().open).toBe(false)
+  })
+
+  it('an onSelect failure keeps the shell open with search/highlight/token intact, no consumption, and select re-arms', async () => {
+    let attempts = 0
+    const deps = makeDeps()
+    const { popup } = await readyPopup({
+      onSelect: () => {
+        attempts += 1
+        if (attempts === 1) throw new Error('host rejected')
+        return undefined
+      },
+    }, deps)
+    popup.setSearch('a')
+    popup.move(1)
+    await popup.select(1)
+    expect(popup.state.getSnapshot()).toMatchObject({
+      open: true, status: 'ready', submitting: false, error: 'host rejected', search: 'a', active: 1,
+    })
+    expect(deps.consume).not.toHaveBeenCalled()
+    await popup.select(1) // retry = selecting again
+    expect(deps.consume).toHaveBeenCalledExactlyOnceWith(SEGMENT)
+    expect(popup.state.getSnapshot().open).toBe(false)
+  })
+
+  it('ignores selects while closed, pending, failed, or out of filtered range', async () => {
+    const closed = new PopupSelectController<Ctx>(makeDeps())
+    await closed.select(0)
+    expect(closed.state.getSnapshot().open).toBe(false)
+    const failedDeps = makeDeps()
+    const { popup: failed } = await readyPopup({ options: () => Promise.reject(new Error('x')) }, failedDeps)
+    await failed.select(0)
+    expect(failedDeps.consume).not.toHaveBeenCalled()
+    const deps = makeDeps()
+    const { popup } = await readyPopup({}, deps)
+    popup.setSearch('dark')
+    await popup.select(1) // only one filtered row
+    expect(deps.consume).not.toHaveBeenCalled()
+    expect(popup.state.getSnapshot().open).toBe(true)
+  })
+
+  it('a dismiss racing a succeeding onSelect revokes it: no consume, no focus, state stays closed', async () => {
+    let release!: () => void
+    const deps = makeDeps()
+    const { popup } = await readyPopup({
+      onSelect: () => new Promise<void>((resolve) => { release = resolve }),
+    }, deps)
+    const selecting = popup.select(0)
+    popup.dismiss()
+    release()
+    await selecting
+    expect(deps.consume).not.toHaveBeenCalled()
+    expect(deps.focusComposer).not.toHaveBeenCalled()
+    expect(popup.state.getSnapshot().open).toBe(false)
+  })
+
+  it('a dispose racing a failing onSelect revokes its error write', async () => {
+    let reject!: (error: Error) => void
+    const deps = makeDeps()
+    const { popup } = await readyPopup({
+      onSelect: () => new Promise<void>((_resolve, rej) => { reject = rej }),
+    }, deps)
+    const selecting = popup.select(0)
+    popup.dispose()
+    reject(new Error('late'))
+    await selecting
+    expect(popup.state.getSnapshot()).toMatchObject({ open: false, error: null })
+    expect(deps.consume).not.toHaveBeenCalled()
+  })
+
+  it('a reopen racing a succeeding onSelect keeps the new shell: no consume of the old segment', async () => {
+    let release!: () => void
+    const deps = makeDeps()
+    const { popup } = await readyPopup({
+      onSelect: () => new Promise<void>((resolve) => { release = resolve }),
+    }, deps)
+    const selecting = popup.select(0)
+    popup.open('other', spec(), CTX_A, { via: 'enter', token: '/other' })
+    release()
+    await selecting
+    await Promise.resolve()
+    expect(deps.consume).not.toHaveBeenCalled()
+    expect(popup.state.getSnapshot()).toMatchObject({ open: true, command: 'other' })
+  })
+})
+
+describe('dismiss / dispose', () => {
+  it('dismiss closes, aborts the flying fetch, and is a no-op when already closed', async () => {
+    const deps = makeDeps()
+    const popup = new PopupSelectController<Ctx>(deps)
+    let signal!: AbortSignal
+    popup.open('theme', spec({
+      options: (_ctx, s) => {
+        signal = s
+        return new Promise(() => {})
+      },
+    }), CTX_A, SEGMENT)
+    popup.dismiss()
+    expect(signal.aborted).toBe(true)
+    expect(popup.state.getSnapshot().open).toBe(false)
+    expect(deps.focusComposer).not.toHaveBeenCalled() // outside-pointer path: the click's target takes focus
+    popup.dismiss()
+    popup.dispose()
+    expect(popup.state.getSnapshot().open).toBe(false)
+  })
+
+  it('the Escape path restores composer focus explicitly', async () => {
+    const deps = makeDeps()
+    const { popup } = await readyPopup({}, deps)
+    popup.dismiss({ focusComposer: true })
+    expect(deps.focusComposer).toHaveBeenCalledTimes(1)
+    expect(popup.state.getSnapshot().open).toBe(false)
+  })
+})

packages/client/ui-command/tests/service.spec.ts

@@ -0,0 +1,548 @@
+/**
+ * CommandService tests on a real cordis Context with fake slash/connection
+ * faces and real session scopes (createScope): session-keyed candidate
+ * synthesis (host catalog by sessionId + contributions by availability,
+ * collision fail-loud), the dispatch decision table cell by cell, matchSpace
+ * hot-key policy, matchEnter strong-wait / reject, the sessionId execute
+ * payload, the scoped consume-token dispatch, per-session popupFor
+ * lifecycle, and the directory invalidation event subscriptions.
+ */
+import { Context } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import { createScope, scopeOf } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ClientSessionContext, ConsumeTokenRequest, SlashPick, SlashSource } from '@deepseek-ai/dsh-client-ui-slash/client'
+import type { CommandContribution, CommandUiSpec, SelectOption } from '../src/client/contract.ts'
+import type { CommandDescriptor } from '../src/client/directory.ts'
+import { CommandService } from '../src/client/service.ts'
+
+const sid = (k: string): SessionId => k as SessionId
+
+/** The agent-backed session projection (single state; identity only). */
+const proj = (id: string): ClientSessionContext => ({ sessionId: sid(id) })
+
+const S1_CMDS: CommandDescriptor[] = [
+  { name: 'plan', description: 'bare kind' },
+  { name: 'goal', description: 'leadingInput kind', input: { hint: 'goal text' } },
+]
+
+const S2_CMDS: CommandDescriptor[] = [
+  ...S1_CMDS,
+  { name: 'attach', description: 'scoped shadow', input: { hint: 'path' } },
+]
+
+type ExecuteValue = { matched: boolean; result?: { kind: 'success' | 'error'; text?: string } }
+
+interface BenchOptions {
+  /** Scripted catalog per list payload; default serves the fixed catalogs by session. */
+  commands?: (payload: { sessionId: SessionId }) => Promise<{ commands: CommandDescriptor[] }>
+  execute?: (payload: { sessionId: SessionId; line: string }) => Promise<ExecuteValue>
+}
+
+async function bench(opts: BenchOptions = {}) {
+  const ctx = new Context()
+  const registered = new Map<string, SlashSource>()
+  const listCalls: Array<{ sessionId: SessionId }> = []
+  const executeCalls: Array<{ sessionId: SessionId; line: string }> = []
+  const api = {
+    commands: {
+      list: async (payload: { sessionId: SessionId }) => {
+        listCalls.push(payload)
+        const value = await (opts.commands ?? (p => Promise.resolve({
+          commands: p.sessionId === sid('s2') ? S2_CMDS : S1_CMDS,
+        })))(payload)
+        return { result: { ok: true as const, value } }
+      },
+      execute: async (payload: { sessionId: SessionId; line: string }) => {
+        executeCalls.push(payload)
+        const value = await (opts.execute ?? (() => Promise.resolve({ matched: true })))(payload)
+        return { result: { ok: true as const, value } }
+      },
+    },
+  }
+  ctx.provide('slash', {
+    registerSource(src: SlashSource) {
+      const key = `${src.trigger} ${src.name}`
+      registered.set(key, src)
+      return () => { registered.delete(key) }
+    },
+  })
+  // Real scope tags behind a fake sessions face (scope/scopeOf are all the service reads).
+  const scopes = new Map<SessionId, { ctx: Context; fiber: { dispose(): Promise<void> } }>()
+  ctx.provide('sessions', {
+    scope: (id: SessionId) => scopes.get(id)?.ctx,
+    scopeOf: (c: Context) => scopeOf(c),
+  })
+  ctx.provide('connection', { api })
+  /** Notices the fake conversation face collected (runDetached routing). */
+  const notices: Array<{ scope: SessionId | undefined; level: 'info' | 'error'; text: string }> = []
+  ctx.provide('conversation', {
+    input: {
+      for: (actx: Context) => ({
+        notify: (level: 'info' | 'error', text: string) => {
+          notices.push({ scope: scopeOf(actx), level, text })
+        },
+      }),
+    },
+  })
+  const fiber = ctx.plugin(CommandService)
+  await fiber.await()
+  const command = ctx.get('command') as CommandService
+  const source = registered.get('/ command')
+  if (source === undefined) throw new Error('command source not registered')
+  const mint = (key: string) => {
+    const handle = createScope(ctx, sid(key))
+    scopes.set(sid(key), handle)
+    return handle
+  }
+  /** Warm one session's catalog through the source's own candidate pull. */
+  const warm = async (session: ClientSessionContext) => {
+    await source.candidates(session, { query: '', position: 'leading', signal: new AbortController().signal })
+  }
+  return { ctx, fiber, command, source, mint, warm, listCalls, executeCalls, registered, notices }
+}
+
+function menuPick(source: SlashSource, name: string, session: ClientSessionContext, end?: number) {
+  const pick: SlashPick = {
+    candidate: { name },
+    session,
+    position: 'leading',
+    via: 'menu',
+    span: { start: 0, end: end ?? name.length + 1, draftRev: 3 },
+  }
+  return source.onPick(pick)
+}
+
+const themeUi = (over: Partial<CommandUiSpec> = {}): CommandUiSpec => ({
+  kind: 'popupSelect',
+  options: () => Promise.resolve([{ id: 'dark', label: 'Dark' }]),
+  onSelect: () => undefined,
+  ...over,
+})
+
+const themeContribution = (over: Partial<CommandContribution> = {}): CommandContribution => ({
+  name: 'theme',
+  description: 'client popup kind',
+  available: () => true,
+  ui: themeUi(),
+  ...over,
+})
+
+const req = (query: string, position: 'leading' | 'inline' = 'leading') =>
+  ({ query, position, signal: new AbortController().signal })
+
+describe('registration', () => {
+  it('registers the "/" source with matchSpace/matchEnter/warm hooks and removes it on fiber disposal', async () => {
+    const { registered, source, fiber } = await bench()
+    expect(typeof source.matchSpace).toBe('function')
+    expect(typeof source.matchEnter).toBe('function')
+    expect(typeof source.warm).toBe('function')
+    expect([...registered.keys()]).toEqual(['/ command'])
+    await fiber.dispose()
+    expect(registered.size).toBe(0)
+  })
+
+  it('the warm hook prewarms the session key: one pull per session, no duplicate over pending', async () => {
+    const { source, listCalls } = await bench()
+    source.warm!(proj('s1'))
+    expect(listCalls).toEqual([{ sessionId: sid('s1') }])
+    source.warm!(proj('s2'))
+    expect(listCalls).toEqual([{ sessionId: sid('s1') }, { sessionId: sid('s2') }])
+    source.warm!(proj('s1')) // s1 already pending → no duplicate pull
+    expect(listCalls).toHaveLength(2)
+  })
+})
+
+describe('candidates', () => {
+  it('pulls the session catalog; prefix filter and hint mapping apply', async () => {
+    const { source, listCalls } = await bench()
+    const list = await source.candidates(proj('s1'), req('g'))
+    expect(listCalls).toEqual([{ sessionId: sid('s1') }])
+    expect(list).toEqual([{ name: 'goal', description: 'leadingInput kind', hint: 'goal text' }])
+  })
+
+  it('catalogs are per session: another session pulls its own key', async () => {
+    const { source, listCalls } = await bench()
+    const names = (await source.candidates(proj('s2'), req(''))).map(c => c.name)
+    expect(listCalls).toEqual([{ sessionId: sid('s2') }])
+    expect(names).toEqual(['plan', 'goal', 'attach'])
+  })
+
+  it('hides leadingInput commands at inline position', async () => {
+    const { source } = await bench()
+    const names = (await source.candidates(proj('s1'), req('', 'inline'))).map(c => c.name)
+    expect(names).toEqual(['plan'])
+  })
+
+  it('merges available contributions and filters unavailable ones with the per-call projection', async () => {
+    const { command, source } = await bench()
+    const available = vi.fn((session: ClientSessionContext) => session.sessionId === sid('s1'))
+    command.register(themeContribution({ available }))
+    const s1Names = (await source.candidates(proj('s1'), req(''))).map(c => c.name)
+    expect(s1Names).toEqual(['plan', 'goal', 'theme'])
+    expect(available).toHaveBeenLastCalledWith(proj('s1'))
+    const s2Names = (await source.candidates(proj('s2'), req(''))).map(c => c.name)
+    expect(s2Names).not.toContain('theme')
+  })
+
+  it('contribution rows ride the same query prefix filter', async () => {
+    const { command, source } = await bench()
+    command.register(themeContribution())
+    const names = (await source.candidates(proj('s1'), req('th'))).map(c => c.name)
+    expect(names).toEqual(['theme'])
+  })
+
+  it('a contribution/host name collision fails loud', async () => {
+    const { command, source } = await bench()
+    command.register(themeContribution({ name: 'plan' }))
+    await expect(source.candidates(proj('s1'), req(''))).rejects.toThrow('collides with a host command')
+  })
+})
+
+describe('dispatch (menu column)', () => {
+  it('contribution → opens the session popup with the open-time projection, no execute', async () => {
+    const { command, source, mint, warm, executeCalls } = await bench()
+    const options = vi.fn((_s: ClientSessionContext) => Promise.resolve([{ id: 'dark', label: 'Dark' }]))
+    command.register(themeContribution({ ui: themeUi({ options }) }))
+    const scope = mint('s1')
+    await warm(proj('s1'))
+    expect(menuPick(source, 'theme', proj('s1'))).toBe('handled')
+    const popup = command.popupFor(scope.ctx)
+    expect(popup.state.getSnapshot()).toMatchObject({ open: true, command: 'theme' })
+    expect(options).toHaveBeenCalledExactlyOnceWith(proj('s1'), expect.any(AbortSignal))
+    expect(executeCalls).toEqual([])
+  })
+
+  it('an unavailable contribution falls through to the host catalog', async () => {
+    const { command, source, mint, warm } = await bench()
+    command.register(themeContribution({ available: () => false }))
+    const scope = mint('s1')
+    await warm(proj('s1'))
+    expect(menuPick(source, 'theme', proj('s1'))).toBeUndefined() // no host 'theme' either
+    expect(command.popupFor(scope.ctx).state.getSnapshot().open).toBe(false)
+  })
+
+  it('host leadingInput → {claim} with token "/name " and hint; claiming never executes', async () => {
+    const { source, warm, executeCalls } = await bench()
+    await warm(proj('s1'))
+    const outcome = menuPick(source, 'goal', proj('s1'))
+    if (outcome === undefined || outcome === 'handled' || !('claim' in outcome)) throw new Error('expected claim')
+    expect(outcome.claim.token).toBe('/goal ')
+    expect(outcome.claim.hint).toBe('goal text')
+    expect(executeCalls).toEqual([])
+  })
+
+  it('host bare → consume-token span guard on the session scope + detached execute', async () => {
+    const { source, mint, warm, executeCalls } = await bench()
+    const scope = mint('s1')
+    const consumes: ConsumeTokenRequest[] = []
+    scope.ctx.on('slash/input-consume-token', (r) => {
+      consumes.push(r)
+      return true
+    })
+    await warm(proj('s1'))
+    expect(menuPick(source, 'plan', proj('s1'), 5)).toBe('handled')
+    expect(consumes).toEqual([{ guard: { kind: 'span', span: { start: 0, end: 5, draftRev: 3 } } }])
+    await Promise.resolve()
+    expect(executeCalls).toEqual([{ sessionId: sid('s1'), line: '/plan' }])
+  })
+
+  it('a name the directory no longer serves → undefined (snapshot swapped between menu and pick)', async () => {
+    const { source, warm } = await bench()
+    await warm(proj('s1'))
+    expect(menuPick(source, 'gone', proj('s1'))).toBeUndefined()
+  })
+})
+
+describe('matchSpace (space column)', () => {
+  it('answers undefined from a not-ready key (no waiting, no RPC)', async () => {
+    const { source, listCalls } = await bench()
+    expect(source.matchSpace!(proj('s1'), '/goal')).toBeUndefined()
+    expect(listCalls).toEqual([])
+  })
+
+  it('hot leadingInput exact token → {claim}; the key axis is the session', async () => {
+    const { source, warm } = await bench()
+    await warm(proj('s2'))
+    const outcome = source.matchSpace!(proj('s2'), '/attach')
+    if (outcome === undefined || outcome === 'handled' || !('claim' in outcome)) throw new Error('expected claim')
+    expect(outcome.claim.token).toBe('/attach ')
+    // s1's key is still cold: the same token answers undefined there.
+    expect(source.matchSpace!(proj('s1'), '/attach')).toBeUndefined()
+  })
+
+  it('bare kind and contribution names stay plain text', async () => {
+    const { command, source, warm } = await bench()
+    command.register(themeContribution())
+    await warm(proj('s1'))
+    expect(source.matchSpace!(proj('s1'), '/plan')).toBeUndefined()
+    expect(source.matchSpace!(proj('s1'), '/theme')).toBeUndefined()
+  })
+
+  it('unknown token / non-slash token → undefined', async () => {
+    const { source, warm } = await bench()
+    await warm(proj('s1'))
+    expect(source.matchSpace!(proj('s1'), '/nope')).toBeUndefined()
+    expect(source.matchSpace!(proj('s1'), 'plan')).toBeUndefined()
+  })
+})
+
+describe('matchEnter (enter column)', () => {
+  const signal = () => new AbortController().signal
+
+  it('strong-waits a cold key before adjudicating', async () => {
+    let release!: (value: { commands: CommandDescriptor[] }) => void
+    const { source } = await bench({
+      commands: () => new Promise((resolve) => { release = resolve }),
+    })
+    const wait = source.matchEnter!(proj('s1'), '/goal args', signal())
+    release({ commands: S1_CMDS })
+    const outcome = await wait
+    if (outcome === undefined || outcome === 'handled' || !('claim' in outcome)) throw new Error('expected claim')
+    expect(outcome.claim.token).toBe('/goal ')
+  })
+
+  it('rejects when warmup fails (never a silent downgrade)', async () => {
+    const { source } = await bench({
+      commands: () => Promise.reject(new Error('warmup boom')),
+    })
+    await expect(source.matchEnter!(proj('s1'), '/goal', signal())).rejects.toThrow('warmup boom')
+  })
+
+  it('leadingInput claims args-tolerant (bare and with trailing text)', async () => {
+    const { source, warm } = await bench()
+    await warm(proj('s1'))
+    for (const line of ['/goal', '/goal refactor the loop']) {
+      const outcome = await source.matchEnter!(proj('s1'), line, signal())
+      if (outcome === undefined || outcome === 'handled' || !('claim' in outcome)) throw new Error('expected claim')
+      expect(outcome.claim.token).toBe('/goal ')
+    }
+  })
+
+  it('bare host command executes detached with the bare-token consume guard', async () => {
+    const { source, mint, warm, executeCalls } = await bench()
+    const scope = mint('s1')
+    const consumes: ConsumeTokenRequest[] = []
+    scope.ctx.on('slash/input-consume-token', (r) => {
+      consumes.push(r)
+      return true
+    })
+    await warm(proj('s1'))
+    await expect(source.matchEnter!(proj('s1'), '/plan', signal())).resolves.toBe('handled')
+    expect(consumes).toEqual([{ guard: { kind: 'bare-token', token: '/plan' } }])
+    await Promise.resolve()
+    expect(executeCalls).toEqual([{ sessionId: sid('s1'), line: '/plan' }])
+  })
+
+  it('bare kind with trailing text → undefined and no RPC (default sink owns the line)', async () => {
+    const { source, warm, executeCalls } = await bench()
+    await warm(proj('s1'))
+    await expect(source.matchEnter!(proj('s1'), '/plan now', signal())).resolves.toBeUndefined()
+    expect(executeCalls).toEqual([])
+  })
+
+  it('contribution: bare token opens the popup without touching the directory; args → undefined', async () => {
+    const { command, source, mint, listCalls } = await bench()
+    command.register(themeContribution())
+    const scope = mint('s1')
+    await expect(source.matchEnter!(proj('s1'), '/theme', signal())).resolves.toBe('handled')
+    expect(command.popupFor(scope.ctx).state.getSnapshot().open).toBe(true)
+    expect(listCalls).toEqual([]) // contribution short-circuits ahead of ensureReady
+    await expect(source.matchEnter!(proj('s1'), '/theme dark', signal())).resolves.toBeUndefined()
+  })
+
+  it('unknown name, bare "/", and non-slash lines → undefined', async () => {
+    const { source, warm } = await bench()
+    await warm(proj('s1'))
+    await expect(source.matchEnter!(proj('s1'), '/nope', signal())).resolves.toBeUndefined()
+    await expect(source.matchEnter!(proj('s1'), '/', signal())).resolves.toBeUndefined()
+    await expect(source.matchEnter!(proj('s1'), 'plain text', signal())).resolves.toBeUndefined()
+  })
+})
+
+describe('execute payload', () => {
+  it('claim.submit addresses the session and maps the detached result', async () => {
+    const { source, warm, executeCalls } = await bench({
+      execute: () => Promise.resolve({ matched: true, result: { kind: 'success', text: 'goal set' } }),
+    })
+    await warm(proj('s1'))
+    const outcome = source.matchSpace!(proj('s1'), '/goal')
+    if (outcome === undefined || outcome === 'handled' || !('claim' in outcome)) throw new Error('expected claim')
+    const settled = await outcome.claim.submit('ship it', new Context())
+    expect(executeCalls).toEqual([{ sessionId: sid('s1'), line: '/goal ship it' }])
+    expect(settled).toEqual({ kind: 'success', text: 'goal set' })
+  })
+
+  it('maps matched:false to an error outcome and a matched bare result to success', async () => {
+    const claimOf = async (opts: BenchOptions) => {
+      const b = await bench(opts)
+      await b.warm(proj('s1'))
+      const outcome = b.source.matchSpace!(proj('s1'), '/goal')
+      if (outcome === undefined || outcome === 'handled' || !('claim' in outcome)) throw new Error('expected claim')
+      return outcome.claim
+    }
+    const first = await claimOf({ execute: () => Promise.resolve({ matched: false }) })
+    const bad = await first.submit('x', new Context())
+    expect(bad.kind).toBe('error')
+    const second = await claimOf({ execute: () => Promise.resolve({ matched: true }) })
+    await expect(second.submit('', new Context())).resolves.toEqual({ kind: 'success' })
+  })
+})
+
+describe('detached result notices', () => {
+  const flush = () => new Promise(resolve => setTimeout(resolve, 0))
+
+  it('success text → info; error result → error; rejection → error, all on the triggering session', async () => {
+    let mode: 'info' | 'error' | 'reject' = 'info'
+    const { source, mint, warm, notices } = await bench({
+      execute: () => {
+        if (mode === 'reject') return Promise.reject(new Error('network down'))
+        return Promise.resolve({
+          matched: true,
+          result: mode === 'info'
+            ? { kind: 'success' as const, text: 'compacted 12 messages' }
+            : { kind: 'error' as const, text: 'plan mode refused' },
+        })
+      },
+    })
+    mint('s1')
+    await warm(proj('s1'))
+    menuPick(source, 'plan', proj('s1'))
+    await flush()
+    expect(notices).toEqual([{ scope: sid('s1'), level: 'info', text: 'compacted 12 messages' }])
+
+    notices.length = 0
+    mode = 'error'
+    await source.matchEnter!(proj('s1'), '/plan', new AbortController().signal)
+    await flush()
+    expect(notices).toEqual([{ scope: sid('s1'), level: 'error', text: 'plan mode refused' }])
+
+    notices.length = 0
+    mode = 'reject'
+    menuPick(source, 'plan', proj('s1'))
+    await flush()
+    expect(notices).toEqual([{ scope: sid('s1'), level: 'error', text: 'network down' }])
+  })
+
+  it('success without text stays silent; a torn-down scope drops the notice', async () => {
+    const { source, warm, notices } = await bench({
+      execute: () => Promise.resolve({ matched: true, result: { kind: 'success' as const, text: 'orphan' } }),
+    })
+    await warm(proj('ghost')) // never minted: scopeFor misses
+    menuPick(source, 'plan', proj('ghost'))
+    await flush()
+    expect(notices).toEqual([])
+  })
+})
+
+describe('register (contribution face)', () => {
+  it('duplicate registration throws; the disposer frees the name', async () => {
+    const { command } = await bench()
+    const dispose = command.register(themeContribution())
+    expect(() => command.register(themeContribution())).toThrow('duplicate contribution')
+    dispose()
+    command.register(themeContribution())()
+  })
+})
+
+describe('popupFor', () => {
+  it('resolves lazily per session; a foreign session gets its own controller; unscoped ctx throws', async () => {
+    const { ctx, command, mint } = await bench()
+    const a = mint('s1')
+    const first = command.popupFor(a.ctx)
+    expect(command.popupFor(a.ctx)).toBe(first)
+    expect(command.popupFor(mint('s2').ctx)).not.toBe(first)
+    expect(() => command.popupFor(ctx)).toThrow('requires a session scope')
+  })
+
+  it('a successful select dispatches the scoped consume-token and fires the bound composer focus', async () => {
+    const { command, source, mint } = await bench()
+    const onSelect = vi.fn()
+    command.register(themeContribution({ ui: themeUi({ onSelect }) }))
+    const scope = mint('s1')
+    const consumes: ConsumeTokenRequest[] = []
+    scope.ctx.on('slash/input-consume-token', (r) => {
+      consumes.push(r)
+      return true
+    })
+    const focus = vi.fn()
+    command.bindComposerFocus(sid('s1'), focus)
+
+    expect(menuPick(source, 'theme', proj('s1'), 6)).toBe('handled')
+    const popup = command.popupFor(scope.ctx)
+    await Promise.resolve() // options land
+    await popup.select(0)
+    expect(onSelect).toHaveBeenCalledExactlyOnceWith({ id: 'dark', label: 'Dark' } satisfies SelectOption, proj('s1'))
+    expect(consumes).toEqual([{ guard: { kind: 'span', span: { start: 0, end: 6, draftRev: 3 } } }])
+    expect(focus).toHaveBeenCalledTimes(1)
+  })
+
+  it('the enter path opens with the bare-token guard', async () => {
+    const { command, source, mint } = await bench()
+    command.register(themeContribution())
+    const scope = mint('s1')
+    const consumes: ConsumeTokenRequest[] = []
+    scope.ctx.on('slash/input-consume-token', (r) => {
+      consumes.push(r)
+      return true
+    })
+    await source.matchEnter!(proj('s1'), '/theme', new AbortController().signal)
+    const popup = command.popupFor(scope.ctx)
+    await Promise.resolve()
+    await popup.select(0)
+    expect(consumes).toEqual([{ guard: { kind: 'bare-token', token: '/theme' } }])
+  })
+
+  it('the scope disposer disposes the controller and a re-mint resolves fresh', async () => {
+    const { command, source, mint } = await bench()
+    command.register(themeContribution())
+    const scope = mint('s1')
+    await source.matchEnter!(proj('s1'), '/theme', new AbortController().signal)
+    const popup = command.popupFor(scope.ctx)
+    expect(popup.state.getSnapshot().open).toBe(true)
+
+    await scope.fiber.dispose()
+    expect(popup.state.getSnapshot().open).toBe(false)
+    expect(command.popupFor(mint('s1').ctx)).not.toBe(popup)
+  })
+})
+
+describe('directory invalidation events', () => {
+  it('commands/changed repulls in the background while the old snapshot serves', async () => {
+    let round = 0
+    const { ctx, source, warm } = await bench({
+      commands: () => {
+        round += 1
+        return Promise.resolve({
+          commands: round === 1
+            ? S1_CMDS
+            : [{ name: 'fresh', description: '', input: { hint: 'h' } }],
+        })
+      },
+    })
+    await warm(proj('s1'))
+    ctx.emit('commands/changed')
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(source.matchSpace!(proj('s1'), '/fresh')).not.toBeUndefined()
+    expect(source.matchSpace!(proj('s1'), '/goal')).toBeUndefined()
+  })
+
+  it('connection/reset hard-drops every session key until its rewarm lands', async () => {
+    let block = false
+    let release!: (value: { commands: CommandDescriptor[] }) => void
+    const { ctx, source, warm } = await bench({
+      commands: () => (block
+        ? new Promise((resolve) => { release = resolve })
+        : Promise.resolve({ commands: S2_CMDS })),
+    })
+    await warm(proj('s2'))
+    expect(source.matchSpace!(proj('s2'), '/attach')).not.toBeUndefined()
+    block = true
+    ctx.emit('connection/reset')
+    // Hard reset: silent until the rewarm lands.
+    expect(source.matchSpace!(proj('s2'), '/attach')).toBeUndefined()
+    release({ commands: S2_CMDS })
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(source.matchSpace!(proj('s2'), '/attach')).not.toBeUndefined()
+  })
+})

packages/client/ui-command/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../connection"
+    },
+    {
+      "path": "../runtime"
+    },
+    {
+      "path": "../ui-conversation"
+    },
+    {
+      "path": "../ui-primitives"
+    },
+    {
+      "path": "../ui-slash"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/client/ui-command/tsdown.config.ts

@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-ui-command', ['lib/types/index.js', 'lib/types/invariant.js'])

packages/client/ui-conversation/README.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write
-README.md: f5e2603e8ad588740bea3be4f1a195d658721f0c
-README.zh.md: 900d3d1608da3c86078dc56ec819b1f851e63de7
+#   pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md
+README.md: 453922dafd1eb7a617cb2d1c93ac1daa2e7273c6
+README.zh.md: 88992176165ab11050a30c7df381479796908ba2

packages/client/ui-conversation/README.md

@@ -2,16 +2,18 @@
 
 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).
+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 and the todo row), input dock (queue rows plus the todo plan strip), 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.
+Generic tool rows classify the built-in bash, read, search, write, edit, and run_code 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. The code variant summarizes with the model-authored `description` and expands to the program itself; its logged sub-dispatches render as always-visible nested rows through the SAME keyed toolview hole (custom registrations and the GenericToolCard fallback apply to sub-rows unchanged), and the details panel resolves a selected sub-call id to its full logged args and complete output.
 
 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).
 
+The todo surfaces are two registrations over that shape, both plain registrant plugins with `inject: ['slots', 'conversation']`. `TodoRow` takes the `'conversation.chat.toolview'` key `todo_write` and summarizes what the call attempted (`<done>/<total> 已完成 · <active item>` parsed from its args, falling back to the generic summary on malformed or wrongly-shaped model JSON, and keeping the generic dot for non-ok execution states so a cancelled call never reads as a completed update). `TodoDock` takes the `'conversation.input.dock'` list slot at `order: -1` — above the queue rows — and is the durable plan strip: it selects `todos` off the session snapshot and renders `TodoPanel`, which takes the plain list, hides itself while the list is empty, and collapses to a header of title plus `"<done>/<total> tasks · <n> in progress"` (status glyphs are the figma check / progress / dashed-pending set). The dock adapter owns the selection so the panel stays a pure function of its props; the persistent list lives here rather than in the row so the row stays one line. Anything the input-zone composer chain hides (a `conversation.composer` takeover such as ui-question's) hides the whole dock, this strip included.
+
 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).
@@ -31,3 +33,4 @@ None; this package neither assembles nor sends a provider request.
 - **Assistant footer extensions (IconActions row, per-message paging) are reserved slots** — drawn in the design, not implemented.
 - **The sparkle icon for the others tool row is a hand-drawn approximation** — the design glyph's vector geometry is not exportable locally; promotion into ui-primitives waits on an exact export.
 - **Approval cards are display-only placeholders** — question requests answer through the composer chain (ui-question), while web-side approval answering is the P-II approvals project.
+- **TodoPanel truncates long item text to one ellipsized line** — the figma strip has no wrap or expand affordance; full text is not readable inline.

packages/client/ui-conversation/README.zh.md

@@ -2,16 +2,18 @@
 
 [English](README.md) | 中文
 
-会话领域：骨架（标题栏／标签页／编辑器／空状态）、聊天视图（分组步骤摘要流、流式尾部隔离、统计行、逐工具行 slot 及一个 bash 示例注册方）、最小详情面板、按 scope 寻址的 ConversationService。契约：api-contracts v3 §7 加 slot 终端设计（store seat／props share）。
+会话领域：骨架（标题栏／标签页／编辑器／空状态）、聊天视图（分组步骤摘要流、流式尾部隔离、统计行、逐工具行 slot 及一个 bash 示例注册方与 todo 行）、输入区 dock（队列行加 todo 计划条）、最小详情面板、按 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>` 摘要，同时保留共享的行到详情交互。
+通用工具行把内置的 bash、read、search、write、edit 和 run_code 名称归入专用视觉变体。文件系统变体会渲染 edit 图标和 `Write · <path>` 或 `Edit · <path>` 摘要，同时保留共享的行到详情交互。code 变体以模型撰写的 `description` 作摘要，展开后显示程序本身；其已记录的子调用经由同一个键控 toolview 空位渲染为始终可见的嵌套行（自定义注册和 GenericToolCard fallback 原样适用于子行），details 面板则会根据选中的子调用 id 解析出其完整记录的参数与完整输出。
 
 工具行同样是 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 会拒绝没有任何渲染方的声明）。
 
+todo 两个面就是在该形状上的两个注册项，都是普通注册方插件，`inject: ['slots', 'conversation']`。`TodoRow` 占用 `'conversation.chat.toolview'` 的 `todo_write` key，摘要该次调用「试图写入」的内容（从其 args 解析出 `<已完成>/<总数> 已完成 · <进行中条目>`；模型 JSON 残缺或形状不对时回落到通用摘要；非 ok 执行状态保留通用状态点，使被取消的调用绝不读成一次已完成的更新）。`TodoDock` 以 `order: -1` 占用 `'conversation.input.dock'` 列表 slot（位于队列行之上），是常驻的计划条：它从会话快照中选取 `todos` 并渲染 `TodoPanel`，后者接收纯列表，在列表为空时自我隐藏，折叠时收成标题加 `"<已完成>/<总数> tasks · <n> in progress"` 的表头（状态图标为 figma 的勾选／进行中／虚线未开始一组）。选取由 dock 适配器负责，因此面板保持为其 props 的纯函数；常驻列表放在此处而非行内，行才能保持单行。输入区 composer 链隐藏的一切（例如 ui-question 对 `conversation.composer` 的接管）也会隐藏整个 dock，包括这条计划条。
+
 逐 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/*` 子路径获取它们）。
@@ -31,3 +33,4 @@
 - **assistant footer 扩展（IconActions 行、逐消息分页）是预留 slot**：设计中已有图稿，尚未实现。
 - **others 工具行的闪光图标是手绘近似版本**：无法在本地导出设计字形的矢量几何；等到存在精确导出后再将其提升到 ui-primitives。
 - **审批卡片只是只读占位符**：问题请求通过编辑器链回答（ui-question），Web 侧审批回答属于 P-II 审批项目。
+- **TodoPanel 将过长条目截成单行省略号**：figma 条没有换行或展开入口，完整文本无法在行内读完。

packages/client/ui-conversation/package.json

@@ -41,6 +41,7 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-client-runtime": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-slash": "^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",
@@ -50,6 +51,7 @@
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
     "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slash": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@types/react": "~18.3.1",

packages/client/ui-conversation/src/client/apply.ts

@@ -5,15 +5,20 @@ import type { SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 import type { ViewTab } from './contract/views.ts'
 import type {
-  ChatViewInjected, ConversationInjected, DetailsInjected, EmptyStateInjected,
+  ChatViewInjected, ComposerBarInjected, ConversationInjected, ConversationSessionInjected, DetailsInjected,
 } from './contract/slots.ts'
 import { createChatStore } from './stores.ts'
 import { ConversationService } from './service.ts'
+import { InputHub } from './input/hub.ts'
+import { InputBar } from './skeleton/InputBar.tsx'
 import { ChatView } from './chat/ChatView.tsx'
 import { bashToolviewSample } from './toolviews/bash-sample.tsx'
+import { todoToolview } from './toolviews/todo-row.tsx'
+import { todoDockEntry } from './skeleton/TodoPanel.tsx'
+import { queueDockEntry } from './queue/QueueDock.tsx'
 import { ConversationRoot } from './skeleton/ConversationRoot.tsx'
+import { ConversationSession } from './skeleton/ConversationSession.tsx'
 import { DetailsPanel } from './skeleton/DetailsPanel.tsx'
-import { EmptyState } from './skeleton/EmptyState.tsx'
 
 /** Services required by the conversation plugin. */
 export const inject = ['slots', 'layout', 'sessions', 'workspaces']
@@ -49,50 +54,100 @@ export function apply(ctx: Context): void {
     return tabs
   }
 
-  // Conversation occupant. Declaring the view ring here is claiming it:
-  // ConversationRoot is the only component authorized to render the ring.
+  // The per-session input machine registry (InputService face; published as
+  // ctx.conversation.input by the service below sharing this one instance).
+  const inputHub = new InputHub(ctx)
+
+  // Decision 19/20: the input machine feeds every session-scope slot
+  // component through the standard provide channel — the 'input' hook plus
+  // the two public actions. Materialization is the shell creation trigger
+  // (per-session lazy; scope disposer tears down).
+  ctx.effect(() => sessions.provide({
+    hooks: ['input'],
+    props: ['inputActions'],
+    resolve: (binding) => {
+      const shell = inputHub.shellFor(binding)
+      return {
+        hooks: { input: shell.state },
+        props: { inputActions: shell.actions },
+      }
+    },
+  }), 'ui-conversation: input standard-kit provider')
+
+  // Resident current-session-optional shell. It owns the stable Hero/composer
+  // frame while strict session slots fill only their session-bound regions.
   slots.register({
     name: 'conversation',
-    // The composer chain rides the same declaration table: takeover plugins
-    // register selector-routed replacements of the InputBar.
     children: {
-      'conversation.view': { kind: 'list', scope: 'session' },
+      'conversation.session': { kind: 'single', scope: 'session' },
       'conversation.composer': { kind: 'chain', scope: 'session' },
+      'conversation.composer.bar': { kind: 'single', scope: 'session' },
+      'conversation.input.overlay': { kind: 'list', scope: 'session' },
+      'conversation.input.dock': { kind: 'list', scope: 'session' },
+      'conversation.composer.dock': { kind: 'list', scope: 'session' },
+      'conversation.input.left': { kind: 'list', scope: 'session' },
+      'conversation.input.right': { kind: 'list', scope: 'session' },
+      'conversation.hero.workspace': { kind: 'single', scope: 'root' },
     },
+    inject: (sessionId: SessionId | undefined): ConversationInjected => ({
+      selectWorkspace: (workspaceId) => {
+        void workspaces.connectWorkspace(workspaceId).then((nextId) => {
+          if (sessionId !== undefined && nextId !== sessionId) {
+            const from = inputHub.shell(sessionId)
+            const draft = from.snapshot.draft
+            if (draft !== '') {
+              inputHub.shell(nextId).setDraft(draft)
+              from.setDraft('')
+            }
+          }
+          sessions.open(nextId)
+        }).catch(() => {
+          // Failure leaves the current Hero state available to retry.
+        })
+      },
+    }),
+  }, ConversationRoot)
+
+  // The strict session subtree owns only per-session store and view content;
+  // the resident parent keeps Hero and composer layout identity stable.
+  slots.register({
+    name: 'conversation.session',
+    children: { 'conversation.view': { kind: 'list', scope: 'session' } },
     store: chatStore,
-    inject: (sessionId: SessionId, actions: BoundActions<typeof chatStore>): ConversationInjected => {
-      // History pull is NOT triggered here: the runtime sessions service opens
-      // the event window when the watch lands on the session (cell/binding
-      // resolution) — an inject factory assembles callbacks, it has no side
-      // effect on session state.
-      const scoped = scopedConversation(sessions, sessionId)
+    inject: (sessionId: SessionId, _actions: BoundActions<typeof chatStore>): ConversationSessionInjected => ({
+      views: {
+        list: viewTabs,
+        subscribe: fn => slots.subscribe('conversation.view', fn),
+        version: () => slots.getVersion('conversation.view'),
+      },
+      bindDraftMirror: write => inputHub.shell(sessionId).bindMirror(write),
+      open: (id) => { sessions.open(id) },
+    }),
+  }, ConversationSession)
+
+  // The default composer body: its own single slot inside the composer
+  // chain's fallback (decision 20). Public machine surface arrives via the
+  // provide channel above; the keyboard command face and the stop/retry
+  // verbs ride this inject (package-internal — hub and bar are one plugin).
+  slots.register({
+    name: 'conversation.composer.bar',
+    // The two named control seats in the bar's tool row (plan left, model
+    // right); empty until their owning plugins register (B ruling).
+    children: {
+      'conversation.input.plan': { kind: 'single', scope: 'session' },
+      'conversation.input.model': { kind: 'single', scope: 'session' },
+    },
+    inject: (sessionId: SessionId): ComposerBarInjected => {
       return {
-        views: {
-          list: viewTabs,
-          subscribe: fn => slots.subscribe('conversation.view', fn),
-          version: () => slots.getVersion('conversation.view'),
-        },
-        send: (text, mode) => {
-          const trimmed = text.trim()
-          if (trimmed === '') return
-          // Optimistic clear with failure restore (choreography lives with the
-          // sender; the business failure also lands in snapshot.promptError).
-          // The store write path stays inside the declared actions set:
-          // restoreDraft itself no-ops once the user typed something new.
-          actions.clearDraft()
-          void scoped.send(trimmed, mode).catch(() => { actions.restoreDraft(trimmed) })
-        },
+        keyboard: inputHub.keyboard(sessionId),
         stop: () => {
-          scoped.cancel().catch(() => {
+          scopedConversation(sessions, sessionId).cancel().catch(() => {
             // Stop failure surfaces via snapshot.promptError; nothing to restore.
           })
         },
-        open: (sessionId) => { sessions.open(sessionId) },
-        updateSessionPrompt: (text) => { scoped.updatePendingPrompt(text) },
-        retrySessionPrompt: () => { scoped.retryPendingPrompt() },
       }
     },
-  }, ConversationRoot)
+  }, InputBar)
 
   // The chat view: first entry of the ring this package just declared.
   // Declaring the keyed toolview hole here is claiming it: ChatView is the
@@ -124,11 +179,22 @@ export function apply(ctx: Context): void {
   // toolview registrants using `inject: ['conversation']` as their load-order
   // seam: the service being present implies the chat entry (and with it the
   // 'conversation.chat.toolview' declaration) is on the ledger.
-  ctx.plugin(ConversationService)
+  ctx.plugin(ConversationService, { input: inputHub })
 
-  // The bash sample rides that exact seam, in third-party posture.
+  // The bash sample rides that exact seam, in third-party posture
+  // (ToolRow-matching Bash · {description} chrome; scoped badge in child sessions).
   ctx.plugin(bashToolviewSample)
 
+  // The todo_write row rides the same seam (a product registration, not a sample).
+  ctx.plugin(todoToolview)
+
+  // The plan strip rides the input dock above the queue rows (same posture).
+  ctx.plugin(todoDockEntry)
+
+  // The read-only queue dock entry (T9 file territory) rides the same
+  // registration seam into the input dock declared above.
+  ctx.plugin(queueDockEntry)
+
   slots.register({
     name: 'details',
     store: chatStore,
@@ -137,13 +203,4 @@ export function apply(ctx: Context): void {
     }),
   }, DetailsPanel)
 
-  slots.register({
-    name: 'conversation.empty',
-    children: { 'conversation.empty.workspace': { kind: 'single', scope: 'root' } },
-    inject: (): EmptyStateInjected => ({
-      startSession: (workspaceId, prompt) => { workspaces.startSession(workspaceId, prompt) },
-      updateSessionPrompt: (text) => { sessions.updateIntent(text) },
-      sendSession: () => { workspaces.sendSession() },
-    }),
-  }, EmptyState)
 }

packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx

@@ -44,7 +44,7 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({ blocks, strea
     <div className={css.root} data-streaming={streaming || undefined}>
       {blocks.map((block, i) => {
         switch (block.kind) {
-          case 'text': return <MarkdownText key={i} text={block.text} />
+          case 'text': return <MarkdownText key={i} text={block.text} streaming={streaming} />
           case 'reasoning': return <ThinkRow key={i} text={block.text} running={streaming && i === last} />
           // Tool-call heads render as tool rows in the chat view's grouping pass.
           case 'tool-call': return null

packages/client/ui-conversation/src/client/chat/ChatView.module.css

@@ -37,12 +37,18 @@
   border-radius: 6px;
 }
 
-/* Selection linkage: the selected call row wears the blue outline.
-   button-info-fill flips 500→400 with the theme, hitting the darker-blue
-   dark-mode spec exactly (business-primary stays 500 on both). */
-.callRow[data-selected] {
-  outline: 1.5px solid var(--dsw-alias-button-info-fill);
-  outline-offset: 1px;
+/* Selection still sets data-selected for details linkage; no outline —
+   tool rows match Think chrome (no selected ring). */
+
+/* run_code sub-dispatch rows: indented under the parent row, left-edged so
+   the code turn reads as one unit; each nested row is itself a .callRow. */
+.subCalls {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  margin: 4px 0 2px 22px;
+  padding-left: 8px;
+  border-left: 1px solid var(--dsw-alias-border-l2);
 }
 
 .hint {

packages/client/ui-conversation/src/client/chat/ChatView.tsx

@@ -20,7 +20,7 @@ import {
   memo, useLayoutEffect, useMemo, useRef, useState, type ReactNode,
 } from 'react'
 import type {
-  ConversationNode, ConversationSnapshot, RunningToolCall, ToolResultNode,
+  CodeSubCall, ConversationNode, ConversationSnapshot, RunningToolCall, ToolResultNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
@@ -45,10 +45,39 @@ type RenderToolRow = ChatViewSlotProps['renderSlot']
  *  chat view narrows once to the runtime snapshot the binding actually feeds. */
 type UseConversation = SnapshotSelectorHook<ConversationSnapshot>
 
+/** One `run_code` sub-dispatch row: the identical keyed-slot dispatch as a
+ *  top-level call (same registrations, same fallback), nested by the parent.
+ *  A started-but-unsettled sub-call arrives as the RunningToolCall shape and
+ *  renders the running state exactly as a native in-flight row. */
+const SubCallRow = memo(function SubCallRow({ renderSlot, node, onOpenDetails, selected }: {
+  renderSlot: RenderToolRow
+  node: CodeSubCall
+  onOpenDetails: OpenDetails
+  selected: boolean
+}) {
+  const settled = 'kind' in node
+  const toolName = settled ? node.call?.name ?? '' : node.name
+  const seq = settled ? node.seq : node.time
+  const owner = useMemo(() => ({
+    callId: node.callId, toolName, block: node,
+    openDetails: () => { onOpenDetails({ turnSeq: seq, callId: node.callId, toolName }) },
+  }), [node, toolName, seq, onOpenDetails])
+  return (
+    <div className={css.callRow} data-selected={selected || undefined}>
+      {renderSlot('conversation.chat.toolview', owner, {
+        entryKey: toolName,
+        fallback: <GenericToolCard {...owner} />,
+      })}
+    </div>
+  )
+})
+
 /** One tool call row (result or running): dispatches through the keyed
  *  toolview slot with the owner payload; unregistered tools fall back to
- *  GenericToolCard at this render site. */
-const CallRow = memo(function CallRow({ renderSlot, callId, toolName, block, seq, onOpenDetails, selected }: {
+ *  GenericToolCard at this render site. A `run_code` call additionally
+ *  renders its logged sub-dispatches as always-visible indented rows —
+ *  each one the same keyed-slot dispatch as a native top-level call. */
+const CallRow = memo(function CallRow({ renderSlot, callId, toolName, block, seq, onOpenDetails, selected, subCalls, selectedCallId }: {
   renderSlot: RenderToolRow
   callId: string
   toolName: string
@@ -57,6 +86,10 @@ const CallRow = memo(function CallRow({ renderSlot, callId, toolName, block, seq
   seq: number
   onOpenDetails: OpenDetails
   selected: boolean
+  /** `run_code` sub-dispatches in dispatch order (reference-stable per parent; running entries settle in place); undefined for ordinary calls. */
+  subCalls?: readonly CodeSubCall[] | undefined
+  /** The store's selected callId, matched against sub-rows (undefined when no sub-row here is selected). */
+  selectedCallId?: string | undefined
 }) {
   const owner = useMemo(() => ({
     callId, toolName, block,
@@ -68,17 +101,32 @@ const CallRow = memo(function CallRow({ renderSlot, callId, toolName, block, seq
         entryKey: toolName,
         fallback: <GenericToolCard {...owner} />,
       })}
+      {subCalls !== undefined && subCalls.length > 0 && (
+        <div className={css.subCalls} data-subcalls>
+          {subCalls.map((node) => (
+            <SubCallRow
+              key={node.callId}
+              renderSlot={renderSlot}
+              node={node}
+              onOpenDetails={onOpenDetails}
+              selected={node.callId === selectedCallId}
+            />
+          ))}
+        </div>
+      )}
     </div>
   )
 })
 
 /** Consecutive tool results as one step-run group (figma VERTICAL gap10). */
-const ToolGroup = memo(function ToolGroup({ renderSlot, results, onOpenDetails, selectedCallId }: {
+const ToolGroup = memo(function ToolGroup({ renderSlot, results, onOpenDetails, selectedCallId, codeDispatches }: {
   renderSlot: RenderToolRow
   results: readonly ToolResultNode[]
   onOpenDetails: OpenDetails
-  /** Only set when the selected call lives in THIS group (memo economy). */
+  /** Only set when the selected call lives in THIS group, top-level or nested (memo economy). */
   selectedCallId: string | undefined
+  /** Sub-dispatch index off the snapshot (map reference is chunk-storm stable). */
+  codeDispatches: ReadonlyMap<string, readonly CodeSubCall[]>
 }) {
   return (
     <div className={css.toolGroup}>
@@ -92,6 +140,8 @@ const ToolGroup = memo(function ToolGroup({ renderSlot, results, onOpenDetails,
           seq={node.seq}
           onOpenDetails={onOpenDetails}
           selected={node.callId === selectedCallId}
+          subCalls={codeDispatches.get(node.callId)}
+          selectedCallId={selectedCallId}
         />
       ))}
     </div>
@@ -116,6 +166,7 @@ function StreamingTail({ useSession, onGrow }: {
 export function ChatView({ useSession, useStore, renderSlot, openDetails, loadOlder }: ChatViewSlotProps) {
   const nodes = useSession((s) => s.nodes)
   const runningCalls = useSession((s) => s.runningCalls)
+  const codeDispatches = useSession((s) => s.codeDispatches)
   const pending = useSession((s) => s.pending)
   const openState = useSession((s) => s.openState)
   const openErrorMessage = useSession((s) => s.openError === null ? null : `${s.openError.message}（${s.openError.code}）`)
@@ -203,7 +254,8 @@ export function ChatView({ useSession, useStore, renderSlot, openDetails, loadOl
   const renderItem = (item: ChatFlowItem): ReactNode => {
     if (item.kind === 'tool-group') {
       const inGroup = selectedCallId !== undefined
-        && item.results.some((r) => r.callId === selectedCallId)
+        && item.results.some((r) => r.callId === selectedCallId
+          || codeDispatches.get(r.callId)?.some((sub) => sub.callId === selectedCallId) === true)
       return (
         <ToolGroup
           key={item.key}
@@ -211,6 +263,7 @@ export function ChatView({ useSession, useStore, renderSlot, openDetails, loadOl
           results={item.results}
           onOpenDetails={openDetails}
           selectedCallId={inGroup ? selectedCallId : undefined}
+          codeDispatches={codeDispatches}
         />
       )
     }
@@ -250,6 +303,8 @@ export function ChatView({ useSession, useStore, renderSlot, openDetails, loadOl
                 seq={call.turn}
                 onOpenDetails={openDetails}
                 selected={call.callId === selectedCallId}
+                subCalls={codeDispatches.get(call.callId)}
+                selectedCallId={selectedCallId}
               />
             ))}
           </div>

packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx

@@ -6,7 +6,7 @@
 
 import type { ReactNode } from 'react'
 import {
-  IconApiOutline14, IconBrowseOutline16, IconEditOutline16, IconSearchOutline16, IconThinkOutline14,
+  IconApiOutline14, IconBrowseOutline16, IconCodeOutline16, IconEditOutline16, IconSearchOutline16, IconThinkOutline14,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ToolRowOwnerProps } from '../contract/slots.ts'
 import { toolRowModel, type ToolRowVariant } from '../contract/tool-call-model.ts'
@@ -21,6 +21,7 @@ const VARIANT_ICONS: Record<ToolRowVariant, ReactNode> = {
   bash: <IconApiOutline14 size={16} />,
   write: <IconEditOutline16 />,
   edit: <IconEditOutline16 />,
+  code: <IconCodeOutline16 />,
   others: <IconSparkle16 />,
 }
 

packages/client/ui-conversation/src/client/chat/MessageItem.module.css

@@ -1,10 +1,11 @@
-/* User bubble: right-aligned, figma r22 fill = the bubble specific token
-   (#EDF3FE light / dark pair rides the token sheet). */
+/* User bubble: right-aligned column (bubble + IconActions). Figma
+   User_Bubble/message_container 659:38813 — r22 fill, actions gap 6 below. */
 
-/* Block spacing is the flow column's gap alone — no extra padding here. */
 .userRow {
   display: flex;
-  justify-content: flex-end;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: 6px;
 }
 
 .bubble {
@@ -19,6 +20,46 @@
   color: var(--dsw-alias-label-primary);
 }
 
+.actions {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  height: 28px;
+}
+
+/* Hover-capable pointers: hide until the row is hovered/focused. Touch /
+   hover:none keeps actions visible (opacity:0 still hit-tests). */
+@media (hover: hover) {
+  .actions {
+    opacity: 0;
+    transition: opacity var(--ds-transition-duration) var(--ds-ease-in-out);
+  }
+
+  .userRow:hover .actions,
+  .userRow:focus-within .actions {
+    opacity: 1;
+  }
+}
+
+.action {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  padding: 6px;
+  border: none;
+  border-radius: 28px;
+  background: transparent;
+  color: var(--dsw-alias-label-tertiary);
+  cursor: pointer;
+}
+
+.action:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+  color: var(--dsw-alias-label-secondary);
+}
+
 .badge {
   display: inline-block;
   margin-bottom: 4px;
@@ -32,3 +73,18 @@
 .contextRow {
   padding: 2px 0;
 }
+
+/* Reference chip projection inside a user bubble (`<skill>name</skill>` model
+   spans render as chips; free geometry — no textarea pairing here). */
+.refChip {
+  display: inline-block;
+  margin: 0 2px;
+  padding: 0 8px;
+  border-radius: 6px;
+  background: rgba(97, 135, 216, 0.22);
+  color: var(--dsw-alias-label-primary);
+  font-size: 0.85em;
+  line-height: 1.6;
+  white-space: nowrap;
+  vertical-align: baseline;
+}

packages/client/ui-conversation/src/client/chat/MessageItem.tsx

@@ -1,13 +1,18 @@
-// MessageItem: the four simple node kinds — user bubble (right-aligned),
-// steering (badged bubble), context injection and unknown-surface JSON rows.
-// Props are frozen node slices off the snapshot cache; memo holds across
-// streaming because unchanged nodes keep their references.
+// MessageItem: the four simple node kinds — user bubble (right-aligned, with
+// copy / branch / edit IconActions), steering (badged bubble), context
+// injection and unknown-surface JSON rows. Props are frozen node slices off
+// the snapshot cache; memo holds across streaming because unchanged nodes
+// keep their references.
 
-import { memo } from 'react'
+import { memo, useCallback } from 'react'
+import type { ReactNode } from 'react'
 import type {
   ContextMessageNode, SteeringMessageNode, UnknownSurfaceNode, UserMessageNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
-import { JsonBlock, MessageText } from '@deepseek-ai/dsh-client-ui-primitives'
+import {
+  IconBranchOutline16, IconCopyOutline16, IconEditOutline16,
+  JsonBlock, MessageText, Tooltip,
+} from '@deepseek-ai/dsh-client-ui-primitives'
 import css from './MessageItem.module.css'
 
 export interface MessageItemProps {
@@ -25,16 +30,114 @@ function contentText(content: readonly unknown[]): { text: string; rest: unknown
   return { text: texts.join(''), rest }
 }
 
+/** Best-effort clipboard write; rejections stay swallowed (no success chrome). */
+async function writeClipboard(text: string): Promise<void> {
+  if (navigator.clipboard?.writeText) {
+    try {
+      await navigator.clipboard.writeText(text)
+    } catch {
+      // Denied permissions / iframe policy.
+    }
+    return
+  }
+  const exec = typeof document.execCommand === 'function'
+    ? document.execCommand.bind(document)
+    : undefined
+  if (exec === undefined) return
+  const el = document.createElement('textarea')
+  el.value = text
+  el.setAttribute('readonly', '')
+  el.style.position = 'fixed'
+  el.style.left = '-9999px'
+  document.body.appendChild(el)
+  el.select()
+  try {
+    exec('copy')
+  } catch {
+    // Clipboard unavailable; the button stays idle.
+  }
+  el.remove()
+}
+
+/**
+ * Display projection of reference forms in a user bubble (free geometry — no
+ * textarea alignment constraint here); everything else stays plain text. The
+ * logged model text remains the single truth; this is presentation only. Two
+ * shapes decorate: legacy `<skill>name</skill>` spans (pre-decision-21
+ * history) and plain-text `/name` / `@name` word-boundary tokens (decision
+ * 21: the sent text IS the reference — the bubble uses the same plainest
+ * token scan as the composer, minus the lexicon: sent tokens were validated
+ * at compose time, so shape alone decorates).
+ */
+function projectUserText(text: string): ReactNode {
+  const re = /<skill>([^<]+)<\/skill>|(^|\s)([/@][\w-]+)(?=\s|$)/g
+  const parts: ReactNode[] = []
+  let cursor = 0
+  let m: RegExpExecArray | null
+  while ((m = re.exec(text)) !== null) {
+    const legacy = m[1] !== undefined
+    const tokenStart = legacy ? m.index : m.index + (m[2]?.length ?? 0)
+    const label = legacy ? `/${m[1]}` : m[3] ?? ''
+    if (tokenStart > cursor) parts.push(<MessageText key={cursor} text={text.slice(cursor, tokenStart)} />)
+    parts.push(
+      <span key={tokenStart} className={css.refChip} data-ref-chip={label.startsWith('@') ? 'subagent' : 'skill'}>
+        {label}
+      </span>,
+    )
+    cursor = legacy ? m.index + m[0].length : tokenStart + label.length
+  }
+  if (parts.length === 0) return <MessageText text={text} />
+  if (cursor < text.length) parts.push(<MessageText key={cursor} text={text.slice(cursor)} />)
+  return <>{parts}</>
+}
+
+/** User-bubble IconActions (figma 659:38820): copy is live; branch/edit are chrome stubs. */
+function UserActions({ text }: { text: string }) {
+  const onCopy = useCallback(() => {
+    void writeClipboard(text)
+  }, [text])
+  return (
+    <div className={css.actions}>
+      <Tooltip label="复制" side="bottom">
+        <button type="button" className={css.action} aria-label="复制" onClick={onCopy}>
+          <IconCopyOutline16 />
+        </button>
+      </Tooltip>
+      <Tooltip label="在新对话中分支" side="bottom">
+        <button type="button" className={css.action} aria-label="在新对话中分支">
+          <IconBranchOutline16 />
+        </button>
+      </Tooltip>
+      <Tooltip label="编辑" side="bottom">
+        <button type="button" className={css.action} aria-label="编辑">
+          <IconEditOutline16 />
+        </button>
+      </Tooltip>
+    </div>
+  )
+}
+
 export const MessageItem = memo(function MessageItem({ node }: MessageItemProps) {
   switch (node.kind) {
-    case 'user':
+    case 'user': {
+      const { text, rest } = contentText(node.content)
+      return (
+        <div className={css.userRow}>
+          <div className={css.bubble}>
+            {projectUserText(text)}
+            {rest.map((block, i) => <JsonBlock key={i} label="附加内容块" payload={block} />)}
+          </div>
+          <UserActions text={text} />
+        </div>
+      )
+    }
     case 'steering': {
       const { text, rest } = contentText(node.content)
       return (
         <div className={css.userRow}>
           <div className={css.bubble}>
-            {node.kind === 'steering' && <span className={css.badge}>插话</span>}
-            <MessageText text={text} />
+            <span className={css.badge}>插话</span>
+            {projectUserText(text)}
             {rest.map((block, i) => <JsonBlock key={i} label="附加内容块" payload={block} />)}
           </div>
         </div>

packages/client/ui-conversation/src/client/chat/ToolRow.module.css

@@ -86,3 +86,10 @@ button.leading {
   word-break: break-word;
   color: var(--dsw-alias-label-tertiary);
 }
+
+/* The code variant's expanded body is the run_code program, rendered through
+   the shared CodeBlock (shiki-highlighted TypeScript); only indentation is
+   this row's concern. */
+.codeBody {
+  margin: 4px 0 4px 22px;
+}