refactor(cli)!: one shared base config with per-surface overlays

`dsh` shipped two config trees that were 43 rows the same: apps/cli/cordis.yml composed web as 74 flat rows, while the TUI booted examples/tui-agent/cordis.yml whose single `@deepseek-ai/dsh-tui-demo` row mounted twelve plugins behind a twenty-key pass-through Config. Neither file was what its location claimed — apps/cli hardcoded the "example" as the product default and the "demo" bundle was the application — and every capability change had to be made twice. - apps/cli/base.cordis.yml holds the 43 shared rows; tui.cordis.yml and web.cordis.yml are patch lists stating only what differs per surface - overlays apply as SIBLING patch lists at one include level, because include patches never cross an include boundary. Precedence: base < surface < (--config | personal ~/.dsh/config.yaml) < launcher flag/profile patches - `--config` now applies an overlay INSTEAD OF the personal one, so a demo or test tree never inherits the user's route; new `--config-replace` boots a file as the entire tree (the old `--config` behaviour). Both survive /resume - vendor/include: index each `insert`ed row as it is added so a later patch can configure or disable it. Upstream built the id index once before the patch loop, leaving every surface-only row — the whole TUI front door — silently unpatchable from user config. Logged as local modification 8 - session identity moves to dsh-agent-loop's CONFIGURED_AGENT_IDENTITIES_KEY; dsh-tui's MAIN_SESSION_ID_KEY is deleted (only the bundle read it) - delete examples/tui-agent, examples/cordis-agent, packages/examples/tui-demo; TUI tests → apps/cli/tests, cordis e2e → packages/cordis/tool-cordis/tests, examples/code-mode survives as an overlay leaf - `dsh web` gains --config, threaded into AppCLIEntry as an extra overlay Three latent defects surfaced and are fixed here: the TUI captured the optional sessionQuery service once at construction and could permanently disable /resume when it won the mount race; the session-store root silently reverted to a project-local ./.sessions; --config-replace was dropped by the resume handoff. Verified by booting each tree through the real Loader (TUI 55 entries, web 75, zero unsettled) rather than reading YAML. All eight terminal snapshots replay byte-identically; 14/14 PTY smoke, 112/112 snapshots, 25/25 doc-sync, hygiene and lint clean.
2026-08-29 04:26:38 +00:00 · 2026-07-29 21:15:42 +08:00
parent e7c0a5b794
commit f290a8b851
182 changed files with 1659 additions and 2400 deletions
@@ -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-23-client-plugin-loading-model.md: 4028f50bf5cf8a05063df3bf5e2b4b7f45a3c02e
-2026-07-23-client-plugin-loading-model.zh.md: 7dc96b47c950af07adb71ba7fe131d53e5c0e51d
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
+2026-07-23-client-plugin-loading-model.md: ef9f14f2a150b0845ff89939bce5f8863dc15707
+2026-07-23-client-plugin-loading-model.zh.md: 0fbcbb0717be9d5aac27c33d9482c7e13bf7f4ea
@@ -116,7 +116,7 @@ One governance implementation runs on both sides of the wire; the browser-specif

 Costs accepted: the vendored Loader carries idle machinery in the browser (EntryTree persistence is a no-op, groups/isolation unused); every plugin edit in dev pays a bundle rebuild plus fiber remount; graph `inject` rows are informational — activation truth is service-level — so a mismatch surfaces at the settled sweep, not at graph validation; and the three not-yet-promoted libraries keep their static-import export surface until their DI conversions land.

-Roster endgame (landed 2026-07-25 with the config-tree boot move): the roster lives in `apps/cli/cordis.yml`, `mountWebPlugins` and the `CLIENT_PACKAGES` constant are gone, and recomposing a deployment means swapping the yml/overlay. The graph composer moved from a webserver-side registry into the `dsh-client-modules` node half (the package upgraded to dual-face per this note's promotion rule — its consumer now reaches it through cordis DI), and the transport split landed alongside: the webserver became a plain route-registration plugin, `/api/*` binding moved to the connection node half over the upgraded `api-gateway` plugin (`dsh-host-apiproxy` providing `ctx.apiProxy`), and the dev bundle watch + SSE channel moved to the hmr node half.
+Roster endgame (landed 2026-07-25 with the config-tree boot move): the roster lives in `apps/cli/web.cordis.yml`, `mountWebPlugins` and the `CLIENT_PACKAGES` constant are gone, and recomposing a deployment means swapping the yml/overlay. The graph composer moved from a webserver-side registry into the `dsh-client-modules` node half (the package upgraded to dual-face per this note's promotion rule — its consumer now reaches it through cordis DI), and the transport split landed alongside: the webserver became a plain route-registration plugin, `/api/*` binding moved to the connection node half over the upgraded `api-gateway` plugin (`dsh-host-apiproxy` providing `ctx.apiProxy`), and the dev bundle watch + SSE channel moved to the hmr node half.

 ## Alternatives considered

@@ -116,7 +116,7 @@ wire 两侧跑着同一份治理实现；浏览器特有的表面只是一套模

 接受的代价：vendored Loader 在浏览器里背着闲置机件（EntryTree 持久化是 no-op，分组/隔离未用）；开发期每次修改插件都要付一次 bundle 重建加 fiber 重挂；图中 `inject` 行仅是信息性说明——激活的真相在服务层——因此不匹配会在 settled 扫描时浮出，而不是在图校验时被拦下；三个尚未升格的库在各自的 DI 转换落地之前保持静态 import 的导出面。

-名册的终局（2026-07-25 随配置树 boot 迁移落地）：名册住 `apps/cli/cordis.yml`，`mountWebPlugins` 与 `CLIENT_PACKAGES` 常量已消失，重组一次部署等于换 yml/overlay。图的组合器从 webserver 侧的注册表迁进 `dsh-client-modules` 的 node 半（该包按本 note 的升级法则升格为双面——其消费方现经 cordis DI 到达），传输拆分同轮落地：webserver 变为朴素路由注册插件，`/api/*` 绑定迁到 connection 的 node 半、走升格后的 `api-gateway` 插件（`dsh-host-apiproxy` 提供 `ctx.apiProxy`），dev 的 bundle 监视与 SSE 通道迁到 hmr 的 node 半。
+名册的终局（2026-07-25 随配置树 boot 迁移落地）：名册住 `apps/cli/base.cordis.yml` plus its surface overlay，`mountWebPlugins` 与 `CLIENT_PACKAGES` 常量已消失，重组一次部署等于换 yml/overlay。图的组合器从 webserver 侧的注册表迁进 `dsh-client-modules` 的 node 半（该包按本 note 的升级法则升格为双面——其消费方现经 cordis DI 到达），传输拆分同轮落地：webserver 变为朴素路由注册插件，`/api/*` 绑定迁到 connection 的 node 半、走升格后的 `api-gateway` 插件（`dsh-host-apiproxy` 提供 `ctx.apiProxy`），dev 的 bundle 监视与 SSE 通道迁到 hmr 的 node 半。

 ## Alternatives considered

@@ -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-24-web-config-tree-boot-and-transport-layering.md: 99e5d0d95f320464a6f12857e9d6e90e3587c777
-2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: 89c1a578f0ad0841eea7512538e3de8095b82c4d
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
+2026-07-24-web-config-tree-boot-and-transport-layering.md: bf1dd829af73e61f2545c1f9034bc7ffda7042ed
+2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: 03c1b64f3a9a17cb0f607764ea2c1a52b77551a3
@@ -12,7 +12,7 @@ English | [中文](2026-07-24-web-config-tree-boot-and-transport-layering.zh.md)

 ## Decision

-**Composition is one flat config tree.** `apps/cli/cordis.yml` holds every row — the host runtime (32 rows), the `api-gateway` row, the `webserver` row, and the `dshClient` rows (the browser roster; the modules row is simultaneously a host row). No spine bundle: every plugin is one row and every config field is yml-editable. `--dev` appends the `dsh-client-hmr` row in code before the settle sweep — prod and dev differ by exactly that row. Row order carries no load semantics; activation is service-availability driven, and the boot compensates with a fail-loud triple: `assertEntriesLoaded` (import failures), `installFailLoud` (late apply rejections), and an all-ACTIVE sweep (PENDING fibers — cordis inject waiting has no timeout).
+**Composition is one flat config tree.** `apps/cli/base.cordis.yml` plus its surface overlay holds every row — the host runtime (32 rows), the `api-gateway` row, the `webserver` row, and the `dshClient` rows (the browser roster; the modules row is simultaneously a host row). No spine bundle: every plugin is one row and every config field is yml-editable. That stance later became repository-wide, with the rows both surfaces share factored into `apps/cli/base.cordis.yml` and each surface reduced to an overlay ([shared-base overlays](../simplification/2026-07-29-shared-base-config-overlays.md)). `--dev` appends the `dsh-client-hmr` row in code before the settle sweep — prod and dev differ by exactly that row. Row order carries no load semantics; activation is service-availability driven, and the boot compensates with a fail-loud triple: `assertEntriesLoaded` (import failures), `installFailLoud` (late apply rejections), and an all-ACTIVE sweep (PENDING fibers — cordis inject waiting has no timeout).

 **Boot glue is a class pair.** `AppCLIEntry` (apps/cli) and `AppWebEntry` (the shell kernel) hold only what must exist independently of cordis: argv facts, the composed patch set, the parsed boot manifest, the module system instance, loading-page handles — everything else lives in plugins. `AppCLIEntry.run()` is three stages: layered env (ambient > cwd `.env` > `$DSH_HOME/.env`, closing the defect above) → patch composition → Loader include boot plus the triple. `AppWebEntry.run()` mirrors it browser-side: parse `window.__DSH_BOOT__` into a `BootManifest` (two views: npm-package rows for the module table, cordis-plugin rows for entry composition; malformed wire throws), build the module system, render the loading page, prefetch the `immediately` tier in parallel with Context/Loader setup, **await the prefetch before creating entries** (materialization is `tree.import`'s synchronous require, unprotected by fiber inject waiting; cross-package require edges such as i18n → runtime/client need every immediately-tier factory registered first — an empirically found 10–25% boot race otherwise), adopt the modules entry, create the graph rows, settle, sweep.

@@ -12,7 +12,7 @@ Status: implemented

 ## 决策

-**组合是一棵平铺 config tree。** `apps/cli/cordis.yml` 持有全部行——host runtime（32 行）、`api-gateway` 行、`webserver` 行、`dshClient` 行（浏览器 roster；modules 行同时是 host 行）。不做 spine bundle：每插件一行、每个 config 字段 yml 可改。`--dev` 在 settle sweep 之前由代码追加 `dsh-client-hmr` 行——prod 与 dev 的全部差异就是这一行。行序无装载语义；激活由服务可用性驱动，boot 以 fail-loud 三件套补偿：`assertEntriesLoaded`（import 失败）、`installFailLoud`（迟到的 apply 拒绝）、all-ACTIVE sweep（PENDING fiber——cordis inject 等待没有超时）。
+**组合是一棵平铺 config tree。** `apps/cli/base.cordis.yml` plus its surface overlay 持有全部行——host runtime（32 行）、`api-gateway` 行、`webserver` 行、`dshClient` 行（浏览器 roster；modules 行同时是 host 行）。不做 spine bundle：每插件一行、每个 config 字段 yml 可改。这一立场后来推广到全仓：两个 surface 共享的配置项被抽取进 `apps/cli/base.cordis.yml`，各 surface 则收敛为一份 overlay（[共享 base overlay](../simplification/2026-07-29-shared-base-config-overlays.md)）。`--dev` 在 settle sweep 之前由代码追加 `dsh-client-hmr` 行——prod 与 dev 的全部差异就是这一行。行序无装载语义；激活由服务可用性驱动，boot 以 fail-loud 三件套补偿：`assertEntriesLoaded`（import 失败）、`installFailLoud`（迟到的 apply 拒绝）、all-ACTIVE sweep（PENDING fiber——cordis inject 等待没有超时）。

 **boot 胶水是一对 class。** `AppCLIEntry`（apps/cli）与 `AppWebEntry`（壳内核）只持有独立于 cordis 必须提前存在的东西：argv 事实、合成的 patch 集、解析出的 boot manifest、模块系统实例、loading 页句柄——其余一律进插件。`AppCLIEntry.run()` 三段：分层 env（ambient > cwd `.env` > `$DSH_HOME/.env`，顺手关掉上述缺陷）→ patch 合成 → Loader include boot 加三件套。`AppWebEntry.run()` 在浏览器侧镜像它：把 `window.__DSH_BOOT__` 解析成 `BootManifest`（双视角：npm 包行给模块表、cordis 插件行给 entry 组合；畸形 wire 大声抛）、建模块系统、渲染 loading 页、immediately 层预取与 Context/Loader 准备并行、**create entry 之前等预取齐**（物化是 `tree.import` 的同步 require，不受 fiber inject 等待保护；i18n → runtime/client 这类跨包 require 边要求 immediately 层工厂全部注册完——否则有实测 10–25% 的 boot 竞态）、收编 modules entry、逐图行 create、settle、sweep。

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-dsh-native-typescript-source-launch.md
-2026-07-28-dsh-native-typescript-source-launch.md: 1ba1dd2663038ad7c49af71f8b428245f7fa3e2b
-2026-07-28-dsh-native-typescript-source-launch.zh.md: 02f84f34820469ad9e810ae17d79d3fe12b0cd4c
+2026-07-28-dsh-native-typescript-source-launch.md: 3fa6ee3711ab5a44391e5c261cff1e7c05fa495a
+2026-07-28-dsh-native-typescript-source-launch.zh.md: b749687b3a8c0f0fb92826dabbcedffa21e433f8
@@ -20,7 +20,7 @@ The `dsh` TUI, Web, and headless source launches use `node --experimental-transf

 `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.
+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/base.cordis.yml` plus its surface overlay 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.

@@ -20,7 +20,7 @@ Cordis 配置还引入了另一条解析边界。`cordis.yml` 中的 bare plugin

 `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 默认解析。
+只有当目标包是最近 package manifest 的自身名称或其已声明的运行时依赖时，源码 import 才会重定向。Cordis Loader 使用配置目录 URL 作为 import parent；此时 resolver 会向上查找声明该插件的 workspace manifest。因此，`examples/tui-agent/cordis.yml` 的依赖由 `examples/package.json` 持有，`apps/cli/base.cordis.yml` plus its surface overlay 的依赖由 `apps/cli/package.json` 持有。未命中 tsconfig paths、引用未声明依赖或不是 bare specifier 的说明符全部交回 Node 默认解析。

 `verify-cordis-config` 对这两个解析方 manifest 执行单向完整性检查：配置中的每个 bare plugin package 都必须出现在对应 manifest 的 `dependencies` 中，manifest 可以包含该配置未引用的额外依赖。根 `AGENTS.md` 将同步更新配置和依赖定为常驻规则。

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-launcher-owned-resume-identity.md
-2026-07-28-launcher-owned-resume-identity.md: 8c48194892f67c1a0f3f87094cd174ca1a71a383
-2026-07-28-launcher-owned-resume-identity.zh.md: 88113017986ac8aaf473d246f701c977804353bf
+2026-07-28-launcher-owned-resume-identity.md: 775f57c019a0dafbb2cfb724a8fb140610234032
+2026-07-28-launcher-owned-resume-identity.zh.md: 94e1de1402586186f6b184baeb8873b1e2868551
@@ -6,7 +6,7 @@ English | [中文](2026-07-28-launcher-owned-resume-identity.zh.md)

 ## Problem

-Two facts a launcher owns were shipped as deployment config keys on `dsh-tui-demo`: `resumeSessionId` (which session `main` binds to) and `resumeCommand` (the exit hint template, with `{session}` interpolated). Neither varies by deployment — both are properties of how the process was invoked, which only the launcher knows.
+Two facts a launcher owns were shipped as deployment config keys on the TUI app bundle: `resumeSessionId` (which session `main` binds to) and `resumeCommand` (the exit hint template, with `{session}` interpolated). Neither varies by deployment — both are properties of how the process was invoked, which only the launcher knows.

 Routing them through YAML made them silently droppable. `@cordisjs/plugin-include` applies a targeted patch by replacing whole top-level keys (`target[key] = value`), so a personal `~/.dsh/config.yaml` patching the `tui-agent` entry's `config` replaces the shipped block entirely. A user overlay written to change provider and model therefore deleted every resume key it did not restate, and nothing reported it: absent `resumeCommand` legitimately means "no fallback configured".

@@ -16,12 +16,14 @@ A config key cannot express these facts safely, because the deployment is not th

 ## Decision

-Session identity and the exit line are launcher-owned context slots, provided before any Loader entry mounts. Neither appears in any `cordis.yml` or in `dsh-tui`'s or `dsh-tui-demo`'s `Config`.
+Session identity and the exit line are launcher-owned context slots, provided before any Loader entry mounts. Neither appears in any `cordis.yml` nor in any plugin's `Config`.

-`dsh-tui` declares both slots beside the existing `tuiResumeHost` host capability, which set the precedent — a resume host has always been a provided capability rather than config:
+Both sit beside the existing `tuiResumeHost` host capability, which set the precedent — a resume host has always been a provided capability rather than config. Each slot is declared by the package that consumes it:

- `MAIN_SESSION_ID_KEY` carries a `MainSessionIdentity` (`{ id: SessionId, resume: boolean }`). `dsh-tui-demo` binds both the TUI and the configured agent to `id`, and takes the history-loading `resumeSessionId` path only when `resume` is set, because that path requires an existing log and fails loud without one. An absent slot means no launcher chose a session, so the app mints `main-session-<uuid>` and creates it fresh.
- `TUI_GOODBYE_MESSAGE_KEY` carries the complete line printed once the terminal is released on exit. Absent prints nothing.
+- `CONFIGURED_AGENT_IDENTITIES_KEY` (`dsh-agent-loop`) carries launcher identities keyed by configured-agent `id`, each a `LauncherAgentIdentity` (`{ id: SessionId, resume: boolean }`). `agent-loop` applies the matching identity over its configured agent, replacing both identity keys, and takes the history-loading `resumeSessionId` path only when `resume` is set, because that path requires an existing log and fails loud without one. An absent slot leaves the configured identity untouched. The `tui` row resolves the same id through its own `sessionId` key, so the front door renders exactly the agent that was bound.
+- `TUI_GOODBYE_MESSAGE_KEY` (`dsh-tui`) carries the complete line printed once the terminal is released on exit. Absent prints nothing.
+
+Identity belongs to `agent-loop` because that is the plugin which creates configured agents, and because a patch replaces a row's whole `config`: an overlay repointing the agent row's model route would erase a launcher-set identity key. See [the shared-base overlay note](../simplification/2026-07-29-shared-base-config-overlays.md).

 `apps/cli` mints or selects the id and builds the line from the invocation it is reproducing, sharing one `resumeArgs` helper with the `/resume` execve handoff so the printed command and the in-place handoff cannot diverge. The line now names `--config` when one was passed, and reproduces `dsh meta --resume <id>` in meta mode — closing the mode-aware hint deferred by the `dsh meta` note, where a copied hint previously only worked from the checkout.

@@ -33,9 +35,9 @@ The TUI owns rendering, not wording: it applies `displayText` before its own `pa

 ## Alternatives considered

-**Keep the keys and add built-in defaults in `dsh-tui-demo`.** Rejected: a default in code survives an overlay, but two ways to state one fact remain, and a config author can still set the key wrong — which is exactly how the stale `process.env.RESUME_SESSION_ID` line disabled resume.
+**Keep the keys and add built-in defaults in the app bundle.** Rejected: a default in code survives an overlay, but two ways to state one fact remain, and a config author can still set the key wrong — which is exactly how the stale `process.env.RESUME_SESSION_ID` line disabled resume.

-**Merge `dsh-tui-demo` into `apps/cli` and delete the slot entirely.** Rejected after investigation, though it is the only way to remove the slot. `examples/tui-agent/code-mode.cordis.yml` patches the `tui-agent` entry through a nested `plugin-include` to switch `tools.mode` and the persona, and `examples/cordis-agent/cordis.yml` reuses the bundle as a different product; both extension points exist only because `tui-agent` is a declared config entry. Merging also moves a 162-line, 18-dependency composition into the CLI's `v8 ignore` process-wiring block, out of the per-file coverage gate.
+**Merge the app bundle into `apps/cli` and delete the slot entirely.** Rejected here, then [adopted later](../simplification/2026-07-29-shared-base-config-overlays.md) in a form this note did not consider: the composition moved into flat config files (`apps/cli/base.cordis.yml` plus a per-surface overlay) rather than into CLI code, so it never entered the `v8 ignore` process-wiring block, and the overlay extension points survive as ordinary row patches. The slot itself was not deleted — it moved to `dsh-agent-loop`, because a launcher fact still cannot travel through a replaceable config key.

 **Put the goodbye message on `TuiResumeHost`.** Rejected: an exit line is not a handoff capability, and a host that cannot replace its process may still want to print one. They are independent slots.

@@ -55,8 +57,8 @@ The TUI owns rendering, not wording: it applies `displayText` before its own `pa

 ## Testing

-`packages/ui/tui/tests/tui.spec.ts` pins the printed line, the absent-slot silence, and escape sanitization of a hostile message; the former two exit-suppression tests are replaced, since suppression is the behavior this change removes. `packages/examples/tui-demo/tests/tui-agent.spec.ts` drives the identity slot for the resume, launcher-minted, and no-slot cases through a fake `ctx.get`.
+`packages/ui/tui/tests/tui.spec.ts` pins the printed line, the absent-slot silence, and escape sanitization of a hostile message; the former two exit-suppression tests are replaced, since suppression is the behavior this change removes. `packages/core/agent-loop/tests/` drives the identity slot for the resume, launcher-minted, and no-slot cases.

-The load-bearing coverage is `examples/tui-agent/tests/tui-keyless-smoke.e2e.ts`, which launches the real `apps/cli/src/bin.ts` in a PTY: one test asserts the exit line carries `--config`, and a regression test seeds a personal `config.yaml` that replaces the entire `tui-agent` config block and asserts the line still prints — encoding "an overlay cannot drop resume" as an executed contract rather than a comment.
+The load-bearing coverage is `apps/cli/tests/tui-keyless-smoke.e2e.ts`, which launches the real `apps/cli/src/bin.ts` in a PTY: one test asserts the exit line carries `--config`, and a regression test seeds a personal `config.yaml` that replaces the entire `agent-loop` config block and asserts the line still prints — encoding "an overlay cannot drop resume" as an executed contract rather than a comment.

 Verified live in tmux against the real personal overlay: the defect reproduced on unmodified staging (requested id ignored, fresh id in the banner), and on this branch the same overlay yields a printed exit line, a `--resume` that restores the prior turn, and a `/resume` selector marking the session `current · live · persisted`. A wrong id now fails loud.
@@ -6,7 +6,7 @@ Status: implemented

 ## Problem

-有两项本应由启动器持有的事实，却被作为 `dsh-tui-demo` 上的部署配置键交付：`resumeSessionId`（`main` 绑定到哪个会话）与 `resumeCommand`（退出提示的模板，其中 `{session}` 会被插值）。二者都不随部署而变——它们都是进程被如何调用的属性，而这一点只有启动器知道。
+有两项本应由启动器持有的事实，却被作为 TUI 应用组合包上的部署配置键交付：`resumeSessionId`（`main` 绑定到哪个会话）与 `resumeCommand`（退出提示的模板，其中 `{session}` 会被插值）。二者都不随部署而变——它们都是进程被如何调用的属性，而这一点只有启动器知道。

 把它们经由 YAML 传递，使其可被静默丢弃。`@cordisjs/plugin-include` 施加定向补丁的方式是替换整个顶层键（`target[key] = value`），因此一份对 `tui-agent` 条目的 `config` 打补丁的个人 `~/.dsh/config.yaml`，会把交付时的整块内容整体替换掉。于是，一份为改动 provider 和 model 而写的用户 overlay，会删掉它未重述的每一个 resume 键，且没有任何东西报告这一点：缺失 `resumeCommand` 合法地意味着「未配置回退」。

@@ -16,12 +16,14 @@ Status: implemented

 ## Decision

-会话身份与退出行是由启动器持有的上下文槽位，在任何 Loader 条目挂载之前提供。二者都不出现在任何 `cordis.yml` 中，也不出现在 `dsh-tui` 或 `dsh-tui-demo` 的 `Config` 中。
+会话身份与退出行是由启动器持有的上下文槽位，在任何 Loader 条目挂载之前提供。二者都不出现在任何 `cordis.yml` 中，也不出现在任何插件的 `Config` 中。

-`dsh-tui` 在既有的 `tuiResumeHost` 宿主能力旁声明这两个槽位，后者确立了先例——resume 宿主一直是一项被提供的能力，而非配置：
+这两个槽位与既有的 `tuiResumeHost` 宿主能力并列，后者确立了先例——resume 宿主一直是一项被提供的能力，而非配置。每个槽位都由消费它的包声明：

- `MAIN_SESSION_ID_KEY` 承载一个 `MainSessionIdentity`（`{ id: SessionId, resume: boolean }`）。`dsh-tui-demo` 把 TUI 与所配置的 agent 都绑定到 `id`，并且仅当 `resume` 被置位时才走加载历史的 `resumeSessionId` 路径，因为该路径要求存在一份日志、否则会明确报错。槽位缺失意味着没有启动器选定会话，于是应用铸造 `main-session-<uuid>` 并新建它。
- `TUI_GOODBYE_MESSAGE_KEY` 承载退出时终端释放后打印一次的完整行。缺失则什么都不打印。
+- `CONFIGURED_AGENT_IDENTITIES_KEY`（`dsh-agent-loop`）按所配置 agent 的 `id` 承载启动器身份，每项为一个 `LauncherAgentIdentity`（`{ id: SessionId, resume: boolean }`）。`agent-loop` 将匹配的身份覆盖到其所配置的 agent 上，替换两个身份键；并且仅当 `resume` 被置位时才走加载历史的 `resumeSessionId` 路径，因为该路径要求存在一份日志、否则会明确报错。槽位缺失则保留配置中的身份不变。`tui` 配置项通过自身的 `sessionId` 键解析同一个 id，因此前端入口渲染的正是被绑定的那个 agent。
+- `TUI_GOODBYE_MESSAGE_KEY`（`dsh-tui`）承载退出时终端释放后打印一次的完整行。缺失则什么都不打印。
+
+身份归属于 `agent-loop`，因为它才是创建所配置 agent 的插件；也因为 patch 会整体替换配置项的 `config`：重新指向 agent 配置项模型路由的 overlay 会抹掉启动器设置的身份键。参见[共享 base overlay note](../simplification/2026-07-29-shared-base-config-overlays.md)。

 `apps/cli` 铸造或选定 id，并依据它所复现的那次调用构建该行，与 `/resume` 的 execve 移交共用同一个 `resumeArgs` 助手，从而使打印出的命令与原地移交不会分歧。该行现在会在传入了 `--config` 时命名它，并在 meta 模式下复现 `dsh meta --resume <id>`——从而收口了 `dsh meta` note 所推迟的随 mode 变化的提示，在那里被复制的提示此前只有在检出目录中才有效。

@@ -33,9 +35,9 @@ TUI 持有渲染，而非措辞：它在自己的 `palette.muted` 之前先应

 ## Alternatives considered

-**保留这些键，并在 `dsh-tui-demo` 中加入内建默认值。** 拒绝：代码中的默认值能在 overlay 下存活，但表达同一事实的两种途径依然并存，而配置作者仍可把键设错——这正是那行陈旧的 `process.env.RESUME_SESSION_ID` 使 resume 失效的方式。
+**保留这些键，并在应用组合包中加入内建默认值。** 拒绝：代码中的默认值能在 overlay 下存活，但表达同一事实的两种途径依然并存，而配置作者仍可把键设错——这正是那行陈旧的 `process.env.RESUME_SESSION_ID` 使 resume 失效的方式。

-**把 `dsh-tui-demo` 合并进 `apps/cli` 并彻底删除该槽位。** 经调查后拒绝，尽管这是移除该槽位的唯一途径。`examples/tui-agent/code-mode.cordis.yml` 通过一个嵌套的 `plugin-include` 给 `tui-agent` 条目打补丁，以切换 `tools.mode` 与人设，而 `examples/cordis-agent/cordis.yml` 把该 bundle 作为另一款产品复用；这两个扩展点都仅因 `tui-agent` 是一个声明式配置条目才存在。合并还会把一段 162 行、18 个依赖的组合逻辑挪进 CLI 的 `v8 ignore` 进程接线块中，脱离逐文件覆盖率门禁。
+**把应用组合包合并进 `apps/cli` 并彻底删除该槽位。** 此处拒绝，但后来以本 note 未曾设想的形式[被采纳](../simplification/2026-07-29-shared-base-config-overlays.md)：组合被搬进平铺的配置文件（`apps/cli/base.cordis.yml` 加各 surface 一份 overlay），而非搬进 CLI 代码，因此从未进入 `v8 ignore` 进程接线块，overlay 的扩展点也作为普通配置项 patch 保留了下来。槽位本身并未被删除——它迁移到了 `dsh-agent-loop`，因为启动器的事实依然不能经由一个可被整体替换的配置键传递。

 **把 goodbye 消息放到 `TuiResumeHost` 上。** 拒绝：退出行不是一项移交能力，而一个无法替换自身进程的宿主仍可能想要打印一行。它们是相互独立的槽位。

@@ -55,8 +57,8 @@ TUI 持有渲染，而非措辞：它在自己的 `palette.muted` 之前先应

 ## Testing

-`packages/ui/tui/tests/tui.spec.ts` 钉住打印出的行、槽位缺失时的静默，以及对恶意消息的转义净化；此前那两个退出抑制测试被替换，因为抑制正是本次改动移除的行为。`packages/examples/tui-demo/tests/tui-agent.spec.ts` 通过一个伪造的 `ctx.get`，为 resume、启动器铸造与无槽位三种情形驱动身份槽位。
+`packages/ui/tui/tests/tui.spec.ts` 钉住打印出的行、槽位缺失时的静默，以及对恶意消息的转义净化；此前那两个退出抑制测试被替换，因为抑制正是本次改动移除的行为。`packages/core/agent-loop/tests/` 为 resume、启动器铸造与无槽位三种情形驱动身份槽位。

-承重的覆盖是 `examples/tui-agent/tests/tui-keyless-smoke.e2e.ts`，它在一个 PTY 中拉起真实的 `apps/cli/src/bin.ts`：一个测试断言退出行携带 `--config`，一个回归测试植入一份个人 `config.yaml` 来替换整块 `tui-agent` 配置块并断言该行仍会打印——把「overlay 不能丢掉 resume」编码为一条被执行的契约，而非一句注释。
+承重的覆盖是 `apps/cli/tests/tui-keyless-smoke.e2e.ts`，它在一个 PTY 中拉起真实的 `apps/cli/src/bin.ts`：一个测试断言退出行携带 `--config`，一个回归测试植入一份个人 `config.yaml` 来替换整块 `agent-loop` 配置块并断言该行仍会打印——把「overlay 不能丢掉 resume」编码为一条被执行的契约，而非一句注释。

 在 tmux 中针对真实的个人 overlay 做过实测：该缺陷在未修改的 staging 上复现（所请求的 id 被忽略，banner 里是新的 id），而在本分支上同一份 overlay 会产出一行打印的退出行、一个能恢复上一轮次的 `--resume`，以及一个把该会话标记为 `current · live · persisted` 的 `/resume` 选择器。错误的 id 现在会明确报错。
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
-2026-07-08-self-referential-cordis-toolset.md: 40934fe0e2975c4e068df6ef8f31ed7921df3230
-2026-07-08-self-referential-cordis-toolset.zh.md: 13662b9359aa85895ce85391ebd5a5902cc451cc
+2026-07-08-self-referential-cordis-toolset.md: 335d5e808016ebc37c8457c5dcf4d7da9d8b8c93
+2026-07-08-self-referential-cordis-toolset.zh.md: 8d2a105a2189aa23915f718c6440069d1a2aa9ed
@@ -12,7 +12,7 @@ First, model-written registration must be validated where it happens: a malforme

 ## Decision

-The toolset ships as [`@deepseek-ai/dsh-tool-cordis`](../../../../packages/cordis/tool-cordis/README.md) and is demoed by [`examples/cordis-agent`](../../../../examples/cordis-agent/README.md). It gives the model three tools over the live Cordis runtime in the current DSH process: inspect it, mount an in-memory temporary Plugin, and unmount that Plugin to quiescence.
+The toolset ships as [`@deepseek-ai/dsh-tool-cordis`](../../../../packages/cordis/tool-cordis/README.md) and is demoed by `examples/web-cordis`. It gives the model three tools over the live Cordis runtime in the current DSH process: inspect it, mount an in-memory temporary Plugin, and unmount that Plugin to quiescence.

 The vm isolates accidental global pollution, and the context façade hides framework internals. Neither restricts the authority of exposed services: a temporary Plugin can call `ctx.bash` with the host executor's privileges and reach the real filesystem and web services. It runs in the shared DSH runtime and may affect other sessions in that process. This is an opt-in development tool with bash-equivalent trust, not a security boundary or product default.

@@ -12,7 +12,7 @@ Status: implemented

 ## 决策

-该工具集以 [`@deepseek-ai/dsh-tool-cordis`](../../../../packages/cordis/tool-cordis/README.md) 发布，并由 [`examples/cordis-agent`](../../../../examples/cordis-agent/README.md) 演示。它为模型提供三个工具，操作当前 DSH 进程中的活跃 Cordis 运行时：审视它、挂载一个仅存于内存的临时 Plugin，再将该 Plugin 卸载至完全停稳。
+该工具集以 [`@deepseek-ai/dsh-tool-cordis`](../../../../packages/cordis/tool-cordis/README.md) 发布，并由 `examples/web-cordis` 演示。它为模型提供三个工具，操作当前 DSH 进程中的活跃 Cordis 运行时：审视它、挂载一个仅存于内存的临时 Plugin，再将该 Plugin 卸载至完全停稳。

 vm 隔离了意外的全局污染，上下文门面隐藏了框架内部细节。但二者都不限制已暴露服务的权限：临时 Plugin 可以调用 `ctx.bash` 以宿主执行器的权限运行命令，也能访问真实的文件系统和网络服务。它运行在共享 DSH runtime 中，可能影响同一进程的其他 session。这是一个需要显式启用的开发工具，信任等级与 bash 相当，不是安全边界，也不是产品默认配置。

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md
-2026-07-17-dedicated-full-screen-tui-front-door.md: bc6241e925d5bf094deded761fb96fd6b6c48a1f
-2026-07-17-dedicated-full-screen-tui-front-door.zh.md: 0f5306ff547cb975b29d1fbcb7e610b3a540ce18
+2026-07-17-dedicated-full-screen-tui-front-door.md: 0f9492509a4fedcf1fcd16deed3b9cd570e3ba18
+2026-07-17-dedicated-full-screen-tui-front-door.zh.md: 0d5a508d200ee39d751070854ce9b93f78ad4121
@@ -14,7 +14,7 @@ The interactive channel must remain a Cordis plugin over the same agent, session

 DeepSeek Harness ships [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) as a dedicated Cordis plugin. It owns terminal input and presentation only; agent lifecycle, session persistence, tool execution, and the model-facing question tool remain separate composition entries. The plugin requires both stdin and stdout to be TTYs and fails instead of silently changing to line-oriented behavior.

-The app layer has one terminal front door. `@deepseek-ai/dsh-tui-demo` mounts the TUI before the configured agent, and `examples/tui-agent` owns the interactive coding composition and Code Mode overlay directly. Non-interactive tasks use `@deepseek-ai/dsh-cli-demo`; ACP remains a separate automation protocol.
+There is one terminal front door. `@deepseek-ai/dsh-tui` mounts before the configured agent, and `apps/cli/tui.cordis.yml` — an overlay over the shared `base.cordis.yml` — owns the interactive coding composition, with the Code Mode overlay in `examples/code-mode`. Non-interactive tasks use `@deepseek-ai/dsh-cli-demo`; ACP remains a separate automation protocol.

 The selected front door receives the exact generated or resumed `SessionId` used by the pre-created agent. It mounts before the agent composition, waits for the matching root agent, and enters full-screen mode only after that agent exists. A matching `agent-loop/config-start-failed` event is therefore reported before screen takeover and exits with status 1.

@@ -14,7 +14,7 @@ Status: implemented

 DeepSeek Harness 将 [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) 作为独立的 Cordis 插件交付。该插件只负责终端输入与呈现；agent 生命周期、会话持久化、工具执行以及模型可见的提问工具仍由不同组合项负责。插件要求 stdin 和 stdout 均为 TTY；条件不满足时会失败，不会静默切换为逐行输出。

-应用组合层只有一个终端入口。`@deepseek-ai/dsh-tui-demo` 在已配置 agent 之前挂载 TUI，`examples/tui-agent` 直接拥有交互式 coding 组装及其 Code Mode overlay。非交互任务使用 `@deepseek-ai/dsh-cli-demo`；ACP 仍是独立的自动化协议。
+只有一个终端入口。`@deepseek-ai/dsh-tui` 在已配置 agent 之前挂载，而 `apps/cli/tui.cordis.yml`——叠加在共享 `base.cordis.yml` 之上的 overlay——拥有交互式 coding 组装，Code Mode overlay 则位于 `examples/code-mode`。非交互任务使用 `@deepseek-ai/dsh-cli-demo`；ACP 仍是独立的自动化协议。

 所选入口接收预创建 agent 使用的同一个新建或恢复 `SessionId`。入口先于 agent 组合挂载，等待相符的根 agent 出现，然后才进入全屏模式。因此，相符的 `agent-loop/config-start-failed` 事件会在接管屏幕前报告，并以状态码 1 退出。

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md
-2026-07-24-web-session-model-selector.md: 4bd52bba8d3ba16c01fc59d2b561516f6fd0bb87
-2026-07-24-web-session-model-selector.zh.md: 35f3525b80e7d27fb573e854aefc317ed354df53
+2026-07-24-web-session-model-selector.md: bf2f1f3c677ef576b1a00fb8bd0133154462d705
+2026-07-24-web-session-model-selector.zh.md: b2e17bdf487c717dc85e9b16b8f8e526557cdfb9
@@ -18,7 +18,7 @@ The browser `ModelService` owns one `ModelDirectory` per live session. Its snaps

 `@deepseek-ai/dsh-client-ui-conversation` declares the session-scoped single slot `conversation.input.model` as a child of its composer-bar entry. InputBar renders the seat in its trailing controls immediately before the pending indicator and primary button; the seat receives the bar's `locked` owner prop and session scope. `@deepseek-ai/dsh-client-ui-model` occupies that seat and also contributes `/model` over the same directory. Its compact trigger displays the catalog model name and effective reasoning label, falling back to ids when metadata is absent. The upward menu first offers Model and, when the current exact model supports it, Effort; Model drills into provider groups, while Effort drills into the adapter-ordered levels. The provider-default row appears only when the adapter does not configure a model default.

-The production browser roster is the flat config tree in `apps/cli/cordis.yml`; the model feature is one `dshClient` row rather than a package hardcoded in Web boot code. Its package manifest orders it after the runtime and command feature, while Cordis service injection waits for the conversation slot before registering the composer occupant.
+The production browser roster is the flat config tree in `apps/cli/web.cordis.yml`; the model feature is one `dshClient` row rather than a package hardcoded in Web boot code. Its package manifest orders it after the runtime and command feature, while Cordis service injection waits for the conversation slot before registering the composer occupant.

 ## Alternatives considered

@@ -18,7 +18,7 @@ Web Host 为每个新建或恢复的 agent（智能体）复用 `installAgentLlm

 `@deepseek-ai/dsh-client-ui-conversation` 将会话作用域的单实例 slot `conversation.input.model` 声明为其输入栏 entry 的子 slot。InputBar 在尾部控件区将该 seat 渲染于 pending 指示器与主按钮之前；该 seat 接收输入栏的 `locked` owner prop 与会话作用域。`@deepseek-ai/dsh-client-ui-model` 占用该 seat，并在同一目录上提供 `/model`。其紧凑型触发器显示目录中的模型名称与生效的推理强度标签；元数据缺失时则回退到相应 ID。向上展开的菜单首先提供 Model，并在当前精确模型支持时提供 Effort；Model 可深入提供方分组，Effort 可深入适配器排序的级别。仅当适配器没有配置模型默认值时，才显示提供方默认值行。

-生产环境的浏览器名册是 `apps/cli/cordis.yml` 中的平铺 config tree；模型功能对应其中一行 `dshClient` 配置项，而不是 Web boot 代码中硬编码的包。其包 manifest（元数据清单）将加载顺序置于运行时与命令功能之后；Cordis 服务注入则等待 conversation slot 可用，再注册 composer 占用方。
+生产环境的浏览器名册是 `apps/cli/base.cordis.yml` plus its surface overlay 中的平铺 config tree；模型功能对应其中一行 `dshClient` 配置项，而不是 Web boot 代码中硬编码的包。其包 manifest（元数据清单）将加载顺序置于运行时与命令功能之后；Cordis 服务注入则等待 conversation slot 可用，再注册 composer 占用方。

 ## 考虑过的替代方案

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-cross-workspace-resume.md
-2026-07-28-cross-workspace-resume.md: 09b638398ea9379d39df94fcb42da3395cdd70df
-2026-07-28-cross-workspace-resume.zh.md: 5a2e7d2535c07b4ace0416b234dc28b32cbcd2fc
+2026-07-28-cross-workspace-resume.md: d559b73a5ba0f8136d20ef6dcf7c62989d1527e9
+2026-07-28-cross-workspace-resume.zh.md: 404b81cbc07a455e5553a9c227d663e491456c9e
@@ -8,7 +8,7 @@ English | [中文](2026-07-28-cross-workspace-resume.zh.md)

 `/resume` could only reach sessions started in the launch directory, so returning to yesterday's work in another project meant remembering its path, leaving the TUI, and relaunching there. Two independent causes produced that limit, and fixing either alone changes nothing.

-Storage was the binding one. The shipped `tui-demo` bundle defaulted `persistenceRoot` to a relative `./.sessions`, so each launch directory owned a disjoint JSONL root and a disjoint derived `session-query.db`. Sessions from another project were not filtered out of the listing — they were absent from the store the listing reads. The JSONL backend already partitions per-cwd *inside* one root, so the partitioning was doubled: once by root, once within it.
+Storage was the binding one. The shipped TUI composition defaulted its persistence root to a relative `./.sessions`, so each launch directory owned a disjoint JSONL root and a disjoint derived `session-query.db`. Sessions from another project were not filtered out of the listing — they were absent from the store the listing reads. The JSONL backend already partitions per-cwd *inside* one root, so the partitioning was doubled: once by root, once within it.

 The picker then filtered again. It dropped records whose `cwd` differed from the current session before display, and `summarizeResumeCandidate` independently marked a differing `cwd` as `disabledReason: 'different workspace'`, so a foreign session that did reach the store was both hidden and refused.

@@ -20,7 +20,7 @@ The dsh launcher supplies one session root under its Harness home through a boot

 **Storage.** `dsh-paths` owns the location as `resolveSessionsRoot()` (`sessions` under the Harness home, by `resolveDshHome`'s precedence), but only the launcher assumes it: shared-store policy is the dsh CLI's, never a plugin's. The TUI surface provides the root through the `SESSIONS_ROOT_KEY` boot slot (`ctx.provide` before Loader entries mount) and `dsh web` patches the same root in `apps/cli/src/app-cli-entry.ts`. Two CLI surfaces computing that path independently is exactly the failure this change fixes — disjoint stores — so the fact gets one home rather than a `join` per caller, alongside the existing `registryRoot()` precedent for `run`.

-`tui-demo` itself keeps a project-local `./.sessions` default and reads the launcher slot between explicit config and that default (`config.persistenceRoot ?? ctx.get(SESSIONS_ROOT_KEY) ?? './.sessions'`). The precedence lives in `composeTuiApp`, not as a schemastery `.default()`, because a schema default would materialize before the compose function runs and shadow the slot for every Loader mount. `examples/tui-agent/cordis.yml` omits `persistenceRoot` so the launcher slot (or, for a bare example boot, the project-local default) applies. Configuring an explicit root always wins, which remains the correct choice for a hermetic deployment.
+The shared base states that precedence in the row itself: `apps/cli/base.cordis.yml`'s `session-persistence-jsonl` row reads `root: !!js launcherSessionsRoot ?? './.sessions'`, so the launcher slot wins and a bare boot without one keeps the project-local default. Expressing it as the row's own `!!js` value rather than a schemastery `.default()` matters for the same reason it did in the bundle: a schema default would materialize before the slot could be read. An overlay or personal patch that states an explicit root always wins, which remains the correct choice for a hermetic deployment.

 **Scope, not exclusion.** A workspace other than the current one is a display scope rather than a disabled reason. `showResume()` summarizes every record and the `ResumePicker` owns a `scope` of `'workspace' | 'all'`, defaulting to the current workspace so the common case is unchanged. Tab toggles; the scope line names the active scope and the count the other holds; each row in the all-workspaces scope reports its own workspace, and that label joins the searchable text only in the scope that shows it. A toggle clears the query and selection so the highlighted row always belongs to the visible list, and the per-row workspace line makes a row one terminal row taller in that scope, which the visible-count budget accounts for.

@@ -49,4 +49,4 @@ The dsh launcher supplies one session root under its Harness home through a boot

 ## Testing

-TUI tests cover the default scope hiding other workspaces while reporting their count, Tab revealing them with per-row workspace labels, Tab back clearing the query and selection, searching by workspace label, a cwd-less record staying visible but disabled, and the handoff receiving both the id and the workspace re-read at preflight. The former "reject a moved cwd" case now asserts the handoff carries the new directory. `dsh-paths` tests pin `resolveSessionsRoot`'s precedence against `resolveDshHome`'s. `tui-demo` composition tests pin the project-local default and the derived `session-query.db` path. The keyless TUI snapshot pins both scopes of the selector, including the scope line, the per-row workspace lines, and the Tab hint in the footer. A manual cross-workspace resume verified at the process level that the replacement's working directory became the target workspace.
+TUI tests cover the default scope hiding other workspaces while reporting their count, Tab revealing them with per-row workspace labels, Tab back clearing the query and selection, searching by workspace label, a cwd-less record staying visible but disabled, and the handoff receiving both the id and the workspace re-read at preflight. The former "reject a moved cwd" case now asserts the handoff carries the new directory. `dsh-paths` tests pin `resolveSessionsRoot`'s precedence against `resolveDshHome`'s. `apps/cli` tests pin the project-local default and the derived `session-query.db` path. The keyless TUI snapshot pins both scopes of the selector, including the scope line, the per-row workspace lines, and the Tab hint in the footer. A manual cross-workspace resume verified at the process level that the replacement's working directory became the target workspace.
@@ -8,7 +8,7 @@ Status: implemented

 `/resume` 只能触达在启动目录中创建的会话，因此要回到昨天在另一个项目里的工作，就得记住它的路径、退出 TUI、再到那里重新启动。造成这一限制的原因有两个，彼此独立，只修其中一个都不会有任何变化。

-存储是那个决定性的原因。已交付的 `tui-demo` 组合包把 `persistenceRoot` 默认成相对路径 `./.sessions`，于是每个启动目录都独占一份互不相交的 JSONL 根目录，以及一份互不相交的派生 `session-query.db`。来自另一个项目的会话并不是在列表中被过滤掉的——它们根本不存在于列表读取的存储中。JSONL 后端本来就会在*同一个*根目录*内部*按 cwd 分区，所以分区被叠加了两层：一层按根目录，一层在根目录内部。
+存储是那个决定性的原因。已交付的 TUI 组合把持久化根默认成相对路径 `./.sessions`，于是每个启动目录都独占一份互不相交的 JSONL 根目录，以及一份互不相交的派生 `session-query.db`。来自另一个项目的会话并不是在列表中被过滤掉的——它们根本不存在于列表读取的存储中。JSONL 后端本来就会在*同一个*根目录*内部*按 cwd 分区，所以分区被叠加了两层：一层按根目录，一层在根目录内部。

 接着选择器又过滤了一次。它在展示前丢弃 `cwd` 与当前会话不同的记录，而 `summarizeResumeCandidate` 又独立地把不同的 `cwd` 标记为 `disabledReason: 'different workspace'`，于是一个确实进入了存储的外部会话既被隐藏，也会被拒绝。

@@ -20,7 +20,7 @@ dsh 启动器通过启动槽位提供其 Harness home 下的同一个会话根

 **存储。** `dsh-paths` 以 `resolveSessionsRoot()` 拥有该位置（按 `resolveDshHome` 的优先级，取 Harness home 下的 `sessions`），但只有启动器假定它：共享存储策略属于 dsh CLI，绝不属于插件。TUI 界面通过 `SESSIONS_ROOT_KEY` 启动槽位（在 Loader 条目挂载前 `ctx.provide`）提供该根目录，`dsh web` 则在 `apps/cli/src/app-cli-entry.ts` 中为同一根目录打补丁。CLI 的两处界面各自独立计算该路径，正是本次改动所修复的那种失败——互不相交的存储——因此这项事实只有一个归属，而不是每个调用方各做一次 `join`，这与 `run` 已有的 `registryRoot()` 先例一致。

-`tui-demo` 自身保持项目本地的 `./.sessions` 默认值，并在显式配置与该默认值之间读取启动器槽位（`config.persistenceRoot ?? ctx.get(SESSIONS_ROOT_KEY) ?? './.sessions'`）。这一优先级放在 `composeTuiApp` 内，而不是写成 schemastery 的 `.default()`，因为 schema 默认值会在 compose 函数运行前物化，使每次 Loader 挂载都遮蔽该槽位。`examples/tui-agent/cordis.yml` 不写 `persistenceRoot`，因此启动器槽位（裸示例启动时则为项目本地默认值）生效。显式配置的根目录总是获胜，对于封闭部署来说这仍然是正确的选择。
+共享 base 直接在配置项自身表达这一优先级：`apps/cli/base.cordis.yml` 的 `session-persistence-jsonl` 配置项写作 `root: !!js launcherSessionsRoot ?? './.sessions'`，因此启动器槽位优先，而没有槽位的裸启动则保留项目本地默认值。把它写成配置项自身的 `!!js` 取值、而不是 schemastery 的 `.default()`，其原因与在组合包中相同：schema 默认值会在能够读取槽位之前就物化。若 overlay 或个人 patch 显式声明了根目录，则始终以其为准——对于要求自洽封闭的部署，这仍是正确选择。

 **是范围，不是排除。** 当前 workspace 之外的 workspace 是一种展示范围，而不是禁用理由。`showResume()` 汇总每一条记录，`ResumePicker` 持有一个 `'workspace' | 'all'` 的 `scope`，默认为当前 workspace，因此常见场景毫无变化。Tab 切换范围；范围行会说明当前生效的范围，以及另一个范围下的数量；在全 workspace 范围中每一行都报告自己的 workspace，而该标签只在展示它的范围里才加入可搜索文本。切换范围会清空查询和选中项，使高亮行始终属于可见列表；而逐行的 workspace 行会让该范围下的每一行在终端里多占一行，可见条数预算已经把这一点计入。

@@ -49,4 +49,4 @@ dsh 启动器通过启动槽位提供其 Harness home 下的同一个会话根

 ## Testing

-TUI 测试覆盖默认范围隐藏其他 workspace 但报告其数量、Tab 显示它们并带上逐行 workspace 标签、再按 Tab 返回时清空查询与选中项、按 workspace 标签搜索、无 cwd 的记录仍可见但不可选，以及交接同时收到 id 和在预检时重新读取到的 workspace。原先「拒绝已移动的 cwd」的用例现在断言交接携带新目录。`dsh-paths` 测试固定 `resolveSessionsRoot` 的优先级与 `resolveDshHome` 的一致。`tui-demo` 组合测试固定项目本地默认值以及派生出的 `session-query.db` 路径。无密钥 TUI 快照固定选择器的两个范围，包括范围行、逐行 workspace 行，以及页脚中的 Tab 提示。手动执行的一次跨 workspace 恢复在进程层面验证了替换后进程的工作目录变为目标 workspace。
+TUI 测试覆盖默认范围隐藏其他 workspace 但报告其数量、Tab 显示它们并带上逐行 workspace 标签、再按 Tab 返回时清空查询与选中项、按 workspace 标签搜索、无 cwd 的记录仍可见但不可选，以及交接同时收到 id 和在预检时重新读取到的 workspace。原先「拒绝已移动的 cwd」的用例现在断言交接携带新目录。`dsh-paths` 测试固定 `resolveSessionsRoot` 的优先级与 `resolveDshHome` 的一致。`apps/cli` 测试钉住项目本地默认值与派生的 `session-query.db` 路径。无密钥 TUI 快照固定选择器的两个范围，包括范围行、逐行 workspace 行，以及页脚中的 Tab 提示。手动执行的一次跨 workspace 恢复在进程层面验证了替换后进程的工作目录变为目标 workspace。
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-dsh-guided-skill-session-commands.md
-2026-07-28-dsh-guided-skill-session-commands.md: 338629f5a1adb9c1973daf87f2f52479bd70ba47
-2026-07-28-dsh-guided-skill-session-commands.zh.md: a9a8a70212dd92b9c850a529789f4e4879838090
+2026-07-28-dsh-guided-skill-session-commands.md: a11807dca9ad1640857cd95a8b528df691b8a27e
+2026-07-28-dsh-guided-skill-session-commands.zh.md: e48420ed77496d8c336031473364f9008fccced7
@@ -12,7 +12,7 @@ Two recurring flows begin with the user manually invoking one skill and answerin

 `dsh migrate` and `dsh upgrade` boot the ordinary TUI as a fresh session whose first turn auto-invokes a bundled skill (`dsh-migrate`, `dsh-upgrade`), exactly as if the user typed `/skill:<name>` and pressed Enter.

-The seed reuses the existing TUI skill path, not a new one. `createTuiChat` already has `invokeSkill(name, instructions)` — the code a typed `/skill:<name>` runs, including the "Unknown skill" notice. The launcher passes the skill name to the app through a new boot-context slot `INITIAL_SKILL_KEY` (`tuiInitialSkill`), mirroring `MAIN_SESSION_ID_KEY`/`TUI_GOODBYE_MESSAGE_KEY`: `ctx.provide` is the only channel from launcher argv into a Loader-mounted plugin. The TUI's `apply()` reads the slot and folds it into `config.initialSkill`; after `ui.start()` succeeds, `createTuiChat` fires `invokeSkill(config.initialSkill, '')` once when set.
+The seed reuses the existing TUI skill path, not a new one. `createTuiChat` already has `invokeSkill(name, instructions)` — the code a typed `/skill:<name>` runs, including the "Unknown skill" notice. The launcher passes the skill name to the TUI through a new boot-context slot `INITIAL_SKILL_KEY` (`tuiInitialSkill`), mirroring `CONFIGURED_AGENT_IDENTITIES_KEY`/`TUI_GOODBYE_MESSAGE_KEY`: `ctx.provide` is the only channel from launcher argv into a Loader-mounted plugin. The TUI's `apply()` reads the slot and folds it into `config.initialSkill`; after `ui.start()` succeeds, `createTuiChat` fires `invokeSkill(config.initialSkill, '')` once when set.

 **Freshness is gated in the launcher, not the TUI.** `runSkillSession` always mints a fresh session and provides the slot only when `resumeSessionId === undefined`, so a later `dsh --resume <id>` of that session is an ordinary TUI session with no re-injection. The TUI stays generic: it invokes whatever skill it is handed, once, at startup.

@@ -36,7 +36,7 @@ No keyless PTY snapshot: per the maintainer's scope call for this change, unit c

 **Support `--resume` on `migrate`/`upgrade`.** Rejected: these are one-shot guided entries. A resumed session is an ordinary TUI session reachable through the default surface's `dsh --resume <id>`; re-injecting the skill on resume would duplicate the first turn.

-**Read `INITIAL_SKILL_KEY` in the app bundle (like `MAIN_SESSION_ID_KEY`) rather than in the TUI's `apply()`.** Not needed: `initialSkill` is a TUI `Config` field consumed in `createTuiChat`, so folding the slot into config at the TUI entry keeps it beside the other launcher-owned runtime reads (`tuiResumeHost`, `tuiGoodbyeMessage`) and leaves the app bundle unchanged.
+**Read `INITIAL_SKILL_KEY` outside the TUI (as `CONFIGURED_AGENT_IDENTITIES_KEY` is read by `agent-loop`) rather than in the TUI's `apply()`.** Not needed: `initialSkill` is a TUI `Config` field consumed in `createTuiChat`, so folding the slot into config at the TUI entry keeps it beside the other launcher-owned runtime reads (`tuiResumeHost`, `tuiGoodbyeMessage`) and touches no other plugin.

 ## Consequences

@@ -12,7 +12,7 @@ Status: implemented

 `dsh migrate` 与 `dsh upgrade` 以全新会话启动普通 TUI，其首轮自动调用一个内置 skill（`dsh-migrate`、`dsh-upgrade`），效果等同于用户键入 `/skill:<name>` 并回车。

-播种复用现有的 TUI skill 路径，而非新增一条。`createTuiChat` 已有 `invokeSkill(name, instructions)`——即键入 `/skill:<name>` 所走的代码，包含“未知 skill”通知。启动器通过一个新的启动上下文槽 `INITIAL_SKILL_KEY`（`tuiInitialSkill`）把 skill 名称传给应用，与 `MAIN_SESSION_ID_KEY`/`TUI_GOODBYE_MESSAGE_KEY` 一致：`ctx.provide` 是从启动器 argv 进入 Loader 挂载插件的唯一通道。TUI 的 `apply()` 读取该槽并折叠进 `config.initialSkill`；`ui.start()` 成功后，`createTuiChat` 在其被设置时调用一次 `invokeSkill(config.initialSkill, '')`。
+播种复用现有的 TUI skill 路径，而非新增一条。`createTuiChat` 已有 `invokeSkill(name, instructions)`——即键入 `/skill:<name>` 所走的代码，包含“未知 skill”通知。启动器通过一个新的启动上下文槽 `INITIAL_SKILL_KEY`（`tuiInitialSkill`）把 skill 名称传给 TUI，与 `CONFIGURED_AGENT_IDENTITIES_KEY`/`TUI_GOODBYE_MESSAGE_KEY` 一致：`ctx.provide` 是从启动器 argv 进入 Loader 挂载插件的唯一通道。TUI 的 `apply()` 读取该槽并折叠进 `config.initialSkill`；`ui.start()` 成功后，`createTuiChat` 在其被设置时调用一次 `invokeSkill(config.initialSkill, '')`。

 **新鲜性在启动器而非 TUI 中把关。** `runSkillSession` 总是创建全新会话，且仅在 `resumeSessionId === undefined` 时提供该槽，因此之后 `dsh --resume <id>` 恢复该会话时是普通 TUI 会话，不会重复注入。TUI 保持通用：它只是把接到的 skill 在启动时调用一次。

@@ -36,7 +36,7 @@ Status: implemented

 **在 `migrate`/`upgrade` 上支持 `--resume`。** 已否决：它们是一次性引导入口。恢复的会话是可经默认界面 `dsh --resume <id>` 到达的普通 TUI 会话；恢复时重新注入 skill 会重复首轮。

-**在应用 bundle 中读取 `INITIAL_SKILL_KEY`（像 `MAIN_SESSION_ID_KEY` 那样）而非在 TUI 的 `apply()` 中。** 无此必要：`initialSkill` 是在 `createTuiChat` 中消费的 TUI `Config` 字段，因此在 TUI 入口处把该槽折叠进 config，可与其他启动器拥有的运行时读取（`tuiResumeHost`、`tuiGoodbyeMessage`）并列，且无需改动应用 bundle。
+**在 TUI 之外读取 `INITIAL_SKILL_KEY`（如同 `agent-loop` 读取 `CONFIGURED_AGENT_IDENTITIES_KEY` 那样），而非在 TUI 的 `apply()` 中。** 无此必要：`initialSkill` 是在 `createTuiChat` 中消费的 TUI `Config` 字段，因此在 TUI 入口处把该槽位折叠进配置，可以让它与其他由启动器持有的运行时读取（`tuiResumeHost`、`tuiGoodbyeMessage`）并列，且不触及任何其他插件。

 ## 后果

@@ -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-remove-stdio-and-echo-agents.md: d804f8e3c3de886fc48c87d6378c9f06d0e3c15a
-2026-07-20-remove-stdio-and-echo-agents.zh.md: d42e6d527231e1703153c02c66d9286fa1e73c95
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md
+2026-07-20-remove-stdio-and-echo-agents.md: 4b6a41489b3a1031aad6134052273035ea208e30
+2026-07-20-remove-stdio-and-echo-agents.zh.md: 95af2e74ccce4738fed713c3c58904c48517a479
@@ -18,7 +18,7 @@ The stdio and Echo agents are removed without compatibility packages, modes, com

 The remaining application roles are explicit:

- [`@deepseek-ai/dsh-tui-demo`](../../../../packages/examples/tui-demo/README.md) owns terminal-interactive execution. It rejects non-TTY streams before Loader boot; `examples/tui-agent` owns the complete coding composition, Code Mode overlay, PTY coverage, and terminal snapshots.
+- [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) owns terminal-interactive execution. It rejects non-TTY streams before Loader boot; `apps/cli/base.cordis.yml` plus the `tui.cordis.yml` overlay own the complete coding composition, with the Code Mode overlay in `examples/code-mode` and PTY plus terminal-snapshot coverage in `apps/cli/tests/`.
 - [`@deepseek-ai/dsh-cli-demo`](../../../../packages/examples/cli-demo/README.md) owns non-interactive execution, including pipes. `examples/headless-agent` owns the real-model one-shot composition, replay snapshots, generic real-agent suites, and test-only keyless Loader fixtures.
 - [`@deepseek-ai/dsh-acp-demo`](../../../../packages/examples/acp-demo/README.md) and `@deepseek-ai/dsh-jsonrpc` own their framed protocol integrations.

@@ -18,7 +18,7 @@ DeepSeek Harness 在 TUI 和 Headless coding agent 之外，还提供了两个

 保留的应用角色均有明确归属：

- [`@deepseek-ai/dsh-tui-demo`](../../../../packages/examples/tui-demo/README.md) 负责终端交互式执行。它会在 Loader 启动前拒绝非 TTY 流；`examples/tui-agent` 拥有完整 coding 组装、Code Mode 覆盖层、PTY 覆盖和终端快照。
+- [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) 负责终端交互式执行。它会在 Loader 启动前拒绝非 TTY 流；`examples/tui-agent` 拥有完整 coding 组装、Code Mode 覆盖层、PTY 覆盖和终端快照。
 - [`@deepseek-ai/dsh-cli-demo`](../../../../packages/examples/cli-demo/README.md) 负责非交互式执行，包括管道方式。`examples/headless-agent` 拥有真实模型的单次任务组装、回放快照、通用真实 agent 测试套件，以及仅供测试使用的无密钥 Loader fixture。
 - [`@deepseek-ai/dsh-acp-demo`](../../../../packages/examples/acp-demo/README.md) 和 `@deepseek-ai/dsh-jsonrpc` 负责各自的分帧协议集成。

@@ -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/simplification/2026-07-29-shared-base-config-overlays.md
+2026-07-29-shared-base-config-overlays.md: c3c1bd962dd61201958053d1f1c04e05646f78bd
+2026-07-29-shared-base-config-overlays.zh.md: dcf7eaafa7f46b8c2fc1a45e627d31770ba3b234
@@ -0,0 +1,53 @@
+# Agent Note: One shared base config with per-surface overlays
+
+Status: implemented
+
+English | [中文](2026-07-29-shared-base-config-overlays.zh.md)
+
+## Problem
+
+`dsh` shipped two full config trees that were 43 rows the same. `apps/cli/cordis.yml` composed the web surface as 74 flat rows, while the TUI booted `examples/tui-agent/cordis.yml`, whose single `@deepseek-ai/dsh-tui-demo` row mounted twelve plugins and re-declared their configuration as its own twenty-key pass-through `Config`.
+
+Neither file was what its location claimed. `examples/tui-agent` was not an example: `apps/cli/src/tui.ts` hardcoded it as the product's default config, and it owned the TUI PTY smoke, the eight terminal snapshot scenarios, and the PTY harness the `cordis-agent` leaf imported. `dsh-tui-demo` was not a demo either — it was the application, mounted by the shipped binary from `packages/examples/`.
+
+The duplication was the load-bearing problem. Of the 43 shared rows, 38 were byte-identical and 5 differed for a defensible per-surface reason, so every capability change had to be made twice and could silently drift. The bundle also inverted a default: `composeTuiApp` read `config.goals ?? {}`, so the shipped TUI mounted goals, `tool-goal`, `goal-session`, and `/goal` although no config key requested them.
+
+## Decision
+
+One shared base, one overlay per surface, composed as sibling patch lists.
+
+`apps/cli/base.cordis.yml` holds the 43 rows both surfaces mount. `apps/cli/tui.cordis.yml` and `apps/cli/web.cordis.yml` are **patch lists**, not trees: each states the handful of rows whose value is surface-specific and inserts its own rows. The launcher includes the base once and applies every overlay as a sibling patch list at **one** include level, because include patches never cross an include boundary — stacking overlays as nested includes would silently stop reaching base rows.
+
+Precedence is list order, last write winning per row: base, then the surface overlay, then either a `--config` overlay or the personal `~/.dsh/config.yaml`, then the launcher's own flag and profile patches.
+
+`--config <path>` now applies an overlay **instead of** the personal overlay, so a demo or test tree never inherits the user's provider and model. `--config-replace <path>` boots a file as the entire tree, bypassing base, surface overlay, and personal overlay alike; that is what the old `--config` did, so trees like `examples/web-cordis` moved to the new flag. Both flags survive the `/resume` execve handoff, or resuming would silently change the agent.
+
+A patch replaces its target row's whole `config` rather than merging, which shapes the split: a row whose value differs per surface lives in the overlays, never in the base, so no row is patched by three layers at once. Session identity therefore cannot ride a config key at all — it moved to `dsh-agent-loop`'s `CONFIGURED_AGENT_IDENTITIES_KEY`, as [the launcher-owned identity note](../architecture/2026-07-28-launcher-owned-resume-identity.md) now records.
+
+`examples/tui-agent`, `examples/cordis-agent`, and `packages/examples/tui-demo` are deleted. The TUI tests move to `apps/cli/tests/`, the cordis-toolset e2e to `packages/cordis/tool-cordis/tests/`, and `examples/code-mode` survives as a genuine example: an overlay that patches `tools.mode` and inserts the code runtime.
+
+## Alternatives considered
+
+**Leave both trees flat and duplicated.** Rejected: 43 rows maintained twice is the defect, and a gate asserting they stay identical would freeze the duplication rather than remove it.
+
+**Nest the overlays as includes (`code-mode` → `tui` → `base`).** Rejected after testing the Loader: patches do not cross an include boundary, so the outer file's patches are dropped with only a warning. A three-level chain left `tools` unpatchable, and a base behind one include made every personal patch a silent no-op.
+
+**Put the union of all rows in the base and have each overlay disable what it does not want.** Rejected: the base stops meaning "shared", and each surface carries rows it exists only to switch off.
+
+**Keep the per-surface rows in the base and let overlays patch them.** Adopted only for the five rows that must exist in both trees, because a patch cannot create a row. Their base entries carry the plugin name and the config both surfaces share; each overlay states the rest.
+
+## Consequences
+
+An overlay or `--config` tree that named `@deepseek-ai/dsh-tui-demo`, or patched the `tui-agent` row, no longer resolves. Overlays now patch the row that owns each key: the model route on `agent-loop`, the persona on `system-prompt`, presentation on `tui`.
+
+A patch whose `id` matches no row stays a Loader warning rather than an error. That is deliberate: one personal overlay is shared across surfaces, and `insert` rows match nothing by design, so a row that exists only under `web` must not fail the TUI's boot.
+
+`dsh web` gains `--config`, threaded into `AppCLIEntry` as an extra overlay. `AppCLIEntry` reads both the base and its surface overlay when recovering row defaults for its own patch merge, since a flag override must preserve the overlay's other fields on the same row.
+
+## Verification
+
+Composition is checked by booting each tree through the real Loader and inspecting settled entries, not by reading YAML: the TUI settles 55 entries and web 75, both with zero unloaded or unsettled rows, and web's `httpServer` up. The three-layer case (`base` + `tui` + `code-mode`) confirms `tools.mode` reaching `code` over the TUI overlay's `native`.
+
+All eight terminal snapshot scenarios replay byte-identically after moving, and the 14-case PTY smoke passes, including two cases that assert a personal overlay reaches an **inserted** row — the behavior the vendored `plugin-include` fix enables ([`vendor/README.md`](../../../../vendor/README.md) local modification 8, covered by `packages/ui/app-boot/tests/config-reload.spec.ts`).
+
+Flattening surfaced three latent defects, each fixed here: the TUI captured the optional `sessionQuery` service once at construction and so could permanently disable `/resume` when it won the mount race; the shipped session-store root silently reverted to a project-local `./.sessions`; and `--config-replace` was dropped by the resume handoff.
@@ -0,0 +1,53 @@
+# Agent Note: 一份共享 base 配置加各 surface 的 overlay
+
+Status: implemented
+
+[English](2026-07-29-shared-base-config-overlays.md) | 中文
+
+## 问题
+
+`dsh` 交付了两棵完整的配置树，其中 43 个配置项完全相同。`apps/cli/cordis.yml` 以 74 个平铺配置项组合 web surface，而 TUI 启动的是 `examples/tui-agent/cordis.yml`——其中单独一行 `@deepseek-ai/dsh-tui-demo` 挂载了十二个插件，并把它们的配置重新声明为自己那份二十个键、仅作透传的 `Config`。
+
+这两份文件都名不副实。`examples/tui-agent` 并不是示例：`apps/cli/src/tui.ts` 把它硬编码为产品的默认配置；它还拥有 TUI 的 PTY 冒烟测试、八个终端快照场景，以及被 `cordis-agent` 叶节点 import 的 PTY harness。`dsh-tui-demo` 也不是 demo——它就是应用本身，由交付的二进制从 `packages/examples/` 中挂载。
+
+真正决定性的问题是重复。43 个共享配置项中，38 个逐字节相同，5 个因各 surface 的正当理由而不同；因此每次能力改动都必须改两处，而且可能无声漂移。该组合包还反转了一个默认值：`composeTuiApp` 读取 `config.goals ?? {}`，于是交付的 TUI 挂载了 goals、`tool-goal`、`goal-session` 和 `/goal`——尽管没有任何配置键要求它们。
+
+## 决策
+
+一份共享 base，每个 surface 一份 overlay，以平级 patch 列表的形式组合。
+
+`apps/cli/base.cordis.yml` 持有两个 surface 都会挂载的 43 个配置项。`apps/cli/tui.cordis.yml` 与 `apps/cli/web.cordis.yml` 是 **patch 列表**，不是配置树：各自声明少数取值因 surface 而异的配置项，并 insert 自己的配置项。启动器只 include base 一次，并把每个 overlay 作为**同一** include 层级上的平级 patch 列表应用——因为 include patch 不会跨越 include 边界，把 overlay 堆叠成嵌套 include 会使其静默地无法触达 base 配置项。
+
+优先级即列表顺序，逐配置项后写者胜：base，然后是 surface overlay，接着是 `--config` overlay 或个人 `~/.dsh/config.yaml`，最后是启动器自身的 flag 与 profile patch。
+
+`--config <path>` 现在应用一个 overlay 来**取代**个人 overlay，因此 demo 或测试用的树绝不会继承用户的 provider 与 model。`--config-replace <path>` 则把某个文件作为整棵树启动，同时绕过 base、surface overlay 与个人 overlay；这正是旧 `--config` 的行为，所以像 `examples/web-cordis` 这样的树改用了新 flag。两个 flag 都会在 `/resume` 的 execve 交接中保留，否则 resume 会静默更换 agent。
+
+patch 会整体替换目标配置项的 `config` 而不合并，这决定了拆分方式：取值因 surface 而异的配置项住在 overlay 中，绝不住在 base 里，从而没有任何配置项会被三层同时 patch。因此会话身份根本不能经由配置键传递——它迁移到了 `dsh-agent-loop` 的 `CONFIGURED_AGENT_IDENTITIES_KEY`，如[启动器持有身份的 note](../architecture/2026-07-28-launcher-owned-resume-identity.md) 现在所记录。
+
+`examples/tui-agent`、`examples/cordis-agent` 与 `packages/examples/tui-demo` 均被删除。TUI 测试迁往 `apps/cli/tests/`，cordis 工具集的 e2e 迁入 `packages/cordis/tool-cordis/tests/`，而 `examples/code-mode` 作为一个名副其实的示例保留下来：一个 patch `tools.mode` 并 insert code runtime 的 overlay。
+
+## 备选方案
+
+**保留两棵平铺且重复的树。** 拒绝：43 个配置项维护两份正是缺陷本身，而用一个门禁断言二者保持一致只会固化重复，而非消除它。
+
+**把 overlay 嵌套成 include（`code-mode` → `tui` → `base`）。** 在对 Loader 实测后拒绝：patch 不会跨越 include 边界，因此外层文件的 patch 只会伴随一条告警被丢弃。三层链条使 `tools` 无法被 patch，而位于一层 include 之后的 base，会让每个个人 patch 都变成静默的空操作。
+
+**把所有配置项的并集放进 base，由各 overlay 禁用自己不需要的部分。** 拒绝：base 将不再意味着「共享」，而每个 surface 都要携带仅为将其关闭而存在的配置项。
+
+**把因 surface 而异的配置项留在 base 中，由 overlay 去 patch。** 仅对必须同时存在于两棵树中的那五个配置项采用，因为 patch 无法创建配置项。它们在 base 中的条目携带插件名与两个 surface 共享的配置，其余部分由各 overlay 声明。
+
+## 影响
+
+指名 `@deepseek-ai/dsh-tui-demo`、或 patch `tui-agent` 配置项的 overlay 与 `--config` 树将不再可解析。overlay 现在要 patch 拥有对应键的那一行：模型路由在 `agent-loop`，人设在 `system-prompt`，呈现设置在 `tui`。
+
+若某个 patch 的 `id` 不匹配任何配置项，Loader 仍只告警而不报错。这是有意为之：同一份个人 overlay 会跨 surface 共用，而 `insert` 配置项按设计本就不匹配任何目标，因此仅在 `web` 下存在的配置项不能让 TUI 启动失败。
+
+`dsh web` 新增 `--config`，作为一份额外 overlay 传入 `AppCLIEntry`。`AppCLIEntry` 在为自身 patch 合并恢复配置项默认值时会同时读取 base 与其 surface overlay，因为 flag 覆盖必须保留同一配置项上 overlay 的其他字段。
+
+## 验证
+
+组合的正确性通过用真实 Loader 启动每棵树并检查已就绪的条目来核对，而不是靠阅读 YAML：TUI 就绪 55 个条目、web 就绪 75 个，两者都没有未加载或未就绪的配置项，且 web 的 `httpServer` 已启动。三层叠加的情形（`base` + `tui` + `code-mode`）确认 `tools.mode` 越过 TUI overlay 的 `native` 达到了 `code`。
+
+全部八个终端快照场景在迁移后逐字节重放一致，14 个用例的 PTY 冒烟测试全部通过，其中两个用例断言个人 overlay 能触达一个 **insert 进来的**配置项——这正是 vendored `plugin-include` 修复所启用的行为（[`vendor/README.md`](../../../../vendor/README.md) 本地修改第 8 条，由 `packages/ui/app-boot/tests/config-reload.spec.ts` 覆盖）。
+
+平铺过程暴露出三处潜伏缺陷，均在此一并修复：TUI 曾在构造时一次性捕获可选的 `sessionQuery` 服务，因此在挂载竞争中胜出时会永久禁用 `/resume`；交付的会话存储根目录曾静默退回项目本地的 `./.sessions`；`--config-replace` 曾在 resume 交接中被丢弃。
@@ -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/testing/2026-07-18-tui-terminal-state-snapshots.md
-2026-07-18-tui-terminal-state-snapshots.md: 18c79bc2d0dabf4d78887354f30a2cdc083899e1
-2026-07-18-tui-terminal-state-snapshots.zh.md: d1d4a6ca859e94a153e0bf645a17f03c0dac234b
+2026-07-18-tui-terminal-state-snapshots.md: b8e6f77d96fbd4d077d55fefa3652813c737a37b
+2026-07-18-tui-terminal-state-snapshots.zh.md: 1b2f6b58e53d9ccd5f0935dab9e9812d2bfe3eb4
@@ -21,7 +21,7 @@ TUI coverage has four complementary layers:
 3. `examples/tui-agent/tests/tui.snapshot.ts` replays committed JSONL session logs through the production agent loop and real tools, then compares the resulting semantic terminal state.
 4. `examples/tui-agent/tests/tui-keyless-smoke.e2e.ts` boots the real Loader composition in a PTY, drives a scripted conversation through streaming and `ask_user_question`, and verifies startup, input, exit, failure reporting, and terminal restoration.

-The runnable TUI has its own `examples/tui-agent` leaf beside the Headless and ACP leaves. It owns the interactive coding backends and tools directly and loads `@deepseek-ai/dsh-tui-demo`; TUI snapshots and PTY tests live with that leaf. The [redundant-agent removal](../simplification/2026-07-20-remove-stdio-and-echo-agents.md) owns this consolidation.
+The runnable TUI is the shipped `apps/cli` composition: the shared `base.cordis.yml` plus the `tui.cordis.yml` overlay, which owns the interactive coding backends, tools, and front door. TUI snapshots and PTY tests live in `apps/cli/tests/`. The [redundant-agent removal](../simplification/2026-07-20-remove-stdio-and-echo-agents.md) owns this consolidation.

 ### Recorded-session replay

@@ -21,7 +21,7 @@ TUI 覆盖分为四个互补层次：
 3. `examples/tui-agent/tests/tui.snapshot.ts` 通过生产 agent loop 和真实工具回放已提交的 JSONL 会话日志，再比较生成的语义终端状态。
 4. `examples/tui-agent/tests/tui-keyless-smoke.e2e.ts` 在 PTY 中启动真实 Loader 组合，驱动一段经过流式输出和 `ask_user_question` 的脚本化会话，并验证启动、输入、退出、失败报告和终端恢复。

-可运行 TUI 在 `examples/tui-agent` 中拥有独立叶节点，与 Headless 和 ACP 叶节点并列。它直接拥有交互式 coding 后端与工具，并加载 `@deepseek-ai/dsh-tui-demo`；TUI 快照和 PTY 测试也归属这个叶节点。[移除重复 agent 的决策](../simplification/2026-07-20-remove-stdio-and-echo-agents.md)负责此次整合。
+可运行 TUI 就是交付的 `apps/cli` 组合：共享的 `base.cordis.yml` 加 `tui.cordis.yml` overlay，后者拥有交互式 coding 后端、工具与前端入口。TUI 快照和 PTY 测试位于 `apps/cli/tests/`。[移除重复 agent 的决策](../simplification/2026-07-20-remove-stdio-and-echo-agents.md)负责此次整合。

 ### 已录制会话回放

@@ -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/testing/2026-07-24-web-gui-browser-e2e-lane.md
-2026-07-24-web-gui-browser-e2e-lane.md: ce59dcce270d548c91e3719eee8e9c83aea0c154
-2026-07-24-web-gui-browser-e2e-lane.zh.md: bad3dd15ed7b98cc17340666a6c1094d0de057b1
+2026-07-24-web-gui-browser-e2e-lane.md: 37e2bccddb3725073ebb38377c2cd7464b418012
+2026-07-24-web-gui-browser-e2e-lane.zh.md: f2bbdbb028a3e35831298fea4d5a0f3dec410b82
@@ -16,7 +16,7 @@ The web GUI ships as a real assembled chain — chromium page → client plugin

 A plain shared-fixture module (the [testing-policy sanctioned shape](../../../../docs/testing.md)), not a package: the gate-worthy logic — replay derivation, session parsing, log scrubbing, persistence — lives in the gated packages `dsh-llm-replay`, `dsh-acp-snapshot`, and `dsh-session-persistence-jsonl`; what remains is boot wiring and browser glue, and chromium-driving code cannot hold per-file 100% coverage on the browserless coverage runners.

-`launchWebScaffold()` boots the real web composition from the shipped `apps/cli/cordis.yml` through the vendored Loader's include mechanism — the same tree and mechanism `AppCLIEntry` drives for `dsh web`. Divergences ride include patches over that tree, the ACP `cordis.snapshot.yml` pattern expressed in-process: temp `persistenceRoot`, `workspace-context` disabled (recorded fixtures must not embed this repo's AGENTS.md), `session-title-llm` disabled (its fire-and-forget title call would race the loop for the session's replay cursor), the webserver row pinned to port 0 with the built dist, and in keyless modes `llm-deepseek` disabled. A patch id that stops matching a row fails the boot sweep loudly instead of drifting. The boot runs `chdir`'d to the temp workspace so the api-gateway's `process.cwd()` session default, tool cwds, and fixtures agree; the `dsh web` bin's own glue (argv, profile json, AppCLIEntry) stays held by the keyless CLI smokes in `smoke-real.e2e.ts`. Setup rollback and ordinary close both dispose the Cordis tree before removing the two owned temp roots, attempt every cleanup independently, and report cleanup failures without masking the setup failure.
+`launchWebScaffold()` boots the real web composition from the shipped `apps/cli/base.cordis.yml` plus its surface overlay through the vendored Loader's include mechanism — the same tree and mechanism `AppCLIEntry` drives for `dsh web`. Divergences ride include patches over that tree, the ACP `cordis.snapshot.yml` pattern expressed in-process: temp `persistenceRoot`, `workspace-context` disabled (recorded fixtures must not embed this repo's AGENTS.md), `session-title-llm` disabled (its fire-and-forget title call would race the loop for the session's replay cursor), the webserver row pinned to port 0 with the built dist, and in keyless modes `llm-deepseek` disabled. A patch id that stops matching a row fails the boot sweep loudly instead of drifting. The boot runs `chdir`'d to the temp workspace so the api-gateway's `process.cwd()` session default, tool cwds, and fixtures agree; the `dsh web` bin's own glue (argv, profile json, AppCLIEntry) stays held by the keyless CLI smokes in `smoke-real.e2e.ts`. Setup rollback and ordinary close both dispose the Cordis tree before removing the two owned temp roots, attempt every cleanup independently, and report cleanup failures without masking the setup failure.

 Keyless model displacement is the disabled adapter row plus `installLlmReplay` filling the open seam on the settled root ctx in providers-catalog mode — never catch-all: with the adapter row disabled no adapter exists, so catch-all would leave `resolveModelInfo` unroutable and `compact-basic`'s post-step pressure check would warn every step instead of being provably inert (the published 128k `contextWindow` keeps it inert for small fixtures). The direct install rather than an inserted replay plugin row is deliberate: it returns the `ReplayHandle` the teardown consumption check needs. A scenario with no fixture leaves the seam empty, so a stray stream fails loud with NO_ADAPTER.

@@ -66,7 +66,7 @@ Surveyed AI-chat/agent web UIs and mocking layers (LibreChat, vercel/ai-chatbot

 **A committed normalized-session-log golden as a second expected surface.** Rejected: the log surface is pinned by the ACP/headless/TUI suites through the same loop and persistence; here it would double refresh cost and re-test lower tiers. Inline world-state assertions on root-context events keep the world-verification duty.

-**Spawning the `dsh web` bin with a `DSH_SNAPSHOT` replay branch.** Rejected: it needs a test-only replay branch plus environment plumbing in the shipped CLI. The in-process scaffold already loads the same `apps/cli/cordis.yml`; only argv, profile JSON, and `AppCLIEntry` glue remain outside it, and the keyless CLI smokes cover those paths.
+**Spawning the `dsh web` bin with a `DSH_SNAPSHOT` replay branch.** Rejected: it needs a test-only replay branch plus environment plumbing in the shipped CLI. The in-process scaffold already loads the same `apps/cli/base.cordis.yml` plus its surface overlay; only argv, profile JSON, and `AppCLIEntry` glue remain outside it, and the keyless CLI smokes cover those paths.

 **Changing the wire protocol for testability.** Rejected: the contract already has a first-class keyless isomorphic seam (`InProcessApiClient(toFetchHandler(api))`), the per-event unbatched SSE is exactly what makes replay observable in a browser, and testing a wire we no longer ship would invert the tier's purpose.

@@ -16,7 +16,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu

 一个普通的共享 fixture 模块（[测试政策认可的形态](../../../../docs/testing.md)），不是包：值得门禁把守的逻辑——回放推导、会话解析、日志脱敏、持久化——都在已受门禁的包 `dsh-llm-replay`、`dsh-acp-snapshot`、`dsh-session-persistence-jsonl` 中；剩下的只是启动接线和浏览器胶水，而驱动 chromium 的源码在无浏览器的覆盖率 runner 上无法诚实保持逐文件 100% 覆盖率。

-`launchWebScaffold()` 通过 vendored Loader 的 include 机制，从交付的 `apps/cli/cordis.yml` 启动真实 web 组合——与 `AppCLIEntry` 为 `dsh web` 驱动的是同一棵树、同一套机制。差异全部经 include patch 覆盖在这棵树上，即 ACP `cordis.snapshot.yml` 模式的进程内表达：临时 `persistenceRoot`；禁用 `workspace-context`（录制的 fixture 不得嵌入本仓库的 AGENTS.md）；禁用 `session-title-llm`（其发后不管的标题调用会与循环争抢会话的回放游标）；webserver 行钉到端口 0 加已构建 dist；无密钥模式下禁用 `llm-deepseek`。patch 的 id 一旦不再匹配任何行，boot 扫描会大声失败而不是漂移。boot 在临时工作区 `chdir` 下运行，使 api-gateway 的 `process.cwd()` 会话默认值、工具 cwd 与 fixture 一致；`dsh web` bin 自身的胶水（argv、profile json、AppCLIEntry）仍由 `smoke-real.e2e.ts` 中的无密钥 CLI 冒烟把守。初始化回滚和正常关闭都会先对 Cordis 树执行 dispose（资源释放），再删除 scaffold 持有的两个临时根目录；每项清理都会独立尝试，并会报告清理失败而不掩盖初始化失败。
+`launchWebScaffold()` 通过 vendored Loader 的 include 机制，从交付的 `apps/cli/base.cordis.yml` plus its surface overlay 启动真实 web 组合——与 `AppCLIEntry` 为 `dsh web` 驱动的是同一棵树、同一套机制。差异全部经 include patch 覆盖在这棵树上，即 ACP `cordis.snapshot.yml` 模式的进程内表达：临时 `persistenceRoot`；禁用 `workspace-context`（录制的 fixture 不得嵌入本仓库的 AGENTS.md）；禁用 `session-title-llm`（其发后不管的标题调用会与循环争抢会话的回放游标）；webserver 行钉到端口 0 加已构建 dist；无密钥模式下禁用 `llm-deepseek`。patch 的 id 一旦不再匹配任何行，boot 扫描会大声失败而不是漂移。boot 在临时工作区 `chdir` 下运行，使 api-gateway 的 `process.cwd()` 会话默认值、工具 cwd 与 fixture 一致；`dsh web` bin 自身的胶水（argv、profile json、AppCLIEntry）仍由 `smoke-real.e2e.ts` 中的无密钥 CLI 冒烟把守。初始化回滚和正常关闭都会先对 Cordis 树执行 dispose（资源释放），再删除 scaffold 持有的两个临时根目录；每项清理都会独立尝试，并会报告清理失败而不掩盖初始化失败。

 无密钥的模型替换 = 禁用适配器行的 patch 加 `installLlmReplay` 在停稳的根 ctx 上以提供方目录（providers-catalog）模式填充开放的 seam——绝不用 catch-all：适配器行被禁用后不存在任何适配器，catch-all 会让 `resolveModelInfo` 无路由可走，`compact-basic` 的步后压力检查将步步告警，而不是被可证明地闲置（发布的 128k `contextWindow` 使该路径对小 fixture 保持闲置）。选择直接安装而非插入回放插件行是刻意的：直接安装返回收尾消费检查所需的 `ReplayHandle`。没有 fixture 的场景让 seam 保持空置，任何离群的流式调用都会以 NO_ADAPTER 大声失败。

@@ -66,7 +66,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu

 **第二份提交的规范化会话日志预期输出。** 已否决：日志表面已由 ACP/headless/TUI 套件经同一循环与持久化钉住；在此只会翻倍刷新成本并重复测试下层。内联在根上下文事件上的世界状态断言保住了验证世界的义务。

-**以 `DSH_SNAPSHOT` 回放分支拉起 `dsh web` bin。** 已否决：它需要在交付的 CLI 中增加测试专用回放分支和环境变量管道。进程内 scaffold 已加载同一份 `apps/cli/cordis.yml`；只剩 argv、profile JSON 和 `AppCLIEntry` 胶水不在其覆盖范围内，而这些路径已由无密钥 CLI 冒烟覆盖。
+**以 `DSH_SNAPSHOT` 回放分支拉起 `dsh web` bin。** 已否决：它需要在交付的 CLI 中增加测试专用回放分支和环境变量管道。进程内 scaffold 已加载同一份 `apps/cli/base.cordis.yml` plus its surface overlay；只剩 argv、profile JSON 和 `AppCLIEntry` 胶水不在其覆盖范围内，而这些路径已由无密钥 CLI 冒烟覆盖。

 **为可测试性改 wire 协议。** 已否决：契约已有第一等的无密钥同构 seam（`InProcessApiClient(toFetchHandler(api))`），逐事件不合批的 SSE 恰是回放在浏览器中可观测的原因，测试一条不再交付的 wire 会颠倒该层的存在意义。

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write apps/cli/README.md
-README.md: 93c36d18abd06bbd7a80c918f520b92489180395
-README.zh.md: 85f4624a592eaf2ae44dc31fb4e18fb5657e62fd
+README.md: 8b52c8bd5c5b7b75855e2bfbe28d061c5f3742b0
+README.zh.md: 0df55c52f723e901b090673b8fea663f38cbeaaf
@@ -8,7 +8,7 @@ Argv is parsed once through a [Commander](https://github.com/tj/commander.js) ad

 The TUI surface:

- boots the shipped default config (`examples/tui-agent/cordis.yml`), or the tree named by `--config <path>` (the demo/test escape for booting an alternate example tree), through [`dsh-app-boot`](../../packages/ui/app-boot/README.md);
+- boots the shipped default config (`apps/cli/base.cordis.yml`), or the tree named by `--config <path>` (the demo/test escape for booting an alternate example tree), through [`dsh-app-boot`](../../packages/ui/app-boot/README.md);
 - resumes a persisted session with `dsh --resume <session-id>` and, when the Node host exposes `process.execve`, supplies the TUI's in-place handoff host: after selector preflight and current-session flush, the host disposes the app and replaces the process with a normalized resume invocation; runtimes without process replacement leave the session running and say so. This CLI owns session identity and the exit line rather than the config: it mints or selects the `main` session id and provides it, plus the exact command that reproduces this invocation, on the boot context ([`MAIN_SESSION_ID_KEY`](../../packages/ui/tui/README.md) and `TUI_GOODBYE_MESSAGE_KEY`). No `cordis.yml` key can drop resume, and a missing or unreadable id fails loud instead of creating a fresh session;
 - treats the **invoking directory** as the workspace — sessions, relative paths, and workspace instructions resolve from the cwd (`dsh meta` is the sole exception, below);
 - tells the agent where its own source lives: after boot it adds a prompt section naming this harness checkout, resolved from the launcher's real path so it holds under a PATH symlink and an arbitrary cwd, so the self-referential `cordis` toolset can read and modify it;
@@ -8,7 +8,7 @@ Argv 只会通过 [Commander](https://github.com/tj/commander.js) 适配器（[`

 TUI 界面：

- 启动已交付的默认配置（`examples/tui-agent/cordis.yml`），或由 `--config <path>` 指定的树（演示／测试用于启动其他示例树的逃生口），并通过 [`dsh-app-boot`](../../packages/ui/app-boot/README.md) 完成启动；
+- 启动已交付的默认配置（`apps/cli/base.cordis.yml`），或由 `--config <path>` 指定的树（演示／测试用于启动其他示例树的逃生口），并通过 [`dsh-app-boot`](../../packages/ui/app-boot/README.md) 完成启动；
 - 使用 `dsh --resume <session-id>` 恢复已持久化会话。当 Node 宿主公开 `process.execve` 时，还会提供 TUI 的原地移交宿主：选择器预检并刷新当前会话后，宿主会释放应用，并以规范化的恢复调用替换进程；不支持进程替换的运行时会让会话继续运行并给出提示。会话身份与退出行由本 CLI 拥有，而非由配置指定：它创建或选定 `main` 会话 id，并把该 id 以及可复现本次调用的确切命令一起提供到启动上下文（[`MAIN_SESSION_ID_KEY`](../../packages/ui/tui/README.md) 与 `TUI_GOODBYE_MESSAGE_KEY`）。任何 `cordis.yml` 键都无法移除恢复能力；缺失或无法读取的 id 会明确报错，而不会创建新会话；
 - 将 **调用目录** 视为 workspace：会话、相对路径和 workspace 指令都从 cwd 解析（`dsh meta` 是唯一例外，见下文）；
 - 告知 agent 自身源码所在位置：启动后添加一个命名此 harness checkout 的提示词段。该路径从启动器的真实路径解析，因此在 PATH 符号链接和任意 cwd 下仍然有效，使自指的 `cordis` 工具集可以读取并修改它；
@@ -0,0 +1,210 @@
+# The shared `dsh` core: every row both the TUI (`tui.cordis.yml`) and the web
+# surface (`web.cordis.yml`) mount identically. Neither surface includes the
+# other — each is a patch list applied over THIS file at one include level, so a
+# surface overlay, a `--config` overlay, and the personal `~/.dsh/config.yaml`
+# all address these rows by id. Patch lists stack in that order, last write
+# winning per row.
+#
+# A patch replaces the targeted row's whole `config` rather than merging into
+# it, so a row whose value differs per surface does NOT live here: it belongs to
+# each overlay, keeping any single row down to one overlay layer plus the user's.
+# That is why `agent-loop`, `system-prompt`, `tools`, `fs-local`, and
+# `llm-deepseek` thinking defaults are absent below.
+#
+# Row order carries no load semantics (activation is service-availability
+# driven); the grouping is for readers.
+
+- id: timer
+  name: '@cordisjs/plugin-timer'
+
+- id: llm
+  name: '@deepseek-ai/dsh-llm'
+
+- id: session
+  name: '@deepseek-ai/dsh-session'
+
+- id: session-title
+  name: '@deepseek-ai/dsh-session-title'
+  config:
+    fallbackMaxWords: 5
+    fallbackMaxBytes: 40
+    maxTitleBytes: 80
+
+- id: session-title-llm
+  name: '@deepseek-ai/dsh-session-title-first-message-llm'
+  config:
+    targetWords: 5
+    targetCjkCharacters: 10
+    maxInputBytes: 4096
+    maxOutputTokens: 64
+    timeoutMs: 60000
+
+- id: user-interaction
+  name: '@deepseek-ai/dsh-user-interaction'
+
+- id: agent
+  name: '@deepseek-ai/dsh-agent'
+
+- id: tasks
+  name: '@deepseek-ai/dsh-tasks-local'
+
+- id: llm-retry
+  name: '@deepseek-ai/dsh-llm-retry'
+
+# The session store root is the launcher's policy, not a plugin's: `dsh` shares
+# one store under the Harness home across every cwd, so `/resume` and
+# `dsh ps` span workspaces. Without a launcher the project-local fallback keeps
+# an embedder's sessions beside its project.
+- id: session-persistence-jsonl
+  name: '@deepseek-ai/dsh-session-persistence-jsonl'
+  config:
+    root: !!js launcherSessionsRoot ?? './.sessions'
+
+- id: subprocess
+  name: '@deepseek-ai/dsh-subprocess-local'
+
+- id: bash-local
+  name: '@deepseek-ai/dsh-bash-local'
+  config:
+    timeoutMs: 60000
+
+- id: tool-bash
+  name: '@deepseek-ai/dsh-tool-bash'
+
+- id: tool-tasks
+  name: '@deepseek-ai/dsh-tool-tasks'
+
+- id: fs-policy
+  name: '@deepseek-ai/dsh-fs-policy'
+
+- id: tool-fs
+  name: '@deepseek-ai/dsh-tool-fs'
+
+- id: tool-fs-search
+  name: '@deepseek-ai/dsh-tool-fs-search'
+
+- id: workspace-context
+  name: '@deepseek-ai/dsh-workspace-context'
+  config:
+    maxBytes: 65536
+
+- id: skill
+  name: '@deepseek-ai/dsh-skill'
+
+- id: skill-local
+  name: '@deepseek-ai/dsh-skill-local'
+
+- id: tool-skill
+  name: '@deepseek-ai/dsh-tool-skill'
+
+- id: commands
+  name: '@deepseek-ai/dsh-commands'
+
+- id: goal
+  name: '@deepseek-ai/dsh-goal'
+
+- id: goal-session
+  name: '@deepseek-ai/dsh-goal-session'
+
+- id: command-goal
+  name: '@deepseek-ai/dsh-command-goal'
+
+- id: plan-mode
+  name: '@deepseek-ai/dsh-plan-mode'
+  config:
+    section: |
+          You are in plan mode. Stay in plan mode until exit_plan_mode succeeds or the user switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
+
+          Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
+
+          The tool catalog stays the same across modes for request-cache stability. These plan-mode rules override any later tool description or guidance that suggests using mutation tools; those tools remain listed only to keep the request shape stable. Do not use todo_write to track this planning phase: it tracks implementation after an approved plan, while the plan itself belongs in exit_plan_mode.
+
+          Resolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.
+
+          Make the plan decision-complete: state the goal and success criteria; group implementation changes by subsystem; identify public API, schema, and data-flow changes; cover edge cases, failure modes, tests, acceptance criteria, and explicit assumptions. Keep it concise enough to review but detailed enough that another engineer can implement it without making design decisions.
+
+          When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
+
+- id: token-meter
+  name: '@deepseek-ai/dsh-token-meter'
+
+- id: compact-basic
+  name: '@deepseek-ai/dsh-compact-basic'
+
+- id: subagent
+  name: '@deepseek-ai/dsh-subagent'
+
+- id: subagent-spawn
+  name: '@deepseek-ai/dsh-subagent-spawn'
+  config:
+    providerName: spawn
+
+- id: subagent-fork
+  name: '@deepseek-ai/dsh-subagent-fork'
+  config:
+    providerName: fork
+
+- id: tool-subagent
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: spawn
+    toolName: subagent
+
+- id: tool-subagent-fork
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: fork
+    toolName: subagent_fork
+
+- id: workflow-workerthread
+  name: '@deepseek-ai/dsh-workflow-workerthread'
+  config:
+    provider: spawn
+
+- id: tool-workflow
+  name: '@deepseek-ai/dsh-tool-workflow'
+
+- id: timeout-policy
+  name: '@deepseek-ai/dsh-timeout-policy'
+
+- id: spill-local
+  name: '@deepseek-ai/dsh-spill-local'
+
+- id: spill-policy
+  name: '@deepseek-ai/dsh-spill-policy'
+  config:
+    maxInlineBytes: 50000
+
+# ── rows every surface mounts, whose values each overlay states ──────────────
+
+# The tool registry. Presentation mode is a surface choice, so each overlay
+# states it; omitting it here keeps the schema default (native).
+- id: tools
+  name: '@deepseek-ai/dsh-tools'
+
+# The deployment persona is a surface choice; plan-mode and tool plugins own
+# their own prompt sections.
+- id: system-prompt
+  name: '@deepseek-ai/dsh-system-prompt'
+  config:
+    persona: ''
+
+# Agents created at startup. The TUI pre-creates `main`; the web surface creates
+# sessions on client request, so its overlay keeps this empty.
+- id: agent-loop
+  name: '@deepseek-ai/dsh-agent-loop'
+  config:
+    agents: []
+
+# The filesystem provider. `cwd` defaults to the package's `process.cwd()`; the
+# TUI states it explicitly because that value is also the session workspace.
+- id: fs-local
+  name: '@deepseek-ai/dsh-fs-local'
+
+# The native DeepSeek adapter; reads the key/base-url the boot's layered .env
+# loading left in the environment. Thinking defaults are a surface choice.
+- id: llm-deepseek
+  name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    baseURL: !!js process.env.DEEPSEEK_BASE_URL
@@ -1,38 +1,67 @@
 <!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
     Run `pnpm run gen-doc-graphs` to regenerate. -->

-# TUI Agent App Composition
+# dsh TUI Composition

 The TUI agent combines the real DeepSeek adapter, coding tools, compaction, subagents, and workflows with the full-screen terminal app package.

 ```mermaid
 flowchart LR
-  cfg["examples/tui-agent<br/>cordis.yml"]
-  plugin_tui_hmr["hmr<br/>@cordisjs/plugin-hmr"]
-  cfg --> plugin_tui_hmr
-  plugin_tui_llm_deepseek["llm-deepseek<br/>@deepseek-ai/dsh-llm-deepseek"]
-  cfg --> plugin_tui_llm_deepseek
-  plugin_tui_llm_pi_ai["llm-pi-ai<br/>@deepseek-ai/dsh-llm-pi-ai"]
-  cfg --> plugin_tui_llm_pi_ai
-  plugin_tui_subprocess["subprocess<br/>@deepseek-ai/dsh-subprocess-local"]
-  cfg --> plugin_tui_subprocess
-  plugin_tui_bash["bash<br/>@deepseek-ai/dsh-bash-local"]
-  cfg --> plugin_tui_bash
-  plugin_tui_tui_agent["tui-agent<br/>@deepseek-ai/dsh-tui-demo"]
-  cfg --> plugin_tui_tui_agent
-  plugin_tui_tui_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-spine-demo"]
-  plugin_tui_tui_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"]
-  plugin_tui_tui_agent --> frontdoor_tui["@deepseek-ai/dsh-tui<br/>pre-created main agent"]
-  bundle_agent_core --> spine_llm["ctx.llm"]
-  bundle_agent_core --> spine_sessions["ctx.sessions"]
-  bundle_agent_core --> spine_tools["ctx.tools + tool-bash"]
-  bundle_agent_core --> spine_loop["ctx.agents + ctx.agentLoop"]
+  cfg["apps/cli (dsh)<br/>cordis.yml"]
+  plugin_tui_timer["timer<br/>@cordisjs/plugin-timer"]
+  cfg --> plugin_tui_timer
+  plugin_tui_llm["llm<br/>@deepseek-ai/dsh-llm"]
+  cfg --> plugin_tui_llm
+  plugin_tui_session["session<br/>@deepseek-ai/dsh-session"]
+  cfg --> plugin_tui_session
+  plugin_tui_session_title["session-title<br/>@deepseek-ai/dsh-session-title"]
+  cfg --> plugin_tui_session_title
  plugin_tui_session_title_llm["session-title-llm<br/>@deepseek-ai/dsh-session-title-first-message-llm"]
  cfg --> plugin_tui_session_title_llm
+  plugin_tui_user_interaction["user-interaction<br/>@deepseek-ai/dsh-user-interaction"]
+  cfg --> plugin_tui_user_interaction
+  plugin_tui_agent["agent<br/>@deepseek-ai/dsh-agent"]
+  cfg --> plugin_tui_agent
+  plugin_tui_tasks["tasks<br/>@deepseek-ai/dsh-tasks-local"]
+  cfg --> plugin_tui_tasks
+  plugin_tui_llm_retry["llm-retry<br/>@deepseek-ai/dsh-llm-retry"]
+  cfg --> plugin_tui_llm_retry
+  plugin_tui_session_persistence_jsonl["session-persistence-jsonl<br/>@deepseek-ai/dsh-session-persistence-jsonl"]
+  cfg --> plugin_tui_session_persistence_jsonl
+  plugin_tui_subprocess["subprocess<br/>@deepseek-ai/dsh-subprocess-local"]
+  cfg --> plugin_tui_subprocess
+  plugin_tui_bash_local["bash-local<br/>@deepseek-ai/dsh-bash-local"]
+  cfg --> plugin_tui_bash_local
+  plugin_tui_tool_bash["tool-bash<br/>@deepseek-ai/dsh-tool-bash"]
+  cfg --> plugin_tui_tool_bash
+  plugin_tui_tool_tasks["tool-tasks<br/>@deepseek-ai/dsh-tool-tasks"]
+  cfg --> plugin_tui_tool_tasks
+  plugin_tui_fs_policy["fs-policy<br/>@deepseek-ai/dsh-fs-policy"]
+  cfg --> plugin_tui_fs_policy
+  plugin_tui_tool_fs["tool-fs<br/>@deepseek-ai/dsh-tool-fs"]
+  cfg --> plugin_tui_tool_fs
+  plugin_tui_tool_fs_search["tool-fs-search<br/>@deepseek-ai/dsh-tool-fs-search"]
+  cfg --> plugin_tui_tool_fs_search
+  plugin_tui_workspace_context["workspace-context<br/>@deepseek-ai/dsh-workspace-context"]
+  cfg --> plugin_tui_workspace_context
+  plugin_tui_skill["skill<br/>@deepseek-ai/dsh-skill"]
+  cfg --> plugin_tui_skill
+  plugin_tui_skill_local["skill-local<br/>@deepseek-ai/dsh-skill-local"]
+  cfg --> plugin_tui_skill_local
+  plugin_tui_tool_skill["tool-skill<br/>@deepseek-ai/dsh-tool-skill"]
+  cfg --> plugin_tui_tool_skill
+  plugin_tui_commands["commands<br/>@deepseek-ai/dsh-commands"]
+  cfg --> plugin_tui_commands
+  plugin_tui_goal["goal<br/>@deepseek-ai/dsh-goal"]
+  cfg --> plugin_tui_goal
+  plugin_tui_goal_session["goal-session<br/>@deepseek-ai/dsh-goal-session"]
+  cfg --> plugin_tui_goal_session
+  plugin_tui_command_goal["command-goal<br/>@deepseek-ai/dsh-command-goal"]
+  cfg --> plugin_tui_command_goal
+  plugin_tui_plan_mode["plan-mode<br/>@deepseek-ai/dsh-plan-mode"]
+  cfg --> plugin_tui_plan_mode
  plugin_tui_token_meter["token-meter<br/>@deepseek-ai/dsh-token-meter"]
  cfg --> plugin_tui_token_meter
-  plugin_tui_tool_result_prune["tool-result-prune<br/>@deepseek-ai/dsh-compact-tool-result-prune"]
-  cfg --> plugin_tui_tool_result_prune
  plugin_tui_compact_basic["compact-basic<br/>@deepseek-ai/dsh-compact-basic"]
  cfg --> plugin_tui_compact_basic
  plugin_tui_subagent["subagent<br/>@deepseek-ai/dsh-subagent"]
@@ -49,39 +78,53 @@ flowchart LR
  cfg --> plugin_tui_workflow_workerthread
  plugin_tui_tool_workflow["tool-workflow<br/>@deepseek-ai/dsh-tool-workflow"]
  cfg --> plugin_tui_tool_workflow
-  plugin_tui_tool_ralph["tool-ralph<br/>@deepseek-ai/dsh-tool-ralph"]
-  cfg --> plugin_tui_tool_ralph
-  plugin_tui_plan_mode["plan-mode<br/>@deepseek-ai/dsh-plan-mode"]
-  cfg --> plugin_tui_plan_mode
-  plugin_tui_fs_local["fs-local<br/>@deepseek-ai/dsh-fs-local"]
-  cfg --> plugin_tui_fs_local
-  plugin_tui_fs_policy["fs-policy<br/>@deepseek-ai/dsh-fs-policy"]
-  cfg --> plugin_tui_fs_policy
-  plugin_tui_tool_fs["tool-fs<br/>@deepseek-ai/dsh-tool-fs"]
-  cfg --> plugin_tui_tool_fs
-  plugin_tui_source_guard["source-guard<br/>@deepseek-ai/dsh-source-guard"]
-  cfg --> plugin_tui_source_guard
-  plugin_tui_tool_fs_search["tool-fs-search<br/>@deepseek-ai/dsh-tool-fs-search"]
-  cfg --> plugin_tui_tool_fs_search
  plugin_tui_timeout_policy["timeout-policy<br/>@deepseek-ai/dsh-timeout-policy"]
  cfg --> plugin_tui_timeout_policy
  plugin_tui_spill_local["spill-local<br/>@deepseek-ai/dsh-spill-local"]
  cfg --> plugin_tui_spill_local
  plugin_tui_spill_policy["spill-policy<br/>@deepseek-ai/dsh-spill-policy"]
  cfg --> plugin_tui_spill_policy
+  plugin_tui_tools["tools<br/>@deepseek-ai/dsh-tools"]
+  cfg --> plugin_tui_tools
+  plugin_tui_system_prompt["system-prompt<br/>@deepseek-ai/dsh-system-prompt"]
+  cfg --> plugin_tui_system_prompt
+  plugin_tui_agent_loop["agent-loop<br/>@deepseek-ai/dsh-agent-loop"]
+  cfg --> plugin_tui_agent_loop
+  plugin_tui_fs_local["fs-local<br/>@deepseek-ai/dsh-fs-local"]
+  cfg --> plugin_tui_fs_local
+  plugin_tui_llm_deepseek["llm-deepseek<br/>@deepseek-ai/dsh-llm-deepseek"]
+  cfg --> plugin_tui_llm_deepseek
 ```

 | Plugin id | Package / module |
 | --- | --- |
-| `hmr` | `@cordisjs/plugin-hmr` |
-| `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` |
-| `llm-pi-ai` | `@deepseek-ai/dsh-llm-pi-ai` |
-| `subprocess` | `@deepseek-ai/dsh-subprocess-local` |
-| `bash` | `@deepseek-ai/dsh-bash-local` |
-| `tui-agent` | `@deepseek-ai/dsh-tui-demo` |
+| `timer` | `@cordisjs/plugin-timer` |
+| `llm` | `@deepseek-ai/dsh-llm` |
+| `session` | `@deepseek-ai/dsh-session` |
+| `session-title` | `@deepseek-ai/dsh-session-title` |
 | `session-title-llm` | `@deepseek-ai/dsh-session-title-first-message-llm` |
+| `user-interaction` | `@deepseek-ai/dsh-user-interaction` |
+| `agent` | `@deepseek-ai/dsh-agent` |
+| `tasks` | `@deepseek-ai/dsh-tasks-local` |
+| `llm-retry` | `@deepseek-ai/dsh-llm-retry` |
+| `session-persistence-jsonl` | `@deepseek-ai/dsh-session-persistence-jsonl` |
+| `subprocess` | `@deepseek-ai/dsh-subprocess-local` |
+| `bash-local` | `@deepseek-ai/dsh-bash-local` |
+| `tool-bash` | `@deepseek-ai/dsh-tool-bash` |
+| `tool-tasks` | `@deepseek-ai/dsh-tool-tasks` |
+| `fs-policy` | `@deepseek-ai/dsh-fs-policy` |
+| `tool-fs` | `@deepseek-ai/dsh-tool-fs` |
+| `tool-fs-search` | `@deepseek-ai/dsh-tool-fs-search` |
+| `workspace-context` | `@deepseek-ai/dsh-workspace-context` |
+| `skill` | `@deepseek-ai/dsh-skill` |
+| `skill-local` | `@deepseek-ai/dsh-skill-local` |
+| `tool-skill` | `@deepseek-ai/dsh-tool-skill` |
+| `commands` | `@deepseek-ai/dsh-commands` |
+| `goal` | `@deepseek-ai/dsh-goal` |
+| `goal-session` | `@deepseek-ai/dsh-goal-session` |
+| `command-goal` | `@deepseek-ai/dsh-command-goal` |
+| `plan-mode` | `@deepseek-ai/dsh-plan-mode` |
 | `token-meter` | `@deepseek-ai/dsh-token-meter` |
-| `tool-result-prune` | `@deepseek-ai/dsh-compact-tool-result-prune` |
 | `compact-basic` | `@deepseek-ai/dsh-compact-basic` |
 | `subagent` | `@deepseek-ai/dsh-subagent` |
 | `subagent-spawn` | `@deepseek-ai/dsh-subagent-spawn` |
@@ -90,17 +133,15 @@ flowchart LR
 | `tool-subagent-fork` | `@deepseek-ai/dsh-tool-subagent` |
 | `workflow-workerthread` | `@deepseek-ai/dsh-workflow-workerthread` |
 | `tool-workflow` | `@deepseek-ai/dsh-tool-workflow` |
-| `tool-ralph` | `@deepseek-ai/dsh-tool-ralph` |
-| `plan-mode` | `@deepseek-ai/dsh-plan-mode` |
-| `fs-local` | `@deepseek-ai/dsh-fs-local` |
-| `fs-policy` | `@deepseek-ai/dsh-fs-policy` |
-| `tool-fs` | `@deepseek-ai/dsh-tool-fs` |
-| `source-guard` | `@deepseek-ai/dsh-source-guard` |
-| `tool-fs-search` | `@deepseek-ai/dsh-tool-fs-search` |
 | `timeout-policy` | `@deepseek-ai/dsh-timeout-policy` |
 | `spill-local` | `@deepseek-ai/dsh-spill-local` |
 | `spill-policy` | `@deepseek-ai/dsh-spill-policy` |
+| `tools` | `@deepseek-ai/dsh-tools` |
+| `system-prompt` | `@deepseek-ai/dsh-system-prompt` |
+| `agent-loop` | `@deepseek-ai/dsh-agent-loop` |
+| `fs-local` | `@deepseek-ai/dsh-fs-local` |
+| `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` |

-Source config: [`examples/tui-agent/cordis.yml`](cordis.yml).
+Source config: [`apps/cli/base.cordis.yml`](base.cordis.yml).

 Maintenance mode: hybrid: the leaf plugin list is parsed from its `cordis.yml`; app package expansion is curated from package source.
@@ -1,420 +0,0 @@
-# dsh web — the full web-shape composition: host runtime (layer 1), the
-# transport/service layer (layer 2), and the browser plugin roster (dshClient
-# rows the modules node half scans into window.__DSH_BOOT__). Row order
-# carries no load semantics (activation is service-availability driven); the
-# grouping below is for readers. `--dev` appends the dsh-client-hmr row in
-# code (AppCLIEntry) — prod and dev differ by exactly that one row.
-# AppCLIEntry patches this tree before boot: profile json + CLI flags +
-# distIndex land as config patches over the rows below (yaml = engineering
-# defaults, json = user config, user wins per field).
-
-# ── layer 1: runtime ────────────────────────────────────────────────────────
-
- id: timer
-  name: '@cordisjs/plugin-timer'
-
- id: llm
-  name: '@deepseek-ai/dsh-llm'
-
- id: session
-  name: '@deepseek-ai/dsh-session'
-
-# Projection registry: drives every registered domain unit over committed
-# session events and serves finished values (history-tail projections block +
-# session/projection frames). Without this row every domain's optional unit
-# injection stays silent — no block, no frames, no titles/todos on the web.
- id: session-projection
-  name: '@deepseek-ai/dsh-session-projection'
-
- id: session-title
-  name: '@deepseek-ai/dsh-session-title'
-  config:
-    fallbackMaxWords: 5
-    fallbackMaxBytes: 40
-    maxTitleBytes: 80
-
-# Model-made titles on the first-message cadence (the web sidebar renders
-# session/title). Same values as the TUI composition.
- id: session-title-llm
-  name: '@deepseek-ai/dsh-session-title-first-message-llm'
-  config:
-    targetWords: 5
-    targetCjkCharacters: 10
-    maxInputBytes: 4096
-    maxOutputTokens: 64
-    timeoutMs: 60000
-
- id: system-prompt
-  name: '@deepseek-ai/dsh-system-prompt'
-  config:
-    persona: ''
-
- id: tools
-  name: '@deepseek-ai/dsh-tools'
-  config:
-    # TEMPORARY workaround: DSH_TOOLS_MODE (native|code|both) opts a whole dsh
-    # process into Code Mode while per-session tool-mode selection is being
-    # designed; unset keeps the schema default (native). Remove the env seam
-    # once the web UI owns the choice per session.
-    mode: !!js process.env.DSH_TOOLS_MODE
-
-# Code Mode substrate for the row above. Mounted unconditionally because
-# Loader metadata is static (no conditional rows): a native-mode boot only
-# registers the service — a worker thread spawns per run_code execution.
- id: code-runtime
-  name: '@deepseek-ai/dsh-code-runtime-worker'
-
- id: user-interaction
-  name: '@deepseek-ai/dsh-user-interaction'
-
- id: agent
-  name: '@deepseek-ai/dsh-agent'
-
- id: tasks
-  name: '@deepseek-ai/dsh-tasks-local'
-
- id: agent-loop
-  name: '@deepseek-ai/dsh-agent-loop'
-  config:
-    agents: []
-
-# The native DeepSeek adapter; reads the key/base-url the boot's layered
-# .env loading (cwd then $DSH_HOME) left in the environment.
- id: llm-deepseek
-  name: '@deepseek-ai/dsh-llm-deepseek'
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-    baseURL: !!js process.env.DEEPSEEK_BASE_URL
-
-# Common pi-ai provider routes read credentials and endpoint overrides from the
-# boot's layered environment.
- id: llm-pi-ai
-  name: '@deepseek-ai/dsh-llm-pi-ai'
-  config:
-    providers:
-      - provider: openai
-        apiKey: !!js process.env.OPENAI_API_KEY
-        baseURL: !!js process.env.OPENAI_BASE_URL
-      - provider: anthropic
-        apiKey: !!js process.env.ANTHROPIC_API_KEY
-        baseURL: !!js process.env.ANTHROPIC_BASE_URL
-
-# Transient-failure recovery around the loop's model calls (same policy as
-# the TUI's agent-spine composition; defaults: 2 retries, 500ms→10s backoff).
- id: llm-retry
-  name: '@deepseek-ai/dsh-llm-retry'
-
-# Session store root. AppCLIEntry resolves the engineering default to a
-# global dir under the Harness home ($DSH_HOME, else ~/.dsh): sessions live
-# in one place across every cwd, not a project-local ./.sessions. The
-# persistenceRoot profile key (user config) still overrides this per field.
- id: session-persistence-jsonl
-  name: '@deepseek-ai/dsh-session-persistence-jsonl'
-  config:
-    root: './.sessions'
-
- id: storage
-  name: '@deepseek-ai/dsh-storage'
-
- id: storage-json
-  name: '@deepseek-ai/dsh-storage-json'
-  config:
-    root: './.storages'
-
- id: storage-domain
-  name: '@deepseek-ai/dsh-storage-domain'
-  config:
-    backend: json
-
- 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'
-
-# The sandboxed product path (the acp-agent composition): per-platform
-# runner provider, the shared policy home, the confined bash executor, and
-# the approval seam its escalation asks through. The web deployment default
-# is danger-full-access + never (same behavior as the former bash-local
-# rows); DSH_PERMISSION_MODE opts a process into a confined default, and
-# per-session switches ride the /permission command's knob events.
- id: sandbox
-  name: '@deepseek-ai/dsh-sandbox-local'
-
- id: sandbox-policy
-  name: '@deepseek-ai/dsh-sandbox-policy'
-  config:
-    mode: !!js process.env.DSH_PERMISSION_MODE ?? 'danger-full-access'
-    workspaceRoot: !!js process.cwd()
-
- id: bash-sandbox
-  name: '@deepseek-ai/dsh-bash-sandbox'
-
- id: approval
-  name: '@deepseek-ai/dsh-user-approval'
-  config:
-    policy: !!js "(process.env.DSH_PERMISSION_MODE ?? 'danger-full-access') === 'danger-full-access' ? 'never' : 'ask'"
-
-# Presets over the two knobs (requires the confining executor + approval):
-# the web permission chip's table, served through the permissions projection
-# and switched through /permission.
- id: permission
-  name: '@deepseek-ai/dsh-permission'
-  config:
-    presets:
-      read-only:
-        sandbox: read-only
-        approval: ask
-      workspace-write:
-        sandbox: workspace-write
-        approval: ask
-      danger-full-access:
-        sandbox: danger-full-access
-        approval: never
-
- id: tool-bash
-  name: '@deepseek-ai/dsh-tool-bash'
-
- id: tool-todo
-  name: '@deepseek-ai/dsh-tool-todo'
-
- id: tool-tasks
-  name: '@deepseek-ai/dsh-tool-tasks'
-
-# fs cwd stays the package default (process.cwd()) — the same value the
-# gateway injects into session.cwd, so paths and sessions agree. The
-# sandboxed backend rides the SAME policy as bash: write/edit fence by the
-# effective mode, so read/write/edit stay available under every mode.
- id: fs-sandbox
-  name: '@deepseek-ai/dsh-fs-sandbox'
-
- id: fs-policy
-  name: '@deepseek-ai/dsh-fs-policy'
-
- id: tool-fs
-  name: '@deepseek-ai/dsh-tool-fs'
-
- id: tool-fs-search
-  name: '@deepseek-ai/dsh-tool-fs-search'
-
- id: workspace-context
-  name: '@deepseek-ai/dsh-workspace-context'
-  config:
-    maxBytes: 65536
-
- id: skill
-  name: '@deepseek-ai/dsh-skill'
-
- id: skill-local
-  name: '@deepseek-ai/dsh-skill-local'
-
- id: tool-skill
-  name: '@deepseek-ai/dsh-tool-skill'
-
-# Host command registry: the single source of truth behind command.list /
-# command.execute; the web '/' menu is a pure projection of this registry.
- id: commands
-  name: '@deepseek-ai/dsh-commands'
-
-# Goal service + automatic same-session continuation + the /goal command.
-# The GoalService registers the 'goal' session projection unit; the web
-# GoalBar reads it through useProjection.
- id: goal
-  name: '@deepseek-ai/dsh-goal'
-
- id: goal-session
-  name: '@deepseek-ai/dsh-goal-session'
-
- id: command-goal
-  name: '@deepseek-ai/dsh-command-goal'
-
-# Plan mode registers /plan (the first real command on the web surface).
-# Section text mirrors examples/tui-agent/cordis.yml (the reference
-# deployment); plan-mode throws at load on an empty section.
- id: plan-mode
-  name: '@deepseek-ai/dsh-plan-mode'
-  config:
-    section: |
-          You are in plan mode. Stay in plan mode until exit_plan_mode succeeds or the user switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
-
-          Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
-
-          The tool catalog stays the same across modes for request-cache stability. These plan-mode rules override any later tool description or guidance that suggests using mutation tools; those tools remain listed only to keep the request shape stable. Do not use todo_write to track this planning phase: it tracks implementation after an approved plan, while the plan itself belongs in exit_plan_mode.
-
-          Resolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.
-
-          Make the plan decision-complete: state the goal and success criteria; group implementation changes by subsystem; identify public API, schema, and data-flow changes; cover edge cases, failure modes, tests, acceptance criteria, and explicit assumptions. Keep it concise enough to review but detailed enough that another engineer can implement it without making design decisions.
-
-          When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
-
-# token-meter rejects unknown config keys — keep this row bare.
- id: token-meter
-  name: '@deepseek-ai/dsh-token-meter'
-
- id: compact-basic
-  name: '@deepseek-ai/dsh-compact-basic'
-
- id: subagent
-  name: '@deepseek-ai/dsh-subagent'
-
- id: subagent-spawn
-  name: '@deepseek-ai/dsh-subagent-spawn'
-  config:
-    providerName: spawn
-
- id: subagent-fork
-  name: '@deepseek-ai/dsh-subagent-fork'
-  config:
-    providerName: fork
-
- id: tool-subagent
-  name: '@deepseek-ai/dsh-tool-subagent'
-  config:
-    provider: spawn
-    toolName: subagent
-
- id: tool-subagent-fork
-  name: '@deepseek-ai/dsh-tool-subagent'
-  config:
-    provider: fork
-    toolName: subagent_fork
-
- id: workflow-workerthread
-  name: '@deepseek-ai/dsh-workflow-workerthread'
-  config:
-    provider: spawn
-
- id: tool-workflow
-  name: '@deepseek-ai/dsh-tool-workflow'
-
- id: timeout-policy
-  name: '@deepseek-ai/dsh-timeout-policy'
-
- id: spill-local
-  name: '@deepseek-ai/dsh-spill-local'
-
-# Omitting maxInlineBytes makes the whole policy a silent no-op — always
-# state it explicitly.
- id: spill-policy
-  name: '@deepseek-ai/dsh-spill-policy'
-  config:
-    maxInlineBytes: 50000
-
-# The API gateway: the transport-agnostic dispatch face every client shape
-# shares. provider/model are the host default routing — the profile json's
-# mapping target (user config overrides these engineering defaults).
-# Directory-picking package, dual-face: the node half serves the gateway's
-# host.* picker RPCs, the browser half fills ui-workspace's directory-flow
-# slots — one row composes the whole interaction. Swap point: mount
-# '-native' instead for the host-display OS chooser.
- id: directory-picker
-  name: '@deepseek-ai/dsh-host-directory-picker-browse'
-
- id: api-gateway
-  name: '@deepseek-ai/dsh-host-apiproxy'
-  config:
-    provider: deepseek
-    model: deepseek-v4-flash
-
-# ── layer 2: transport/service ──────────────────────────────────────────────
-
-# Plain route-registration carrier. distIndex is an assembly fact, not user
-# config — AppCLIEntry resolves the frontend dist and patches it in; host and
-# port arrive as CLI-flag patches over these defaults.
- id: webserver
-  name: '@deepseek-ai/dsh-host-webserver'
-  config:
-    host: 127.0.0.1
-    port: 3080
-
-# ── browser plugin roster (dshClient rows; node halves are layer-2 hosts) ──
-
-# Dual-face: node half scans this very tree for dshClient rows, composes
-# window.__DSH_BOOT__, serves /plugins/<id>/client.js; browser half is the
-# module table the shell kernel constructs before cordis exists (§4.7 —
-# adopted as a plugin entry by the kernel, never fetched).
- id: modules
-  name: '@deepseek-ai/dsh-client-modules'
-
-# Owns both ends of the web transport: node half binds the gateway to the
-# webserver under /api; browser half is the fetch/SSE client.
- id: connection
-  name: '@deepseek-ai/dsh-client-connection'
-
- id: client-runtime
-  name: '@deepseek-ai/dsh-client-runtime'
-
- id: ui-theme
-  name: '@deepseek-ai/dsh-client-ui-theme'
-
- id: locale
-  name: '@deepseek-ai/dsh-client-locale'
-
- id: ui-layout
-  name: '@deepseek-ai/dsh-client-ui-layout'
-
- id: ui-sidebar
-  name: '@deepseek-ai/dsh-client-ui-sidebar'
-
- id: ui-settings
-  name: '@deepseek-ai/dsh-client-ui-settings'
-
- id: ui-settings-general
-  name: '@deepseek-ai/dsh-client-ui-settings-general'
-
- id: ui-models
-  name: '@deepseek-ai/dsh-client-ui-models'
-
- id: ui-conversation
-  name: '@deepseek-ai/dsh-client-ui-conversation'
-
-
- id: ui-workspace
-  name: '@deepseek-ai/dsh-client-ui-workspace'
-
-# Input triggers: the '/' | '@' pipeline (ui-slash), the command surface over
-# it (ui-command), and the two reference sources (ui-skill / ui-subagent).
- id: ui-slash
-  name: '@deepseek-ai/dsh-client-ui-slash'
-
- id: ui-command
-  name: '@deepseek-ai/dsh-client-ui-command'
-
- id: ui-skill
-  name: '@deepseek-ai/dsh-client-ui-skill'
-
- id: ui-subagent
-  name: '@deepseek-ai/dsh-client-ui-subagent'
-
-# Goal surface: GoalBar in the input dock over the goal session projection.
- id: ui-goal
-  name: '@deepseek-ai/dsh-client-ui-goal'
-
-# Model selection: the /model popupSelect + composer seat over session.models.
- id: ui-model
-  name: '@deepseek-ai/dsh-client-ui-model'
-
-# The /permission popup picker (hostBacked over the host /permission command).
- id: ui-permission
-  name: '@deepseek-ai/dsh-client-ui-permission'
-
-# Plan control: the composer plan seat over the plan projection + /plan channel.
- id: ui-plan
-  name: '@deepseek-ai/dsh-client-ui-plan'
-
- id: ui-question
-  name: '@deepseek-ai/dsh-client-ui-question'
-
- id: ui-trajectory
-  name: '@deepseek-ai/dsh-client-ui-trajectory'
@@ -110,6 +110,7 @@
    "js-yaml": "^4.2.0"
  },
  "devDependencies": {
-    "@types/js-yaml": "^4.0.9"
+    "@types/js-yaml": "^4.0.9",
+    "node-pty": "1.1.0"
  }
 }
@@ -17,7 +17,7 @@ import type { FiberState } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import Include, { type PatchOptions } from '@cordisjs/plugin-include'
 import yaml from 'js-yaml'
-import { assertEntriesLoaded, installFailLoud, loadEnv } from '@deepseek-ai/dsh-app-boot'
+import { assertEntriesLoaded, installFailLoud, loadEnv, loadOverlayPatches } from '@deepseek-ai/dsh-app-boot'
 import { resolveDshHome, resolveSessionsRoot } from '@deepseek-ai/dsh-paths'
 // Empty type import carries the httpServer Context merge for the port read below.
 import type {} from '@deepseek-ai/dsh-host-webserver'
@@ -100,8 +100,21 @@ const FIBER_PENDING = 0 as FiberState.PENDING

 /** Constructor facts for one dsh invocation over the shared composition (argv already parsed by the surface bin). */
 export interface AppCLIEntryOptions {
-  /** Absolute path of the shipped cordis.yml. */
+  /** Absolute path of the shared base config the Loader includes. */
  configPath: string
+  /**
+   * Absolute path of this surface's overlay: a patch list applied over
+   * {@link configPath} before this entry's own profile/flag patches. Its rows
+   * are also merge inputs, so a flag override preserves the overlay's other
+   * fields on the same row.
+   */
+  overlayPath: string
+  /**
+   * Optional extra overlay applied after {@link overlayPath} and before this
+   * entry's own profile/flag patches — the `--config` escape for demos and
+   * tests that need a row this surface does not ship.
+   */
+  extraOverlayPath?: string
  /** Whether to append the HMR row (the whole prod/dev difference; web surface only). */
  dev: boolean
  /** --host when explicitly passed; undefined keeps the yml engineering default. */
@@ -223,11 +236,22 @@ export class AppCLIEntry {
    ctx.baseUrl = pathToFileURL(join(resolve(this.options.configPath), '..')).href + '/'
    await ctx.plugin(Loader)
    ctx.loader.builtins.include = Include
+    // One include of the shared base with every overlay as a sibling patch
+    // list: patches never cross an include boundary, so nesting them would
+    // silently stop reaching base rows. The surface overlay applies first, then
+    // this entry's profile-json and CLI-flag patches, which therefore win.
+    const patches = [
+      ...loadOverlayPatches('dsh', this.options.overlayPath),
+      ...this.options.extraOverlayPath === undefined
+        ? []
+        : loadOverlayPatches('dsh', this.options.extraOverlayPath),
+      ...this.patches,
+    ]
    await ctx.loader.create({
      name: 'cordis:include',
      config: {
        path: pathToFileURL(resolve(this.options.configPath)).href,
-        ...this.patches.length > 0 ? { patches: this.patches } : {},
+        ...patches.length > 0 ? { patches } : {},
      },
    })
    if (this.options.dev) {
@@ -262,17 +286,39 @@ export class AppCLIEntry {
    }
  }

-  /** Bypass parse of the shipped yml (id → row) for patch-merge inputs; Loader still reads the file itself. */
+  /**
+   * Bypass parse of the base and this surface's overlay (id → row) for
+   * patch-merge inputs; the Loader still reads both files itself. The overlay
+   * wins per row, matching the order its patches are applied in, and its
+   * `insert` rows are indexed too because a flag may target one of them.
+   */
  private parseYmlRows(): Map<string, { config?: unknown }> {
-    const doc = yaml.load(readFileSync(this.options.configPath, 'utf8'), { schema: includeYamlSchema })
-    if (!Array.isArray(doc)) throw new Error(`dsh: ${this.options.configPath} is not a top-level entry list`)
    const rows = new Map<string, { config?: unknown }>()
-    for (const row of doc as { id?: string; config?: unknown }[]) {
-      if (typeof row.id === 'string') rows.set(row.id, row)
+    const files = [this.options.configPath, this.options.overlayPath]
+    if (this.options.extraOverlayPath !== undefined) files.push(this.options.extraOverlayPath)
+    for (const file of files) {
+      for (const row of this.parseRowList(file)) {
+        if (typeof row.id === 'string') rows.set(row.id, row)
+        for (const inserted of row.insert ?? []) {
+          if (typeof inserted.id === 'string') rows.set(inserted.id, inserted)
+        }
+      }
    }
    return rows
  }

+  /**
+   * Parse one entry or patch list, rejecting anything that is not a top-level
+   * array so a malformed file fails here rather than at row lookup.
+   * @param file - absolute path of the config or overlay file.
+   * @returns the parsed top-level entries.
+   */
+  private parseRowList(file: string): { id?: string; config?: unknown; insert?: { id?: string; config?: unknown }[] }[] {
+    const doc = yaml.load(readFileSync(file, 'utf8'), { schema: includeYamlSchema })
+    if (!Array.isArray(doc)) throw new Error(`dsh: ${file} is not a top-level entry list`)
+    return doc as { id?: string; config?: unknown; insert?: { id?: string; config?: unknown }[] }[]
+  }
+
  /** Profile json under cwd; read-only — never created here, absent = no user config. */
  private readProfile(): Record<string, unknown> {
    let raw: string
@@ -11,10 +11,15 @@

 import { Command, CommanderError } from 'commander'

-/** Interactive TUI: the default mode. `--config` swaps the tree; `--resume <id>` rehydrates a session. */
+/**
+ * Interactive TUI: the default mode. `--config` applies an overlay over the
+ * shipped composition in place of the personal one, `--config-replace` boots a
+ * file as the whole tree instead, and `--resume <id>` rehydrates a session.
+ */
 interface TuiInvocation {
  mode: 'tui'
  config?: string
+  configReplace?: string
  resume?: string
 }

@@ -69,6 +74,8 @@ interface ListSessionsInvocation {
 */
 interface WebInvocation {
  mode: 'web'
+  /** Overlay of loader patches applied over the shipped web composition. */
+  config?: string
  host?: string
  port?: number
  dev: boolean
@@ -88,6 +95,7 @@ export type DshInvocation =

 /** Raw web-subcommand options straight from Commander. */
 interface WebOptions {
+  config?: string
  host?: string
  port?: string
  dev?: boolean
@@ -104,6 +112,7 @@ interface WebOptions {
 function resolveWeb(options: WebOptions): WebInvocation {
  return {
    mode: 'web',
+    ...options.config !== undefined && { config: options.config },
    ...options.host !== undefined && { host: options.host },
    ...options.port !== undefined && { port: Number(options.port) },
    dev: options.dev === true,
@@ -140,15 +149,16 @@ Examples:
    // subcommand without a positional collision.
    .option('-p, --prompt <task>', 'answer this task without the interactive UI, then exit')
    .option('--resume <id>', 'continue a past session by id (list ids with `dsh ps`)')
-    .option('--config <path>', 'start with an alternate plugin configuration file')
-    .action((options: { config?: string; prompt?: string; resume?: string }) => {
+    .option('--config <path>', 'apply this overlay of loader patches instead of the personal one')
+    .option('--config-replace <path>', 'boot this file as the entire tree, ignoring the shipped and personal configuration')
+    .action((options: { config?: string; configReplace?: string; prompt?: string; resume?: string }) => {
      if (options.prompt !== undefined) {
        // A headless prompt owns the invocation; an empty task has nothing to
        // run, and --config/--resume are TUI inputs that must not silently
        // vanish from a headless run.
        if (options.prompt === '') program.error('error: --prompt needs a task')
-        if (options.config !== undefined || options.resume !== undefined) {
-          program.error('error: --prompt takes no --config or --resume')
+        if (options.config !== undefined || options.configReplace !== undefined || options.resume !== undefined) {
+          program.error('error: --prompt takes no --config, --config-replace, or --resume')
        }
        resolved = { mode: 'headless', prompt: options.prompt }
        return
@@ -156,9 +166,15 @@ Examples:
      // An empty --resume= id would silently start a fresh session downstream
      // (agent-loop treats '' as no-resume), so a mistyped resume must fail loud.
      if (options.resume === '') program.error('error: --resume needs a session id')
+      // The two config flags are mutually exclusive: one layers over the shipped
+      // tree, the other discards it, so accepting both would silently drop one.
+      if (options.config !== undefined && options.configReplace !== undefined) {
+        program.error('error: --config and --config-replace are mutually exclusive')
+      }
      resolved = {
        mode: 'tui',
        ...options.config !== undefined && { config: options.config },
+        ...options.configReplace !== undefined && { configReplace: options.configReplace },
        ...options.resume !== undefined && { resume: options.resume },
      }
    })
@@ -168,8 +184,9 @@ Examples:
  // a leaked `--config`/`-p`/`--resume` is a mistyped invocation that must fail
  // loud rather than silently run and drop the input.
  const rejectParentOptions = (command: string): void => {
-    const parent = program.opts<{ config?: string; prompt?: string; resume?: string }>()
-    if (parent.config !== undefined || parent.prompt !== undefined || parent.resume !== undefined) {
+    const parent = program.opts<{ config?: string; configReplace?: string; prompt?: string; resume?: string }>()
+    if (parent.config !== undefined || parent.configReplace !== undefined
+      || parent.prompt !== undefined || parent.resume !== undefined) {
      program.error(`error: ${command} takes none of --config, -p/--prompt, or --resume`)
    }
  }
@@ -208,6 +225,7 @@ Examples:
  // would duplicate a fact this file does not own.
  const web = program.command('web').description('serve the browser UI on the configured host and port')
  web
+    .option('--config <path>', 'apply this overlay of loader patches over the shipped configuration')
    .option('--host <host>', 'bind host; pass 0.0.0.0 to reach it from another machine')
    .option('--port <port>', 'listen port; pass 0 to let the OS pick a free one')
    .option('--dev', 'developer mode: hot-reload the browser client')
@@ -30,7 +30,7 @@ const invocation = parseDshArgs(process.argv.slice(2), readVersion())
 switch (invocation.mode) {
  case 'web': {
    const { runWeb } = await import('./web.ts')
-    await runWeb(invocation.host, invocation.port, invocation.dev, invocation.workspaceRoot, invocation.trustedHosts)
+    await runWeb(invocation.host, invocation.port, invocation.dev, invocation.workspaceRoot, invocation.trustedHosts, invocation.config)
    break
  }
  case 'headless': {
@@ -40,7 +40,7 @@ switch (invocation.mode) {
  }
  case 'tui': {
    const { runTui } = await import('./tui.ts')
-    await runTui(invocation.config, invocation.resume)
+    await runTui(invocation.config, invocation.resume, undefined, undefined, invocation.configReplace)
    break
  }
  case 'meta': {
@@ -76,7 +76,8 @@ async function consumeUntilTurnEnd(frames: AsyncIterable<RpcRequest<MuxFrame>>,
 export async function runHeadless(task: string): Promise<void> {
  // A missing DEEPSEEK_API_KEY throws here (plugin load is fail-loud, uncaught by design).
  const entry = new AppCLIEntry({
-    configPath: fileURLToPath(new URL('../cordis.yml', import.meta.url)),
+    configPath: fileURLToPath(new URL('../base.cordis.yml', import.meta.url)),
+    overlayPath: fileURLToPath(new URL('../web.cordis.yml', import.meta.url)),
    dev: false,
    port: 0,
  })
@@ -25,11 +25,13 @@ import {
  boot,
  installFailLoud,
  loadEnv,
+  loadOverlayPatches,
  loadPersonalPatches,
  resolveConfigPath,
 } from '@deepseek-ai/dsh-app-boot'
 import { resolveDshHome, resolveSessionsRoot } from '@deepseek-ai/dsh-paths'
 import { SessionId } from '@deepseek-ai/dsh-session'
+import { CONFIGURED_AGENT_IDENTITIES_KEY } from '@deepseek-ai/dsh-agent-loop'
 import type { Context } from 'cordis'
 import { registerLiveSessions } from './register-session.ts'
 import {
@@ -46,7 +48,18 @@ const NAME = 'dsh'
 // Both the source tree (apps/cli/src) and the bundled bin (apps/cli/lib) sit
 // one directory under apps/cli, so the shipped default config resolves with
 // the same relative hop from either artifact.
-const DEFAULT_CONFIG = fileURLToPath(new URL('../../../examples/tui-agent/cordis.yml', import.meta.url))
+// The shared core every `dsh` surface mounts, and the TUI's own overlay over
+// it. Both the source tree (apps/cli/src) and the bundled bin (apps/cli/lib)
+// sit one directory under apps/cli, so each resolves with the same hop.
+const BASE_CONFIG = fileURLToPath(new URL('../base.cordis.yml', import.meta.url))
+const TUI_OVERLAY = fileURLToPath(new URL('../tui.cordis.yml', import.meta.url))
+
+// The `agents` entry in tui.cordis.yml the TUI drives; the launcher binds its
+// session identity by this config id.
+const MAIN_AGENT_ID = 'main'
+
+/** Filename of the derived `/resume` index, kept beside the session logs. */
+const SESSION_QUERY_DB = 'session-query.db'

 // The harness checkout root: three hops up from apps/cli/{src,lib}, resolved
 // from this bin's location so it holds however `dsh` is launched (a PATH
@@ -93,24 +106,31 @@ export async function runSkillSession(skill: string): Promise<void> {

 /**
 * Run the interactive TUI from the invoking directory.
- * @param config - a config path to boot instead of the shipped default, or
- * `undefined` for the default; already parsed from `--config`.
+ * @param config - an overlay patch list applied over the shared base and the
+ * TUI overlay, REPLACING the personal `~/.dsh/config.yaml` so a named tree never
+ * inherits the user's route, or `undefined` to use the personal overlay;
+ * already parsed from `--config`.
 * @param resumeSessionId - a persisted session id to resume, or `undefined` to
 * mint a fresh one; already parsed and non-empty-validated from `--resume`.
 * Either way the resulting identity reaches the booted app through
- * {@link MAIN_SESSION_ID_KEY}, so no config key selects the session.
+ * {@link CONFIGURED_AGENT_IDENTITIES_KEY}, so no config key selects the session
+ * and an overlay replacing the agent row cannot drop it.
 * @param workspace - a directory to make the workspace instead of the invoking
 * one, or `undefined` to keep the cwd. Only `dsh meta` passes it.
 * @param initialSkill - a bundled skill to auto-invoke as a fresh session's
 * first turn, or `undefined`. Set only by {@link runSkillSession} and ignored
 * on a resume, so it never re-fires; reaches the app through
 * {@link INITIAL_SKILL_KEY}.
+ * @param configReplace - a config path to boot as the ENTIRE tree, bypassing the
+ * shared base, the TUI overlay, and the personal overlay alike, or `undefined`
+ * to compose them; already parsed from `--config-replace`.
 */
 export async function runTui(
  config: string | undefined,
  resumeSessionId: string | undefined,
  workspace?: string,
  initialSkill?: string,
+  configReplace?: string,
 ): Promise<void> {
  // Refuse pipes BEFORE booting: a compose-time throw inside the Loader tree
  // is logged per-entry rather than rethrown, so a piped launch would
@@ -150,7 +170,13 @@ export async function runTui(
  const resumeArgs = (sessionId: string, targetCwd?: string): string[] =>
    workspace !== undefined && (targetCwd === undefined || targetCwd === workspace)
      ? ['meta', `--resume=${sessionId}`]
-      : [`--resume=${sessionId}`, ...config !== undefined ? ['--config', config] : []]
+      : [
+        `--resume=${sessionId}`,
+        // Both config flags must survive the handoff: resuming into a different
+        // tree than the session was created in would silently change the agent.
+        ...config !== undefined ? ['--config', config] : [],
+        ...configReplace !== undefined ? ['--config-replace', configReplace] : [],
+      ]
  // Mint the fresh id here rather than in the app bundle: the exit line names
  // the session to resume, so the launcher must know it before the tree boots.
  const identity: MainSessionIdentity = resumeSessionId === undefined
@@ -186,10 +212,25 @@ export async function runTui(
      }
    },
  }
+  // One include of the shared base, with every overlay applied as a sibling
+  // patch list: patches never cross an include boundary, so stacking these as
+  // nested includes would silently stop reaching base rows. Later lists win.
+  //
+  // `--config` REPLACES the personal overlay rather than layering under it: an
+  // explicitly named tree must not inherit `~/.dsh/config.yaml`'s route, or a
+  // demo or test config would silently run on the user's provider and model.
+  // `--config-replace` additionally discards the base and the surface overlay.
+  const replaceTree = configReplace !== undefined
+  const patches = replaceTree ? [] : [
+    ...loadOverlayPatches(NAME, TUI_OVERLAY),
+    ...config === undefined
+      ? loadPersonalPatches(NAME) ?? []
+      : loadOverlayPatches(NAME, resolveConfigPath(config, undefined)),
+  ]
  const ctx = await boot(
    NAME,
-    resolveConfigPath(config ?? DEFAULT_CONFIG, undefined),
-    loadPersonalPatches(NAME),
+    replaceTree ? resolveConfigPath(configReplace, undefined) : BASE_CONFIG,
+    patches,
    (hostCtx) => {
      // The launcher owns session identity and the exit line: a config-mounted
      // app bundle reads both from these slots, so no cordis.yml key can drop
@@ -200,6 +241,13 @@ export async function runTui(
      // the Harness home across every cwd, so /resume and list-sessions see
      // every workspace. The bundle treats the slot as opaque.
      hostCtx.provide(SESSIONS_ROOT_KEY, launcherSessionsRoot())
+      // The agent-loop row reads this to bind `main`, and the tui row reads the
+      // same id, so a personal overlay repointing the model route cannot drop
+      // the session identity or desynchronise the two.
+      hostCtx.provide(CONFIGURED_AGENT_IDENTITIES_KEY, { [MAIN_AGENT_ID]: identity })
+      // The launcher owns the session store location, so it also owns the
+      // derived index path that must sit beside those logs.
+      hostCtx.provide('launcherSessionQueryPath', join(launcherSessionsRoot(), SESSION_QUERY_DB))
      if (resumeHost !== undefined) hostCtx.provide('tuiResumeHost', resumeHost)
      // Seed the first turn only for a fresh session, so resuming never
      // re-invokes the skill.
@@ -7,10 +7,13 @@
 */

 import { fileURLToPath } from 'node:url'
+import { resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
 import { AppCLIEntry } from './app-cli-entry.ts'
 import { registerLiveSessions } from './register-session.ts'

-const CONFIG_PATH = fileURLToPath(new URL('../cordis.yml', import.meta.url))
+// The shared core every `dsh` surface mounts, plus this surface's overlay over it.
+const BASE_CONFIG = fileURLToPath(new URL('../base.cordis.yml', import.meta.url))
+const WEB_OVERLAY = fileURLToPath(new URL('../web.cordis.yml', import.meta.url))

 // Display-only mirror of the webserver schema's loopback host: the address the
 // local URL always prints. Not a source of truth — the schema is.
@@ -24,6 +27,8 @@ const LOOPBACK_HOST = '127.0.0.1'
 * @param dev - mount the client HMR driver and watch plugin bundles for rebuilds.
 * @param workspaceRoot - parent directory for name-created workspaces, or `undefined` for the gateway's cwd fallback.
 * @param trustedHosts - extra authorities for the /api browser-trust fence, or `undefined` for the derived LAN literals alone.
+ * @param config - an overlay of loader patches applied over the shipped web
+ * composition, or `undefined` for none; already parsed from `--config`.
 */
 export async function runWeb(
  host: string | undefined,
@@ -31,9 +36,12 @@ export async function runWeb(
  dev: boolean,
  workspaceRoot: string | undefined,
  trustedHosts: string[] | undefined,
+  config?: string,
 ): Promise<void> {
  const entry = new AppCLIEntry({
-    configPath: CONFIG_PATH,
+    configPath: BASE_CONFIG,
+    overlayPath: WEB_OVERLAY,
+    ...config !== undefined && { extraOverlayPath: resolveConfigPath(config, undefined) },
    dev,
    ...host !== undefined && { host },
    ...port !== undefined && { port },
@@ -0,0 +1,71 @@
+# Overlay for the keyless conversational PTY test: the shipped composition with
+# only the model replaced, so the terminal interaction is deterministic and
+# network-free while the agent/TUI/user-question stack stays the production one.
+#
+# Passed as `--config`, so the launcher includes `base.cordis.yml`, applies
+# `tui.cordis.yml`, then this file — all sibling patch lists at one include
+# level. A patch replaces the targeted row's whole `config`, so each row below
+# restates every key it owns.
+
+# The scripted adapter replaces the DeepSeek one: no key, no network. A patch's
+# `name` is an assertion rather than a replacement, so the base row is disabled
+# and the adapter inserted. Relative specifiers resolve against the INCLUDED
+# file's directory (apps/cli), because the include moves baseUrl to that tree.
+- id: llm-deepseek
+  disabled: true
+
+- insert:
+    - id: scripted-llm
+      name: './tests/fixtures/tui-scripted-llm.ts'
+
+- id: agent-loop
+  config:
+    agents:
+      - id: main
+        provider: tui-scripted
+        model: tui-scripted-model
+        # `cwd` scopes the session to this workspace, which is what `/resume`
+        # filters on; dropping it would hide the seeded session.
+        cwd: !!js process.cwd()
+
+- id: system-prompt
+  config:
+    persona: 'Scripted model {{model}}.'
+
+# The smoke's log inspection reads plain `.jsonl` under the workspace, so this
+# fixture pins a project-local root instead of the launcher's shared store, and
+# keeps the artifacts uncompressed like the other snapshot-facing configs.
+- id: session-persistence-jsonl
+  config:
+    root: './.sessions'
+    compression: none
+
+# The derived index must sit under the same root as the logs it indexes; this
+# fixture pins both to the workspace instead of the launcher's shared store.
+- id: session-query-sqlite
+  config:
+    path: './.sessions/session-query.db'
+
+- id: plan-mode
+  config:
+    section: 'Stay in plan mode for this scripted TUI test.'
+
+# The scripted adapter answers the tool-less title request with a fixed string,
+# so the PTY test can assert the logged title reaches the terminal window title.
+- id: session-title-llm
+  config:
+    targetWords: 5
+    targetCjkCharacters: 10
+    maxInputBytes: 4096
+    maxOutputTokens: 64
+    timeoutMs: 10000
+
+- id: tui
+  config:
+    sessionId: !!js configuredAgentIdentities?.main?.id ?? 'main'
+    welcome: 'scripted TUI ready.'
+    showReasoning: true
+
+# HMR watches the repository; a PTY subprocess test must not start a watcher.
+- id: hmr
+  disabled: true
@@ -9,9 +9,10 @@ import { packChunkRuns, SessionId, type SessionEvent, type SessionHeader } from
 import { logPath, toHeaderLine } from '../../../packages/session-persistence/session-persistence-jsonl/src/format.ts'
 import { runTuiPtySmoke, type TuiPtySmokeOptions } from './pty-harness.ts'

-const dshBinScript = fileURLToPath(new URL('../../../apps/cli/src/bin.ts', import.meta.url))
-const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url))
-const codeModeConfigPath = fileURLToPath(new URL('../code-mode.cordis.yml', import.meta.url))
+const dshBinScript = fileURLToPath(new URL('../src/bin.ts', import.meta.url))
+// `--config` layers an overlay over the shared base, so the default surface
+// needs no config argument at all; these are the overlays under test.
+const codeModeConfigPath = fileURLToPath(new URL('../../../examples/code-mode/cordis.yml', import.meta.url))
 const scriptedConfigPath = fileURLToPath(new URL('./fixtures/tui-scripted.cordis.yml', import.meta.url))
 const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))

@@ -119,12 +120,16 @@ async function readLoggedRequestContext(cwd: string): Promise<LoggedRequestConte
  throw new Error(`session log ${logRelPath} has no request/header event`)
 }

-/** Shared defaults: the keyless key, the dsh bin, and the live cordis.yml (passed as the positional config). */
+/**
+ * Shared defaults: the keyless key and the dsh bin. Each case supplies either
+ * `configArgs: []` (boot the shipped composition, `base.cordis.yml` +
+ * `tui.cordis.yml`, with no flags) or `configPath` (an overlay layered over that
+ * same base through `--config`).
+ */
 function smoke(overrides: Partial<TuiPtySmokeOptions> & { label: string }): Promise<string> {
  return runTuiPtySmoke({
-    tempDirPrefix: 'tui-agent-smoke-',
+    tempDirPrefix: 'dsh-tui-smoke-',
    binScript: dshBinScript,
-    configPath,
    tsconfigPath,
    env: { DEEPSEEK_API_KEY: 'keyless-tui-no-call' },
    ...overrides,
@@ -139,13 +144,14 @@ const SELECT_PRO_MODEL = [
  { waitFor: 'Select model', send: '\x1b[B\x1b[Z\r' },
 ] as const

-describe('tui-agent keyless smoke (real Loader tree in a PTY)', () => {
+describe('dsh TUI keyless smoke (real Loader tree in a PTY)', () => {
  it('boots pi-tui, sweeps the borderless banner in, enters plan mode, and restores the terminal', async () => {
    // With no configured welcome the borderless banner sweeps in left-to-right;
    // the detail line's session id (`main-session-<uuid>`) renders only once
    // the sweep reaches it, so it marks a settled banner.
    const output = await smoke({
-      label: 'tui-agent boot',
+      label: 'dsh boot',
+      configArgs: [],
      actions: [
        { waitFor: 'main-session-', send: '/plan' },
        { waitFor: '[off|message] — Enter or leave plan mode', send: '\r' },
@@ -165,8 +171,8 @@ describe('tui-agent keyless smoke (real Loader tree in a PTY)', () => {

  it('switches models, streams a response, answers a user-question dialog, and exits cleanly', async () => {
    const output = await smoke({
-      label: 'tui-agent conversation',
-      tempDirPrefix: 'tui-agent-conversation-',
+      label: 'dsh conversation',
+      tempDirPrefix: 'dsh-tui-conversation-',
      configPath: scriptedConfigPath,
      actions: [
        ...SELECT_PRO_MODEL,
@@ -223,8 +229,8 @@ describe('tui-agent keyless smoke (real Loader tree in a PTY)', () => {
    // rendered `<skill name="…">` block reaches the model — proven by the
    // scripted adapter echoing the fixture's body marker only when it arrives.
    const output = await smoke({
-      label: 'tui-agent skill',
-      tempDirPrefix: 'tui-agent-skill-',
+      label: 'dsh skill',
+      tempDirPrefix: 'dsh-tui-skill-',
      configPath: scriptedConfigPath,
      prepare: seedWorkspace({
        skills: {
@@ -252,8 +258,11 @@ describe('tui-agent keyless smoke (real Loader tree in a PTY)', () => {

  it('fuzzy-completes an @file path without reading or submitting the file', async () => {
    const output = await smoke({
-      label: 'tui-agent file autocomplete',
-      tempDirPrefix: 'tui-agent-file-autocomplete-',
+      label: 'dsh file autocomplete',
+      tempDirPrefix: 'dsh-tui-file-autocomplete-',
+      // The shipped composition: no welcome, so the banner's session-id detail
+      // line marks a settled boot. Completion never calls the model.
+      configArgs: [],
      prepare: seedWorkspace({
        workspace: {
          'src/terminal-special-case.ts': 'export const marker = true\n',
@@ -275,8 +284,8 @@ describe('tui-agent keyless smoke (real Loader tree in a PTY)', () => {
    // The overlay's only keyless composition proof: the include+patch tree,
    // worker code runtime, and one-tool registry all mount before the banner.
    const output = await smoke({
-      label: 'tui-agent code mode',
-      tempDirPrefix: 'tui-agent-code-mode-',
+      label: 'dsh code mode',
+      tempDirPrefix: 'dsh-tui-code-mode-',
      configPath: codeModeConfigPath,
      actions: [{ waitFor: 'TUI Code Mode ready.', send: '/exit\r' }],
    })
@@ -325,8 +334,10 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {

  it('applies the personal overlay: config.yaml patches the tree and .env feeds its !!js', async () => {
    // The whole personal-config chain in one boot: the personal .env supplies
-    // the variable, config.yaml patches the tui-agent entry with a `!!js`
-    // reference to it, and the banner renders the patched welcome verbatim.
+    // the variable, config.yaml patches the `tui` row — a row the SURFACE
+    // OVERLAY inserted, not one the base declares — with a `!!js` reference to
+    // it, and the banner renders the patched welcome verbatim. That proves a
+    // later patch list reaches a row an earlier one inserted.
    const output = await smoke({
      label: 'dsh personal overlay',
      tempDirPrefix: 'dsh-personal-overlay-',
@@ -336,12 +347,11 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
        personal: {
          '.env': 'DSH_PERSONAL_WELCOME=PERSONAL OVERLAY READY.\n',
          'config.yaml': [
-            '- id: tui-agent',
-            "  name: '@deepseek-ai/dsh-tui-demo'",
+            '- id: workspace-context',
+            '  disabled: true',
+            '- id: tui',
            '  config:',
-            '    provider: deepseek',
-            '    model: deepseek-v4-flash',
-            '    workspaceContext: false',
+            "    sessionId: !!js configuredAgentIdentities?.main?.id ?? 'main'",
            '    welcome: !!js process.env.DSH_PERSONAL_WELCOME',
            '',
          ].join('\n'),
@@ -393,10 +403,11 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
    expect(output).toMatch(/To resume this session: dsh --resume=main-session-[0-9a-f-]{36} --config/)
  }, LOADER_SMOKE_TEST_TIMEOUT_MS)

-  it('keeps resume working when the personal overlay replaces the whole tui-agent config', async () => {
+  it('keeps resume working when the personal overlay replaces the whole agent-loop config', async () => {
    // Loader patches replace a targeted `config` key wholesale, so a personal
-    // overlay that omits a resume key used to silently disable the exit hint.
-    // Launcher-owned identity and exit line make that unreachable.
+    // overlay repointing the model route drops every identity key the shipped
+    // row declared. Launcher-owned identity makes that unreachable: agent-loop
+    // applies the launcher's id over whatever route survives.
    const output = await smoke({
      label: 'dsh overlay keeps resume',
      tempDirPrefix: 'dsh-overlay-resume-',
@@ -405,12 +416,18 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
      prepare: seedWorkspace({
        personal: {
          'config.yaml': [
-            '- id: tui-agent',
-            "  name: '@deepseek-ai/dsh-tui-demo'",
+            '- id: workspace-context',
+            '  disabled: true',
+            '- id: agent-loop',
            '  config:',
-            '    provider: deepseek',
-            '    model: deepseek-v4-flash',
-            '    workspaceContext: false',
+            '    agents:',
+            '      - id: main',
+            '        provider: deepseek',
+            '        model: deepseek-v4-flash',
+            '        cwd: !!js process.cwd()',
+            '- id: tui',
+            '  config:',
+            "    sessionId: !!js configuredAgentIdentities?.main?.id ?? 'main'",
            '    welcome: OVERLAY REPLACED THE CONFIG.',
            '',
          ].join('\n'),
@@ -426,7 +443,7 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
    // consumes into its own `[exit 3]` pill. Rendering both would report the same
    // exit twice, so the marker must not survive into the card body.
    const output = await smoke({
-      label: 'tui-agent bash exit pill',
+      label: 'dsh bash exit pill',
      tempDirPrefix: 'dsh-bash-exit-pill-',
      configPath: scriptedConfigPath,
      actions: [
@@ -0,0 +1,131 @@
+# `dsh` (the default surface) — the full-screen TUI, as a patch list over
+# `base.cordis.yml`. The launcher includes the base and applies this file, then
+# any `--config` overlay, then the personal `~/.dsh/config.yaml`, as sibling
+# patch lists at ONE include level: patches never cross an include boundary, so
+# stacking overlays as nested includes would silently stop reaching base rows.
+#
+# A patch replaces the targeted row's whole `config`, so each row below restates
+# every key it owns. A patch whose `id` matches no row is skipped with a Loader
+# warning, which is deliberate: one personal overlay is shared across surfaces,
+# so a row that exists only under `web` must not fail the TUI's boot.
+#
+# The launcher owns session identity and the exit line, and provides both on the
+# boot context rather than through config, so no key here — and no overlay
+# replacing one — can drop `--resume`.
+
+# ── surface-specific values the base deliberately omits ─────────────────────
+
+# `main` is the agent the TUI drives. `provider`/`model` are the route `dsh
+# login` rewrites and a personal overlay repoints; `cwd` anchors the session to
+# the invoking directory, which is also what scopes `/resume` to this workspace.
+- id: agent-loop
+  config:
+    agents:
+      - id: main
+        provider: deepseek
+        model: deepseek-v4-pro
+        cwd: !!js process.cwd()
+
+# Keep the persona to identity and behavior; tool plugins own tool guidance.
+# The loop resolves {{model}} from this agent's configuration.
+- id: system-prompt
+  config:
+    persona: |
+      You are a coding agent powered by the {{model}} model.
+
+      Verify your work by running the code or tests. Keep answers brief and
+      factual.
+
+# Shipped default: full thinking at max effort on every request (wire-only
+# defaults; they never enter the request header).
+- id: llm-deepseek
+  config:
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    baseURL: !!js process.env.DEEPSEEK_BASE_URL
+    thinking: enabled
+    reasoningEffort: max
+
+# This single-session app resolves relative paths from the process cwd.
+- id: fs-local
+  config:
+    cwd: !!js process.cwd()
+
+# The shipped TUI presents the native tool registry. `examples/code-mode` is the
+# overlay that switches this row to the `run_code` transport.
+- id: tools
+  config:
+    mode: native
+
+# ── TUI-only rows ───────────────────────────────────────────────────────────
+
+- insert:
+    # Development-only hot reload; it depends on Loader internals, so it stays a
+    # surface row rather than joining the shared base.
+    - id: hmr
+      name: '@cordisjs/plugin-hmr'
+      config:
+        root: ['.']
+
+    # Relational runtime checks over the authoritative event streams; each
+    # companion registers the assertions its own package owns.
+    - id: invariants
+      name: '@deepseek-ai/dsh-invariants'
+    - id: session-invariant
+      name: '@deepseek-ai/dsh-session/invariant'
+    - id: agent-invariant
+      name: '@deepseek-ai/dsh-agent/invariant'
+    - id: scope-invariant
+      name: '@deepseek-ai/dsh-scope/invariant'
+    - id: agent-loop-invariant
+      name: '@deepseek-ai/dsh-agent-loop/invariant'
+
+    - id: session-checkpoint-policy
+      name: '@deepseek-ai/dsh-session-checkpoint-policy'
+
+    # The derived query index behind `/resume`. The launcher owns the session
+    # store location, so it provides the resolved index path on the boot context
+    # (`launcherSessionQueryPath`); the index and the logs it indexes therefore
+    # cannot diverge. The project-local fallback applies when no launcher sets it.
+    - id: session-query-sqlite
+      name: '@deepseek-ai/dsh-session-query-sqlite'
+      config:
+        path: !!js launcherSessionQueryPath ?? './.sessions/session-query.db'
+
+    - id: session-reference
+      name: '@deepseek-ai/dsh-session-reference'
+
+    # Refuses write/edit inside the dsh checkout this launcher runs from, on that
+    # checkout's own branch, until the session loads dsh-customize. Inert
+    # everywhere else, so an ordinary project sees no change.
+    - id: source-guard
+      name: '@deepseek-ai/dsh-source-guard'
+
+    - id: tool-result-prune
+      name: '@deepseek-ai/dsh-compact-tool-result-prune'
+
+    # Persisted same-session goals reach the model and the slash menu here; the
+    # domain, driver, and `/goal` command are in the base.
+    - id: tool-goal
+      name: '@deepseek-ai/dsh-tool-goal'
+
+    # A separate fixed consumer demonstrates fresh-agent Ralph iteration without
+    # changing the workflow tool or same-session goal behavior.
+    - id: tool-ralph
+      name: '@deepseek-ai/dsh-tool-ralph'
+
+    # The keyboard-backed provider behind ask_user_question and the plan-mode
+    # review, and the front door it renders inside.
+    - id: tui-prompt
+      name: '@deepseek-ai/dsh-tui/prompt'
+
+    # The TUI renders exactly the agent the agent-loop row bound, so it reads the
+    # same launcher-owned identity rather than restating one.
+    - id: tui
+      name: '@deepseek-ai/dsh-tui'
+      config:
+        sessionId: !!js configuredAgentIdentities?.main?.id ?? 'main'
+        showReasoning: true
+        maxToolOutputLines: 6
+
+    - id: tool-ask-user
+      name: '@deepseek-ai/dsh-tool-ask-user'
@@ -0,0 +1,167 @@
+# `dsh web` — the browser surface, as a patch list over `base.cordis.yml`.
+# The launcher includes the base and applies this file, then any `--config`
+# overlay, then AppCLIEntry's profile-json and CLI-flag patches, as sibling patch
+# lists at ONE include level: patches never cross an include boundary, so
+# stacking overlays as nested includes would silently stop reaching base rows.
+#
+# A patch replaces the targeted row's whole `config`, so each row below restates
+# every key it owns. `--dev` appends the dsh-client-hmr row in code
+# (AppCLIEntry) — prod and dev differ by exactly that one row.
+
+# ── surface-specific values the base deliberately omits ─────────────────────
+
+- id: system-prompt
+  config:
+    persona: ''
+
+- id: tools
+  config:
+    # TEMPORARY workaround: DSH_TOOLS_MODE (native|code|both) opts a whole dsh
+    # process into Code Mode while per-session tool-mode selection is being
+    # designed; unset keeps the schema default (native). Remove the env seam
+    # once the web UI owns the choice per session.
+    mode: !!js process.env.DSH_TOOLS_MODE
+
+- id: agent-loop
+  config:
+    agents: []
+
+- id: llm-deepseek
+  config:
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    baseURL: !!js process.env.DEEPSEEK_BASE_URL
+
+- id: fs-local
+
+# ── web-only host rows, the transport layer, and the browser roster ─────────
+
+# `dshClient` rows are the browser roster the modules node half scans into
+# window.__DSH_BOOT__; the modules row is simultaneously a host row.
+- insert:
+    - id: session-projection
+      name: '@deepseek-ai/dsh-session-projection'
+
+    - id: code-runtime
+      name: '@deepseek-ai/dsh-code-runtime-worker'
+
+    - id: storage
+      name: '@deepseek-ai/dsh-storage'
+
+    - id: storage-json
+      name: '@deepseek-ai/dsh-storage-json'
+      config:
+        root: './.storages'
+
+    - id: storage-domain
+      name: '@deepseek-ai/dsh-storage-domain'
+      config:
+        backend: json
+
+    - id: workspace
+      name: '@deepseek-ai/dsh-workspace'
+
+    - id: session-projection-cache
+      name: '@deepseek-ai/dsh-session-projection-cache'
+      config:
+        writeEveryEvents: 200
+        writeIntervalMs: 5000
+
+    - id: tool-todo
+      name: '@deepseek-ai/dsh-tool-todo'
+
+    # The API gateway: the transport-agnostic dispatch face every client shape
+    # shares. provider/model are the host default routing — the profile json's
+    # mapping target (user config overrides these engineering defaults).
+    - id: api-gateway
+      name: '@deepseek-ai/dsh-host-apiproxy'
+      config:
+        provider: deepseek
+        model: deepseek-v4-flash
+
+    # ── layer 2: transport/service ──────────────────────────────────────────────
+
+    # Plain route-registration carrier. distIndex is an assembly fact, not user
+    # config — AppCLIEntry resolves the frontend dist and patches it in; host and
+    # port arrive as CLI-flag patches over these defaults.
+    - id: webserver
+      name: '@deepseek-ai/dsh-host-webserver'
+      config:
+        host: 127.0.0.1
+        port: 3080
+
+    # ── browser plugin roster (dshClient rows; node halves are layer-2 hosts) ──
+
+    # Dual-face: node half scans this very tree for dshClient rows, composes
+    # window.__DSH_BOOT__, serves /plugins/<id>/client.js; browser half is the
+    # module table the shell kernel constructs before cordis exists (§4.7 —
+    # adopted as a plugin entry by the kernel, never fetched).
+    - id: modules
+      name: '@deepseek-ai/dsh-client-modules'
+
+    # Owns both ends of the web transport: node half binds the gateway to the
+    # webserver under /api; browser half is the fetch/SSE client.
+    - id: connection
+      name: '@deepseek-ai/dsh-client-connection'
+
+    - id: client-runtime
+      name: '@deepseek-ai/dsh-client-runtime'
+
+    - id: ui-theme
+      name: '@deepseek-ai/dsh-client-ui-theme'
+
+    - id: locale
+      name: '@deepseek-ai/dsh-client-locale'
+
+    - id: ui-layout
+      name: '@deepseek-ai/dsh-client-ui-layout'
+
+    - id: ui-sidebar
+      name: '@deepseek-ai/dsh-client-ui-sidebar'
+
+    - id: ui-settings
+      name: '@deepseek-ai/dsh-client-ui-settings'
+
+    - id: ui-settings-general
+      name: '@deepseek-ai/dsh-client-ui-settings-general'
+
+    - id: ui-models
+      name: '@deepseek-ai/dsh-client-ui-models'
+
+    - id: ui-conversation
+      name: '@deepseek-ai/dsh-client-ui-conversation'
+
+
+    - id: ui-workspace
+      name: '@deepseek-ai/dsh-client-ui-workspace'
+
+    # Input triggers: the '/' | '@' pipeline (ui-slash), the command surface over
+    # it (ui-command), and the two reference sources (ui-skill / ui-subagent).
+    - id: ui-slash
+      name: '@deepseek-ai/dsh-client-ui-slash'
+
+    - id: ui-command
+      name: '@deepseek-ai/dsh-client-ui-command'
+
+    - id: ui-skill
+      name: '@deepseek-ai/dsh-client-ui-skill'
+
+    - id: ui-subagent
+      name: '@deepseek-ai/dsh-client-ui-subagent'
+
+    # Goal surface: GoalBar in the input dock over the goal session projection.
+    - id: ui-goal
+      name: '@deepseek-ai/dsh-client-ui-goal'
+
+    # Model selection: the /model popupSelect + composer seat over session.models.
+    - id: ui-model
+      name: '@deepseek-ai/dsh-client-ui-model'
+
+    # Plan control: the composer plan seat over the plan projection + /plan channel.
+    - id: ui-plan
+      name: '@deepseek-ai/dsh-client-ui-plan'
+
+    - id: ui-question
+      name: '@deepseek-ai/dsh-client-ui-question'
+
+    - id: ui-trajectory
+      name: '@deepseek-ai/dsh-client-ui-trajectory'
@@ -89,7 +89,6 @@ flowchart LR
  pkg_skill_local["skill-local"]
  svc_agents["ctx.agents<br/>Agent service"]
  pkg_acp["acp"]
-  pkg_tui_demo["tui-demo"]
  svc_agentLoop["ctx.agentLoop<br/>Concrete loop driver"]
  pkg_agent_spine_demo["agent-spine-demo"]
  pkg_goal["goal"]
@@ -245,7 +244,6 @@ flowchart LR
  svc_agents --> pkg_agent_loop
  svc_agents --> pkg_cli_demo
  svc_agents --> pkg_subagent_inprocess
-  svc_agents --> pkg_tui_demo
  svc_approval --> pkg_tool_bash
  svc_approval --> pkg_tools
  svc_bash --> pkg_hooks_claude
@@ -359,7 +357,7 @@ flowchart LR
 | `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. |
+| `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) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
 | `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | Folds revisioned objective state from the session log and keeps live continuation activation process-local. |
 | `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`lsp-local`](../packages/lsp/lsp-local), [`subagent-acp`](../packages/subagent/subagent-acp) | - | The bash executors, the LSP host, and the ACP subagent backend spawn their children through ctx.subprocess; the service owns tree lifetime, stdio dispositions (pipes, inherit, bounded spill-backed collection), and kill escalation. |
@@ -108,7 +108,7 @@ export interface Config {

 Depends on: [`AgentOptions`](core-data-structures/core.md) · [`SessionId`](core-data-structures/core.md)

-Source: [`packages/core/agent-loop/src/index.ts:155`](../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:211`](../packages/core/agent-loop/src/index.ts)

 ## `@deepseek-ai/dsh-agent-spine-demo`

@@ -2005,59 +2005,6 @@ export interface TuiThemeConfig {

 Source: [`packages/ui/tui/src/config.ts:117`](../packages/ui/tui/src/config.ts)

-## `@deepseek-ai/dsh-tui-demo`
-
-```ts config-catalog
-/** App config routed to the spine, TUI, configured agent, and JSONL backend. */
-export interface Config {
-  /** Provider route for the `main` agent. */
-  provider: string
-  /** Model name for the `main` agent; a matching adapter must be registered. */
-  model: string
-  /** Bundled agent-loop concurrency cap; `1` is serial and omission uses its default. */
-  maxParallelToolCalls?: number
-  /** Deployment persona forwarded to the system-prompt plugin. */
-  persona?: string
-  /** Explicit model-facing tool order forwarded to the system-prompt plugin. */
-  toolOrder?: string[]
-  /** Tool-registry presentation config forwarded through agent-spine-demo. */
-  tools?: ToolsConfig
-  /** DeepSeek Harness home directory exposed to bash and used for local skill discovery. */
-  dshHome?: string
-  /** Fallback session-title limits forwarded through agent-spine-demo. */
-  sessionTitle?: NonNullable<agentCore.Config['sessionTitle']>
-  /**
-   * Directory for JSONL sessions and the derived query index. Precedence:
-   * this explicit config, then the launcher's opaque `SESSIONS_ROOT_KEY` boot
-   * slot (the dsh CLI resolves it to `DSH_HOME/sessions`), then a project-local
-   * `./.sessions` fallback — the bundle itself never assumes a global store.
-   */
-  persistenceRoot?: string
-  /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
-  persistenceCompression?: JsonlCompression
-  /** Cross-session reference discovery and snapshot byte budgets. */
-  sessionReferences?: SessionReferenceConfig
-  /** TUI transcript's optional first line; absent renders nothing on start. */
-  welcome?: string
-  /** Full-screen TUI presentation settings. */
-  ui?: uiTui.TuiConfig
-  /** Skill registry, local-provider, and model-facing consumer config. */
-  skills?: agentCore.SkillConfig
-  /** Model-facing bash tool config forwarded through agent-spine-demo. */
-  toolBash?: NonNullable<agentCore.Config['toolBash']>
-  /** Generic background-task controls forwarded through agent-spine-demo; set false to omit them. */
-  toolTasks?: NonNullable<agentCore.Config['toolTasks']>
-  /** Persisted same-session goals; owner defaults enable them, or false disables the stack and command. */
-  goals?: agentCore.GoalConfig | false
-  /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */
-  workspaceContext: agentCore.Config['workspaceContext']
-}
-```
-
-Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`JsonlCompression`](../packages/session-persistence/session-persistence-jsonl/src/index.ts) · [`SessionReferenceConfig`](#deepseek-aidsh-session-reference) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`uiTui`](../packages/ui/tui/src/index.ts)
-
-Source: [`packages/examples/tui-demo/src/index.ts:44`](../packages/examples/tui-demo/src/index.ts)
-
 ## `@deepseek-ai/dsh-user-approval`

 ```ts config-catalog
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/extension-cookbook.md
-extension-cookbook.md: 36ab56dcdce1166ef69cec7834f6c17be72d89c3
-extension-cookbook.zh.md: 8c8f9486ec592fcc80f1053f54adce2e33798d4b
+extension-cookbook.md: 3fed79372e284df8d2cf87a3b1ca6fac6e2131ae
+extension-cookbook.zh.md: 1d422712592c7427fde785f1419633a13a55cca3
@@ -91,7 +91,7 @@ export function apply(ctx: Context) {

 ## Runnable wirings

-Runnable leaves load their plugin trees from `examples/*/cordis.yml`; the root `demo:*` scripts and those leaf directories are the authoritative inventory. Interactive leaves use [`@deepseek-ai/dsh-tui-demo`](../../packages/examples/tui-demo), non-interactive leaves use [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo), ACP leaves use [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo), and the app packages share [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo).
+Runnable leaves load their plugin trees from `examples/*/cordis.yml`; the root `demo:*` scripts and those leaf directories are the authoritative inventory. Interactive leaves use [`@deepseek-ai/dsh-tui`](../../packages/ui/tui), non-interactive leaves use [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo), ACP leaves use [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo), and the app packages share [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo).

 ## The feature → mechanism map

@@ -91,7 +91,7 @@ export function apply(ctx: Context) {

 ## 可运行的组装示例

-可运行叶子从 `examples/*/cordis.yml` 加载各自的插件树；根目录的 `demo:*` 脚本和这些叶子目录是权威清单。交互式叶子使用 [`@deepseek-ai/dsh-tui-demo`](../../packages/examples/tui-demo)，非交互式叶子使用 [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo)，ACP 叶子使用 [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo)，应用包共享 [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo)。
+可运行叶子从 `examples/*/cordis.yml` 加载各自的插件树；根目录的 `demo:*` 脚本和这些叶子目录是权威清单。交互式叶子使用 [`@deepseek-ai/dsh-tui`](../../packages/ui/tui)，非交互式叶子使用 [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo)，ACP 叶子使用 [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo)，应用包共享 [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo)。

 ## 功能→机制映射

@@ -381,7 +381,7 @@ A declarative agent entry failed before it could publish a live agent. Consumers

 Types: [SessionId](../core-data-structures/core.md)

-Source: [`packages/core/agent-loop/src/index.ts:148`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:157`](../../packages/core/agent-loop/src/index.ts)

 ## `approval/*`

@@ -44,7 +44,7 @@ async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandl

 Types: [Agent](../core-data-structures/core.md) · [AgentOptions](../core-data-structures/core.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md)

-Source: [`packages/core/agent-loop/src/index.ts:196`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:252`](../../packages/core/agent-loop/src/index.ts)

 ## `ctx.agents` — `AgentRegistry`

@@ -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
-01-first-plugin.md: b730b7ad7dc9ebd2e5dc8af4f7a83bd58ac7d4d8
-01-first-plugin.zh.md: 1e6901c048f5268ddead0faca85eaf5eef9c7533
+#   pnpm run verify-translation-pairing --write docs/cordis-tutorial/01-first-plugin.md
+01-first-plugin.md: 060f7d6296799d8db9c85bc7404a7b729d455cd2
+01-first-plugin.zh.md: 289df3d426fc4ffefd8a5439c72a6089b9745a2f
@@ -48,7 +48,7 @@ The process exits on its own once nothing is left running. What happened:
 2. The Loader read `cordis.yml`, resolved `./hello.ts`, and mounted it as a child plugin.
 3. Cordis called your `apply(ctx)`.

-There is no framework bootstrap code in your file: a plugin describes what it contributes, and `cordis.yml` composes the application. The [TUI agent](../../examples/tui-agent/cordis.yml), for example, is a longer plugin composition.
+There is no framework bootstrap code in your file: a plugin describes what it contributes, and `cordis.yml` composes the application. The [TUI agent](../../apps/cli/base.cordis.yml), for example, is a longer plugin composition.

 ## The two other plugin shapes

@@ -48,7 +48,7 @@ hello from my first plugin
 2. Loader 读取 `cordis.yml`，解析 `./hello.ts`，然后将其作为子插件挂载。
 3. Cordis 调用你的 `apply(ctx)`。

-你的文件中没有框架启动代码：插件描述自己的贡献，`cordis.yml` 则组合应用。例如，[TUI agent（智能体）](../../examples/tui-agent/cordis.yml) 就是一个更长的插件组合。
+你的文件中没有框架启动代码：插件描述自己的贡献，`cordis.yml` 则组合应用。例如，[TUI agent（智能体）](../../apps/cli/base.cordis.yml) 就是一个更长的插件组合。

 ## 其他两种插件形态

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
-development.md: 0a18e29d3da4f694707521e230017e6b22cad740
-development.zh.md: 885b51c701267215cc50d31ecd1694ae2c9af9ca
+development.md: 53e545aabb074d4ad4c5ad62722c88f9ae4c06ae
+development.zh.md: a5c95f0fb7e16b7678b5165856b0bc8e2e274d8c
@@ -143,7 +143,7 @@ The full-screen interactive coding agent needs `DEEPSEEK_API_KEY` in the environ
 pnpm run demo:tui
 ```

-The self-referential cordis-agent demo can inspect and modify its live plugin runtime and needs the same credentials:
+The self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):

 ```sh
 pnpm run demo:cordis
@@ -143,7 +143,7 @@ pnpm run demo:headless "summarize this workspace"
 pnpm run demo:tui
 ```

-自指的 cordis-agent 演示可以检查并修改其实时插件运行时，并需要相同的凭证：
+自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：

 ```sh
 pnpm run demo:cordis
@@ -7,7 +7,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac

 | Event | Mode | Declared in | Dispatchers | Listeners |
 | --- | --- | --- | --- | --- |
-| `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:148`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | [`tui`](../packages/ui/tui) |
+| `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:157`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | [`tui`](../packages/ui/tui) |
 | `agent/cancel-requested` | `emit` | [`packages/core/agent/src/types.ts:286`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal-session`](../packages/goal/goal-session) |
 | `agent/created` | `emit` | [`packages/core/agent/src/types.ts:218`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) |
 | `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:227`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) |
@@ -12,9 +12,8 @@ The process decision behind this index is recorded in [the documentation graph A
 | [module dependency graph](module-graph.md) | `generated` |
 | [tool schema catalog and package map](tool-catalog.md) | `generated` |
 | [capability seams and core services](capability-seams.md) | `hybrid generated` |
-| [tui-agent app composition](../examples/tui-agent/composition.md) | `hybrid generated` |
+| [dsh TUI composition](../apps/cli/composition.md) | `hybrid generated` |
 | [headless-agent app composition](../examples/headless-agent/composition.md) | `hybrid generated` |
-| [cordis-agent app composition](../examples/cordis-agent/composition.md) | `hybrid generated` |
 | [acp-agent app composition](../examples/acp-agent/composition.md) | `hybrid generated` |
 | [event producer/consumer matrix](event-producer-consumer.md) | `hybrid generated` |
 | [agent turn and step lifecycle](agent-lifecycle.md) | `curated` |
@@ -181,7 +181,6 @@ flowchart TD
    pkg_agent_spine_demo["agent-spine-demo"]
    pkg_cli_demo["cli-demo"]
    pkg_jsonrpc_demo["jsonrpc-demo"]
-    pkg_tui_demo["tui-demo"]
  end
  subgraph group_guard["packages/guard"]
    pkg_repeat_tool_guard["repeat-tool-guard"]
@@ -963,24 +962,6 @@ flowchart TD
  pkg_cli_demo --> pkg_session_persistence_jsonl
  pkg_cli_demo --> pkg_tools
  pkg_cli_demo --> pkg_workspace_context
-  pkg_tui_demo --> pkg_agent
-  pkg_tui_demo --> pkg_agent_loop
-  pkg_tui_demo --> pkg_agent_spine_demo
-  pkg_tui_demo --> pkg_command_goal
-  pkg_tui_demo --> pkg_commands
-  pkg_tui_demo --> pkg_invariants
-  pkg_tui_demo --> pkg_llm
-  pkg_tui_demo --> pkg_session
-  pkg_tui_demo --> pkg_session_checkpoint_policy
-  pkg_tui_demo --> pkg_session_persistence_jsonl
-  pkg_tui_demo --> pkg_session_query
-  pkg_tui_demo --> pkg_session_query_sqlite
-  pkg_tui_demo --> pkg_session_reference
-  pkg_tui_demo --> pkg_tool_ask_user
-  pkg_tui_demo --> pkg_tools
-  pkg_tui_demo --> pkg_tui
-  pkg_tui_demo --> pkg_user_interaction
-  pkg_tui_demo --> pkg_workspace_context
  pkg_sdk_client --> pkg_invariants
  pkg_sdk_client --> pkg_llm
  pkg_sdk_client --> pkg_sdk_protocol
@@ -1160,6 +1141,5 @@ flowchart TD
 | [`jsonrpc`](../packages/ui/jsonrpc) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/sdk-protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
 | [`cli-demo`](../packages/examples/cli-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
-| [`tui-demo`](../packages/examples/tui-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`command-goal`](../packages/goal/command-goal), [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`session-reference`](../packages/context/session-reference), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-interaction`](../packages/ui/user-interaction), [`workspace-context`](../packages/context/workspace-context) |
 | [`sdk-client`](../packages/sdk/sdk-client) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/sdk-protocol), [`session`](../packages/core/session) |
 | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/sdk-client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/testing.md
-testing.md: 04bd7782fa4328b6b693f13f60f4e33b463f8a18
-testing.zh.md: 5712fd8ce7b0cd46ebeb237bdd12c6c572ebe3de
+testing.md: 53f6d3c8a9c0eca61d7c5272ab78da9492ddc2a2
+testing.zh.md: 527ab0b1a0fa28fc9fd210e7955aa2280cd1850a
@@ -46,4 +46,4 @@ An e2e assertion re-runs the command or re-reads the file externally; a keyword

 ## When a snapshot test is required

-Every non-trivial model-, protocol-, or human-visible change adds or updates a keyless scenario in the same PR through a runnable example's owning snapshot suite. Package tests, e2e assertions, mock/test-only compositions, and PR rationale do not replace the assembled transcript; extend the harness when needed. ACP automation scenarios use `examples/<name>/tests/snapshots/`, a scenario table over the [`dsh-acp-snapshot`](../packages/support/acp-snapshot/README.md) suite factory (`examples/acp-agent` is primary); `examples/headless-agent` owns the `stream-json` snapshot and replay fixtures. Completed interactive-terminal journeys use JSONL-driven scenarios under `examples/tui-agent/tests/snapshots/`; transient presentation uses the package-local semantic matrix, with a PTY case when input, Loader selection, or terminal teardown changes. Browser-rendered web GUI journeys use `apps/web/tests/snapshots/`. New capability seams, lifecycle shapes, or transcript surfaces name every coverage tier at plan time and verify the harness can express it before implementation.
+Every non-trivial model-, protocol-, or human-visible change adds or updates a keyless scenario in the same PR through a runnable example's owning snapshot suite. Package tests, e2e assertions, mock/test-only compositions, and PR rationale do not replace the assembled transcript; extend the harness when needed. ACP automation scenarios use `examples/<name>/tests/snapshots/`, a scenario table over the [`dsh-acp-snapshot`](../packages/support/acp-snapshot/README.md) suite factory (`examples/acp-agent` is primary); `examples/headless-agent` owns the `stream-json` snapshot and replay fixtures. Completed interactive-terminal journeys use JSONL-driven scenarios under `apps/cli/tests/snapshots/`; transient presentation uses the package-local semantic matrix, with a PTY case when input, Loader selection, or terminal teardown changes. Browser-rendered web GUI journeys use `apps/web/tests/snapshots/`. New capability seams, lifecycle shapes, or transcript surfaces name every coverage tier at plan time and verify the harness can express it before implementation.
@@ -46,4 +46,4 @@ e2e 断言应重新运行命令或从外部重新读取文件；对 agent 自身

 ## 何时需要快照测试

-每项非平凡的模型可见、协议可见或人类可见变更，都必须在同一 PR 中，通过可运行示例所属的快照套件添加或更新无密钥场景。包测试、e2e 断言、mock 与仅测试组合、PR 理由都不能取代组装后的 transcript；必要时应扩展 harness。ACP 自动化场景使用 `examples/<name>/tests/snapshots/`，即基于 [`dsh-acp-snapshot`](../packages/support/acp-snapshot/README.md) 套件工厂的场景表（`examples/acp-agent` 为主套件）；`examples/headless-agent` 拥有 `stream-json` 快照与回放 fixture。已完成的交互式终端旅程使用 `examples/tui-agent/tests/snapshots/` 下由 JSONL 驱动的场景；瞬态呈现使用包内语义矩阵，输入、Loader 选择或终端清理发生变化时还要添加 PTY 用例。新的能力 seam、生命周期形态或 transcript 呈现接口在计划阶段就要列出每个覆盖层级，并在实现前验证 harness 能够表达它们。
+每项非平凡的模型可见、协议可见或人类可见变更，都必须在同一 PR 中，通过可运行示例所属的快照套件添加或更新无密钥场景。包测试、e2e 断言、mock 与仅测试组合、PR 理由都不能取代组装后的 transcript；必要时应扩展 harness。ACP 自动化场景使用 `examples/<name>/tests/snapshots/`，即基于 [`dsh-acp-snapshot`](../packages/support/acp-snapshot/README.md) 套件工厂的场景表（`examples/acp-agent` 为主套件）；`examples/headless-agent` 拥有 `stream-json` 快照与回放 fixture。已完成的交互式终端旅程使用 `apps/cli/tests/snapshots/` 下由 JSONL 驱动的场景；瞬态呈现使用包内语义矩阵，输入、Loader 选择或终端清理发生变化时还要添加 PTY 用例。新的能力 seam、生命周期形态或 transcript 呈现接口在计划阶段就要列出每个覆盖层级，并在实现前验证 harness 能够表达它们。
@@ -19,7 +19,7 @@ This table connects model-visible tool names to the plugin package and service s
 | `@deepseek-ai/dsh-tools` | `run_code` | `ctx.tools`, `ctx.codeRuntime (execution time)`, `ctx.systemPrompt` | `tool/call`, `one tool/code-dispatch-start + tool/code-dispatch pair per bridged sub-call`, `tool/result` | - | Owned by the tool registry as a reserved transport outside filterable capability layers under `mode: code` / `mode: both` (see the Code Mode Agent Note). Under `code` it is the registry's only wire contribution; the other visible capabilities are declared in a generated TypeScript SDK section, and a program calls them through bindings scheduled under the native concurrency contract (submission-ordered starts and policy; concurrency-safe bodies overlap up to `maxParallelSubCalls`) that re-enter the complete guarded tool pipeline and link each nested execution to this outer result. |
 | `@deepseek-ai/dsh-plan-mode` | `exit_plan_mode` | `ctx.tools`, `ctx.systemPrompt`, `ctx.userInteraction (execution time, opportunistic)` | `tool/call`, `plan/mode inactive on an approved review`, `tool/result` | - | exit_plan_mode stays in the model-facing schema while planning is inactive so transitions add no tool-catalog churn on top of the plan-policy change. Its execute path rejects calls outside plan mode; in plan mode it presents the plan over the user-interaction seam (approve / keep planning with feedback), and approval logs plan mode inactive at the step boundary. |
 | `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`, `ctx.bash`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The bash tool is the model-facing consumer of the bash executor seam. A `run_in_background` run registers with the generic `ctx.tasks` runtime and is collected/stopped through the `task_*` tools from `@deepseek-ai/dsh-tool-tasks`; the `enableRunInBackground` config (default true) removes the parameter entirely when disabled. |
-| `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`, `cordis_mount`, `cordis_unmount` | `ctx.tools` | `tool/call`, `tool/result`, `process-local temporary Plugin lifecycle` | - | Ships in examples/cordis-agent only (a deliberate opt-in — temporary Plugin code reaches the real runtime, see .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins created by cordis_mount may register ADDITIONAL model-visible tools until unmounted or DSH restarts; a full changed request header logs those tool-set changes. |
+| `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`, `cordis_mount`, `cordis_unmount` | `ctx.tools` | `tool/call`, `tool/result`, `process-local temporary Plugin lifecycle` | - | Not in any shipped tree (a deliberate opt-in — temporary Plugin code reaches the real runtime, see .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins created by cordis_mount may register ADDITIONAL model-visible tools until unmounted or DSH restarts; a full changed request header logs those tool-set changes. |
 | `@deepseek-ai/dsh-tool-fs` | `edit`, `read`, `write` | `ctx.tools`, `ctx.fs`, `ctx.systemPrompt` | `tool/call`, `fs/write-intent or fs/edit-intent for mutations`, `fs/observed after successful file operations`, `tool/result` | - | The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. |
 | `@deepseek-ai/dsh-tool-fs-search` | `glob`, `grep` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | glob and grep are conditional bash-backed discovery tools: they register only when ctx.bash can find `rg`, then run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. |
 | `@deepseek-ai/dsh-tool-pty` | `terminal_close`, `terminal_list`, `terminal_open`, `terminal_read`, `terminal_send`, `terminal_signal` | `ctx.tools`, `ctx.pty`, `ctx.systemPrompt`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The six terminal tools are opt-in and complement one-shot bash/filesystem tools. `terminal_send(run_in_background: true)` registers with `ctx.tasks`; TUI, named key sequences, BEL, resize, auto-start, and cross-agent sharing are absent from the schema. |
@@ -28,7 +28,7 @@ This table connects model-visible tool names to the plugin package and service s
 | `@deepseek-ai/dsh-tool-ralph` | `ralph` | `ctx.tools`, `ctx.workflows`, `ctx.subagents`, `ctx.systemPrompt`, `a calling Agent (exec.agent parents every fresh round)` | `tool/call`, `tool/result`, `workflow and child session events during execution` | - | A fixed foreground workflow starts one fresh structured child per round; the model selects only the immutable objective and an optional round cap. |
 | `@deepseek-ai/dsh-tool-skill` | `skill` | `ctx.tools`, `ctx.skills` | `tool/call`, `tool/result` | - | - |
 | `@deepseek-ai/dsh-tool-session-query` | `session_event_read`, `session_event_search`, `session_event_trace`, `session_search`, `session_trace` | `ctx.tools`, `ctx.systemPrompt`, `ctx.sessionQuery`, `a calling Agent for workspace authority` | `tool/call`, `tool/result` | - | The five read-only tools hide provider cursors and authorize every result from the immutable calling agent session. The package is opt-in; compositions that need enforced deadlines or bounded inline output also mount the generic timeout or spill policies. |
-| `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`, `ctx.subagents` | `tool/call`, `tool/result`, `child session events through the chosen provider` | `subagent`, `subagent_fork` | The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/tui-agent/cordis.yml` and `examples/acp-agent/cordis.yml`. |
+| `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`, `ctx.subagents` | `tool/call`, `tool/result`, `child session events through the chosen provider` | `subagent`, `subagent_fork` | The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `apps/cli/base.cordis.yml` and `examples/acp-agent/cordis.yml`. |
 | `@deepseek-ai/dsh-tool-tasks` | `task_kill`, `task_list`, `task_output` | `ctx.tools`, `ctx.tasks`, `ctx.systemPrompt` | `tool/call`, `tool/result`, `user/message via agent.inject() for background completion notices` | - | The kind-agnostic background-task control surface: background bash commands, PTY sends, and subagents are read, listed, and killed through the same three tools. Loading the plugin attaches the control surface that arms producers' `ctx.tasks.start()`. |
 | `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`, `owning Agent session` | `tool/call`, `todo/write`, `tool/result` | - | todo_write is session-owned state; UIs render the latest todo/write event as a checklist. |
 | `@deepseek-ai/dsh-tool-workflow` | `workflow` | `ctx.tools`, `ctx.workflows`, `ctx.systemPrompt`, `a calling Agent (exec.agent parents the script children)` | `tool/call`, `tool/result` | - | - |
@@ -277,7 +277,7 @@ Unmount a current-process temporary Plugin created by cordis_mount. Waits for it

 Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cordis/src/index.ts)

-Ships in examples/cordis-agent only (a deliberate opt-in — temporary Plugin code reaches the real runtime, see .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins created by cordis_mount may register ADDITIONAL model-visible tools until unmounted or DSH restarts; a full changed request header logs those tool-set changes.
+Not in any shipped tree (a deliberate opt-in — temporary Plugin code reaches the real runtime, see .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins created by cordis_mount may register ADDITIONAL model-visible tools until unmounted or DSH restarts; a full changed request header logs those tool-set changes.

 ## `@deepseek-ai/dsh-tool-fs`

@@ -1049,7 +1049,7 @@ Delegate a self-contained task to a subagent (a separate agent that works in its

 Source: [`packages/subagent/tool-subagent/src/index.ts`](../packages/subagent/tool-subagent/src/index.ts)

-The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/tui-agent/cordis.yml` and `examples/acp-agent/cordis.yml`.
+The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `apps/cli/base.cordis.yml` and `examples/acp-agent/cordis.yml`.

 ## `@deepseek-ai/dsh-tool-tasks`

--- a/Show More
+++ b/Show More