Merge latest master into subagent policy inheritance

.agents/notes/implemented/architecture/2026-06-14-session-persistence.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
-2026-06-14-session-persistence.md: 75e13b860f621ed407849b3b4c62ff7287ab4812
-2026-06-14-session-persistence.zh.md: a6bd400a053779c742940236737447d1687622de
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-14-session-persistence.md
+2026-06-14-session-persistence.md: 137b2b01126214629952812f3dd3b71985a3acda
+2026-06-14-session-persistence.zh.md: 2846ee92349c297fb3a173ba9dd3e2ff3cd9ee1a

.agents/notes/implemented/architecture/2026-06-14-session-persistence.md

@@ -29,7 +29,7 @@ Key choices recorded here because they are durable, contested, and surprising:
 
 Each key choice above records its rejected alternative where the choice is stated: a **chunk-filtered canonical log** (Codex's `policy.rs` shape) — breaks the contiguous-seq contract; **truncating a crashed turn** — silently destroys a long autonomous run's real work; an **in-log `session/meta` event as line 0** — metadata is not replayable state; **finite fractional `createdAt` values** — have no producer and diverge from integer Unix-millisecond storage and query columns; **adopting a non-pristine unversioned SQLite file** — can overwrite unrelated objects or identity; **hard-injecting `sessionPersistence` into the loop** — would pend non-persistent demos forever.
 
-Format versioning: the header carries a `version`; `load` rejects any non-current version (no migration — the pre-release session format is pinned at `SESSION_FORMAT_VERSION = 0` and absorbs shape churn, per the AGENTS.md pre-release stance). Stated honestly: append-only + flush is robust to partial trailing writes (tolerated on load) but not to fsync-less power loss mid-line; a DB/WAL backend is the stronger option later.
+Format versioning: the header carries a `version`; `load` rejects any non-current version. The pre-release session format stays pinned at `SESSION_FORMAT_VERSION = 0` and carries no broad compatibility promise, while the coordinator may own an explicit narrow import upgrade when persisted user data requires it ([pre-identity message recovery](../bug-fix/2026-07-28-load-pre-identity-session-messages.md)). Stated honestly: append-only + flush is robust to partial trailing writes (tolerated on load) but not to fsync-less power loss mid-line; a DB/WAL backend is the stronger option later.
 
 ## Consequences
 

.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md

@@ -29,7 +29,7 @@ Status: implemented
 
 上述每个关键选择都在陈述处记录了被否决的替代方案：**过滤分片的规范日志**（Codex 的 `policy.rs` 形式）破坏连续 seq 契约；**截断崩溃的轮次**会静默销毁长时间自主运行中的真实工作；**日志内 `session/meta` 事件作为第 0 行**——元数据不是可回放状态；**有限的非整数 `createdAt` 值**没有生产方，且与整数 Unix 毫秒存储及查询列不一致；**接受非全新的未版本化 SQLite 文件**可能覆盖无关对象或应用标识；**将 `sessionPersistence` 硬注入循环**会让非持久化的演示永远挂起。
 
-格式版本控制：header 携带一个 `version`；`load` 拒绝任何非当前版本（不做迁移——预发布阶段的会话格式固定为 `SESSION_FORMAT_VERSION = 0` 并吸收形状变动，遵循 AGENTS.md 的预发布立场）。坦率地说：仅追加 + 刷写对部分尾部写入是健壮的（加载时容忍），但对行写入中途的无 fsync 断电不健壮；数据库/WAL 后端是后续更强的选项。
+格式版本控制：header 携带一个 `version`；`load` 拒绝任何非当前版本。预发布阶段的会话格式仍固定为 `SESSION_FORMAT_VERSION = 0`，不承诺广泛兼容；当持久化用户数据确有需要时，协调器可以负责显式且范围受限的导入升级（[消息标识机制引入前的消息恢复](../bug-fix/2026-07-28-load-pre-identity-session-messages.md)）。坦率地说：仅追加 + 刷写对部分尾部写入是健壮的（加载时容忍），但对行写入中途的无 fsync 断电不健壮；数据库/WAL 后端是后续更强的选项。
 
 ## 后果
 

.agents/notes/implemented/architecture/2026-07-28-dsh-native-typescript-source-launch.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-dsh-native-typescript-source-launch.md
+2026-07-28-dsh-native-typescript-source-launch.md: 019389f3e5e9229f4359bbd58c95dbb2f14eb24b
+2026-07-28-dsh-native-typescript-source-launch.zh.md: 2cfff25d228e67ac85a9bc9087fa09ddb64213a0

.agents/notes/implemented/architecture/2026-07-28-dsh-native-typescript-source-launch.md

@@ -0,0 +1,45 @@
+# Agent Note: Native TypeScript source launch for dsh
+
+Status: implemented
+
+English | [中文](2026-07-28-dsh-native-typescript-source-launch.zh.md)
+
+## Problem
+
+The `dsh` source entry point originally used `tsx` to run `apps/cli/src/bin.ts`, with the same third-party loader implicitly handling both TypeScript transformation and the root tsconfig's `paths` resolution. With Node handling TypeScript natively, it does not apply tsconfig path mappings; resolving through package exports would instead mix potentially stale or nonexistent `lib/` artifacts into the source launch.
+
+Node's transform also does not perform type analysis. A type imported through an ordinary value import remains a runtime ESM request, and TypeScript's `export =` becomes a CommonJS assignment rather than an ESM default export. The source graph therefore has to use explicit type-only imports and native ESM exports; a resolve hook cannot repair incompatible source syntax.
+
+Cordis configuration introduces a separate resolution boundary. Bare plugins in `cordis.yml` do not pass through TypeScript import analysis, so their resolver manifest may omit the required dependencies. The Cordis Loader logs plugin import errors and leaves an entry without a fiber, but does not fail startup itself; a typo in the configuration can therefore produce an incomplete application with exit code 0.
+
+## Decision
+
+The `dsh` TUI, Web, and headless source launches use `node --experimental-transform-types`; Node performs TypeScript transformation without loading `tsx` or esbuild. `bin/dsh`, the root-level `dsh`/TUI/Web demos, and Code Mode TUI enter the same `apps/cli/src/bin.ts` launch chain. Test and E2E launchers retain their existing strategies, and the built `lib/bin.js` continues to run under ordinary Node.
+
+`scripts/tspath-loader.ts` registers only a module resolve hook. It uses `TSX_TSCONFIG_PATH` when set (resolving relative values from the invoking cwd) and otherwise reads the root `tsconfig.json`; `TsconfigPathsResolver` follows that config's `extends` chain through the repository's existing TypeScript development tool, selects exact or wildcard `paths` entries according to tsconfig rules, and maps matching workspace bare specifiers to `.ts`/`.mts`/`.cts` source files or directory index files. Node remains solely responsible for code transformation. The source-only loader is not part of the built CLI and `apps/cli` does not declare `typescript` as a runtime dependency.
+
+Source imports are redirected only when the target package is either the nearest package manifest's own name or one of that manifest's declared runtime dependencies. The Cordis Loader uses the configuration directory URL as the import parent; the resolver then searches upward for the workspace manifest that declares the plugin, so dependency ownership for `examples/tui-agent/cordis.yml` lies with `examples/package.json`, and dependency ownership for `apps/cli/cordis.yml` lies with `apps/cli/package.json`. Specifiers that do not match tsconfig paths, refer to undeclared dependencies, or are not bare all fall back to Node's default resolution.
+
+`verify-cordis-config` performs a one-way completeness check on both resolver manifests: every bare plugin package in a configuration must appear in the corresponding manifest's `dependencies`, while the manifest may contain extra dependencies not referenced by that configuration. The root `AGENTS.md` makes updating the configuration and dependencies together a standing rule.
+
+After the Loader settles, the shared `dsh-app-boot` checks every enabled entry that has no fiber and rejects startup with `plugin(s) failed to load: ...; Cordis startup failed because these plugin(s) could not be resolved`, listing all failed plugins. This diagnostic lives at the app layer and does not change the vendored Loader's startup behavior.
+
+Node-compatible TypeScript is part of this source-launch contract. Vendored Cordis, Loader, Include, HMR, and Schemastery mark erased imports with `import type`. Schemastery uses a native ESM default export and declares `type: module`; its `.mjs` and `.cjs` build outputs retain the existing ESM-default and callable-`require()` behavior. These divergences are recorded in `vendor/README.md`; no runtime behavior is added to the vendored frameworks.
+
+## Alternatives considered
+
+**Continue using `tsx`.** Rejected because `tsx`/esbuild would continue to own TypeScript transformation, so this launch chain could not prove that Node's native transformation works.
+
+**Load the built `lib/` through package exports from the source entry point.** Rejected because this would mix the source plane with the artifact plane; a zero-build development launch could read stale artifacts or fail outright.
+
+**Apply the root tsconfig `paths` unconditionally.** Rejected because this would allow undeclared cross-package imports and Cordis plugins to keep resolving, hiding mismatches between the manifest and the actual runtime graph.
+
+**Transform imports inside the custom loader.** Rejected because type-aware source rewriting would reintroduce a compiler-style transform and make the loader, rather than Node, responsible for TypeScript execution. Making the checked-in source Node-compatible keeps the launch boundary explicit.
+
+## Consequences
+
+- TUI/headless retain a zero-build source loop, while Web still builds its frontend artifacts before starting the CLI source entry. TypeScript syntax passes only through Node's native transform; the URL-only loader uses the checkout's root development dependencies and adds no CLI runtime dependency.
+- Workspace package imports and Cordis configuration dependencies must both be declared explicitly in the resolver manifest; the static gate prevents configuration from landing before its dependencies, while extra dependencies are not errors.
+- Plugin import failures no longer leave an incomplete application with exit code 0; the final error identifies both the Cordis startup failure and the specific plugin names, while the Loader's original error remains earlier in the logs.
+- Vendored source in the CLI graph must remain compatible with Node's transform-types module semantics; the local-modification log makes the upstream sync obligation explicit.
+- CI's `lib` mode, test/E2E launchers, and other example launchers retain their existing strategies; this native source loader covers only the `dsh` CLI application chain.

.agents/notes/implemented/architecture/2026-07-28-dsh-native-typescript-source-launch.zh.md

@@ -0,0 +1,45 @@
+# Agent Note: dsh 原生 TypeScript 源码启动
+
+Status: implemented
+
+[English](2026-07-28-dsh-native-typescript-source-launch.md) | 中文
+
+## 问题
+
+`dsh` 源码入口原本使用 `tsx` 运行 `apps/cli/src/bin.ts`，TypeScript 转换和根 tsconfig 的 `paths` 解析都由同一个第三方 loader 隐式处理。改由 Node 原生处理 TypeScript 后，Node 不会应用 tsconfig 路径映射；如果改为通过包导出解析，源码启动会混入可能陈旧或不存在的 `lib/` 产物。
+
+Node 的转换也不执行类型分析。通过普通值 import 导入的类型会保留为运行时 ESM 请求，而 TypeScript 的 `export =` 会变成 CommonJS 赋值，而不是 ESM default export。因此，源码图必须显式使用仅类型导入和原生 ESM 导出；resolve hook 无法修复不兼容的源码语法。
+
+Cordis 配置还引入了另一条解析边界。`cordis.yml` 中的 bare plugin 不经过 TypeScript import 分析，其解析方 manifest 可能漏掉所需依赖。Cordis Loader 会记录插件 import 错误，并留下没有 fiber 的 entry，但不会让启动本身失败；配置中的拼写错误因此可能得到退出码为 0 的残缺应用。
+
+## 决策
+
+`dsh` 的 TUI、Web 和无头源码启动使用 `node --experimental-transform-types`，由 Node 完成 TypeScript 转换，不加载 `tsx` 或 esbuild。`bin/dsh`、根级 `dsh`/TUI/Web demo 以及 Code Mode TUI 都进入同一条 `apps/cli/src/bin.ts` 启动链路。测试与 e2e 启动器保留各自现有策略，构建后的 `lib/bin.js` 继续由普通 Node 运行。
+
+`scripts/tspath-loader.ts` 只注册一个模块 resolve hook。设置 `TSX_TSCONFIG_PATH` 时，它会使用该路径（相对路径从调用方的 cwd 解析），否则读取根 `tsconfig.json`；`TsconfigPathsResolver` 使用仓库已有的 TypeScript 开发工具沿该配置的 `extends` 链解析，按 tsconfig 规则选择精确或 wildcard `paths` 条目，并将命中的 workspace bare specifier 映射到 `.ts`/`.mts`/`.cts` 源文件或目录 index 文件。代码转换始终只由 Node 负责。该源码专用 loader 不属于构建后的 CLI，`apps/cli` 也不会把 `typescript` 声明为运行时依赖。
+
+只有当目标包是最近 package manifest 的自身名称或其已声明的运行时依赖时，源码 import 才会重定向。Cordis Loader 使用配置目录 URL 作为 import parent；此时 resolver 会向上查找声明该插件的 workspace manifest。因此，`examples/tui-agent/cordis.yml` 的依赖由 `examples/package.json` 持有，`apps/cli/cordis.yml` 的依赖由 `apps/cli/package.json` 持有。未命中 tsconfig paths、引用未声明依赖或不是 bare specifier 的说明符全部交回 Node 默认解析。
+
+`verify-cordis-config` 对这两个解析方 manifest 执行单向完整性检查：配置中的每个 bare plugin package 都必须出现在对应 manifest 的 `dependencies` 中，manifest 可以包含该配置未引用的额外依赖。根 `AGENTS.md` 将同步更新配置和依赖定为常驻规则。
+
+Loader 完成结算后，共享的 `dsh-app-boot` 会检查每个已启用但没有 fiber 的 entry，并以 `plugin(s) failed to load: ...; Cordis startup failed because these plugin(s) could not be resolved` 拒绝启动，同时列出全部加载失败的插件。该诊断位于应用层，不改变 vendor 中 Loader 的启动行为。
+
+Node-compatible TypeScript 是这项源码启动契约的一部分。vendor 中的 Cordis、Loader、Include、HMR（热模块替换）和 Schemastery 使用 `import type` 标记会被擦除的导入。Schemastery 使用原生 ESM default export 并声明 `type: module`；其 `.mjs` 和 `.cjs` 构建产物分别保留现有的 ESM default export 行为和 `require()` 返回可调用值的行为。这些差异记录在 `vendor/README.md` 中；没有为 vendor 中的框架新增运行时行为。
+
+## 曾考虑的替代方案
+
+**继续使用 `tsx`。** 不采用，因为 `tsx`/esbuild 会继续负责 TypeScript 转换，本启动链路无法因此证明 Node 原生转换可用。
+
+**让源码入口通过包导出加载构建后的 `lib/`。** 不采用，因为这会混合 source plane 与 artifact plane；零构建开发启动可能读取陈旧产物或直接失败。
+
+**无条件应用根 tsconfig `paths`。** 不采用，因为这会让未声明的跨包 import 和 Cordis 插件继续成功解析，从而掩盖 manifest 与实际运行图之间的不一致。
+
+**在自定义 loader 内转换 import。** 不采用，因为感知类型的源码改写会重新引入编译器式转换，并让 loader 而非 Node 负责执行 TypeScript。使签入仓库的源码兼容 Node，可以让启动边界保持显式。
+
+## 后果
+
+- TUI／无头界面保留零构建源码回路，Web 仍会在启动 CLI 源码入口前构建前端产物。TypeScript 语法只经过 Node 原生转换；仅处理 URL 的 loader 使用 checkout 根目录的开发依赖，不增加 CLI 运行时依赖。
+- workspace package import 和 Cordis 配置依赖都必须在解析方 manifest 中明确声明；静态门禁防止配置先于依赖落地，额外依赖不构成错误。
+- 插件 import 失败不再留下退出码为 0 的残缺应用；最终错误同时说明 Cordis 启动失败及具体插件名，Loader 的原始错误仍会保留在更早的日志中。
+- CLI 源码图中的 vendor 源码必须与 Node 的 transform-types 模块语义兼容；本地修改记录明确了上游同步义务。
+- CI 的 `lib` 模式、测试／e2e 启动器和其他示例启动器保留各自现有策略；该原生源码 loader 只覆盖 `dsh` CLI 应用链路。

.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md
+2026-07-28-load-pre-identity-session-messages.md: 2901527658421b37576bdf5b49e66829104a3b41
+2026-07-28-load-pre-identity-session-messages.zh.md: 61d57ac9f3318299b63faa659b6d155e8e89fae3

.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md

@@ -0,0 +1,38 @@
+# Agent Note: Load sessions persisted before message identity
+
+Status: implemented
+
+English | [中文](2026-07-28-load-pre-identity-session-messages.zh.md)
+
+## Problem
+
+The identified immutable message change replaced four durable event payloads with complete message values. Existing v0 JSONL and SQLite sessions still held the immediately preceding shapes: direct `content`/`source` on user and steering events, `content`/`provenance` on assistant events, and `callId`/`content`/`isError` on tool results. Their headers still matched `SESSION_FORMAT_VERSION`, but current-shape validation rejected them before resume could construct a live `Session`.
+
+Changing the message representation without a version bump made those logs indistinguishable at the header level from current v0 logs. The runtime needs a narrow import rule that restores data created by the supported first-party backends without weakening validation for unrelated obsolete or malformed events.
+
+## Decision
+
+`PersistenceCoordinator` normalizes the four exact pre-identity message payloads after backend decoding and before current message validation. It wraps their existing semantic fields in the current role-specific message shape and assigns `legacy-message:<session-id>:<event-seq>` as the deterministic imported `MessageId`. A legacy `tool/result` content replacement inherits the imported id of its replacement target, preserving the current content-only rewrite invariant.
+
+The same normalization runs for `load`, `inspect`, an ownerless loaded state claiming its live session, and HMR prefix adoption. Prefix comparisons therefore compare the live current-shape seed with the same normalized stored view. Current-looking wrappers with missing or invalid fields are not repaired, and unsupported event vocabulary, request headers, versions, and surface relations retain their existing rejection paths.
+
+The upgrade is read-only. Stored legacy records remain unchanged; a resumed session appends only current-shape events after them. Deterministic identities make repeated loads and a mixed legacy/current log reproduce the same message ids without a backend-specific rewrite transaction.
+
+## Alternatives considered
+
+**Reject the logs under the pre-release compatibility stance.** This is the default for unrelated v0 churn, but it strands real first-party sessions even though every old field maps unambiguously to the current message representation.
+
+**Rewrite the complete stored log in place.** This would canonicalize the artifact but violate the append-only storage contract, require separate atomic replacement mechanisms for JSONL and SQLite, and expand a read compatibility fix into a migration system.
+
+**Mint random ids on each load.** The messages would satisfy the type shape but lose stable identity across inspect, resume, restart, and mixed legacy/current appends.
+
+## Consequences
+
+Pre-identity JSONL and SQLite sessions resume with their original message content, sources, provider provenance, tool correlation, errors, metadata, and surface replacements. The returned events are otherwise indistinguishable from current imported message snapshots and remain deeply frozen.
+
+This is one explicit same-version import exception, not a general v0 compatibility layer. Adding another exception requires another complete, unambiguous mapping at the persistence boundary; malformed current data continues to fail rather than being guessed into validity. The shared coordinator contract exercises the upgrade against the in-memory reference, JSONL, and SQLite backends, including deterministic reload and tool-result replacement identity.
+
+## Related
+
+- [Create every message as an identified immutable value](../architecture/2026-07-28-identified-immutable-message-values.md) — owns the current message identity and immutability contract.
+- [Session persistence as an abstract service](../architecture/2026-06-14-session-persistence.md) — owns the append-only backend and resume boundary.

.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md

@@ -0,0 +1,38 @@
+# Agent Note: 加载消息标识机制引入前持久化的会话
+
+Status: implemented
+
+[English](2026-07-28-load-pre-identity-session-messages.md) | 中文
+
+## 问题
+
+带标识的不可变消息变更将四种持久事件载荷替换为完整消息值。现有的 v0 JSONL 和 SQLite 会话仍保留紧邻该变更之前的形状：用户事件和 steering（中途引导）事件直接携带 `content`/`source`，assistant 事件携带 `content`/`provenance`，工具结果则携带 `callId`/`content`/`isError`。这些会话的 header 仍与 `SESSION_FORMAT_VERSION` 匹配，但当前形状验证会拒绝它们，导致恢复流程无法构造实时 `Session`。
+
+消息表示改变时没有提升版本，导致这些日志无法仅凭 header 与当前的 v0 日志区分。运行时需要一条范围受限的导入规则，既能恢复受支持的第一方后端所创建的数据，又不削弱对无关过时事件或格式错误事件的验证。
+
+## 决策
+
+`PersistenceCoordinator` 会在后端解码之后、当前消息验证之前，规范化消息标识机制引入前的四种特定消息载荷。它将载荷现有的语义字段包装进当前按角色区分的消息形状，并为其分配确定性的导入 `MessageId`：`legacy-message:<session-id>:<event-seq>`。旧版 `tool/result` 的内容替换会继承替换目标导入后的 id，从而保持当前仅改写内容的不变量。
+
+同一项规范化也用于 `load`、`inspect`、无 owner 的已加载状态认领其实时会话，以及 HMR（热模块替换）前缀接管。因此，前缀比较会将实时的当前形状 seed 与同一份规范化存储视图进行比较。看似当前形状、但字段缺失或无效的包装层不会被修复；不受支持的事件词汇、请求 header、版本和 surface 关系仍沿用现有拒绝路径。
+
+这项升级只发生在读取时。存储中的旧版记录保持不变；会话恢复后，只会在其后追加当前形状的事件。确定性标识使重复加载以及新旧形状混合的日志无需执行后端专用的重写事务，也能复现相同的消息 id。
+
+## 考虑过的替代方案
+
+**按照预发布兼容性立场拒绝这些日志。** 这是处理其他 v0 形状变动的默认方式，但即使每个旧字段都能明确映射到当前消息表示，它仍会导致真实的第一方会话无法恢复。
+
+**就地重写完整的存储日志。** 这会使产物规范化，但违反仅追加存储契约，还需要为 JSONL 和 SQLite 分别实现原子替换机制，并将一次读取兼容性修复扩大为迁移系统。
+
+**每次加载时随机生成 id。** 这些消息会满足类型形状，却无法在检查、恢复、重启以及新旧形状混合追加之间保持稳定标识。
+
+## 后果
+
+消息标识机制引入前的 JSONL 和 SQLite 会话可以恢复，并保留原始的消息内容、来源、提供方溯源信息、工具关联、错误、元数据和 surface 替换。除此之外，返回事件与当前导入的消息快照无法区分，并且仍然经过深度冻结。
+
+这是一个显式的同版本导入例外，而非通用的 v0 兼容层。若要增加另一个例外，必须在持久化边界提供另一套完整且无歧义的映射；当前数据若格式错误，系统仍会拒绝，而不会猜测如何将其变成有效数据。共享协调器契约会针对内存参考实现、JSONL 和 SQLite 后端验证这项升级，包括重新加载时的确定性，以及工具结果替换时的标识继承。
+
+## 相关
+
+- [将每条消息创建为带标识的不可变值](../architecture/2026-07-28-identified-immutable-message-values.md)：该记录负责当前的消息标识与不可变性契约。
+- [会话持久化作为抽象服务](../architecture/2026-06-14-session-persistence.md)：该记录负责仅追加后端与恢复边界。

.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.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
-2026-07-20-dsh-cli-personal-config.md: 9525aa811d792a918f03a52c21bc273e92fb8be7
-2026-07-20-dsh-cli-personal-config.zh.md: f21d4b1f22b3a3807b6b4155969282343f6048f5
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
+2026-07-20-dsh-cli-personal-config.md: cc965438214b68078647596af5a28fd666e7bd95
+2026-07-20-dsh-cli-personal-config.zh.md: 02f9c578061e1c25044c377c3ec8f80594275ae7

.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md

@@ -12,7 +12,7 @@ A developer's own preferences — which provider and model the TUI uses, persona
 
 Two coupled pieces, aligned with the `apps/` assembly tier proposed by the `dsh web` PR (#443):
 
-**The `dsh` CLI (`apps/cli`, npm name `@deepseek-ai/dsh`).** `apps/*` joins the workspaces as the product-assembly tier over `packages/*` libraries. The bin's dispatch reserves `web` and `-p`/`--prompt` for PR #443 (they exit with a pointer) so the two branches merge as a near-union; everything else runs the default surface: the interactive TUI, booting the shipped `examples/tui-agent/cordis.yml` (or an explicit config argument) with the invoking directory as the workspace. The committed `bin/dsh` launcher resolves the checkout through its own real path and runs the bin **from source** via the repo's tsx, so `ln -sf "$(pwd)/bin/dsh" ~/.local/bin/dsh` installs a command that always executes the current working tree. `pnpm run demo:tui` runs the same entry.
+**The `dsh` CLI (`apps/cli`, npm name `@deepseek-ai/dsh`).** `apps/*` joins the workspaces as the product-assembly tier over `packages/*` libraries. The bin's dispatch reserves `web` and `-p`/`--prompt` for PR #443 (they exit with a pointer) so the two branches merge as a near-union; everything else runs the default surface: the interactive TUI, booting the shipped `examples/tui-agent/cordis.yml` (or an explicit config argument) with the invoking directory as the workspace. The committed `bin/dsh` launcher resolves the checkout through its own real path and runs the bin **from source** through Node's native TypeScript transform plus the app-owned tsconfig-paths loader, so `ln -sf "$(pwd)/bin/dsh" ~/.local/bin/dsh` installs a command that always executes the current working tree. `pnpm run demo:tui` runs the same entry.
 
 **Personal config (`dsh-app-boot`).** The personal overlay lives in the Harness home — `$DSH_HOME`, else `~/.dsh` — resolved by the shared [`resolveDshHome`](../architecture/2026-07-24-single-harness-home-resolver.md) (`@deepseek-ai/dsh-paths`), the same single root skills and AGENTS.md resolve against. The dsh TUI surface consumes its two optional files; the demo bins boot their committed trees verbatim:
 

.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md

@@ -12,7 +12,7 @@ Status: implemented
 
 两个耦合的部分，与 `dsh web` PR（#443）提出的 `apps/` 装配层对齐：
 
-**`dsh` CLI（`apps/cli`，npm 名 `@deepseek-ai/dsh`）。** `apps/*` 作为 `packages/*` 库之上的产品装配层加入 workspaces。bin 的分发把 `web` 和 `-p`/`--prompt` 保留给 PR #443（它们以指引退出），使两个分支能以接近并集的方式合并；其余一切都运行默认表面：交互式 TUI，加载随仓库提供的 `examples/tui-agent/cordis.yml`（或显式的配置参数），并以调用目录为工作区。已提交的 `bin/dsh` 启动器通过自身真实路径解析 checkout，用仓库的 tsx **从源码**运行该 bin，因此 `ln -sf "$(pwd)/bin/dsh" ~/.local/bin/dsh` 安装的命令永远执行当前工作树。`pnpm run demo:tui` 运行同一入口。
+**`dsh` CLI（`apps/cli`，npm 名 `@deepseek-ai/dsh`）。** `apps/*` 作为 `packages/*` 库之上的产品装配层加入 workspaces。bin 的分发把 `web` 和 `-p`/`--prompt` 保留给 PR #443（它们以指引退出），使两个分支能以接近并集的方式合并；其余一切都运行默认表面：交互式 TUI，加载随仓库提供的 `examples/tui-agent/cordis.yml`（或显式的配置参数），并以调用目录为工作区。已提交的 `bin/dsh` 启动器通过自身真实路径解析 checkout，通过 Node 的原生 TypeScript 转换和应用自身持有的 tsconfig-paths loader **从源码**运行该 bin，因此 `ln -sf "$(pwd)/bin/dsh" ~/.local/bin/dsh` 安装的命令永远执行当前工作树。`pnpm run demo:tui` 运行同一入口。
 
 **个人配置（`dsh-app-boot`）。** 个人 overlay 存放在 Harness home——`$DSH_HOME`，否则 `~/.dsh`——由共享的 [`resolveDshHome`](../architecture/2026-07-24-single-harness-home-resolver.md)（`@deepseek-ai/dsh-paths`）解析，与 skills、AGENTS.md 解析所依据的单一根目录相同。dsh 的 TUI 表面消费其中两个可选文件；各示例 bin 仍然逐字节按已提交的配置树启动：
 

.agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.md
-2026-06-16-pnpm-over-yarn.md: 918da1d056dfec73f78d849e08ad06d397e654c0
-2026-06-16-pnpm-over-yarn.zh.md: 4fbb357f689b4a960d0662cbefa5bec30f79bcc1
+2026-06-16-pnpm-over-yarn.md: 30b34c65fdea94b20dec4d627a0fca40de760fd1
+2026-06-16-pnpm-over-yarn.zh.md: eb13890b7e7051301874b9273966771328b065a3

.agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.md

@@ -8,7 +8,7 @@ English | [中文](2026-06-16-pnpm-over-yarn.zh.md)
 
 The repo shipped on **Yarn 4** with the `node-modules` linker — a deliberately conservative choice that behaves like npm's flat layout while giving us Yarn's workspaces and `yarn constraints`. It worked. But Yarn 4's Plug'n'Play heritage makes the `node-modules` linker the off-the-beaten-path mode, and the broader JS ecosystem — tooling defaults, CI actions, Corepack examples, contributor familiarity — increasingly centers on pnpm. For a repo that is built primarily by agents and read by occasional human contributors, "the package manager most tools and people expect" has real value: fewer surprises, better-trodden failure paths, more copy-pasteable answers.
 
-The switching cost is at its lowest right now. Nothing publishes from this repo yet (every package is `private: true`); dev/test/demo all run **unbuilt** via tsx, so the package manager only has to (a) resolve and link `node_modules`, (b) run the workspace scripts, and (c) enforce the workspace constraints. The one Yarn-specific asset is `yarn.config.cjs` (the `@yarnpkg/types` constraints engine), which is small and mechanical to re-express. This mirrors the reasoning in [the tsdown decision](../../archived/process/2026-06-11-tsdown-over-dumble.md): swap a load-bearing tool for the healthier-ecosystem option while the blast radius is still small.
+The switching cost is at its lowest right now. Nothing publishes from this repo yet (every package is `private: true`); development, tests, and source-mode demos run through their declared TypeScript launchers, while artifact checks build explicitly. The package manager therefore only has to (a) resolve and link `node_modules`, (b) run the workspace scripts, and (c) enforce the workspace constraints. The one Yarn-specific asset is `yarn.config.cjs` (the `@yarnpkg/types` constraints engine), which is small and mechanical to re-express. This mirrors the reasoning in [the tsdown decision](../../archived/process/2026-06-11-tsdown-over-dumble.md): swap a load-bearing tool for the healthier-ecosystem option while the blast radius is still small.
 
 ## Decision
 

.agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.zh.md

@@ -8,7 +8,7 @@ Status: implemented
 
 本仓库最初使用 **Yarn 4** 搭配 `node-modules` 链接器启动。这是一个刻意保守的选择：行为类似 npm 的扁平布局，同时享有 Yarn 的 workspaces 和 `yarn constraints`。它能正常工作。但 Yarn 4 源自 Plug'n'Play 的血统，使得 `node-modules` 链接器成为非主流模式；而更广泛的 JS 生态——工具默认值、CI action、Corepack 示例、贡献者的熟悉度——正日益以 pnpm 为中心。对于一个主要由 agent（智能体）构建、偶尔有人类贡献者阅读的仓库而言，「大多数工具和人所期望的包管理器」具有实际价值：更少的意外、更成熟的故障路径、更多可直接复用的解答。
 
-切换成本目前处于最低点。本仓库尚无任何包（package）发布（每个包都是 `private: true`）；开发/测试/演示全部通过 tsx **未构建**运行，因此包管理器只需做到：（a）解析并链接 `node_modules`，（b）运行 workspace 脚本，（c）强制执行 workspace 约束。唯一的 Yarn 特有资产是 `yarn.config.cjs`（`@yarnpkg/types` 约束引擎），体量小且可机械地重新表达。这与 [tsdown 决策](../../archived/process/2026-06-11-tsdown-over-dumble.md)的逻辑一致：在爆炸半径尚小时，将承重工具换为生态更健康的选项。
+切换成本目前处于最低点。本仓库尚无任何包（package）发布（每个包都是 `private: true`）；开发流程、测试和源码模式 demo 都通过各自声明的 TypeScript 启动器运行，产物检查则会显式构建。因此，包管理器只需做到：（a）解析并链接 `node_modules`，（b）运行 workspace 脚本，（c）强制执行 workspace 约束。唯一的 Yarn 特有资产是 `yarn.config.cjs`（`@yarnpkg/types` 约束引擎），体量小且可机械地重新表达。这与 [tsdown 决策](../../archived/process/2026-06-11-tsdown-over-dumble.md)的逻辑一致：在爆炸半径尚小时，将承重工具换为生态更健康的选项。
 
 ## 决策
 

.agents/notes/implemented/process/2026-06-17-ts-build-config.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
-2026-06-17-ts-build-config.md: 5bdfc5e170f12cd95a68f443ab8d02b16db554f3
-2026-06-17-ts-build-config.zh.md: 9f74fb6be9c8e00a070e27a609edf8421a2b5ca6
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-06-17-ts-build-config.md
+2026-06-17-ts-build-config.md: 20dd3d8d0a11e01397c36388903cd112a170f0bf
+2026-06-17-ts-build-config.zh.md: 196ed3f2921a4be6f65cd56fc496993b7121f484

.agents/notes/implemented/process/2026-06-17-ts-build-config.md

@@ -62,7 +62,7 @@ pnpm run clean:
 tsx scripts/clean.ts
 ```
 
-`pnpm run demo:*` still runs `src` directly through tsx and root paths, without a compile step.
+The source-mode demos run through their declared TypeScript launchers and the root paths map. The `dsh` TUI chain uses Node's native transform plus its app-owned paths loader, the Web demo builds its required artifacts before entering that same CLI source chain, and the other source demos continue to use tsx.
 
 ## Alternatives considered
 
@@ -75,7 +75,7 @@ tsx scripts/clean.ts
 
 Build responsibilities are clearer:
 
-- Each module under `packages/<group>/<pkg>` and `vendor/*` has one local tsconfig for build, typecheck, and tools that run source directly, such as `tsx` and `vitest`.
+- Each module under `packages/<group>/<pkg>` and `vendor/*` has one local tsconfig for build, typecheck, and tools that run source directly, such as the `dsh` source loader, `tsx`, and `vitest`.
 - The `build` command drives the root solution graph. `tsc -b` owns the publishable per-module `.js` and `.d.ts` output, and the bundler owns only `lib/index.*`.
     - `lib/types/*.d.ts` and `.d.ts.map` are the publish declaration output.
     - `lib/types/*.d.ts` uses explicit `.ts` relative specifiers, which TypeScript's NodeNext/Node16 resolver maps to sibling `.d.ts` files.

.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md

@@ -62,7 +62,7 @@ pnpm run clean:
 tsx scripts/clean.ts
 ```
 
-`pnpm run demo:*` 仍通过 tsx 和根路径直接运行 `src`，无需编译步骤。
+源码模式 demo 通过各自声明的 TypeScript 启动器和根路径映射运行。`dsh` TUI 链使用 Node 原生转换及应用自有的路径 loader，Web demo 在进入同一条 CLI 源码链路前先构建所需产物，其他源码 demo 继续使用 tsx。
 
 ## 曾考虑的替代方案
 
@@ -75,7 +75,7 @@ tsx scripts/clean.ts
 
 构建职责更加清晰：
 
-- `packages/<group>/<pkg>` 和 `vendor/*` 下的每个模块有一份本地 tsconfig，同时服务于构建、类型检查和直接运行源码的工具（如 `tsx` 和 `vitest`）。
+- `packages/<group>/<pkg>` 和 `vendor/*` 下的每个模块有一份本地 tsconfig，同时服务于构建、类型检查和直接运行源码的工具（如 `dsh` 源码 loader、`tsx` 和 `vitest`）。
 - `build` 命令驱动根 solution 图。`tsc -b` 负责可发布的逐模块 `.js` 和 `.d.ts` 输出，打包器仅负责 `lib/index.*`。
     - `lib/types/*.d.ts` 和 `.d.ts.map` 是发布用的声明输出。
     - `lib/types/*.d.ts` 使用显式 `.ts` 相对说明符，TypeScript 的 NodeNext/Node16 解析器会将其映射到同级的 `.d.ts` 文件。

.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
-2026-07-27-session-projection-and-command-log.md: 51cc60208ecafd55738c12f1887056c7b0427117
-2026-07-27-session-projection-and-command-log.zh.md: 71f6f6ea944c7c1bdd7e560ec8f0dc2528522fc1
+2026-07-27-session-projection-and-command-log.md: 6a073c956c27bbfc65cff2d4f44ca12023df0cd5
+2026-07-27-session-projection-and-command-log.zh.md: 500f07968db049e4a174ff3b7a075bfe095283db

.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md

@@ -51,7 +51,7 @@ declare module 'cordis' {
 
 - Values are wire JSON payloads; the same map typed end to end (host unit, wire block, React hook) via `import type` — no second DTO table, no separate client-side "views" map. How a value is *rendered* is the slot system's business, never the projection layer's.
 - **The host is the only place a projection is computed.** The framework drives every registered unit forward eagerly: each committed session event passes through `apply`; a unit uninterested in an event returns the same state reference, and an unchanged reference (`Object.is`) produces no downstream work. Clients never fold domain events — they receive finished values (baseline block + push frame below). This removes the double-implementation trap (plan's two-event fold written once, on the host) and any client-side domain code.
-- **State is always computed, never logged.** The log holds events only; the unit's state lives in the framework's per-session watermark cache (`{state, observedSeq}` per unit) and, in a later phase, in a **persisted projection cache** on the domain-KV storage seam: rows of `(sessionId, key, stateVersion, observedSeq, stateJson)`. A row is never wrong, only possibly stale — `observedSeq` says exactly how stale. The one read recipe, cold and live alike: take the cached state (or `init()`), forward-apply only the events past its watermark, `view` the result. Cold listings (every session's title across all workspaces) become an index read plus, at worst, a short tail replay; the session-persistence seam grows a read-from-seq primitive for that tail in the same later phase. Write policy: throttled (count/interval, configurable) plus two mandatory points — `turn/end` and detach (the live-to-cold moment). A crash between writes costs a longer tail replay, never a wrong value.
+- **State is always computed, never logged.** The log holds events only; the unit's state lives in the framework's per-session watermark cache (`{state, observedSeq}` per unit) and, in a later phase, in a **persisted projection cache** on the domain-KV storage seam: rows of `(sessionId, key, ver, seq, val)` (`ver` = the unit's `stateVersion`, `seq` = the watermark, `val` = the state JSON). A row is never wrong, only possibly stale — its `seq` says exactly how stale. The one read recipe, cold and live alike: take the cached state (or `init()`), forward-apply only the events past its watermark, `view` the result. Cold listings (every session's title across all workspaces) become an index read plus, at worst, a short tail replay; the session-persistence seam grows a read-from-seq primitive for that tail in the same later phase. Write policy: throttled (count/interval, configurable) plus two mandatory points — `turn/end` and detach (the live-to-cold moment). A crash between writes costs a longer tail replay, never a wrong value.
 - A domain's input event set is its own choice: todos folds `todo/write` alone; plan folds `plan/mode` plus its own `/plan` `command/run` records (see the plan section); goal folds `goal/change` metadata; session title folds its title events (retiring the bespoke `session/title` frame and the client's title-snapshot map — the fourth hand-rolled projection this seam absorbs).
 - Registration is an effect (disposer with the fiber): an unloaded plugin's key disappears from subsequent responses and the client reads it as capability absence — HMR semantics for free. Duplicate keys throw. Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected.
 - The package owns `./invariant` (every served key has a live registration).
@@ -133,7 +133,7 @@ Infrastructure first; the three in-flight PRs are left untouched and re-target a
 2. **Client base**: the generic value store + `useProjection` seat; retire the per-domain cell machinery and, with title's unit registered, the `session/title` frame and title-snapshot map. Depends on 1 for the frame shape (fixtures feed synthetic frames meanwhile).
 3. **Command channel**: the two events, executor logging, generic node + keyed slot, notice retirement, `{matched, commandId?}` admission. Parallel with 1.
 4. **Domain re-targets** (after 1+2): todo (unit in `tool-todo`, drop the rider field), then plan (two-event unit, RPCs retired, toggle → `/plan`), then goal (`goal/change` unit, drop `goals.get`, move the six `Session` methods into the domain plugin's inject).
-5. **Persisted projection cache** (later phase, after the domain-KV storage seam): the `(sessionId, key, stateVersion, observedSeq, state)` rows, throttled writes with turn/end + detach mandatory points, and the persistence read-from-seq primitive for cold tail replay.
+5. **Persisted projection cache** (later phase, after the domain-KV storage seam): the `(sessionId, key, ver, seq, val)` rows, throttled writes with turn/end + detach mandatory points, and the persistence read-from-seq primitive for cold tail replay.
 
 ## Alternatives considered
 

.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md

@@ -51,7 +51,7 @@ declare module 'cordis' {
 
 - 值就是协议层的 JSON 载荷；同一张类型表经 `import type` 端到端贯通（host 侧单元、协议块、React 钩子）——没有第二张 DTO 表，也没有独立的客户端「views」表。值如何*渲染*是 slot 体系的事，永远不归投影层管。
 - **host 是投影唯一的计算地点。** 框架正向驱动（eager drive）每个已注册的单元：每个已提交的会话事件都经过 `apply`；对某事件不感兴趣的单元返回同一个状态引用，而引用未变（`Object.is`）就不产生任何下游工作。客户端从不折叠领域事件——它们收到的是成品值（基线块 + 下文的推送帧）。这消除了双重实现陷阱（plan 的双事件折叠只在 host 写一遍），也消除了一切客户端侧领域代码。
-- **状态永远靠计算得出，绝不入日志。** 日志只存事件；单元的状态住在框架的按会话水位线缓存里（每单元一份 `{state, observedSeq}`），并在后续阶段进入 domain-KV 存储 seam 上的**持久投影缓存（persisted projection cache）**：形如 `(sessionId, key, stateVersion, observedSeq, stateJson)` 的行。一行永远不会是错的，至多是陈旧的——`observedSeq` 精确说明陈旧到哪。冷读与活读共用同一套读取配方：取缓存状态（或 `init()`），只对超出其水位线的事件做正向 `apply`，再对结果做 `view`。冷列表（跨全部 workspace 列出每个会话的标题）变成一次索引读，至多外加一小段尾部回放；session-persistence seam 在同一后续阶段为这段尾部补一个按 seq 起读的原语。写入策略：节流（次数/间隔，可配置）外加两个强制点——`turn/end` 与 detach（由活转冷的时刻）。两次写入之间崩溃的代价是尾部回放更长一些，绝不会是值出错。
+- **状态永远靠计算得出，绝不入日志。** 日志只存事件；单元的状态住在框架的按会话水位线缓存里（每单元一份 `{state, observedSeq}`），并在后续阶段进入 domain-KV 存储 seam 上的**持久投影缓存（persisted projection cache）**：形如 `(sessionId, key, ver, seq, val)` 的行（`ver` = 单元的 `stateVersion`，`seq` = 水位线，`val` = 状态 JSON）。一行永远不会是错的，至多是陈旧的——其 `seq` 精确说明陈旧到哪。冷读与活读共用同一套读取配方：取缓存状态（或 `init()`），只对超出其水位线的事件做正向 `apply`，再对结果做 `view`。冷列表（跨全部 workspace 列出每个会话的标题）变成一次索引读，至多外加一小段尾部回放；session-persistence seam 在同一后续阶段为这段尾部补一个按 seq 起读的原语。写入策略：节流（次数/间隔，可配置）外加两个强制点——`turn/end` 与 detach（由活转冷的时刻）。两次写入之间崩溃的代价是尾部回放更长一些，绝不会是值出错。
 - 领域的输入事件集由领域自己选择：todos 只折叠 `todo/write`；plan 折叠 `plan/mode` 外加它自己的 `/plan` `command/run` 记录（见 plan 一节）；goal 折叠 `goal/change` 元数据；会话标题折叠其标题事件（顺带下线专设的 `session/title` 帧与客户端的标题快照表——这是该 seam 收编的第四个手工投影）。
 - 注册是 effect（disposer 随 fiber 走）：插件卸载后其 key 从后续响应中消失，客户端将其读作能力缺失——HMR（热模块替换）语义随之自动成立。key 重复直接 throw。领域插件在 `ctx.inject(['sessionProjections'], …)` 下注册，因此不带注册表的 headless 组装完全不受影响。
 - 该包拥有 `./invariant`（每个被服务的 key 都有一条存活的注册）。
@@ -133,7 +133,7 @@ host 侧命令执行器（`packages/ui/commands`）在调用处理器前追加 `
 2. **客户端基座**：通用值仓 + `useProjection` 席位；下线按领域的 cell 机制，并在标题单元注册后一并下线 `session/title` 帧与标题快照表。帧的形状依赖 1（在此之前 fixture（测试前置数据）喂合成帧）。
 3. **命令通道**：两个事件、执行器落日志、通用节点 + keyed slot、通知通道下线、`{matched, commandId?}` 准入。与 1 并行。
 4. **领域重新对接**（在 1+2 之后）：先 todo（单元进 `tool-todo`，删掉搭载字段），再 plan（双事件单元、RPC 下线、开关改发 `/plan`），最后 goal（`goal/change` 单元，删掉 `goals.get`，把六个 `Session` 方法移入领域插件的 inject）。
-5. **持久投影缓存**（后续阶段，待 domain-KV 存储 seam 就绪后）：`(sessionId, key, stateVersion, observedSeq, state)` 行、带 turn/end 与 detach 强制点的节流写入，以及持久化侧供冷尾部回放用的按 seq 起读原语。
+5. **持久投影缓存**（后续阶段，待 domain-KV 存储 seam 就绪后）：`(sessionId, key, ver, seq, val)` 行、带 turn/end 与 detach 强制点的节流写入，以及持久化侧供冷尾部回放用的按 seq 起读原语。
 
 ## Alternatives considered
 

.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md
+2026-07-28-storage-root-and-derived-medium-recovery.md: 06fa98b10dc5ac3164d8905e7005a42d9e99ae92
+2026-07-28-storage-root-and-derived-medium-recovery.zh.md: b7bd18ffdbfaf412d9a91940cf1770e273f5b847

.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md

@@ -0,0 +1,57 @@
+# Agent Note: Storage root placement and derived-medium recovery
+
+Status: proposed
+
+English | [中文](2026-07-28-storage-root-and-derived-medium-recovery.zh.md)
+
+## Problem
+
+The persisted projection cache ([RFC](2026-07-27-session-projection-and-command-log.md), shipped as `dsh-session-projection-cache`) surfaced two gaps in the storage substrate it landed on. Both are properties of the domain-KV stack ([design](2026-07-24-domain-kv-storage-and-workspace.md)), not of the cache itself, and both bite the cache first because it is the first *derived* medium on that stack.
+
+**Where the files actually live.** The shipped composition gives the json backend a relative root — `root: './.storages'` (apps/cli/cordis.yml) — and `AppCLIEntry.composePatches` patches only the session store's root to the global harness home (`$DSH_HOME/sessions`, default `~/.dsh/sessions`, profile-overridable via `persistenceRoot`); no equivalent patch or profile key exists for `storage-json`. `JsonStorageBackend` never resolves its root either — each unit open joins the still-relative path against whatever `process.cwd()` is at that moment (packages/storage/storage-json/src/index.ts) — the exact hazard the JSONL session backend resolves-once to prevent ("later process.cwd() changes cannot split one backend across roots", packages/session-persistence/session-persistence-jsonl/src/index.ts). Net effect: session logs are global across launch directories, but `workspace.json` and `session_projcache.json` land under `<launch dir>/.storages/`. Two launches from different directories share their sessions yet see different workspace registries and different projection caches — and the cache exists precisely to serve the cross-session cold listing, which now misses for every session last cached under another launch directory.
+
+**How recovery works today.** Inside a healthy medium the cache is fully self-healing by design: a `stateVersion`-mismatched row is discarded and refolded, a log shrunk below a row's watermark is detected by the anchored restore floor and answered with one full re-read, and every background write is fail-soft. But at the *medium* level there is no recovery at all: a truncated, hand-edited, or version-bumped `session_projcache.json` fails `openJsonUnit` with `malformed-medium`/`version-mismatch` (packages/storage/storage-json/src/format.ts), a schema-drifted record fails domain open with `invalid-record` (packages/storage/storage-domain/src/index.ts), the rejection propagates through `SessionProjectionCache[Service.init]`, and under the CLI's fail-loud boot the assembly refuses to start. A file whose entire content is rebuildable from session logs can brick boot. This contradicts the cache package's own stated stance ("a stale or unreadable cache costs a longer tail replay, never a wrong value") and the cache domain spec's JSDoc ("version bumps discard the whole medium"), which today describes an aspiration, not the implementation. The same fail-loud path is *correct* for `workspace.json` — workspace records are authoritative, not derivable — so the missing concept is a per-domain declaration of authority, not a global behavior change.
+
+## Proposal
+
+Two independent changes, one per gap.
+
+### One global storage root, resolved once
+
+- `AppCLIEntry.composePatches` Source 0 additionally patches `storage-json.root` to `join(resolveDshHome(), 'storages')` — `~/.dsh/storages` by default, beside `~/.dsh/sessions` — and `PROFILE_MAPPINGS` gains `storageRoot` → (`storage-json`, `root`), mirroring `persistenceRoot` exactly. The yml keeps `./.storages` as the raw-composition engineering default (tests and bare Loader boots are unaffected), same layering as the session root today.
+- `JsonStorageBackend` resolves its configured root once at construction (`resolve(config.root)`), adopting the JSONL backend's recorded rationale verbatim: a later `process.cwd()` change must not split one backend across roots. The SQLite storage backend already resolves its path.
+- Pre-release stance applies: no migration shim. A deployment that cached under `<cwd>/.storages` re-derives everything (workspace re-bootstraps from the header index; the projection cache refolds lazily) or moves the two json files by hand once.
+
+### Declared derived media: reset instead of reject
+
+- `DomainSpec` gains `recovery?: 'reject' | 'reset'` (default `'reject'`). The spec object is already the single source of a domain's identity and layout; whether its medium is authoritative or derived is the same kind of fact and lives in the same place. `session_projcache` declares `'reset'`; `workspace` stays on the default.
+- `KvFacet` gains one primitive: `destroy(descriptor): Promise<void>` — remove the unit's medium entirely (json: delete the file; sqlite: drop the unit's tables). Like `open`, it is a backend storage primitive, not policy.
+- `DomainFacility.open`, when a spec declares `'reset'` and the open fails with exactly a damage-class error — `StorageError('version-mismatch' | 'malformed-medium')` or `DomainError('invalid-record')` — logs one warning naming the domain and the discarded medium, calls `destroy`, and opens again empty. Every other failure (`backend-not-found`, `facet-unsupported`, `already-open`, I/O errors) stays loud regardless of the declaration: misconfiguration and environmental faults are not medium damage. The retry is single-shot — a second failure propagates, so a persistently failing medium cannot loop.
+- With this in place the cache domain spec's version field gains its intended meaning: bumping `version` (or letting zod reject drifted rows) genuinely discards the whole medium and the cache rebuilds through its normal write points and cold reads — the recovery ladder's outermost rung, matching the row-level rungs already shipped.
+
+## Alternatives considered
+
+**Keep per-launch-directory `.storages` (status quo)** — rejected: sessions are global, so every derived-from-sessions medium splits against its own source of truth; the cache's motivating scenario (one listing over all sessions) structurally misses rows, and the workspace registry indexes sessions it cannot see from another launch directory.
+
+**Patch only the projection cache's route to a global root, leave `workspace.json` per-cwd** — rejected: the workspace registry has the identical global-vs-cwd mismatch, and the user decision that shaped the cache placed it deliberately beside `workspace.json` — one hub root keeps the media co-located and the mental model single.
+
+**Cache-plugin-local recovery (catch damage errors in `SessionProjectionCache[Service.init]`, delete the file, reopen)** — rejected: the plugin cannot name the medium path without reaching around the backend abstraction, and every future derived domain would re-implement the same catch; the facility is the one place that already classifies open failures.
+
+**Fall back to an ephemeral in-memory domain on damage** — rejected: it silently degrades to memory-only for the life of the process and the damaged file never heals; the next boot fails the same way.
+
+**Rename the damaged medium aside (`<unit>.json.corrupt-<ts>`) instead of deleting** — not chosen: a derived medium's damaged bytes have no recovery value (the logs are the source of truth) and the litter accumulates unbounded; delete is the honest operation. Rename-aside remains the right choice if a future *authoritative* domain ever wants reset semantics — which is exactly why `recovery` is per-spec.
+
+**A blanket auto-reset for every domain (no spec field)** — rejected outright: `workspace.json` is authoritative user data; silently resetting it on a version bump would destroy workspaces. Authority is a property of the domain and must be declared by its owner.
+
+## Acceptance criteria
+
+- `dsh` launched from any directory reads and writes the same `$DSH_HOME/storages/*.json` (default `~/.dsh/storages`); the profile key `storageRoot` overrides it; a raw Loader boot of the yml still lands in `./.storages` relative to the boot cwd, resolved once at backend construction.
+- With a truncated, version-bumped, or schema-drifted `session_projcache.json`, the assembly boots clean: one warning names the discarded medium, the file is gone, the cache rebuilds through normal operation, and the cold listing column reappears as sessions are re-checkpointed.
+- The same damage to `workspace.json` still fails boot loudly.
+- Facility tests cover: each damage class resets a `'reset'` domain exactly once; non-damage failures stay loud on a `'reset'` domain; a `'reject'` domain propagates every failure; `destroy` removes the medium on both shipped backends.
+
+## Risks
+
+- **Auto-delete on a misclassified error destroys a healthy file.** Mitigated by the closed damage-class list: reset fires only on the three deterministic parse-time codes; ENOENT is already "empty unit", and every I/O error (EACCES, EIO) propagates loudly. The single-shot retry bounds the blast radius to one delete per open.
+- **Root relocation changes where existing checkouts look.** Accepted under the pre-release stance (backends reject old formats, no external consumers); the note above records the one-time manual move for anyone who cares about a per-cwd `workspace.json`'s content.
+- **`destroy` is a new destructive primitive on the storage seam.** Its only caller is the facility's declared-reset path; the backend contract documents it as facility-owned, and nothing model-facing or user-facing can reach it.

.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md

@@ -0,0 +1,57 @@
+# Agent Note：存储根目录落点与派生介质恢复
+
+Status: proposed
+
+[English](2026-07-28-storage-root-and-derived-medium-recovery.md) | 中文
+
+## Problem
+
+持久投影缓存（[RFC](2026-07-27-session-projection-and-command-log.md)，已作为 `dsh-session-projection-cache` 落地）暴露了它所依托的存储基座的两个缺口。二者都是 domain-KV 栈（[设计](2026-07-24-domain-kv-storage-and-workspace.md)）的属性而非缓存自身的问题，且都首先咬到缓存——因为它是这条栈上第一个*派生*介质。
+
+**文件到底存在哪。** 出厂组合给 json 后端的是相对根目录——`root: './.storages'`（apps/cli/cordis.yml）——而 `AppCLIEntry.composePatches` 只把会话存储的根 patch 到全局 harness home（`$DSH_HOME/sessions`，默认 `~/.dsh/sessions`，可经 profile 键 `persistenceRoot` 覆盖）；`storage-json` 没有对应的 patch 也没有 profile 键。`JsonStorageBackend` 自己也从不 resolve 根——每次打开 unit 都把仍然相对的路径 join 到当时的 `process.cwd()` 上（packages/storage/storage-json/src/index.ts）——这正是 JSONL 会话后端用「构造时 resolve 一次」防住的那个隐患（"later process.cwd() changes cannot split one backend across roots"，packages/session-persistence/session-persistence-jsonl/src/index.ts）。净效果：会话日志跨启动目录全局共享，但 `workspace.json` 和 `session_projcache.json` 落在 `<启动目录>/.storages/` 下。从两个不同目录启动，会话相同，工作区注册表和投影缓存却各是一份——而缓存存在的意义恰恰是跨会话冷列表，如今凡是上次在别的启动目录下缓存过的会话全部 miss。
+
+**现在是怎么恢复的。** 在健康介质内部，缓存按设计完全自愈：`stateVersion` 不匹配的行被丢弃重折，日志缩短到行水位以下由带锚的 restore floor 检出并以一次全量重读回答，每次后台写都是 fail-soft。但在*介质*层面完全没有恢复：被截断、被手改或版本被 bump 的 `session_projcache.json` 会让 `openJsonUnit` 以 `malformed-medium`/`version-mismatch` 失败（packages/storage/storage-json/src/format.ts），schema 漂移的记录让域 open 以 `invalid-record` 失败（packages/storage/storage-domain/src/index.ts），拒绝一路穿过 `SessionProjectionCache[Service.init]`，在 CLI 的 fail-loud 启动下整个组装拒绝启动。一个内容完全可从会话日志重建的文件能把启动搞死。这与缓存包自己声明的立场（"a stale or unreadable cache costs a longer tail replay, never a wrong value"）和缓存域 spec 的 JSDoc（"version bumps discard the whole medium"）相矛盾——后者今天描述的是愿望而非实现。同一条 fail-loud 路径对 `workspace.json` 却是*正确*的——工作区记录是权威数据，不可派生——所以缺的概念是按域声明权威性，而不是全局改行为。
+
+## Proposal
+
+两个独立改动，一个缺口一个。
+
+### 全局唯一存储根，构造时 resolve 一次
+
+- `AppCLIEntry.composePatches` 的 Source 0 追加把 `storage-json.root` patch 到 `join(resolveDshHome(), 'storages')`——默认 `~/.dsh/storages`，与 `~/.dsh/sessions` 并肩——并且 `PROFILE_MAPPINGS` 增加 `storageRoot` →（`storage-json`，`root`），与 `persistenceRoot` 完全镜像。yml 保留 `./.storages` 作为裸组合的工程默认（测试和裸 Loader 启动不受影响），分层方式与今天的会话根相同。
+- `JsonStorageBackend` 在构造时对配置根 `resolve` 一次，原样采纳 JSONL 后端已记录的理由：后续 `process.cwd()` 变化不得把一个后端劈到多个根下。SQLite 存储后端已经 resolve 其路径。
+- 适用 pre-release 立场：不做迁移垫片。曾在 `<cwd>/.storages` 下缓存过的部署要么全部重新派生（工作区从 header 索引重新 bootstrap；投影缓存惰性重折），要么手动把两个 json 文件挪一次。
+
+### 声明派生介质：损坏时重置而非拒绝
+
+- `DomainSpec` 增加 `recovery?: 'reject' | 'reset'`（默认 `'reject'`）。spec 对象已经是一个域的身份与布局的单一来源；其介质是权威还是派生属于同类事实，落在同一处。`session_projcache` 声明 `'reset'`；`workspace` 保持默认。
+- `KvFacet` 增加一个原语：`destroy(descriptor): Promise<void>`——整体移除该 unit 的介质（json：删文件；sqlite：drop 该 unit 的表）。与 `open` 一样，它是后端存储原语，不是策略。
+- `DomainFacility.open` 在 spec 声明 `'reset'` 且 open 恰以损坏类错误失败时——`StorageError('version-mismatch' | 'malformed-medium')` 或 `DomainError('invalid-record')`——记一条命名该域和被丢弃介质的警告，调用 `destroy`，再空开一次。其余一切失败（`backend-not-found`、`facet-unsupported`、`already-open`、I/O 错误）无论声明与否都保持大声：配置错误和环境故障不是介质损坏。重试单发——第二次失败原样传播，持续失败的介质不会成环。
+- 有了这个，缓存域 spec 的 version 字段才获得其本意：bump `version`（或让 zod 拒绝漂移行）真正丢弃整个介质，缓存经正常写点和冷读重建——恢复阶梯的最外一档，与已落地的行级各档对齐。
+
+## Alternatives considered
+
+**保持按启动目录的 `.storages`（现状）**——拒绝：会话是全局的，所以每个从会话派生的介质都与自己的真源劈叉；缓存的动机场景（一次列出全部会话）结构性丢行，工作区注册表索引着从另一个启动目录看不见的会话。
+
+**只把投影缓存的 route 指到全局根，`workspace.json` 留在 per-cwd**——拒绝：工作区注册表有一模一样的全局 vs per-cwd 错位，而且塑造缓存的用户决策就是刻意把它放在 `workspace.json` 旁边——一个 hub 根让介质同址、心智模型单一。
+
+**缓存插件本地恢复（在 `SessionProjectionCache[Service.init]` 捕获损坏错误、删文件、重开）**——拒绝：插件不越过后端抽象就叫不出介质路径，且未来每个派生域都要重抄同一段 catch；facility 是唯一已经在分类 open 失败的地方。
+
+**损坏时退到内存态临时域**——拒绝：进程余生静默降级为仅内存，损坏文件永不自愈；下次启动照样失败。
+
+**把损坏介质改名旁置（`<unit>.json.corrupt-<ts>`）而非删除**——未选：派生介质的损坏字节没有恢复价值（日志才是真源），残骸无界累积；删除才是诚实的操作。若未来某个*权威*域想要重置语义，旁置改名才是对的——这正是 `recovery` 按 spec 声明的理由。
+
+**所有域一律自动重置（不加 spec 字段）**——断然拒绝：`workspace.json` 是权威用户数据；版本 bump 时静默重置会毁掉工作区。权威性是域的属性，必须由其所有者声明。
+
+## Acceptance criteria
+
+- 从任意目录启动 `dsh` 都读写同一份 `$DSH_HOME/storages/*.json`（默认 `~/.dsh/storages`）；profile 键 `storageRoot` 可覆盖；裸 Loader 启动 yml 仍落在相对启动 cwd 的 `./.storages`,并在后端构造时 resolve 一次。
+- `session_projcache.json` 被截断、版本 bump 或 schema 漂移时，组装干净启动：一条警告命名被丢弃的介质，文件消失，缓存经正常运转重建，冷列表列随会话重新 checkpoint 逐步回归。
+- 同样的损坏发生在 `workspace.json` 上仍大声拒绝启动。
+- facility 测试覆盖：每个损坏类恰好重置一次 `'reset'` 域；非损坏失败在 `'reset'` 域上保持大声；`'reject'` 域传播一切失败；`destroy` 在两个出厂后端上都移除介质。
+
+## Risks
+
+- **错误分类失误导致自动删除健康文件。** 由封闭的损坏类清单缓解：重置只在三个确定性解析期代码上触发；ENOENT 本来就是「空 unit」,一切 I/O 错误（EACCES、EIO）大声传播。单发重试把爆炸半径限定为每次 open 至多一删。
+- **根迁移改变既有 checkout 的查找位置。** 在 pre-release 立场下接受（后端拒绝旧格式、无外部消费者）；上文为在乎 per-cwd `workspace.json` 内容的人记录了一次性手动搬移。
+- **`destroy` 是存储 seam 上新增的破坏性原语。** 唯一调用方是 facility 的声明重置路径；后端契约将其记档为 facility 专属,任何面向模型或面向用户的路径都触不到它。

AGENTS.md

@@ -89,7 +89,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 ## Conventions
 
 - Every npm package is `@deepseek-ai/dsh-<name>`; vendored packages keep upstream names and are `private: true`. `cordis` is a peerDependency (+ dev) of every harness package.
-- ESM everywhere (`"type": "module"`). Cross-package imports use package names; in-package relative imports include `.ts`. CI subprocesses that boot examples or Cordis configs run built `lib/` under plain Node; only explicit source-path regressions use tsx ([testing policy](docs/testing.md#test-subprocess-launch-modes)).
+- ESM everywhere (`"type": "module"`). Cross-package imports use package names; in-package relative imports include `.ts`. Config subprocesses run built `lib/` under plain Node; source regressions use their declared launcher ([testing policy](docs/testing.md#test-subprocess-launch-modes)). CLI source-launch code and every module it reaches must support Node `--experimental-transform-types`: use `import type` for erased bindings and native ESM exports, with no TSX/JSX or tsx/esbuild-only transforms. TUI/Web `cordis.yml` bare plugins must appear in their resolver manifest's `dependencies`; `verify-cordis-config` enforces the [source-launch contract](.agents/notes/implemented/architecture/2026-07-28-dsh-native-typescript-source-launch.md).
 - **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer.
 - **Runtime invariants assert owned relationships.** Check authoritative event streams or mutable data, not service or method presence, plugin metadata or effects, or fixed pure examples. If a package has no plausible relationship, an explained empty companion is correct ([package contract](packages/AGENTS.md)).
 - **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`; scoped keys absent from payloads need `@dshScopeScan unsupported`. Public service methods document parameters and non-void returns.

apps/cli/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: 42d2a9641cf5d497c9aae45d9f60fce4498addb9
-README.zh.md: 0a62f8bb72e2cf2dbe045d28b81768bf4df800de
+#   pnpm run verify-translation-pairing --write apps/cli/README.md
+README.md: 13a80b1d0e0105bc0c30c019209b2e0295b7bef9
+README.zh.md: 2a5d9c15c57351ef03ebe60a5cdf90f0d0c8f18b

apps/cli/README.md

@@ -26,4 +26,6 @@ Symlink the source-running launcher onto your PATH; it resolves the checkout thr
 ln -sf "$(pwd)/bin/dsh" ~/.local/bin/dsh
 ```
 
+Source launches run `apps/cli/src/bin.ts` through Node's `--experimental-transform-types`; `scripts/tspath-loader.ts` only projects tsconfig `paths` into module resolution and does not transform code. Every module reachable from the CLI source entry follows Node's transform-types contract: erased bindings use `import type`, exports use native ESM, and the graph contains no TSX/JSX or transforms that only tsx/esbuild provides. The loader reads `TSX_TSCONFIG_PATH` when set (relative paths resolve from the invoking cwd), otherwise the repository's root tsconfig, using the root TypeScript development tool rather than an application dependency. It maps a workspace import only for a package self-reference or a declared runtime dependency. The TUI configs resolve bare plugins through `examples/package.json`, while the Web/headless `cordis.yml` resolves them through this package's `dependencies`; `verify-cordis-config` requires every configured bare plugin to be declared, while allowing unrelated dependencies.
+
 `pnpm run dsh` runs the same entry from the repo root and forwards arguments directly, for example `pnpm run dsh -p "task"`. The built form (`lib/bin.js`, via `pnpm run build`) boots the same config under plain Node.

apps/cli/README.zh.md

@@ -26,4 +26,6 @@ Web 和无头界面启动同一个共享组合（`cordis.yml`）：两者都将
 ln -sf "$(pwd)/bin/dsh" ~/.local/bin/dsh
 ```
 
+源码启动会通过 Node 的 `--experimental-transform-types` 运行 `apps/cli/src/bin.ts`；`scripts/tspath-loader.ts` 只会将 tsconfig 的 `paths` 映射投射到模块解析中，而不会转换代码。从 CLI 源码入口可达的每个模块都遵守 Node transform-types 契约：会被擦除的绑定使用 `import type`，export 使用原生 ESM，整个依赖图不含 TSX/JSX，也不依赖仅由 tsx/esbuild 提供的转换。设置 `TSX_TSCONFIG_PATH` 时，loader 会读取该路径（相对路径从调用方的 cwd 解析），否则读取仓库根 tsconfig；它使用根目录的 TypeScript 开发工具，而不是应用依赖。仅当 workspace import 是包自身引用或已声明的运行时依赖时，loader 才会映射该 import。TUI 配置通过 `examples/package.json` 解析裸插件，而 Web／无头 `cordis.yml` 则通过本包的 `dependencies` 解析；`verify-cordis-config` 要求每个已配置的裸插件均已声明，同时允许存在无关依赖。
+
 `pnpm run dsh` 从仓库根目录运行同一入口并直接转发参数，例如 `pnpm run dsh -p "task"`。构建形式（`lib/bin.js`，通过 `pnpm run build`）会在普通 Node 下启动同一配置。

apps/cli/cordis.yml

@@ -116,6 +116,16 @@
 - id: workspace
   name: '@deepseek-ai/dsh-workspace'
 
+# Persisted projection cache: durable per-session checkpoints of every
+# registered projection unit (json backend → ./.storages/session_projcache.json,
+# beside workspace.json), throttled between the two mandatory points
+# (turn/end + detach), serving cold listings without full-log loads.
+- id: session-projection-cache
+  name: '@deepseek-ai/dsh-session-projection-cache'
+  config:
+    writeEveryEvents: 200
+    writeIntervalMs: 5000
+
 # Managed child-process groups for the bash executor (spawn/kill/output plumbing).
 - id: subprocess
   name: '@deepseek-ai/dsh-subprocess-local'

apps/cli/package.json

@@ -57,6 +57,7 @@
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
     "@deepseek-ai/dsh-session-projection": "workspace:^",
+    "@deepseek-ai/dsh-session-projection-cache": "workspace:^",
     "@deepseek-ai/dsh-session-title": "workspace:^",
     "@deepseek-ai/dsh-session-title-first-message-llm": "workspace:^",
     "@deepseek-ai/dsh-skill": "workspace:^",

apps/cli/src/tsconfig-paths-loader.ts

@@ -0,0 +1,216 @@
+/**
+ * Node module resolve hook for the `dsh` source launcher. It projects the root
+ * tsconfig `paths` map into Node resolution while leaving all TypeScript syntax
+ * handling to Node's native transform-types runtime.
+ * @module @deepseek-ai/dsh/tsconfig-paths-loader
+ */
+
+import { readFile, stat } from 'node:fs/promises'
+import { dirname, extname, join, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import type { ResolveHookContext, ResolveFnOutput } from 'node:module'
+import ts from 'typescript'
+
+interface LoaderData {
+  tsconfigPath: string
+}
+
+interface PackageManifest {
+  name?: string
+  dependencies?: Record<string, string>
+  optionalDependencies?: Record<string, string>
+  peerDependencies?: Record<string, string>
+}
+
+interface PathRule {
+  pattern: string
+  prefix: string
+  suffix: string
+  targets: readonly string[]
+}
+
+interface PathsCompilerOptions {
+  readonly baseUrl?: string
+  readonly paths?: ts.MapLike<string[]>
+  readonly pathsBasePath?: string
+}
+
+// Node's native TypeScript transform cannot parse JSX, so `.tsx` is excluded.
+const SOURCE_EXTENSIONS = ['.ts', '.mts', '.cts'] as const
+
+/**
+ * Resolve package imports through one parsed tsconfig paths table.
+ *
+ * Manifest reads are process-scoped and memoized by path. Only matched source
+ * aliases enter the cache, bounding it to directories participating in source
+ * resolution.
+ */
+export class TsconfigPathsResolver {
+  private readonly rules: readonly PathRule[]
+  private readonly configDirectory: string
+  private readonly manifests = new Map<string, Promise<PackageManifest | undefined>>()
+
+  private constructor(configDirectory: string, paths: ts.MapLike<string[]>) {
+    this.configDirectory = configDirectory
+    this.rules = Object.entries(paths)
+      .map(([pattern, targets]) => {
+        const wildcard = pattern.indexOf('*')
+        return {
+          pattern,
+          prefix: wildcard === -1 ? pattern : pattern.slice(0, wildcard),
+          suffix: wildcard === -1 ? '' : pattern.slice(wildcard + 1),
+          targets,
+        }
+      })
+      .sort((left, right) => {
+        const leftExact = left.pattern.includes('*') ? 0 : 1
+        const rightExact = right.pattern.includes('*') ? 0 : 1
+        return rightExact - leftExact || right.prefix.length - left.prefix.length || right.suffix.length - left.suffix.length
+      })
+  }
+
+  /**
+   * Parse a tsconfig including its `extends` chain.
+   * @param tsconfigPath Absolute tsconfig path supplying `compilerOptions.paths`.
+   * @returns A resolver backed by that path table.
+   */
+  static create(tsconfigPath: string): TsconfigPathsResolver {
+    let unrecoverable: ts.Diagnostic | undefined
+    const parsed = ts.getParsedCommandLineOfConfigFile(tsconfigPath, {}, {
+      ...ts.sys,
+      onUnRecoverableConfigFileDiagnostic(diagnostic) { unrecoverable = diagnostic },
+    })
+    if (parsed === undefined) {
+      const detail = unrecoverable === undefined
+        ? 'unknown configuration error'
+        : ts.flattenDiagnosticMessageText(unrecoverable.messageText, '\n')
+      throw new Error(`dsh source loader could not parse ${tsconfigPath}: ${detail}`)
+    }
+    const options = parsed.options as PathsCompilerOptions
+    const paths = options.paths
+    if (paths === undefined) throw new Error(`dsh source loader requires compilerOptions.paths in ${tsconfigPath}`)
+    const configDirectory = options.baseUrl ?? options.pathsBasePath ?? dirname(tsconfigPath)
+    return new TsconfigPathsResolver(configDirectory, paths)
+  }
+
+  /**
+   * Resolve one bare package specifier to a source file when the importing
+   * package (or config-directory owner) declares that package at runtime.
+   * @param specifier Module specifier passed to Node.
+   * @param parentURL Importing file or Loader config-directory URL.
+   * @returns Source file URL, or `undefined` when normal Node resolution owns the request.
+   */
+  async resolve(specifier: string, parentURL: string | undefined): Promise<string | undefined> {
+    const packageName = packageNameFromSpecifier(specifier)
+    if (packageName === undefined || parentURL === undefined || !parentURL.startsWith('file:')) return undefined
+    const matched = this.match(specifier)
+    if (matched === undefined) return undefined
+    const configParent = parentURL.endsWith('/')
+    const parentPath = fileURLToPath(parentURL)
+    const startDirectory = configParent ? parentPath : dirname(parentPath)
+    if (!await this.isDeclaredRuntimeDependency(startDirectory, packageName, configParent)) return undefined
+
+    for (const target of matched.targets) {
+      const substituted = target.replace('*', matched.wildcard)
+      const candidate = await existingSourcePath(resolve(this.configDirectory, substituted))
+      if (candidate !== undefined) return pathToFileURL(candidate).href
+    }
+    return undefined
+  }
+
+  private match(specifier: string): { targets: readonly string[]; wildcard: string } | undefined {
+    for (const rule of this.rules) {
+      if (!rule.pattern.includes('*')) {
+        if (specifier === rule.pattern) return { targets: rule.targets, wildcard: '' }
+        continue
+      }
+      if (!specifier.startsWith(rule.prefix) || !specifier.endsWith(rule.suffix)) continue
+      const wildcard = specifier.slice(rule.prefix.length, specifier.length - rule.suffix.length)
+      return { targets: rule.targets, wildcard }
+    }
+    return undefined
+  }
+
+  private async isDeclaredRuntimeDependency(
+    startDirectory: string,
+    packageName: string,
+    searchAncestors: boolean,
+  ): Promise<boolean> {
+    for (let directory = startDirectory; ; directory = dirname(directory)) {
+      const manifest = await this.readManifest(join(directory, 'package.json'))
+      if (manifest !== undefined) {
+        if (declaresRuntimeDependency(manifest, packageName)) return true
+        if (!searchAncestors) return false
+      }
+      const parent = dirname(directory)
+      if (parent === directory) return false
+    }
+  }
+
+  private readManifest(path: string): Promise<PackageManifest | undefined> {
+    let pending = this.manifests.get(path)
+    if (pending !== undefined) return pending
+    pending = readFile(path, 'utf8').then(
+      content => JSON.parse(content) as PackageManifest,
+      (error: unknown) => {
+        if (error instanceof Error && (error as NodeJS.ErrnoException).code === 'ENOENT') return undefined
+        throw error
+      },
+    )
+    this.manifests.set(path, pending)
+    return pending
+  }
+}
+
+let resolver: TsconfigPathsResolver | undefined
+
+/** Initialize the hook worker from the source-launch preloader. */
+export function initialize(data: LoaderData): void {
+  resolver = TsconfigPathsResolver.create(data.tsconfigPath)
+}
+
+/** Resolve declared workspace packages to source and delegate every other request to Node. */
+export async function resolveHook(
+  specifier: string,
+  context: ResolveHookContext,
+  nextResolve: (specifier: string, context: ResolveHookContext) => Promise<ResolveFnOutput>,
+): Promise<ResolveFnOutput> {
+  const url = await resolver?.resolve(specifier, context.parentURL)
+  return url === undefined ? nextResolve(specifier, context) : { url, shortCircuit: true }
+}
+
+// Node customization hooks discover this exact export name.
+export { resolveHook as resolve }
+
+function packageNameFromSpecifier(specifier: string): string | undefined {
+  if (specifier.startsWith('.') || specifier.startsWith('/') || /^[a-z][a-z+.-]*:/i.test(specifier)) {
+    return undefined
+  }
+  const segments = specifier.split('/')
+  return specifier.startsWith('@')
+    ? segments.length >= 2 ? `${segments[0]}/${segments[1]}` : undefined
+    : segments[0] || undefined
+}
+
+function declaresRuntimeDependency(manifest: PackageManifest, packageName: string): boolean {
+  return manifest.name === packageName
+    || packageName in (manifest.dependencies ?? {})
+    || packageName in (manifest.optionalDependencies ?? {})
+    || packageName in (manifest.peerDependencies ?? {})
+}
+
+async function existingSourcePath(base: string): Promise<string | undefined> {
+  const extension = extname(base)
+  if (extension === '.tsx') return undefined
+  const candidates = extension === ''
+    ? [base, ...SOURCE_EXTENSIONS.map(extension => `${base}${extension}`), ...SOURCE_EXTENSIONS.map(extension => join(base, `index${extension}`))]
+    : [base]
+  for (const candidate of candidates) {
+    try {
+      if ((await stat(candidate)).isFile()) return candidate
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    }
+  }
+  return undefined
+}

apps/cli/tests/tsconfig-paths-loader.spec.ts

@@ -0,0 +1,180 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import type { ResolveFnOutput, ResolveHookContext } from 'node:module'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { initialize, resolveHook, TsconfigPathsResolver } from '../src/tsconfig-paths-loader.ts'
+
+class ResolverFixture {
+  readonly root = mkdtempSync(join(tmpdir(), 'dsh-tsconfig-paths-'))
+
+  path(relativePath: string): string {
+    return join(this.root, relativePath)
+  }
+
+  write(relativePath: string, content = 'export {}\n'): string {
+    const path = this.path(relativePath)
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, content)
+    return path
+  }
+
+  writeJson(relativePath: string, value: unknown): string {
+    return this.write(relativePath, `${JSON.stringify(value)}\n`)
+  }
+
+  createResolver(paths: Record<string, string[]>): TsconfigPathsResolver {
+    const tsconfigPath = this.writeJson('tsconfig.json', { compilerOptions: { paths } })
+    return TsconfigPathsResolver.create(tsconfigPath)
+  }
+
+  parentURL(relativePath = 'consumer/src/nested/index.ts'): string {
+    return pathToFileURL(this.path(relativePath)).href
+  }
+
+  dispose(): void {
+    rmSync(this.root, { recursive: true, force: true })
+  }
+}
+
+const fixtures: ResolverFixture[] = []
+
+function fixture(): ResolverFixture {
+  const value = new ResolverFixture()
+  fixtures.push(value)
+  return value
+}
+
+afterEach(() => {
+  for (const value of fixtures.splice(0)) value.dispose()
+})
+
+describe('TsconfigPathsResolver', () => {
+  it('orders exact, longer-prefix, and longer-suffix path rules', async () => {
+    const files = fixture()
+    files.writeJson('consumer/package.json', {
+      dependencies: {
+        '@scope/feature-name': '*',
+        '@scope/feature-other': '*',
+        '@scope/plain-suffix': '*',
+      },
+    })
+    files.write('targets/exact.ts')
+    files.write('targets/prefix/other.ts')
+    files.write('targets/generic/feature-other.ts')
+    files.write('targets/suffix/plain.ts')
+    files.write('targets/generic/plain-suffix.ts')
+    const resolver = files.createResolver({
+      '@scope/*': ['./targets/generic/*'],
+      '@scope/*-suffix': ['./targets/suffix/*'],
+      '@scope/feature-*': ['./targets/prefix/*'],
+      '@scope/feature-name': ['./targets/exact.ts'],
+    })
+
+    await expect(resolver.resolve('@scope/feature-name', files.parentURL()))
+      .resolves.toBe(pathToFileURL(files.path('targets/exact.ts')).href)
+    await expect(resolver.resolve('@scope/feature-other', files.parentURL()))
+      .resolves.toBe(pathToFileURL(files.path('targets/prefix/other.ts')).href)
+    await expect(resolver.resolve('@scope/plain-suffix', files.parentURL()))
+      .resolves.toBe(pathToFileURL(files.path('targets/suffix/plain.ts')).href)
+  })
+
+  it('resolves only self-references and runtime dependencies from the nearest ancestor manifest', async () => {
+    const files = fixture()
+    files.writeJson('consumer/package.json', {
+      name: 'self-package',
+      dependencies: { dependency: '*' },
+      optionalDependencies: { optional: '*' },
+      peerDependencies: { peer: '*' },
+    })
+    for (const name of ['self-package', 'dependency', 'optional', 'peer', 'undeclared']) {
+      files.write(`targets/${name}.ts`)
+    }
+    const resolver = files.createResolver(Object.fromEntries(
+      ['self-package', 'dependency', 'optional', 'peer', 'undeclared']
+        .map(name => [name, [`./targets/${name}`]]),
+    ))
+
+    for (const name of ['self-package', 'dependency', 'optional', 'peer']) {
+      await expect(resolver.resolve(name, files.parentURL()))
+        .resolves.toBe(pathToFileURL(files.path(`targets/${name}.ts`)).href)
+    }
+    await expect(resolver.resolve('undeclared', files.parentURL())).resolves.toBeUndefined()
+  })
+
+  it('probes native TypeScript extensions and index files but excludes TSX and missing targets', async () => {
+    const files = fixture()
+    const names = ['plain-ts', 'module-mts', 'common-cts', 'directory', 'tsx-implicit', 'tsx-explicit', 'missing']
+    files.writeJson('consumer/package.json', {
+      dependencies: Object.fromEntries(names.map(name => [name, '*'])),
+    })
+    files.write('targets/plain.ts')
+    files.write('targets/module.mts')
+    files.write('targets/common.cts')
+    files.write('targets/directory/index.ts')
+    files.write('targets/component.tsx')
+    const resolver = files.createResolver({
+      'plain-ts': ['./targets/plain'],
+      'module-mts': ['./targets/module'],
+      'common-cts': ['./targets/common'],
+      'directory': ['./targets/directory'],
+      'tsx-implicit': ['./targets/component'],
+      'tsx-explicit': ['./targets/component.tsx'],
+      'missing': ['./targets/missing'],
+    })
+
+    for (const [name, target] of [
+      ['plain-ts', 'targets/plain.ts'],
+      ['module-mts', 'targets/module.mts'],
+      ['common-cts', 'targets/common.cts'],
+      ['directory', 'targets/directory/index.ts'],
+    ] as const) {
+      await expect(resolver.resolve(name, files.parentURL()))
+        .resolves.toBe(pathToFileURL(files.path(target)).href)
+    }
+    await expect(resolver.resolve('tsx-implicit', files.parentURL())).resolves.toBeUndefined()
+    await expect(resolver.resolve('tsx-explicit', files.parentURL())).resolves.toBeUndefined()
+    await expect(resolver.resolve('missing', files.parentURL())).resolves.toBeUndefined()
+  })
+
+  it('anchors inherited paths at the config that declared them', async () => {
+    const files = fixture()
+    files.writeJson('consumer/package.json', { dependencies: { custom: '*' } })
+    files.write('targets/custom.ts')
+    files.writeJson('base.json', { compilerOptions: { paths: { custom: ['./targets/custom'] } } })
+    const customTsconfig = files.writeJson('configs/custom.json', { extends: '../base.json' })
+    const resolver = TsconfigPathsResolver.create(customTsconfig)
+
+    await expect(resolver.resolve('custom', files.parentURL()))
+      .resolves.toBe(pathToFileURL(files.path('targets/custom.ts')).href)
+  })
+
+  it('short-circuits matched aliases and delegates unsupported schemes or unmatched requests', async () => {
+    const files = fixture()
+    files.writeJson('consumer/package.json', { dependencies: { matched: '*' } })
+    const target = files.write('targets/matched.ts')
+    const tsconfigPath = files.writeJson('tsconfig.json', {
+      compilerOptions: { paths: { matched: ['./targets/matched'] } },
+    })
+    initialize({ tsconfigPath })
+    const context: ResolveHookContext = {
+      conditions: [],
+      importAttributes: {},
+      parentURL: files.parentURL(),
+    }
+    const nextResolve = vi.fn(async (
+      specifier: string,
+      _context: ResolveHookContext,
+    ): Promise<ResolveFnOutput> => ({ url: `next:${specifier}` }))
+
+    await expect(resolveHook('matched', context, nextResolve))
+      .resolves.toEqual({ url: pathToFileURL(target).href, shortCircuit: true })
+    expect(nextResolve).not.toHaveBeenCalled()
+
+    for (const specifier of ['unmatched', 'node:fs', 'data:text/javascript,export default 1', 'https://example.test/mod.ts']) {
+      await expect(resolveHook(specifier, context, nextResolve)).resolves.toEqual({ url: `next:${specifier}` })
+      expect(nextResolve).toHaveBeenLastCalledWith(specifier, context)
+    }
+  })
+})

bin/dsh

@@ -1,7 +1,7 @@
 #!/bin/sh
-# dsh launcher: runs the apps/cli `dsh` bin FROM SOURCE with this checkout's
-# tsx, so a symlink from anywhere (e.g. ~/.local/bin/dsh) always executes the
-# current working tree — code changes apply on the next launch, no build step.
+# dsh launcher: runs the apps/cli `dsh` bin FROM SOURCE through Node's native
+# TypeScript transform, so a symlink from anywhere (e.g. ~/.local/bin/dsh)
+# always executes the current working tree without a build step.
 set -eu
 
 # Resolve symlink chains without readlink -f (not on every macOS).
@@ -15,7 +15,8 @@ while [ -L "$script" ]; do
 done
 root=$(CDPATH='' cd -- "$(dirname -- "$script")/.." && pwd)
 
-# tsx is imported by absolute path because bare `--import tsx` resolves from
-# the invoking cwd, which is usually outside this repository.
-export TSX_TSCONFIG_PATH="$root/tsconfig.json"
-exec node --import "$root/node_modules/tsx/dist/loader.mjs" "$root/apps/cli/src/bin.ts" "$@"
+# The preloader projects this checkout's tsconfig paths into Node resolution;
+# TypeScript transformation itself remains Node-owned (no tsx/esbuild hook).
+exec node --experimental-transform-types \
+  --import "$root/scripts/tspath-loader.ts" \
+  "$root/apps/cli/src/bin.ts" "$@"

docs/capability-seams.md

@@ -77,6 +77,8 @@ flowchart LR
   pkg_session_projection["session-projection"]
   svc_sessionProjections["ctx.sessionProjections<br/>Session projection units"]
   pkg_host_apiproxy["host-apiproxy"]
+  pkg_session_projection_cache["session-projection-cache"]
+  svc_sessionProjectionCache["ctx.sessionProjectionCache<br/>Persisted projection cache"]
   svc_tui["ctx.tui<br/>Mounted-terminal interaction service"]
   pkg_skill["skill"]
   svc_skills["ctx.skills<br/>Skill provider registry"]
@@ -184,6 +186,7 @@ flowchart LR
   pkg_session_persistence_jsonl --> svc_sessionPersistence
   pkg_session_persistence_sqlite --> svc_sessionPersistence
   pkg_session_projection --> svc_sessionProjections
+  pkg_session_projection_cache --> svc_sessionProjectionCache
   pkg_session_query --> svc_sessionQuery
   pkg_session_query_sqlite --> svc_sessionQuery
   pkg_session_reference --> svc_sessionReferences
@@ -261,6 +264,7 @@ flowchart LR
   svc_sessionPersistence --> pkg_session_query
   svc_sessionPersistence --> pkg_session_query_sqlite
   svc_sessionPersistence --> pkg_tool_bash
+  svc_sessionProjectionCache --> pkg_host_apiproxy
   svc_sessionProjections --> pkg_host_apiproxy
   svc_sessionProjections --> pkg_session_title
   svc_sessionProjections --> pkg_tool_todo
@@ -336,6 +340,7 @@ flowchart LR
 | `ctx.planMode` | `core` | [`plan-mode`](../packages/plan/plan-mode) | - | - | - | Folds logged plan/mode state, flushes user selections at turn boundaries, renders deployment-owned guidance, registers /plan, and keeps the plan-exit schema stable across transitions. |
 | `ctx.commands` | `core` | [`commands`](../packages/ui/commands) | - | [`tui`](../packages/ui/tui) | - | Plugins register direct human commands; TUI consumes the effective per-agent catalog without sending invocations to the model. |
 | `ctx.sessionProjections` | `core` | [`session-projection`](../packages/session-projection/session-projection) | - | [`tool-todo`](../packages/todo/tool-todo), [`session-title`](../packages/session-title/session-title), [`host-apiproxy`](../packages/host/apiproxy) | - | Domains register state-driven fold units; the eager drive keeps per-session watermark states and api-proxy serves baselines and pushes changed values. |
+| `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session-projection/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs. |
 | `ctx.tui` | `bundle` | [`tui`](../packages/ui/tui) | - | - | - | One TUI front door provides a FIFO overlay host; injected plugins receive caller-fiber ownership without access to pi-tui or terminal lifecycle state. |
 | `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
 | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`cli-demo`](../packages/examples/cli-demo), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`tui-demo`](../packages/examples/tui-demo) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |

docs/config-catalog.md

@@ -1048,6 +1048,27 @@ export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
 
 Source: [`packages/session-persistence/session-persistence-sqlite/src/index.ts:58`](../packages/session-persistence/session-persistence-sqlite/src/index.ts)
 
+## `@deepseek-ai/dsh-session-projection-cache`
+
+Requires: `storageDomain` · `sessionProjections` · `sessionPersistence` · `sessions`
+
+```ts config-catalog
+/**
+ * Plugin config. Both throttle triggers are deployment choices with no
+ * universally correct value, so the composition states them explicitly
+ * (cordis.yml); the two mandatory write points (`turn/end` and session
+ * disposal) are policy, not tunables, and always fire.
+ */
+export interface Config {
+  /** Committed events per session that force a durable checkpoint write between mandatory points. */
+  writeEveryEvents: number
+  /** Longest time (milliseconds) a dirty checkpoint may stay unwritten between mandatory points. */
+  writeIntervalMs: number
+}
+```
+
+Source: [`packages/session-projection/session-projection-cache/src/index.ts:42`](../packages/session-projection/session-projection-cache/src/index.ts)
+
 ## `@deepseek-ai/dsh-session-query-sqlite`
 
 Requires: `sessions`
@@ -2209,6 +2230,7 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 - `@deepseek-ai/dsh-agent-loop-testkit` ([`packages/support/agent-loop-testkit/src/index.ts`](../packages/support/agent-loop-testkit/src/index.ts))
 - `@deepseek-ai/dsh-app-boot` ([`packages/ui/app-boot/src/index.ts`](../packages/ui/app-boot/src/index.ts))
 - `@deepseek-ai/dsh-brand` ([`packages/util/brand/src/index.ts`](../packages/util/brand/src/index.ts))
+- `@deepseek-ai/dsh-client-test-runtime` ([`packages/client/test-runtime/src/index.ts`](../packages/client/test-runtime/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-primitives` ([`packages/client/ui-primitives/src/index.ts`](../packages/client/ui-primitives/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-slots` ([`packages/client/ui-slots/src/index.ts`](../packages/client/ui-slots/src/index.ts))
 - `@deepseek-ai/dsh-client-web` ([`packages/client/web/src/index.ts`](../packages/client/web/src/index.ts))

docs/cordis-catalog/core/context.md

@@ -256,7 +256,7 @@ Read a service from the store without the inject requirement.
 
 **Returns** the service value, or `undefined` when not (yet) provided.
 
-[Source](../../../vendor/cordis/src/reflect.ts#L16)
+[Source](../../../vendor/cordis/src/reflect.ts#L17)
 
 ### ctx.set(name, value)
 
@@ -281,7 +281,7 @@ Only the fiber that provided the service may set it; setting an unprovided name
 - `name` — the service name.
 - `value` — the new service value.
 
-[Source](../../../vendor/cordis/src/reflect.ts#L28)
+[Source](../../../vendor/cordis/src/reflect.ts#L29)
 
 ### ctx.provide(name, value)
 
@@ -311,7 +311,7 @@ The service becomes visible to dependents in the same isolation scope once the f
 
 **Returns** a disposer that unregisters the service.
 
-[Source](../../../vendor/cordis/src/reflect.ts#L43)
+[Source](../../../vendor/cordis/src/reflect.ts#L44)
 
 ### ctx.accessor(name, options)
 
@@ -335,7 +335,7 @@ The accessor is removed when the current fiber unloads. Throws if the name is al
 - `name` — the context property name.
 - `options` — the `get` hook and optional `set` hook.
 
-[Source](../../../vendor/cordis/src/reflect.ts#L55)
+[Source](../../../vendor/cordis/src/reflect.ts#L56)
 
 ### ctx.mixin(name, mixins)
 
@@ -361,4 +361,4 @@ Each mixed-in key becomes an accessor that forwards to the service (binding meth
 - `name` — the context property holding the source service.
 - `mixins` — keys to forward, or a source-key → ctx-key map.
 
-[Source](../../../vendor/cordis/src/reflect.ts#L66)
+[Source](../../../vendor/cordis/src/reflect.ts#L67)

docs/cordis-catalog/core/events.md

@@ -26,7 +26,7 @@ Dispatch an event, running all listeners concurrently.
 
 **Returns** a promise resolving once every listener has settled.
 
-[Source](../../../vendor/cordis/src/events.ts#L43)
+[Source](../../../vendor/cordis/src/events.ts#L44)
 
 ### ctx.emit(name, ...args)
 
@@ -46,7 +46,7 @@ Dispatch an event synchronously, ignoring listener return values.
 - `name` — the event name.
 - `args` — arguments passed to every listener.
 
-[Source](../../../vendor/cordis/src/events.ts#L52)
+[Source](../../../vendor/cordis/src/events.ts#L53)
 
 ### ctx.serial(name, ...args)
 
@@ -69,7 +69,7 @@ Dispatch an event, awaiting listeners in order until one bails.
 
 **Returns** the first bail value (non-null, non-false, non-undefined), if any.
 
-[Source](../../../vendor/cordis/src/events.ts#L62)
+[Source](../../../vendor/cordis/src/events.ts#L63)
 
 ### ctx.bail(name, ...args)
 
@@ -92,7 +92,7 @@ Dispatch an event, calling listeners in order until one bails.
 
 **Returns** the first bail value (non-null, non-false, non-undefined), if any.
 
-[Source](../../../vendor/cordis/src/events.ts#L72)
+[Source](../../../vendor/cordis/src/events.ts#L73)
 
 ### ctx.waterfall(name, ...args)
 
@@ -120,7 +120,7 @@ Each listener wraps the rest of the chain: calling `next()` invokes the next lis
 
 **Returns** the outermost listener's return value.
 
-[Source](../../../vendor/cordis/src/events.ts#L85)
+[Source](../../../vendor/cordis/src/events.ts#L86)
 
 ### ctx.on(name, listener, options?)
 
@@ -144,7 +144,7 @@ Register an event listener owned by the current fiber.
 
 **Returns** a disposer removing the listener; `true` if it was still registered.
 
-[Source](../../../vendor/cordis/src/events.ts#L96)
+[Source](../../../vendor/cordis/src/events.ts#L97)
 
 ### ctx.once(name, listener, options?)
 
@@ -168,7 +168,7 @@ Same as `on()`, but the listener disposes itself after its first call.
 
 **Returns** a disposer removing the listener; `true` if it was still registered.
 
-[Source](../../../vendor/cordis/src/events.ts#L105)
+[Source](../../../vendor/cordis/src/events.ts#L106)
 
 ## EventOptions
 
@@ -184,7 +184,7 @@ interface EventOptions {
 }
 ```
 
-[Source](../../../vendor/cordis/src/events.ts#L111)
+[Source](../../../vendor/cordis/src/events.ts#L112)
 
 ## DispatchMode
 
@@ -204,4 +204,4 @@ Event dispatch strategy used by the event service.
 type DispatchMode = 'emit' | 'parallel' | 'serial' | 'bail' | 'waterfall'
 ```
 
-[Source](../../../vendor/cordis/src/events.ts#L31)
+[Source](../../../vendor/cordis/src/events.ts#L32)

docs/cordis-catalog/core/fiber.md

@@ -34,7 +34,7 @@ Register a cleanup-aware effect on this fiber.
 
 **Returns** a disposer that tears the effect down and settles once done.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L419)
+[Source](../../../vendor/cordis/src/fiber.ts#L420)
 
 ### ctx.fiber
 
@@ -45,7 +45,7 @@ fiber: Fiber
 
 The fiber (plugin runtime instance) that owns this context.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L11)
+[Source](../../../vendor/cordis/src/fiber.ts#L12)
 
 ## The Fiber class
 
@@ -53,7 +53,7 @@ Runtime instance of one plugin application.
 
 A fiber tracks dependency state, validated config, lifecycle effects, and cleanup for the plugin context returned by `ctx.plugin()`.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L183)
+[Source](../../../vendor/cordis/src/fiber.ts#L184)
 
 ### fiber.uid
 
@@ -64,7 +64,7 @@ public uid: number | null
 
 Unique id within the registry; 0 for the root fiber, `null` once disposed.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L185)
+[Source](../../../vendor/cordis/src/fiber.ts#L186)
 
 ### fiber.ctx
 
@@ -75,7 +75,7 @@ public readonly ctx: Context
 
 The context this fiber's plugin runs in (extends the parent context).
 
-[Source](../../../vendor/cordis/src/fiber.ts#L187)
+[Source](../../../vendor/cordis/src/fiber.ts#L188)
 
 ### fiber.config
 
@@ -86,7 +86,7 @@ public config: any
 
 The validated plugin config (updated by `update()`).
 
-[Source](../../../vendor/cordis/src/fiber.ts#L189)
+[Source](../../../vendor/cordis/src/fiber.ts#L190)
 
 ### fiber.state
 
@@ -97,7 +97,7 @@ public state
 
 Current lifecycle state; transitions emit `internal/status`.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L191)
+[Source](../../../vendor/cordis/src/fiber.ts#L192)
 
 ### fiber.dispose
 
@@ -108,7 +108,7 @@ public readonly dispose: () => Promise<void>
 
 Dispose this fiber: unload the plugin, then settle once cleanup finished.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L193)
+[Source](../../../vendor/cordis/src/fiber.ts#L194)
 
 ### fiber.store
 
@@ -119,7 +119,7 @@ public store: Dict<Impl> | undefined
 
 Snapshot of required service implementations while loaded; `undefined` otherwise.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L195)
+[Source](../../../vendor/cordis/src/fiber.ts#L196)
 
 ### fiber.inertia
 
@@ -130,7 +130,7 @@ public inertia: Promise<void> | undefined
 
 The in-flight load/unload transition, if one is currently running.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L197)
+[Source](../../../vendor/cordis/src/fiber.ts#L198)
 
 ### fiber.name
 
@@ -141,7 +141,7 @@ get name()
 
 The plugin's display name, inherited from the nearest named ancestor, else `'root'`.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L340)
+[Source](../../../vendor/cordis/src/fiber.ts#L341)
 
 ### fiber.assertActive()
 
@@ -159,7 +159,7 @@ Throw if the fiber has already been disposed.
 
 **Returns** nothing when the fiber is still active.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L355)
+[Source](../../../vendor/cordis/src/fiber.ts#L356)
 
 ### fiber.effect(execute, label?)
 
@@ -190,7 +190,7 @@ Register a cleanup-aware effect on this fiber.
 
 **Returns** a disposer that tears the effect down and settles once done.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L419)
+[Source](../../../vendor/cordis/src/fiber.ts#L420)
 
 ### fiber.getEffects()
 
@@ -207,7 +207,7 @@ Return metadata for currently registered effects.
 
 **Returns** one `EffectMeta` tree per labeled live effect.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L572)
+[Source](../../../vendor/cordis/src/fiber.ts#L573)
 
 ### fiber.await()
 
@@ -225,7 +225,7 @@ Wait for current lifecycle work and rethrow startup errors.
 
 **Returns** this fiber, once it has settled into a stable state.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L701)
+[Source](../../../vendor/cordis/src/fiber.ts#L702)
 
 ### fiber.restart()
 
@@ -243,7 +243,7 @@ Dispose and immediately reload this plugin with its current config.
 
 **Returns** a promise resolving once the reload settled.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L715)
+[Source](../../../vendor/cordis/src/fiber.ts#L716)
 
 ### fiber.update(config, noSave?)
 
@@ -271,7 +271,7 @@ Runs the `internal/update` waterfall first, so update hooks (and HMR) can veto o
 
 **Returns** nothing; the restart runs behind the `internal/update` waterfall.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L733)
+[Source](../../../vendor/cordis/src/fiber.ts#L734)
 
 ## Effect
 
@@ -292,7 +292,7 @@ type Effect<T = any> =
   | AsyncEffect<T>
 ```
 
-[Source](../../../vendor/cordis/src/fiber.ts#L82)
+[Source](../../../vendor/cordis/src/fiber.ts#L83)
 
 ## Disposable
 
@@ -310,7 +310,7 @@ Disposers run in reverse registration order when the owning fiber unloads; they
 type Disposable<T = any> = () => T
 ```
 
-[Source](../../../vendor/cordis/src/fiber.ts#L73)
+[Source](../../../vendor/cordis/src/fiber.ts#L74)
 
 ## EffectMeta
 
@@ -326,7 +326,7 @@ interface EffectMeta {
 }
 ```
 
-[Source](../../../vendor/cordis/src/fiber.ts#L95)
+[Source](../../../vendor/cordis/src/fiber.ts#L96)
 
 ## CordisError
 
@@ -352,7 +352,7 @@ namespace CordisError {
 }
 ```
 
-[Source](../../../vendor/cordis/src/fiber.ts#L156)
+[Source](../../../vendor/cordis/src/fiber.ts#L157)
 
 ## ValidationError
 
@@ -372,4 +372,4 @@ class ValidationError extends TypeError {
 }
 ```
 
-[Source](../../../vendor/cordis/src/fiber.ts#L18)
+[Source](../../../vendor/cordis/src/fiber.ts#L19)

docs/cordis-catalog/core/registry.md

@@ -30,7 +30,7 @@ Shorthand for `ctx.plugin({ inject, apply: callback })`: the callback is unloade
 
 **Returns** the fiber; awaiting it settles once loading finished.
 
-[Source](../../../vendor/cordis/src/registry.ts#L175)
+[Source](../../../vendor/cordis/src/registry.ts#L176)
 
 ### ctx.plugin(plugin, ...args)
 
@@ -53,7 +53,7 @@ Load a plugin in the current context.
 
 **Returns** the fiber; awaiting it settles once loading finished (rejecting on config or startup errors).
 
-[Source](../../../vendor/cordis/src/registry.ts#L184)
+[Source](../../../vendor/cordis/src/registry.ts#L185)
 
 ## Plugin
 
@@ -118,7 +118,7 @@ namespace Plugin {
 }
 ```
 
-[Source](../../../vendor/cordis/src/registry.ts#L91)
+[Source](../../../vendor/cordis/src/registry.ts#L92)
 
 ## Inject
 
@@ -149,4 +149,4 @@ namespace Inject {
 }
 ```
 
-[Source](../../../vendor/cordis/src/registry.ts#L18)
+[Source](../../../vendor/cordis/src/registry.ts#L19)

docs/cordis-catalog/services.md

@@ -1056,7 +1056,9 @@ abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>
  * A coordinator-backed cold load reserves the identity across storage awaits,
  * so concurrent publication of a same-id live Session rejects.
  * Returned events are detached, and every identified message is deeply
- * frozen; malformed identified messages reject before any stored event is returned.
+ * frozen. Coordinator-backed implementations upgrade supported pre-identity
+ * message events before validation; other malformed messages reject before
+ * any stored event is returned.
  * @param id - the persisted session to reload.
  * @returns the header and a log ending on a balanced `turn/end`.
  */
@@ -1066,14 +1068,34 @@ abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEven
  * Inspect a header and its valid contiguous stored prefix without repairing
  * a torn tail, closing an interrupted turn, or publishing coordinator state.
  * This read is serialized with writes for the same id and returns detached
- * values with deeply frozen identified messages, so observers cannot mutate message
- * identity/content or backend-owned state. Malformed identified messages reject.
+ * values with upgraded, deeply frozen identified messages, so observers
+ * cannot mutate message identity/content or backend-owned state. Other
+ * malformed messages reject.
  * @param id - the persisted session to inspect.
  * @param signal - optional cancellation for queued and backend read work.
  * @returns the header and valid stored event prefix exactly as observed.
  */
 abstract inspect(id: SessionId, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
 
+/**
+ * Read the stored events from `fromSeq` onward — the read-from-seq
+ * primitive for read models that resume from a watermark (e.g. a persisted
+ * projection cache folding only the tail past its checkpoint). Like
+ * {@link inspect} it is non-mutating and detached: no torn-tail truncation,
+ * no synthetic closers, no coordinator-state publication; only events from
+ * the valid contiguous stored prefix are returned, so a torn fragment never
+ * reaches the caller. `fromSeq` at or beyond the stored prefix returns an
+ * empty event list (never an error). Backends whose medium can seek by seq
+ * (SQLite) read only the suffix; sequential media (JSONL, both encodings)
+ * still parse the whole artifact and skip forward — the primitive bounds
+ * what is RETURNED and refolded, not every backend's physical read.
+ * @param id - the persisted session to read.
+ * @param fromSeq - first event seq to include; a non-negative safe integer.
+ * @param signal - optional cancellation for queued and backend read work.
+ * @returns the header and the stored events with `seq >= fromSeq`.
+ */
+abstract readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
+
 /**
  * Lightweight listing from metadata, without a full-log parse.
  * @param signal - optional cancellation for backend listing work.
@@ -1098,6 +1120,54 @@ Types: [SessionEvent](../core-data-structures/core.md) · [SessionHeader](../cor
 
 Source: [`packages/session-persistence/session-persistence/src/index.ts:52`](../../packages/session-persistence/session-persistence/src/index.ts)
 
+## `ctx.sessionProjectionCache` — `SessionProjectionCache`
+
+The persisted projection cache service. Opens the `session_projcache` domain at init, checkpoints live sessions on a throttled write-behind (count/interval triggers from Config) plus two mandatory points — `turn/end` and session disposal (the live-to-cold moment) — and serves the cold-read ladder: cached row, persistence `readFrom` tail, registry `restore`, durable write-back. Every durable write is fail-soft: failures log a warning and the cache self-heals on the next write or cold read.
+
+```ts cordis-catalog
+/**
+ * The zero-I/O listing read: whole values viewed straight from the stored
+ * rows (version-matching keys only), each cut carried with its watermark
+ * so a client value store can seed under its higher-seq-wins rule — as
+ * stale as the last durable checkpoint but never wrong, and never from an
+ * unrelated log (the caller's header is the identity witness). Fresher
+ * paths (the history tail baseline, {@link coldSnapshot}) supersede these
+ * values whenever a session is actually opened.
+ * @param meta - the listed session's header (identity witness; no log read).
+ * @returns the cut (`asOfSeq` = lowest served-row watermark), or
+ *   `undefined` when no usable row exists for this lifecycle.
+ */
+cachedSnapshot(meta: SessionHeader): ProjectionSnapshot | undefined
+
+/**
+ * Durably checkpoint one live session NOW (both mandatory points call
+ * this; tests and carriers may too). The registry cut is snapshotted at
+ * this boundary (states are live references), then the whole record is
+ * replaced. NOT fail-soft — callers on the fail-soft paths contain it.
+ * @param session - the live session to checkpoint.
+ * @returns resolution after durability and event emission.
+ */
+async write(session: Session): Promise<void>
+
+/**
+ * Cold-read one persisted session's projections with zero full-log load:
+ * cached rows + a persistence `readFrom` tail from the registry's restore
+ * floor, refolded by the registry and written back (fail-soft) so the next
+ * cold read starts closer. A cache row invalidated by a shrunk log
+ * (crash-repair truncation) triggers one full re-read from seq 0 — the
+ * ladder's slow rung, still no crash. Rejects when the session has no
+ * persisted log (`not found` from the persistence seam).
+ * @param id - the persisted session to read.
+ * @param signal - optional cancellation for the persistence reads.
+ * @returns the snapshot cut at the stored log end.
+ */
+async coldSnapshot(id: SessionId, signal?: AbortSignal): Promise<ProjectionSnapshot>
+```
+
+Types: [Session](../core-data-structures/session.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md)
+
+Source: [`packages/session-projection/session-projection-cache/src/index.ts:71`](../../packages/session-projection/session-projection-cache/src/index.ts)
+
 ## `ctx.sessionProjections` — `SessionProjectionRegistry`
 
 `ctx.sessionProjections`: the projection unit table and its drive. The service subscribes to `session/event` once; every committed event passes every registered unit's `apply` (eager drive), and a changed state reference notifies the change feed with the schema-validated view. Cells build lazily — a unit registered after events flowed, or a session older than the registry, folds `init` over the in-memory log on first touch (event or read). Registration is an effect (disposer rides the calling fiber): an unloaded domain plugin's key disappears from snapshots and clients read it as capability absence. Duplicate keys throw. Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected.
@@ -1130,11 +1200,81 @@ onChanged(listener: ProjectionChangeListener): () => void
  * @returns the snapshot; `values` is empty when no unit is registered.
  */
 snapshot(session: Session): ProjectionSnapshot
+
+/**
+ * State-level checkpoint of every registered unit for one session, read
+ * from the watermark cache (missing cells fold lazily over the in-memory
+ * log). This is the write side of the persisted projection cache: the
+ * returned rows are the `(key → {ver, seq, val})` part of the durable
+ * `(sessionId, key, ver, seq, val)`
+ * rows. Every `val` is a DETACHED structured clone — never the live
+ * cell reference: the watermark cache is this registry's authoritative
+ * mutable state, and a caller reaching the live reference could corrupt
+ * every subsequent snapshot and frame through it (plain JSON by the unit
+ * contract, so the clone is total).
+ * @param session - the session whose unit states are checkpointed.
+ * @returns one row per registered key; empty when no unit is registered.
+ */
+checkpoint(session: Session): ProjectionCheckpoint
+
+/**
+ * The stored seq a {@link restore} tail read over `checkpoint` must start
+ * at: one event BELOW the lowest usable watermark (a row is usable when
+ * its `ver` matches the live unit's `stateVersion`; an absent or mismatched row
+ * pulls the floor to `0` — that key must refold the full log). The
+ * one-below anchor is load-bearing: the tail then proves how far the
+ * stored log still extends, so {@link restore} can detect a log that
+ * shrank below a row's watermark (crash-repair truncation) instead of
+ * serving the stale row as current — an empty tail read from the anchor
+ * yields an end below every watermark and the restore rejects for a full
+ * re-read.
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
+ * @returns the seq to hand the persistence `readFrom`, or `undefined`
+ *   when no unit is registered (no read needed — {@link restore} would
+ *   serve empty values regardless).
+ */
+restoreFloor(checkpoint: ProjectionCheckpoint): number | undefined
+
+/**
+ * View a checkpoint's rows without any log read: for every registered
+ * unit whose row's `ver` matches, serve the schema-validated
+ * `view` of the stored state; mismatched or absent rows leave their key
+ * absent (a cold or listing consumer treats it as not-yet-available and a
+ * fuller read path refolds it). The zero-I/O rung of the read ladder —
+ * values are as stale as their rows, never wrong.
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
+ * @returns whole values per key with a usable row; empty when none.
+ */
+viewCheckpoint(checkpoint: ProjectionCheckpoint): Partial<SessionProjectionMap>
+
+/**
+ * Cold read: fold every registered unit over a stored log suffix, seeding
+ * each from its checkpoint row when usable — the one read recipe (cached
+ * state + forward tail replay + `view`) applied without a live `Session`.
+ * Call with the events returned by a persistence
+ * `readFrom(id, restoreFloor(checkpoint))` and that same floor as
+ * `baseSeq`; the floor's one-below anchor makes the supplied end honest,
+ * so a shrunk log is detected here. A row is usable iff its
+ * `ver` matches the live unit's `stateVersion`, it does not predate `baseSeq`
+ * (`seq >= baseSeq - 1`), and it does not claim events past the
+ * supplied end (`seq <= endSeq`); an unusable row is discarded
+ * and its key refolds from `init` — which is only sound over the full
+ * log, so a discarded row with `baseSeq > 0` throws (the caller re-reads
+ * from seq 0, e.g. after a crash-repair truncation shrank the log below
+ * a row's watermark).
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
+ * @param events - the stored events with `seq >= baseSeq`, in seq order.
+ * @param baseSeq - the seq `events` starts at (its first event's seq when non-empty).
+ * @returns the snapshot cut at the supplied log end (`asOfSeq` is the last
+ *   supplied event's seq, `baseSeq - 1` for an empty tail) plus the
+ *   refreshed checkpoint rows at that cut, ready for a durable write-back.
+ */
+restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }
 ```
 
-Types: [Session](../core-data-structures/session.md)
+Types: [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md)
 
-Source: [`packages/session-projection/session-projection/src/index.ts:136`](../../packages/session-projection/session-projection/src/index.ts)
+Source: [`packages/session-projection/session-projection/src/index.ts:156`](../../packages/session-projection/session-projection/src/index.ts)
 
 ## `ctx.sessionQuery` — `SessionQueryService` (abstract seam)
 

docs/event-producer-consumer.md

@@ -32,8 +32,8 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `goal/changed` | `emit` | [`packages/goal/goal/src/types.ts:169`](../packages/goal/goal/src/types.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:58`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-title`](../packages/session-title/session-title) |
 | `session/created` | `emit` | [`packages/core/session/src/index.ts:71`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`llm-retry`](../packages/llm/llm-retry), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
-| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:81`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:93`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), `apiproxy`, [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) |
+| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:81`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:93`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), `apiproxy`, [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) |
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:103`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) |
 | `slash/input-begin-command` | `bail` | [`packages/client/ui-slash/src/types.ts:230`](../packages/client/ui-slash/src/types.ts) | - | `ui-conversation` |
 | `slash/input-consume-token` | `bail` | [`packages/client/ui-slash/src/types.ts:244`](../packages/client/ui-slash/src/types.ts) | - | `ui-conversation` |

docs/module-graph.md

@@ -141,6 +141,7 @@ flowchart TD
     pkg_client_locale["client-locale"]
     pkg_client_modules["client-modules"]
     pkg_client_runtime["client-runtime"]
+    pkg_client_test_runtime["client-test-runtime"]
     pkg_client_ui_command["client-ui-command"]
     pkg_client_ui_conversation["client-ui-conversation"]
     pkg_client_ui_layout["client-ui-layout"]
@@ -211,6 +212,7 @@ flowchart TD
   end
   subgraph group_session_projection["packages/session-projection"]
     pkg_session_projection["session-projection"]
+    pkg_session_projection_cache["session-projection-cache"]
   end
   subgraph group_storage["packages/storage"]
     pkg_storage["storage"]
@@ -275,6 +277,10 @@ flowchart TD
   pkg_client_locale --> pkg_client_ui_primitives
   pkg_client_locale --> pkg_client_ui_slots
   pkg_client_locale --> pkg_invariants
+  pkg_client_test_runtime --> pkg_client_runtime
+  pkg_client_test_runtime --> pkg_client_ui_slots
+  pkg_client_test_runtime --> pkg_client_web_react
+  pkg_client_test_runtime --> pkg_invariants
   pkg_client_ui_models --> pkg_client_runtime
   pkg_client_ui_models --> pkg_client_ui_slots
   pkg_client_ui_models --> pkg_invariants
@@ -502,6 +508,11 @@ flowchart TD
   pkg_pty --> pkg_invariants
   pkg_scripts --> pkg_app_boot
   pkg_scripts --> pkg_invariants
+  pkg_session_projection_cache --> pkg_invariants
+  pkg_session_projection_cache --> pkg_session
+  pkg_session_projection_cache --> pkg_session_persistence
+  pkg_session_projection_cache --> pkg_session_projection
+  pkg_session_projection_cache --> pkg_storage_domain
   pkg_tasks --> pkg_agent
   pkg_tasks --> pkg_brand
   pkg_tasks --> pkg_invariants
@@ -942,6 +953,7 @@ flowchart TD
 | [`client-connection`](../packages/client/connection) | `client` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`client-hmr`](../packages/client/hmr) | `client` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`client-locale`](../packages/client/locale) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-test-runtime`](../packages/client/test-runtime) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
 | [`client-ui-models`](../packages/client/ui-models) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-settings`](../packages/client/ui-settings) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
@@ -1005,6 +1017,7 @@ flowchart TD
 | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`pty`](../packages/pty/pty) | `pty` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`scripts`](../packages/sdk/scripts) | `sdk` | [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants) |
+| [`session-projection-cache`](../packages/session-projection/session-projection-cache) | `session-projection` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`storage-domain`](../packages/storage/storage-domain) |
 | [`tasks`](../packages/tasks/tasks) | `tasks` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`session-telemetry`](../packages/telemetry/session-telemetry) | `telemetry` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`workflow`](../packages/workflow/workflow) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |

package.json

@@ -14,13 +14,14 @@
     "website"
   ],
   "scripts": {
-    "build": "tsc -b && tsdown",
+    "build": "npm run build:lib && npm run build:web",
+    "build:lib": "tsc -b && tsdown",
     "build:web": "pnpm --filter @deepseek-ai/dsh-frontend run build",
     "clean": "tsx scripts/clean.ts",
     "change-scope": "tsx scripts/change-scope.ts",
     "typecheck": "tsc -b",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
+    "lint": "node --max-old-space-size=8192 node_modules/eslint/bin/eslint.js .",
+    "lint:fix": "node --max-old-space-size=8192 node_modules/eslint/bin/eslint.js . --fix",
     "duplication": "jscpd --config .jscpd.json packages scripts",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
@@ -29,7 +30,7 @@
     "test:snapshot:record": "DSH_SNAPSHOT=record vitest run --config vitest.snapshot.config.ts --update",
     "test:snapshot:refresh": "DSH_SNAPSHOT=refresh vitest run --config vitest.snapshot.config.ts",
     "migrate:packed-session-fixtures": "tsx scripts/migrate-packed-session-fixtures.ts",
-    "test:web": "npm run build && npm run build:web && vitest run --config vitest.web.config.ts",
+    "test:web": "npm run build && vitest run --config vitest.web.config.ts",
     "test:gui": "vitest run packages/client packages/host",
     "check:all": "tsx scripts/run-gates.ts check-all",
     "check:ci": "tsx scripts/run-gates.ts ci-primary",
@@ -95,13 +96,13 @@
     "constraints": "tsx scripts/check-workspace-constraints.ts",
     "doc-sync": "tsx scripts/run-gates.ts doc-sync",
     "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-package-invariants && pnpm run verify-built-package-invariants && pnpm run verify-cordis-config && pnpm run verify-node-next-types && pnpm run verify-runtime-closure",
-    "dsh": "node --import tsx apps/cli/src/bin.ts",
+    "dsh": "node --experimental-transform-types --import ./scripts/tspath-loader.ts apps/cli/src/bin.ts",
     "demo:headless": "node --import tsx packages/examples/cli-demo/src/bin.ts --config examples/headless-agent/cordis.yml",
-    "demo:tui": "node --import tsx apps/cli/src/bin.ts",
+    "demo:tui": "node --experimental-transform-types --import ./scripts/tspath-loader.ts apps/cli/src/bin.ts",
     "demo:code-mode": "node scripts/demo-code-mode.mjs",
     "demo:cordis": "node scripts/demo-cordis.mjs",
     "demo:acp": "node --import tsx packages/examples/acp-demo/src/bin.ts --config examples/acp-agent/cordis.yml",
-    "demo:web": "npm run build && npm run build:web && node --import tsx apps/cli/src/bin.ts web",
+    "demo:web": "npm run build && node --experimental-transform-types --import ./scripts/tspath-loader.ts apps/cli/src/bin.ts web",
     "mock:llm": "node --import tsx packages/support/llm-mock-server/src/bin.ts",
     "dev:web": "tsx scripts/dev-web.ts --poll",
     "postinstall": "node scripts/install-lefthook.mjs"

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

@@ -0,0 +1,56 @@
+/**
+ * The outward session face. Feature packages never see the concrete Session
+ * class: components read conversation state through `useSession` (the
+ * ObservableSnapshot half), and orchestration code calls the behavior verbs
+ * below — nothing else. Widening this interface is the explicit act of
+ * widening what features may do to a session (and what every test fixture
+ * must stub); runtime-internal entry points (history staging, wire-frame
+ * dispatch) stay on the class, invisible out here.
+ */
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { RpcResult, SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import type { ConversationSnapshot } from '../sessions/conversation.ts'
+import type { ObservableSnapshot } from './store.ts'
+
+/** Key-addressed projection read face (the useProjection resolution path; see ProjectionValueStore). */
+export interface ProjectionsFace {
+  /**
+   * The identity-stable bare observable for one projection key (absence is
+   * an `undefined` snapshot, never a missing face).
+   * @param key - projection key.
+   * @returns the key's value face.
+   */
+  faceOf(key: string): ObservableSnapshot<unknown>
+}
+
+/** Identity plus the behavior verbs features may invoke on a session. */
+export interface ISession {
+  /** The session's host identity (agent id — same axis). */
+  readonly sessionId: SessionId
+  /** Host-computed projection values by key (the useProjection seat). */
+  readonly projections: ProjectionsFace
+  /**
+   * Send a prompt into the session.
+   * @param content - model-facing content blocks.
+   * @param mode - 'queue' appends a turn; 'steer' interrupts the running one.
+   * @returns acceptance, or the business error (also mirrored into snapshot.promptError).
+   */
+  prompt(content: ContentBlock[], mode: 'queue' | 'steer'): Promise<RpcResult<{ accepted: true }>>
+  /**
+   * Cancel the running turn.
+   * @returns acceptance, or the business error.
+   */
+  cancel(): Promise<RpcResult<{ accepted: true }>>
+  /**
+   * Extend the history window backwards (older messages pagination).
+   * @returns completion; failures land in snapshot.openState/loadingOlder.
+   */
+  loadOlder(): Promise<void>
+}
+
+/**
+ * The full outward face: behavior verbs plus the conversation read side
+ * (the `useSession` hook source). This is the type carried by
+ * `SessionBinding.session` and the provide channel.
+ */
+export type SessionFace = ISession & ObservableSnapshot<ConversationSnapshot>

packages/client/runtime/src/client/contract/sessions-port.ts

@@ -0,0 +1,47 @@
+/**
+ * Cross-domain sessions face: the contract surface sibling domains (today:
+ * workspaces) consume instead of the sessions implementation. The sessions
+ * domain satisfies it structurally — SessionsService is assignable, checked
+ * wherever the assembly layer or a test injects the real service — so
+ * widening this face is the explicit act of widening the inter-domain
+ * dependency.
+ */
+
+import type { SessionId, WorkspaceId } from '@deepseek-ai/dsh-client-connection/client'
+import type { ObservableSnapshot } from './store.ts'
+
+/** Session-list row facts sibling domains read: recency, blank-reuse eligibility, and its cwd canon. */
+export interface SessionsPortSummary {
+  id: SessionId
+  /** Empty-log bit (blank sessions are reused by New Session instead of minting another). */
+  blank: boolean
+  cwd?: string
+  updatedAt: number
+}
+
+/** Session-list facts sibling domains read: readiness, selection, and the row map. */
+export interface SessionsPortList {
+  ids: SessionId[]
+  byId: Record<SessionId, SessionsPortSummary>
+  current: SessionId | undefined
+  phase: 'pending' | 'ready'
+}
+
+/** The sessions-service face injected into sibling domains. */
+export interface SessionsPort {
+  /** Observable list snapshot (read face only; writes stay inside the sessions domain). */
+  readonly list: ObservableSnapshot<SessionsPortList>
+  /**
+   * Create a session on the host.
+   * @param opts - target workspace.
+   * @returns the new session id.
+   */
+  create(opts: { workspaceId: WorkspaceId }): Promise<SessionId>
+  /**
+   * Select a session as current.
+   * @param id - session id (must exist in the list store).
+   */
+  open(id: SessionId): void
+  /** Clear the current selection into the no-session view state. */
+  clear(): void
+}

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

@@ -0,0 +1,64 @@
+/**
+ * The outward sessions-service face — what `ctx.sessions` exposes to feature
+ * packages and the renderer host, and therefore exactly what the test
+ * runtime's sessions double must implement. Wire-pump entry points
+ * (handleMuxEnvelope/handleConnected/refresh) and runtime internals stay on
+ * the concrete class; cross-domain consumers keep the narrower
+ * [SessionsPort](./sessions-port.ts). Widening this interface is the
+ * explicit act of widening what features may do to the sessions domain.
+ */
+import type { Context } from 'cordis'
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import type { HostObservable, SessionMaybeProvideInfo } from '@deepseek-ai/dsh-client-ui-slots'
+import type {
+  SessionBinding, SessionListState, SessionProvideDescriptor,
+} from '../sessions/service.ts'
+import type { SessionFace } from './session.ts'
+import type { ObservableSnapshot } from './store.ts'
+
+/** The sessions-service face injected as `ctx.sessions`. */
+export interface ISessions {
+  /** The useSessions standard feed (list rows + current selection; read face — writes stay inside the domain). */
+  readonly list: ObservableSnapshot<SessionListState>
+  /** Atomic current-session provide projection (the renderer host's `sessions.provideInfo` feed). */
+  readonly currentProvideInfo: HostObservable<SessionMaybeProvideInfo>
+  /**
+   * Select a session as current.
+   * @param id - session id (must exist in the list; unknown ids fail loud).
+   */
+  open(id: SessionId): void
+  /** Clear the current selection into the no-session view state. */
+  clear(): void
+  /**
+   * Register a per-session standard-props provider (hooks become `use<Name>`
+   * selector hooks on the render side; props spread verbatim).
+   * @param descriptor - static member roster plus per-session resolver.
+   * @returns disposer removing the provider.
+   */
+  provide(descriptor: SessionProvideDescriptor): () => void
+  /**
+   * Resolve an Agent-scoped context view (use-and-discard).
+   * @param id - session id.
+   * @returns scoped ctx, or undefined for a session neither listed nor already scoped.
+   */
+  scope(id: SessionId): Context | undefined
+  /**
+   * Read the Agent scope tag off a context (service-method seam: fetch
+   * bundles must reach scope resolution through ctx.sessions).
+   * @param ctx - any client context.
+   * @returns the session id, or undefined on root contexts.
+   */
+  scopeOf(ctx: Context): SessionId | undefined
+  /**
+   * Resolve the session face behind an Agent-scoped context.
+   * @param ctx - an Agent-scoped context.
+   * @returns the session face, or undefined when the ctx is untagged or its scope was pruned.
+   */
+  sessionOf(ctx: Context): SessionFace | undefined
+  /**
+   * Resolve the stable session binding (scope-addressed assembly feed).
+   * @param id - session id.
+   * @returns binding, or undefined for a session neither listed nor already scoped.
+   */
+  binding(id: SessionId): SessionBinding | undefined
+}

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

@@ -0,0 +1,65 @@
+/**
+ * The outward workspaces-service face — what `ctx.workspaces` exposes to
+ * feature packages and the renderer host, and therefore exactly what the
+ * test runtime's workspaces double must implement. Wire-pump entry points
+ * (handleHostEnvelope/handleConnected/refresh/startInitialSelection) stay on
+ * the concrete class. Widening this interface is the explicit act of
+ * widening what features may do to the workspaces domain.
+ */
+import type { SessionId, WorkspaceId, WorkspaceView } from '@deepseek-ai/dsh-client-connection/client'
+import type { WorkspaceListState } from '../workspaces/service.ts'
+import type { ObservableSnapshot } from './store.ts'
+
+/** The workspaces-service face injected as `ctx.workspaces`. */
+export interface IWorkspaces {
+  /** The useWorkspaces standard feed (read face — writes stay inside the domain). */
+  readonly list: ObservableSnapshot<WorkspaceListState>
+  /**
+   * Connect a Workspace to its reusable or freshly created blank session.
+   * @param workspaceId - target workspace.
+   * @returns the connected session id.
+   */
+  connectWorkspace(workspaceId: WorkspaceId): Promise<SessionId>
+  /**
+   * The New Session flow: connect the target (or recent) Workspace and open
+   * the resulting session; failures surface on the session list state.
+   * @param workspaceId - explicit target; omitted uses the recency projection.
+   */
+  startSession(workspaceId?: WorkspaceId): void
+  /**
+   * Create a Workspace by name or register an existing path.
+   * @param input - exactly one Host create spelling.
+   * @returns the created or idempotently resolved Workspace.
+   */
+  create(input: { name: string } | { path: string }): Promise<WorkspaceView>
+  /**
+   * Open the Host's native directory picker.
+   * @returns the selected path, or null when the user cancelled.
+   */
+  pickDirectory(): Promise<string | null>
+  /**
+   * Open a filesystem path with the Host operating system's default application.
+   * @param path - absolute or host-resolvable path.
+   */
+  openPath(path: string): Promise<void>
+  /**
+   * Rename a Workspace.
+   * @param workspaceId - target workspace.
+   * @param title - the new display title.
+   * @returns the updated Workspace view.
+   */
+  rename(workspaceId: WorkspaceId, title: string): Promise<WorkspaceView>
+  /**
+   * Delete a Workspace (its sessions fall back to the unaccounted group).
+   * @param workspaceId - target workspace.
+   */
+  delete(workspaceId: WorkspaceId): Promise<void>
+  /**
+   * Move an accounted session within/into a Workspace's ordered list.
+   * @param workspaceId - target workspace.
+   * @param sessionId - accounted session to move.
+   * @param beforeSessionId - accounted anchor to insert before; omitted appends.
+   * @returns the updated Workspace view.
+   */
+  insertSessionBefore(workspaceId: WorkspaceId, sessionId: SessionId, beforeSessionId?: SessionId): Promise<WorkspaceView>
+}

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

@@ -12,10 +12,17 @@ import type { UseProjection } from './sessions/projection-store.ts'
 export { SlotsService } from './slots.ts'
 export type { RootOwnerProps } from './slots.ts'
 export { SessionCreateError, SessionsService, scopeOf, workspaceTitleOf } from './sessions/service.ts'
+// The provide channel is shared with the client test runtime (one
+// materialization/projection implementation; no test-side mirror to drift).
+export { SessionProvideChannel } from './sessions/provide.ts'
+export type { SessionProvideChannelHost } from './sessions/provide.ts'
 export { createScope } from './agents/scope.ts'
 export type { AgentScopeHandle } from './agents/scope.ts'
 export { WorkspaceCreateError, WorkspacesService } from './workspaces/service.ts'
 export type { Session } from './sessions/session.ts'
+export type { ISession, ProjectionsFace, SessionFace } from './contract/session.ts'
+export type { ISessions } from './contract/sessions.ts'
+export type { IWorkspaces } from './contract/workspaces.ts'
 export type {
   SessionBinding, SessionListState, SessionProvideContribution, SessionProvideDescriptor, SessionSummary,
 } from './sessions/service.ts'
@@ -109,8 +116,10 @@ declare module 'cordis' {
   }
   interface Context {
     slots: import('./slots.ts').SlotsService
-    sessions: import('./sessions/service.ts').SessionsService
-    workspaces: import('./workspaces/service.ts').WorkspacesService
+    /** The outward face only; the concrete service stays inside the runtime. */
+    sessions: import('./contract/sessions.ts').ISessions
+    /** The outward face only; the concrete service stays inside the runtime. */
+    workspaces: import('./contract/workspaces.ts').IWorkspaces
   }
 }
 

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

@@ -212,6 +212,19 @@ export class SessionManager {
             session.handleBlank(s.blank)
             session.handleRunning(s.running)
           }
+          // Seed each row's projection baseline into the per-session value
+          // store (cold titles surface without opening the session). Per-key
+          // apply, not seed(): the list block is a partial baseline — the
+          // cold cache serves only version-matching keys — so an absent key
+          // must not clear; higher-seq-wins still keeps a stale list block
+          // from overwriting a newer push frame or tail baseline.
+          for (const s of result.value.items) {
+            const block = s.projections
+            if (block === undefined) continue
+            const store = this.projectionStore(s.sessionId)
+            const values = block.values as Record<string, unknown>
+            for (const key of Object.keys(values)) store.apply(key, values[key], block.asOfSeq)
+          }
         } else {
           this.listState = 'error'
           this.listError = result.error

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

@@ -0,0 +1,190 @@
+/**
+ * The session standard-props provide channel: provider roster, bundle
+ * materialization (fail-loud on undeclared/missing/duplicate members), the
+ * static no-session projection, and the atomic current-session projection
+ * observable. One implementation — SessionsService drives it from wire
+ * truth, the test runtime's sessions double drives it from fixtures — so
+ * the materialization rules and the projection semantics cannot drift
+ * between production and the test bench.
+ */
+import type { HostObservable, SessionMaybeProvideInfo, SessionProvideInfo } from '@deepseek-ai/dsh-client-ui-slots'
+import type { SessionBinding, SessionProvideDescriptor } from './service.ts'
+
+/** The owner-side hooks: how the channel reaches the owner's live bundles and current selection. */
+export interface SessionProvideChannelHost {
+  /**
+   * Re-materialize every already-materialized bundle against the new roster
+   * (call {@link SessionProvideChannel.materializeInfo} per live binding).
+   * Lazily-materialized sessions pick the new roster up on first resolve.
+   */
+  rebuildBundles(): void
+  /** Resolve the current selection's bundle (the owner's maybe-provide lookup). */
+  resolveCurrent(): SessionMaybeProvideInfo
+}
+
+/**
+ * Provider roster + materialization + current projection. The channel owns
+ * every rule a provider contribution must satisfy; owners keep only their
+ * per-session bundle storage and the definition of "current".
+ */
+export class SessionProvideChannel {
+  private readonly providers: SessionProvideDescriptor[] = []
+  private maybeInfoCache: SessionMaybeProvideInfo
+  /** Latest published current bundle (identity comparison dedupes republish). */
+  private currentSnapshot: SessionMaybeProvideInfo
+  /** Projection subscribers (plain cell: bundles hold live session sources, so no store freeze may touch them). */
+  private readonly listeners = new Set<() => void>()
+
+  /**
+   * Atomic current-session provide projection: selection changes and
+   * provider-roster changes publish through this one source, so a roster
+   * change under a stable current id republishes the bundle instead of
+   * stranding mounted entries.
+   */
+  readonly currentProvideInfo: HostObservable<SessionMaybeProvideInfo>
+
+  /**
+   * @param host - owner-side bundle storage and current-selection resolution.
+   */
+  constructor(private readonly host: SessionProvideChannelHost) {
+    // 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.maybeInfoCache = this.materializeMaybeInfo()
+    this.currentSnapshot = this.maybeInfoCache
+    this.currentProvideInfo = {
+      getSnapshot: () => this.currentSnapshot,
+      subscribe: (fn) => {
+        this.listeners.add(fn)
+        return () => { this.listeners.delete(fn) }
+      },
+    }
+  }
+
+  /** The static no-session projection under the current roster (declared names present, values undefined). */
+  get maybeInfo(): SessionMaybeProvideInfo {
+    return this.maybeInfoCache
+  }
+
+  /**
+   * Register a per-session standard-props provider (see
+   * SessionsService.provide for the product contract). Live bundles rebuild
+   * immediately; misdeclared providers fail loud here, at the registration
+   * edge, and the registration rolls back — the channel never stays on a
+   * roster it cannot materialize.
+   * @param descriptor - static member roster plus per-session resolver.
+   * @returns disposer removing the provider.
+   */
+  provide(descriptor: SessionProvideDescriptor): () => void {
+    this.providers.push(descriptor)
+    try {
+      this.applyRosterChange()
+    } catch (error) {
+      this.providers.splice(this.providers.indexOf(descriptor), 1)
+      // Restore the previous (valid) roster's bundles; cannot rethrow — the
+      // pre-push roster materialized successfully before.
+      this.applyRosterChange()
+      throw error
+    }
+    return () => {
+      const at = this.providers.indexOf(descriptor)
+      if (at >= 0) this.providers.splice(at, 1)
+      this.applyRosterChange()
+    }
+  }
+
+  /**
+   * Re-derive the current selection's bundle and publish it when it changed.
+   * Bundles are identity-stable per (scope, roster) materialization, so an
+   * identity compare is exact; synchronous notify — call sites (the owner's
+   * list subscription, provide()) already sit behind their own batching or
+   * registration edges.
+   */
+  publishCurrent(): void {
+    const next = this.host.resolveCurrent()
+    if (next === this.currentSnapshot) return
+    this.currentSnapshot = next
+    for (const fn of [...this.listeners]) {
+      try {
+        fn()
+      } catch (error) {
+        // Contain subscriber failures: this notify runs inside the list
+        // notification, where a throwing render-side subscriber would starve
+        // later listeners and abort the projection pass that scheduled it.
+        console.error('sessions.currentProvideInfo subscriber failed:', error)
+      }
+    }
+  }
+
+  /**
+   * Materialize the standard-props bundle for one session (fails loud on
+   * undeclared, missing, and duplicate member names).
+   * @param binding - session assembly handle fed to every resolver.
+   * @returns the materialized bundle (identity-stable until the next materialization).
+   */
+  materializeInfo(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,
+      // The useProjection seat: key-addressed bare value faces off the
+      // session's projection store (open key space — never a static roster member).
+      projections: { faceOf: key => binding.session.projections.faceOf(key) },
+    }
+  }
+
+  /** Rebuild the static projection and the owner's live bundles, then republish the current one. */
+  private applyRosterChange(): void {
+    this.maybeInfoCache = this.materializeMaybeInfo()
+    this.host.rebuildBundles()
+    this.publishCurrent()
+  }
+
+  /** Build the static no-session kit and reject duplicate declared names. */
+  private materializeMaybeInfo(): 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 } // no projections face: every key reads absent without a session
+  }
+}

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

@@ -22,9 +22,12 @@ import type {
 } from '@deepseek-ai/dsh-client-ui-slots'
 import type { SnapshotStore } from '../contract/store.ts'
 import { createSnapshotStore } from '../contract/store.ts'
+import type { SessionFace } from '../contract/session.ts'
+import type { ISessions } from '../contract/sessions.ts'
 import { createScope, scopeOf as scopeTagOf } from '../agents/scope.ts'
 import { SessionManager } from './manager.ts'
 import type { SessionListPhase } from './manager.ts'
+import { SessionProvideChannel } from './provide.ts'
 import type { Session } from './session.ts'
 
 /** Session list row projected from the host list RPC plus live stream increments. */
@@ -79,7 +82,8 @@ export class SessionCreateError extends Error {
 /** Session assembly handle for SessionProvider/inject factories (identity-stable per session). */
 export interface SessionBinding {
   readonly sessionId: SessionId
-  readonly session: Session
+  /** The outward session face only — feature code never sees the concrete class. */
+  readonly session: SessionFace
   readonly ctx: Context
 }
 
@@ -119,6 +123,8 @@ interface ScopeRecord {
   fiber: Fiber
   ctx: Context
   binding: SessionBinding
+  /** The concrete Session for runtime-internal entry points (staging open()); the binding carries only the outward face. */
+  session: Session
   /** Render-layer standard-props bundle (identity-stable per scope; the renderer's per-info caches key off it). */
   provideInfo: SessionProvideInfo
 }
@@ -146,7 +152,7 @@ export interface SessionProvideDescriptor {
 }
 
 /** Root sessions service: list store, current selection, object-layer manager, scope tree, bindings, ancestry. */
-export class SessionsService {
+export class SessionsService implements ISessions {
   /** List snapshot store (list RPC + host stream increments; re-pulled on reconnect) — the useSessions standard feed, current included. */
   readonly list: SnapshotStore<SessionListState>
   /** The object-layer instance cluster and frame dispatch entry. */
@@ -170,14 +176,8 @@ 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
-  /** Latest published {@link SessionsService.currentProvideInfo} bundle (identity comparison dedupes republish). */
-  private currentProvideInfoSnapshot: SessionMaybeProvideInfo
-  /** currentProvideInfo subscribers (plain cell: bundles hold live Session sources, so no store freeze may touch them). */
-  private readonly currentProvideInfoListeners = new Set<() => void>()
+  /** The provide channel (roster, materialization rules, current projection) — shared with the test runtime's double. */
+  private readonly provideChannel: SessionProvideChannel
   /**
    * The staged session id — follows `list.current` exactly, holding its last
    * defined value across masked gaps (a transiently absent selection blanks
@@ -212,23 +212,17 @@ export class SessionsService {
     // The current-provide projection follows the same current writes.
     this.list.subscribe(() => {
       this.followCurrent()
-      this.updateCurrentProvideInfo()
+      this.provideChannel.publishCurrent()
     })
-    // 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()
-    this.currentProvideInfoSnapshot = this.maybeInfo
-    this.currentProvideInfo = {
-      getSnapshot: () => this.currentProvideInfoSnapshot,
-      subscribe: (fn) => {
-        this.currentProvideInfoListeners.add(fn)
-        return () => { this.currentProvideInfoListeners.delete(fn) }
+    this.provideChannel = new SessionProvideChannel({
+      rebuildBundles: () => {
+        for (const record of this.scopes.values()) {
+          record.provideInfo = this.provideChannel.materializeInfo(record.binding)
+        }
       },
-    }
+      resolveCurrent: () => this.maybeProvideInfo(this.list.getSnapshot().current),
+    })
+    this.currentProvideInfo = this.provideChannel.currentProvideInfo
     rootCtx.reflect.provide('sessions', this, undefined)
   }
 
@@ -243,105 +237,10 @@ export class SessionsService {
    * @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)
-    }
-    this.updateCurrentProvideInfo()
-  }
-
-  /**
-   * Re-derive the current selection's provide bundle and publish it when it
-   * changed. Bundles are identity-stable per (scope, roster)
-   * materialization, so an identity compare is exact; synchronous notify —
-   * both call sites (list.subscribe, provide()) already sit behind their own
-   * batching or registration edges.
-   */
-  private updateCurrentProvideInfo(): void {
-    const next = this.maybeProvideInfo(this.list.getSnapshot().current)
-    if (next === this.currentProvideInfoSnapshot) return
-    this.currentProvideInfoSnapshot = next
-    for (const fn of [...this.currentProvideInfoListeners]) {
-      try {
-        fn()
-      } catch (error) {
-        // Contain subscriber failures: this notify runs inside the list
-        // notification, where a throwing render-side subscriber would starve
-        // later listeners and abort the projection pass that scheduled it.
-        console.error('sessions.currentProvideInfo subscriber failed:', error)
-      }
-    }
-  }
-
-  /** 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 } // no projections face: every key reads absent without a session
-  }
-
-  /** 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,
-      // The useProjection seat: key-addressed bare value faces off the
-      // session's projection store (open key space — never a static roster member).
-      projections: { faceOf: key => binding.session.projections.faceOf(key) },
-    }
+    // scopes before later plugins register) — the channel rebuilds their
+    // bundles through the host hooks so every provider lands by first render.
+    return this.provideChannel.provide(descriptor)
   }
 
   /**
@@ -439,9 +338,9 @@ export class SessionsService {
    * `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.
+   * @returns the session face, or undefined when the ctx is untagged or its scope was pruned.
    */
-  sessionOf(ctx: Context): Session | undefined {
+  sessionOf(ctx: Context): SessionFace | undefined {
     const id = scopeTagOf(ctx)
     if (id === undefined) return undefined
     return this.scopes.get(id)?.binding.session
@@ -473,7 +372,7 @@ export class SessionsService {
    * return the static no-session projection rather than removing hook props.
    */
   private maybeProvideInfo(id: string | undefined): SessionMaybeProvideInfo {
-    return (id === undefined ? undefined : this.provideInfo(id)) ?? this.maybeInfo
+    return (id === undefined ? undefined : this.provideInfo(id)) ?? this.provideChannel.maybeInfo
   }
 
   /**
@@ -497,7 +396,7 @@ export class SessionsService {
      * validates and the projection masks absent selections), so resolve
      * cannot miss; kept so a future current writer cannot crash the notify. */
     if (record !== undefined) {
-      void record.binding.session.open()
+      void record.session.open()
     }
   }
 
@@ -540,8 +439,9 @@ export class SessionsService {
       fiber,
       ctx,
       binding,
+      session,
       // Sources are bare observables; React binds selector hooks at its own seam.
-      provideInfo: this.materializeProvideInfo(binding),
+      provideInfo: this.provideChannel.materializeInfo(binding),
     }
     this.scopes.set(id, record)
     return record
@@ -608,7 +508,7 @@ export class SessionsService {
     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()
+    record.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)

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

@@ -10,7 +10,7 @@ import type {
 // 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 { SessionFace } from '../contract/session.ts'
 import type {
   CodeSubCall, ComposerPhase, ConversationNode, ConversationSnapshot, OpenState,
   PromptError, QueuedMessage, RunningToolCall,
@@ -67,9 +67,11 @@ function queuePreviewOf(content: readonly ContentBlock[]): string {
 
 /**
  * Owns a session's event window, derived conversation state, and observable
- * snapshot. React bindings remain outside this data layer.
+ * snapshot. React bindings remain outside this data layer. Features see only
+ * the {@link SessionFace} slice (ISession verbs + the snapshot source); the
+ * remaining public members are manager/runtime entry points.
  */
-export class Session implements ObservableSnapshot<ConversationSnapshot> {
+export class Session implements SessionFace {
   // ---- Window and derived state (all private; the snapshot is the only read surface) ----
   private events: SessionEvent[] = []
   /** Wire views aligned with `events` by index (envelope-level annotations; undefined = no view).

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

@@ -6,7 +6,8 @@ import type {
 } from '@deepseek-ai/dsh-client-connection/client'
 import type { SnapshotStore } from '../contract/store.ts'
 import { createSnapshotStore } from '../contract/store.ts'
-import type { SessionsService } from '../sessions/service.ts'
+import type { SessionsPort, SessionsPortList } from '../contract/sessions-port.ts'
+import type { IWorkspaces } from '../contract/workspaces.ts'
 import { WorkspaceManager, type WorkspaceListPhase } from './manager.ts'
 
 /** Workspace list plus the two-baseline readiness and default-target projection. */
@@ -30,7 +31,7 @@ export class WorkspaceCreateError extends Error {
 }
 
 /** Real Workspace object layer and Host actions. */
-export class WorkspacesService {
+export class WorkspacesService implements IWorkspaces {
   /** UI-facing immutable projection; the manager remains wire truth. */
   readonly list: SnapshotStore<WorkspaceListState>
   /** Workspace baseline and frame owner. */
@@ -43,9 +44,9 @@ export class WorkspacesService {
   /**
    * @param ctx - client root context.
    * @param api - shared wire client.
-   * @param sessions - lower-level Session service used for recency and blank-session reuse.
+   * @param sessions - cross-domain sessions face used for recency and blank-session reuse.
    */
-  constructor(ctx: Context, private readonly api: IApiClient, private readonly sessions: SessionsService) {
+  constructor(ctx: Context, private readonly api: IApiClient, private readonly sessions: SessionsPort) {
     this.manager = new WorkspaceManager(api)
     this.list = createSnapshotStore<WorkspaceListState>({
       items: [], state: 'idle', phase: 'pending', error: null,
@@ -271,7 +272,7 @@ export class WorkspacesService {
 /** Stable tie-breaking follows Host Workspace order. */
 function recentWorkspace(
   workspaces: readonly WorkspaceView[],
-  sessions: ReturnType<SessionsService['list']['getSnapshot']>['byId'],
+  sessions: SessionsPortList['byId'],
 ): WorkspaceId | undefined {
   let selected: WorkspaceId | undefined
   let selectedTime = Number.NEGATIVE_INFINITY

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

@@ -160,6 +160,28 @@ describe('list lifecycle', () => {
     expect(manager.getListSnapshot().items.find(item => item.sessionId === S1)?.title).toBeUndefined()
   })
 
+  it('seeds cold titles from the list rows\' projections block under higher-seq-wins', async () => {
+    const api = new FakeApiClient()
+    const manager = new SessionManager(api)
+    // A push frame landed before the list (S2's title is newer than the block's cut).
+    manager.handleMuxEnvelope({
+      rpcId: 'push-newer' as never,
+      payload: { type: 'session/projection', sessionId: S2, key: 'title', value: 'Pushed', seq: 9 } as never,
+    })
+    api.onList = () => Promise.resolve(ok({
+      items: [
+        { ...summary(S1), projections: { asOfSeq: 4, values: { title: 'Cold cached' } } },
+        { ...summary(S2, { updatedAt: 200 }), projections: { asOfSeq: 5, values: { title: 'List stale' } } },
+      ] as never[],
+    }))
+    await manager.refreshList()
+    const items = manager.getListSnapshot().items
+    // Cold row: title surfaces straight from the list block — no open, no history.
+    expect(items.find(item => item.sessionId === S1)?.title).toBe('Cold cached')
+    // The stale list block (seq 5) cannot overwrite the newer push frame (seq 9).
+    expect(items.find(item => item.sessionId === S2)?.title).toBe('Pushed')
+  })
+
   it('drops a projection row beyond the subscription baseline before accepting its durable replay', async () => {
     const api = new FakeApiClient()
     api.onList = () => Promise.resolve(ok({ items: [summary(S1)] as never[] }))

packages/client/test-runtime/README.i18n.yaml

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

packages/client/test-runtime/README.md

@@ -0,0 +1,24 @@
+# @deepseek-ai/dsh-client-test-runtime
+
+English | [中文](README.zh.md)
+
+jsdom slot test runtime for client feature specs: a real Cordis `Context`, the production `SlotsService` and web-react renderer, assembled around typed session/workspace doubles. Feature suites exercise declaration, registration, scope, store, inject, rendering, updates, and disposal without hand-building the machinery per suite — and without a second implementation of any production logic.
+
+The doubles implement the same outward faces features receive through ctx (`TestSessions implements ISessions`, `TestWorkspaces implements IWorkspaces`; each fixture session is a `FixtureSession implements SessionFace`), so a production face change breaks the bench at compile time instead of silently drifting. Provide-bundle materialization runs the production `SessionProvideChannel` — the one implementation shared with `SessionsService`. Fixtures feed plain data: list rows, conversation snapshots (immer-patched via `updateSnapshot`), projection values, and `ISession`-typed behavior stubs that fail loud when a spec calls an unstubbed verb. The typed `provide()` constrains fakes for declared service names to `Partial` of that service's outward face.
+
+Local DOM snapshots: `declare(children)` registers an auto frame whose per-key `<div data-slot>` wrappers are snapshot roots; `renderSlot(key, owner)` returns the slot-local view (container, scoped Testing Library queries, in-place `update(owner)`); a registered snapshot serializer folds CSS-module class hashes (`_frame_a1b2c3` → `frame`) to keep `.snap` files structural and collapses `<svg>` internals to a `data-content` fingerprint. Suites needing a custom page frame use `root.declare(children, Frame)` instead; `mount(plugin)` runs a real fiber with fail-loud service prechecks, and `dispose()` tears down views, feature fibers, minted scopes, and persisted store state on one axis.
+
+Not part of the product plugin graph (no `dshClient`); feature packages depend on it in `devDependencies` only.
+
+## Model Experience
+
+None, as this package is browser-side test infrastructure; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Consumed through repository source aliases only.** Specs resolve the package through tsconfig `paths` to `src`; the built `lib/` artifact re-exports `@deepseek-ai/dsh-client-runtime/client`, whose bundle is a browser loader script with no Node ESM exports, so `lib/index.js` is not importable under plain Node. Acceptable while every consumer is an in-repo Vitest suite; a Node-compatible runtime entry is deferred until an out-of-repo consumer exists.
+- **Conversation snapshots are fixture data, not replayed history.** `updateSnapshot` writes the snapshot store directly; the wire-to-snapshot computation stays covered by the runtime package's own tests and the replay e2e. A fixture can therefore express states the production fold would never produce.

packages/client/test-runtime/README.zh.md

@@ -0,0 +1,24 @@
+# @deepseek-ai/dsh-client-test-runtime
+
+[English](README.md) | 中文
+
+面向 client feature 测试的 jsdom slot 测试运行时：真实 Cordis `Context`、生产 `SlotsService` 与 web-react 渲染器，围绕带类型的 session/workspace 测试替身组装。feature 套件无需逐套件手搭机器即可测遍声明、注册、scope、store、inject、渲染、更新与销毁——且不存在任何生产逻辑的第二份实现。
+
+替身实现的正是 feature 经 ctx 拿到的对外面（`TestSessions implements ISessions`、`TestWorkspaces implements IWorkspaces`；每个 fixture session 是 `FixtureSession implements SessionFace`），生产面一旦改形，测试台在编译期即断，而非静默漂移。provide bundle 材料化直接运行生产 `SessionProvideChannel`——与 `SessionsService` 共用同一份实现。fixture 灌入的是普通数据：列表行、会话快照（经 `updateSnapshot` 以 immer 补丁改写）、projection 值，以及按 `ISession` 取型的行为桩——spec 调用未打桩的动词时报错自明。带类型的 `provide()` 将已声明服务名的 fake 约束为该服务对外面的 `Partial` 子集。
+
+局部 DOM 快照：`declare(children)` 注册自动 frame，逐 key 的 `<div data-slot>` 包裹层即快照根；`renderSlot(key, owner)` 返回该 slot 的局部视图（container、限定范围的 Testing Library 查询、原位 `update(owner)`）；注册的快照序列化器把 CSS-module 哈希类名折回语义名（`_frame_a1b2c3` → `frame`）保持 `.snap` 只含结构，并把 `<svg>` 内部折叠为 `data-content` 指纹。需要自定义页面 frame 的套件改用 `root.declare(children, Frame)`；`mount(plugin)` 在真实 fiber 上运行并对缺失服务先行报错；`dispose()` 沿单一轴拆除视图、feature fiber、已铸 scope 与持久化 store 状态。
+
+不属于产品插件图（无 `dshClient`）；feature 包仅以 `devDependencies` 依赖之。
+
+## Model Experience
+
+无；本包是浏览器侧测试基础设施，无一物到达模型请求。
+
+#### KV Cache effect
+
+无；本包既不组装也不发送 provider 请求。
+
+## Known Limitations and Deferred Work
+
+- **仅可经仓内源码别名消费。** spec 通过 tsconfig `paths` 解析到 `src`；构建产物 `lib/` 再导出 `@deepseek-ai/dsh-client-runtime/client`，而该 bundle 是无 Node ESM 导出的浏览器 loader 脚本，故 `lib/index.js` 在纯 Node 下不可导入。当前所有消费方都是仓内 Vitest 套件，可接受；Node 兼容的运行时入口待出现仓外消费方再补。
+- **会话快照是 fixture 数据，不是重放历史。** `updateSnapshot` 直写快照 store；wire 到快照的运算仍由 runtime 包自身测试与 replay e2e 把守。因此 fixture 可以表达生产折叠永不产出的状态。

packages/client/test-runtime/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@deepseek-ai/dsh-client-test-runtime",
+  "description": "jsdom slot test runtime: real Cordis Context + SlotsService + web-react renderer with test-owned session/workspace doubles for feature specs",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "vitest": "^4.1.8"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
+    "@deepseek-ai/dsh-client-web-react": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-client-web-react": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}

packages/client/test-runtime/src/fixtures.ts

@@ -0,0 +1,82 @@
+/** Session/workspace fixture shapes and snapshot defaults for the test runtime. */
+import type {
+  ConversationSnapshot, ISession, SessionId, SessionSummary, WorkspaceListState,
+} from '@deepseek-ai/dsh-client-runtime/client'
+
+/**
+ * Fixture overrides for the session behavior face: any subset of the
+ * production ISession verbs (typed against it, so a face change surfaces
+ * here at compile time), plus extra members feature-specific casts consume.
+ * The open Record tail means a misnamed EXTRA member is not caught by the
+ * compiler (it grafts as dead weight); the ISession verbs stay safe — a
+ * misnamed verb leaves the fail-loud stub in place, which names itself at
+ * the first call.
+ */
+export type SessionBehaviorOverrides = Partial<ISession> & Record<string, unknown>
+
+/**
+ * act-wrapped mutation runner shared by every runtime object: public mutators
+ * funnel through it so tests never handle SlotCore microtask batching or
+ * React act themselves.
+ */
+export type Stabilizer = (fn: () => void | Promise<void>) => Promise<void>
+
+/**
+ * Session fixture accepted by {@link TestSessions.add}: identity plus optional
+ * snapshot/list-row overrides and the session behavior face the feature under
+ * test actually calls (kept open — the runtime never fakes methods a test did
+ * not supply, so an unstubbed call fails loud at the call site).
+ */
+export interface SessionFixture {
+  id: string
+  /** Overrides merged over {@link conversationSnapshot} (sessionId comes from `id`). */
+  snapshot?: Partial<Omit<ConversationSnapshot, 'sessionId'>>
+  /** List-row overrides merged over the defaults derived from `id`. */
+  summary?: Partial<Omit<SessionSummary, 'id'>>
+  /** Session behavior face: exactly the methods the feature under test calls (ISession subset + extras). */
+  session?: SessionBehaviorOverrides
+}
+
+/**
+ * A complete quiescent conversation snapshot (open window, no traffic).
+ * @param sessionId - owning session id.
+ * @returns the snapshot; spread fixture overrides on top.
+ */
+export function conversationSnapshot(sessionId: SessionId): ConversationSnapshot {
+  return {
+    sessionId,
+    nodes: [],
+    foldDegraded: false,
+    partial: null,
+    runningCalls: [],
+    codeDispatches: new Map(),
+    pending: [],
+    queue: [],
+    running: false,
+    composerPhase: 'active',
+    removed: false,
+    openState: 'open',
+    openError: null,
+    hasMore: false,
+    loadingOlder: false,
+    promptError: null,
+    blank: false,
+    lastAgentError: null,
+  }
+}
+
+/**
+ * A ready workspace list with no workspaces (the shape WorkspacesService
+ * projects after both baselines land).
+ * @returns the initial state of the test workspaces store.
+ */
+export function workspaceListState(): WorkspaceListState {
+  return {
+    items: [],
+    state: 'idle',
+    phase: 'ready',
+    error: null,
+    baselinesReady: true,
+    recentWorkspaceId: undefined,
+  }
+}

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

@@ -0,0 +1,372 @@
+/**
+ * jsdom slot test runtime: a real small runtime — Cordis `Context`, the
+ * runtime `SlotsService`, and the web-react renderer — assembled around
+ * test-owned session/workspace doubles, so feature specs exercise
+ * declaration, registration, scope, store, inject, rendering, updates, and
+ * disposal without hand-building the machinery per suite.
+ *
+ * Not part of the product plugin graph (no `dshClient`); feature packages
+ * depend on it in devDependencies only. It copies no SlotCore/renderer/store
+ * machinery — everything mounts the production implementations.
+ * @module @deepseek-ai/dsh-client-test-runtime
+ */
+/* eslint-disable @typescript-eslint/no-redundant-type-constituents --
+ * `keyof SlotMap & string` is the declare-merge key pattern (see ui-slots):
+ * this compilation unit sees only the runtime's 'root' row, but consumer
+ * programs merge their own keys in; the rule fires on the narrow-map view. */
+import { Context, Inject } from 'cordis'
+import type { Fiber, Plugin } from 'cordis'
+import { createElement, Fragment, useSyncExternalStore } from 'react'
+import type { ReactNode } from 'react'
+import { act, render, within } from '@testing-library/react'
+import type { RenderResult } from '@testing-library/react'
+import type { queries } from '@testing-library/dom'
+import type { BoundFunctions } from '@testing-library/dom'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { createSlotRenderer } from '@deepseek-ai/dsh-client-web-react'
+import type {
+  ChildrenDecl, ComposedProps, OwnerOf, SlotComponent, SlotMap, SlotRendererHost, StoreInstanceLike,
+} from '@deepseek-ai/dsh-client-ui-slots'
+import { registerDomSnapshotSerializer } from './snapshot.ts'
+import { TestSessions } from './sessions.ts'
+import { TestWorkspaces } from './workspaces.ts'
+import type { Stabilizer } from './fixtures.ts'
+
+export { domSnapshotSerializer, registerDomSnapshotSerializer } from './snapshot.ts'
+export { FixtureSession, TestSessions } from './sessions.ts'
+export { TestWorkspaces } from './workspaces.ts'
+export { conversationSnapshot, workspaceListState } from './fixtures.ts'
+export type { SessionBehaviorOverrides, SessionFixture, Stabilizer } from './fixtures.ts'
+
+/** Erased register face for the internal root call (the public declare seam holds the typing). */
+type ErasedRegister = (options: object, component: unknown) => () => void
+
+/**
+ * One rendered slot's local view, from {@link SlotTestRuntime.renderSlot}:
+ * the `data-slot` wrapper is the snapshot root (`expect(view.container)
+ * .toMatchSnapshot()` captures exactly this slot's output), Testing Library
+ * queries are bound inside it, and `update` re-renders with new owner props.
+ */
+export interface SlotView<K extends keyof SlotMap & string> {
+  /** The `<div data-slot="<key>">` wrapper around the slot's rendered output. */
+  readonly container: HTMLElement
+  /** Testing Library queries scoped to {@link SlotView.container}. */
+  readonly view: BoundFunctions<typeof queries>
+  /**
+   * Replace the owner props and flush the re-render (the render-site update:
+   * in production the owner recomputes the share and React re-renders).
+   * @param owner - the next owner props share.
+   */
+  update(owner: OwnerOf<K>): void
+}
+
+/**
+ * Mounted feature plugin handle: the live fiber plus an act-wrapped,
+ * idempotent dispose (unload cascade: entries, declared child slots, store
+ * instances, and provided services all fall together).
+ */
+export interface FeatureHandle {
+  /** The plugin's live Cordis fiber (state assertions, escape hatch). */
+  readonly fiber: Fiber
+  /**
+   * Dispose the plugin fiber inside React act; repeated calls no-op.
+   * @returns completion of the unload cascade.
+   */
+  dispose(): Promise<void>
+}
+
+/**
+ * Owner-props cell behind the auto frame: one external store the frame
+ * subscribes to, so {@link SlotTestRuntime.renderSlot} and
+ * {@link SlotView.update} drive React through the standard uSES seam.
+ */
+class OwnerPropsCell {
+  private readonly owners = new Map<string, object>()
+  private readonly listeners = new Set<() => void>()
+  private version = 0
+
+  /** Snapshot version for uSES pairing (bumped on every set). */
+  readonly getVersion = (): number => this.version
+
+  /**
+   * Subscribe to owner-props changes.
+   * @param fn - change callback.
+   * @returns unsubscribe.
+   */
+  readonly subscribe = (fn: () => void): (() => void) => {
+    this.listeners.add(fn)
+    return () => { this.listeners.delete(fn) }
+  }
+
+  /**
+   * Install or replace one key's owner props and notify (synchronous; the
+   * caller wraps in act).
+   * @param key - slot key.
+   * @param owner - owner props share.
+   */
+  set(key: string, owner: object): void {
+    this.owners.set(key, owner)
+    this.version += 1
+    for (const fn of [...this.listeners]) fn()
+  }
+
+  /** Keys with supplied owner props, in first-supply order. */
+  entries(): readonly (readonly [string, object])[] {
+    return [...this.owners.entries()]
+  }
+}
+
+/**
+ * The test-owned 'root' occupant: declares the child slots a suite needs
+ * through the REAL `slots.register`, with a caller-supplied minimal frame —
+ * the runtime never guesses a feature's page structure.
+ */
+export class TestRoot {
+  private disposeEntry: (() => void) | undefined
+
+  /**
+   * @param slots - the runtime SlotsService.
+   * @param stabilize - the owning runtime's act wrapper.
+   */
+  constructor(private readonly slots: SlotsService, private readonly stabilize: Stabilizer) {}
+
+  /**
+   * Register the root frame, declaring (and thereby claiming) the child
+   * slots. One declaration per runtime — a second call fails loud in the
+   * core ('root' is a single slot).
+   * @param children - child-slot declaration table (declaration + render authorization + runtime spec).
+   * @param frame - minimal frame component; its props derive from the declared keys (composed-props contract).
+   * @returns completion of the act-wrapped registration.
+   */
+  async declare<const D extends ChildrenDecl>(
+    children: D,
+    frame: SlotComponent<ComposedProps<'root', keyof NoInfer<D> & keyof SlotMap & string, undefined, object>>,
+  ): Promise<void> {
+    await this.stabilize(() => {
+      // Erased hop (same pattern as SlotsService's own implementation arm);
+      // the declare signature above is the typed seam.
+      this.disposeEntry = (this.slots.register as unknown as ErasedRegister)({ name: 'root', children }, frame)
+    })
+  }
+
+  /** Remove the root registration and collapse its declarations (runtime dispose path). */
+  release(): void {
+    this.disposeEntry?.()
+    this.disposeEntry = undefined
+  }
+}
+
+/**
+ * The assembled test runtime. Obtain via {@link SlotTestRuntime.create};
+ * dispose with {@link SlotTestRuntime.dispose} (afterEach). Public mutators
+ * are act-wrapped throughout — tests never handle SlotCore microtask
+ * batching or React act themselves.
+ */
+export class SlotTestRuntime {
+  /** The runtime's Cordis root (escape hatch: extra services via `ctx.provide`, raw `ctx.plugin` mounts). */
+  readonly ctx: Context
+  /** The production SlotsService mounted on {@link SlotTestRuntime.ctx}. */
+  readonly slots: SlotsService
+  /** The test-owned 'root' occupant. */
+  readonly root: TestRoot
+  /** Sessions double (list/current observable, cells, scopes, behavior faces). */
+  readonly sessions: TestSessions
+  /** Workspaces double (list observable, recorded intent actions). */
+  readonly workspaces: TestWorkspaces
+
+  private readonly stabilizer: Stabilizer = async (fn) => {
+    await act(async () => { await fn() })
+  }
+
+  private host: SlotRendererHost | undefined
+  private readonly views: RenderResult[] = []
+  private readonly handles: FeatureHandle[] = []
+  private disposed = false
+  /** Auto-frame state ({@link SlotTestRuntime.declare} / {@link SlotTestRuntime.renderSlot}). */
+  private readonly ownerCell = new OwnerPropsCell()
+  private readonly autoDeclared = new Set<string>()
+  private autoRootView: RenderResult | undefined
+
+  private constructor(ctx: Context, slots: SlotsService) {
+    this.ctx = ctx
+    this.slots = slots
+    this.root = new TestRoot(slots, this.stabilizer)
+    this.sessions = new TestSessions(this.stabilizer, ctx)
+    this.workspaces = new TestWorkspaces(this.stabilizer)
+    ctx.provide('sessions', this.sessions)
+    ctx.provide('workspaces', this.workspaces)
+    // Capturing install: the production renderer does the rendering; the
+    // wrapper only takes the host face for storeOf (no machinery copied).
+    const renderer = createSlotRenderer()
+    slots.install({
+      renderRoot: (host, ownerProps) => {
+        this.host = host
+        return renderer.renderRoot(host, ownerProps)
+      },
+    })
+  }
+
+  /**
+   * Assemble a runtime: real Context, mounted SlotsService, installed
+   * renderer, and the session/workspace doubles provided as services.
+   * @returns the ready runtime.
+   */
+  static async create(): Promise<SlotTestRuntime> {
+    registerDomSnapshotSerializer()
+    const ctx = new Context()
+    const fiber = ctx.plugin(SlotsService)
+    await fiber.await()
+    return new SlotTestRuntime(ctx, ctx.get('slots') as SlotsService)
+  }
+
+  /**
+   * Provide an extra service the feature under test injects (e.g. a layout
+   * fake). Sugar over `ctx.provide`, typed against the Context declaration
+   * merge: for a declared service name the fake must be a subset of that
+   * service's outward face (Partial — supply only what the feature calls),
+   * so a production face change breaks the fake at compile time. Undeclared
+   * names stay unchecked (ad-hoc test services).
+   * @param name - service name.
+   * @param value - service implementation (test double).
+   */
+  provide<K extends string>(name: K, value: K extends keyof Context ? Partial<Context[K]> : unknown): void {
+    this.ctx.provide(name, value)
+  }
+
+  /**
+   * Mount a feature plugin on a real fiber. Required services are prechecked
+   * so a missing provider fails loud instead of suspending the fiber forever
+   * (deliberate load-order suspension tests use `ctx.plugin` directly).
+   * @param plugin - plugin value (function, class, or `{ inject, apply }` object).
+   * @returns handle owning the fiber's explicit disposal.
+   */
+  async mount(plugin: Plugin): Promise<FeatureHandle> {
+    const required = Object.keys(Inject.resolve((plugin as { inject?: Inject }).inject))
+    const missing = required.filter(name => this.ctx.get(name) === undefined)
+    if (missing.length > 0) {
+      throw new Error(`mount would suspend: missing service(s) ${missing.join(', ')} — provide() them first`)
+    }
+    const fiber = this.ctx.plugin(plugin)
+    await this.stabilizer(async () => {
+      await fiber.await()
+    })
+    let disposed = false
+    const handle: FeatureHandle = {
+      fiber,
+      dispose: async () => {
+        if (disposed) return
+        disposed = true
+        await this.stabilizer(() => fiber.dispose())
+      },
+    }
+    this.handles.push(handle)
+    return handle
+  }
+
+  /**
+   * Render the root slot tree through the ctx-level entry (the shell's own
+   * seam): `ctx.slots.renderSlot('root', {})` under Testing Library.
+   * @returns the Testing Library view.
+   */
+  renderRoot(): RenderResult {
+    const view = render(createElement(Fragment, null, this.slots.renderSlot('root', {})))
+    this.views.push(view)
+    return view
+  }
+
+  /**
+   * Declare child slots under an auto-generated root frame — the single-slot
+   * mounting path for local DOM snapshots. Each key later supplied through
+   * {@link SlotTestRuntime.renderSlot} renders inside its own
+   * `<div data-slot="<key>">` wrapper (the snapshot root). Mutually exclusive
+   * with {@link TestRoot.declare} ('root' is a single slot); one call per
+   * runtime.
+   * @param children - child-slot declaration table (same contract as TestRoot.declare).
+   * @returns completion of the act-wrapped registration.
+   */
+  async declare(children: ChildrenDecl): Promise<void> {
+    for (const key of Object.keys(children)) this.autoDeclared.add(key)
+    const cell = this.ownerCell
+    const AutoFrame = (props: { renderSlot: (key: string, owner: object) => ReactNode }) => {
+      useSyncExternalStore(cell.subscribe, cell.getVersion)
+      return createElement(Fragment, null, cell.entries().map(([key, owner]) =>
+        createElement('div', { 'data-slot': key, key }, props.renderSlot(key, owner))))
+    }
+    await this.root.declare(children as never, AutoFrame as never)
+  }
+
+  /**
+   * Render one declared slot with its owner props and return the local view.
+   * The whole root tree mounts through the production assembly path
+   * (renderer, scope providers, store axis); only this key's output lands in
+   * the returned container. Call again with another key to view a sibling
+   * slot of the same tree.
+   * @param key - a key declared through {@link SlotTestRuntime.declare}.
+   * @param owner - owner props share for the render site.
+   * @returns the slot-local view (snapshot container, scoped queries, owner updates).
+   */
+  renderSlot<K extends keyof SlotMap & string>(key: K, owner: OwnerOf<K>): SlotView<K> {
+    if (!this.autoDeclared.has(key)) {
+      throw new Error(`renderSlot('${key}') without declare() — declare the key first (or use root.declare for a custom frame)`)
+    }
+    const install = (next: object): void => {
+      // Synchronous cell write inside act: the frame re-renders through uSES.
+      act(() => {
+        this.ownerCell.set(key, next)
+      })
+    }
+    install(owner)
+    this.autoRootView ??= this.renderRoot()
+    const container = this.autoRootView.container.querySelector(`[data-slot="${key}"]`)
+    if (!(container instanceof HTMLElement)) {
+      throw new Error(`renderSlot('${key}'): the auto frame rendered no wrapper — was the runtime already disposed?`)
+    }
+    return { container, view: within(container), update: install }
+  }
+
+  /**
+   * Resolve the store instance the renderer would hand a slot's component
+   * (identity assertions, action-driven writes). Requires a prior
+   * {@link SlotTestRuntime.renderRoot} — the host face exists only inside the
+   * installed renderer, exactly as in production.
+   * @param key - slot key whose first entry declares the store.
+   * @param scopeKey - session id for session-scope slots; omit for root scope.
+   * @returns the live store instance.
+   */
+  storeOf(key: keyof SlotMap & string, scopeKey?: string): StoreInstanceLike {
+    if (this.host === undefined) {
+      throw new Error('storeOf before renderRoot() — the host face exists only inside the installed renderer')
+    }
+    const entry = this.host.entriesOf(key)[0]
+    if (entry === undefined) throw new Error(`storeOf('${key}'): no registration on the ledger`)
+    const instance = this.host.storeOf(entry, scopeKey)
+    if (instance === undefined) throw new Error(`storeOf('${key}'): the entry declares no store`)
+    return instance
+  }
+
+  /**
+   * Flush pending ledger/store notifications inside act — for mutations made
+   * outside the runtime's own methods (e.g. a direct `slots.register`).
+   * @returns completion of the act pass.
+   */
+  async flush(): Promise<void> {
+    await this.stabilizer(() => {})
+  }
+
+  /**
+   * Tear down: unmount React trees first, then dispose feature fibers, the
+   * root registration, minted session scopes, and persisted test state.
+   * Idempotent.
+   * @returns completion of the teardown.
+   */
+  async dispose(): Promise<void> {
+    if (this.disposed) return
+    this.disposed = true
+    this.autoRootView = undefined
+    for (const view of this.views.splice(0)) view.unmount()
+    for (const handle of this.handles.splice(0)) await handle.dispose()
+    this.root.release()
+    await this.sessions.disposeScopes()
+    localStorage.clear()
+  }
+}

packages/client/test-runtime/src/invariant.ts

@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-test-runtime`.
+ * @module @deepseek-ai/dsh-client-test-runtime/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-test-runtime'
+
+/** Cordis companion plugin name. */
+export const name = 'client-test-runtime-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this test-support package owns no production event
+ * stream or mutable data — it assembles the runtime SlotsService and renderer
+ * (whose packages own their invariants) around test doubles; its own behavior
+ * is exercised by its package tests.
+ */
+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/test-runtime/src/sessions.ts

@@ -0,0 +1,390 @@
+/** Test-owned sessions face: the SlotsService host contract over declarative fixtures. */
+import type { Context } from 'cordis'
+import { createScope, scopeOf, SessionProvideChannel } from '@deepseek-ai/dsh-client-runtime/client'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  ConversationSnapshot, ISessions, ObservableSnapshot, ProjectionsFace, SessionFace, SessionId,
+  SessionListState, SessionProvideDescriptor, SessionSummary, SnapshotStore,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { HostObservable, SessionMaybeProvideInfo, SessionProvideInfo } from '@deepseek-ai/dsh-client-ui-slots'
+import { conversationSnapshot } from './fixtures.ts'
+import type { SessionFixture, Stabilizer } from './fixtures.ts'
+
+/**
+ * The fixture-backed session face: conversation reads delegate to the
+ * fixture's snapshot store; ISession verbs are fail-loud stubs unless the
+ * fixture supplies them (the runtime never fakes behavior a test did not
+ * declare — an unstubbed call names itself instead of half-working). Extra
+ * fixture methods are grafted verbatim for feature-side casts.
+ */
+export class FixtureSession implements SessionFace {
+  /**
+   * The useProjection seat: identity-stable per-key faces over the fixture's
+   * projection values (set via {@link TestSessions.setProjection}).
+   */
+  readonly projections: ProjectionsFace & { set(key: string, value: unknown): void }
+
+  /**
+   * @param sessionId - host identity (branded view of the fixture id).
+   * @param store - conversation snapshot store (updateSnapshot writes it).
+   * @param overrides - fixture-declared behavior face, grafted over the stubs.
+   */
+  constructor(
+    readonly sessionId: SessionId,
+    private readonly store: SnapshotStore<ConversationSnapshot>,
+    overrides: Record<string, unknown>,
+  ) {
+    const values = new Map<string, unknown>()
+    const listeners = new Map<string, Set<() => void>>()
+    const faces = new Map<string, ObservableSnapshot<unknown>>()
+    this.projections = {
+      faceOf: (key: string) => {
+        let face = faces.get(key)
+        if (face === undefined) {
+          face = {
+            getSnapshot: () => values.get(key),
+            subscribe: (fn: () => void) => {
+              const set = listeners.get(key) ?? new Set()
+              set.add(fn)
+              listeners.set(key, set)
+              return () => { set.delete(fn) }
+            },
+          }
+          faces.set(key, face)
+        }
+        return face
+      },
+      set: (key: string, value: unknown) => {
+        values.set(key, value)
+        for (const fn of [...(listeners.get(key) ?? [])]) fn()
+      },
+    }
+    Object.assign(this, overrides)
+  }
+
+  /** @returns the fixture conversation snapshot (useSession read side). */
+  getSnapshot(): ConversationSnapshot {
+    return this.store.getSnapshot()
+  }
+
+  /**
+   * Subscribe to fixture snapshot changes.
+   * @param fn - change callback.
+   * @returns unsubscribe.
+   */
+  subscribe(fn: () => void): () => void {
+    return this.store.subscribe(fn)
+  }
+
+  /**
+   * Fail-loud stub; supply `prompt` on the fixture's session face to exercise it.
+   * @returns never — always throws.
+   */
+  prompt(): never {
+    throw new Error(`test session "${this.sessionId}": prompt is not stubbed — supply it on the fixture's session face`)
+  }
+
+  /**
+   * Fail-loud stub; supply `cancel` on the fixture's session face to exercise it.
+   * @returns never — always throws.
+   */
+  cancel(): never {
+    throw new Error(`test session "${this.sessionId}": cancel is not stubbed — supply it on the fixture's session face`)
+  }
+
+  /**
+   * Fail-loud stub; supply `loadOlder` on the fixture's session face to exercise it.
+   * @returns never — always throws.
+   */
+  loadOlder(): never {
+    throw new Error(`test session "${this.sessionId}": loadOlder is not stubbed — supply it on the fixture's session face`)
+  }
+}
+
+/** One live test session: fixture-derived stores plus its minted scope state. */
+interface SessionRecord {
+  summary: SessionSummary
+  snapshot: SnapshotStore<ConversationSnapshot>
+  session: FixtureSession
+  scope: Context | undefined
+  scopeFiber: { dispose(): Promise<void> } | undefined
+  /** Materialized standard-props bundle (identity-stable per session; invalidated on roster change). */
+  provideInfo: SessionProvideInfo | undefined
+}
+
+/** Test binding shape handed to provider resolvers and feature injects (a SessionBinding whose session is the fixture face). */
+export interface TestSessionBinding {
+  readonly sessionId: SessionId
+  readonly session: FixtureSession
+  readonly ctx: Context
+}
+
+/**
+ * Sessions test double behind the renderer host and feature injects: owns the
+ * list/current observable, the standard-props provide channel (the runtime's
+ * `useSession` contribution included), scope minting through the production
+ * `createScope`, and the session behavior face supplied per fixture.
+ *
+ * Implements the same ISessions face features receive as `ctx.sessions`, so
+ * a production face change breaks this double at compile time; the extra
+ * members (add/updateSnapshot/setCurrent/remove/behavior/calls and the
+ * legacy provideInfo/maybeProvideInfo lookups) are bench-only surface.
+ */
+export class TestSessions implements ISessions {
+  /** The useSessions standard feed (list rows + current selection). */
+  readonly list: SnapshotStore<SessionListState>
+  /**
+   * Atomic current-session provide projection (production SessionsService
+   * mirror): selection changes and provider-roster changes publish through
+   * this one source — the member the SlotsService host face hands the
+   * renderer's SessionProvider.
+   */
+  readonly currentProvideInfo: HostObservable<SessionMaybeProvideInfo>
+  private readonly records = new Map<SessionId, SessionRecord>()
+  /** The production provide channel (roster, materialization rules, current projection) — no test-side mirror. */
+  private readonly channel: SessionProvideChannel
+
+  /** Calls observed on the service-level face (open/clear), newest last. */
+  readonly calls: { method: 'open' | 'clear'; args: unknown[] }[] = []
+
+  /**
+   * @param stabilize - the owning runtime's act wrapper.
+   * @param rootCtx - the runtime's Cordis root; scope fibers mount under it.
+   */
+  constructor(private readonly stabilize: Stabilizer, private readonly rootCtx: Context) {
+    this.list = createSnapshotStore<SessionListState>({
+      ids: [], byId: {}, current: undefined, phase: 'ready',
+    })
+    this.channel = new SessionProvideChannel({
+      rebuildBundles: () => {
+        for (const record of this.records.values()) {
+          if (record.provideInfo !== undefined) {
+            record.provideInfo = this.channel.materializeInfo(this.bindingOf(record.session.sessionId, record))
+          }
+        }
+      },
+      resolveCurrent: () => this.maybeProvideInfo(this.list.getSnapshot().current),
+    })
+    this.currentProvideInfo = this.channel.currentProvideInfo
+    // The projection follows every current write, as in production.
+    this.list.subscribe(() => { this.channel.publishCurrent() })
+  }
+
+  /**
+   * Add a session from a fixture and (by default) make it current.
+   * @param fixture - identity + snapshot/summary overrides + behavior face.
+   * @param opts - pass `current: false` to add without selecting.
+   * @returns the stable session id (branded view of `fixture.id`).
+   */
+  async add(fixture: SessionFixture, opts?: { current?: boolean }): Promise<SessionId> {
+    const id = fixture.id as SessionId
+    if (this.records.has(id)) throw new Error(`test session "${id}" already added`)
+    const summary: SessionSummary = {
+      id,
+      displayTitle: fixture.id,
+      running: false,
+      blank: false,
+      updatedAt: this.records.size + 1,
+      ...fixture.summary,
+    }
+    const snapshot = createSnapshotStore<ConversationSnapshot>({
+      ...conversationSnapshot(id),
+      ...fixture.snapshot,
+    })
+    this.records.set(id, {
+      summary,
+      snapshot,
+      session: new FixtureSession(id, snapshot, fixture.session ?? {}),
+      scope: undefined,
+      scopeFiber: undefined,
+      provideInfo: undefined,
+    })
+    await this.stabilize(() => {
+      this.list.update((draft) => {
+        draft.ids.push(id)
+        draft.byId[id] = summary
+        if (opts?.current !== false) draft.current = id
+      })
+    })
+    return id
+  }
+
+  /**
+   * Update a session's conversation snapshot through an immer draft (the
+   * live-stream stand-in: components subscribed via useSession re-render).
+   * @param id - session id.
+   * @param mutate - draft mutator.
+   */
+  async updateSnapshot(id: string, mutate: (draft: ConversationSnapshot) => void): Promise<void> {
+    const record = this.require(id)
+    await this.stabilize(() => { record.snapshot.update(mutate) })
+  }
+
+  /**
+   * Switch the current selection (undefined = the no-session empty state).
+   * @param id - session id to select, or undefined to clear.
+   */
+  async setCurrent(id: string | undefined): Promise<void> {
+    if (id !== undefined) this.require(id)
+    await this.stabilize(() => {
+      this.list.update((draft) => { draft.current = id as SessionId | undefined })
+    })
+  }
+
+  /**
+   * Remove a session: list row, scope fiber, and per-session store instances
+   * (with persisted state) die together — the same single lifecycle axis the
+   * production SessionsService drives on session death, minus staging.
+   * @param id - session id.
+   */
+  async remove(id: string): Promise<void> {
+    const record = this.require(id)
+    this.records.delete(id as SessionId)
+    await this.stabilize(async () => {
+      this.list.update((draft) => {
+        draft.ids = draft.ids.filter(existing => existing !== id)
+        const { [id as SessionId]: _dead, ...rest } = draft.byId
+        draft.byId = rest
+        if (draft.current === id) draft.current = undefined
+      })
+      if (record.scopeFiber !== undefined) await record.scopeFiber.dispose()
+      this.rootCtx.get('slots')?.pruneStoreScope(id)
+    })
+  }
+
+  /**
+   * Register a per-session standard-props provider (production `provide`
+   * contract: hooks become `use<Name>` selector hooks on the render side,
+   * props spread verbatim; duplicate names fail loud at materialization).
+   * @param descriptor - static member roster plus per-session resolver.
+   * @returns disposer removing the provider.
+   */
+  provide(descriptor: SessionProvideDescriptor): () => void {
+    return this.channel.provide(descriptor)
+  }
+
+  /**
+   * Resolve the definite per-session standard-props bundle (host face member).
+   * @param id - session id.
+   * @returns the identity-stable bundle, or undefined for unknown sessions.
+   */
+  provideInfo(id: string): SessionProvideInfo | undefined {
+    const record = this.records.get(id as SessionId)
+    if (record === undefined) return undefined
+    record.provideInfo ??= this.channel.materializeInfo(this.bindingOf(id as SessionId, record))
+    return record.provideInfo
+  }
+
+  /**
+   * Resolve the current-session-optional standard kit (host face member):
+   * unknown or absent ids return the static no-session projection.
+   * @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.channel.maybeInfo
+  }
+
+  /**
+   * Resolve (mint on first touch) the session-scoped Cordis context through
+   * the production `createScope`, so real `scopeOf`/scope-addressed services
+   * resolve it.
+   * @param id - session id.
+   * @returns the scoped context, or undefined for unknown sessions.
+   */
+  scope(id: string): Context | undefined {
+    const record = this.records.get(id as SessionId)
+    if (record === undefined) return undefined
+    if (record.scope === undefined) {
+      const handle = createScope(this.rootCtx, id as SessionId)
+      record.scope = handle.ctx
+      record.scopeFiber = handle.fiber
+    }
+    return record.scope
+  }
+
+  /**
+   * Session assembly binding (inject factories and provide resolvers receive it).
+   * @param id - session id.
+   * @returns sessionId + behavior face + scoped ctx, or undefined when unknown.
+   */
+  binding(id: string): TestSessionBinding | undefined {
+    const record = this.records.get(id as SessionId)
+    if (record === undefined) return undefined
+    return this.bindingOf(id as SessionId, record)
+  }
+
+  /**
+   * Read the session scope tag off a context (service-method seam mirror).
+   * @param ctx - any client context.
+   * @returns the session id, or undefined on root contexts.
+   */
+  scopeOf(ctx: Context): SessionId | undefined {
+    return scopeOf(ctx)
+  }
+
+  /**
+   * Resolve the scoped session face off a context (production `sessionOf`
+   * mirror).
+   * @param ctx - any client context.
+   * @returns the fixture session face, or undefined off-scope.
+   */
+  sessionOf(ctx: Context): SessionFace | undefined {
+    const id = scopeOf(ctx)
+    if (id === undefined) return undefined
+    return this.records.get(id)?.session
+  }
+
+  /**
+   * Service-level selection call (recorded, then applied to the list store
+   * synchronously — inject callbacks call this outside any act window; the
+   * store notify is microtask-batched so the next stabilized step observes it).
+   * @param id - session id.
+   */
+  open(id: SessionId): void {
+    this.calls.push({ method: 'open', args: [id] })
+    this.require(id)
+    this.list.update((draft) => { draft.current = id })
+  }
+
+  /** Clear the current selection (recorded; the production no-session flow). */
+  clear(): void {
+    this.calls.push({ method: 'clear', args: [] })
+    this.list.update((draft) => { draft.current = undefined })
+  }
+
+  /**
+   * The session face of a fixture (typed view for assertions; fixture
+   * behavior methods are grafted onto it).
+   * @param id - session id.
+   * @returns the FixtureSession the binding and provide channel carry.
+   */
+  behavior(id: string): FixtureSession {
+    return this.require(id).session
+  }
+
+  /** Dispose minted scope fibers (runtime dispose path). */
+  async disposeScopes(): Promise<void> {
+    for (const record of this.records.values()) {
+      if (record.scopeFiber !== undefined) {
+        await record.scopeFiber.dispose()
+        record.scope = undefined
+        record.scopeFiber = undefined
+      }
+    }
+  }
+
+  private bindingOf(id: SessionId, record: SessionRecord): TestSessionBinding {
+    const ctx = this.scope(id)
+    /* v8 ignore next 2 -- bindingOf only runs for a live record, whose scope
+     * always resolves; kept so a future caller cannot mint a ctx-less binding. */
+    if (ctx === undefined) throw new Error(`test session "${id}" resolved no scope`)
+    return { sessionId: id, session: record.session, ctx }
+  }
+
+  private require(id: string): SessionRecord {
+    const record = this.records.get(id as SessionId)
+    if (record === undefined) throw new Error(`test session "${id}" is not added`)
+    return record
+  }
+}

packages/client/test-runtime/src/snapshot.ts

@@ -0,0 +1,89 @@
+/**
+ * DOM snapshot hygiene: a vitest snapshot serializer that keeps `.snap`
+ * files structural. Two normalizations, both on a clone (the live DOM is
+ * untouched, so class/tag queries keep working):
+ *
+ * - CSS-module scoped class names (`_frame_334d2d`, this repo's
+ *   `_[local]_[hash]` shape) fold back to their semantic local (`frame`), so
+ *   CSS edits do not churn snapshots.
+ * - `<svg>` internals collapse to a `data-content` fingerprint on the svg
+ *   element: path geometry is print noise, but the fingerprint still flips
+ *   when an icon's artwork actually changes.
+ */
+import { expect } from 'vitest'
+import type { SnapshotSerializer } from 'vitest'
+
+/** One scoped class token: `_<local>_<hash>` (local may itself contain underscores). */
+const SCOPED_CLASS = /^_(.+)_[a-z0-9]+$/
+
+/** Fold scoped tokens in one class attribute value; foreign tokens pass through. */
+function normalizeClassValue(value: string): string {
+  return value
+    .split(/\s+/)
+    .filter(token => token !== '')
+    .map(token => token.replace(SCOPED_CLASS, '$1'))
+    .join(' ')
+}
+
+/** FNV-1a 32-bit over the svg markup: deterministic, dependency-free fingerprint. */
+function fingerprint(markup: string): string {
+  let hash = 0x811c9dc5
+  for (let i = 0; i < markup.length; i++) {
+    hash ^= markup.charCodeAt(i)
+    hash = Math.imul(hash, 0x01000193)
+  }
+  return (hash >>> 0).toString(16).padStart(8, '0')
+}
+
+/** svg elements of a subtree, the root included when it is one. */
+function svgsOf(root: Element): Element[] {
+  const svgs: Element[] = [...root.querySelectorAll('svg')]
+  if (root.tagName.toLowerCase() === 'svg') svgs.unshift(root)
+  return svgs
+}
+
+/** Whether serializing this subtree needs a normalized clone. */
+function needsNormalization(root: Element): boolean {
+  const scoped = [root, ...root.querySelectorAll('[class]')].some((el) => {
+    const value = el.getAttribute('class')
+    return value !== null && value.split(/\s+/).some(token => SCOPED_CLASS.test(token))
+  })
+  return scoped || svgsOf(root).some(svg => svg.childNodes.length > 0)
+}
+
+/**
+ * The serializer plugin. Matches DOM elements whose subtree carries a scoped
+ * class or svg internals; serializes a normalized clone, which no longer
+ * matches, so printing falls through to the built-in DOM element serializer.
+ */
+export const domSnapshotSerializer: SnapshotSerializer = {
+  test(value: unknown): boolean {
+    return typeof Element !== 'undefined' && value instanceof Element && needsNormalization(value)
+  },
+  serialize(value, config, indentation, depth, refs, printer): string {
+    const clone = (value as Element).cloneNode(true) as Element
+    for (const el of [clone, ...clone.querySelectorAll('[class]')]) {
+      const raw = el.getAttribute('class')
+      if (raw !== null) el.setAttribute('class', normalizeClassValue(raw))
+    }
+    for (const svg of svgsOf(clone)) {
+      if (svg.childNodes.length === 0) continue
+      svg.setAttribute('data-content', fingerprint(svg.innerHTML))
+      svg.replaceChildren()
+    }
+    return printer(clone, config, indentation, depth, refs)
+  },
+}
+
+let registered = false
+
+/**
+ * Register {@link domSnapshotSerializer} with vitest's expect (idempotent).
+ * SlotTestRuntime.create() calls this; specs that snapshot DOM outside the
+ * runtime import and call it themselves.
+ */
+export function registerDomSnapshotSerializer(): void {
+  if (registered) return
+  registered = true
+  expect.addSnapshotSerializer(domSnapshotSerializer)
+}

packages/client/test-runtime/src/workspaces.ts

@@ -0,0 +1,147 @@
+/** Test-owned workspaces face: the renderer standard-kit observable plus recorded actions. */
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  IWorkspaces, SessionId, SnapshotStore, WorkspaceId, WorkspaceListState, WorkspaceView,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { workspaceListState } from './fixtures.ts'
+import type { Stabilizer } from './fixtures.ts'
+
+/**
+ * Workspaces test double. Implements the same IWorkspaces face features
+ * receive as `ctx.workspaces`, so a production face change breaks this
+ * double at compile time. Every action records into {@link
+ * TestWorkspaces.calls}; defaults are inert echoes — feature tests needing
+ * richer behavior replace them via {@link TestWorkspaces.stub}.
+ */
+export class TestWorkspaces implements IWorkspaces {
+  /** The useWorkspaces standard feed. */
+  readonly list: SnapshotStore<WorkspaceListState>
+
+  /** Calls observed on the action face, newest last. */
+  readonly calls: { method: string; args: unknown[] }[] = []
+
+  /** Replaceable action seat: feature tests may stub richer behavior. */
+  private readonly stubs = new Map<string, (...args: unknown[]) => unknown>()
+
+  /**
+   * @param stabilize - the owning runtime's act wrapper.
+   */
+  constructor(private readonly stabilize: Stabilizer) {
+    this.list = createSnapshotStore<WorkspaceListState>(workspaceListState())
+  }
+
+  /**
+   * Update the workspace list state through an immer draft.
+   * @param mutate - draft mutator.
+   */
+  async update(mutate: (draft: WorkspaceListState) => void): Promise<void> {
+    await this.stabilize(() => { this.list.update(mutate) })
+  }
+
+  /**
+   * Replace an action's behavior (the recorded call is still appended first).
+   * @param method - action name (e.g. 'connectWorkspace').
+   * @param impl - replacement behavior.
+   */
+  stub(method: string, impl: (...args: unknown[]) => unknown): void {
+    this.stubs.set(method, impl)
+  }
+
+  /**
+   * Connect a workspace to its reusable/new blank session (recorded). The
+   * default resolves the workspace id back as the session id; stub for
+   * cross-session flows.
+   * @param workspaceId - target workspace.
+   * @returns the connected session id.
+   */
+  async connectWorkspace(workspaceId: WorkspaceId): Promise<SessionId> {
+    this.calls.push({ method: 'connectWorkspace', args: [workspaceId] })
+    const stub = this.stubs.get('connectWorkspace')
+    if (stub !== undefined) return await (stub(workspaceId) as Promise<SessionId>)
+    return `session-of-${workspaceId}` as SessionId
+  }
+
+  /**
+   * New-session flow (recorded; stubbed behavior runs when installed).
+   * @param workspaceId - optional explicit workspace target.
+   */
+  startSession(workspaceId?: WorkspaceId): void {
+    this.calls.push({ method: 'startSession', args: [workspaceId] })
+    this.stubs.get('startSession')?.(workspaceId)
+  }
+
+  /**
+   * Create a Workspace (recorded). The default echoes a view derived from
+   * the input; stub for failure or list-coupled flows.
+   * @param input - exactly one Host create spelling.
+   * @returns the created Workspace view.
+   */
+  async create(input: { name: string } | { path: string }): Promise<WorkspaceView> {
+    this.calls.push({ method: 'create', args: [input] })
+    const stub = this.stubs.get('create')
+    if (stub !== undefined) return await (stub(input) as Promise<WorkspaceView>)
+    const title = 'name' in input ? input.name : input.path
+    return {
+      workspaceId: `ws-${title}` as WorkspaceId,
+      title,
+      path: 'path' in input ? input.path : `/${input.name}`,
+      sessionIds: [],
+    } as unknown as WorkspaceView
+  }
+
+  /**
+   * Open a path with the host OS default application (recorded; default no-op).
+   * @param path - host-resolvable path.
+   */
+  async openPath(path: string): Promise<void> {
+    this.calls.push({ method: 'openPath', args: [path] })
+    await (this.stubs.get('openPath')?.(path) as Promise<void> | undefined)
+  }
+
+  /**
+   * Directory picker (recorded). The default cancels (null); stub to select.
+   * @returns the picked path, or null.
+   */
+  async pickDirectory(): Promise<string | null> {
+    this.calls.push({ method: 'pickDirectory', args: [] })
+    const stub = this.stubs.get('pickDirectory')
+    if (stub !== undefined) return await (stub() as Promise<string | null>)
+    return null
+  }
+
+  /**
+   * Rename a Workspace (recorded). The default echoes a minimal view.
+   * @param workspaceId - target workspace.
+   * @param title - new title.
+   * @returns the updated view.
+   */
+  async rename(workspaceId: WorkspaceId, title: string): Promise<WorkspaceView> {
+    this.calls.push({ method: 'rename', args: [workspaceId, title] })
+    const stub = this.stubs.get('rename')
+    if (stub !== undefined) return await (stub(workspaceId, title) as Promise<WorkspaceView>)
+    return { workspaceId, title, path: `/${title}`, sessionIds: [] } as unknown as WorkspaceView
+  }
+
+  /**
+   * Delete a Workspace (recorded; default no-op).
+   * @param workspaceId - target workspace.
+   */
+  async delete(workspaceId: WorkspaceId): Promise<void> {
+    this.calls.push({ method: 'delete', args: [workspaceId] })
+    await (this.stubs.get('delete')?.(workspaceId) as Promise<void> | undefined)
+  }
+
+  /**
+   * Move an accounted session (recorded). The default echoes a minimal view.
+   * @param workspaceId - target workspace.
+   * @param sessionId - session to move.
+   * @param beforeSessionId - anchor; omitted appends.
+   * @returns the updated view.
+   */
+  async insertSessionBefore(workspaceId: WorkspaceId, sessionId: SessionId, beforeSessionId?: SessionId): Promise<WorkspaceView> {
+    this.calls.push({ method: 'insertSessionBefore', args: [workspaceId, sessionId, beforeSessionId] })
+    const stub = this.stubs.get('insertSessionBefore')
+    if (stub !== undefined) return await (stub(workspaceId, sessionId, beforeSessionId) as Promise<WorkspaceView>)
+    return { workspaceId, title: '', path: '', sessionIds: [sessionId] } as unknown as WorkspaceView
+  }
+}

packages/client/test-runtime/tests/__snapshots__/runtime.spec.tsx.snap

@@ -0,0 +1,37 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`single-slot mounting (declare + renderSlot) > folds class hashes and collapses svg internals in snapshots, leaving the live DOM alone 1`] = `
+<div
+  data-slot="trt.panel"
+>
+  <div
+    class="frame plain"
+  >
+    <span
+      class="label"
+    >
+      styled
+    </span>
+    <svg
+      aria-hidden="true"
+      data-content="2bfa09dc"
+      viewBox="0 0 16 16"
+    />
+  </div>
+</div>
+`;
+
+exports[`single-slot mounting edge arms > serializes childless svg untouched next to scoped classes 1`] = `
+<div
+  data-slot="trt.panel"
+>
+  <div
+    class="frame"
+  >
+    <svg
+      aria-hidden="true"
+      viewBox="0 0 1 1"
+    />
+  </div>
+</div>
+`;

packages/client/test-runtime/tests/invariant.spec.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import * as TestRuntimeInvariant from '@deepseek-ai/dsh-client-test-runtime/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+describe('invariant companion', () => {
+  it('registers under the package name with an empty installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    await expect(ctx.plugin(TestRuntimeInvariant).await()).resolves.toBeDefined()
+  })
+})

packages/client/test-runtime/tests/runtime.spec.tsx

@@ -0,0 +1,546 @@
+// @vitest-environment jsdom
+/**
+ * SlotTestRuntime behavior: root declaration + rendering, session
+ * add/update/switch/remove through the real renderer, shared store identity
+ * and scope pruning, feature mount/dispose cascade, and runtime disposal
+ * idempotence. All through the production SlotsService + createSlotRenderer
+ * stack — this suite is the fixture the migrated feature specs rely on.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup } from '@testing-library/react'
+import { defineStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SessionId, WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { PropsRenderSlots, SessionStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
+import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    'trt.panel': { kind: 'single'; scope: 'root'; owner: { label?: string } }
+    'trt.chat': { kind: 'single'; scope: 'session' }
+    'trt.rows': { kind: 'list'; scope: 'root' }
+  }
+}
+
+afterEach(cleanup)
+
+type FrameProps = PropsRenderSlots<'trt.panel' | 'trt.chat' | 'trt.rows'>
+
+/** Root frame declaring all three suite slots (render sites for each kind). */
+function Frame({ renderSlot, SessionProvider }: FrameProps) {
+  return (
+    <>
+      {renderSlot('trt.panel', { label: 'from-owner' }, { fallback: <i>no panel</i> })}
+      <SessionProvider empty={() => <i>no session</i>}>
+        {() => renderSlot('trt.chat', {})}
+      </SessionProvider>
+      {renderSlot('trt.rows', {})}
+    </>
+  )
+}
+
+const CHILDREN = {
+  'trt.panel': { kind: 'single', scope: 'root' },
+  'trt.chat': { kind: 'single', scope: 'session' },
+  'trt.rows': { kind: 'list', scope: 'root' },
+} as const
+
+async function runtimeWithFrame() {
+  const runtime = await SlotTestRuntime.create()
+  await runtime.root.declare(CHILDREN, Frame)
+  return runtime
+}
+
+describe('root declaration and rendering', () => {
+  it('renders declared slots through the real renderer: fallback, then a live registration, then unload', async () => {
+    const runtime = await runtimeWithFrame()
+    const view = runtime.renderRoot()
+    expect(view.container.textContent).toContain('no panel')
+
+    let dispose = (): void => {}
+    await runtime.flush() // no-op guard: flush outside mutations is safe
+    await (async () => {
+      dispose = runtime.slots.register(
+        { name: 'trt.panel' },
+        ({ label }: { label?: string }) => <b>panel:{label}</b>)
+      await runtime.flush()
+    })()
+    expect(view.container.textContent).toContain('panel:from-owner')
+    dispose()
+    await runtime.flush()
+    expect(view.container.textContent).toContain('no panel')
+    await runtime.dispose()
+  })
+
+  it('fails loud when rendering with no root declaration (production boot-order check)', async () => {
+    const runtime = await SlotTestRuntime.create()
+    expect(() => runtime.renderRoot()).toThrow(/'root' has no registration/)
+    await runtime.dispose()
+  })
+})
+
+describe('sessions', () => {
+  it('drives SessionProvider: empty state, current session, switch, live snapshot updates', async () => {
+    const runtime = await runtimeWithFrame()
+    runtime.slots.register({ name: 'trt.chat' }, (props: SessionStandardProps) => {
+      const running = props.useSession(s => s.running)
+      return <span>chat:{props.sessionId}:{String(running)}</span>
+    })
+    const view = runtime.renderRoot()
+    expect(view.container.textContent).toContain('no session')
+
+    await runtime.sessions.add({ id: 's1' })
+    expect(view.container.textContent).toContain('chat:s1:false')
+
+    await runtime.sessions.updateSnapshot('s1', (draft) => { draft.running = true })
+    expect(view.container.textContent).toContain('chat:s1:true')
+
+    await runtime.sessions.add({ id: 's2' }) // becomes current by default
+    expect(view.container.textContent).toContain('chat:s2:false')
+
+    await runtime.sessions.setCurrent(undefined)
+    expect(view.container.textContent).toContain('no session')
+    await runtime.sessions.setCurrent('s1')
+    expect(view.container.textContent).toContain('chat:s1:true')
+    await runtime.dispose()
+  })
+
+  it('add with current:false keeps the selection; unknown ids fail loud on the mutators', async () => {
+    const runtime = await runtimeWithFrame()
+    await runtime.sessions.add({ id: 's1' })
+    await runtime.sessions.add({ id: 's2' }, { current: false })
+    expect(runtime.sessions.list.getSnapshot().current).toBe('s1')
+    expect(runtime.sessions.list.getSnapshot().ids).toEqual(['s1', 's2'])
+    await expect(runtime.sessions.add({ id: 's1' })).rejects.toThrow(/already added/)
+    await expect(runtime.sessions.setCurrent('ghost')).rejects.toThrow(/not added/)
+    await expect(runtime.sessions.updateSnapshot('ghost', () => {})).rejects.toThrow(/not added/)
+    await expect(runtime.sessions.remove('ghost')).rejects.toThrow(/not added/)
+    expect(() => runtime.sessions.behavior('ghost')).toThrow(/not added/)
+    await runtime.dispose()
+  })
+
+  it('mints REAL-tag scopes lazily and resolves them through the production scopeOf; bindings expose the behavior face', async () => {
+    const runtime = await runtimeWithFrame()
+    const prompt = vi.fn()
+    await runtime.sessions.add({ id: 's1', session: { prompt } })
+
+    expect(runtime.sessions.provideInfo('ghost')).toBeUndefined()
+    expect(runtime.sessions.scope('ghost')).toBeUndefined()
+    expect(runtime.sessions.binding('ghost')).toBeUndefined()
+
+    const scope = runtime.sessions.scope('s1')!
+    expect(runtime.sessions.scope('s1')).toBe(scope) // stable per session
+    expect(runtime.sessions.scopeOf(scope)).toBe('s1')
+    expect(runtime.sessions.scopeOf(runtime.ctx)).toBeUndefined()
+    // sessionOf resolves the behavior face off the scope tag.
+    expect(runtime.sessions.sessionOf(scope)).toBe(runtime.sessions.behavior('s1'))
+    expect(runtime.sessions.sessionOf(runtime.ctx)).toBeUndefined()
+
+    const binding = runtime.sessions.binding('s1')!
+    expect(binding.sessionId).toBe('s1')
+    expect(binding.ctx).toBe(scope)
+    ;(binding.session as { prompt: () => void }).prompt()
+    expect(prompt).toHaveBeenCalledOnce()
+    expect(runtime.sessions.behavior('s1')).toBe(binding.session)
+    // The binding's session doubles as the conversation observable face.
+    expect((binding.session as { getSnapshot(): { sessionId: string } }).getSnapshot().sessionId).toBe('s1')
+
+    // A scoped service resolves through the scope ctx (scope-addressed pattern).
+    runtime.provide('probe', { hello: 'world' })
+    expect(scope.get('probe')).toEqual({ hello: 'world' })
+    await runtime.dispose()
+  })
+
+  it('materializes provide bundles: built-in session hook, custom providers, no-session projection', async () => {
+    const runtime = await runtimeWithFrame()
+    await runtime.sessions.add({ id: 's1' })
+
+    const info = runtime.sessions.provideInfo('s1')!
+    expect(info.sessionId).toBe('s1')
+    expect(info.hooks['session']).toBeDefined() // the built-in useSession source
+    expect(runtime.sessions.provideInfo('s1')).toBe(info) // identity-stable
+
+    // A feature provider (the ui-conversation input pattern): declared names
+    // materialize per session and land in the no-session roster as undefined.
+    const off = runtime.sessions.provide({
+      hooks: ['probe'],
+      props: ['probeActions'],
+      resolve: binding => ({
+        hooks: { probe: { getSnapshot: () => binding.sessionId, subscribe: () => () => {} } },
+        props: { probeActions: { poke: () => {} } },
+      }),
+    })
+    const enriched = runtime.sessions.provideInfo('s1')!
+    expect(enriched.hooks['probe']?.getSnapshot()).toBe('s1')
+    expect(enriched.props['probeActions']).toBeDefined()
+    const maybe = runtime.sessions.maybeProvideInfo(undefined)
+    expect(maybe.sessionId).toBeUndefined()
+    expect(Object.keys(maybe.hooks)).toEqual(['session', 'probe'])
+    expect(runtime.sessions.maybeProvideInfo('s1')).toBe(runtime.sessions.provideInfo('s1'))
+    expect(runtime.sessions.maybeProvideInfo('ghost').sessionId).toBeUndefined()
+
+    // Misdeclared providers fail loud AT REGISTRATION (the production
+    // channel rebuilds live bundles eagerly and rolls the roster back):
+    // missing hook, missing prop, duplicate hook, duplicate prop.
+    expect(() => runtime.sessions.provide({ hooks: ['void'], resolve: () => ({}) }))
+      .toThrow(/missing hook "void"/)
+    expect(() => runtime.sessions.provide({ props: ['void'], resolve: () => ({}) }))
+      .toThrow(/missing prop "void"/)
+    expect(() => runtime.sessions.provide({
+      hooks: ['session'],
+      resolve: () => ({ hooks: { session: { getSnapshot: () => 0, subscribe: () => () => {} } } }),
+    })).toThrow(/duplicate hook "session"/)
+    const propA = runtime.sessions.provide({ props: ['twice'], resolve: () => ({ props: { twice: 1 } }) })
+    expect(() => runtime.sessions.provide({ props: ['twice'], resolve: () => ({ props: { twice: 2 } }) }))
+      .toThrow(/duplicate prop "twice"/)
+    propA()
+    // The rejected registrations rolled back: the roster still materializes.
+    expect(runtime.sessions.provideInfo('s1')).toBeDefined()
+    off()
+    off() // disposer is idempotent
+    expect(Object.keys(runtime.sessions.maybeProvideInfo(undefined).hooks)).toEqual(['session'])
+    await runtime.dispose()
+  })
+
+  it('records service-face calls; open() moves the selection and clear() empties it', async () => {
+    const runtime = await runtimeWithFrame()
+    await runtime.sessions.add({ id: 's1' })
+    await runtime.sessions.add({ id: 's2' })
+    runtime.sessions.open('s1' as SessionId)
+    await runtime.flush()
+    expect(runtime.sessions.list.getSnapshot().current).toBe('s1')
+    runtime.sessions.clear()
+    await runtime.flush()
+    expect(runtime.sessions.list.getSnapshot().current).toBeUndefined()
+    expect(runtime.sessions.calls).toEqual([
+      { method: 'open', args: ['s1'] },
+      { method: 'clear', args: [] },
+    ])
+    await runtime.dispose()
+  })
+})
+
+describe('stores', () => {
+  const createSuiteStore = () => defineStore({
+    init: () => ({ note: '' }),
+    persist: 'trt.store',
+    actions: { setNote: (d, note: string) => { d.note = note } },
+  })
+
+  it('resolves per-session instances via the host face: shared identity, isolation, action-driven re-render', async () => {
+    const runtime = await runtimeWithFrame()
+    const handle = createSuiteStore()
+    runtime.slots.register(
+      { name: 'trt.chat', store: handle },
+      (props: SessionStandardProps & { useStore: <S>(sel: (s: { note: string }) => S) => S }) =>
+        <span>note:{props.useStore(s => s.note)}</span>)
+    const view = runtime.renderRoot()
+    await runtime.sessions.add({ id: 's1' })
+
+    expect(() => runtime.storeOf('trt.panel')).toThrow(/no registration/)
+    const store = runtime.storeOf('trt.chat', 's1')
+    await runtime.flush()
+    ;(store.actions['setNote'] as (note: string) => void)('hello')
+    await runtime.flush()
+    expect(view.container.textContent).toContain('note:hello')
+    expect(runtime.storeOf('trt.chat', 's1')).toBe(store) // cached per scope key
+
+    await runtime.sessions.add({ id: 's2' })
+    const other = runtime.storeOf('trt.chat', 's2')
+    expect(other).not.toBe(store)
+    expect(other.getSnapshot()).toEqual({ note: '' })
+    await runtime.dispose()
+  })
+
+  it('storeOf guards: before renderRoot, and for storeless entries', async () => {
+    const runtime = await runtimeWithFrame()
+    runtime.slots.register({ name: 'trt.panel' }, () => null)
+    expect(() => runtime.storeOf('trt.panel')).toThrow(/before renderRoot/)
+    runtime.renderRoot()
+    expect(() => runtime.storeOf('trt.panel')).toThrow(/declares no store/)
+    await runtime.dispose()
+  })
+
+  it('remove() prunes the session store scope: persisted state clears, a re-added session starts fresh', async () => {
+    const runtime = await runtimeWithFrame()
+    const handle = createSuiteStore()
+    runtime.slots.register({ name: 'trt.chat', store: handle }, () => null)
+    runtime.renderRoot()
+    await runtime.sessions.add({ id: 's1' })
+
+    const doomed = runtime.storeOf('trt.chat', 's1')
+    ;(doomed.actions['setNote'] as (note: string) => void)('buried')
+    expect(localStorage.getItem('trt.store.s1')).not.toBeNull()
+
+    await runtime.sessions.remove('s1')
+    expect(localStorage.getItem('trt.store.s1')).toBeNull()
+    expect(runtime.sessions.list.getSnapshot().ids).toEqual([])
+    expect(runtime.sessions.provideInfo('s1')).toBeUndefined()
+
+    await runtime.sessions.add({ id: 's1' })
+    const reborn = runtime.storeOf('trt.chat', 's1')
+    expect(reborn).not.toBe(doomed)
+    expect(reborn.getSnapshot()).toEqual({ note: '' })
+    await runtime.dispose()
+  })
+
+  it('remove() also disposes a minted scope fiber; removing a non-current session keeps the selection', async () => {
+    const runtime = await runtimeWithFrame()
+    await runtime.sessions.add({ id: 's1' })
+    await runtime.sessions.add({ id: 's2' }, { current: false })
+    const scope = runtime.sessions.scope('s1')!
+    await runtime.sessions.remove('s2')
+    expect(runtime.sessions.list.getSnapshot().current).toBe('s1')
+    await runtime.sessions.remove('s1')
+    expect(scope.fiber.uid).toBeNull() // disposed fiber loses its uid
+    expect(runtime.sessions.list.getSnapshot().current).toBeUndefined()
+    await runtime.dispose()
+  })
+})
+
+describe('workspaces', () => {
+  it('feeds useWorkspaces and records/stubs intent actions', async () => {
+    const runtime = await runtimeWithFrame()
+    runtime.slots.register(
+      { name: 'trt.panel' },
+      (props: { useWorkspaces: <S>(sel: (s: { phase: string }) => S) => S }) =>
+        <span>ws:{props.useWorkspaces(s => s.phase)}</span>)
+    const view = runtime.renderRoot()
+    expect(view.container.textContent).toContain('ws:ready')
+
+    await runtime.workspaces.update((draft) => { draft.phase = 'pending' })
+    expect(view.container.textContent).toContain('ws:pending')
+
+    runtime.workspaces.startSession('w1' as WorkspaceId)
+    await expect(runtime.workspaces.connectWorkspace('w2' as WorkspaceId)).resolves.toBe('session-of-w2')
+    expect(runtime.workspaces.calls).toEqual([
+      { method: 'startSession', args: ['w1'] },
+      { method: 'connectWorkspace', args: ['w2'] },
+    ])
+    const stub = vi.fn(() => Promise.resolve('other' as never))
+    runtime.workspaces.stub('connectWorkspace', stub)
+    await expect(runtime.workspaces.connectWorkspace('w3' as WorkspaceId)).resolves.toBe('other')
+    expect(stub).toHaveBeenCalledOnce()
+    await runtime.dispose()
+  })
+})
+
+describe('feature mount and disposal', () => {
+  it('mounts a plugin on a real fiber; dispose() cascades entries, declared children, and services', async () => {
+    const runtime = await runtimeWithFrame()
+    runtime.provide('layout', { openDetails: vi.fn() })
+    const feature = await runtime.mount({
+      inject: ['slots', 'layout'],
+      apply: (ctx: typeof runtime.ctx) => {
+        ctx.provide('feature-service', { ok: true })
+        ctx.slots.register({
+          name: 'trt.rows',
+          id: 'row-1',
+          children: { 'trt.rows.hole': { kind: 'single', scope: 'root' } },
+        } as never, ((props: { renderSlot: (key: string, owner: object) => unknown }) =>
+          <div data-testid="row">{props.renderSlot('trt.rows.hole', {}) as React.ReactNode}</div>) as never)
+      },
+    })
+    const view = runtime.renderRoot()
+    expect(view.getByTestId('row')).toBeTruthy()
+    expect(runtime.ctx.get('feature-service')).toEqual({ ok: true })
+    expect(runtime.slots.entries('trt.rows')).toHaveLength(1)
+
+    await feature.dispose()
+    await feature.dispose() // idempotent
+    expect(runtime.slots.entries('trt.rows')).toHaveLength(0)
+    expect(runtime.slots.spec('trt.rows.hole' as never)).toBeUndefined()
+    expect(runtime.ctx.get('feature-service')).toBeUndefined()
+    expect(view.queryByTestId('row')).toBeNull()
+    await runtime.dispose()
+  })
+
+  it('mount fails loud on missing services instead of suspending forever', async () => {
+    const runtime = await runtimeWithFrame()
+    await expect(runtime.mount({ inject: ['slots', 'absent-service'], apply: () => {} }))
+      .rejects.toThrow(/missing service\(s\) absent-service/)
+    await runtime.dispose()
+  })
+
+  it('runtime dispose is idempotent, unmounts views, disposes mounted features, and clears persisted state', async () => {
+    const runtime = await runtimeWithFrame()
+    const feature = await runtime.mount({
+      inject: ['slots'],
+      apply: (ctx: typeof runtime.ctx) => { ctx.slots.register({ name: 'trt.panel' }, () => <b>p</b>) },
+    })
+    const view = runtime.renderRoot()
+    expect(view.container.textContent).toContain('p')
+    localStorage.setItem('trt.leftover', 'x')
+
+    await runtime.dispose()
+    expect(view.container.innerHTML).toBe('')
+    expect(feature.fiber.uid).toBeNull()
+    expect(localStorage.getItem('trt.leftover')).toBeNull()
+    await runtime.dispose() // idempotent
+    await expect(runtime.dispose()).resolves.toBeUndefined()
+  })
+})
+
+describe('single-slot mounting (declare + renderSlot)', () => {
+  it('renders one slot inside its data-slot wrapper and updates owner props in place', async () => {
+    const runtime = await SlotTestRuntime.create()
+    await runtime.declare({ 'trt.panel': { kind: 'single', scope: 'root' } })
+    runtime.slots.register(
+      { name: 'trt.panel' },
+      ({ label }: { label?: string }) => <b data-testid="panel">{label ?? 'none'}</b>)
+    const slot = runtime.renderSlot('trt.panel', { label: 'first' })
+    expect(slot.container.getAttribute('data-slot')).toBe('trt.panel')
+    expect(slot.view.getByTestId('panel').textContent).toBe('first')
+
+    const panel = slot.view.getByTestId('panel')
+    slot.update({ label: 'second' })
+    expect(slot.view.getByTestId('panel').textContent).toBe('second')
+    // In-place re-render: the element identity survived the owner flip.
+    expect(slot.view.getByTestId('panel')).toBe(panel)
+    await runtime.dispose()
+  })
+
+  it('views sibling slots of one tree separately and rejects undeclared keys', async () => {
+    const runtime = await SlotTestRuntime.create()
+    await runtime.declare({
+      'trt.panel': { kind: 'single', scope: 'root' },
+      'trt.rows': { kind: 'list', scope: 'root' },
+    })
+    runtime.slots.register({ name: 'trt.panel' }, () => <b>panel</b>)
+    runtime.slots.register({ name: 'trt.rows', id: 'r1' }, () => <i>row</i>)
+    const panel = runtime.renderSlot('trt.panel', {})
+    const rows = runtime.renderSlot('trt.rows', {})
+    expect(panel.container.textContent).toBe('panel')
+    expect(rows.container.textContent).toBe('row')
+    expect(() => runtime.renderSlot('trt.chat', {})).toThrow(/without declare\(\)/)
+    await runtime.dispose()
+  })
+
+  it('folds class hashes and collapses svg internals in snapshots, leaving the live DOM alone', async () => {
+    const runtime = await SlotTestRuntime.create()
+    await runtime.declare({ 'trt.panel': { kind: 'single', scope: 'root' } })
+    runtime.slots.register({ name: 'trt.panel' }, () => (
+      <div className="_frame_a1b2c3 plain">
+        <span className="_label_ff00aa">styled</span>
+        <svg viewBox="0 0 16 16" aria-hidden="true">
+          <path d="M0 0L16 16" fill="currentColor" />
+        </svg>
+      </div>
+    ))
+    const slot = runtime.renderSlot('trt.panel', {})
+    expect(slot.container).toMatchSnapshot()
+    // The serializer works on a clone: the live DOM keeps hashes and paths.
+    expect(slot.container.querySelector('div')!.className).toBe('_frame_a1b2c3 plain')
+    expect(slot.container.querySelector('svg path')).not.toBeNull()
+    await runtime.dispose()
+  })
+})
+
+describe('fixture session face', () => {
+  it('fail-loud stubs name the missing verb; supplied overrides run instead', async () => {
+    const runtime = await SlotTestRuntime.create()
+    await runtime.sessions.add({ id: 's1' })
+    const bare = runtime.sessions.behavior('s1')
+    expect(() => bare.prompt()).toThrow(/prompt is not stubbed/)
+    expect(() => bare.cancel()).toThrow(/cancel is not stubbed/)
+    expect(() => bare.loadOlder()).toThrow(/loadOlder is not stubbed/)
+    await runtime.dispose()
+  })
+
+  it('projections faces are identity-stable per key, read absent, and notify on set', async () => {
+    const runtime = await SlotTestRuntime.create()
+    await runtime.sessions.add({ id: 's1' })
+    const session = runtime.sessions.behavior('s1')
+    const face = session.projections.faceOf('todos')
+    expect(session.projections.faceOf('todos')).toBe(face)
+    expect(face.getSnapshot()).toBeUndefined()
+    const seen: unknown[] = []
+    const off = face.subscribe(() => { seen.push(face.getSnapshot()) })
+    session.projections.set('todos', [1, 2])
+    expect(seen).toEqual([[1, 2]])
+    off()
+    session.projections.set('todos', [3])
+    expect(seen).toEqual([[1, 2]]) // unsubscribed
+    // A never-subscribed key sets without listeners (the empty-notify arm).
+    session.projections.set('untouched', 1)
+    // The provide bundle hands the same store to the render side.
+    const info = runtime.sessions.provideInfo('s1')!
+    expect(info.projections?.faceOf('todos').getSnapshot()).toEqual([3])
+    // A roster change rebuilds the ALREADY-materialized bundle eagerly
+    // (production channel semantics: mounted entries must see the provider)
+    // and skips never-materialized records (they pick the roster up lazily).
+    await runtime.sessions.add({ id: 's-lazy' }, { current: false })
+    const offProbe = runtime.sessions.provide({
+      hooks: ['probe2'],
+      resolve: () => ({ hooks: { probe2: { getSnapshot: () => 1, subscribe: () => () => {} } } }),
+    })
+    const rebuilt = runtime.sessions.provideInfo('s1')!
+    expect(rebuilt).not.toBe(info)
+    expect(rebuilt.hooks['probe2']).toBeDefined()
+    offProbe()
+    await runtime.dispose()
+  })
+})
+
+describe('workspaces action face', () => {
+  it('records every IWorkspaces verb with inert defaults and honors stubs', async () => {
+    const runtime = await SlotTestRuntime.create()
+    const ws = runtime.workspaces
+    const created = await ws.create({ name: 'alpha' })
+    expect(created.title).toBe('alpha')
+    const registered = await ws.create({ path: '/tmp/beta' })
+    expect(registered.path).toBe('/tmp/beta')
+    await expect(ws.pickDirectory()).resolves.toBeNull()
+    const renamed = await ws.rename('w1' as WorkspaceId, 'Renamed')
+    expect(renamed.title).toBe('Renamed')
+    await ws.delete('w1' as WorkspaceId)
+    await ws.openPath('/proj/file.ts')
+    const moved = await ws.insertSessionBefore('w1' as WorkspaceId, 's1' as SessionId, 's2' as SessionId)
+    expect(moved.sessionIds).toEqual(['s1'])
+    expect(ws.calls.map(c => c.method)).toEqual(
+      ['create', 'create', 'pickDirectory', 'rename', 'delete', 'openPath', 'insertSessionBefore'])
+
+    ws.stub('create', () => Promise.resolve({ workspaceId: 'ws-x', title: 'X', path: '/x', sessionIds: [] } as never))
+    ws.stub('pickDirectory', () => Promise.resolve('/picked'))
+    ws.stub('rename', () => Promise.resolve({ workspaceId: 'w1', title: 'S', path: '/s', sessionIds: [] } as never))
+    ws.stub('delete', () => Promise.resolve())
+    ws.stub('openPath', () => Promise.resolve())
+    ws.stub('insertSessionBefore', () => Promise.resolve({ workspaceId: 'w1', title: '', path: '', sessionIds: [] } as never))
+    expect((await ws.create({ name: 'y' })).title).toBe('X')
+    await expect(ws.pickDirectory()).resolves.toBe('/picked')
+    expect((await ws.rename('w1' as WorkspaceId, 'z')).title).toBe('S')
+    await ws.delete('w1' as WorkspaceId)
+    await ws.openPath('/other')
+    expect((await ws.insertSessionBefore('w1' as WorkspaceId, 's1' as SessionId)).sessionIds).toEqual([])
+    await runtime.dispose()
+  })
+})
+
+describe('single-slot mounting edge arms', () => {
+  it('renderSlot fails loud after dispose and after an external unmount', async () => {
+    const runtime = await SlotTestRuntime.create()
+    await runtime.declare({ 'trt.panel': { kind: 'single', scope: 'root' } })
+    runtime.slots.register({ name: 'trt.panel' }, () => <b>p</b>)
+    runtime.renderSlot('trt.panel', {})
+    // RTL cleanup empties the mounted tree behind the runtime's back: the
+    // wrapper lookup names the state instead of returning a dead container.
+    cleanup()
+    expect(() => runtime.renderSlot('trt.panel', {})).toThrow(/rendered no wrapper/)
+    await runtime.dispose()
+    // After dispose the root registration is gone: the production boot-order
+    // check fires before any wrapper lookup.
+    expect(() => runtime.renderSlot('trt.panel', {})).toThrow(/'root' has no registration/)
+  })
+
+  it('serializes childless svg untouched next to scoped classes', async () => {
+    const runtime = await SlotTestRuntime.create()
+    await runtime.declare({ 'trt.panel': { kind: 'single', scope: 'root' } })
+    runtime.slots.register({ name: 'trt.panel' }, () => (
+      <div className="_frame_a1b2c3">
+        <svg viewBox="0 0 1 1" aria-hidden="true" />
+      </div>
+    ))
+    const slot = runtime.renderSlot('trt.panel', {})
+    expect(slot.container).toMatchSnapshot()
+    await runtime.dispose()
+  })
+})

packages/client/test-runtime/tsconfig.json

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

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

@@ -9,10 +9,10 @@
 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 { ClientContext, ISessions } from '@deepseek-ai/dsh-client-runtime/client'
 import type {
   CandidateRequest, ClientSessionContext, CommandClaim, PickOutcome, SlashCandidate, SlashPick,
-  SlashServiceContract, SubmitOutcome,
+  SubmitOutcome,
 } from '@deepseek-ai/dsh-client-ui-slash/client'
 import type { CommandContribution, CommandServiceContract } from './contract.ts'
 import type { CommandDescriptor } from './directory.ts'
@@ -46,7 +46,7 @@ export class CommandService extends Service implements CommandServiceContract {
       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
+    const slash = ctx.get('slash')
     if (slash === undefined) throw new Error('ui-command: slash service unavailable')
     ctx.effect(() => slash.registerSource({
       trigger: '/',
@@ -292,7 +292,7 @@ export class CommandService extends Service implements CommandServiceContract {
     return this.sessions().scope(id)
   }
 
-  private sessions(): SessionsService {
+  private sessions(): ISessions {
     const sessions = this.ctx.get('sessions')
     if (sessions === undefined) throw new Error('ui-command: sessions service unavailable')
     return sessions

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

@@ -1,7 +1,7 @@
 /** Registers the conversation components, shared store, and service callbacks. */
 import type { Context } from 'cordis'
 import type { BoundActions } from '@deepseek-ai/dsh-client-ui-slots'
-import type { SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ISessions, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 import type { ViewTab } from './contract/views.ts'
 import type {
@@ -10,6 +10,7 @@ import type {
 import { resolveToolPath } from './contract/tool-call-model.ts'
 import { createChatStore } from './stores.ts'
 import { ConversationService } from './service.ts'
+import type { IConversation } from './service.ts'
 import { InputHub } from './input/hub.ts'
 import { InputBar } from './skeleton/InputBar.tsx'
 import { ChatView } from './chat/ChatView.tsx'
@@ -24,8 +25,8 @@ import { DetailsPanel } from './skeleton/DetailsPanel.tsx'
 /** Services required by the conversation plugin. */
 export const inject = ['slots', 'layout', 'sessions', 'workspaces']
 
-/** Resolve the session-scoped conversation service (scope-addressed send/cancel), failing loud. */
-function scopedConversation(sessions: SessionsService, id: SessionId): ConversationService {
+/** Resolve the session-scoped conversation face (scope-addressed send/cancel), failing loud. */
+function scopedConversation(sessions: ISessions, id: SessionId): IConversation {
   const scoped = sessions.scope(id)
   if (scoped === undefined) throw new Error(`ui-conversation: session "${id}" resolved no scope`)
   const conversation = scoped.get('conversation')

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

@@ -3,10 +3,9 @@
  * between the independently implemented skeleton and chat domains; `apply.ts`
  * owns their slot assembly.
  */
-import type { ConversationService } from './service.ts'
-
 export { apply, inject } from './apply.ts'
 export { ConversationService } from './service.ts'
+export type { IConversation } from './service.ts'
 
 export type {
   CallId, ChatStoreState, SelectionTarget, ViewTab,
@@ -22,6 +21,7 @@ export type {
 
 declare module 'cordis' {
   interface Context {
-    conversation: ConversationService
+    /** The outward face only; the concrete service stays inside this plugin. */
+    conversation: import('./service.ts').IConversation
   }
 }

packages/client/ui-conversation/src/client/input/hub.ts

@@ -8,9 +8,8 @@
  * bail events) and owns the default-sink choreography: every session is a
  * real host entity, so the sink is one unconditional prompt path.
  */
-import type { ClientContext, Session, SessionBinding, SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
-import type { SlashController, SlashServiceContract } from '@deepseek-ai/dsh-client-ui-slash/client'
-import type {} from '@deepseek-ai/dsh-client-ui-slash/client'
+import type { ClientContext, ISessions, SessionBinding, SessionFace, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SlashController } from '@deepseek-ai/dsh-client-ui-slash/client'
 import { queueReadFaceOf } from '../queue/store.ts'
 import type { ComposerKeyboard, InputService, SessionInput } from './contract.ts'
 import type { PopupDismissFace } from './facade.ts'
@@ -113,7 +112,7 @@ export class InputHub implements InputService {
    * exactly one path; a failed first prompt is an ordinary prompt failure
    * (error strip via promptError, draft restored only while untouched).
    */
-  private sink(session: Session, text: string, mode: 'queue' | 'steer'): void {
+  private sink(session: SessionFace, text: string, mode: 'queue' | 'steer'): void {
     if (text === '') return
     const shell = this.shells.get(session.sessionId)
     // Commit, not an editable clear: undo must not resurrect sent content.
@@ -129,7 +128,7 @@ export class InputHub implements InputService {
   }
 
   private controller(actx: ClientContext): SlashController | undefined {
-    const slash = this.rootCtx.get('slash') as SlashServiceContract | undefined
+    const slash = this.rootCtx.get('slash')
     return slash?.sessionOf(actx)
   }
 
@@ -138,7 +137,7 @@ export class InputHub implements InputService {
     return command?.popupFor(actx)
   }
 
-  private sessions(): SessionsService {
+  private sessions(): ISessions {
     const sessions = this.rootCtx.get('sessions')
     if (sessions === undefined) throw new Error('conversation.input: sessions service unavailable')
     return sessions

packages/client/ui-conversation/src/client/queue/store.ts

@@ -5,7 +5,7 @@
  * reference-stable across unrelated snapshot swaps, so this is a pure
  * projection — no second store, no copy.
  */
-import type { ObservableSnapshot, Session } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ObservableSnapshot, SessionFace } from '@deepseek-ai/dsh-client-runtime/client'
 import type { QueuedMessage } from '../input/contract.ts'
 
 /**
@@ -13,10 +13,10 @@ import type { QueuedMessage } from '../input/contract.ts'
  * The wiring layer (T5) overlays this onto InputState.queue; the runtime
  * QueuedMessage and the input-contract QueuedMessage are structurally the
  * same frozen shape ({key, preview}).
- * @param session - the resident session instance.
+ * @param session - the resident session face.
  * @returns the queue read face (snapshot reference stable while the queue is unchanged).
  */
-export function queueReadFaceOf(session: Session): ObservableSnapshot<readonly QueuedMessage[]> {
+export function queueReadFaceOf(session: SessionFace): ObservableSnapshot<readonly QueuedMessage[]> {
   return {
     getSnapshot: () => session.getSnapshot().queue,
     subscribe: fn => session.subscribe(fn),

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

@@ -12,24 +12,50 @@ import type { Context } from 'cordis'
 // Type-only imports: a plugin-to-plugin value import is a bundle purity
 // error, so scope resolution goes through the sessions service (scopeOf
 // method) instead of the standalone helper.
-import type { Session, SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
-import { InputHub } from './input/hub.ts'
+import type { ISessions, SessionFace, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { InputService } from './input/contract.ts'
+
+/**
+ * The outward conversation face (`ctx.conversation`): the scope-addressed
+ * verbs and the input registry other plugins may reach — and exactly what a
+ * test fake must supply.
+ */
+export interface IConversation {
+  /** The per-session input machine registry (InputService face). */
+  readonly input: InputService
+  /**
+   * Send a prompt into the caller scope's session.
+   * @param text - prompt text, sent verbatim as one text block.
+   * @param mode - queue after the current turn, or steer into it.
+   * @returns completion; business failures reject (and land in promptError).
+   */
+  send(text: string, mode: 'queue' | 'steer'): Promise<void>
+  /**
+   * Cancel the scoped session's in-flight turn.
+   * @returns completion; failures reject as in send.
+   */
+  cancel(): Promise<void>
+  /**
+   * Pull one older history page for the scoped session.
+   * @returns completion of the page pull.
+   */
+  loadOlder(): Promise<void>
+}
 
 /** Scope-addressed conversation service (root singleton, provided as `conversation`). */
-export class ConversationService extends Service {
+export class ConversationService extends Service implements IConversation {
   /** The per-session input machine registry (InputService face, design §5.2). */
-  readonly input: InputHub
+  readonly input: InputService
 
   /**
    * @param ctx - owning root context (the plugin apply context; the service
    * registers itself and follows that fiber's lifetime).
-   * @param config - the shared InputHub constructed by the plugin apply
-   * (shared with the slot inject factories); absent = own instance
-   * (object-layer tests that never touch slots).
+   * @param config - carries the InputService instance constructed by the
+   * plugin apply (the same InputHub the slot inject factories close over).
    */
-  constructor(ctx: Context, config?: { input?: InputHub }) {
+  constructor(ctx: Context, config: { input: InputService }) {
     super(ctx, 'conversation')
-    this.input = config?.input ?? new InputHub(ctx)
+    this.input = config.input
   }
 
   /**
@@ -57,8 +83,8 @@ export class ConversationService extends Service {
     await this.scopedSession('loadOlder').loadOlder()
   }
 
-  /** Resolve the caller scope's Session or throw on root contexts. */
-  private scopedSession(op: string): Session {
+  /** Resolve the caller scope's session face or throw on root contexts. */
+  private scopedSession(op: string): SessionFace {
     const id = this.scopeId(op)
     const binding = this.requireSessions().binding(id)
     if (binding === undefined) throw new Error(`conversation.${op}: session "${id}" resolved no binding`)
@@ -74,10 +100,9 @@ export class ConversationService extends Service {
     return id
   }
 
-  private requireSessions(): SessionsService {
-    // ctx.get instead of ctx.sessions: the typed Context merge is suspended
-    // while the client/host `sessions` declaration collision awaits
-    // arbitration (see the runtime package's Context merge note).
+  private requireSessions(): ISessions {
+    // Strict ctx.get, not the injection proxy: the scope-addressed pattern
+    // reads the service off whatever context the tracker rebound.
     const sessions = this.ctx.get('sessions')
     if (sessions === undefined) throw new Error('conversation: sessions service unavailable')
     return sessions

packages/client/ui-conversation/tests/apply-inject.spec.tsx

@@ -1,144 +1,73 @@
 // @vitest-environment jsdom
 // apply inject factories exercised end to end against the terminal thin
-// shape: the conversation surface (views triple, send choreography incl.
-// optimistic clear + failure restore THROUGH the declared store actions,
-// openDetails = select action + layout orchestration, sessions.open
-// navigation), and the closeDetails details surface. Complements
-// chat-apply.spec.tsx (registration)
-// and selection-survival.spec.ts (store axis). History opening is NOT an
-// inject concern anymore — the runtime sessions service opens on watch
-// (sessions-service.spec.ts owns that behavior).
+// shape: the strict session surface (views triple, draft mirror), the
+// provide-channel input face (machine-sink submit choreography incl.
+// optimistic clear + failure restore), the resident surface (selectWorkspace
+// draft carrying), the composer-bar stop face, openDetails = select action +
+// layout orchestration, and the closeDetails details surface. Complements
+// chat-apply.spec.tsx (registration) and selection-survival.spec.tsx (store
+// axis). History opening is NOT an inject concern — the runtime sessions
+// service opens on watch (sessions-service.spec.ts owns that behavior).
+//
+// The inject surfaces are read off the ledger entries deliberately (typed at
+// this spec's own contract): these cases pin factory choreography the UI
+// guards would mask. Rendering-path acceptance lives in
+// chat-toolview-slot.spec.tsx.
 
-import { Context } from 'cordis'
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import { cleanup } from '@testing-library/react'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
-import { SlotsService, scopeOf } from '@deepseek-ai/dsh-client-runtime/client'
-import type {
-  SessionId, SessionListState, WorkspaceListState,
-} from '@deepseek-ai/dsh-client-runtime/client'
-import type { SlotRendererHost } from '@deepseek-ai/dsh-client-web-react'
+import { describe, expect, it, vi } from 'vitest'
+import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
+import type { SessionBehaviorOverrides } from '@deepseek-ai/dsh-client-test-runtime'
+import type { ISession, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type {
   ChatViewInjected, ComposerBarInjected, ConversationInjected, ConversationSessionInjected, DetailsInjected,
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { createChatStore } from '../src/client/stores.ts'
 
-afterEach(cleanup)
-
 const ROOT = 'root-1' as SessionId
 
 type ChatInstance = ReturnType<ReturnType<typeof createChatStore>['create']>
 type ChatActions = ChatInstance['actions']
 
-const SCOPE_TAG: symbol = (() => {
-  const recorded: (string | symbol)[] = []
-  const spy = new Proxy(new Context(), {
-    get(target, prop, receiver) {
-      recorded.push(prop)
-      // Reflect.get is typed any; the probe only records property names.
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-      return Reflect.get(target, prop, receiver)
-    },
-  })
-  void scopeOf(spy)
-  const symbol = recorded.find((p): p is symbol => typeof p === 'symbol')
-  if (symbol === undefined) throw new Error('scopeOf probe recorded no symbol read')
-  return symbol
-})()
+/** ISession verb mocks, typed against the production face (['prompt'] etc. keep vitest mock ergonomics). */
+function sessionFakeFor() {
+  return {
+    open: vi.fn(() => Promise.resolve()),
+    loadOlder: vi.fn<ISession['loadOlder']>(() => Promise.resolve()),
+    prompt: vi.fn<ISession['prompt']>(() => Promise.resolve({ ok: true, value: { accepted: true } })),
+    cancel: vi.fn<ISession['cancel']>(() => Promise.resolve({ ok: true, value: { accepted: true } })),
+  } satisfies SessionBehaviorOverrides
+}
 
 async function bench() {
-  const ctx = new Context()
-  const slotsFiber = ctx.plugin(SlotsService)
-  await slotsFiber.await()
-  const slots = ctx.get('slots') as SlotsService
-
-  const listStore = createSnapshotStore<SessionListState>({
-    ids: [ROOT],
-    byId: { [ROOT]: { id: ROOT, title: 'R', displayTitle: 'R', cwd: '/proj', running: false, blank: false, updatedAt: 1 } },
-    current: ROOT,
-    phase: 'ready',
-  })
-  const sessionFake = {
-    sessionId: ROOT,
-    open: vi.fn(() => Promise.resolve()),
-    loadOlder: vi.fn(() => Promise.resolve()),
-    prompt: vi.fn<() => Promise<{ ok: boolean; value?: object; error?: { code: string; message: string } }>>(
-      () => Promise.resolve({ ok: true, value: { accepted: true } })),
-    cancel: vi.fn<() => Promise<{ ok: boolean; value?: object; error?: { code: string; message: string } }>>(
-      () => Promise.resolve({ ok: true, value: { accepted: true } })),
-    // Observable face (the input machine's queue read face rides it).
-    getSnapshot: () => ({ queue: [] }),
-    subscribe: () => () => {},
-  }
-  const scopes = new Map<SessionId, Context>()
-  const mint = (id: SessionId): Context => {
-    let scoped = scopes.get(id)
-    if (scoped === undefined) {
-      scoped = ctx.plugin(() => {}).ctx.extend({ [SCOPE_TAG]: id })
-      scopes.set(id, scoped)
-    }
-    return scoped
-  }
-  type TestProvider = {
-    resolve(binding: { sessionId: SessionId; session: typeof sessionFake; ctx: Context }): {
-      hooks?: Record<string, unknown>
-      props?: Record<string, unknown>
-    }
-  }
-  const providers: TestProvider[] = []
-  const absentInfo = { sessionId: undefined, hooks: {}, props: {} }
-  const sessionsFake = {
-    list: listStore,
-    binding: (id: SessionId) => ({ sessionId: id, session: sessionFake, ctx: mint(id) }),
-    scope: (id: SessionId) => mint(id),
-    provideInfo: () => undefined,
-    currentProvideInfo: { getSnapshot: () => absentInfo, subscribe: () => () => {} },
-    provide: (descriptor: TestProvider) => { providers.push(descriptor); return () => {} },
-    scopeOf,
-    sessionOf: (actx: Context) => (scopeOf(actx) === undefined ? undefined : sessionFake),
-    open: vi.fn(),
-  }
-  ctx.provide('sessions', sessionsFake)
-  const workspaceStore = createSnapshotStore<WorkspaceListState>({
-    items: [], state: 'idle', phase: 'ready', error: null,
-    baselinesReady: true, recentWorkspaceId: undefined,
+  const runtime = await SlotTestRuntime.create()
+  const sessionFake = sessionFakeFor()
+  await runtime.sessions.add({
+    id: ROOT,
+    summary: { title: 'R', displayTitle: 'R', cwd: '/proj' },
+    session: sessionFake,
   })
-  const workspacesFake = {
-    list: workspaceStore,
-    connectWorkspace: vi.fn(async () => ROOT),
-    openPath: vi.fn(async () => {}),
-  }
-  ctx.provide('workspaces', workspacesFake)
   const layoutFake = { openDetails: vi.fn(), closeDetails: vi.fn() }
-  ctx.provide('layout', layoutFake)
-  ctx.provide('locale', { bind: () => (key: string) => key })
+  runtime.provide('layout', layoutFake)
 
-  // The AppFrame role: the three conversation-package slots must be declared
-  // by a live entry before apply can contribute into them (the stand-in
-  // consumes renderSlot to satisfy the declare-means-render check).
-  slots.register({
-    name: 'root',
-    children: {
-      'conversation': { kind: 'single', scope: 'session-maybe' },
-      'details': { kind: 'single', scope: 'session' },
-    },
+  // The AppFrame role: the conversation-package slots must be declared by a
+  // live entry before apply can contribute into them.
+  await runtime.root.declare({
+    'conversation': { kind: 'single', scope: 'session-maybe' },
+    'details': { kind: 'single', scope: 'session' },
   }, (_p: { renderSlot?: unknown }) => null)
 
-  const fiber = ctx.plugin({ inject: [...inject], apply })
-  await fiber.await()
+  const feature = await runtime.mount({ inject: [...inject], apply })
 
-  // Reach the render-side entry view (inject + store handle) the way the
-  // renderer does: through the host face.
-  let host: SlotRendererHost | undefined
-  slots.install({ renderRoot: (h) => { host = h; return null } })
-  slots.renderSlot('root', {})
-  const hostFace = host!
-  const entryOf = (key: 'conversation' | 'conversation.session' | 'conversation.composer.bar' | 'conversation.view' | 'details') => hostFace.entriesOf(key)[0]!
+  // The host face (store resolution) exists only inside the installed
+  // renderer, so materialize it the way the shell does.
+  runtime.renderRoot()
+  const entryOf = (key: 'conversation' | 'conversation.session' | 'conversation.composer.bar' | 'conversation.view' | 'details') =>
+    runtime.slots.entries(key)[0]!
   /** Resolve store instance + call the inject the way the outlet would. */
   const conversationSurface = (id: SessionId) => {
     const entry = entryOf('conversation.session')
-    const instance = hostFace.storeOf(entry, id) as ChatInstance
+    const instance = runtime.storeOf('conversation.session', id) as ChatInstance
     const injected = (entry.inject as unknown as (sessionId: SessionId, actions: ChatActions) => ConversationSessionInjected)(
       id, instance.actions)
     return { instance, injected }
@@ -154,27 +83,28 @@ async function bench() {
   /** Same resolution for the chat entry riding the view ring. */
   const chatViewSurface = (id: SessionId) => {
     const entry = entryOf('conversation.view')
-    const instance = hostFace.storeOf(entry, id) as ChatInstance
+    const instance = runtime.storeOf('conversation.view', id) as ChatInstance
     const injected = (entry.inject as unknown as (sessionId: SessionId, actions: ChatActions) => ChatViewInjected)(
       id, instance.actions)
     return { instance, injected }
   }
   /** Materialize the input provide contribution the way the runtime does. */
   const inputSurface = (id: SessionId) => {
-    const contribution = providers[0]!.resolve(sessionsFake.binding(id))
-    const state = contribution.hooks!['input'] as {
+    const info = runtime.sessions.provideInfo(id)!
+    const state = info.hooks['input'] as {
       getSnapshot: () => { draft: string }
       subscribe: (fn: () => void) => () => void
     }
-    const actions = contribution.props!['inputActions'] as {
+    const actions = info.props['inputActions'] as {
       setDraft: (text: string) => void
       submit: (mode?: 'queue' | 'steer') => void
     }
     return { state, actions }
   }
   return {
-    ctx, slots, hostFace, entryOf, conversationSurface, residentSurface, composerSurface, chatViewSurface, inputSurface,
-    sessionFake, sessionsFake, workspacesFake, layoutFake, mint,
+    runtime, feature, slots: runtime.slots, entryOf,
+    conversationSurface, residentSurface, composerSurface, chatViewSurface, inputSurface,
+    sessionFake, layoutFake,
   }
 }
 
@@ -190,6 +120,7 @@ describe('conversation slot inject surface', () => {
     const chatView = b.chatViewSurface(ROOT)
     chatView.injected.loadOlder()
     expect(b.sessionFake.loadOlder).toHaveBeenCalledTimes(1)
+    await b.runtime.dispose()
   })
 
   it('the provide-channel input face submits through the machine sink: trim, optimistic clear, failure restore without clobber', async () => {
@@ -208,14 +139,14 @@ describe('conversation slot inject surface', () => {
     await Promise.resolve()
     expect(b.sessionFake.prompt).toHaveBeenCalledWith([{ type: 'text', text: 'hello' }], 'queue')
     // Failure: restored (draft still empty when the rejection lands).
-    b.sessionFake.prompt.mockResolvedValueOnce({ ok: false, error: { code: 'agent-busy', message: 'b' } })
+    b.sessionFake.prompt.mockResolvedValueOnce({ ok: false, error: { code: 'agent-busy', message: 'b', details: { reason: 'b' } } })
     actions.setDraft('retry me')
     actions.submit('queue')
     await vi.waitFor(() => {
       expect(state.getSnapshot().draft).toBe('retry me')
     })
     // Failure landing after new typing: no clobber (restore fills empty only).
-    b.sessionFake.prompt.mockResolvedValueOnce({ ok: false, error: { code: 'agent-busy', message: 'b' } })
+    b.sessionFake.prompt.mockResolvedValueOnce({ ok: false, error: { code: 'agent-busy', message: 'b', details: { reason: 'b' } } })
     actions.submit('queue')
     actions.setDraft('typed during flight')
     await new Promise(r => setTimeout(r, 0))
@@ -229,23 +160,25 @@ describe('conversation slot inject surface', () => {
     expect(mirrored).toEqual(['mirrored text'])
     unbind()
     // Stop failure is swallowed (promptError owns the surface).
-    b.sessionFake.cancel.mockResolvedValueOnce({ ok: false, error: { code: 'internal', message: 'x' } })
+    b.sessionFake.cancel.mockResolvedValueOnce({ ok: false, error: { code: 'internal', message: 'x', details: {} } })
     b.composerSurface(ROOT).stop()
     await new Promise(r => setTimeout(r, 0))
     expect(b.sessionFake.cancel).toHaveBeenCalledTimes(1)
+    await b.runtime.dispose()
   })
 
-  it('inject fails loud when the session resolves no scope or the scope lacks the service', async () => {
+  it('inject fails loud when the session resolves no binding or the scope lacks the service', async () => {
     const b = await bench()
     const entry = b.entryOf('conversation.composer.bar')
     const injectFn = entry.inject as unknown as (sessionId: SessionId) => ComposerBarInjected
-    // Unknown session: sessions.scope answers nothing.
-    ;(b.sessionsFake.scope as unknown) = () => undefined
-    expect(() => { injectFn(ROOT).stop() }).toThrow(/resolved no scope/)
-    // A scope minted outside the service tree: no conversation service on it.
-    const foreign = new Context()
-    ;(b.sessionsFake.scope as unknown) = () => foreign.plugin(() => {}).ctx.extend({})
-    expect(() => { injectFn(ROOT).stop() }).toThrow(/unavailable through the session scope/)
+    // Unknown session: the keyboard face's binding resolution answers nothing.
+    expect(() => { injectFn('ghost' as SessionId).stop() }).toThrow(/resolved no binding/)
+    // A scope whose service tree lost 'conversation' (the feature fiber
+    // unloaded while a retained inject closure re-runs): fails loud too.
+    const stop = injectFn(ROOT).stop
+    await b.feature.dispose()
+    expect(() => { stop() }).toThrow(/unavailable through the session scope/)
+    await b.runtime.dispose()
   })
 
   it('openDetails (chat view face) writes the selection through the store actions and opens the panel', async () => {
@@ -258,6 +191,7 @@ describe('conversation slot inject surface', () => {
     // writes land where the skeleton and details read.
     const conv = b.conversationSurface(ROOT)
     expect(conv.instance).toBe(instance)
+    await b.runtime.dispose()
   })
 
   it('openFile (chat view face) resolves against session cwd and calls workspaces.openPath', async () => {
@@ -265,8 +199,9 @@ describe('conversation slot inject surface', () => {
     const { injected } = b.chatViewSurface(ROOT)
     injected.openFile('src/a.ts')
     await vi.waitFor(() => {
-      expect(b.workspacesFake.openPath).toHaveBeenCalledWith('/proj/src/a.ts')
+      expect(b.runtime.workspaces.calls).toContainEqual({ method: 'openPath', args: ['/proj/src/a.ts'] })
     })
+    await b.runtime.dispose()
   })
 
   it('routes navigation and workspace switching through the runtime owners, carrying the draft', async () => {
@@ -274,23 +209,73 @@ describe('conversation slot inject surface', () => {
     const { injected } = b.conversationSurface(ROOT)
     const resident = b.residentSurface(ROOT)
     injected.open(ROOT)
-    expect(b.sessionsFake.open).toHaveBeenCalledWith(ROOT)
+    expect(b.runtime.sessions.calls).toContainEqual({ method: 'open', args: [ROOT] })
     // Same-session connect (the picked workspace resolves to this session):
     // no draft movement, plain re-open.
+    b.runtime.workspaces.stub('connectWorkspace', () => Promise.resolve(ROOT))
     const { state, actions } = b.inputSurface(ROOT)
     actions.setDraft('carry me')
     void resident.selectWorkspace('workspace-1' as never)
-    await vi.waitFor(() => { expect(b.sessionsFake.open).toHaveBeenCalledTimes(2) })
-    expect(b.workspacesFake.connectWorkspace).toHaveBeenCalledWith('workspace-1')
+    await vi.waitFor(() => {
+      expect(b.runtime.sessions.calls.filter(c => c.method === 'open')).toHaveLength(2)
+    })
+    expect(b.runtime.workspaces.calls).toContainEqual({ method: 'connectWorkspace', args: ['workspace-1'] })
     expect(state.getSnapshot().draft).toBe('carry me')
     // Cross-session connect: the draft MOVES — the old machine empties, the
     // new session's machine receives the text, then navigation lands there.
     const OTHER = 'other-1' as SessionId
-    b.workspacesFake.connectWorkspace.mockResolvedValueOnce(OTHER)
+    await b.runtime.sessions.add({ id: OTHER }, { current: false })
+    b.runtime.workspaces.stub('connectWorkspace', () => Promise.resolve(OTHER))
     void resident.selectWorkspace('workspace-2' as never)
-    await vi.waitFor(() => { expect(b.sessionsFake.open).toHaveBeenCalledWith(OTHER) })
+    await vi.waitFor(() => {
+      expect(b.runtime.sessions.calls).toContainEqual({ method: 'open', args: [OTHER] })
+    })
     expect(state.getSnapshot().draft).toBe('')
     expect(b.inputSurface(OTHER).state.getSnapshot().draft).toBe('carry me')
+    await b.runtime.dispose()
+  })
+
+  it('selectWorkspace edge arms: no-session resident, empty-draft move, connect failure retryable', async () => {
+    const b = await bench()
+    // No-session resident (hero before any session): connect resolves and
+    // navigation proceeds without any draft choreography.
+    const noSession = b.residentSurface(undefined)
+    b.runtime.workspaces.stub('connectWorkspace', () => Promise.resolve(ROOT))
+    void noSession.selectWorkspace('workspace-0' as never)
+    await vi.waitFor(() => {
+      expect(b.runtime.sessions.calls).toContainEqual({ method: 'open', args: [ROOT] })
+    })
+
+    // Cross-session connect with an EMPTY draft: no move, no clearing.
+    const OTHER = 'b9-other' as SessionId
+    await b.runtime.sessions.add({ id: OTHER }, { current: false })
+    const resident = b.residentSurface(ROOT)
+    const { state } = b.inputSurface(ROOT)
+    expect(state.getSnapshot().draft).toBe('')
+    b.runtime.workspaces.stub('connectWorkspace', () => Promise.resolve(OTHER))
+    void resident.selectWorkspace('workspace-3' as never)
+    await vi.waitFor(() => {
+      expect(b.runtime.sessions.calls).toContainEqual({ method: 'open', args: [OTHER] })
+    })
+    expect(b.inputSurface(OTHER).state.getSnapshot().draft).toBe('')
+
+    // Connect failure: the rejection propagates to the caller (the view owns
+    // the rollback) and no further navigation happens.
+    const opens = b.runtime.sessions.calls.filter(c => c.method === 'open').length
+    b.runtime.workspaces.stub('connectWorkspace', () => Promise.reject(new Error('offline')))
+    await expect(resident.selectWorkspace('workspace-4' as never)).rejects.toThrow('offline')
+    expect(b.runtime.sessions.calls.filter(c => c.method === 'open')).toHaveLength(opens)
+    await b.runtime.dispose()
+  })
+
+  it('scopedConversation fails loud when the session resolves no scope', async () => {
+    const b = await bench()
+    // The chat-view inject resolves the scoped conversation service at inject
+    // time: an unlisted session hits the scope() === undefined throw directly.
+    const entry = b.entryOf('conversation.view')
+    const injectFn = entry.inject as unknown as (sessionId: SessionId, actions: unknown) => unknown
+    expect(() => injectFn('never-listed' as SessionId, {})).toThrow(/resolved no scope/)
+    await b.runtime.dispose()
   })
 
   it('views read face projects the ring ledger (subscribe/version through ctx.slots)', async () => {
@@ -313,6 +298,7 @@ describe('conversation slot inject surface', () => {
     off()
     off2()
     unsub()
+    await b.runtime.dispose()
   })
 })
 
@@ -325,9 +311,9 @@ describe('details inject surface', () => {
     injected.closeDetails()
     expect(b.layoutFake.closeDetails).toHaveBeenCalledTimes(1)
     // The shared handle: details resolves the SAME instance conversation writes.
-    const conv = b.hostFace.storeOf(b.entryOf('conversation.session'), ROOT)
-    const details = b.hostFace.storeOf(entry, ROOT)
+    const conv = b.runtime.storeOf('conversation.session', ROOT)
+    const details = b.runtime.storeOf('details', ROOT)
     expect(details).toBe(conv)
+    await b.runtime.dispose()
   })
-
 })

packages/client/ui-conversation/tests/chat-apply.spec.tsx

@@ -1,89 +1,53 @@
 // @vitest-environment jsdom
 // apply wiring: the conversation service provided, the chat view registered
 // as the first 'conversation.view' ring entry declaring the keyed toolview
-// hole, the three slot registrations land against a root entry's children
-// declarations (the AppFrame role), the shared store handle rides all session
-// entries, and the bash sample mounts through the load-order seam as a keyed
-// entry. Full-chain rendering belongs to the machinery spec
-// (chat-toolview-slot.spec.tsx) and the shell e2e; this spec stops at the
-// assembly surface.
+// hole, the slot registrations land against a root entry's children
+// declarations (the AppFrame role), the shared store handle rides all strict
+// session entries, and the bash sample + todo row mount through the
+// load-order seam as keyed entries. Full-chain rendering belongs to the
+// machinery spec (chat-toolview-slot.spec.tsx) and the shell e2e; this spec
+// stops at the assembly surface.
 
-import { Context } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
-import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
-import type { SessionId, SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
+import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
 const ROOT = 'root-1' as SessionId
 const CHILD = 'child-1' as SessionId
 
 async function bench() {
-  const ctx = new Context()
-  const slotsFiber = ctx.plugin(SlotsService)
-  await slotsFiber.await()
+  const runtime = await SlotTestRuntime.create()
+  await runtime.sessions.add({ id: ROOT, summary: { title: 'R', displayTitle: 'R' } }, { current: false })
+  await runtime.sessions.add(
+    { id: CHILD, summary: { title: 'C', displayTitle: 'C', parentId: ROOT } }, { current: false })
+  runtime.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
 
-  const listStore = createSnapshotStore<SessionListState>({
-    ids: [ROOT, CHILD],
-    byId: {
-      [ROOT]: { id: ROOT, title: 'R', displayTitle: 'R', running: false, blank: false, updatedAt: 1 },
-      [CHILD]: { id: CHILD, title: 'C', displayTitle: 'C', parentId: ROOT, running: false, blank: false, updatedAt: 2 },
-    },
-    current: undefined,
-    phase: 'ready',
-  })
-  const absentInfo = { sessionId: undefined, hooks: {}, props: {} }
-  const sessionsFake = {
-    list: listStore,
-    binding: vi.fn(),
-    scope: () => undefined,
-    provideInfo: () => undefined,
-    currentProvideInfo: { getSnapshot: () => absentInfo, subscribe: () => () => {} },
-    provide: vi.fn(() => () => {}),
-    create: vi.fn(),
-    open: vi.fn(),
-    updateIntent: vi.fn(),
-  }
-  ctx.provide('sessions', sessionsFake)
-  ctx.provide('workspaces', {
-    startSession: vi.fn(),
-    sendSession: vi.fn(),
-    openPath: vi.fn(async () => {}),
-  })
-  ctx.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
-  ctx.provide('locale', { bind: () => (key: string) => key })
-
-  // Declared by ui-layout's root entry in production; a stand-in root
-  // occupant declares them here so the contributions land (it consumes
-  // renderSlot to satisfy the declare-means-render check).
-  const slots = ctx.get('slots') as SlotsService
-  slots.register({
-    name: 'root',
-    children: {
-      'conversation': { kind: 'single', scope: 'session-maybe' },
-      'details': { kind: 'single', scope: 'session' },
-    },
+  // Declared by ui-layout's root entry in production; the test root declares
+  // them here so the contributions land.
+  await runtime.root.declare({
+    'conversation': { kind: 'single', scope: 'session-maybe' },
+    'details': { kind: 'single', scope: 'session' },
   }, (_p: { renderSlot?: unknown }) => null)
 
-  const fiber = ctx.plugin({ inject: [...inject], apply })
-  return { ctx, fiber, slots }
+  const feature = await runtime.mount({ inject: [...inject], apply })
+  return { runtime, feature, slots: runtime.slots }
 }
 
 /** First stored entry for a key (inject/store live directly on StoredEntry). */
-function renderEntryOf(slots: SlotsService, key: 'conversation' | 'conversation.session' | 'conversation.view' | 'details') {
+function renderEntryOf(slots: Awaited<ReturnType<typeof bench>>['slots'], key: 'conversation' | 'conversation.session' | 'conversation.view' | 'details') {
   return slots.entries(key)[0] as undefined | { inject?: unknown; store?: unknown }
 }
 
 describe('apply wiring', () => {
   it('provides the conversation service', async () => {
     const b = await bench()
-    await b.fiber.await()
-    expect(b.ctx.get('conversation')).toBeDefined()
+    expect(b.runtime.ctx.get('conversation')).toBeDefined()
+    await b.runtime.dispose()
   })
 
   it('registers the chat view as the first ring entry, declaring the keyed toolview hole', async () => {
     const b = await bench()
-    await b.fiber.await()
     const entries = b.slots.entries('conversation.view')
     expect(entries.map(e => e.options.id)).toEqual(['chat'])
     expect(entries[0]?.options.label).toBe('Chat')
@@ -91,11 +55,11 @@ describe('apply wiring', () => {
     // Declaring is claiming: the chat entry's registration put the hole on
     // the ledger with the contract's kind/scope.
     expect(b.slots.spec('conversation.chat.toolview')).toEqual({ kind: 'keyed', scope: 'session' })
+    await b.runtime.dispose()
   })
 
   it('occupies the slots + the ring; session entries share one store handle', async () => {
     const b = await bench()
-    await b.fiber.await()
     const conversation = renderEntryOf(b.slots, 'conversation')
     const conversationSession = renderEntryOf(b.slots, 'conversation.session')
     const chatView = renderEntryOf(b.slots, 'conversation.view')
@@ -111,21 +75,21 @@ describe('apply wiring', () => {
     // The hero workspace picker hole rides the conversation entry's children
     // declaration (the empty-state occupant is gone).
     expect(b.slots.spec('conversation.hero.workspace')).toEqual({ kind: 'single', scope: 'root' })
+    await b.runtime.dispose()
   })
 
   it('mounts the bash sample and the todo row as keyed entries through the load-order seam', async () => {
     const b = await bench()
-    await b.fiber.await()
     // Both registrant plugins' inject: ['slots', 'conversation'] resolved — the
     // service being present implies the chat entry declared the hole first.
     const entries = b.slots.entries('conversation.chat.toolview')
     expect(entries.map(e => e.options.key)).toEqual(['bash', 'todo_write'])
+    await b.runtime.dispose()
   })
 
   it('plugin fiber disposal collects every registration (unload cascade, ring and hole included)', async () => {
     const b = await bench()
-    await b.fiber.await()
-    await b.fiber.dispose()
+    await b.feature.dispose()
     expect(b.slots.entries('conversation')).toHaveLength(0)
     // The declared ring collapses with its declaring entry, and the chat
     // entry's keyed hole (with the sample's registration) collapses with it.
@@ -133,6 +97,7 @@ describe('apply wiring', () => {
     expect(b.slots.entries('conversation.chat.toolview')).toHaveLength(0)
     expect(b.slots.spec('conversation.chat.toolview')).toBeUndefined()
     expect(b.slots.entries('details')).toHaveLength(0)
-    expect(b.ctx.get('conversation')).toBeUndefined()
+    expect(b.runtime.ctx.get('conversation')).toBeUndefined()
+    await b.runtime.dispose()
   })
 })

packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx

@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 // The dissolved tool ring's acceptance chain on the REAL machinery stack:
-// cordis Context + SlotsService ledger + the web-react renderer + this
-// package's own apply — no outlet twins. Proves the keyed
+// SlotTestRuntime (cordis Context + SlotsService ledger + the web-react
+// renderer) + this package's own apply — no outlet twins. Proves the keyed
 // 'conversation.chat.toolview' hole end to end: registered rows dispatch by
 // entryKey (the bash sample lands through its plugin), unregistered tools
 // fall back to GenericToolCard at the render site, live registration/unload
@@ -10,23 +10,16 @@
 // inject: ['slots', 'conversation'] load-order seam suspends on real fiber
 // semantics until the service (and with it the hole declaration) is present.
 
-import { Context } from 'cordis'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { act, cleanup, fireEvent, render } from '@testing-library/react'
-import { createSnapshotStore, SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
-import type {
-  ConversationSnapshot, SessionId, SessionListState, ToolResultNode, WorkspaceListState,
-} from '@deepseek-ai/dsh-client-runtime/client'
-import { createSlotRenderer } from '@deepseek-ai/dsh-client-web-react'
+import { cleanup, fireEvent } from '@testing-library/react'
+import type { ISession, SessionId, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
 import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
+import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { ToolRowProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
 const SID = 's1' as SessionId
 
-/** Identity-stable no-session bundle (uSES getSnapshot contract). */
-const ABSENT_INFO = { sessionId: undefined, hooks: {}, props: {} }
-
 afterEach(cleanup)
 // The chat store persists under its declared key; clear between cases.
 beforeEach(() => {
@@ -40,117 +33,38 @@ const toolResult = (seq: number, callId: string, name: string, args = '{"command
   content: [], isError: false, callView: null, resultView: null,
 })
 
-function snapshotWith(nodes: ToolResultNode[]): ConversationSnapshot {
-  return {
-    sessionId: SID, nodes, foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(),
-    pending: [], queue: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null,
-    hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null,
-  }
-}
-
 /** Test-owned AppFrame role: declares and renders the resident conversation area. */
 type AppRootProps = PropsRenderSlots<'conversation' | 'details'>
 function AppRoot({ renderSlot }: AppRootProps) {
   return <>{renderSlot('conversation', {})}</>
 }
 
+const LAYOUT_CHILDREN = {
+  'conversation': { kind: 'single', scope: 'session-maybe' },
+  'details': { kind: 'single', scope: 'session' },
+} as const
+
 /**
- * Real-stack bench: SlotsService plugin, renderer installed, sessions/layout
- * fakes at the service seams only (external boundaries), the package apply on
- * its own fiber, and the test AppFrame occupying 'root'.
+ * Real-stack bench: SlotTestRuntime with the session/layout doubles at the
+ * service seams only (external boundaries), the package apply on its own
+ * fiber, and the test AppFrame occupying 'root'.
  */
 async function bench(nodes: ToolResultNode[]) {
-  const ctx = new Context()
-  const slotsFiber = ctx.plugin(SlotsService)
-  await slotsFiber.await()
-  const slots = ctx.get('slots') as SlotsService
-
-  const session = createSnapshotStore<ConversationSnapshot>(snapshotWith(nodes))
-  const list = createSnapshotStore<SessionListState>({
-    ids: [SID],
-    byId: { [SID]: { id: SID, title: 'S', displayTitle: 'S', running: false, blank: false, updatedAt: 1 } },
-    current: SID,
-    phase: 'ready',
-  })
-  // Identity-stable provide bundle: the renderer caches hooks per source and
-  // inject results per bundle, both by object identity. Registered providers
-  // (the package's input contribution) materialize into it lazily, once.
-  const providers: ((binding: object) => { hooks?: object; props?: object })[] = []
-  let info: { sessionId: SessionId; hooks: object; props: object } | undefined
-  const scoped = { send: vi.fn(async () => {}), cancel: vi.fn(async () => {}) }
+  const runtime = await SlotTestRuntime.create()
   const layout = { openDetails: vi.fn(), closeDetails: vi.fn() }
-  const actxFake = { get: () => scoped, effect: () => {}, on: () => () => {} }
-  const bindingOf = (id: SessionId) => ({
-    sessionId: id,
-    ctx: actxFake,
+  runtime.provide('layout', layout)
+  await runtime.sessions.add({
+    id: SID,
+    summary: { title: 'S', displayTitle: 'S' },
+    snapshot: { nodes },
     session: {
-      sessionId: id,
-      loadOlder: vi.fn(),
-      prompt: vi.fn(async () => ({ ok: true, value: { accepted: true } })),
-      // Observable face for the input machine's queue read face.
-      getSnapshot: () => session.getSnapshot(),
-      subscribe: (fn: () => void) => session.subscribe(fn),
+      loadOlder: vi.fn<ISession['loadOlder']>(),
+      prompt: vi.fn<ISession['prompt']>(async () => ({ ok: true, value: { accepted: true } })),
     },
   })
-  const provideInfo = (id: string) => {
-    if (id !== SID) return undefined
-    if (info === undefined) {
-      const hooks: Record<string, unknown> = { session }
-      const props: Record<string, unknown> = {}
-      for (const provider of providers) {
-        const c = provider(bindingOf(SID))
-        Object.assign(hooks, c.hooks ?? {})
-        Object.assign(props, c.props ?? {})
-      }
-      info = { sessionId: SID, hooks, props }
-    }
-    return info
-  }
-  ctx.provide('sessions', {
-    list,
-    binding: bindingOf,
-    scope: () => actxFake,
-    provideInfo,
-    currentProvideInfo: {
-      getSnapshot: () => provideInfo(SID),
-      subscribe: () => () => {},
-    },
-    provide: (d: { resolve: (typeof providers)[number] }) => { providers.push(d.resolve); return () => {} },
-    scopeOf: () => SID,
-    create: vi.fn(),
-    open: vi.fn(),
-    updateIntent: vi.fn(),
-  })
-  const workspaces = {
-    list: createSnapshotStore<WorkspaceListState>({
-      items: [], state: 'idle', phase: 'ready', error: null,
-      baselinesReady: true, recentWorkspaceId: undefined,
-    }),
-    startSession: vi.fn(),
-    sendSession: vi.fn(),
-    openPath: vi.fn(async () => {}),
-  }
-  ctx.provide('workspaces', workspaces)
-  ctx.provide('layout', layout)
-  ctx.provide('locale', { bind: () => (key: string) => key })
-
-  slots.install(createSlotRenderer())
-  slots.register({
-    name: 'root',
-    children: {
-      'conversation': { kind: 'single', scope: 'session-maybe' },
-      'details': { kind: 'single', scope: 'session' },
-    },
-  }, AppRoot)
-
-  const fiber = ctx.plugin({ inject: [...inject], apply })
-  await fiber.await()
-  return { ctx, slots, fiber, session, list, layout, workspaces }
-}
-
-/** Render the whole tree through the ctx-level root seam (the shell's own entry). */
-function mountApp(slots: SlotsService) {
-  return render(<>{slots.renderSlot('root', {})}</>)
+  await runtime.root.declare(LAYOUT_CHILDREN, AppRoot)
+  const feature = await runtime.mount({ inject: [...inject], apply })
+  return { runtime, slots: runtime.slots, feature, layout }
 }
 
 describe('keyed toolview hole through the real machinery', () => {
@@ -159,7 +73,7 @@ describe('keyed toolview hole through the real machinery', () => {
       toolResult(3, 'c1', 'bash'),
       toolResult(4, 'c2', 'mystery', '{"n":1}'),
     ])
-    const view = mountApp(b.slots)
+    const view = b.runtime.renderRoot()
     // bash: the sample plugin's keyed registration took the row (root
     // session → global arm, decided inside the component off useSessions).
     expect(view.container.querySelector('[data-sample="bash-global"]')).not.toBeNull()
@@ -167,6 +81,7 @@ describe('keyed toolview hole through the real machinery', () => {
     expect(view.getByText('Build')).toBeTruthy()
     // mystery: no registration under that key → render-site fallback.
     expect(view.getByText('Tool call')).toBeTruthy()
+    await b.runtime.dispose()
   })
 
   it('renders top-level Cordis calls with lifecycle titles over the generic variants', async () => {
@@ -176,7 +91,7 @@ describe('keyed toolview hole through the real machinery', () => {
       toolResult(4, 'cordis-2', 'cordis_mount', JSON.stringify({ code })),
       toolResult(5, 'cordis-3', 'cordis_unmount', '{"id":"dyn-2"}'),
     ])
-    const view = mountApp(b.slots)
+    const view = b.runtime.renderRoot()
 
     expect(view.container.querySelector('[data-tool="cordis_inspect"]')?.textContent).toContain('Inspect')
     const mounted = view.container.querySelector('[data-variant="code"]')
@@ -186,42 +101,46 @@ describe('keyed toolview hole through the real machinery', () => {
 
     fireEvent.click(mounted!.querySelector('button[aria-expanded]')!)
     expect(mounted!.querySelector('pre.shiki')?.textContent).toBe(code)
+    await b.runtime.dispose()
   })
 
   it('file-path clicks travel owner openFile → chat inject → workspaces.openPath', async () => {
     const b = await bench([toolResult(3, 'c1', 'read', '{"path":"src/a.ts"}')])
-    const view = mountApp(b.slots)
+    const view = b.runtime.renderRoot()
     view.getByText('src/a.ts').click()
     expect(b.layout.openDetails).not.toHaveBeenCalled()
     await vi.waitFor(() => {
-      expect(b.workspaces.openPath).toHaveBeenCalledWith('src/a.ts')
+      expect(b.runtime.workspaces.calls).toContainEqual({ method: 'openPath', args: ['src/a.ts'] })
     })
+    await b.runtime.dispose()
   })
 
   it('bash summary clicks do not open details or host paths', async () => {
     const b = await bench([toolResult(3, 'c1', 'bash')])
-    const view = mountApp(b.slots)
+    const view = b.runtime.renderRoot()
     view.getByText('Build').click()
     expect(b.layout.openDetails).not.toHaveBeenCalled()
-    expect(b.workspaces.openPath).not.toHaveBeenCalled()
+    expect(b.runtime.workspaces.calls.some(c => c.method === 'openPath')).toBe(false)
+    await b.runtime.dispose()
   })
 
   it('a live keyed registration takes over its tool row and unload reverts to the fallback', async () => {
     const b = await bench([toolResult(3, 'c2', 'mystery', '{"n":1}')])
-    const view = mountApp(b.slots)
+    const view = b.runtime.renderRoot()
     expect(view.getByText('Tool call')).toBeTruthy()
     let dispose = (): void => {}
-    await act(async () => {
-      dispose = b.slots.register(
-        { name: 'conversation.chat.toolview', key: 'mystery' },
-        () => <div data-testid="mystery-row" />)
-    })
+    dispose = b.slots.register(
+      { name: 'conversation.chat.toolview', key: 'mystery' },
+      () => <div data-testid="mystery-row" />)
+    await b.runtime.flush()
     // Per-key version tick: the row flipped without a remount of the view.
     expect(view.getByTestId('mystery-row')).toBeTruthy()
     expect(view.queryByText('Tool call')).toBeNull()
-    await act(async () => { dispose() })
+    dispose()
+    await b.runtime.flush()
     expect(view.queryByTestId('mystery-row')).toBeNull()
     expect(view.getByText('Tool call')).toBeTruthy()
+    await b.runtime.dispose()
   })
 
   it('a duplicate key registration fails loud at load', async () => {
@@ -230,6 +149,7 @@ describe('keyed toolview hole through the real machinery', () => {
       { name: 'conversation.chat.toolview', key: 'bash' },
       () => null,
     )).toThrow(/key "bash"/)
+    await b.runtime.dispose()
   })
 
   it('the inject channel feeds (sessionId) => I into the row component', async () => {
@@ -247,66 +167,33 @@ describe('keyed toolview hole through the real machinery', () => {
     }, ({ mark, poke }: ToolRowProps & { mark: string; poke: () => void }) => (
       <button data-testid="probe-row" onClick={poke}>{mark}</button>
     ))
-    const view = mountApp(b.slots)
+    const view = b.runtime.renderRoot()
     const row = view.getByTestId('probe-row')
     expect(row.textContent).toBe(`for:${SID}`)
     row.click()
     expect(poked).toEqual([SID])
+    await b.runtime.dispose()
   })
 })
 
 describe('registrant load-order seam', () => {
   it("suspends a registrant on inject: ['slots', 'conversation'] until the service (and the hole) exists", async () => {
-    const ctx = new Context()
-    const slotsFiber = ctx.plugin(SlotsService)
-    await slotsFiber.await()
-    const slots = ctx.get('slots') as SlotsService
-    ctx.provide('sessions', {
-      list: createSnapshotStore<SessionListState>({
-        ids: [], byId: {}, current: undefined, phase: 'ready',
-      }),
-      binding: () => undefined,
-      scope: () => undefined,
-      provideInfo: () => undefined,
-      currentProvideInfo: {
-        getSnapshot: () => ABSENT_INFO,
-        subscribe: () => () => {},
-      },
-      provide: () => () => {},
-      create: vi.fn(),
-      open: vi.fn(),
-      updateIntent: vi.fn(),
-    })
-    ctx.provide('workspaces', {
-      list: createSnapshotStore<WorkspaceListState>({
-        items: [], state: 'idle', phase: 'ready', error: null,
-        baselinesReady: true, recentWorkspaceId: undefined,
-      }),
-      startSession: vi.fn(),
-      sendSession: vi.fn(),
-      openPath: vi.fn(async () => {}),
-    })
-    ctx.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
-    ctx.provide('locale', { bind: () => (key: string) => key })
-    slots.register({
-      name: 'root',
-      children: {
-        'conversation': { kind: 'single', scope: 'session-maybe' },
-        'details': { kind: 'single', scope: 'session' },
-      },
-    }, AppRoot)
+    const runtime = await SlotTestRuntime.create()
+    runtime.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
+    await runtime.root.declare(LAYOUT_CHILDREN, AppRoot)
 
     // Third-party posture, mounted BEFORE ui-conversation: real fiber inject
     // semantics hold it — apply must not run while 'conversation' is absent.
-    // (Plain arrow, not vi.fn: mock functions carry a prototype and trip the
-    // fiber's isConstructor branch.)
+    // Uses ctx.plugin directly (the deliberate-suspension escape hatch; mount()
+    // would fail loud on the missing service). (Plain arrow, not vi.fn: mock
+    // functions carry a prototype and trip the fiber's isConstructor branch.)
     let applyRuns = 0
-    const registrantApply = (registrantCtx: Context): void => {
+    const registrantApply = (registrantCtx: typeof runtime.ctx): void => {
       applyRuns += 1
       registrantCtx.slots.register(
         { name: 'conversation.chat.toolview', key: 'late' }, () => null)
     }
-    const late = ctx.plugin({
+    const late = runtime.ctx.plugin({
       name: 'late-registrant',
       inject: ['slots', 'conversation'],
       apply: registrantApply,
@@ -317,11 +204,11 @@ describe('registrant load-order seam', () => {
     // Mounting the package resolves the seam: service present ⟹ the chat
     // entry (and its hole declaration) is already on the ledger, so the
     // suspended registrant lands without an undeclared-slot throw.
-    const fiber = ctx.plugin({ inject: [...inject], apply })
-    await fiber.await()
+    await runtime.mount({ inject: [...inject], apply })
     await late.await()
     expect(applyRuns).toBe(1)
-    expect(slots.entries('conversation.chat.toolview').map(e => e.options.key))
+    expect(runtime.slots.entries('conversation.chat.toolview').map(e => e.options.key))
       .toEqual(expect.arrayContaining(['bash', 'late']))
+    await runtime.dispose()
   })
 })

packages/client/ui-conversation/tests/selection-survival.spec.ts

@@ -1,149 +0,0 @@
-// @vitest-environment jsdom
-/**
- * Exercises selection persistence through the real SlotsService store axis;
- * component stubs cannot prove per-session identity or disposal.
- */
-import { Context } from 'cordis'
-import { beforeEach, describe, expect, it } from 'vitest'
-import { createSnapshotStore, SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
-import type { SessionId, SessionListState, WorkspaceListState } from '@deepseek-ai/dsh-client-runtime/client'
-import { createChatStore } from '../src/client/stores.ts'
-
-const sid = (s: string): SessionId => s as SessionId
-
-/** Identity-stable no-session bundle (uSES getSnapshot contract). */
-const ABSENT_INFO = { sessionId: undefined, hooks: {}, props: {} }
-
-interface Bench {
-  slots: SlotsService
-  chat: ReturnType<typeof createChatStore>
-}
-
-function bench(): Bench {
-  const ctx = new Context()
-  ctx.provide('sessions', {
-    list: createSnapshotStore<SessionListState>({
-      ids: [], byId: {}, current: undefined, phase: 'ready',
-    }),
-    provideInfo: () => undefined,
-    currentProvideInfo: {
-      getSnapshot: () => ABSENT_INFO,
-      subscribe: () => () => {},
-    },
-    provide: () => () => {},
-  })
-  ctx.provide('workspaces', {
-    list: createSnapshotStore<WorkspaceListState>({
-      items: [], state: 'idle', phase: 'ready', error: null,
-      baselinesReady: true, recentWorkspaceId: undefined,
-    }),
-  })
-  // Service self-registers as ctx 'slots' (cordis Service constructor).
-  const slots = new SlotsService(ctx)
-  const chat = createChatStore()
-  // The apply.ts shape: one shared handle across both session-slot
-  // registrations. 'conversation'/'details' must first exist in the ledger —
-  // register a root occupant declaring them (the AppFrame role; the stand-in
-  // consumes renderSlot to satisfy the declare-means-render check).
-  slots.register({
-    name: 'root',
-    children: {
-      'conversation': { kind: 'single', scope: 'session-maybe' },
-      'conversation.session': { kind: 'single', scope: 'session' },
-      'details': { kind: 'single', scope: 'session' },
-    },
-  }, (_p: { renderSlot?: unknown }) => null)
-  // apply.ts mounts the shared chat handle only under session-scope slots
-  // (the session-maybe 'conversation' shell carries no store).
-  slots.register({ name: 'conversation.session', store: chat }, () => null)
-  slots.register({ name: 'details', store: chat }, () => null)
-  return { slots, chat }
-}
-
-/** Resolve the store instance the renderer would hand a slot's component for a session. */
-function storeFor(b: Bench, slot: 'conversation.session' | 'details', sessionId: SessionId) {
-  const host = renderHost(b)
-  const entry = host.entriesOf(slot)[0]!
-  return host.storeOf(entry, sessionId)! as ReturnType<ReturnType<typeof createChatStore>['create']>
-}
-
-/** The host face is only built at renderSlot time; install a stub renderer once to reach it. */
-function renderHost(b: Bench): import('@deepseek-ai/dsh-client-ui-slots').SlotRendererHost {
-  const captured = (b as unknown as { _host?: import('@deepseek-ai/dsh-client-ui-slots').SlotRendererHost })
-  if (captured._host === undefined) {
-    b.slots.install({
-      renderRoot: (host) => {
-        captured._host = host
-        return null
-      },
-    })
-    b.slots.renderSlot('root', {})
-  }
-  return captured._host!
-}
-
-beforeEach(() => {
-  localStorage.clear()
-})
-
-describe('selection survives on the store seat', () => {
-  it('one session, two slots: conversation writes, details reads the SAME instance', () => {
-    const b = bench()
-
-    const conv = storeFor(b, 'conversation.session', sid('s1'))
-    const details = storeFor(b, 'details', sid('s1'))
-    conv.actions.select({ turnSeq: 3, callId: 'c1' })
-    expect(details.store.getSnapshot().selection).toEqual({ turnSeq: 3, callId: 'c1' })
-    // Identity, not just value: the shared handle resolves one instance per scope key.
-    expect(details).toBe(conv)
-  })
-
-  it('sessions are isolated: s2 selection never bleeds into s1', () => {
-    const b = bench()
-
-    const one = storeFor(b, 'conversation.session', sid('s1'))
-    const two = storeFor(b, 'conversation.session', sid('s2'))
-    expect(two).not.toBe(one)
-    one.actions.select({ turnSeq: 1, callId: 'a' })
-    two.actions.select({ turnSeq: 9, callId: 'z' })
-    expect(one.store.getSnapshot().selection).toEqual({ turnSeq: 1, callId: 'a' })
-    expect(two.store.getSnapshot().selection).toEqual({ turnSeq: 9, callId: 'z' })
-  })
-
-  it('a list-projection update keeps instance identity and the selection value', () => {
-    const b = bench()
-    const id = sid('s1')
-    const projection = createSnapshotStore({ displayTitle: 's1' })
-
-    const store = storeFor(b, 'conversation.session', id)
-    store.actions.select({ turnSeq: 3, callId: 'c1' })
-    store.actions.setDraft('half-typed')
-
-    projection.set({ displayTitle: 'proj-a' })
-    expect(projection.getSnapshot().displayTitle).toBe('proj-a')
-
-    const after = storeFor(b, 'conversation.session', id)
-    expect(after).toBe(store)
-    expect(after.store.getSnapshot().selection).toEqual({ turnSeq: 3, callId: 'c1' })
-    expect(after.store.getSnapshot().draft).toBe('half-typed')
-  })
-
-  it('session death buries the instance and its persisted draft', () => {
-    const b = bench()
-
-    const doomed = storeFor(b, 'conversation.session', sid('s1'))
-    doomed.actions.setDraft('to be buried')
-    doomed.actions.select({ turnSeq: 1 })
-    expect(localStorage.getItem('dsh.conversation.chat.s1')).not.toBeNull()
-
-    // SessionsService calls this public slot lifecycle seam when the scope dies.
-    b.slots.pruneStoreScope(sid('s1'))
-
-    // Persisted residue is gone with the session...
-    expect(localStorage.getItem('dsh.conversation.chat.s1')).toBeNull()
-    // ...and a re-created same-id session starts from a FRESH instance.
-    const reborn = storeFor(b, 'conversation.session', sid('s1'))
-    expect(reborn).not.toBe(doomed)
-    expect(reborn.store.getSnapshot()).toEqual({ selection: null, draft: '', view: null })
-  })
-})

packages/client/ui-conversation/tests/selection-survival.spec.tsx

@@ -0,0 +1,109 @@
+// @vitest-environment jsdom
+/**
+ * Exercises selection persistence through the real SlotsService store axis;
+ * component stubs cannot prove per-session identity or disposal.
+ */
+import { beforeEach, describe, expect, it } from 'vitest'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
+import { createChatStore } from '../src/client/stores.ts'
+
+const sid = (s: string): SessionId => s as SessionId
+
+type ChatInstance = ReturnType<ReturnType<typeof createChatStore>['create']>
+
+async function bench() {
+  const runtime = await SlotTestRuntime.create()
+  const chat = createChatStore()
+  // The apply.ts shape: one shared handle across both strict-session slot
+  // registrations ('conversation.session'/'details'); the session-maybe
+  // 'conversation' shell carries no store by design. The slots must first
+  // exist in the ledger — the test root declares them (the AppFrame role).
+  await runtime.root.declare({
+    'conversation': { kind: 'single', scope: 'session-maybe' },
+    'conversation.session': { kind: 'single', scope: 'session' },
+    'details': { kind: 'single', scope: 'session' },
+  }, (_p: { renderSlot?: unknown }) => null)
+  runtime.slots.register({ name: 'conversation.session', store: chat }, () => null)
+  runtime.slots.register({ name: 'details', store: chat }, () => null)
+  runtime.renderRoot() // materializes the host face storeOf resolves through
+  return { runtime, chat }
+}
+
+/** Resolve the store instance the renderer would hand a slot's component for a session. */
+function storeFor(b: Awaited<ReturnType<typeof bench>>, slot: 'conversation.session' | 'details', sessionId: SessionId) {
+  return b.runtime.storeOf(slot, sessionId) as ChatInstance
+}
+
+beforeEach(() => {
+  localStorage.clear()
+})
+
+describe('selection survives on the store seat', () => {
+  it('one session, two slots: conversation writes, details reads the SAME instance', async () => {
+    const b = await bench()
+
+    const conv = storeFor(b, 'conversation.session', sid('s1'))
+    const details = storeFor(b, 'details', sid('s1'))
+    conv.actions.select({ turnSeq: 3, callId: 'c1' })
+    expect(details.store.getSnapshot().selection).toEqual({ turnSeq: 3, callId: 'c1' })
+    // Identity, not just value: the shared handle resolves one instance per scope key.
+    expect(details).toBe(conv)
+    await b.runtime.dispose()
+  })
+
+  it('sessions are isolated: s2 selection never bleeds into s1', async () => {
+    const b = await bench()
+
+    const one = storeFor(b, 'conversation.session', sid('s1'))
+    const two = storeFor(b, 'conversation.session', sid('s2'))
+    expect(two).not.toBe(one)
+    one.actions.select({ turnSeq: 1, callId: 'a' })
+    two.actions.select({ turnSeq: 9, callId: 'z' })
+    expect(one.store.getSnapshot().selection).toEqual({ turnSeq: 1, callId: 'a' })
+    expect(two.store.getSnapshot().selection).toEqual({ turnSeq: 9, callId: 'z' })
+    await b.runtime.dispose()
+  })
+
+  it('a list-projection update keeps instance identity and the selection value', async () => {
+    const b = await bench()
+    const id = sid('s1')
+
+    const store = storeFor(b, 'conversation.session', id)
+    store.actions.select({ turnSeq: 3, callId: 'c1' })
+    store.actions.setDraft('half-typed')
+
+    // A projection churn elsewhere (list rows re-projected) must not touch
+    // store identity: drive the runtime's own list observable.
+    await b.runtime.sessions.add({ id, summary: { displayTitle: 'proj-a' } })
+    expect(b.runtime.sessions.list.getSnapshot().byId[id]?.displayTitle).toBe('proj-a')
+
+    const after = storeFor(b, 'conversation.session', id)
+    expect(after).toBe(store)
+    expect(after.store.getSnapshot().selection).toEqual({ turnSeq: 3, callId: 'c1' })
+    expect(after.store.getSnapshot().draft).toBe('half-typed')
+    await b.runtime.dispose()
+  })
+
+  it('session death buries the instance and its persisted draft', async () => {
+    const b = await bench()
+    await b.runtime.sessions.add({ id: 's1' })
+
+    const doomed = storeFor(b, 'conversation.session', sid('s1'))
+    doomed.actions.setDraft('to be buried')
+    doomed.actions.select({ turnSeq: 1 })
+    expect(localStorage.getItem('dsh.conversation.chat.s1')).not.toBeNull()
+
+    // TestSessions.remove drives the same public slot lifecycle seam the
+    // production SessionsService calls when the scope dies (pruneStoreScope).
+    await b.runtime.sessions.remove('s1')
+
+    // Persisted residue is gone with the session...
+    expect(localStorage.getItem('dsh.conversation.chat.s1')).toBeNull()
+    // ...and a re-created same-id session starts from a FRESH instance.
+    const reborn = storeFor(b, 'conversation.session', sid('s1'))
+    expect(reborn).not.toBe(doomed)
+    expect(reborn.store.getSnapshot()).toEqual({ selection: null, draft: '', view: null })
+    await b.runtime.dispose()
+  })
+})

packages/client/ui-conversation/tests/service-orchestration.spec.ts

@@ -1,39 +1,32 @@
 // @vitest-environment jsdom
+// ConversationService scope addressing over the runtime's real scope tag:
+// TestSessions mints tagged scopes through the production createScope, so the
+// service's scopeOf/binding path runs against production resolution (no local
+// tag probe).
 import { Context } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
-import { scopeOf } from '@deepseek-ai/dsh-client-runtime/client'
-import type { SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
 import { ConversationService } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { InputHub } from '../src/client/input/hub.ts'
 
-const sid = (id: string) => id as SessionId
-const SCOPE_TAG: symbol = (() => {
-  const reads: (string | symbol)[] = []
-  const proxy = new Proxy(new Context(), {
-    get(target, property, receiver): unknown {
-      reads.push(property)
-      return Reflect.get(target, property, receiver)
-    },
-  })
-  void scopeOf(proxy)
-  return reads.find((value): value is symbol => typeof value === 'symbol')!
-})()
-
-async function bench(withSessions = true) {
-  const ctx = new Context()
+async function bench() {
+  const runtime = await SlotTestRuntime.create()
   const prompt = vi.fn(() => Promise.resolve({ ok: true as const, value: { accepted: true as const } }))
   const cancel = vi.fn(() => Promise.resolve({ ok: true as const, value: { accepted: true as const } }))
   const loadOlder = vi.fn(() => Promise.resolve())
-  const sessions = {
-    binding: (sessionId: SessionId) => ({
-      sessionId, session: { prompt, cancel, loadOlder },
-    }),
-    scopeOf,
-  } as unknown as SessionsService
-  if (withSessions) ctx.provide('sessions', sessions)
-  await ctx.plugin(ConversationService).await()
-  const root = ctx.get('conversation') as ConversationService
-  const scoped = ctx.plugin(() => {}).ctx.extend({ [SCOPE_TAG]: sid('s1') }).get('conversation') as ConversationService
-  return { root, scoped, prompt, cancel, loadOlder }
+  await runtime.sessions.add({
+    id: 's1',
+    session: { prompt, cancel, loadOlder },
+  })
+  // config.input is required (the apply shares its hub with the inject
+  // factories); the bench passes its own instance explicitly.
+  const fiber = runtime.ctx.plugin(ConversationService, {
+    input: new InputHub(runtime.ctx),
+  })
+  await fiber.await()
+  const root = runtime.ctx.get('conversation') as ConversationService
+  const scoped = runtime.sessions.scope('s1')!.get('conversation') as ConversationService
+  return { runtime, root, scoped, prompt, cancel, loadOlder }
 }
 
 describe('ConversationService', () => {
@@ -45,6 +38,7 @@ describe('ConversationService', () => {
     expect(b.prompt).toHaveBeenCalledWith([{ type: 'text', text: 'hello' }], 'steer')
     expect(b.cancel).toHaveBeenCalledOnce()
     expect(b.loadOlder).toHaveBeenCalledOnce()
+    await b.runtime.dispose()
   })
 
   it('folds Session business failures into callback rejections', async () => {
@@ -53,12 +47,21 @@ describe('ConversationService', () => {
     await expect(b.scoped.send('x', 'queue')).rejects.toThrow('conversation.send failed: agent-busy: busy')
     b.cancel.mockResolvedValueOnce({ ok: false, error: { code: 'internal', message: 'nope', details: {} } } as never)
     await expect(b.scoped.cancel()).rejects.toThrow('conversation.cancel failed: internal: nope')
+    await b.runtime.dispose()
   })
 
-  it('fails loudly from the root scope or without SessionsService', async () => {
+  it('fails loudly from the root scope, on an unbound session, or without SessionsService', async () => {
     const b = await bench()
     await expect(b.root.send('x', 'queue')).rejects.toThrow(/requires a session scope/)
-    const missing = await bench(false)
-    await expect(missing.root.send('x', 'queue')).rejects.toThrow(/sessions service unavailable/)
+    await b.runtime.sessions.remove('s1')
+    await expect(b.scoped.send('x', 'queue')).rejects.toThrow(/resolved no binding/)
+    await b.runtime.dispose()
+    // No SessionsService at all: a bare context (the runtime always provides one).
+    const bare = new Context()
+    await bare.plugin(ConversationService, {
+      input: new InputHub(bare),
+    }).await()
+    const orphan = bare.get('conversation') as ConversationService
+    await expect(orphan.send('x', 'queue')).rejects.toThrow(/sessions service unavailable/)
   })
 })

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

@@ -17,14 +17,16 @@ import { ThemePresenter } from './theme-presenter.ts'
 
 // Contract surface only (export-convergence rule: cross-package consumers
 // keep a symbol exported; test-only/package-internal symbols live off /src).
-// LayoutService: the ctx.layout service class (consumers type against it).
+// ILayout: the ctx.layout face consumers and test fakes type against.
 // OwnerShare contracts below are the render-side halves registrants compose
 // against; the frame components and the store factory are package-internal.
 export { LayoutService } from './service.ts'
+export type { ILayout } from './service.ts'
 
 declare module 'cordis' {
   interface Context {
-    layout: LayoutService
+    /** The outward face only; the concrete service stays inside this plugin. */
+    layout: import('./service.ts').ILayout
   }
 }
 

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

@@ -14,8 +14,23 @@ import type { createLayoutStore } from './stores.ts'
 /** The layout store's bound action set (framework-baked, draft params peeled). */
 export type PanelActions = BoundActions<ReturnType<typeof createLayoutStore>>
 
+/**
+ * The outward layout face (`ctx.layout`): the panel transitions other
+ * plugins may trigger — and exactly what a test fake must supply. The
+ * attachPanels wiring hook stays on the concrete class (root-entry assembly
+ * only).
+ */
+export interface ILayout {
+  /** Toggle the sidebar panel (closed ⟷ contract default width). */
+  toggleSidebar(): void
+  /** Open the details panel (no-op when already open). */
+  openDetails(): void
+  /** Close the details panel. */
+  closeDetails(): void
+}
+
 /** Cross-plugin panel-action face (ctx.layout). */
-export class LayoutService {
+export class LayoutService implements ILayout {
   #panels: PanelActions | undefined
 
   /**

packages/client/ui-sidebar/package.json

@@ -47,6 +47,7 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
     "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",

packages/client/ui-sidebar/tests/__snapshots__/sidebar-snapshot.spec.tsx.snap

@@ -0,0 +1,131 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`sidebar shell snapshots > renders the collapsed rail after the crossfade settles, in place 1`] = `
+<div
+  data-slot="sidebar"
+>
+  <div
+    class="root collapsed railIn"
+    style=""
+  >
+    <div
+      class="logoRow"
+    >
+      <button
+        aria-label="Open sidebar"
+        class="iconButton toggle"
+        type="button"
+      >
+        <svg
+          aria-hidden="true"
+          class="railFish"
+          data-content="965fe321"
+          fill="none"
+          height="17.6580310880829"
+          viewBox="0 0 23.16 17.04"
+          width="24"
+        />
+        <svg
+          class="panelIcon"
+          data-content="35f95b0c"
+          fill="none"
+          height="18"
+          viewBox="0 0 16 16"
+          width="18"
+          xmlns="http://www.w3.org/2000/svg"
+        />
+      </button>
+    </div>
+    <button
+      aria-label="New session"
+      class="newSession"
+      type="button"
+    >
+      <svg
+        data-content="c0ce4dcc"
+        fill="none"
+        height="18"
+        viewBox="0 0 16 16"
+        width="18"
+        xmlns="http://www.w3.org/2000/svg"
+      />
+    </button>
+    <div
+      class="regionArea"
+    />
+    <div
+      class="footArea"
+    />
+  </div>
+</div>
+`;
+
+exports[`sidebar shell snapshots > renders the expanded column (wordmark, capsule, empty holes) 1`] = `
+<div
+  data-slot="sidebar"
+>
+  <div
+    class="root"
+    style="width: 300px;"
+  >
+    <div
+      class="logoRow"
+    >
+      <button
+        aria-label="New session"
+        class="brand wide"
+        type="button"
+      >
+        <svg
+          aria-hidden="true"
+          data-content="951274b9"
+          fill="none"
+          height="24"
+          viewBox="0 0 182 24"
+          width="182"
+        />
+      </button>
+      <button
+        aria-label="Collapse sidebar"
+        class="iconButton toggle"
+        type="button"
+      >
+        <svg
+          class="panelIcon"
+          data-content="35f95b0c"
+          fill="none"
+          height="16"
+          viewBox="0 0 16 16"
+          width="16"
+          xmlns="http://www.w3.org/2000/svg"
+        />
+      </button>
+    </div>
+    <button
+      aria-label="New session"
+      class="newSession"
+      type="button"
+    >
+      <svg
+        data-content="c0ce4dcc"
+        fill="none"
+        height="14"
+        viewBox="0 0 16 16"
+        width="14"
+        xmlns="http://www.w3.org/2000/svg"
+      />
+      <span
+        class="newSessionLabel wide"
+      >
+        New Session
+      </span>
+    </button>
+    <div
+      class="regionArea"
+    />
+    <div
+      class="footArea"
+    />
+  </div>
+</div>
+`;

packages/client/ui-sidebar/tests/sidebar-snapshot.spec.tsx

@@ -0,0 +1,51 @@
+// @vitest-environment jsdom
+/**
+ * Local DOM snapshots of the sidebar shell through the real assembly path:
+ * SlotTestRuntime mounts the package apply on its own fiber, the auto frame
+ * supplies the layout's owner share at the render site, and the snapshot
+ * captures exactly the 'sidebar' slot's output (CSS-module class names
+ * folded to their semantic locals by the runtime's serializer). The child
+ * holes (sidebar.workspaces / sidebar.settings) have no registrant here, so
+ * the snapshots pin the shell chrome itself.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, waitFor } from '@testing-library/react'
+import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
+import { apply, inject } from '@deepseek-ai/dsh-client-ui-sidebar/client'
+
+afterEach(cleanup)
+
+async function bench() {
+  const runtime = await SlotTestRuntime.create()
+  runtime.provide('layout', { toggleSidebar: vi.fn() })
+  await runtime.declare({ 'sidebar': { kind: 'single', scope: 'root' } })
+  await runtime.mount({ inject: [...inject], apply })
+  return runtime
+}
+
+describe('sidebar shell snapshots', () => {
+  it('renders the expanded column (wordmark, capsule, empty holes)', async () => {
+    const runtime = await bench()
+    const slot = runtime.renderSlot('sidebar', { collapsed: false, width: 300 })
+    // Wordmark + capsule both start a session in the expanded state.
+    expect(slot.view.getAllByRole('button', { name: 'New session' })).toHaveLength(2)
+    expect(slot.container).toMatchSnapshot()
+    await runtime.dispose()
+  })
+
+  it('renders the collapsed rail after the crossfade settles, in place', async () => {
+    const runtime = await bench()
+    const slot = runtime.renderSlot('sidebar', { collapsed: false, width: 300 })
+    const shell = slot.container.firstElementChild
+    slot.update({ collapsed: true, width: 56 })
+    // The wide content (wordmark shortcut) unmounts at the 150ms settle;
+    // only the rail's capsule remains a New-session button.
+    await waitFor(() => {
+      expect(slot.view.getAllByRole('button', { name: 'New session' })).toHaveLength(1)
+    })
+    expect(slot.container).toMatchSnapshot()
+    // Same tree position: the owner flip re-rendered the shell in place.
+    expect(slot.container.firstElementChild).toBe(shell)
+    await runtime.dispose()
+  })
+})

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

@@ -24,7 +24,8 @@ export type { SlashServiceContract } from './contract.ts'
 
 declare module 'cordis' {
   interface Context {
-    slash: SlashService
+    /** The outward face only; the concrete service stays inside this plugin. */
+    slash: import('./contract.ts').SlashServiceContract
   }
 }
 

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

@@ -7,7 +7,7 @@
  */
 import { Service } from 'cordis'
 import type { Context } from 'cordis'
-import type { ClientContext, SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ClientContext, ISessions, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SlashSource } from '../types.ts'
 import { SlashController } from './controller.ts'
 import type { SlashServiceContract } from './contract.ts'
@@ -99,7 +99,7 @@ export class SlashService extends Service implements SlashServiceContract {
     return controller
   }
 
-  private sessions(): SessionsService {
+  private sessions(): ISessions {
     const sessions = this.ctx.get('sessions')
     if (sessions === undefined) throw new Error('ui-slash: sessions service unavailable')
     return sessions

packages/client/web/package.json

@@ -31,6 +31,7 @@
   "devDependencies": {
     "@cordisjs/plugin-loader": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@types/react": "~18.3.1",
     "@types/react-dom": "~18.3.0",

packages/client/web/tests/app-shell.spec.tsx

@@ -0,0 +1,61 @@
+// @vitest-environment jsdom
+/**
+ * App-shell assembly plugin on the real machinery: bare Context + production
+ * SlotsService + the test-runtime session/workspace doubles. Deliberately NOT
+ * mounted through SlotTestRuntime — its create() installs the capturing
+ * renderer and install() is boot-once; app-shell IS the production installer,
+ * so this bench hands it the uninstalled service exactly as boot does.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, render } from '@testing-library/react'
+import { Context } from 'cordis'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { TestSessions, TestWorkspaces } from '@deepseek-ai/dsh-client-test-runtime'
+import type { Stabilizer } from '@deepseek-ai/dsh-client-test-runtime'
+import * as AppShell from '@deepseek-ai/dsh-client-web/src/app-shell.ts'
+
+afterEach(cleanup)
+
+const stabilize: Stabilizer = async (fn) => { await act(async () => { await fn() }) }
+
+async function bench() {
+  const ctx = new Context()
+  await ctx.plugin(SlotsService).await()
+  const slots = ctx.get('slots') as SlotsService
+  ctx.provide('sessions', new TestSessions(stabilize, ctx))
+  ctx.provide('workspaces', new TestWorkspaces(stabilize))
+  ctx.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
+  const fiber = ctx.plugin({ inject: [...AppShell.inject], apply: AppShell.apply })
+  await fiber.await()
+  return { ctx, slots, fiber }
+}
+
+describe('app-shell assembly plugin', () => {
+  it('installs the renderer and provides the assembled appShell face', async () => {
+    const { ctx, slots } = await bench()
+    slots.register({ name: 'root' }, () => <div data-testid="root-probe" />)
+    const shell = ctx.get('appShell')
+    expect(shell).toBeDefined()
+    const view = render(<>{shell!.renderApp()}</>)
+    expect(view.getByTestId('root-probe')).toBeTruthy()
+  })
+
+  it('assembles once: repeated renderApp calls reuse the built closure', async () => {
+    const { ctx, slots } = await bench()
+    slots.register({ name: 'root' }, () => <div data-testid="root-probe" />)
+    const shell = ctx.get('appShell')!
+    const first = render(<>{shell.renderApp()}</>)
+    expect(first.getByTestId('root-probe')).toBeTruthy()
+    first.unmount()
+    // Second call rides the cached closure (renderApp ??=) and still renders.
+    const second = render(<>{shell.renderApp()}</>)
+    expect(second.getByTestId('root-probe')).toBeTruthy()
+  })
+
+  it('fiber dispose retracts the service and uninstalls the renderer', async () => {
+    const { ctx, slots, fiber } = await bench()
+    await stabilize(() => fiber.dispose())
+    expect(ctx.get('appShell')).toBeUndefined()
+    expect(() => slots.renderSlot('root', {})).toThrow('not installed')
+  })
+})

packages/client/web/tests/app.spec.tsx

@@ -0,0 +1,65 @@
+// @vitest-environment jsdom
+/**
+ * buildRenderApp on SlotTestRuntime: the fail-loud sessions precondition, the
+ * one ctx-level renderSlot('root') call, and the document-title projection
+ * arms over the real slot stack.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render } from '@testing-library/react'
+import { Context } from 'cordis'
+import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import { buildRenderApp } from '@deepseek-ai/dsh-client-web/src/app.tsx'
+
+let runtime: SlotTestRuntime | undefined
+
+afterEach(async () => {
+  cleanup()
+  await runtime?.dispose()
+  runtime = undefined
+  document.title = ''
+})
+
+async function bench() {
+  runtime = await SlotTestRuntime.create()
+  await runtime.root.declare({}, () => <div data-testid="frame" />)
+  return { runtime, renderApp: buildRenderApp({ ctx: runtime.ctx }) }
+}
+
+describe('buildRenderApp', () => {
+  it('fails loud when the sessions service is unavailable', () => {
+    expect(() => buildRenderApp({ ctx: new Context() })).toThrow('sessions service unavailable')
+  })
+
+  it('renders the root slot tree through the one ctx-level renderSlot call', async () => {
+    const b = await bench()
+    const view = render(<>{b.renderApp()}</>)
+    expect(view.getByTestId('frame')).toBeTruthy()
+  })
+
+  it('projects the current session durable title and falls back to the product title', async () => {
+    document.title = 'Product'
+    const b = await bench()
+    render(<>{b.renderApp()}</>)
+    // No current session: the product title stands.
+    expect(document.title).toBe('Product')
+    await b.runtime.sessions.add({ id: 's1', summary: { title: 'First' } })
+    expect(document.title).toBe('First — Product')
+    await b.runtime.sessions.setCurrent(undefined)
+    expect(document.title).toBe('Product')
+    // A session without a durable title keeps the product title.
+    await b.runtime.sessions.add({ id: 's2' })
+    expect(document.title).toBe('Product')
+  })
+
+  it('a current id without a list row falls back (selection/list arbitration transient)', async () => {
+    document.title = 'Product'
+    const b = await bench()
+    await b.runtime.sessions.add({ id: 's1', summary: { title: 'First' } })
+    render(<>{b.renderApp()}</>)
+    expect(document.title).toBe('First — Product')
+    b.runtime.sessions.list.update((draft) => { draft.current = 'ghost' as SessionId })
+    await b.runtime.flush()
+    expect(document.title).toBe('Product')
+  })
+})

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -526,11 +526,15 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>',
-        jsDoc: '/**\n * Load a header and balanced contiguous log. A complete interrupted final\n * turn is preserved and durably closed with missing tool errors plus any open\n * step and turn boundaries; only a torn final record is discarded. Unknown\n * versions and corruption in the committed prefix reject. Implementations\n * MUST NOT crash-repair an identity still bound to a live Session: a balanced\n * live log may return with its stored header as a durable snapshot, while an\n * open live turn rejects.\n * A coordinator-backed cold load reserves the identity across storage awaits,\n * so concurrent publication of a same-id live Session rejects.\n * Returned events are detached, and every identified message is deeply\n * frozen; malformed identified messages reject before any stored event is returned.\n * @param id - the persisted session to reload.\n * @returns the header and a log ending on a balanced `turn/end`.\n */',
+        jsDoc: '/**\n * Load a header and balanced contiguous log. A complete interrupted final\n * turn is preserved and durably closed with missing tool errors plus any open\n * step and turn boundaries; only a torn final record is discarded. Unknown\n * versions and corruption in the committed prefix reject. Implementations\n * MUST NOT crash-repair an identity still bound to a live Session: a balanced\n * live log may return with its stored header as a durable snapshot, while an\n * open live turn rejects.\n * A coordinator-backed cold load reserves the identity across storage awaits,\n * so concurrent publication of a same-id live Session rejects.\n * Returned events are detached, and every identified message is deeply\n * frozen. Coordinator-backed implementations upgrade supported pre-identity\n * message events before validation; other malformed messages reject before\n * any stored event is returned.\n * @param id - the persisted session to reload.\n * @returns the header and a log ending on a balanced `turn/end`.\n */',
       },
       {
         signature: 'abstract inspect(id: SessionId, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }>',
-        jsDoc: '/**\n * Inspect a header and its valid contiguous stored prefix without repairing\n * a torn tail, closing an interrupted turn, or publishing coordinator state.\n * This read is serialized with writes for the same id and returns detached\n * values with deeply frozen identified messages, so observers cannot mutate message\n * identity/content or backend-owned state. Malformed identified messages reject.\n * @param id - the persisted session to inspect.\n * @param signal - optional cancellation for queued and backend read work.\n * @returns the header and valid stored event prefix exactly as observed.\n */',
+        jsDoc: '/**\n * Inspect a header and its valid contiguous stored prefix without repairing\n * a torn tail, closing an interrupted turn, or publishing coordinator state.\n * This read is serialized with writes for the same id and returns detached\n * values with upgraded, deeply frozen identified messages, so observers\n * cannot mutate message identity/content or backend-owned state. Other\n * malformed messages reject.\n * @param id - the persisted session to inspect.\n * @param signal - optional cancellation for queued and backend read work.\n * @returns the header and valid stored event prefix exactly as observed.\n */',
+      },
+      {
+        signature: 'abstract readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }>',
+        jsDoc: '/**\n * Read the stored events from `fromSeq` onward — the read-from-seq\n * primitive for read models that resume from a watermark (e.g. a persisted\n * projection cache folding only the tail past its checkpoint). Like\n * {@link inspect} it is non-mutating and detached: no torn-tail truncation,\n * no synthetic closers, no coordinator-state publication; only events from\n * the valid contiguous stored prefix are returned, so a torn fragment never\n * reaches the caller. `fromSeq` at or beyond the stored prefix returns an\n * empty event list (never an error). Backends whose medium can seek by seq\n * (SQLite) read only the suffix; sequential media (JSONL, both encodings)\n * still parse the whole artifact and skip forward — the primitive bounds\n * what is RETURNED and refolded, not every backend\'s physical read.\n * @param id - the persisted session to read.\n * @param fromSeq - first event seq to include; a non-negative safe integer.\n * @param signal - optional cancellation for queued and backend read work.\n * @returns the header and the stored events with `seq >= fromSeq`.\n */',
       },
       {
         signature: 'abstract list(signal?: AbortSignal): Promise<SessionHeader[]>',
@@ -542,6 +546,24 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
     ],
   },
+  {
+    key: 'sessionProjectionCache',
+    summary: 'The persisted projection cache service.',
+    methods: [
+      {
+        signature: 'cachedSnapshot(meta: SessionHeader): ProjectionSnapshot | undefined',
+        jsDoc: '/**\n * The zero-I/O listing read: whole values viewed straight from the stored\n * rows (version-matching keys only), each cut carried with its watermark\n * so a client value store can seed under its higher-seq-wins rule — as\n * stale as the last durable checkpoint but never wrong, and never from an\n * unrelated log (the caller\'s header is the identity witness). Fresher\n * paths (the history tail baseline, {@link coldSnapshot}) supersede these\n * values whenever a session is actually opened.\n * @param meta - the listed session\'s header (identity witness; no log read).\n * @returns the cut (`asOfSeq` = lowest served-row watermark), or\n *   `undefined` when no usable row exists for this lifecycle.\n */',
+      },
+      {
+        signature: 'async write(session: Session): Promise<void>',
+        jsDoc: '/**\n * Durably checkpoint one live session NOW (both mandatory points call\n * this; tests and carriers may too). The registry cut is snapshotted at\n * this boundary (states are live references), then the whole record is\n * replaced. NOT fail-soft — callers on the fail-soft paths contain it.\n * @param session - the live session to checkpoint.\n * @returns resolution after durability and event emission.\n */',
+      },
+      {
+        signature: 'async coldSnapshot(id: SessionId, signal?: AbortSignal): Promise<ProjectionSnapshot>',
+        jsDoc: '/**\n * Cold-read one persisted session\'s projections with zero full-log load:\n * cached rows + a persistence `readFrom` tail from the registry\'s restore\n * floor, refolded by the registry and written back (fail-soft) so the next\n * cold read starts closer. A cache row invalidated by a shrunk log\n * (crash-repair truncation) triggers one full re-read from seq 0 — the\n * ladder\'s slow rung, still no crash. Rejects when the session has no\n * persisted log (`not found` from the persistence seam).\n * @param id - the persisted session to read.\n * @param signal - optional cancellation for the persistence reads.\n * @returns the snapshot cut at the stored log end.\n */',
+      },
+    ],
+  },
   {
     key: 'sessionProjections',
     summary: '`ctx.sessionProjections`: the projection unit table and its drive.',
@@ -558,6 +580,22 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'snapshot(session: Session): ProjectionSnapshot',
         jsDoc: '/**\n * One consistent cut over every registered unit for one session, read from\n * the watermark cache (missing cells fold lazily over the in-memory log).\n * Fully synchronous — every value and `asOfSeq` reflect the same log\n * position. Each value passes its unit\'s schema before leaving.\n * @param session - the session whose projection values are read.\n * @returns the snapshot; `values` is empty when no unit is registered.\n */',
       },
+      {
+        signature: 'checkpoint(session: Session): ProjectionCheckpoint',
+        jsDoc: '/**\n * State-level checkpoint of every registered unit for one session, read\n * from the watermark cache (missing cells fold lazily over the in-memory\n * log). This is the write side of the persisted projection cache: the\n * returned rows are the `(key → {ver, seq, val})` part of the durable\n * `(sessionId, key, ver, seq, val)`\n * rows. Every `val` is a DETACHED structured clone — never the live\n * cell reference: the watermark cache is this registry\'s authoritative\n * mutable state, and a caller reaching the live reference could corrupt\n * every subsequent snapshot and frame through it (plain JSON by the unit\n * contract, so the clone is total).\n * @param session - the session whose unit states are checkpointed.\n * @returns one row per registered key; empty when no unit is registered.\n */',
+      },
+      {
+        signature: 'restoreFloor(checkpoint: ProjectionCheckpoint): number | undefined',
+        jsDoc: '/**\n * The stored seq a {@link restore} tail read over `checkpoint` must start\n * at: one event BELOW the lowest usable watermark (a row is usable when\n * its `ver` matches the live unit\'s `stateVersion`; an absent or mismatched row\n * pulls the floor to `0` — that key must refold the full log). The\n * one-below anchor is load-bearing: the tail then proves how far the\n * stored log still extends, so {@link restore} can detect a log that\n * shrank below a row\'s watermark (crash-repair truncation) instead of\n * serving the stale row as current — an empty tail read from the anchor\n * yields an end below every watermark and the restore rejects for a full\n * re-read.\n * @param checkpoint - persisted rows for one session (possibly stale or empty).\n * @returns the seq to hand the persistence `readFrom`, or `undefined`\n *   when no unit is registered (no read needed — {@link restore} would\n *   serve empty values regardless).\n */',
+      },
+      {
+        signature: 'viewCheckpoint(checkpoint: ProjectionCheckpoint): Partial<SessionProjectionMap>',
+        jsDoc: '/**\n * View a checkpoint\'s rows without any log read: for every registered\n * unit whose row\'s `ver` matches, serve the schema-validated\n * `view` of the stored state; mismatched or absent rows leave their key\n * absent (a cold or listing consumer treats it as not-yet-available and a\n * fuller read path refolds it). The zero-I/O rung of the read ladder —\n * values are as stale as their rows, never wrong.\n * @param checkpoint - persisted rows for one session (possibly stale or empty).\n * @returns whole values per key with a usable row; empty when none.\n */',
+      },
+      {
+        signature: 'restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }',
+        jsDoc: '/**\n * Cold read: fold every registered unit over a stored log suffix, seeding\n * each from its checkpoint row when usable — the one read recipe (cached\n * state + forward tail replay + `view`) applied without a live `Session`.\n * Call with the events returned by a persistence\n * `readFrom(id, restoreFloor(checkpoint))` and that same floor as\n * `baseSeq`; the floor\'s one-below anchor makes the supplied end honest,\n * so a shrunk log is detected here. A row is usable iff its\n * `ver` matches the live unit\'s `stateVersion`, it does not predate `baseSeq`\n * (`seq >= baseSeq - 1`), and it does not claim events past the\n * supplied end (`seq <= endSeq`); an unusable row is discarded\n * and its key refolds from `init` — which is only sound over the full\n * log, so a discarded row with `baseSeq > 0` throws (the caller re-reads\n * from seq 0, e.g. after a crash-repair truncation shrank the log below\n * a row\'s watermark).\n * @param checkpoint - persisted rows for one session (possibly stale or empty).\n * @param events - the stored events with `seq >= baseSeq`, in seq order.\n * @param baseSeq - the seq `events` starts at (its first event\'s seq when non-empty).\n * @returns the snapshot cut at the supplied log end (`asOfSeq` is the last\n *   supplied event\'s seq, `baseSeq - 1` for an empty tail) plus the\n *   refreshed checkpoint rows at that cut, ready for a durable write-back.\n */',
+      },
     ],
   },
   {
@@ -1863,6 +1901,14 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'ProjectionChangeListener',
     declaration: 'export type ProjectionChangeListener = (session: Session, key: Extract<keyof SessionProjectionMap, string>, value: unknown, seq: number) => void;',
   },
+  {
+    name: 'ProjectionCheckpoint',
+    declaration: 'export type ProjectionCheckpoint = Record<string, ProjectionCheckpointRow>;',
+  },
+  {
+    name: 'ProjectionCheckpointRow',
+    declaration: 'export interface ProjectionCheckpointRow {\n    ver: number;\n    seq: number;\n    val: unknown;\n}',
+  },
   {
     name: 'ProjectionDefinition',
     declaration: 'export interface ProjectionDefinition<K extends keyof SessionProjectionMap, S> {\n    key: K;\n    schema: ZodType<SessionProjectionMap[K]>;\n    init(): S;\n    apply(state: S, event: SessionEvent): S;\n    view(state: S): SessionProjectionMap[K];\n    stateVersion: number;\n}',

packages/core/agent-loop/tests/resume.spec.ts

@@ -5,7 +5,7 @@ import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import LlmService from '@deepseek-ai/dsh-llm'
-import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SESSION_FORMAT_VERSION, Session, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
@@ -77,6 +77,65 @@ function throwUnknown(value: unknown): never {
 }
 
 describe('the session-persistence Agent Note: AgentLoop factory create/resume', () => {
+  it('resumes a session persisted before messages gained identities', async () => {
+    const sessionId = SessionId('pre-identity-resume')
+    const first = await persistentHarness(new MockAdapter([]))
+    await first.ctx.sessionPersistence.create({
+      version: SESSION_FORMAT_VERSION,
+      id: sessionId,
+      createdAt: 1,
+    })
+    await first.ctx.sessionPersistence.append(sessionId, [
+      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+      {
+        type: 'user/message',
+        seq: 1,
+        time: 2,
+        data: { content: [{ type: 'text', text: 'old question' }], source: { kind: 'user' } },
+        surfaceOp: 'append',
+      },
+      { type: 'step/start', seq: 2, time: 3, data: { turn: 1, step: 1 } },
+      {
+        type: 'assistant/message',
+        seq: 3,
+        time: 4,
+        data: {
+          turn: 1,
+          step: 1,
+          content: [{ type: 'text', text: 'old answer' }],
+          provenance: { provider: 'mock', model: 'mock' },
+        },
+        surfaceOp: 'append',
+      },
+      { type: 'step/end', seq: 4, time: 5, data: { turn: 1, step: 1 } },
+      { type: 'turn/end', seq: 5, time: 6, data: { turn: 1, reason: { kind: 'completed' } } },
+    ] as unknown as SessionEvent[])
+    await first.ctx.fiber.dispose()
+
+    const ctx = await mountPersistentHarness(first.root, new MockAdapter([textResponse('new answer')]))
+    const handle = await ctx.agents.resume({
+      resumeSessionId: sessionId,
+      agentOptions: { provider: 'mock', model: 'mock' },
+    })
+    expect(handle.agent.session.deriveMessages()).toMatchObject([
+      { id: `legacy-message:${sessionId}:1`, role: 'user' },
+      { id: `legacy-message:${sessionId}:3`, role: 'assistant' },
+    ])
+
+    handle.agent.followup(createUserMessage({
+      content: [{ type: 'text', text: 'new question' }],
+      source: { kind: 'user' },
+    }))
+    await waitForIdle(ctx, handle.agent)
+    expect(handle.agent.session.deriveMessages()).toHaveLength(4)
+    expect(handle.agent.session.events.at(-1)).toMatchObject({
+      type: 'turn/end',
+      data: { reason: { kind: 'completed' } },
+    })
+    await handle.dispose()
+    await ctx.fiber.dispose()
+  })
+
   it('normalizes a non-Error resume publication failure for rollback and rethrows it', async () => {
     const sessionId = SessionId('unknown-resume-failure-s')
     const root = await persistSession(sessionId)

packages/core/session/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/session/README.md
-README.md: 40516d12180de9c30efd40fdffa873da20ddacb3
-README.zh.md: 43842643a3434c741f219f7b6c26622cddfae8e7
+README.md: a9b6905dcf2b8ef1f75595e567273f7a3150a412
+README.zh.md: f1a5e97e32d1ad1abcd6ad96e6c621af9972e989

packages/core/session/README.md

@@ -142,5 +142,5 @@ Logging causes no invalidation, and exact reconstruction preserves request-prefi
 
 - **Session branching/tree** (pi-style entry tree) — deferred unless needed beyond boundary-based `fork()`.
 - **`fork()` cuts only at stable boundaries of live sessions** — the selected prefix must end outside an open turn and the source must be in the store; forking a persisted-but-unloaded session is excluded from the [fork API](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md).
-- **`SESSION_FORMAT_VERSION` stays pinned at `0`** — pre-release, no compatibility implied: a backend rejects any other version, and no migration path exists until the first release ([policy](../../../AGENTS.md)).
+- **`SESSION_FORMAT_VERSION` stays pinned at `0`** — pre-release, no broad compatibility implied: `Session` accepts only current seed shapes and a backend rejects any other version. Narrow storage import upgrades belong to the persistence boundary ([policy](../../../AGENTS.md), [pre-identity message recovery](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md)).
 - **`TurnEndReasonMap` omits the ACP-named `refusal` / `max_turn_requests` variants** — producer-gated: they land when an adapter or the loop first emits them.

packages/core/session/README.zh.md

@@ -142,5 +142,5 @@
 
 - **会话分支／树**（pi 风格条目树）：除非需要超越基于边界的 `fork()` 能力，否则暂缓。
 - **`fork()` 仅在实时会话的稳定边界处切分**：所选前缀结束时不得有开放轮次，且源会话必须位于存储中；[fork API](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md) 不支持对已持久化但未加载的会话进行 fork。
-- **`SESSION_FORMAT_VERSION` 固定为 `0`**：预发布阶段不承诺兼容性；后端会拒绝其他任何版本，首次发布前不提供迁移路径（[政策](../../../AGENTS.md)）。
+- **`SESSION_FORMAT_VERSION` 固定为 `0`**：预发布阶段不承诺广泛兼容性；`Session` 只接受当前 seed 形状，后端会拒绝其他任何版本。范围受限的存储导入升级应由持久化边界负责（[政策](../../../AGENTS.md)、[消息标识机制引入前的消息恢复](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md)）。
 - **`TurnEndReasonMap` 不含 ACP（Agent Client Protocol）命名的 `refusal`／`max_turn_requests` 变体**：受生产方约束；只有当适配器或循环首次产生这些变体时才加入。

packages/host/apiproxy/package.json

@@ -47,6 +47,7 @@
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-persistence": "workspace:^",
     "@deepseek-ai/dsh-session-projection": "workspace:^",
+    "@deepseek-ai/dsh-session-projection-cache": "workspace:^",
     "@deepseek-ai/dsh-skill": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/dsh-user-approval": "workspace:^",

packages/host/apiproxy/src/api-proxy.ts

@@ -30,6 +30,8 @@ import type {
 } from './api/index.ts'
 // Type-only: resolves `ctx.get('sessionProjections')` to the projection registry.
 import type {} from '@deepseek-ai/dsh-session-projection'
+// Type-only: resolves `ctx.get('sessionProjectionCache')` (the cold listing column).
+import type {} from '@deepseek-ai/dsh-session-projection-cache'
 // Type-only edges: resolve `ctx.get('commands')`, the `commands/change` event, and `ctx.get('skills')`.
 import type {} from '@deepseek-ai/dsh-commands'
 import type {} from '@deepseek-ai/dsh-skill'
@@ -297,6 +299,28 @@ function projectionsFor(ctx: Context, agent: Agent): SessionProjectionsBlock | u
   return registry.snapshot(agent.session)
 }
 
+/**
+ * The projection baseline of one session.list row, fail-soft: attached
+ * sessions cut the registry's live watermark cache; cold sessions view the
+ * persisted projection cache's identity-checked stored rows (zero log loads
+ * either way — the listing use case the cache exists for). The block shape
+ * (values + asOfSeq) matches the history tail's, so a client seeds its
+ * value store under the same higher-seq-wins rule. Any failure — and an
+ * empty value set — yields an absent block: a listing without projections
+ * is degraded, never broken.
+ */
+function listProjectionsFor(ctx: Context, meta: SessionHeader, session: Session | undefined): SessionProjectionsBlock | undefined {
+  try {
+    const block = session !== undefined
+      ? ctx.get('sessionProjections')?.snapshot(session)
+      : ctx.get('sessionProjectionCache')?.cachedSnapshot(meta)
+    return block !== undefined && Object.keys(block.values).length > 0 ? block : undefined
+  } catch (error) {
+    ctx.logger.warn(`session.list: projection column for "${meta.id}" failed (serving the row without it): ${String(error)}`)
+    return undefined
+  }
+}
+
 /**
  * Thrown by the cold-resume path when the id names no servable session
  * (absent from the store, or a pre-project legacy log without a cwd).
@@ -654,13 +678,25 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
       async list(request) {
         const items = ctx.sessions.list().map((session) => {
           const agent = ctx.agents.get(session.id)
-          return summarize(session, agent?.status === 'running')
+          const projections = listProjectionsFor(ctx, session.header, session)
+          return {
+            ...summarize(session, agent?.status === 'running'),
+            ...projections === undefined ? {} : { projections },
+          }
         })
         const attached = new Set(items.map(item => item.sessionId))
         const persistence = ctx.get('sessionPersistence')
         if (persistence !== undefined) {
           const cold = (await persistence.list()).filter(meta => !attached.has(meta.id) && meta.cwd !== undefined)
-          items.push(...await Promise.all(cold.map(meta => summarizeCold(persistence, meta))))
+          items.push(...await Promise.all(cold.map(async (meta) => {
+            // Cold rows read the persisted projection cache only — never a
+            // log load; a session without a cache row simply has no column.
+            const projections = listProjectionsFor(ctx, meta, undefined)
+            return {
+              ...await summarizeCold(persistence, meta),
+              ...projections === undefined ? {} : { projections },
+            }
+          })))
         }
         items.sort((a, b) => b.updatedAt - a.updatedAt)
         return ok(request, { items })

packages/host/apiproxy/src/api/sessions.schema.ts

@@ -37,7 +37,7 @@ export const sessionEventSchema = z.object({
   surfaceOp: z.unknown().optional(),
 }) as unknown as z.ZodType<SessionEvent>
 
-/** SessionSummary row of session.list. */
+/** SessionSummary row of session.list (`projections` reuses the history block's shape and schema). */
 export const sessionSummarySchema = z.object({
   sessionId: sessionIdSchema,
   updatedAt: z.number(),
@@ -45,7 +45,8 @@ export const sessionSummarySchema = z.object({
   blank: z.boolean(),
   parentSessionId: sessionIdSchema.optional(),
   cwd: z.string().optional(),
-}) satisfies z.ZodType<Wire<SessionSummary>>
+  projections: z.lazy(() => sessionProjectionsBlockSchema).optional(),
+}) as unknown as z.ZodType<Wire<SessionSummary>>
 
 /** session.list request payload (cursor is a reserved seat, unimplemented in v1). */
 export const sessionListRequestSchema = z.object({
@@ -53,9 +54,9 @@ export const sessionListRequestSchema = z.object({
 }) satisfies z.ZodType<Wire<RequestPayload<'session.list'>>>
 
 /** session.list response value. */
-export const sessionListValueSchema = z.object({
+export const sessionListValueSchema: z.ZodType<Wire<ResponseValue<'session.list'>>> = z.object({
   items: z.array(sessionSummarySchema),
-}) satisfies z.ZodType<Wire<ResponseValue<'session.list'>>>
+})
 
 /** session.create request payload (at most one of workspaceId / cwd). */
 export const sessionCreateRequestSchema = z.object({

packages/host/apiproxy/src/api/sessions.ts

@@ -143,6 +143,18 @@ export interface SessionSummary {
   parentSessionId?: SessionId
   /** Session working directory (header.cwd passthrough); absent when unrecorded. */
   cwd?: string
+  /**
+   * Projection baseline for this row, with zero log loads: attached sessions
+   * read the registry's live watermark cut; cold sessions read the persisted
+   * projection cache's stored rows — as stale as that session's last durable
+   * checkpoint (`asOfSeq` says exactly how stale), never wrong, and directly
+   * seedable into the client's per-session value store under its
+   * higher-seq-wins rule (a list baseline can never overwrite a newer push
+   * frame). Absent when no value is available (no registry, no cache row for
+   * a cold session, or a fail-soft cache read miss); a listing client treats
+   * absence as "no title yet", exactly like a blank session.
+   */
+  projections?: SessionProjectionsBlock
 }
 
 /** Session-domain unary methods (the map keys session.* of RpcMethodMap). */

packages/host/apiproxy/tests/api-proxy-projections.spec.ts

@@ -13,7 +13,7 @@ import { z } from 'zod'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import SessionStore from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import type { Session } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
@@ -125,6 +125,82 @@ describe('session.history projections block', () => {
   })
 })
 
+describe('session.list projections column', () => {
+  it('serves attached rows from the live registry cut, watermarked for client seeding', async () => {
+    const { ctx, session } = await harness(true)
+    ctx.sessionProjections.register(lastUserUnit())
+    seedMessages(session, 1)
+    const response = await api(ctx).sessions.list(request({}))
+    if (!response.result.ok) throw new Error('unreachable')
+    const row = response.result.value.items.find(item => item.sessionId === session.id)
+    expect(row?.projections?.values['test/last-user']).toEqual({ text: 'm0' })
+    expect(row?.projections?.asOfSeq).toBe(session.seq - 1)
+  })
+
+  it('omits the column entirely when no registry is mounted', async () => {
+    const { ctx, session } = await harness(false)
+    seedMessages(session, 1)
+    const response = await api(ctx).sessions.list(request({}))
+    if (!response.result.ok) throw new Error('unreachable')
+    const row = response.result.value.items.find(item => item.sessionId === session.id)
+    expect(row).toBeDefined()
+    expect(row !== undefined && 'projections' in row).toBe(false)
+  })
+
+  it('serves cold rows from the persisted projection cache with zero log loads', async () => {
+    const { ctx } = await harness(true)
+    const coldId = SessionId('session-cold-listing')
+    const load = () => { throw new Error('list must not load event logs') }
+    ctx.provide('sessionPersistence', {
+      list: async () => [{ version: 0, id: coldId, createdAt: 5, cwd: '/tmp' }],
+      locate: () => undefined,
+      load,
+      inspect: load,
+      readFrom: load,
+    } as never)
+    ctx.provide('sessionProjectionCache', {
+      // The carrier hands the listed header through as the identity witness.
+      cachedSnapshot: (meta: { id: unknown; createdAt: number }) =>
+        (meta.id === coldId && meta.createdAt === 5
+          ? { asOfSeq: 7, values: { 'test/last-user': { text: 'cached' } } }
+          : undefined),
+    } as never)
+    const response = await api(ctx).sessions.list(request({}))
+    if (!response.result.ok) throw new Error('unreachable')
+    const row = response.result.value.items.find(item => item.sessionId === coldId)
+    expect(row?.running).toBe(false)
+    expect(row?.projections).toEqual({ asOfSeq: 7, values: { 'test/last-user': { text: 'cached' } } })
+  })
+
+  it('cold rows without a cache plugin (or without a stored row) just lack the column', async () => {
+    const { ctx } = await harness(true)
+    const coldId = SessionId('session-cold-uncached')
+    ctx.provide('sessionPersistence', {
+      list: async () => [{ version: 0, id: coldId, createdAt: 5, cwd: '/tmp' }],
+      locate: () => undefined,
+    } as never)
+    const response = await api(ctx).sessions.list(request({}))
+    if (!response.result.ok) throw new Error('unreachable')
+    const row = response.result.value.items.find(item => item.sessionId === coldId)
+    expect(row).toBeDefined()
+    expect(row !== undefined && 'projections' in row).toBe(false)
+  })
+
+  it('a throwing column read degrades that row, never the listing', async () => {
+    const { ctx, session } = await harness(true)
+    ctx.sessionProjections.register({
+      ...lastUserUnit(),
+      view: () => { throw new Error('unit exploded') },
+    })
+    seedMessages(session, 1)
+    const response = await api(ctx).sessions.list(request({}))
+    if (!response.result.ok) throw new Error('unreachable')
+    const row = response.result.value.items.find(item => item.sessionId === session.id)
+    expect(row).toBeDefined()
+    expect(row !== undefined && 'projections' in row).toBe(false)
+  })
+})
+
 describe('session/projection push frame', () => {
   /** Drain frames until `count` session/projection frames arrived. */
   async function collect(iterable: AsyncIterable<RpcRequest<MuxFrame>>, count: number, abort: AbortController): Promise<MuxFrame[]> {