Merge remote-tracking branch 'origin/master' into perf/tui-resume-scan

# Conflicts: # packages/ui/tui/README.i18n.yaml
2026-08-03 13:37:53 +08:00
parent 6792a12d8c 4d6bf76326
commit 776cc6889a
788 changed files with 30113 additions and 3651 deletions
--- a/packages/ui/app-boot/README.i18n.yaml
+++ b/packages/ui/app-boot/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/ui/app-boot/README.md
-README.md: ebd8e0842b934f6887e3c122e781c1d0f13bb5d3
-README.zh.md: ccd897d48178482aa74d0eb73505e26ec3a08d6c
+README.md: 2eb9e904d574df39b0884558fc0a53f9dc04cdc1
+README.zh.md: 78bd99943fcadebf42a5d772d49f3bfcf6a8790a
--- a/packages/ui/app-boot/README.md
+++ b/packages/ui/app-boot/README.md
@@ -8,17 +8,19 @@ Shared boot glue for the app bins ([`dsh`](../../../apps/cli/README.md), [`dsh-c
 |---|---|
 | `resolveConfigPath(path, snapshotMode, cwd?)` | Absolute config path; `snapshotMode === 'replay'` swaps a `cordis.yml`/`.yaml` basename for its sibling `cordis.snapshot.yml` |
 | `loadEnv(binName, dir?, warn?)` | Load the gitignored `.env` (Node `process.loadEnvFile`); absent file is fine, an unloadable one warns a single labelled line (default: stderr) |
-| `installFailLoud(binName, proc?)` | Turn a post-`boot()` unhandled Loader rejection into one labelled stderr line + `exit(1)`; returns the uninstaller (for tests) |
+| `installFailLoud(binName, proc?)` | Turn an unhandled boot or later Loader rejection into one labelled stderr line + `exit(1)`; returns the uninstaller (for tests) |
 | `assertEntriesLoaded(ctx, binName)` | Throw when a settled tree holds an enabled entry with no fiber, reporting every unresolved plugin name as a Cordis startup failure |
 | `assertEntriesActivated(ctx, binName)` | Include the `assertEntriesLoaded` check, then await every enabled entry after the Loader settles; throw with each failed plugin's original stack or each pending plugin's unresolved services |
 | `loadPersonalPatches(binName, dir?)` | Parse the optional `config.yaml` in the Harness home (default [`resolveDshHome()`](../../util/paths/README.md): `$DSH_HOME`, else `~/.dsh`) — a top-level YAML array of include `PatchOptions` (id-targeted config overrides, `insert` lists, `!!js` allowed); absent file → `undefined`, an unreadable/unparsable/non-array file throws |
 | `loadOverlayPatches(binName, file)` | Parse a required patch-list file with the same shape as personal config; read or parse failures throw a labelled error |
-| `boot(binName, absoluteConfigPath, patches?, prepare?)` | Create the root context, expose `dshHomePath(...segments)` to Loader `!!js` config expressions, install Loader, run optional host preparation before config-tree entries mount (`prepare` may use Loader and provide launcher-owned context slots such as [`MAIN_SESSION_ID_KEY`](../tui/README.md)), then mount and await the include tree, assert entries loaded and activated, and return the root context |
+| `mountRootInclude(ctx, absoluteConfigPath, patches?)` | Mount the statically imported Include builtin and retain the exact root entry used by personal-config HMR |
+| `watchPersonalPatches(ctx, options)` | Register `$DSH_HOME/config.yaml` with the existing Cordis HMR service; each add/change/removal transactionally recomposes the full patch list through the caller's `compose` closure (app-owned layers around the current personal overlay) and returns an async disposer |
+| `boot(binName, absoluteConfigPath, patches?, prepare?)` | Create the root context, expose `dshHomePath(...segments)` to Loader `!!js` config expressions, install Loader, run optional host preparation before config-tree entries mount (`prepare` may use Loader and provide launcher-owned context slots such as [`MAIN_SESSION_ID_KEY`](../tui/README.md)), then mount and await the include tree, assert entries loaded and activated, and return the root context — or dispose the partial context and reject a labelled error |
 | `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | Compose the base config and labeled overlay layers offline — the include's own parser and patch algorithm (`entryListSchema`/`applyEntryPatches`), so the result equals what `boot()` mounts — and render YAML with `!!js` expressions verbatim; each run of same-provenance rows is preceded by a `# ==` comment naming the contributing file and the layers that patched it, keeping the output one loadable document; a patch matching no row goes to `warn` with its layer label (default: one stderr line), read/parse/shape failures throw |
-| `addHarnessSourceSection(ctx, sourceRoot)` | Add a global `harness:source` prompt section (ordered just after the harness identity, before the persona) telling the agent the on-disk path to its own source checkout; a no-op returning `undefined` when the booted tree has no `systemPrompt` service. The section is registered against that service's fiber, so a dev HMR reload of the system prompt drops it until the next boot |
+| `addHarnessSourceSection(ctx, sourceRoot)` | Add a global `harness:source` prompt section (ordered just after the harness identity, before the persona) telling the agent the on-disk path to the DSH implementation checkout while warning it not to infer the current working directory from that path and to use `pwd` instead; a no-op returning `undefined` when the booted tree has no `systemPrompt` service. The section is registered against that service's fiber, so a dev HMR reload of the system prompt drops it until the next boot |
 | `HARNESS_SOURCE_SECTION` | The `'harness:source'` section name `addHarnessSourceSection` registers under |

-Two Loader failure classes require separate guards because tree settlement propagates neither to its caller. A failed plugin import leaves a fiber-less entry that `assertEntriesLoaded` turns into a `boot()` rejection naming every unresolved plugin. A plugin callback or config failure leaves a failed fiber because `loader.await()` settles lifecycle tasks without propagating that error; `assertEntriesActivated` awaits the fiber explicitly and includes its original stack in the startup rejection. Before throwing, the audit marks those exact rejection reasons through one process checkpoint so `installFailLoud` coalesces Loader's duplicate notification while every unrelated unhandled rejection remains fatal.
+Loader settlement rejects import and lifecycle failures with the failing entry and stage; `boot()` disposes the partial context and wraps that failure with the bin name. Entries settlement leaves behind are audited separately: `assertEntriesLoaded` turns an enabled fiber-less entry into a rejection naming every unresolved plugin, and `assertEntriesActivated` awaits each failed fiber to include its original stack in the startup rejection and names each pending entry's unresolved services. Before throwing, the audit marks those exact rejection reasons through one process checkpoint so `installFailLoud` coalesces Loader's duplicate notification while every unrelated unhandled rejection remains fatal.

 Bare plugin specifiers in a config (`@deepseek-ai/dsh-*`, npm packages) resolve through the Cordis Loader's internal module loader. Repository bins install Loader's optional `node-addon-require-builtin` peer; external callers must supply it or install plugins where plain Node import resolution can find them. Relative specifiers resolve against the config directory without the native helper. The built `dsh-app-boot` artifact embeds the statically mounted Include implementation while leaving Loader external, so the include tree and host bind to one Loader peer. The `dsh` source launcher additionally maps manifest-declared workspace packages to their TypeScript source; its configuration gate requires every TUI/Web bare plugin to appear in the resolver manifest's `dependencies`. The bins' subprocess smokes exercise the internal-loader path, while this package's unit suite drives `boot()` in-process against configs with relative specifiers.

@@ -26,11 +28,13 @@ This package carries no loader hooks and no dev-mode surface. The [`dsh` app](..

 ## Personal config

-A developer's machine-local preferences live outside every repository in the Harness home (default `~/.dsh`, overridable via `$DSH_HOME`; the single root [`resolveDshHome`](../../util/paths/README.md) resolves), consumed by the official `dsh` surfaces ([`apps/cli`](../../../apps/cli/README.md)); the demo bins boot their committed trees verbatim. Two optional files:
+A developer's machine-local preferences live outside every repository in the Harness home (default `~/.dsh`, overridable via `$DSH_HOME`; the single root [`resolveDshHome`](../../util/paths/README.md) resolves), consumed by the `dsh` CLI's TUI, Web, and headless surfaces ([`apps/cli`](../../../apps/cli/README.md)); the demo bins boot their committed trees verbatim. Two optional files:

 - **`.env`** — the credential store of [`dsh-credentials-local`](../../credentials/credentials-local/README.md), read by that provider alone. No surface hoists it into `process.env`: doing so would make every stored key look like a read-only launch override on the next run, blocking rotation from the TUI and the web page. The environment layers are the ambient one and the invoking directory's `.env` (loaded by the bin; `process.loadEnvFile` never overrides), and a composition without the credential provider keeps resolving keys from those alone.
 - **`config.yaml`** — loader overlay patches applied over the shipped default config, with the same semantics as the shipped surface overlays: an id-targeted patch replaces the named entry's whole `config` (restate unchanged fields), `insert` adds entries, and `!!js` expressions interpolate at mount. A patch naming an entry id absent from the booted tree is a silent no-op. An empty or comments-only file throws (it parses to nothing, not to a list); disable the overlay with `[]` or by deleting the file.

+The TUI and Web keep `config.yaml` live through `watchPersonalPatches`; one-shot headless runs read only the startup value. The watcher targets the exact personal path even when the file or immediate parent does not exist, serializes bursts, and recomposes the personal patches inside the caller's layer order (surface overlay below, app-generated patches above). A rejected read, parse, or Loader candidate leaves the last good tree running and the HMR service broadcasts `hmr/config-update-failed(filename, Error)` after logging it; observer failures are contained. Disposing the context closes the watcher and drains an active refresh.
+
 Subprocess test launchers point `DSH_HOME` at an isolated per-test directory so a developer's personal overlay can never leak into fixtures.

 ## Model Experience
--- a/packages/ui/app-boot/README.zh.md
+++ b/packages/ui/app-boot/README.zh.md
@@ -8,17 +8,19 @@
 |---|---|
 | `resolveConfigPath(path, snapshotMode, cwd?)` | 生成绝对配置路径；当 `snapshotMode === 'replay'` 时，把 basename 为 `cordis.yml`/`.yaml` 的文件替换为同级 `cordis.snapshot.yml` |
 | `loadEnv(binName, dir?, warn?)` | 加载已被 git 忽略的 `.env`（Node `process.loadEnvFile`）；文件不存在不影响启动，文件无法加载时输出一行带标签的警告（默认写入 stderr） |
-| `installFailLoud(binName, proc?)` | 将 `boot()` 之后未处理的 Loader rejection 转换为一行带标签的 stderr 消息并执行 `exit(1)`；返回卸载函数（供测试使用） |
+| `installFailLoud(binName, proc?)` | 将启动期或后续未处理的 Loader rejection 转换为一行带标签的 stderr 消息并执行 `exit(1)`；返回卸载函数（供测试使用） |
 | `assertEntriesLoaded(ctx, binName)` | 树结算后，如果其中存在已启用但没有 fiber 的条目，则抛出异常，并以 Cordis 启动故障的形式报告每个未解析插件的名称 |
 | `assertEntriesActivated(ctx, binName)` | 先执行 `assertEntriesLoaded` 检查，再在 Loader 结算后等待每个已启用配置项；抛出的错误包含每个失败插件的原始错误堆栈，或每个等待中插件尚未解析的服务 |
 | `loadPersonalPatches(binName, dir?)` | 解析 Harness home 中可选的 `config.yaml`（默认使用 [`resolveDshHome()`](../../util/paths/README.md)：先取 `$DSH_HOME`，否则取 `~/.dsh`）：其顶层是一个 YAML 数组，内容为 include 的 `PatchOptions`（按 id 定位的配置覆盖、`insert` 列表，允许 `!!js`）；文件不存在时返回 `undefined`，文件不可读、不可解析或内容不是数组时抛出异常 |
 | `loadOverlayPatches(binName, file)` | 解析一份必需的 patch 列表文件，其形状与个人配置相同；读取或解析失败时抛出带标签的错误 |
-| `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文，向 Loader `!!js` 配置表达式暴露 `dshHomePath(...segments)` 并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（`prepare` 可以使用 Loader，也可以提供由启动器拥有的上下文插槽，例如 [`MAIN_SESSION_ID_KEY`](../tui/README.md)），再挂载并等待 include 树结算，断言所有条目均已加载并激活，最后返回根上下文 |
+| `mountRootInclude(ctx, absoluteConfigPath, patches?)` | 挂载静态导入的 Include builtin，并保留个人配置 HMR（热模块替换）使用的确切根配置项 |
+| `watchPersonalPatches(ctx, options)` | 向现有 Cordis HMR 服务注册 `$DSH_HOME/config.yaml`；每次新增、变更或移除都会通过调用方的 `compose` 闭包（应用自有层围绕当前个人 overlay）以事务方式重新组合完整 patch 列表，并返回异步 disposer |
+| `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文，向 Loader `!!js` 配置表达式暴露 `dshHomePath(...segments)` 并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（`prepare` 可以使用 Loader，也可以提供由启动器拥有的上下文插槽，例如 [`MAIN_SESSION_ID_KEY`](../tui/README.md)），再挂载并等待 include 树结算，断言所有条目均已加载并激活，最后返回根上下文——失败时 dispose（资源释放）部分构造的上下文，并以带标签的错误 reject |
 | `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | 离线合成基础配置与带标签的覆盖层——使用 include 自己的解析器和补丁算法（`entryListSchema`/`applyEntryPatches`），因此结果与 `boot()` 挂载的内容一致——并渲染为 YAML，`!!js` 表达式原样保留；每段来源相同的连续行之前都有一条 `# ==` 注释，标明贡献该段的文件以及修补过它的层，输出仍是一份可加载的文档；未匹配到行的补丁连同其层标签交给 `warn`（默认：一行 stderr），读取／解析／形状失败则抛出 |
-| `addHarnessSourceSection(ctx, sourceRoot)` | 添加全局 `harness:source` 提示词段落（顺序紧随 harness 身份、位于 persona 之前），告知 agent（智能体）自身源代码 checkout 的磁盘路径；如果已启动树没有此项服务，则不执行操作并返回 `undefined`。这里的服务是 `systemPrompt`；该段落注册到它的 fiber，因此开发环境 HMR（热模块替换）重新加载系统提示词后，它会消失直至下次启动 |
+| `addHarnessSourceSection(ctx, sourceRoot)` | 添加全局 `harness:source` 提示词段落（顺序紧随 harness 身份、位于 persona 之前），告知 agent（智能体）DSH 实现代码 checkout 的磁盘路径，同时提醒它不得据此推断当前工作目录，而应使用 `pwd`；如果已启动树没有此项服务，则不执行操作并返回 `undefined`。这里的服务是 `systemPrompt`；该段落注册到它的 fiber，因此开发环境 HMR（热模块替换）重新加载系统提示词后，它会消失直至下次启动 |
 | `HARNESS_SOURCE_SECTION` | `'harness:source'` 段落名称，供 `addHarnessSourceSection` 注册使用 |

-Loader 树结算不会向调用方传播两类故障，因此需要分别保护。插件导入失败会留下没有 fiber 的配置项，`assertEntriesLoaded` 将其转换为 `boot()` rejection，并列出每个未解析插件。插件回调或配置失败则会留下失败的 fiber，因为 `loader.await()` 只结算生命周期任务，不传播该错误；`assertEntriesActivated` 会显式等待该 fiber，并把原始错误堆栈写入启动 rejection。抛出错误前，审计会通过一个进程级检查点标记这些 rejection 的确切原因，从而让 `installFailLoud` 将 Loader 的重复通知合并为一次，而所有无关的未处理 rejection 仍然致命。
+Loader 结算会在导入或生命周期失败时 reject，并携带失败的配置项与阶段；`boot()` 会 dispose 部分构造的上下文，并用 bin 名称包装该失败。结算后遗留的配置项由独立审计处理：`assertEntriesLoaded` 将已启用却没有 fiber 的配置项转换为 rejection 并列出每个未解析插件；`assertEntriesActivated` 会显式等待每个失败的 fiber，把原始错误堆栈写入启动 rejection，并列出每个等待中配置项尚未解析的服务。抛出错误前，审计会通过一个进程级检查点标记这些 rejection 的确切原因，从而让 `installFailLoud` 将 Loader 的重复通知合并为一次，而所有无关的未处理 rejection 仍然致命。

 配置中的裸插件 specifier（`@deepseek-ai/dsh-*`、npm 包（package））通过 Cordis Loader 的内部模块 loader 解析。仓库 bin 会安装 Loader 的可选 peer `node-addon-require-builtin`；外部调用方必须提供该组件，或者把插件安装到普通 Node import 解析可以找到的位置。相对 specifier 无需原生 helper，并以配置目录为基准解析。构建后的 `dsh-app-boot` 产物内嵌静态挂载的 Include 实现，但仍将 Loader 保持为外部依赖，因此 include 树与 host 会绑定到同一个 Loader peer。`dsh` 源码启动器还会将 manifest（元数据清单）声明的 workspace 包映射到其 TypeScript 源码；其配置门禁要求每个 TUI／Web 裸插件都出现在解析所用 manifest 的 `dependencies` 中。bin 的子进程冒烟测试覆盖内部 loader 路径，而本包的单元测试套件会在进程内使用相对 specifier 配置驱动 `boot()`。

@@ -26,11 +28,13 @@ Loader 树结算不会向调用方传播两类故障，因此需要分别保护

 ## 个人配置

-开发者的机器本地偏好位于所有仓库之外的 Harness home 中（默认 `~/.dsh`，可由 `$DSH_HOME` 覆盖；统一由根级 [`resolveDshHome`](../../util/paths/README.md) 解析），并由官方 `dsh` 界面（[`apps/cli`](../../../apps/cli/README.md)）使用；demo bin 会原样启动仓库中提交的树。这里有两个可选文件：
+开发者的机器本地偏好位于所有仓库之外的 Harness home 中（默认 `~/.dsh`，可由 `$DSH_HOME` 覆盖；统一由根级 [`resolveDshHome`](../../util/paths/README.md) 解析），并由 `dsh` CLI（命令行界面）的 TUI、Web 和无头界面（[`apps/cli`](../../../apps/cli/README.md)）使用；demo bin 会原样启动仓库中提交的树。这里有两个可选文件：

 - **`.env`**：[`dsh-credentials-local`](../../credentials/credentials-local/README.md) 的凭据存储，只由该 provider 读取。没有任何表层会把它提升进 `process.env`：那样做会让每个已存密钥在下次运行时看起来都像只读的启动时覆盖，从而阻断从 TUI 与 Web 页面轮换密钥。环境层次由环境中的值与调用目录的 `.env` 构成（由 bin 加载；`process.loadEnvFile` 从不覆盖已有值），没有凭据 provider 的组合仍然只从这两者解析密钥。
 - **`config.yaml`**：在发布的默认配置上应用 Loader overlay patch，语义与交付的 surface overlay 相同：按 id 定位的 patch 会替换对应条目的整个 `config`（未改字段也要重述），`insert` 会添加条目，`!!js` 表达式则在挂载时插值。如果 patch 指定的条目 id 不在已启动树中，则静默不执行任何操作。空文件或仅含注释的文件会抛出异常（其解析结果为空，而不是列表）；如需禁用 overlay，请使用 `[]` 或删除该文件。

+TUI 和 Web 会持续应用 `config.yaml` 的变更，具体由 `watchPersonalPatches` 负责；一次性无头运行只读取启动时的值。即使该文件或其直接父目录不存在，watcher 仍会监视确切的个人配置路径；它会串行处理突发变更，并按调用方的层次顺序重新组合个人 patch（surface overlay 在下、应用生成的 patch 在上）。读取失败、解析失败或 Loader 候选被拒时，最后一个可用树会继续运行；HMR 服务记录错误后广播 `hmr/config-update-failed(filename, Error)`，并隔离 observer 失败。上下文 dispose 时会关闭 watcher，并等待进行中的刷新结束。
+
 子进程测试 launcher 会把 `DSH_HOME` 指向逐测试隔离的目录，确保开发者的个人 overlay 不会泄漏到 fixture（测试前置数据）中。

 ## 模型体验
--- a/packages/ui/app-boot/package.json
+++ b/packages/ui/app-boot/package.json
@@ -30,6 +30,7 @@
    "js-yaml": "^4.2.0"
  },
  "peerDependencies": {
+    "@cordisjs/plugin-hmr": "^1.0.15",
    "@cordisjs/plugin-include": "^1.0.4",
    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
    "@deepseek-ai/dsh-invariants": "^0.0.1",
@@ -37,9 +38,16 @@
    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
    "cordis": "^4.0.0-rc.7"
  },
+  "peerDependenciesMeta": {
+    "@cordisjs/plugin-hmr": {
+      "optional": true
+    }
+  },
  "devDependencies": {
+    "@cordisjs/plugin-hmr": "workspace:^",
    "@cordisjs/plugin-include": "workspace:^",
    "@cordisjs/plugin-loader": "workspace:^",
+    "@cordisjs/plugin-timer": "workspace:^",
    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-paths": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
--- a/packages/ui/app-boot/src/index.ts
+++ b/packages/ui/app-boot/src/index.ts
@@ -11,9 +11,10 @@ import { readFileSync } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
 import * as yaml from 'js-yaml'
 import { Context, type FiberState } from 'cordis'
-import Loader from '@cordisjs/plugin-loader'
+import Loader, { type Entry, type EntryOptions } from '@cordisjs/plugin-loader'
 import Include, { applyEntryPatches, entryListSchema, type PatchOptions } from '@cordisjs/plugin-include'
 import { dshHomePath, resolveDshHome } from '@deepseek-ai/dsh-paths'
+import type {} from '@cordisjs/plugin-hmr'
 // Side-effect type import: resolves `ctx.get('systemPrompt')` to the service.
 import type {} from '@deepseek-ai/dsh-system-prompt'

@@ -67,6 +68,8 @@ export function loadEnv(
 /** File inside the Harness home holding the personal loader overlay patches. */
 export const PERSONAL_CONFIG_FILENAME = 'config.yaml'

+const bootstrapIncludes = new WeakMap<Context, Entry>()
+
 // The include's YAML dialect (`!!js` scalars become expression nodes the
 // Loader interpolates against each entry's context at mount time), imported
 // from the include itself so patch parsing and config dumping can never drift
@@ -287,6 +290,99 @@ function groupedDump(
  return lines.join('\n') + '\n'
 }

+/** Options for live personal-config reconciliation. */
+export interface PersonalPatchWatchOptions {
+  /** Diagnostic prefix used by {@link loadPersonalPatches}. */
+  binName: string
+  /** Harness home containing `config.yaml`; defaults to {@link resolveDshHome}. */
+  dir?: string
+  /**
+   * Compose the full patch list for a fresh personal-overlay generation —
+   * the same composition the app booted with, so a reload can interleave the
+   * new personal patches between app-owned layers (surface overlay below,
+   * profile/flag patches above). Identity when omitted: the personal overlay
+   * is the whole patch list.
+   */
+  compose?: (personalPatches: PatchOptions[]) => PatchOptions[]
+}
+
+/**
+ * Watch the personal overlay through Cordis HMR and transactionally reapply it to the boot include.
+ * @param ctx - settled app context containing the root Include and an active HMR service.
+ * @param options - diagnostic, Harness-home, and patch-composition inputs.
+ * @returns an asynchronous disposer after the exact-path watcher is ready.
+ * @throws when HMR or the root Include is absent, watcher setup fails, or initial path resolution fails.
+ */
+export async function watchPersonalPatches(
+  ctx: Context,
+  options: PersonalPatchWatchOptions,
+): Promise<() => Promise<void>> {
+  const { binName, dir = resolveDshHome(), compose = (patches: PatchOptions[]) => patches } = options
+  const hmr = ctx.get('hmr')
+  if (hmr === undefined) throw new Error(`${binName}: personal config watching requires the Cordis HMR service`)
+  const entry = bootstrapIncludes.get(ctx)
+  if (entry === undefined) throw new Error(`${binName}: personal config watching requires the root Include entry`)
+  const filename = join(dir, PERSONAL_CONFIG_FILENAME)
+  const register = hmr.registerConfig(filename, async () => {
+    // Re-read the include's non-patch options per refresh: a writer that
+    // updates the root Include's other options between refreshes (none exists
+    // today) must not have them silently reverted by a personal reload.
+    const { patches: _previousPatches, ...includeConfig } = entry.options.config as Include.Config
+    const personalPatches = loadPersonalPatches(binName, dir) ?? []
+    const patches = compose(personalPatches)
+    await entry.update({
+      config: {
+        ...includeConfig,
+        patches,
+      },
+    })
+  })
+  try {
+    return await register
+  } catch (error) {
+    // A surface can dispose the whole tree while the watcher is still opening
+    // (a TUI `/exit` typed during startup): the HMR effect registration then
+    // fails with INACTIVE_EFFECT. That is the app exiting exactly as asked,
+    // not a watch failure — return a no-op disposer instead of crashing.
+    if ((error as { code?: string } | null)?.code === 'INACTIVE_EFFECT') return async () => {}
+    throw error
+  }
+}
+
+/**
+ * Mount and remember the exact root Include entry used by app boot and personal-config HMR.
+ * @param ctx - context carrying an initialized Loader service.
+ * @param absoluteConfigPath - absolute YAML or JSON configuration path.
+ * @param patches - initial app and personal patches, applied in order.
+ * @returns the created root Include entry, or `undefined` when a surface
+ * disposed the whole tree (taking the Loader service with it) while the
+ * transactional create was still settling entry lifecycle.
+ */
+export async function mountRootInclude(
+  ctx: Context,
+  absoluteConfigPath: string,
+  patches: readonly PatchOptions[] = [],
+): Promise<Entry | undefined> {
+  ctx.loader.builtins.include = Include
+  // Pinned id: the bootstrap include is app glue, not a config row, and its
+  // id appears in Loader failure chains — a random id would make startup
+  // diagnostics unstable across runs (and snapshot fixtures).
+  const rootInclude: EntryOptions = {
+    id: 'include',
+    name: 'cordis:include',
+    config: {
+      path: pathToFileURL(absoluteConfigPath).href,
+      ...patches.length > 0 ? { patches: [...patches] } : {},
+    },
+  }
+  const includeId = await ctx.loader.create(rootInclude)
+  const loader = ctx.get('loader')
+  if (loader === undefined) return undefined
+  const entry = loader.resolve(includeId)
+  bootstrapIncludes.set(ctx, entry)
+  return entry
+}
+
 /**
 * The slice of `process` {@link installFailLoud} needs — injectable so tests
 * exercise the handler without registering on (or exiting) the real process.
@@ -430,12 +526,13 @@ export async function assertEntriesActivated(ctx: Context, binName: string): Pro
 * `cordis:include` builtin, loading through the ambient module pipeline
 * (vite/tsx/plain ESM) while the included tree's own specifiers stay
 * config-relative. The package build embeds Include while leaving Loader
- * external, so the built include tree and host share one Loader peer. A
- * missing fiber rejects here; a later init rejection is rethrown with its
- * original stack by {@link assertEntriesActivated}; later unhandled
- * rejections remain covered by {@link installFailLoud}. Built bins need the
- * Loader's native helper for bare plugin specifiers; relative specifiers do
- * not.
+ * external, so the built include tree and host share one Loader peer. Loader
+ * settlement rejects startup failures, which `boot` wraps after disposing the
+ * partial context; a missing fiber or never-activating entry is rejected by
+ * the final audit, {@link assertEntriesActivated}, which rethrows a plugin's
+ * init rejection with its original stack; later unhandled rejections remain
+ * covered by {@link installFailLoud}. Built bins need the Loader's native
+ * helper for bare plugin specifiers; relative specifiers do not.
 * @param binName - the diagnostic prefix for load-failure errors.
 * @param absoluteConfigPath - the config to include; must already be absolute
 * (see {@link resolveConfigPath}).
@@ -444,6 +541,9 @@ export async function assertEntriesActivated(ctx: Context, binName: string): Pro
 * @param prepare - optional host setup run after Loader installation and before any config-tree entry mounts.
 * @returns the root context once every entry has started, or as soon as a
 * surface disposed the tree while startup was still in flight.
+ * @throws a labelled error after disposing the partial context — `host
+ * preparation failed` when `prepare` threw before any config-tree entry
+ * mounted, `plugin tree failed to load` afterwards.
 */
 export async function boot(
  binName: string,
@@ -452,39 +552,55 @@ export async function boot(
  prepare?: (ctx: Context) => Promise<void> | void,
 ): Promise<Context> {
  const ctx = new Context()
-  ctx.baseUrl = pathToFileURL(dirname(absoluteConfigPath)).href + '/'
-  ctx.provide('dshHomePath', dshHomePath)
-  await ctx.plugin(Loader)
-  ctx.loader.builtins.include = Include
-  await prepare?.(ctx)
-  await ctx.loader.create({
-    name: 'cordis:include',
-    config: {
-      path: pathToFileURL(absoluteConfigPath).href,
-      ...patches !== undefined && patches.length > 0 ? { patches } : {},
-    },
-  })
-  await ctx.loader.await()
-  // A surface can finish and dispose the whole tree while that await is still
-  // pending: the TUI renders as soon as its own fiber starts, so an `/exit`
-  // typed before the last entry settles tears the context down under us. The
-  // Loader service goes with it, and the activation audit describes a live
-  // tree — reading `ctx.loader` here would throw a TypeError over an app that
-  // exited exactly as asked.
-  if (ctx.get('loader') === undefined) return ctx
-  await assertEntriesActivated(ctx, binName)
-  return ctx
+  // Two failure labels: `prepare` runs before any config-tree entry mounts,
+  // so its failure is host setup, not the plugin tree.
+  let stage = 'host preparation failed'
+  try {
+    ctx.baseUrl = pathToFileURL(dirname(absoluteConfigPath)).href + '/'
+    ctx.provide('dshHomePath', dshHomePath)
+    await ctx.plugin(Loader)
+    await prepare?.(ctx)
+    stage = 'plugin tree failed to load'
+    await mountRootInclude(ctx, absoluteConfigPath, patches)
+    // A surface can finish and dispose the whole tree while startup is still
+    // in flight: the TUI renders as soon as its own fiber starts, so an `/exit`
+    // typed before the last entry settles tears the context down under us. The
+    // Loader service goes with it, and the activation audit describes a live
+    // tree — reading `ctx.loader` past this point would throw a TypeError over
+    // an app that exited exactly as asked. Transactional group updates settle
+    // lifecycle inside the mount, so the teardown can land before it returns;
+    // re-check after every await.
+    await ctx.get('loader')?.await()
+    if (ctx.get('loader') === undefined) return ctx
+    await assertEntriesActivated(ctx, binName)
+    return ctx
+  } catch (cause) {
+    // Root-fiber disposal contains cleanup failures per observer (Cordis
+    // fiber.ts hardening) and a repeated call returns the settled single-shot
+    // result, so this await cannot reject and replace `cause`.
+    await ctx.fiber.dispose()
+    const detail = cause instanceof Error ? cause.message : String(cause)
+    // The transactional Loader wraps a failing entry apply in one message per
+    // tree layer; every layer's message is folded into `detail` above, and the
+    // deepest cause is the plugin's own thrown error, whose stack names the
+    // real failure site — append it so the startup diagnostic preserves the
+    // original activation error instead of only the wrap chain.
+    let deepest: unknown = cause
+    while (deepest instanceof Error && deepest.cause !== undefined) deepest = deepest.cause
+    const stack = deepest instanceof Error && deepest !== cause ? `\n${deepest.stack ?? deepest.message}` : ''
+    throw new Error(`${binName}: ${stage}: ${detail}${stack}`, { cause })
+  }
 }

 /** Prompt-section name for the harness-source location line an app bin adds after boot. */
 export const HARNESS_SOURCE_SECTION = 'harness:source'

 /**
- * Add a global prompt section naming the on-disk path to the harness source
- * checkout the running bin was launched from, so the agent knows where its own
- * source lives (the self-referential `dsh-tool-cordis` toolset reads and edits
- * it). Call once on the settled boot context ({@link boot}); the section orders
- * just after the harness identity opener (`-100`) and before the deployment
+ * Add a global prompt section naming the on-disk harness source checkout while
+ * explicitly distinguishing it from the task workspace and current working
+ * directory. The self-referential `dsh-tool-cordis` toolset reads and edits this
+ * checkout. Call once on the settled boot context ({@link boot}); the section
+ * orders just after the harness identity opener (`-100`) and before the deployment
 * persona (`0`). A booted tree with no `systemPrompt` service has no prompt to
 * augment, so this is then a no-op that returns `undefined`. The section is
 * registered against the `systemPrompt` service's fiber, so a dev HMR reload of
@@ -499,6 +615,6 @@ export function addHarnessSourceSection(ctx: Context, sourceRoot: string): (() =
  return systemPrompt.section({
    name: HARNESS_SOURCE_SECTION,
    order: -99,
-    text: `Your own source code is the checkout at ${sourceRoot}; you can read it there to learn how dsh works and how to extend it.`,
+    text: `The DeepSeek Harness implementation checkout is at ${sourceRoot}. The checkout location and current working directory are separate values and may differ; never infer the working directory from this path. Use pwd to determine the current working directory. Use this checkout only to inspect or extend DSH itself.`,
  })
 }
--- a/packages/ui/app-boot/tests/app-boot.spec.ts
+++ b/packages/ui/app-boot/tests/app-boot.spec.ts
@@ -325,6 +325,22 @@ describe('boot', () => {
    }
  })

+  it('disposes partial host setup and labels non-Error preparation failures', async () => {
+    const dir = tmp()
+    const failure = 42
+    let disposed = false
+    const task = boot(NAME, join(dir, 'cordis.yml'), undefined, (ctx) => {
+      ctx.effect(() => () => { disposed = true })
+      throw failure
+    })
+
+    await expect(task).rejects.toMatchObject({
+      message: `${NAME}: host preparation failed: ${failure}`,
+      cause: failure,
+    })
+    expect(disposed).toBe(true)
+  })
+
  it('exposes dshHomePath to Loader config expressions', async () => {
    const dir = tmp()
    const dshHome = join(dir, 'home')
@@ -375,7 +391,37 @@ describe('boot', () => {
  it('rejects (never exits 0 half-empty) when a config names a plugin that cannot be imported', async () => {
    const dir = tmp()
    writeFileSync(join(dir, 'cordis.yml'), '- id: ghost\n  name: ./missing.mjs\n')
-    await expect(boot(NAME, join(dir, 'cordis.yml'))).rejects.toThrow(`${NAME}: plugin(s) failed to load: ./missing.mjs`)
+    await expect(boot(NAME, join(dir, 'cordis.yml'))).rejects.toThrow(
+      `${NAME}: plugin tree failed to load: failed to apply loader entry`,
+    )
+  })
+
+  it('appends the deepest cause with its original stack to the load failure', async () => {
+    const dir = tmp()
+    writeFileSync(join(dir, 'failing.mjs'), [
+      'export function apply() {',
+      "  const failure = new Error('pinned activation failure')",
+      "  failure.stack = 'Error: pinned activation failure\\n    at failing-fixture'",
+      '  throw failure',
+      '}',
+      '',
+    ].join('\n'))
+    writeFileSync(join(dir, 'cordis.yml'), '- id: failing\n  name: ./failing.mjs\n')
+    await expect(boot(NAME, join(dir, 'cordis.yml'))).rejects.toThrow(new RegExp([
+      String.raw`failed to apply loader entry failing \(\./failing\.mjs\): pinned activation failure\n`,
+      String.raw`Error: pinned activation failure\n {4}at failing-fixture$`,
+    ].join('')))
+  })
+
+  it('falls back to the deepest cause message when its stack was erased', async () => {
+    const dir = tmp()
+    const deepest = new Error('stackless deep failure')
+    delete (deepest as { stack?: string }).stack
+    await expect(boot(NAME, join(dir, 'cordis.yml'), undefined, () => {
+      throw new Error('wrapped setup failure', { cause: deepest })
+    })).rejects.toThrow(
+      `${NAME}: host preparation failed: wrapped setup failure\nstackless deep failure`,
+    )
  })

  it('reports a pending real Loader fiber and the service unresolved in its own context', async () => {
@@ -391,9 +437,9 @@ describe('boot', () => {

 describe('addHarnessSourceSection', () => {
  const SOURCE_ROOT = `${sep}opt${sep}harness-src`
-  const EXPECTED = `Your own source code is the checkout at ${SOURCE_ROOT}; you can read it there to learn how dsh works and how to extend it.`
+  const EXPECTED = `The DeepSeek Harness implementation checkout is at ${SOURCE_ROOT}. The checkout location and current working directory are separate values and may differ; never infer the working directory from this path. Use pwd to determine the current working directory. Use this checkout only to inspect or extend DSH itself.`

-  it('adds the source path between the harness identity and the deployment persona', async () => {
+  it('distinguishes the source path from the current workdir between identity and persona', async () => {
    const ctx = new Context()
    try {
      await ctx.plugin(SystemPrompt, { persona: 'You are a coding agent.' })
--- a/packages/ui/app-boot/tests/config-reload.spec.ts
+++ b/packages/ui/app-boot/tests/config-reload.spec.ts
@@ -1,12 +1,7 @@
 /**
- * Config hot-reload resilience of the booted include tree. `dsh-app-boot`
- * installs a fail-loud unhandled-rejection handler, so a `refresh()` that
- * rethrows a config-file parse error would kill a live app on one bad
- * `cordis.yml` edit (the HMR watcher awaits `refresh()` in an async event
- * callback nobody else catches). These tests pin the vendored
- * `@cordisjs/plugin-include` contract that boot relies on: an invalid file
- * keeps the last good tree, and a valid re-read re-applies overlay patches
- * exactly like the initial load.
+ * Transactional config replacement through the booted Include and Loader tree.
+ * HMR contains rejected refreshes; direct callers receive the error after the
+ * previous generation has been retained or restored.
 */

 import { mkdtempSync, writeFileSync } from 'node:fs'
@@ -15,6 +10,7 @@ import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import type { Context } from 'cordis'
 import type { Include } from '@cordisjs/plugin-include'
+import { Group } from '@cordisjs/plugin-loader'
 import { boot } from '../src/index.ts'

 const NAME = 'dsh-test-bin'
@@ -27,9 +23,10 @@ interface TreeFixture {
  include: Include
 }

-async function bootTree(configBody: string): Promise<TreeFixture> {
+async function bootTree(configBody: string, files: Record<string, string> = {}): Promise<TreeFixture> {
  const dir = mkdtempSync(join(tmpdir(), 'dsh-config-reload-'))
  writeFileSync(join(dir, 'noop.mjs'), NOOP_PLUGIN)
+  for (const [name, content] of Object.entries(files)) writeFileSync(join(dir, name), content)
  writeFileSync(join(dir, 'cordis.yml'), configBody)
  const ctx = await boot(NAME, join(dir, 'cordis.yml'))
  const entry = [...ctx.loader.entries()].find(candidate => candidate.subtree !== undefined)
@@ -41,20 +38,41 @@ function entryConfig(ctx: Context, id: string): unknown {
  return [...ctx.loader.entries()].find(entry => entry.options.id === id)?.options.config
 }

+function entryById(ctx: Context, id: string) {
+  const entry = [...ctx.loader.entries()].find(entry => entry.options.id === id)
+  if (!entry) throw new Error(`missing loader entry ${id}`)
+  return entry
+}
+
+function plugin(name: string, body = ''): string {
+  return `export default function ${name}(_ctx, config = {}) { ${body} }\n`
+}
+
+async function expectUpdateFailure(task: Promise<void>, stage: string): Promise<void> {
+  try {
+    await task
+  } catch (error) {
+    expect(error).toBeInstanceOf(Error)
+    expect((error as Error).message).toContain(`failed to ${stage} loader entry`)
+    return
+  }
+  throw new Error(`expected loader update to fail during ${stage}`)
+}
+
 describe('include refresh with an invalid file', () => {
-  it('keeps the last good tree instead of throwing, then applies the next valid edit', async () => {
+  it('rejects while keeping the last good tree, then applies the next valid edit', async () => {
    const { ctx, dir, include } = await bootTree('- id: noop\n  name: ./noop.mjs\n  config:\n    value: 1\n')
    try {
      expect(entryConfig(ctx, 'noop')).toEqual({ value: 1 })

      writeFileSync(join(dir, 'cordis.yml'), 'invalid: [unclosed\n')
-      await expect(include.refresh()).resolves.toBeUndefined()
+      await expect(include.refresh()).rejects.toThrow('failed to parse config file')
      expect(entryConfig(ctx, 'noop')).toEqual({ value: 1 })

      // An empty file parses to `undefined` without a YAML error; it must be
      // treated exactly like a parse failure, not crash the entry walk.
      writeFileSync(join(dir, 'cordis.yml'), '')
-      await expect(include.refresh()).resolves.toBeUndefined()
+      await expect(include.refresh()).rejects.toThrow('failed to validate config file')
      expect(entryConfig(ctx, 'noop')).toEqual({ value: 1 })

      writeFileSync(join(dir, 'cordis.yml'), '- id: noop\n  name: ./noop.mjs\n  config:\n    value: 2\n')
@@ -67,6 +85,200 @@ describe('include refresh with an invalid file', () => {
  })
 })

+describe('loader entry replacement', () => {
+  it('imports a changed name before replacing the running plugin', async () => {
+    const { ctx } = await bootTree('- id: target\n  name: ./old.mjs\n', {
+      'old.mjs': plugin('oldPlugin'),
+      'new.mjs': plugin('newPlugin'),
+    })
+    try {
+      const entry = entryById(ctx, 'target')
+      await entry.update({ name: './new.mjs' })
+      expect(entry.options.name).toBe('./new.mjs')
+      expect(entry.parent.data.find(options => options.id === 'target')).toBe(entry.options)
+      expect(entry.fiber?.runtime?.callback.name).toBe('newPlugin')
+      expect(entry.options.disabled).toBeUndefined()
+      await entry.fiber?.await()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('retains the running plugin when the replacement cannot be imported', async () => {
+    const { ctx } = await bootTree('- id: target\n  name: ./old.mjs\n', {
+      'old.mjs': plugin('oldPlugin'),
+    })
+    try {
+      const entry = entryById(ctx, 'target')
+      const fiber = entry.fiber
+      await expectUpdateFailure(entry.update({ name: './missing.mjs' }), 'import')
+      expect(entry.options.name).toBe('./old.mjs')
+      expect(entry.fiber === fiber).toBe(true)
+      await fiber?.await()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('restores the previous plugin after replacement application fails', async () => {
+    const { ctx } = await bootTree('- id: target\n  name: ./old.mjs\n', {
+      'old.mjs': plugin('oldPlugin'),
+      'bad.mjs': plugin('badPlugin', 'throw new Error("candidate apply failed")'),
+    })
+    try {
+      const entry = entryById(ctx, 'target')
+      const previous = entry.fiber
+      await expectUpdateFailure(entry.update({ name: './bad.mjs' }), 'apply')
+      expect(entry.options.name).toBe('./old.mjs')
+      expect(entry.fiber === previous).toBe(false)
+      expect(entry.fiber?.runtime?.callback.name).toBe('oldPlugin')
+      expect(entry.options.disabled).toBeUndefined()
+      await entry.fiber?.await()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('restores the previous config when an in-place restart fails', async () => {
+    const { ctx } = await bootTree('- id: target\n  name: ./configurable.mjs\n  config:\n    fail: false\n', {
+      'configurable.mjs': plugin('configurablePlugin', 'if (config.fail) throw new Error("candidate config failed")'),
+    })
+    try {
+      const entry = entryById(ctx, 'target')
+      const fiber = entry.fiber
+      await expectUpdateFailure(entry.update({ config: { fail: true } }), 'apply')
+      expect(entry.options.config).toEqual({ fail: false })
+      expect(entry.fiber === fiber).toBe(true)
+      await fiber?.await()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('does not persist a failed direct fiber update', async () => {
+    const { ctx } = await bootTree('- id: target\n  name: ./configurable.mjs\n  config:\n    fail: false\n', {
+      'configurable.mjs': plugin('configurablePlugin', 'if (config.fail) throw new Error("candidate config failed")'),
+    })
+    try {
+      const entry = entryById(ctx, 'target')
+      const fiber = entry.fiber
+      if (!fiber) throw new Error('target entry has no fiber')
+      await expect(fiber.update({ fail: true })).rejects.toThrow('candidate config failed')
+      expect(entry.options.config).toEqual({ fail: false })
+      expect(entry.parent.data.find(options => options.id === 'target')).toBe(entry.options)
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+})
+
+describe('loader tree replacement', () => {
+  it('rolls back earlier updates and additions when a later entry fails', async () => {
+    const { ctx, dir, include } = await bootTree([
+      '- id: existing',
+      '  name: ./configurable.mjs',
+      '  config:',
+      '    value: old',
+      '',
+    ].join('\n'), {
+      'configurable.mjs': plugin('configurablePlugin'),
+      'bad.mjs': plugin('badPlugin', 'throw new Error("candidate apply failed")'),
+    })
+    try {
+      writeFileSync(join(dir, 'cordis.yml'), [
+        '- id: existing',
+        '  name: ./configurable.mjs',
+        '  config:',
+        '    value: candidate',
+        '- id: added',
+        '  name: ./noop.mjs',
+        '- id: bad',
+        '  name: ./bad.mjs',
+        '',
+      ].join('\n'))
+      await expect(include.refresh()).rejects.toThrow('failed to apply loader entry bad')
+      expect(entryConfig(ctx, 'existing')).toEqual({ value: 'old' })
+      expect([...ctx.loader.entries()].some(entry => entry.options.id === 'added')).toBe(false)
+      expect([...ctx.loader.entries()].some(entry => entry.options.id === 'bad')).toBe(false)
+
+      writeFileSync(join(dir, 'cordis.yml'), [
+        '- id: existing',
+        '  name: ./configurable.mjs',
+        '  config:',
+        '    value: committed',
+        '- id: added',
+        '  name: ./noop.mjs',
+        '',
+      ].join('\n'))
+      await include.refresh()
+      expect(entryConfig(ctx, 'existing')).toEqual({ value: 'committed' })
+      expect(entryById(ctx, 'added').fiber).toBeDefined()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('stops and restores descendants when an ancestor group is disabled and re-enabled', async () => {
+    const { ctx, dir, include } = await bootTree('- id: noop\n  name: ./noop.mjs\n')
+    ctx.loader.builtins.group = Group
+    try {
+      const config = (disabled: boolean) => [
+        '- id: parent',
+        '  name: cordis:group',
+        '  group: true',
+        `  disabled: ${disabled}`,
+        '  config:',
+        '    - id: child',
+        '      name: ./noop.mjs',
+        '',
+      ].join('\n')
+
+      writeFileSync(join(dir, 'cordis.yml'), config(false))
+      await include.refresh()
+      expect(entryById(ctx, 'child').fiber).toBeDefined()
+
+      writeFileSync(join(dir, 'cordis.yml'), config(true))
+      await include.refresh()
+      expect(entryById(ctx, 'child').fiber).toBeUndefined()
+
+      writeFileSync(join(dir, 'cordis.yml'), config(false))
+      await include.refresh()
+      expect(entryById(ctx, 'child').fiber).toBeDefined()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('restores a programmatic entry move when its update fails', async () => {
+    const { ctx } = await bootTree('- id: noop\n  name: ./noop.mjs\n', {
+      'movable.mjs': plugin('movablePlugin', 'if (config.fail) throw new Error("candidate config failed")'),
+    })
+    ctx.loader.builtins.group = Group
+    try {
+      const groupId = await ctx.loader.create({ name: 'cordis:group', group: true, config: [] })
+      const targetId = await ctx.loader.create({ name: './movable.mjs', config: { fail: false } })
+      const target = entryById(ctx, targetId)
+      const source = target.parent
+      const sourceIndex = source.data.indexOf(target.options)
+      const destination = entryById(ctx, groupId).subgroup
+      if (!destination) throw new Error('created loader group has no subgroup')
+
+      await expectUpdateFailure(
+        ctx.loader.update(targetId, { config: { fail: true } }, groupId),
+        'apply',
+      )
+
+      expect(target.parent).toBe(source)
+      expect(Object.getPrototypeOf(target.ctx)).toBe(source.ctx)
+      expect(source.data.indexOf(target.options)).toBe(sourceIndex)
+      expect(destination.data).not.toContain(target.options)
+      expect(target.options.config).toEqual({ fail: false })
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+})
+
 describe('include refresh with overlay patches', () => {
  it('re-applies entry patches and inserted entries on every re-read (parity with initial load)', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'dsh-config-reload-overlay-'))
@@ -116,9 +328,9 @@ describe('include refresh with overlay patches', () => {
      await ctx.loader.await()
      expect(entryConfig(ctx, 'noop')).toEqual({ value: 'patched-v2' })

-      // Removing every patch must revert to the file's own values: patching
-      // may not bake earlier patch results into the cached parse.
-      await entry.update({ config: { path: './base.yml', patches: [] } })
+      // Omitting the patch list must remove the overlay rather than reuse the
+      // Include's previous config through a default parameter.
+      await entry.update({ config: { path: './base.yml' } })
      await ctx.loader.await()
      expect(entryConfig(ctx, 'noop')).toEqual({ value: 'edited-2' })
    } finally {
--- a/packages/ui/app-boot/tests/hmr-config.spec.ts
+++ b/packages/ui/app-boot/tests/hmr-config.spec.ts
@@ -0,0 +1,142 @@
+import { mkdirSync, mkdtempSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { Context } from 'cordis'
+import Hmr from '@cordisjs/plugin-hmr'
+import Loader from '@cordisjs/plugin-loader'
+import Timer from '@cordisjs/plugin-timer'
+import { describe, expect, it } from 'vitest'
+
+async function bootHmr(dir: string): Promise<Context> {
+  const ctx = new Context()
+  ctx.baseUrl = pathToFileURL(dir).href + '/'
+  await ctx.plugin(Loader)
+  await ctx.plugin(Timer)
+  await ctx.plugin(Hmr, { root: [], ignored: [], debounce: 0 })
+  return ctx
+}
+
+async function eventually(test: () => boolean, message: string): Promise<void> {
+  const deadline = Date.now() + 10_000
+  while (!test()) {
+    if (Date.now() >= deadline) throw new Error(message)
+    await new Promise(resolve => setTimeout(resolve, 10))
+  }
+}
+
+describe('HMR exact config paths', () => {
+  it('observes add, change, and unlink outside its module roots', { timeout: 20_000 }, async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-hmr-config-'))
+    const filename = join(dir, 'plugins.yml')
+    const ctx = await bootHmr(dir)
+    const observed: string[] = []
+    try {
+      await ctx.hmr.registerConfig(filename, () => {
+        try {
+          observed.push(readFileSync(filename, 'utf8'))
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+          observed.push('missing')
+        }
+      })
+
+      writeFileSync(filename, 'one', { flag: 'wx' })
+      await eventually(() => observed.includes('one'), 'HMR did not observe config creation')
+      writeFileSync(filename, 'two')
+      await eventually(() => observed.includes('two'), 'HMR did not observe config change')
+      unlinkSync(filename)
+      await eventually(() => observed.includes('missing'), 'HMR did not observe config removal')
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('observes creation when the config parent did not exist at registration', { timeout: 20_000 }, async () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-hmr-config-'))
+    const dir = join(root, 'later')
+    const filename = join(dir, 'plugins.yml')
+    const ctx = await bootHmr(root)
+    const observed: string[] = []
+    try {
+      await ctx.hmr.registerConfig(filename, () => {
+        observed.push(readFileSync(filename, 'utf8'))
+      })
+      mkdirSync(dir)
+      writeFileSync(filename, 'created')
+      await eventually(() => observed.includes('created'), 'HMR did not observe config creation under a new parent')
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('serializes refreshes and waits for them during disposal', { timeout: 20_000 }, async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-hmr-config-'))
+    const filename = join(dir, 'plugins.yml')
+    writeFileSync(filename, 'one')
+    const ctx = await bootHmr(dir)
+    const started = Promise.withResolvers<undefined>()
+    const release = Promise.withResolvers<undefined>()
+    const observed: string[] = []
+    let active = 0
+    let maxActive = 0
+    try {
+      const dispose = await ctx.hmr.registerConfig(filename, async () => {
+        active += 1
+        maxActive = Math.max(maxActive, active)
+        observed.push(readFileSync(filename, 'utf8'))
+        if (observed.length === 1) {
+          started.resolve(undefined)
+          await release.promise
+        }
+        active -= 1
+      })
+      await started.promise
+      writeFileSync(filename, 'two')
+      // Chokidar coalesces atomic writes for 100 ms by default. Wait beyond
+      // that window so this edit is queued before registration disposal.
+      await new Promise(resolve => setTimeout(resolve, 250))
+
+      let disposed = false
+      const disposal = dispose().then(() => { disposed = true })
+      await Promise.resolve()
+      expect(disposed).toBe(false)
+      release.resolve(undefined)
+      await disposal
+      expect(maxActive).toBe(1)
+      expect(observed).toEqual(['one', 'two'])
+    } finally {
+      release.resolve(undefined)
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('normalizes refresh failures and broadcasts them without escaping the watcher', { timeout: 20_000 }, async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-hmr-config-'))
+    const filename = join(dir, 'plugins.yml')
+    const ctx = await bootHmr(dir)
+    const failure = Promise.withResolvers<{ filename: string; error: Error }>()
+    let failureCount = 0
+    try {
+      ctx.on('hmr/config-update-failed', () => {
+        throw new Error('observer failed')
+      })
+      ctx.on('hmr/config-update-failed', (failedFilename, error) => {
+        failureCount += 1
+        failure.resolve({ filename: failedFilename, error })
+      })
+      await ctx.hmr.registerConfig(filename, () => { throw 42 })
+      writeFileSync(filename, 'invalid')
+
+      const observed = await failure.promise
+      expect(observed.filename).toBe(filename)
+      expect(observed.error).toBeInstanceOf(Error)
+      expect(observed.error.message).toBe('42')
+
+      writeFileSync(filename, 'invalid again')
+      await eventually(() => failureCount === 2, 'HMR stopped broadcasting after an observer rejected')
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+})
--- a/packages/ui/app-boot/tests/personal-config.spec.ts
+++ b/packages/ui/app-boot/tests/personal-config.spec.ts
@@ -4,21 +4,36 @@
 * a real Loader tree.
 */

-import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, unlinkSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import { afterEach, describe, expect, it } from 'vitest'
-import type { Context } from 'cordis'
+import { Context } from 'cordis'
+import Hmr from '@cordisjs/plugin-hmr'
+import Loader from '@cordisjs/plugin-loader'
+import Timer from '@cordisjs/plugin-timer'
 import {
  boot,
  loadPersonalPatches,
  PERSONAL_CONFIG_FILENAME,
+  watchPersonalPatches,
 } from '../src/index.ts'

 const NAME = 'dsh-test-bin'

 const tmp = (): string => mkdtempSync(join(tmpdir(), 'dsh-personal-config-'))

+async function eventually(test: () => boolean, message: string): Promise<void> {
+  const deadline = Date.now() + 10_000
+  while (!test()) {
+    if (Date.now() >= deadline) throw new Error(message)
+    await new Promise(resolve => setTimeout(resolve, 10))
+  }
+}
+
+const settleChokidarChangeThrottle = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 75))
+
 describe('loadPersonalPatches', () => {
  afterEach(() => {
    delete process.env.DSH_HOME
@@ -86,7 +101,13 @@ describe('loadPersonalPatches', () => {

 describe('boot with personal patches', () => {
  function writeTree(dir: string): string {
-    writeFileSync(join(dir, 'noop.mjs'), 'export const name = "noop"\nexport function apply() {}\n')
+    writeFileSync(join(dir, 'noop.mjs'), [
+      'export const name = "noop"',
+      'export function apply(_ctx, config = {}) {',
+      '  if (config.fail) throw new Error("candidate config failed")',
+      '}',
+      '',
+    ].join('\n'))
    writeFileSync(join(dir, 'cordis.yml'), '- id: noop\n  name: ./noop.mjs\n  config:\n    value: base\n')
    return join(dir, 'cordis.yml')
  }
@@ -138,4 +159,112 @@ describe('boot with personal patches', () => {
      await ctxEmpty.fiber.dispose()
    }
  })
+
+  it('watches add, failure, recovery, and removal through transactional HMR', { timeout: 20_000 }, async () => {
+    const dir = tmp()
+    const personal = tmp()
+    const filename = join(personal, PERSONAL_CONFIG_FILENAME)
+    const basePatches = [{ id: 'noop', config: { value: 'generated' } }]
+    const ctx = await boot(NAME, writeTree(dir), basePatches)
+    await ctx.plugin(Timer)
+    await ctx.plugin(Hmr, { root: [], ignored: [], debounce: 0 })
+    const failures: Array<{ filename: string; error: Error }> = []
+    ctx.on('hmr/config-update-failed', (failedFilename, error) => {
+      failures.push({ filename: failedFilename, error })
+    })
+    const dispose = await watchPersonalPatches(ctx, {
+      binName: NAME,
+      dir: personal,
+      compose: personalPatches => [...basePatches, ...personalPatches],
+    })
+    try {
+      writeFileSync(filename, '- id: noop\n  config:\n    value: live\n')
+      await eventually(() => (entryConfig(ctx, 'noop') as { value?: string }).value === 'live', 'personal config addition was not applied')
+
+      writeFileSync(filename, '- id: noop\n  config:\n    fail: true\n')
+      await eventually(() => failures.length === 1, 'failed candidate was not broadcast')
+      expect(failures[0]).toMatchObject({ filename })
+      expect(failures[0]?.error).toBeInstanceOf(Error)
+      expect((entryConfig(ctx, 'noop') as { value?: string }).value).toBe('live')
+      await settleChokidarChangeThrottle()
+
+      writeFileSync(filename, 'invalid: [unclosed\n')
+      await eventually(() => failures.length === 2, 'parse failure was not broadcast')
+      expect(failures[1]?.error).toBeInstanceOf(Error)
+      expect((entryConfig(ctx, 'noop') as { value?: string }).value).toBe('live')
+      await settleChokidarChangeThrottle()
+
+      writeFileSync(filename, '- id: noop\n  config:\n    value: recovered\n')
+      await eventually(() => (entryConfig(ctx, 'noop') as { value?: string }).value === 'recovered', 'valid recovery was not applied')
+      await settleChokidarChangeThrottle()
+
+      unlinkSync(filename)
+      await eventually(() => (entryConfig(ctx, 'noop') as { value?: string }).value === 'generated', 'personal config removal did not restore the app-owned patch')
+      expect(failures).toHaveLength(2)
+      await settleChokidarChangeThrottle()
+
+      // Default compose: the personal overlay IS the whole patch list, so a
+      // fresh generation replaces the app-owned layer instead of stacking on it.
+      await dispose()
+      const disposeDefault = await watchPersonalPatches(ctx, { binName: NAME, dir: personal })
+      try {
+        writeFileSync(filename, '- id: noop\n  config:\n    value: identity\n')
+        await eventually(() => (entryConfig(ctx, 'noop') as { value?: string }).value === 'identity', 'default-compose personal patch was not applied')
+      } finally {
+        await disposeDefault()
+      }
+    } finally {
+      await dispose()
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('fails loud when the exact watcher lacks HMR or a root Include', async () => {
+    const dir = tmp()
+    const withoutHmr = await boot(NAME, writeTree(dir))
+    await expect(watchPersonalPatches(withoutHmr, { binName: NAME, dir: tmp() })).rejects.toThrow('requires the Cordis HMR service')
+    await withoutHmr.fiber.dispose()
+
+    const withoutInclude = new Context()
+    withoutInclude.baseUrl = pathToFileURL(`${tmp()}/`).href
+    await withoutInclude.plugin(Loader)
+    await withoutInclude.plugin(Timer)
+    await withoutInclude.plugin(Hmr, { root: [], ignored: [], debounce: 0 })
+    await expect(watchPersonalPatches(withoutInclude, { binName: NAME, dir: tmp() })).rejects.toThrow('requires the root Include entry')
+    await withoutInclude.fiber.dispose()
+  })
+
+  it('returns a no-op disposer when the tree is disposed while the watcher opens', async () => {
+    // A TUI `/exit` typed during startup disposes the whole tree while
+    // registerConfig's effect registration is still in flight (the HMR effect
+    // then fails with INACTIVE_EFFECT); the app is exiting exactly as asked,
+    // so the watcher must not crash the process. The stub makes the race
+    // deterministic — the live-teardown ordering itself is not stageable.
+    const dir = tmp()
+    const ctx = await boot(NAME, writeTree(dir))
+    try {
+      const teardown = Object.assign(new Error('cannot create effect on inactive context'), { code: 'INACTIVE_EFFECT' })
+      ctx.provide('hmr', { registerConfig: () => Promise.reject(teardown) })
+      const dispose = await watchPersonalPatches(ctx, { binName: NAME, dir: tmp() })
+      await expect(dispose()).resolves.toBeUndefined()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('propagates registration failures other than mid-teardown', async () => {
+    const dir = tmp()
+    const personal = tmp()
+    const ctx = await boot(NAME, writeTree(dir))
+    try {
+      await ctx.plugin(Timer)
+      await ctx.plugin(Hmr, { root: [], ignored: [], debounce: 0 })
+      const dispose = await watchPersonalPatches(ctx, { binName: NAME, dir: personal })
+      // Same personal path registered twice: HMR refuses; not a teardown race.
+      await expect(watchPersonalPatches(ctx, { binName: NAME, dir: personal })).rejects.toThrow('already registered')
+      await dispose()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
 })
--- a/packages/ui/app-boot/tests/repository-cache.spec.ts
+++ b/packages/ui/app-boot/tests/repository-cache.spec.ts
@@ -0,0 +1,159 @@
+import { execFile } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { mkdtemp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { promisify } from 'node:util'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { BUNDLED_PNPM_VERSION, RepositoryCache, type RepositoryInstall } from '@cordisjs/plugin-loader/repository'
+
+const execFileAsync = promisify(execFile)
+const roots: string[] = []
+
+async function temporaryRoot(name: string): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), `cordis-${name}-`))
+  roots.push(root)
+  return root
+}
+
+async function fakePackage(directory: string): Promise<void> {
+  const target = join(directory, 'node_modules', 'repository')
+  await mkdir(target, { recursive: true })
+  await writeFile(join(target, 'package.json'), '{"name":"fixture"}\n')
+}
+
+afterEach(async () => {
+  vi.unstubAllEnvs()
+  await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true })))
+})
+
+describe('RepositoryCache', () => {
+  it('single-flights and permanently reuses an exact specifier', async () => {
+    const root = await temporaryRoot('repository-cache')
+    const calls: string[] = []
+    const install: RepositoryInstall = async (directory) => {
+      calls.push(directory)
+      await fakePackage(directory)
+    }
+    const cache = new RepositoryCache(root, install)
+    const specifier = 'github:owner/repository#0123456789abcdef'
+
+    const [first, concurrent] = await Promise.all([cache.resolve(specifier), cache.resolve(specifier)])
+    expect(concurrent).toBe(first)
+    expect(calls).toHaveLength(1)
+
+    const reopened = new RepositoryCache(root, async () => { throw new Error('cache miss') })
+    expect(await reopened.resolve(specifier)).toBe(first)
+    expect(JSON.parse(await readFile(join(first, '..', '..', 'package.json'), 'utf8'))).toMatchObject({
+      packageManager: `pnpm@${BUNDLED_PNPM_VERSION}`,
+      dependencies: { repository: specifier },
+    })
+
+    const second = await cache.resolve('github:owner/repository#fedcba9876543210')
+    expect(second).not.toBe(first)
+    expect(calls).toHaveLength(2)
+  })
+
+  it('accepts the valid winner when independent cache instances race', async () => {
+    const root = await temporaryRoot('repository-race')
+    const bothStarted = Promise.withResolvers<undefined>()
+    let starts = 0
+    const install: RepositoryInstall = async (directory) => {
+      await fakePackage(directory)
+      starts += 1
+      if (starts === 2) bothStarted.resolve(undefined)
+      await bothStarted.promise
+    }
+    const specifier = 'github:owner/repository#race'
+
+    const [first, second] = await Promise.all([
+      new RepositoryCache(root, install).resolve(specifier),
+      new RepositoryCache(root, install).resolve(specifier),
+    ])
+
+    expect(second).toBe(first)
+    expect(starts).toBe(2)
+    expect(await readdir(root)).toHaveLength(1)
+  })
+
+  it('removes a failed staging tree and permits an exact retry', async () => {
+    const root = await temporaryRoot('repository-retry')
+    let attempts = 0
+    const cache = new RepositoryCache(root, async (directory) => {
+      attempts += 1
+      if (attempts === 1) throw new Error('install failed')
+      await fakePackage(directory)
+    })
+
+    await expect(cache.resolve('github:owner/repository#ref')).rejects.toThrow('failed to prepare repository')
+    expect(await readdir(root)).toEqual([])
+    await expect(cache.resolve('github:owner/repository#ref')).resolves.toContain('node_modules')
+    expect(attempts).toBe(2)
+  })
+
+  it('rejects empty or padded specifiers before touching the cache', async () => {
+    const root = await temporaryRoot('repository-input')
+    const cache = new RepositoryCache(root, fakePackage)
+    expect(() => cache.resolve('')).toThrow('non-empty unpadded string')
+    expect(() => cache.resolve(' github:owner/repository#ref')).toThrow('non-empty unpadded string')
+    await expect(readdir(root)).resolves.toEqual([])
+  })
+
+  it('fails loud on a corrupt published marker instead of reinstalling it', async () => {
+    const root = await temporaryRoot('repository-corrupt')
+    const specifier = 'github:owner/repository#corrupt'
+    const key = createHash('sha256').update(specifier).digest('hex')
+    const entry = join(root, key)
+    await mkdir(join(entry, 'node_modules', 'repository'), { recursive: true })
+    await writeFile(join(entry, '.repository-cache.json'), '{}\n')
+    const cache = new RepositoryCache(root, async () => { throw new Error('must not reinstall') })
+
+    await expect(cache.resolve(specifier)).rejects.toThrow('repository cache marker is invalid')
+  })
+
+  it('selects and prepares a root .dsh-plugin Git subpath through the bundled pnpm', { timeout: 60_000 }, async () => {
+    const root = await temporaryRoot('repository-pnpm')
+    const repository = join(root, 'source')
+    await mkdir(join(repository, '.dsh-plugin'), { recursive: true })
+    await mkdir(join(repository, 'skills', 'fixture'), { recursive: true })
+    await writeFile(join(repository, 'package.json'), `${JSON.stringify({
+      name: 'repository-fixture',
+      version: '1.0.0',
+    })}\n`)
+    await writeFile(join(repository, 'skills', 'fixture', 'SKILL.md'), 'repository skill source\n')
+    await writeFile(join(repository, '.dsh-plugin', 'package.json'), `${JSON.stringify({
+      name: 'repository-plugin-fixture',
+      version: '1.0.0',
+      scripts: { prepare: 'node prepare.mjs' },
+      dsh: { skills: ['../skills'] },
+    })}\n`)
+    await writeFile(join(repository, '.dsh-plugin', 'prepare.mjs'), [
+      "import { cp, mkdir, writeFile } from 'node:fs/promises'",
+      "await mkdir('dsh-plugin-assets/skills', { recursive: true })",
+      "await cp('../skills', 'dsh-plugin-assets/skills/0', { recursive: true })",
+      "await writeFile('dsh-plugin.mjs', 'export function apply() {}\\n')",
+      "await writeFile('prepared.txt', `${process.env.REPOSITORY_TEST_VISIBLE ?? 'absent'}|${process.env.REPOSITORY_TEST_TOKEN ?? 'absent'}\\n`)",
+      '',
+    ].join('\n'))
+    await execFileAsync('git', ['init', '--quiet'], { cwd: repository })
+    await execFileAsync('git', ['add', '.'], { cwd: repository })
+    await execFileAsync('git', [
+      '-c', 'user.name=Repository Fixture',
+      '-c', 'user.email=repository@example.invalid',
+      'commit', '--quiet', '-m', 'fixture',
+    ], { cwd: repository })
+    const { stdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: repository, encoding: 'utf8' })
+    const specifier = `git+${pathToFileURL(repository).href}#${stdout.trim()}&path:/.dsh-plugin`
+    vi.stubEnv('REPOSITORY_TEST_VISIBLE', 'visible')
+    vi.stubEnv('REPOSITORY_TEST_TOKEN', 'hidden')
+
+    const installed = await new RepositoryCache(join(root, 'cache')).resolve(specifier)
+    await expect(readFile(join(installed, 'prepared.txt'), 'utf8')).resolves.toBe('visible|absent\n')
+    await expect(readFile(join(installed, 'dsh-plugin.mjs'), 'utf8')).resolves.toContain('export function apply')
+    await expect(readFile(join(installed, 'dsh-plugin-assets/skills/0/fixture/SKILL.md'), 'utf8'))
+      .resolves.toBe('repository skill source\n')
+    await expect(readFile(join(installed, 'package.json'), 'utf8'))
+      .resolves.toContain('repository-plugin-fixture')
+  })
+})
--- a/packages/ui/app-boot/tsconfig.json
+++ b/packages/ui/app-boot/tsconfig.json
@@ -17,6 +17,9 @@
    {
      "path": "../../../vendor/include"
    },
+    {
+      "path": "../../../vendor/hmr"
+    },
    {
      "path": "../../support/invariants"
    },
--- a/packages/ui/tui/README.i18n.yaml
+++ b/packages/ui/tui/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/ui/tui/README.md
-README.md: b1eb150bd7ba27a63038d2557782d6603ec9168f
-README.zh.md: 476153f9aca58a0248193a45f4c5f16e400e3cf0
+README.md: 387c7df29f493650ac74649ab60916436f1a9b12
+README.zh.md: be3c757d343ac62703fcdec4912c481077e397e3
--- a/packages/ui/tui/README.md
+++ b/packages/ui/tui/README.md
@@ -40,7 +40,7 @@ Selection repeats those checks and requires the current agent to be idle before

 The exit line is launcher-owned, not configurable. A launcher provides `TUI_GOODBYE_MESSAGE_KEY` on the boot context — for the shipped `dsh`, the command that resumes this session — and exiting prints it verbatim after the terminal is released; absent, exiting prints nothing. Only the launcher knows how it was invoked, so only it can name a command that works. The TUI escapes terminal controls before rendering and never executes the text. A launcher that also supplies `MAIN_SESSION_ID_KEY` fixes which session the mounted app binds to, so resume survives any config-level patch.

-A launcher can seed a fresh session's first turn by providing `INITIAL_SKILL_KEY` (the skill name) on the boot context; the TUI auto-invokes it exactly as a typed `/skill:<name>`, once the chat is live. The shipped `dsh migrate`/`dsh experimental-upgrade` set it and only for a fresh session, so a resumed session never re-invokes the skill; an unknown name is reported as a notice.
+A launcher can seed a fresh session's first turn by providing `INITIAL_SKILL_KEY` (the skill name) on the boot context; the TUI auto-invokes it exactly as a typed `/skill:<name>`, once the chat is live. The shipped `dsh migrate`/`dsh upgrade` set it and only for a fresh session, so a resumed session never re-invokes the skill; an unknown name is reported as a notice.

 ## Config

--- a/packages/ui/tui/README.zh.md
+++ b/packages/ui/tui/README.zh.md
@@ -40,7 +40,7 @@ Footer 将会话报告的用量汇总为 `↑<uncached input> ↓<output>`；任

 退出时打印的行由启动器拥有，不可通过配置指定。启动器在启动上下文上提供 `TUI_GOODBYE_MESSAGE_KEY`（对于随附的 `dsh`，即恢复本会话的命令），释放终端后退出会原样打印它；未提供时退出不打印任何内容。只有启动器知道自己是如何被调用的，因此只有它能给出可用的命令。TUI 在渲染前会转义终端控制字符，且绝不执行该文本。若启动器同时提供 `MAIN_SESSION_ID_KEY`，则会固定已挂载应用绑定的会话，因此恢复功能不受配置层修补影响。

-启动器可通过在启动上下文上提供 `INITIAL_SKILL_KEY`（skill 名称）来播种全新会话的首轮；聊天就绪后，TUI 会像用户手动键入 `/skill:<name>` 一样自动调用它。随附的 `dsh migrate`/`dsh experimental-upgrade` 会设置该键，且仅对全新会话设置，因此恢复的会话绝不会重复调用该 skill；未知名称会以通知形式报告。
+启动器可通过在启动上下文上提供 `INITIAL_SKILL_KEY`（skill 名称）来播种全新会话的首轮；聊天就绪后，TUI 会像用户手动键入 `/skill:<name>` 一样自动调用它。随附的 `dsh migrate`/`dsh upgrade` 会设置该键，且仅对全新会话设置，因此恢复的会话绝不会重复调用该 skill；未知名称会以通知形式报告。

 ## 配置

--- a/packages/ui/tui/src/config.ts
+++ b/packages/ui/tui/src/config.ts
@@ -122,7 +122,7 @@ export interface Config extends TuiConfig {
  /**
   * Skill name auto-invoked as this session's first user turn, exactly as if
   * the user typed `/skill:<name>`. Set only by a launcher for a fresh
-   * skill-guided session (`dsh migrate`/`dsh experimental-upgrade`); absent
+   * skill-guided session (`dsh migrate`/`dsh upgrade`); absent
   * leaves the first turn to the user.
   */
  initialSkill?: string
--- a/packages/ui/tui/src/index.ts
+++ b/packages/ui/tui/src/index.ts
@@ -227,7 +227,7 @@ export const TUI_GOODBYE_MESSAGE_KEY = 'tuiGoodbyeMessage'
 /**
 * Context key a launcher sets before any Loader entry mounts
 * (`ctx.provide(INITIAL_SKILL_KEY, name)`) to seed a fresh session's first user
- * turn with `/skill:<name>` — the `dsh migrate`/`dsh experimental-upgrade`
+ * turn with `/skill:<name>` — the `dsh migrate`/`dsh upgrade`
 * guided-session entry. The launcher sets it only when minting a fresh session,
 * so it never re-fires on a resumed one. Absent leaves the first turn to the user.
 */
@@ -1690,7 +1690,7 @@ export function createTuiChat(
  })
  startBannerReveal()

-  // A launcher-seeded first turn (`dsh migrate`/`dsh experimental-upgrade`):
+  // A launcher-seeded first turn (`dsh migrate`/`dsh upgrade`):
  // invoke the named skill exactly as a typed `/skill:<name>` would, once the
  // chat is live and the agent is idle. The launcher sets this only for a fresh
  // session, so there is no prior turn to collide with; invokeSkill reports an
--- a/packages/ui/tui/tests/harness.ts
+++ b/packages/ui/tui/tests/harness.ts
@@ -228,7 +228,7 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
      steeredOptions.push(input)
      const id = input.id
      steeredIds.push(id)
-      return id
+      return { outcome: Promise.resolve({ status: 'admitted' as const, turn: 1, step: 1 }) }
    },
    inject(input) {
      injected.push(input.content)
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -5679,7 +5679,7 @@ describe('terminal mounting', () => {
    const session = ctx.sessions.create(SessionId('main'))
    ctx.agents.register({
      id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx,
-      followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, updateInbox: () => 'not-found', reserveTurnAdmission: () => undefined, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => {}, steer: () => ({ outcome: Promise.resolve({ status: 'rejected' as const }) }), inject: () => {}, send: () => {}, updateInbox: () => 'not-found', reserveTurnAdmission: () => undefined, cancel() {}, whenIdle: () => Promise.resolve(),
    })
    const terminal = new FakeTerminal()
    mountTui(ctx, { theme: { color: false } }, { terminal, exit: vi.fn() })
@@ -5704,7 +5704,7 @@ describe('terminal mounting', () => {
    const session = ctx.sessions.create(SessionId('main'))
    ctx.agents.register({
      id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx,
-      followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, updateInbox: () => 'not-found', reserveTurnAdmission: () => undefined, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => {}, steer: () => ({ outcome: Promise.resolve({ status: 'rejected' as const }) }), inject: () => {}, send: () => {}, updateInbox: () => 'not-found', reserveTurnAdmission: () => undefined, cancel() {}, whenIdle: () => Promise.resolve(),
    })
    const terminal = new FakeTerminal()
    // Mirror dsh-tui's own inject (minus loader, the absence under test).
@@ -5739,14 +5739,14 @@ describe('terminal mounting', () => {
    const otherSession = ctx.sessions.create(SessionId('other-session'))
    ctx.agents.register({
      id: otherSession.id, options: {}, session: otherSession, status: 'idle', acceptsNextStep: false, ctx,
-      followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, updateInbox: () => 'not-found', reserveTurnAdmission: () => undefined, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => {}, steer: () => ({ outcome: Promise.resolve({ status: 'rejected' as const }) }), inject: () => {}, send: () => {}, updateInbox: () => 'not-found', reserveTurnAdmission: () => undefined, cancel() {}, whenIdle: () => Promise.resolve(),
    })
    expect(terminal.started).toBe(0)

    const session = ctx.sessions.create(SessionId('late-session'))
    const agent = {
      id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx,
-      followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, updateInbox: () => 'not-found', reserveTurnAdmission: () => undefined, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => {}, steer: () => ({ outcome: Promise.resolve({ status: 'rejected' as const }) }), inject: () => {}, send: () => {}, updateInbox: () => 'not-found', reserveTurnAdmission: () => undefined, cancel() {}, whenIdle: () => Promise.resolve(),
    } as Agent
    ctx.agents.register(agent)
    await tick()
@@ -5777,7 +5777,7 @@ describe('terminal mounting', () => {
    const session = ctx.sessions.create(SessionId('main-session'))
    ctx.agents.register({
      id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx,
-      followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, updateInbox: () => 'not-found', reserveTurnAdmission: () => undefined, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => {}, steer: () => ({ outcome: Promise.resolve({ status: 'rejected' as const }) }), inject: () => {}, send: () => {}, updateInbox: () => 'not-found', reserveTurnAdmission: () => undefined, cancel() {}, whenIdle: () => Promise.resolve(),
    })
    await tick()
    expect(terminal.started).toBe(0)
@@ -5821,7 +5821,7 @@ describe('terminal mounting', () => {
    session.append('step/start', { turn: 1, step: 1 })
    ctx.agents.register({
      id: session.id, options: {}, session, status: 'running', acceptsNextStep: true, ctx,
-      followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, updateInbox: () => 'not-found', reserveTurnAdmission: () => undefined, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => {}, steer: () => ({ outcome: Promise.resolve({ status: 'rejected' as const }) }), inject: () => {}, send: () => {}, updateInbox: () => 'not-found', reserveTurnAdmission: () => undefined, cancel() {}, whenIdle: () => Promise.resolve(),
    })
    const terminal = new FakeTerminal()
    terminal.start = () => { throw new Error('terminal startup failed') }